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

[Jonathan Cameron <jic23@kernel.org>]

On Thu, 8 Feb 2024 12:01:25 +0200
Ramona Gradinariu <ramona.gradinariu@analog.com> 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 <ramona.gradinariu@analog.com>
> ---
> 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
>