From d4a3505431ddab27a1edad0c77be5cbf1f09a36e Mon Sep 17 00:00:00 2001 From: Aaron Cuevas Lopez Date: Thu, 21 Nov 2024 05:54:12 +0100 Subject: [PATCH 1/3] Update data frame format to C-style --- .../controller/channels/data_frames.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) 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, From 1205c607958382b3dacee4cf91bb09ea64ad6c07 Mon Sep 17 00:00:00 2001 From: Aaron Cuevas Lopez Date: Thu, 21 Nov 2024 05:54:32 +0100 Subject: [PATCH 2/3] Clarify acquisition counter definition --- source/hw-spec/controller/index.rst | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/source/hw-spec/controller/index.rst b/source/hw-spec/controller/index.rst index d6413c6..f713569 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 :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, the 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 From 09f0b1c90573c658fa2198273c4b4dfdfc2d9651 Mon Sep 17 00:00:00 2001 From: Aaron Cuevas Lopez Date: Thu, 21 Nov 2024 17:32:06 +0100 Subject: [PATCH 3/3] Address review comments --- source/hw-spec/controller/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/hw-spec/controller/index.rst b/source/hw-spec/controller/index.rst index f713569..c364e56 100644 --- a/source/hw-spec/controller/index.rst +++ b/source/hw-spec/controller/index.rst @@ -8,18 +8,18 @@ to all devices, independently of their physical location. .. _acq_clk: -Acquisition counter +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 :ref:`frame`. +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, the hubs contain a register indicating the measured + 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. @@ -49,7 +49,7 @@ Communication .. toctree:: :maxdepth: 1 - + channels/index addresses register_interface \ No newline at end of file