.. _frame:

Data Frames
============

Data transmission from the :ref:`read channel<data-rd-chan>` and from the
:ref:`write channel<data-wr-chan>` is packed in frames. Each frame is a
timestamped `type-length-value-encoded
<https://en.wikipedia.org/wiki/Type%E2%80%93length%E2%80%93value>`__ structure
that contains data corresponding to a single device :ref:`sample <dev-sample>`.
The frame format is:

::

    uint32  dev_addr
    uint64  acqclk_cnt
    uint32  sample_sz
    var     sample

Where

- ``dev_addr``: Device Address. The address of the device producing the data, as
  featured on the :ref:`device table <dev-table>`.
- ``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_sz``: Sample Size. The full size of the sample, and must be equal to
  the ``rd_samp_size`` field of the :ref:`device descriptor <dev-desc>` 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 <dev-sample>` section.

  While a read frame must always contain a single sample as generated by the devices,
  write frames can contain multiple samples targeted to the same device.