Clarify high-bandwidth stream data alignment requirements

[jonnew]

This proposed specification enhancement stems from open-ephys/liboni#16. After an internal discussion, we are proposing the following enhancements to the spec to balance performance, implementability, and separation of API responsibilities from hardware.

• Currently, high-bandwidth read and write streams are specified to be 32-bits wide. This limits the future utility of the hardware spec. Really, any byte multiple bus width should be supported.
• Data alignment should ultimately be the responsibility of the hardware. The API should be able to use information about read and write sizes provided in the device table to read data from the hardware, or some buffer gathered from hardware, without having to pad its reads to fall on some boundary (e.g. the 32-bit boundary that is currently required).
• The following verbiage is a starting point for the specification changes to make this happen:

The hardware must:

1. Have the ability to inform the API what the width its will use will be. We the space below is a good place to discuss how this should occur and what it will mean to the spec
2. Ensure that device read and write sizes, as reported in the device table and without modification by the API, fall on natural boundaries of the width specified in (1). This ensures the API does not have to do padding on top of the reported read and write sizes in order to prevent data corruption. A corollary of this requirement is that, since devices can report data read and write sizes at byte resolution, the read and write sizes that appear on a device datasheet should not be considered lower bounds that can be rounded to fit the read and write stream bus width. However, this will be transparently presented in the device table which will contain the real read and write sizes of each device, including the padding required to meet the data boundary requirements.

The API must:

1. Use the read and write boundary information reported by the hardware to modify requested block read and write sizes to fall on these boundaries. Again, this modification will be made transparent as the real block read and write sizes will be reported via oni_get_opt().

[jonnew]

In fact, these requirements can be reduced to a simplified API, with no knowledge of the hardware's internal data boundaries by implementing the following rules. Note that these suggestions supersede the above discussion and take a different path to the same end:

• The API operates on bytes. Its not the API's responsibility to align data to a particular boundary.
  • oni_fifo_dat_t and related must not ever be used in the API
• Hardware should inform the driver translator of read and write boundaries
  • Useful for reading efficiency
  • Required for padding write data to interact with hardware by the driver or driver translator (not API)
• The device table may presented larger values for read size than is presented in a device datasheet
  • Read sizes in the device table will be aligned to hardware data width
  • Excess data over the value presented in the device datasheet can be safely ignored
• The device table is required to use the same size for write frames as is presented in a device datasheet
  • Multi frame data can be written in a block wise fashion with no padding
  • Alignment to hardware data width is the responsibility of the driver translator