[PATCH v4 2/3] docs: iio: add documentation for device buffers

[Ramona Gradinariu]

Add documentation for IIO device buffers describing buffer
attributes and how data is structured in buffers using
scan elements.

Signed-off-by: Ramona Gradinariu <ramona.gradinariu@xxxxxxxxxx>
---
changes in v4:
 - documented multiple buffer support
 - reworked scan elements section
 - added reference to ABI docs
 Documentation/iio/iio_devbuf.rst | 125 +++++++++++++++++++++++++++++++
 Documentation/iio/index.rst      |   1 +
 2 files changed, 126 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..e99143efb4d7
--- /dev/null
+++ b/Documentation/iio/iio_devbuf.rst
@@ -0,0 +1,125 @@
+.. 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.
+
+Devices with buffer support feature an additional sub-folder in the
+/sys/bus/iio/devices/deviceX/ folder hierarchy, called bufferY, where Y defaults
+to 0, for devices with a single buffer.
+
+2. Buffer attributes
+====================
+
+An IIO buffer has an associated attributes directory under
+/sys/bus/iio/iio:deviceX/bufferY/. The attributes are described below.
+
+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.
+
+Scan elements
+-------------
+
+The meta information associated with a channel reading placed in a buffer is
+called a scan element. The scan elements are configurable per buffer, thus they
+are exposed to userspace applications via the /sys/bus/iio/iio:deviceX/bufferY/
+directory. The scan elements attributes are presented below.
+
+**_en**
+
+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/buffer0/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.
+
+Please see Documentation/ABI/testing/sysfs-bus-iio for a complete description of
+the attributes.
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