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,32 +10,36 @@ 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.
+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.
 
-In regard of the data frames handled by this channel:
+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 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
+- The controller MUST send all frames received to the destination devices in the
+  same order it receives frames from the computer
 
-- The devices accepting data from the write channel MAY buffer it. The devices 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)
+- 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)
 
-- The devices accepting data from the write channel MAY inform the host about their internal state
-  so the end software 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 device datasheet.
+- The devices accepting 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.
 
-- In summary, the Write Channel 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:
 
 Write Word Alignment

source/hw-spec/devices/datasheet.rst

@@ -77,4 +77,15 @@ 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 inform the host about its internal state so software on the host
+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 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.