Add documentation for IIO device buffers describing buffer
attributes and how data is structured in buffers using
scan elements.
Signed-off-by: Ramona Gradinariu <[email protected]>
---
changes in v3:
- new patch
Documentation/iio/iio_devbuf.rst | 121 +++++++++++++++++++++++++++++++
Documentation/iio/index.rst | 1 +
2 files changed, 122 insertions(+)
create mode 100644 Documentation/iio/iio_devbuf.rst
diff --git a/Documentation/iio/iio_devbuf.rst b/Documentation/iio/iio_devbuf.rst
new file mode 100644
index 000000000000..0563b65316cb
--- /dev/null
+++ b/Documentation/iio/iio_devbuf.rst
@@ -0,0 +1,121 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============================
+Industrial IIO device buffers
+=============================
+
+1. Overview
+===========
+
+The Industrial I/O core offers a way for continuous data capture based on a
+trigger source. Multiple data channels can be read at once from
+/dev/iio:deviceX character device node, thus reducing the CPU load.
+
+2. Buffer attributes
+====================
+
+An IIO buffer has an associated attributes directory under
+/sys/bus/iio/iio:deviceX/buffer/. Here are some of the existing attributes:
+
+Length
+------
+
+Read / Write attribute which states the total number of data samples (capacity)
+that can be stored by the buffer.
+
+Enable
+------
+
+Read / Write attribute which starts / stops the buffer capture. This file should
+be written last, after length and selection of scan elements.
+
+Watermark
+---------
+
+Read / Write positive integer attribute specifying the maximum number of scan
+elements to wait for.
+
+Poll will block until the watermark is reached.
+
+Blocking read will wait until the minimum between the requested read amount or
+the low water mark is available.
+
+Non-blocking read will retrieve the available samples from the buffer even if
+there are less samples then watermark level. This allows the application to
+block on poll with a timeout and read the available samples after the timeout
+expires and thus have a maximum delay guarantee.
+
+Data available
+--------------
+
+Read-only attribute indicating the bytes of data available in the buffer. In the
+case of an output buffer, this indicates the amount of empty space available to
+write data to. In the case of an input buffer, this indicates the amount of data
+available for reading.
+
+3. Scan elements
+================
+
+The meta information associated with a channel reading placed in a buffer is
+called a scan element. The important bits configuring scan elements are exposed
+to userspace applications via the /sys/bus/iio/iio:deviceX/scan_elements/
+directory. This directory contains attributes of the following form:
+
+Enable
+------
+
+Read/ Write attribute used for enabling a channel. If and only if its value
+is non zero, then a triggered capture will contain data samples for this
+channel.
+
+Index
+-----
+
+Read-only positive integer attribute specifying the position of the channel in
+the buffer. Note these are not dependent on what is enabled and may not be
+contiguous. Thus for user-space to establish the full layout these must be used
+in conjunction with all _en attributes to establish which channels are present,
+and the relevant _type attributes to establish the data storage format.
+
+Type
+----
+
+Read-only attribute containing the description of the scan element data storage
+within the buffer and hence the form in which it is read from user space. Format
+is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift], where:
+
+- **be** or **le** specifies big or little endian.
+- **s** or **u**, specifies if signed (2's complement) or unsigned.
+- **bits**, is the number of valid data bits.
+- **storagebits**, is the number of bits (after padding) that it occupies in the
+ buffer.
+- **repeat**, specifies the number of bits/storagebits repetitions. When the
+ repeat element is 0 or 1, then the repeat value is omitted.
+- **shift**, if specified, is the shift that needs to be applied prior to
+ masking out unused bits.
+
+For example, a driver for a 3-axis accelerometer with 12 bit resolution where
+data is stored in two 8-bits registers as follows:
+
+.. code-block:: bash
+
+ 7 6 5 4 3 2 1 0
+ +---+---+---+---+---+---+---+---+
+ |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
+ +---+---+---+---+---+---+---+---+
+
+ 7 6 5 4 3 2 1 0
+ +---+---+---+---+---+---+---+---+
+ |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
+ +---+---+---+---+---+---+---+---+
+
+will have the following scan element type for each axis:
+
+.. code-block:: bash
+
+ $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type
+ le:s12/16>>4
+
+A user space application will interpret data samples read from the buffer as two
+byte little endian signed data, that needs a 4 bits right shift before masking
+out the 12 valid bits of data.
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index db341b45397f..206a0aff5ca1 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -8,6 +8,7 @@ Industrial I/O
:maxdepth: 1
iio_configfs
+ iio_devbuf
Industrial I/O Kernel Drivers
=============================
--
2.34.1
On Thu, 8 Feb 2024 12:01:25 +0200
Ramona Gradinariu <[email protected]> wrote:
> Add documentation for IIO device buffers describing buffer
> attributes and how data is structured in buffers using
> scan elements.
>
> Signed-off-by: Ramona Gradinariu <[email protected]>
> ---
> changes in v3:
> - new patch
> Documentation/iio/iio_devbuf.rst | 121 +++++++++++++++++++++++++++++++
> Documentation/iio/index.rst | 1 +
> 2 files changed, 122 insertions(+)
> create mode 100644 Documentation/iio/iio_devbuf.rst
>
> diff --git a/Documentation/iio/iio_devbuf.rst b/Documentation/iio/iio_devbuf.rst
> new file mode 100644
> index 000000000000..0563b65316cb
> --- /dev/null
> +++ b/Documentation/iio/iio_devbuf.rst
> @@ -0,0 +1,121 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=============================
> +Industrial IIO device buffers
> +=============================
> +
> +1. Overview
> +===========
> +
> +The Industrial I/O core offers a way for continuous data capture based on a
> +trigger source. Multiple data channels can be read at once from
> +/dev/iio:deviceX character device node, thus reducing the CPU load.
> +
> +2. Buffer attributes
> +====================
> +
> +An IIO buffer has an associated attributes directory under
> +/sys/bus/iio/iio:deviceX/buffer/. Here are some of the existing attributes:
Given this is new documentation, can we make it compliant from the start with
multiple buffer support? bufferY
> +3. Scan elements
> +================
> +
> +The meta information associated with a channel reading placed in a buffer is
> +called a scan element. The important bits configuring scan elements are exposed
> +to userspace applications via the /sys/bus/iio/iio:deviceX/scan_elements/
Reference the bufferY directory not scan_elements for this as well.
..
> +
> +A user space application will interpret data samples read from the buffer as two
> +byte little endian signed data, that needs a 4 bits right shift before masking
> +out the 12 valid bits of data.
I can't remember how you do it, but if possible can we have a cross reference to the
autogenerated ABI docs. I want those to remain the 'official' definition of ABI
with this (excellent btw!) document being the user friendly cut down version.
Thanks!
Jonathan
> diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
> index db341b45397f..206a0aff5ca1 100644
> --- a/Documentation/iio/index.rst
> +++ b/Documentation/iio/index.rst
> @@ -8,6 +8,7 @@ Industrial I/O
> :maxdepth: 1
>
> iio_configfs
> + iio_devbuf
>
> Industrial I/O Kernel Drivers
> =============================
> --
> 2.34.1
>