diff --git a/source/hw-spec/controller/channels/data_frames.rst b/source/hw-spec/controller/channels/data_frames.rst index 58d99d6..dca3c5f 100644 --- a/source/hw-spec/controller/channels/data_frames.rst +++ b/source/hw-spec/controller/channels/data_frames.rst @@ -12,21 +12,21 @@ The frame format is: :: - uint32 Device_Address - uint64 Common_Timestamp - uint32 Sample_Size - var Sample + uint32 dev_addr + uint64 acqclk_cnt + uint32 sample_sz + var sample Where -- ``Device_Address``: The address of the device producing the data, as featured +- ``dev_addr``: 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 +- ``acqclk_cnt``: Acquisition counter. 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 +- ``sample_sz``: Sample Size. The full size of the sample, and must be equal to the + ``rd_samp_size`` field of the :ref:`device descriptor ` on read + frames or a multiple of the ``wr_samp_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, diff --git a/source/hw-spec/controller/index.rst b/source/hw-spec/controller/index.rst index d6413c6..c364e56 100644 --- a/source/hw-spec/controller/index.rst +++ b/source/hw-spec/controller/index.rst @@ -4,9 +4,26 @@ 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. +to all devices, independently of their physical location. + +.. _acq_clk: + +Acquisition Counter +--------------------- + +The controller MUST have access to a high resolution clock. The tick count from this +clock is used to synchronize data from all devices independently of their origin hub. +The controller MUST capture the counter value when receiving a :ref:`sample` +and use that value for the ``acqclk_cnt`` field of the corresponding :ref:`frame`. + +.. note:: The controller adds the acquisition counter when it receives the samples + and proceeds to create the associated frame. However, due to hub to controller + transmission delays, this time may have an offset from sample creation time. + To account for this, hubs contain a register indicating the measured + transmission delay. Users can use this value to more precisely synchronize + samples between hubs. + +.. todo:: update note admonition to links after the register map is updated .. _controller_params: @@ -32,7 +49,7 @@ Communication .. toctree:: :maxdepth: 1 - + channels/index addresses register_interface \ No newline at end of file