From 2c8ef7af7d4151a48d70ae58b1c254969cceb8dd Mon Sep 17 00:00:00 2001 From: jonnew Date: Tue, 16 Sep 2025 12:46:57 -0400 Subject: [PATCH 1/2] Update datasheets - Update datasheets to match latest public firmware - Fix formatting in glossary sections --- source/Hardware Guide/Datasheets/bno055.rst | 43 ++-- .../Datasheets/fmc-digital-io.rst | 216 +++++++++++------- .../Datasheets/fmc-link-control.rst | 36 +-- .../Hardware Guide/Datasheets/load-test.rst | 73 +++--- .../Datasheets/rhs2116-trigger.rst | 24 +- source/Hardware Guide/Datasheets/rhs2116.rst | 17 +- 6 files changed, 249 insertions(+), 160 deletions(-) diff --git a/source/Hardware Guide/Datasheets/bno055.rst b/source/Hardware Guide/Datasheets/bno055.rst index 29247602..242065c0 100644 --- a/source/Hardware Guide/Datasheets/bno055.rst +++ b/source/Hardware Guide/Datasheets/bno055.rst @@ -99,38 +99,35 @@ All IMU data is signed with the exception of the calibration status bits (last byte in the frame). The unit conversions for each of these measurements are as follows: -- Euler angle (Tait-Bryan formalism) +Euler angle (Tait-Bryan formalism) + - Yaw: 0 to 360 degrees + - Roll: -180 to 180 degrees + - Pitch: -90 to 90 degrees - - Yaw: 0 to 360 degrees - - Roll: -180 to 180 degrees - - Pitch: -90 to 90 degrees + .. math:: -.. math:: + 1^{\circ} = 16\ LSB - 1^{\circ} = 16\ LSB +Quaternion + .. math:: -- Quaternion + 1 = 2^{14}\ LSB -.. math:: +Acceleration & Gravity Vector + .. math:: - 1 = 2^{14}\ LSB + 1\ m/s^2 = 100\ LSB -- Acceleration & Gravity Vector +Temperature + .. math:: -.. math:: + 1^{\circ}C = 1\ LSB - 1\ m/s^2 = 100\ LSB - -- Temperature - -.. math:: - - 1^{\circ}C = 1\ LSB - -- Calibration Status - - - 0: not calibrated - - 3: fully calibrated +Calibration Status + - 0: Not calibrated + - 1: Poorly calibrated + - 2: Partially Calibrated + - 3: Fully calibrated Host To Device Data Frames ****************************************** diff --git a/source/Hardware Guide/Datasheets/fmc-digital-io.rst b/source/Hardware Guide/Datasheets/fmc-digital-io.rst index 1822ba30..65bc6508 100644 --- a/source/Hardware Guide/Datasheets/fmc-digital-io.rst +++ b/source/Hardware Guide/Datasheets/fmc-digital-io.rst @@ -2,8 +2,8 @@ FMC Host Digital IO Device ########################################### -:Authors: Jonathan P. Newman -:Version: 1 +:Authors: Jonathan P. Newman, Aarón Cuevas López +:Version: 2 :IO: Frame Source, Frame Sink, Register Access :ONIX ID: 18 :ONIX Hubs: :ref:`pcie_host` @@ -46,26 +46,26 @@ The breakout to host serialization protocol is as follows: | - Buttons - Buttons press state. Each bit represents the press state of a single - button in the 6-buttons bank. +Buttons + Buttons press state. Each bit represents the press state of a single + button in the 6-buttons bank. - - 0: Up - - 1: Down + - 0: Up + - 1: Down - Digital In - Digital input port. Each bit represents state of a signal line in the - 8-bit port. +Digital In + Digital input port. Each bit represents state of a signal line in the + 8-bit port. - - 0: Low - - 1: High + - 0: Low + - 1: High - Pnn - Headstage port power state. Each bit represents the power state of one of - the four headstage ports. +Pnn + Headstage port power state. Each bit represents the power state of one of + the four headstage ports. - - 0: Power off - - 1: Power on + - 0: Power off + - 1: Power on A clock recovery circuit is required at the receiver to generate ``clk`` from ``sclk`` in order to sample the ``dat`` lines. @@ -93,67 +93,67 @@ The host to breakout serialization protocol is as follows: | - CMD - Two bit command word that determines what to do with SW. - - - 0b00: Shift slow bits into slow shift register - - 0b01: Validate and move slow shift register to outputs and set initial - state to [0, ..., 0, slow1, slow0]. slow1 should be the desired MSB at - next command. - - 0b10: Reserved, same as 0b00 currently. Don't use. - - 0b11: Reset - - SW - Two-bit "slow-word" part. These bits are accumulated over time in order - to control the display state and non-timing critical apsects of the - breakout board. For instance, LED colors and brightness, headstage lock - state, etc. As of this writing, for :ref:`breakout`, a complete - slow-word is as follows. - - .. wavedrom:: - - { - reg: [ - {bits: 1, name: "Acq. Running" }, - {bits: 1, name: "Acq. Reset Done" }, - {bits: 2, name: "Reserved" }, - {bits: 4, name: "LED Level" }, - {bits: 2, name: "LED Mode" }, - {bits: 2, name: "Port A Status" }, - {bits: 2, name: "Port B Status" }, - {bits: 2, name: "Port C Status" }, - {bits: 2, name: "Port D Status" }, - {bits: 12, name: "Analog IO Dir." }, - {bits: 2, name: "HARP Conf." }, - {bits: 16, name: "GPIO Dir." } - ], - config: {bits: 48, lanes: 8, vflip: true, hflip: true, fontsize: 11} - } - - which are defined as follows: - - - Acq. Running: Host hardware run state. 0 = not running, 1 = running - - Acq. Reset Done: Host reset state. 0 = reset not complete, 1 = reset - complete - - Reserved: NA - - LED Level: 4 bit register for general LED brighness. 0 = dimmest, 16 = - brightest - - LED Mode: 2 bit register for LED mode. 0 = all off, 1 = only - power/running, 2 = power/running, pll, harp, 3 = all on - - Port X Status: 2 bit register describing the headstage port state. 00: - power off, 01: power on, 10: locked, 11: device map good. - - Analog IO Dir.: 12 bit register describing the direcitonality of each - of the analog inputs. 0 = input, 1 = output. - - HARP Config.: 2 bit register for possible future harp configuration. - - GPIO Dir.: 16 bit register for possible future digital io - directionality configuration. - - Digital Out - Digital output port state. Each bit represents state of an output signal - line in the 8-bit port. - - - 0: Low - - 1: High +CMD + Two bit command word that determines what to do with SW. + + - 0b00: Shift slow bits into slow shift register + - 0b01: Validate and move slow shift register to outputs and set initial + state to [0, ..., 0, slow1, slow0]. slow1 should be the desired MSB at + next command. + - 0b10: Reserved, same as 0b00 currently. Don't use. + - 0b11: Reset + +SW + Two-bit "slow-word" part. These bits are accumulated over time in order + to control the display state and non-timing critical apsects of the + breakout board. For instance, LED colors and brightness, headstage lock + state, etc. As of this writing, for :ref:`breakout`, a complete + slow-word is as follows. + + .. wavedrom:: + + { + reg: [ + {bits: 1, name: "Acq. Running" }, + {bits: 1, name: "Acq. Reset Done" }, + {bits: 2, name: "Reserved" }, + {bits: 4, name: "LED Level" }, + {bits: 2, name: "LED Mode" }, + {bits: 2, name: "Port A Status" }, + {bits: 2, name: "Port B Status" }, + {bits: 2, name: "Port C Status" }, + {bits: 2, name: "Port D Status" }, + {bits: 12, name: "Analog IO Dir." }, + {bits: 2, name: "HARP Conf." }, + {bits: 16, name: "GPIO Dir." } + ], + config: {bits: 48, lanes: 8, vflip: true, hflip: true, fontsize: 11} + } + + which are defined as follows: + + - Acq. Running: Host hardware run state. 0 = not running, 1 = running + - Acq. Reset Done: Host reset state. 0 = reset not complete, 1 = reset + complete + - Reserved: NA + - LED Level: 4 bit register for general LED brighness. 0 = dimmest, 16 = + brightest + - LED Mode: 2 bit register for LED mode. 0 = all off, 1 = only + power/running, 2 = power/running, pll, harp, 3 = all on + - Port X Status: 2 bit register describing the headstage port state. 00: + power off, 01: power on, 10: locked, 11: device map good. + - Analog IO Dir.: 12 bit register describing the direcitonality of each + of the analog inputs. 0 = input, 1 = output. + - HARP Config.: 2 bit register for possible future harp configuration. + - GPIO Dir.: 16 bit register for possible future digital io + directionality configuration. + +Digital Out + Digital output port state. Each bit represents state of an output signal + line in the 8-bit port. + + - 0: Low + - 1: High A clock recovery circuit is required at the receiver to generate ``clk`` from ``sclk`` in order to sample the ``dat`` line. @@ -203,9 +203,9 @@ Register Programming - LEDLVL - R/W - On Reset - - 0x0007 + - 0x0003 - None - - The four LSBs dertermine the overall LED brightness. Brightness + - The four LSBs determine the overall LED brightness. Brightness increases linearly with this register's 0-15 value. * - 0x03 @@ -222,7 +222,33 @@ Register Programming - On Reset - 0x0000 - None - - GPIO configuraiton. Reserved for future use. + - GPIO configuration. Reserved for future use. + + * - 0x05 + - CLKHZ + - R + - N/A + - N/A + - None + - The system clock frequency in Hz + + * - 0x06 + - SPACING + - R/W + - On Reset + - 0x0000 + - None + - Minimum CLK_HZ cycles between samples. Can be used to debounce inputs. + Ignored if SAMPLING > 0. + + * - 0x07 + - SAMPLING + - R/W + - On Reset + - 0x0000 + - None + - If > 0, produce one sample with each SAMPLING value of the CLK_HZ clock. + regardless of if there are changes in digital input state or not. .. _onidatasheet_fmc_digital_io_d2h: @@ -254,6 +280,30 @@ current digital input and user input state. config: {bits: 224, lanes: 7, vflip: true, hflip: true, fontsize: 11} } +.. wavedrom:: + + { + reg: [ + {bits: 64, name: "Acquisition Clock Counter", type: 0}, + {bits: 32, name: "Device Address", type: 0}, + {bits: 32, name: "Data Size", type: 0, attr: 10}, + + {bits: 64, name: "Hub Clock Counter", type: 3}, + + {bits: 8, name: "Status Codeword", type: 4}, + + {bits: 5, name: "Reserved"}, + + {bits: 1, name: "CV", type: 2}, + {bits: 1, name: "PP", type: 2}, + {bits: 1, name: "SL", type: 2}, + + {bits: 16} + + ], + config: {bits: 224, lanes: 7, vflip: true, hflip: true, fontsize: 11} + } + | Input Port State @@ -287,5 +337,5 @@ output port state: | - Output Port State - 8-bit output port state +Output Port State + 8-bit output port state diff --git a/source/Hardware Guide/Datasheets/fmc-link-control.rst b/source/Hardware Guide/Datasheets/fmc-link-control.rst index 9d28ab98..43e3a62f 100644 --- a/source/Hardware Guide/Datasheets/fmc-link-control.rst +++ b/source/Hardware Guide/Datasheets/fmc-link-control.rst @@ -109,7 +109,7 @@ Register Programming - R - When LOCK or PASS change - 0 - - None + - None - Link state * Bit 0: LOCK @@ -123,7 +123,7 @@ Register Programming - None - Misc. options for the link device - * Bit 0: `0` Port auto-shutdown disabled `1` Port auto-shutdown enabled + * Bit 0: `0` Port auto-shutdown disabled `1` Port auto-shutdown enabled .. _onidatasheet_fmc_link_control_d2h: @@ -158,28 +158,28 @@ Each frame transmitted to the host is structured as follows: This device produces frames when triggered by the **CV**, **PP**, or **SL** bits. These are defined as follows: - CV - Codeword valid. Indicates that the Status Codeword field has valid data. - A frame is produced when this bit goes high. The codeword meaning is - hub-dependent. See hub documentation for definitions. +CV + Codeword valid. Indicates that the Status Codeword field has valid data. + A frame is produced when this bit goes high. The codeword meaning is + hub-dependent. See hub documentation for definitions. - PP - Parity check pass. This bit reflects the state of the PASS pin on the - DS90UB9x4 deserializer. +PP + Parity check pass. This bit reflects the state of the PASS pin on the + DS90UB9x4 deserializer. - - 0b0: One or more errors were detected in the received payload. - - 0b1: Error free transmission in forward channel operation. + - 0b0: One or more errors were detected in the received payload. + - 0b1: Error free transmission in forward channel operation. - A frame is produced whenever this bit changes state. + A frame is produced whenever this bit changes state. - SL - SERDES lock. This bit reflects the state of the LOCK pin on the DS90UB9x4 - deserializer, which monitors the lock status of FPD-Link III channel. +SL + SERDES lock. This bit reflects the state of the LOCK pin on the DS90UB9x4 + deserializer, which monitors the lock status of FPD-Link III channel. - - 0b0: PLL is unlocked link is down. - - 0b1: PLL is locked, link is active. + - 0b0: PLL is unlocked link is down. + - 0b1: PLL is locked, link is active. - A frame is produced whenever this bit changes state. + A frame is produced whenever this bit changes state. Host To Device Data Frames ****************************************** diff --git a/source/Hardware Guide/Datasheets/load-test.rst b/source/Hardware Guide/Datasheets/load-test.rst index a23b1691..b9f36c45 100644 --- a/source/Hardware Guide/Datasheets/load-test.rst +++ b/source/Hardware Guide/Datasheets/load-test.rst @@ -3,7 +3,7 @@ Load Test Device ########################################### :Authors: Jonathan P. Newman -:Version: 1 +:Version: 2 :IO: Frame Source, Register Access :ONIX ID: 27 :ONIX Hubs: This device is used for real-world bandwidth and latency testing. @@ -63,15 +63,15 @@ Register Programming - On Reset - 0 - None - - The number of incrementing 16-bit integers sent in each frame. + - The number of incrementing 16-bit integers sent in each read-frame. - .. note:: + .. note:: The maximum value of DT0H16_WORDS depends of CLK_HZ and CLK_DIV. There needs to be enough clock cycles to satisfy .. math:: - DT0H16\_WORDS <= CLK\_HZ / CLK\_DIV - 9 + DT0H16\_WORDS <= CLK\_HZ / CLK\_DIV - 9 Setting DTOH16_WORDS above this value will result in a *decreased* device to host load as samples will be skipped. @@ -82,19 +82,30 @@ Register Programming - On Reset - 0 - None - - The number of 32-bit word dummy data in in each Host To Device frame. - Write frames always start with a single 64-bit unsisigned integer, - which is looped subtracted from the Hub Clock Counter when it is - received to produce a Hub Clock Delta that is looped back into the - device to host data frame for testing loop latency. All other data is - ingored. + - The number of 32-bit dummy words in a write-frame. Write-frames always + start with a single 64-bit unsigned integer that is subtracted from the + current acquisition clock counter value when it is received. This value + is looped back into the device to host data frame for testing loop + latency. After the 64-bit unsigned integer, write-frames contain + HTOD32_WORDS 32-bit words which are read and ignored by the device. + These values can be used to test the impact of various data transmission + loads on closed-loop performance. + + * - 0x05 + - DTOH_START + - R/W + - On Reset + - 0 + - None + - The start value of the counter being sent sent with each read-frame. + .. _onidatasheet_loadtest_d2h: Device To Host Data Frames ****************************************** -With DT0H16_WORDS = 4, each frame transmitted to the host is structured as -follows: +With DT0H16_WORDS = 4 and DTOH_START= 42, the first frame transmitted to the host +is structured as follows: .. wavedrom:: @@ -108,10 +119,10 @@ follows: {bits: 64, name: "Hub Clock Delta", type: 5}, - {bits: 16, name: "Frame Word 0", type: 6, atter:42}, - {bits: 16, name: "Frame Word 1", type: 6, atter:43}, - {bits: 16, name: "Frame Word 2", type: 6, atter:44}, - {bits: 16, name: "Frame Word 3", type: 6, atter:45} + {bits: 16, name: "Frame Word 0", type: 6, attr:42}, + {bits: 16, name: "Frame Word 1", type: 6, attr:43}, + {bits: 16, name: "Frame Word 2", type: 6, attr:44}, + {bits: 16, name: "Frame Word 3", type: 6, attr:45} ], config: {bits: 320, lanes: 10, vflip: true, hflip: true, fontsize: 11} @@ -119,16 +130,16 @@ follows: | - Hub Clock Counter Delta - 64-bit unsigned integer that the result of subtracting the Hub Clock - Counter value from the Hub Clock Counter Loop back value in - :ref:`onidatasheet_loadtest_h2d`. This provides a real-world, hardware - timed measurement of closed-loop latency. +Hub Clock Counter Delta + 64-bit unsigned integer that the result of subtracting the Hub Clock + Counter value from the Hub Clock Counter Loop back value in + :ref:`onidatasheet_loadtest_h2d`. This provides a real-world, hardware + timed measurement of closed-loop latency. - Frame Word N - Ignored data that can be used for host to device load testing. When - DT0H16_WORDS is set to a different value, the Data Size field along with - the number of words at the end of the frame will change. +Frame Word N + Ignored data that can be used for host to device load testing. When + DT0H16_WORDS is set to a different value, the Data Size field along with + the number of words at the end of the frame will change. .. _onidatasheet_loadtest_h2d: @@ -155,10 +166,10 @@ follows: | - Hub Clock Counter Loopback - 64-bit unsigned integer that is subtracted from the current Hub Clock - Counter value to produce the Hub Clock Counter Delta field in - :ref:`onidatasheet_bno055_d2h`. +Hub Clock Counter Loopback + 64-bit unsigned integer that is subtracted from the current Hub Clock + Counter value to produce the Hub Clock Counter Delta field in + :ref:`onidatasheet_loadtest_d2h`. - Frame Word N - Ignored data that can be used for host to device load testing. +Frame Word N + Ignored data that can be used for host to device load testing. diff --git a/source/Hardware Guide/Datasheets/rhs2116-trigger.rst b/source/Hardware Guide/Datasheets/rhs2116-trigger.rst index 08d87620..7023d8b2 100644 --- a/source/Hardware Guide/Datasheets/rhs2116-trigger.rst +++ b/source/Hardware Guide/Datasheets/rhs2116-trigger.rst @@ -63,12 +63,30 @@ Register Programming - W - Immediate - 0 - - 0 - - Writing 0x1 to this register will trigger a stimulation sequence if the - TRIGGERSOURCE is set to 0x0 (transmitter). Otherwise it will do nothing. + - None + - A 32-bit value, ``[dly_19, dly_18, ..., dly_0, X, X, ..., X, trigger]``, that initiates a stimulus sequence if the + TRIGGERSOURCE is set to 0x0: + + - ``dly_n`` : global delay for application of stimulus sequence in units + of sample periods. + - ``trigger``: When set to 0b1, trigger stimulation sequence + (subject to global delay). This bit is reset to 0 following application. + Regardless, this register is automatically be reset to 0x0 immediately after writing to it. + * - 0x03 + - TRIGGERARMED + - R/W + - Immediate + - 0x1 + - None + - Writing 0x0 to this register will cause the device to ignore all trigger + inputs regardless of TRIGGERSOURCE. Writing 0x1 to this register will + cause the device to respect the trigger input specified by + TRIGGERSOURCE. + + Device To Host Data Frames ****************************************** No frames are transmitted to the host. diff --git a/source/Hardware Guide/Datasheets/rhs2116.rst b/source/Hardware Guide/Datasheets/rhs2116.rst index 88b6cc4e..67980ef3 100644 --- a/source/Hardware Guide/Datasheets/rhs2116.rst +++ b/source/Hardware Guide/Datasheets/rhs2116.rst @@ -3,7 +3,7 @@ RHS2116 ########################################### :Authors: Jonathan P. Newman -:Version: 1 +:Version: 3 :IO: Frame Source, Register Access :ONIX ID: 31 @@ -239,12 +239,25 @@ waveforms. {bits: 6}, {bits: 10, name: "Channel 15 DC Voltage", type: 5}, - {bits: 16}, + {bits: 16, name: "Recovery State", type: 6} ], config: {bits: 720, lanes: 23, vflip: true, hflip: true, fontsize: 11} } +AC Voltage + AC-coupled, high-gain electrophysiology data array. Each ADC sample is an + 16-bit, offset binary value + +DC Voltage + DC-coupled, low-gain amplifier data array for monitoring stimulation + waveforms. Each ADC sample is an 10-bit, offset binary value + +Recovery State + A 16-element bit mask indicating if a channel in stimulus recovery at the + time indicated by the Hub Clock Counter value in the frame. A value of 1b1 + at index N indicates that channel N is currently in stimulus recovery mode. + .. _onidatasheet_rhs2116_h2d: Host To Device Data Frames From 193d7dc54f0893e9cf6ea4d7afd8eff5a52bc00e Mon Sep 17 00:00:00 2001 From: cjsha Date: Tue, 16 Sep 2025 15:23:05 -0400 Subject: [PATCH 2/2] fix typos/minor errors --- source/Hardware Guide/Datasheets/bno055.rst | 4 +-- .../Datasheets/fmc-digital-io.rst | 26 ------------------- source/Hardware Guide/Datasheets/rhs2116.rst | 2 +- 3 files changed, 3 insertions(+), 29 deletions(-) diff --git a/source/Hardware Guide/Datasheets/bno055.rst b/source/Hardware Guide/Datasheets/bno055.rst index 242065c0..0e254aff 100644 --- a/source/Hardware Guide/Datasheets/bno055.rst +++ b/source/Hardware Guide/Datasheets/bno055.rst @@ -100,9 +100,9 @@ byte in the frame). The unit conversions for each of these measurements are as follows: Euler angle (Tait-Bryan formalism) + - Pitch: -180 to 180 degrees + - Roll: -90 to 90 degrees - Yaw: 0 to 360 degrees - - Roll: -180 to 180 degrees - - Pitch: -90 to 90 degrees .. math:: diff --git a/source/Hardware Guide/Datasheets/fmc-digital-io.rst b/source/Hardware Guide/Datasheets/fmc-digital-io.rst index 65bc6508..ee3bab22 100644 --- a/source/Hardware Guide/Datasheets/fmc-digital-io.rst +++ b/source/Hardware Guide/Datasheets/fmc-digital-io.rst @@ -280,32 +280,6 @@ current digital input and user input state. config: {bits: 224, lanes: 7, vflip: true, hflip: true, fontsize: 11} } -.. wavedrom:: - - { - reg: [ - {bits: 64, name: "Acquisition Clock Counter", type: 0}, - {bits: 32, name: "Device Address", type: 0}, - {bits: 32, name: "Data Size", type: 0, attr: 10}, - - {bits: 64, name: "Hub Clock Counter", type: 3}, - - {bits: 8, name: "Status Codeword", type: 4}, - - {bits: 5, name: "Reserved"}, - - {bits: 1, name: "CV", type: 2}, - {bits: 1, name: "PP", type: 2}, - {bits: 1, name: "SL", type: 2}, - - {bits: 16} - - ], - config: {bits: 224, lanes: 7, vflip: true, hflip: true, fontsize: 11} - } - -| - Input Port State 8-bit input port state diff --git a/source/Hardware Guide/Datasheets/rhs2116.rst b/source/Hardware Guide/Datasheets/rhs2116.rst index 67980ef3..5202df03 100644 --- a/source/Hardware Guide/Datasheets/rhs2116.rst +++ b/source/Hardware Guide/Datasheets/rhs2116.rst @@ -255,7 +255,7 @@ DC Voltage Recovery State A 16-element bit mask indicating if a channel in stimulus recovery at the - time indicated by the Hub Clock Counter value in the frame. A value of 1b1 + time indicated by the Hub Clock Counter value in the frame. A value of 0b1 at index N indicates that channel N is currently in stimulus recovery mode. .. _onidatasheet_rhs2116_h2d: