Merge pull request #90 from open-ephys/issue-76

Clarify Write channel responsibilities

source/hw-spec/controller/channels/read_channel.rst

@@ -7,7 +7,7 @@ Read Channel
 -  **Channel type** : Stream
 -  **Direction** : Read
 
-The read channel provides high bandwidth communication from the controller to
+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`.

source/hw-spec/controller/channels/write_channel.rst

@@ -10,16 +10,37 @@ Write Channel
 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.
+Data is sent as a sequence of :ref:`frame` with their ``Common_Timestamp`` field
+set to 0. Multiple :ref:`device samples <dev-sample>` 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.
+
+A compliant implementation of this channel requires the following:
+
+- The controller MUST accept all frames sent by the host, at any rate that does
+  not exceed the maximal channel bandwidth, which will be
+  implementation-defined.
+
+- The controller MUST send all frames received to the destination devices in the
+  same order it receives frames from the computer
+
+- Devices that accept data from the write channel MAY buffer it. A device's
+  :ref:`dev-datasheet` MUST specify if data is buffered and if there is any
+  possibility of dropping frames (e.g: receiving a frame while one is being
+  processed)
+
+.. _write-chan-sync:
+
+- Devices that accept data from the write channel MAY inform the host about
+  their internal state so a host application can adjust the production rate of
+  write frames accordingly. If used, this mechanism MUST use existing channels
+  (e.g. Register or Read channels), MUST NOT directly affect the operation of
+  the Write channel and MUST be described on the :ref:`dev-datasheet`.
+
+In summary, the Write Channel's sole responsibility is passing frames to devices.
+The Write channel is not required to provide any auxiliary signals about its
+internal state, specific frame delivery timestamps or any other operational
+details.
 
 .. _write-word-alignment:
 

source/hw-spec/devices/datasheet.rst

@@ -77,4 +77,14 @@ Write Frame Format
 If the device accepts :ref:`samples <dev-sample>`, a `bitfield
 <https://en.wikipedia.org/wiki/Bit_field>`__ diagram describing the frame
 structure is required. Bits can be grouped into words as is convenient. If no
-frames are accepted, then a statement of such is required.
+frames are accepted, then a statement of such is required.
+
+In addition to a description of the frame format, this section MUST specify if
+write frames are consumed immediately or buffered. If write frames are buffered,
+this section MUST specify if there is any possibility of dropping frames (e.g:
+receiving a frame while one is being processed).
+
+A device MAY implement a :ref:`mechanism <write-chan-sync>` to inform the host
+about its internal state, for instance to synchronize the production of data on
+the host synchronize with the device's consumption of data. If implemented, this
+mechanism should be detailed in this section.

source/hw-spec/devices/sample.rst

@@ -4,33 +4,33 @@ Device Sample Format
 =====================
 
 Data passed over the read or write streams are transmitted in unit packets,
-or "samples". 
+or "samples".
 
 Read Samples
 -------------
-These are the samples produced by the devices and sent through the 
-:ref:`read stream <com-channels>` to the controller. 
+These are the samples produced by the devices and sent through the
+:ref:`read stream <com-channels>` to the controller.
 Read samples MUST have the following format:
 
 ::
 
     uint64    hubclk_cnt
     var       payload
 
-- ``hubclk_cnt``: Hub Clock Counter. This is the common counter for all devices in 
-  a :ref:`Hub <hub>`, indicating the time of sample capture. 
-- ``payload``: :ref:`Device-specific<dev-datasheet-read-format>` data. This data MUST be 
+- ``hubclk_cnt``: Hub Clock Counter. This is the common counter for all devices in
+  a :ref:`Hub <hub>`, indicating the time of sample capture.
+- ``payload``: :ref:`Device-specific<dev-datasheet-read-format>` data. This data MUST be
   :ref:`Read Sample Size <dev-desc>` - 8 bytes long.
 
 Write samples
 -------------
 These are the samples generated by the host and sent to the devices
-trough the :ref:`write stream <com-channels>`. 
+trough the :ref:`write stream <com-channels>`.
 Write samples MUST have the following format.
 
 ::
 
   var payload
 
-- ``payload``: :ref:`Device-specific<dev-datasheet-write-format>` data. This data MUST be 
-  :ref:`Write Sample Size <dev-desc>` bytes long. 
+- ``payload``: :ref:`Device-specific<dev-datasheet-write-format>` data. This data MUST be
+  :ref:`Write Sample Size <dev-desc>` bytes long.