diff --git a/source/hw-spec/controller.rst b/source/hw-spec/controller.rst deleted file mode 100644 index 6ae94e6..0000000 --- a/source/hw-spec/controller.rst +++ /dev/null @@ -1,355 +0,0 @@ -.. _controller: - -Controller -========== -The controller's purpose is to interface an ONI hardware system with the host -computer. It aggregates and routes device data and provides transparent access -to all devices, independently of their physical location. The host also -contains a common clock that is used to timestamp data from all devices, -independently of their origin hub. - -Communication between the controller and the host computer shall occur over -four abstract communication channels: - -#. **Read**: Read-only, high-bandwidth stream of device output samples from - controller to host. -#. **Write**: Write-only, high-bandwidth stream of device input samples from - host to controller. -#. **Signal**: Read-only stream of short-messages and asynchronous hardware - events from controller to host. -#. **Configuration**: Bidirectional, addressed access to device registers. - -API access to all these channels is blocking, i.e.: an API call that accesses -any channel will not return until the requested transaction on that channel is -complete. Concurrent access to a single channel by different threads is NOT -permitted. However, channels are independent and concurrent access to -*different* channels MUST be permitted. A stream transaction is defined as a -blocking read or write of a set number of bytes, while a register transaction -is defined as a single register read or write cycle to an individual address. - -The required characteristics of these channels are described in the following -sections. A complete understanding of their use during software development -requires an understanding of the :ref:`oni-api`. - -.. _data-rd-chan: - -Read Channel ------------- - -- **Word size** : 32 bits -- **Channel type** : Stream -- **Direction** : Read - -The *read* channel provides high bandwidth communication from the controller to -the host computer. Data from the read stream of all devices that support it is -aggregated and multiplexed by the controller and sent to the host through this -channel. - -Data should be pushed to this channel as quickly as possible. It is the -responsibility of the host computer to read data from the stream quickly enough -to keep up with data production by the controller. Therefore, it is highly -recommended that an ONI system implements some kind of internal buffering to -ameliorate the effects of uneven reading times caused by computer operating -systems or other software limitations. - -.. _frame: - -Data Frames -~~~~~~~~~~~ - -Data from the read channel is packed in frames. Each frame is a timestamped -`type-length-value-encoded `__ -structure that contains data from a single device :ref:`sample `. -The frame format is: - -:: - - uint64 Common_Timestamp - uint32 Device_Address - uint32 Sample_Size - var Sample - -Where - -- ``Common_Timestamp``: A counter common to all devices generated by the - controller common acquisition clock. -- ``Device_Address``: The address of the device producing the data, as featured - on the :ref:`device table `. -- ``Sample_Size``: The full size of the sample, and must be equal to the - ``Read_Sample_Size`` field of the :ref:`device descriptor `. -- ``Sample``: The complete data sample as described on the :ref:`device sample - format ` section. - -.. _data-wr-chan: - -Write Channel -------------- - -- **Word size** : 32 bits -- **Channel type** : Stream -- **Direction** : Write - -The *write* channel provides high bandwidth communication from the host computer -to the controller, and is used to send data to the devices. - -Data is sent with a :ref:`frame ` format identical to the one used for -read, but without the ``Common_Timestamp`` field. It is the responsibility of -the controller to accept frames at any rate the computer might be sending them. -Currently, there is no defined mechanism to inform the host of any possible -dropped frame on the write channel, although this can be included in an -implementation so long as it does not invalidate any other ONI -requirements. - -.. _sig-chan: - -Signal channel --------------- - -- **Word size** : 8 bits -- **Channel type** : Stream -- **Direction** : Read - -The *signal* channel provides a way for the controller to inform the host of -configuration results, which may be provided with a significant delay. -Additionally, it is the channel over which the controller sends the device table -to the host following a system reset. Signal data MUST be framed into packets -using Consistent Overhead Byte Stuffing -(`COBS `__). -Within this scheme, packets are delimited using 0's and always have the -following format: - -:: - - ... | PACKET_FLAG, data0, data1, ..., data_k | ... - -where ``PACKET_FLAG`` is 32-bit unsigned integer with a single unique bit -setting, ``|`` represents a packet delimiter (in this case, 0), “``,``” are for -visual clarity and are not actually in the data stream, and ``...`` represents -other packets. This stream can be read and ignored until a desired packet is -received. Reading this stream shall block if no data is available, which allows -asynchronous configuration acknowledgment. Valid ``PACKET_FLAG``\ s are: - -============ ========== ===================================== -Flag Value Description -============ ========== ===================================== -NULLSIG 0x00000001 Null signal, ignored by host -CONFIGWACK 0x00000002 Configuration write-acknowledgment -CONFIGWNACK 0x00000004 Configuration no-write-acknowledgment -CONFIGRACK 0x00000008 Configuration read-acknowledgment -CONFIGRNACK 0x00000010 Configuration no-read-acknowledgment -DEVICETABACK 0x00000020 Device table start acknowledgment -DEVICEINST 0x00000040 Device descriptor instance -============ ========== ===================================== - -Following a hardware reset, the signal channel is used to provide the -:ref:`device table ` to the host using the following packet -sequence: - -:: - - ... | DEVICETABACK, uint32 num_devices - | DEVICEINST, uint32 dev_addr_0, device_descriptor dev_0 - | DEVICEINST, uint32 dev_addr_1, device_descriptor dev_1 | - ... - | DEVICEINST, uint32 dev_addr_n, device_descriptor dev_n | ... - -Where ``dev_addr_n`` is the full address of each device as described in the -:ref:`device table ` section and ``dev_n`` is a :ref:`device -descriptor `. - -In addition to providing the device table following reset, the signal channel -is also used to asynchronously acknowledge register access via the -:ref:`configuration channel `. Following a device register read or -write, an CONFIGWACK, CONFIGWNACK, CONFIGRACK, or CONFIGRNACK signal is pushed -onto the signal stream by the controller to indicate the validity of the -transaction. For instance, on a successful register read: - -:: - - ... | CONFIGRACK | ... - -.. _conf-chan: - -Configuration Channel ---------------------- - -- **Word size** : 32 bits -- **Channel type** : Register -- **Direction** : Read-Write - -The *configuration* channel supports addressed access to a set of configuration -registers. There are two classes of registers handled by the configuration -channel: the first set of registers encapsulates a generic device register -programming interface. The remaining registers are for global controller -control and configuration and provide access to acquisition parameters and -state control. - -The interface must use 32-bit values and, at least, 24-bit addressing. The -required register map is as follows: - -========== ========================= ================== -Address Name Type -========== ========================= ================== -0x00000000 Device Address Register interface -0x00000001 Register Address Register interface -0x00000002 Register Value Register interface -0x00000003 Read/Write Register interface -0x00000004 Trigger Register interface -0x00000005 Running Global -0x00000006 Reset Global -0x00000007 System Clock Global -0x00000008 Acquisition Clock Global -0x00000009 Reset Acquisition Counter Global -0x0000000A Hardware Address Global -========== ========================= ================== - -Device Register Programming Interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The device programming interface allows transparent access to each device's -:ref:`register map `. It defines a general purpose bus that hides -the specifics of any particular implementation. It is composed of the following -configuration channel registers: - -- ``Device Address``: The fully qualified address of a device as enumerated in - the :ref:`device table ` and to which communication will be - directed as described below. - -- ``Register Address``: The address of the register within the :ref:`register - map ` of the device located at ``Device Address`` that will be - written to or read from. - -- ``Register Value``: Value to be written to or read from and that corresponds - to the register ``Register Address`` of device located at - ``Device Address``. - -- ``Read/Write``: A flag indicating if a read or write should be performed. 0 - indicates read operation. A value > 0 indicates write operation. - -- ``Trigger``: Set > 0 to trigger either register read or write operation - depending on the state of ``Read/Write``. If ``Read/Write`` is 0, a read is - performed. In this case, after a successful operation, ``Register Value`` is - updated with value stored in the register at ``Register Address`` on the - device at ``Device Address``. If ``Read/Write`` is 1, ``Register Value`` is - written to register at ``Register Address`` on the device at - ``Device Address``. The ``Trigger`` register is always set low by the - controller following transmission even if it is not successful or does not - make sense given the supplied register address and/or value. - -Appropriate values of ``Register Address`` and ``Register Value`` are -determined by: - -- Looking at a device's data sheet if the device is an integrated circuit and - using :ref:`raw registers `. -- Examining the :ref:`ONI Device Datasheet ` for :ref:`managed - registers `. - -Register Read Sequence -^^^^^^^^^^^^^^^^^^^^^^ -When a host requests a device register *read*, the following following sequence -must be performed: - -1. Check the value of ``Trigger``. - - - If it is 0, the procedure can proceed. - - Else, the hardware is busy with a previous transaction and a new one - cannot be issued. - -2. The target device is selected by writing its address, as featured on the - device map, into ``Device Address`` on the controller. -3. The desired register address within the device register map is written into - ``Register Address`` on the controller. -4. The ``Read/Write`` register on the controller is set to 0x00. -5. The ``Trigger`` register on the controller is set to 0x01, triggering - configuration transmission. - - 1. (Controller) A register read is routed by the controller to the - appropriate device. - 2. (Controller) ``Trigger`` is set to 0x00 once the operation finishes. - 3. (Controller) ``CONFIGRACK`` is pushed into the signal stream if the - operation was successful, ``CONFIGRNACK`` is pushed if it failed. - -6. The signal stream must be pumped until either ``CONFIGRACK`` or - ``CONFIGRNACK`` is received indicating that controller has either: - - - Completed reading the specified device register and copied its value to - the ``Register Value`` register. - - Failed to read the register in which case the value of ``Register Value`` - contains invalid data. - -7. If operation was successful, the ``Register Value`` can be read. - -Register Write Sequence -^^^^^^^^^^^^^^^^^^^^^^^ -When a host requests a device register *write*, the following following -sequence must be performed: - -1. Check the value of ``Trigger``. - - - If it is 0, the procedure can proceed. - - Else, the hardware is busy with a previous transaction and a new one - cannot be issued. - -2. The target device is selected by writing its address, as featured on the - device map, into ``Device Address`` on the controller -3. The desired register address within the device register map is written into - ``Register Address`` on the controller. -4. The ``Read/Write`` register on the controller is set to 0x01. -5. The ``Trigger`` register on the controller is set to 0x01, triggering - configuration transmission. - - 1. (Controller) A register write is routed by the controller to the - appropriate device. - 2. (Controller) ``Trigger`` is set to 0x00 once the operation finishes. - 3. (Controller) ``CONFIGWACK`` is pushed into the signal stream if the - operation was successful, ``CONFIGWNACK`` is pushed if it failed. - -6. The signal stream must be pumped until either ``CONFIGWACK`` or - ``CONFIGWNACK`` is received indicating that the controller has either: - - - Successfully completed writing the specified device register. - - Failed to write the register. - -Following successful or unsuccessful device register read or write, the -appropriate ACK or NACK packets *must* be passed to the :ref:`signal channel -` by the controller. If they are not, the register read and write -calls will block indefinitely. - -Global Acquisition Registers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following global acquisition registers provide information about, and -control over, the entire acquisition system: - -- ``Running``: Set to > 0 to run the system clock and produce data. Set to 0 to - stop the system clock and therefore stop data flow. Results in no other - configuration changes. - -- ``Reset``: Set to > 0 to trigger a hardware reset and send a fresh device - map to the host. Devices are reset but their managed registers might remain - unchanged, depending on their configuration (See the :ref:`Device registers - ` section for more information). Set to 0 by the controller - upon entering the reset state. - -- ``System Clock``: A read-only register specifying the master hardware clock - frequency in Hz. This is the clock used by the controller to perform data - transmission. - -- ``Acquisition Clock``: A read-only register specifying the system common - clock frequency in Hz. This clock is used to generate an acquisition counter - that timestamps data from all the devices. The ``Common_Timestamp`` in the - read :ref:`frame ` header is incremented at this frequency. - -- ``Reset Acquisition Counter``: This register is used to reset the counter - generating the ``Common_Timestamp`` used in the :ref:`device frames `. - A value of 1 will reset the counter to 0 without affecting the ``Running`` - state. A value of 2 will reset the counter and, at the same time, set - ``Running`` to 1, starting data production. - -- ``Hardware Address``: This is used for systems that allow multiple - controllers with a link between them to synchronize their - ``Common_Timestamps``. When resetting the acquisition counter through the - ``Reset acquisition counter`` on a device with a ``Hardware Address`` of 0, - this command will be sent through an external link to all non-zero devices, - synchronizing the counters. Multiple controller support or hardware-based - timestamp synchronization through dedicated links are optional features of an - ONI system. - diff --git a/source/hw-spec/controller/addresses.rst b/source/hw-spec/controller/addresses.rst new file mode 100644 index 0000000..e770921 --- /dev/null +++ b/source/hw-spec/controller/addresses.rst @@ -0,0 +1,141 @@ +.. _addresses: + +ONI Controller address space +================================= + +An ONI :term:`Controller` has a 16-bit address register space, accessible through the :ref:`conf-chan`. + +The full address space is divided into three address blocks and a fourth currently reserved. The address blocks are: + +.. _address_global: + +Operation registers +------------------- + +**Address range:** 0x0000-0x3FFF + + +This address block is dedicated to controlling the operation of the system and accessing :ref:`dev-register`. + +The address map for this block is as follows: + +========== ========================= ================== +Address Name Type +========== ========================= ================== +0x0000 Reset Global +0x0001 Running Global +0x0002 System Clock Global +0x0003 Acquisition Clock Global +0x0004 Reset Acquisition Counter Global +0x0005 Hardware Address Global +0x0006 Device Address Register interface +0x0007 Register Address Register interface +0x0008 Register Value Register interface +0x0009 Read/Write Register interface +0x000A Trigger Register interface +========== ========================= ================== + +Global Acquisition Registers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The following global acquisition registers provide information about, and +control over, the entire acquisition system: + +- ``Running``: Set to > 0 to run the system clock and produce data. Set to 0 to + stop the system clock and therefore stop data flow. Results in no other + configuration changes. + +- ``Reset``: Set to > 0 to trigger a hardware reset and send a fresh device + map to the host. Devices are reset but their managed registers might remain + unchanged, depending on their configuration (See the :ref:`Device registers + ` section for more information). Set to 0 by the controller + upon entering the reset state. + +- ``System Clock``: A read-only register specifying the master hardware clock + frequency in Hz. This is the clock used by the controller to perform data + transmission. + +- ``Acquisition Clock``: A read-only register specifying the system common + clock frequency in Hz. This clock is used to generate an acquisition counter + that timestamps data from all the devices. The ``Common_Timestamp`` in the + read :ref:`frame ` header is incremented at this frequency. + +- ``Reset Acquisition Counter``: This register is used to reset the counter + generating the ``Common_Timestamp`` used in the :ref:`device frames `. + A value of 1 will reset the counter to 0 without affecting the ``Running`` + state. A value of 2 will reset the counter and, at the same time, set + ``Running`` to 1, starting data production. + + .. _optional-num-sync-dev: + +- ``Hardware Address``: :ref:`(OPTIONAL) ` This is used for systems that allow multiple + controllers with a link between them to synchronize their + ``Common_Timestamps``. When resetting the acquisition counter through the + ``Reset acquisition counter`` on a device with a ``Hardware Address`` of 0, + this command will be sent through an external link to all non-zero devices, + synchronizing the counters. When supported, synchronization is only required + for controllers sharing a hardware implementation. + +Device Register Interface +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These registers provide a standardized way to access :ref:`dev-register`. Read and write +procedures to device registers are detailed in :ref:`register_interface`. + +.. _address_spec: + +Specification parameters +------------------------- + +**Address range:** 0x4000-0x7FFF + +This block contains read-only registers that contain information about hardware +capabilities and ONI specification compliance. + +Currently defined addresses are: + +======== =========================== +Address Name +======== =========================== +0x4000 ONI specification version +0x4001 Read stream alignment +0x4002 Write stream alignment +0x4003 Maximum queued device register operations +0x4004 Number of supported synchronized devices +======== =========================== + +- **ONI specification version**: Specifies the version of the ONI specification the controller adheres to. + Format is, bits 31-24: Major, 23-16: Minor, 15-8: patch, 7-0: reserved + +.. _read-word-alignment-reg: + +- **Read stream alignment**: Specifies, in bits, the data word size the hardware implementation of + the :ref:`read channel ` uses for transmission. + +.. _write-word-alignment-reg: + +- **Write stream alignment**: Specifies, in bits, the data word size the hardware implementation of + the :ref:`write channel ` uses for transmission. + +.. _max-devaccess-reg: + +- **Maximum queued device register operations**: Maximum number of operations that can be queued through the + :ref:`register_interface` + +.. _optional-num-sync-dev-reg: + +- **Number of supported synchronized devices**: This register indicates if the optional capability + for :ref:`hardware synchronization` is supported. If 0, this controller can + not synchronize with others. if >0, it indicates the maximum number of controllers that can be synchronized + together. If the value is 0xFFFFFFFF, then there is no upper bound to this number. + + +.. _address_custom: + +Hardware-specific registers +---------------------------- +**Address range:** 0x8000-0xBFFF + +This block is reserved for hardware-specific registers that fall out of the scope of this specification +but might be required for the correct operation of a specific hardware implementation. + +The :term:`Driver Translator` should, to the possible extent, hide these from the :term:`API`. diff --git a/source/hw-spec/controller/channels/configuration_channel.rst b/source/hw-spec/controller/channels/configuration_channel.rst new file mode 100644 index 0000000..a0940ac --- /dev/null +++ b/source/hw-spec/controller/channels/configuration_channel.rst @@ -0,0 +1,18 @@ +.. _conf-chan: + +Configuration Channel +====================== + +- **Data alignment** : 32 bits +- **Channel type** : Register +- **Direction** : Read-Write + +The *configuration* channel supports addressed access to a set of registers. +The interface must use 32-bit values and 16-bit addressing. Controllers must +implement an :ref:`address map` with all the registers required +by the specification. + +This channel is also used to access the :ref:`register map ` +of the individual devices through an interface comprised of specific +:ref:`configuration registers`. + diff --git a/source/hw-spec/controller/channels/data_frames.rst b/source/hw-spec/controller/channels/data_frames.rst new file mode 100644 index 0000000..04227a1 --- /dev/null +++ b/source/hw-spec/controller/channels/data_frames.rst @@ -0,0 +1,33 @@ +.. _frame: + +Data Frames +============ + +Data transmission from the :ref:`read channel` and from the :ref:`write channel` +is packed in frames. Each frame is a timestamped +`type-length-value-encoded `__ +structure that contains data corresponding to a single device :ref:`sample `. +The frame format is: + +:: + + uint32 Device_Address + uint64 Common_Timestamp + uint32 Sample_Size + var Sample + +Where + +- ``Device_Address``: The address of the device producing the data, as featured + on the :ref:`device table `. +- ``Common_Timestamp``: A counter common to all devices generated by the + controller common acquisition clock. On write frames, this field is ignored. +- ``Sample_Size``: The full size of the sample, and must be equal to the + ``Read_Sample_Size`` field of the :ref:`device descriptor ` on read + frames or a multiple of the ``Write_Sample_Size`` on write frames. +- ``Sample``: The complete data sample as described on the :ref:`device sample + format ` section. + + + While a read frame must always contain a single sample as generated by the devices, + write frames can contain multiple samples targeted to the same device. \ No newline at end of file diff --git a/source/hw-spec/controller/channels/index.rst b/source/hw-spec/controller/channels/index.rst new file mode 100644 index 0000000..b204fd1 --- /dev/null +++ b/source/hw-spec/controller/channels/index.rst @@ -0,0 +1,38 @@ +.. _controller_channels: + +Controller communication channels +================================== + +Communication between the controller and the host computer shall occur over +four abstract communication channels: + +#. :ref:`data-rd-chan`: Read-only, high-bandwidth stream of device output :ref:`samples` from + controller to host. +#. :ref:`data-wr-chan`: Write-only, high-bandwidth stream of device input :ref:`samples` from + host to controller. +#. :ref:`sig-chan`: Read-only stream of short-messages and asynchronous hardware + events from controller to host. +#. :ref:`conf-chan`: Bidirectional, addressed access to device registers. + +API access to all these channels is blocking, i.e.: an API call that accesses +any channel will not return until the requested transaction on that channel is +complete. Concurrent access to a single channel by different threads is NOT +permitted. However, channels are independent and concurrent access to +*different* channels MUST be permitted. A stream transaction is defined as a +blocking read or write of a set number of bytes, while a register transaction +is defined as a single register read or write cycle to an individual address. + +The required characteristics of these channels are described in the following +sections. A complete understanding of their use during software development +requires an understanding of the :ref:`oni-api`. + +.. toctree:: + :hidden: + + data_frames + read_channel + write_channel + signal_channel + configuration_channel + + diff --git a/source/hw-spec/controller/channels/read_channel.rst b/source/hw-spec/controller/channels/read_channel.rst new file mode 100644 index 0000000..f60df59 --- /dev/null +++ b/source/hw-spec/controller/channels/read_channel.rst @@ -0,0 +1,31 @@ +.. _data-rd-chan: + +Read Channel +============= + +- **Data alignment** : 8 bits +- **Channel type** : Stream +- **Direction** : Read + +The *read* channel provides high bandwidth communication from the controller to +the host computer. Data from the read stream of all devices that support it is +aggregated and multiplexed by the controller and sent to the host through this +channel in the form of :ref:`frame`. + +Data should be pushed to this channel as quickly as possible. It is the +responsibility of the host computer to read data from the stream quickly enough +to keep up with data production by the controller. Therefore, it is highly +recommended that an ONI system implements some kind of internal buffering to +ameliorate the effects of uneven reading times caused by computer operating +systems or other software limitations. + +.. _read-word-alignment: + +Read word alignment +--------------------- + +Hardware implementations of controllers might require a :ref:`word size` +greater than 8 bits. In that case, the controller is required to increase the ``Read_Sample_Size`` +values of all devices on the :ref:`dev-table` so they fit into the required +word alignment. Extra bytes after the size defined on the :term:`Device Datasheet` +will be padded with 0xFF. \ No newline at end of file diff --git a/source/hw-spec/controller/channels/signal_channel.rst b/source/hw-spec/controller/channels/signal_channel.rst new file mode 100644 index 0000000..f4393aa --- /dev/null +++ b/source/hw-spec/controller/channels/signal_channel.rst @@ -0,0 +1,77 @@ +.. _sig-chan: + +Signal channel +=============== + +- **Data alignment** : 8 bits +- **Channel type** : Stream +- **Direction** : Read + +The *signal* channel provides a way for the controller to inform the host of +configuration results, which may be provided with a significant delay. +Additionally, it is the channel over which the controller sends the device table +to the host following a system reset. Signal data MUST be framed into packets +using Consistent Overhead Byte Stuffing +(`COBS `__). +Within this scheme, packets are delimited using 0's and always have the +following format: + +:: + + ... | PACKET_FLAG, data0, data1, ..., data_k | ... + +where ``PACKET_FLAG`` is 32-bit unsigned integer with a single unique bit +setting, ``|`` represents a packet delimiter (in this case, 0), “``,``” are for +visual clarity and are not actually in the data stream, and ``...`` represents +other packets. This stream can be read and ignored until a desired packet is +received. Reading this stream shall block if no data is available, which allows +asynchronous configuration acknowledgment. Valid ``PACKET_FLAG``\ s are: + +============ ========== ===================================== +Flag Value Description +============ ========== ===================================== +NULLSIG 0x00000001 Null signal, ignored by host +CONFIGWACK 0x00000002 Configuration write-acknowledgment +CONFIGWNACK 0x00000004 Configuration no-write-acknowledgment +CONFIGRACK 0x00000008 Configuration read-acknowledgment +CONFIGRNACK 0x00000010 Configuration no-read-acknowledgment +DEVICETABACK 0x00000020 Device table start acknowledgment +DEVICEINST 0x00000040 Device descriptor instance +============ ========== ===================================== + +Following a hardware reset, the signal channel is used to provide the +:ref:`device table ` to the host using the following packet +sequence: + +:: + + ... | DEVICETABACK, uint32 num_devices + | DEVICEINST, uint32 dev_addr_0, device_descriptor dev_0 + | DEVICEINST, uint32 dev_addr_1, device_descriptor dev_1 | + ... + | DEVICEINST, uint32 dev_addr_n, device_descriptor dev_n | ... + +Where ``dev_addr_n`` is the full address of each device as described in the +:ref:`device table ` section and ``dev_n`` is a :ref:`device +descriptor `. + +In addition to providing the device table following reset, the signal channel +is also used to asynchronously acknowledge register access via the +:ref:`configuration channel `. Following a device register read or +write, an CONFIGWACK, CONFIGWNACK, CONFIGRACK, or CONFIGRNACK signal is pushed +onto the signal stream by the controller to indicate the validity of the +transaction. In the case of a successful read, the CONFIGRACK flag will be +followed by the result of the read operation. In all other cases, the flag +will be sent with no additional data. + +For instance, on a successful register read: + +:: + + ... | CONFIGRACK, uint32 read_value | ... + +While on a succesful register write: + +:: + + ... | CONFIGWACK | ... \ No newline at end of file diff --git a/source/hw-spec/controller/channels/write_channel.rst b/source/hw-spec/controller/channels/write_channel.rst new file mode 100644 index 0000000..eb92707 --- /dev/null +++ b/source/hw-spec/controller/channels/write_channel.rst @@ -0,0 +1,32 @@ +.. _data-wr-chan: + +Write Channel +============== + +- **Data alignment** : 8 bits +- **Channel type** : Stream +- **Direction** : Write + +The *write* channel provides high bandwidth communication from the host computer +to the controller, and is used to send data to the devices. + +Data is sent through :ref:`frame` with their respective ``Common_Timestamp`` field +set to 0. Multiple samples can be sent in a single write frame. In this case, the +``Sample_Size`` field will be equal to the ``Write_Sample_Size`` multiplied by the +number of sent samples. + +It is the responsibility of the controller to accept frames at any rate the +computer might be sending them. Currently, there is no defined mechanism to +inform the host of any possible dropped frame on the write channel, +although this can be included in an implementation so long as it does not +invalidate any other ONI requirements. + +.. _write-word-alignment: + +Write word alignment +--------------------- + +Hardware implementations of controllers might require a :ref:`word size` +greater than 8 bits. In that case, the host will keep the specified sample sizes and just add +padding bytes with the value 0xFF at the end of a frame to align with the required word size. +The controller must ignore this padding bytes. \ No newline at end of file diff --git a/source/hw-spec/controller/index.rst b/source/hw-spec/controller/index.rst new file mode 100644 index 0000000..6a6912c --- /dev/null +++ b/source/hw-spec/controller/index.rst @@ -0,0 +1,38 @@ +.. _controller: + +Controller +========== +The :term:`controller`'s purpose is to interface an ONI hardware system with the host +computer. It aggregates and routes device data and provides transparent access +to all devices, independently of their physical location. The host also +contains a common clock that is used to timestamp data from all devices, +independently of their origin hub. + +.. _controller_params: + +Hardware-specific parameters +----------------------------- + +Different ONI-compliant controller implementations might specify hardware-specific parameters related to standard ONI elements. +These need to be informed through a :ref:`specific address space ` reserved for ONI compliance parameters. +:term:`Driver translators ` can use this information to hide hardware-specific details to the +relevant :term:`API`. + +Optional features +^^^^^^^^^^^^^^^^^^^ + +Some features defined in the specification will be marked with the text ``(OPTIONAL)``. These features are not mandatory, +so different hardware implementations of a controller might chose to implement them or not. The ONI compliance +address space has specific registers for each declared optional feature which determine the availability of each +optional feature and its parameters, if applicable. + + +Communication +------------- + +.. toctree:: + :maxdepth: 1 + + channels/index + addresses + register_interface \ No newline at end of file diff --git a/source/hw-spec/controller/register_interface.rst b/source/hw-spec/controller/register_interface.rst new file mode 100644 index 0000000..d19c250 --- /dev/null +++ b/source/hw-spec/controller/register_interface.rst @@ -0,0 +1,123 @@ +.. _register_interface: + +Device Register Programming Interface +====================================== + +The device programming interface allows transparent access to each device's +:ref:`register map `. It defines a general purpose bus that hides +the specifics of any particular implementation. + +Using this interface, the host adds device register access requests to an internal +queue. The controller will execute the requests in order. The :term:`Driver Translator` +and :term:`API` must ensure that the number of pending requests in the does not +exceed the :ref:`maximum queue size`. + +The register programming interface is composed of the following +:ref:`conf-chan` registers, which are used to insert requests into the queue: + +- ``Device Address``: The fully qualified address of a device as enumerated in + the :ref:`device table ` and to which communication will be + directed as described below. + +- ``Register Address``: The address of the register within the :ref:`register + map ` of the device located at ``Device Address`` that will be + written to or read from. + +- ``Register Value``: Value to be written to the register ``Register Address`` + of device located at ``Device Address``. For compatibility with older versions + of the specification, reading this register will return the value of the last + successful read operation. Using this register for reading the value this way + is not recommended. + +- ``Read/Write``: A flag indicating if a read or write should be performed. 0 + indicates read operation. A value > 0 indicates write operation. + +- ``Trigger``: Set > 0 to add either a register read or write operation + depending on the state of ``Read/Write``. If ``Read/Write`` is 0, a read + operation is queued. If ``Read/Write`` is 1, an operation to write ``Register Value`` + to the register at ``Register Address`` on the device at ``Device Address`` is queued. + Reading the ``Triger`` register returns 0 if the queue is empty or 1 if there are + pending operations. + +Appropriate values of ``Register Address`` and ``Register Value`` are +determined by: + +- Looking at a device's data sheet if the device is an integrated circuit and + using :ref:`raw registers `. +- Examining the :ref:`ONI Device Datasheet ` for :ref:`managed + registers `. + +Register Read Sequence +------------------------- + +When a host requests one of more device register *reads*, the following following sequence +must be performed: + +1. Check the value of ``Trigger``. + + - If it is 0, the queue is empty and the procedure can safely proceed. + - Else, there are transactions pending on the queue. Since the + exact number of pending elements is unknown, adding new transactions + is not recommended. + +2. For each register read transaction to be added to the queue: + + 1. The target device is selected by writing its address, as featured on the + device map, into ``Device Address`` on the controller. + 2. The desired register address within the device register map is written into + ``Register Address`` on the controller. + 3. The ``Read/Write`` register on the controller is set to 0x00. + 4. The ``Trigger`` register on the controller is set to 0x01, inserting the + operation on the queue. + 5. Repeat as needed until al read transactions have been queued. + +3. For each element on the queue, the controller will: + + 1. Route a register read operation to the appropriate device. + 2. Push ``CONFIGRACK`` followed by the read value into the signal stream if the + operation was successful, or ``CONFIGRNACK`` if it failed. + +4. The signal stream must be pumped until all ``CONFIGRACK`` or + ``CONFIGRNACK`` corresponding to all the requested transactions + are received indicating that the controller has finished execution. + +Register Write Sequence +------------------------- + +When a host requests one or more device register *writes*, the following following +sequence must be performed: + +1. Check the value of ``Trigger``. + + - If it is 0, the queue is empty and the procedure can safely proceed. + - Else, there are transactions pending on the queue. Since the + exact number of pending elements is unknown, adding new transactions + is not recommended. + +2. For each register write transaction to be added to the queue: + + 1. The target device is selected by writing its address, as featured on the + device map, into ``Device Address`` on the controller + 2. The desired register address within the device register map is written into + ``Register Address`` on the controller. + 3. The ``Read/Write`` register on the controller is set to 0x01. + 4. The value to be written into the device register is written into + the ``Register Value`` register in the controller. + 5. The ``Trigger`` register on the controller is set to 0x01, inserting the + operation on the queue. + 6. Repeat as needed until al read transactions have been queued. + +3. For each element on the queue, the controller will: + + 1. Route a register write operation to the appropriate device. + 2. Push ``CONFIGWACK`` into the signal stream if the operation was successful, + or ``CONFIGRNACK`` if it failed. + +4. The signal stream must be pumped until all ``CONFIGWACK`` or + ``CONFIGWNACK`` corresponding to all the requested transactions + are received indicating that the controller has finished execution. + +Following successful or unsuccessful device register read or write, the +appropriate ACK or NACK packets *must* be passed to the :ref:`signal channel +` by the controller. If they are not, the register read and write +calls will block indefinitely. \ No newline at end of file diff --git a/source/hw-spec/dev_table.rst b/source/hw-spec/dev_table.rst index 3e53aee..f7aee51 100644 --- a/source/hw-spec/dev_table.rst +++ b/source/hw-spec/dev_table.rst @@ -32,6 +32,12 @@ of :ref:`device descriptors `. - 8 - 0 +.. note:: The ``Read_Sample_Size`` reported on the device table might differ from the + one specified on the :term:`Device Datasheet` and :ref:`dev-desc` due to adjustments + required to comply to specific :ref:`hardware word size requirements`. + In this case, the host must ignore the extra bytes and decode the data as specified on the + datasheet. + .. _dev-address: Device Address diff --git a/source/hw-spec/index.rst b/source/hw-spec/index.rst index 2ff1d3a..befeec0 100755 --- a/source/hw-spec/index.rst +++ b/source/hw-spec/index.rst @@ -21,6 +21,6 @@ ONI Hardware Specification dev_table devices hubs - controller + controller/index