[PATCH v4 0/3] adis16475 driver documentation

[PATCH v4 0/3] adis16475 driver documentation

[Ramona Gradinariu]

Add documentation for:
- iio device buffers describing buffer attributes and how data is structured in
buffers using scan elements.
- adis16475 driver which describes the driver device files and shows how the
user may use the ABI for various scenarios (configuration, measurement, etc.).

This kind of documentation describes how the user can interract with the drivers
device files, showing the driver's particularities and we think all IIO drivers
need such a documentation and will benefit from it.
Having this documentation in the Linux Kernel will make it more accessible to
the user, seeing how it is in the same location as the code.
Analog Devices is prepared to add similar documentation for all new drivers (for
ADI components), and in time to also add documentation for existing drivers,
following the adis16475 documentation template.

Ramona Gradinariu (3):
  docs: iio: Refactor index.rst
  docs: iio: add documentation for device buffers
  docs: iio: add documentation for adis16475 driver

 Documentation/iio/adis16475.rst  | 406 +++++++++++++++++++++++++++++++
 Documentation/iio/iio_devbuf.rst | 125 ++++++++++
 Documentation/iio/index.rst      |   9 +-
 3 files changed, 539 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/iio/adis16475.rst
 create mode 100644 Documentation/iio/iio_devbuf.rst

--
2.34.1

[PATCH v4 1/3] docs: iio: Refactor index.rst

[Ramona Gradinariu]

Refactor index.rst such that it contains a section for generic
documentation and a section for Kernel Drivers documentation.

Signed-off-by: Ramona Gradinariu <ramona.gradinariu@analog.com>
---
changes in v4:
 - no changes
 Documentation/iio/index.rst | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index 1b7292c58cd0..db341b45397f 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -9,6 +9,11 @@ Industrial I/O

    iio_configfs

-   ep93xx_adc
+Industrial I/O Kernel Drivers
+=============================
+
+.. toctree::
+   :maxdepth: 1

    bno055
+   ep93xx_adc
--
2.34.1

[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@analog.com>
---
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

[PATCH v4 3/3] docs: iio: add documentation for adis16475 driver

[Ramona Gradinariu]

Add documentation for adis16475 driver which describes
the driver device files and shows how the user may use the
ABI for various scenarios (configuration, measurement, etc.).

Signed-off-by: Ramona Gradinariu <ramona.gradinariu@analog.com>
---
changes in v4:
 - fixed typos
 - added IIO interfacing tools section
 Documentation/iio/adis16475.rst | 406 ++++++++++++++++++++++++++++++++
 Documentation/iio/index.rst     |   1 +
 2 files changed, 407 insertions(+)
 create mode 100644 Documentation/iio/adis16475.rst

diff --git a/Documentation/iio/adis16475.rst b/Documentation/iio/adis16475.rst
new file mode 100644
index 000000000000..720995acbe24
--- /dev/null
+++ b/Documentation/iio/adis16475.rst
@@ -0,0 +1,406 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================
+ADIS16475 driver
+================
+
+This driver supports Analog Device's IMUs on SPI bus.
+
+1. Supported devices
+====================
+
+* `ADIS16465 <https://www.analog.com/ADIS16465>`_
+* `ADIS16467 <https://www.analog.com/ADIS16467>`_
+* `ADIS16470 <https://www.analog.com/ADIS16470>`_
+* `ADIS16475 <https://www.analog.com/ADIS16475>`_
+* `ADIS16477 <https://www.analog.com/ADIS16477>`_
+* `ADIS16500 <https://www.analog.com/ADIS16500>`_
+* `ADIS16505 <https://www.analog.com/ADIS16505>`_
+* `ADIS16507 <https://www.analog.com/ADIS16507>`_
+
+Each supported device is a precision, miniature microelectromechanical system
+(MEMS) inertial measurement unit (IMU) that includes a triaxial gyroscope and a
+triaxial accelerometer. Each inertial sensor in the IMU device combines with
+signal conditioning that optimizes dynamic performance. The factory calibration
+characterizes each sensor for sensitivity, bias, alignment, linear acceleration
+(gyroscope bias), and point of percussion (accelerometer location). As a result,
+each sensor has dynamic compensation formulas that provide accurate sensor
+measurements over a broad set of conditions.
+
+2. Device attributes
+====================
+
+Accelerometer, gyroscope measurements are always provided. Furthermore, the
+driver offers the capability to retrieve the delta angle and the delta velocity
+measurements computed by the device.
+
+The delta angle measurements represent a calculation of angular displacement
+between each sample update, while the delta velocity measurements represent a
+calculation of linear velocity change between each sample update.
+
+Finally, temperature data are provided which show a coarse measurement of
+the temperature inside of the IMU device. This data is most useful for
+monitoring relative changes in the thermal environment.
+
+The signal chain of each inertial sensor (accelerometers and gyroscopes)
+includes the application of unique correction formulas, which are derived from
+extensive characterization of bias, sensitivity, alignment, response to linear
+acceleration (gyroscopes), and point of percussion (accelerometer location)
+over a temperature range of −40°C to +85°C, for each ADIS device. These
+correction formulas are not accessible, but users do have the opportunity to
+adjust the bias for each sensor individually through the calibbias attribute.
+
+Each IIO device, has a device folder under /sys/bus/iio/devices/iio:deviceX,
+where X is the IIO index of the device. Under these folders reside a set of
+device files, depending on the characteristics and features of the hardware
+device in questions. These files are consistently generalized and documented in
+the IIO ABI documentation.
+
+The following tables show the adis16475 related device files, found in the
+specific device folder path /sys/bus/iio/devices/iio:deviceX.
+
++-------------------------------------------+----------------------------------------------------------+
+| 3-Axis Accelerometer related device files | Description                                              |
++-------------------------------------------+----------------------------------------------------------+
+| in_accel_scale                            | Scale for the accelerometer channels.                    |
++-------------------------------------------+----------------------------------------------------------+
+| in_accel_x_calibbias                      | Calibration offset for the X-axis accelerometer channel. |
++-------------------------------------------+----------------------------------------------------------+
+| in_accel_calibbias_x                      | x-axis acceleration offset correction                    |
++-------------------------------------------+----------------------------------------------------------+
+| in_accel_x_raw                            | Raw X-axis accelerometer channel value.                  |
++-------------------------------------------+----------------------------------------------------------+
+| in_accel_calibbias_y                      | y-axis acceleration offset correction                    |
++-------------------------------------------+----------------------------------------------------------+
+| in_accel_y_raw                            | Raw Y-axis accelerometer channel value.                  |
++-------------------------------------------+----------------------------------------------------------+
+| in_accel_z_calibbias                      | Calibration offset for the Z-axis accelerometer channel. |
++-------------------------------------------+----------------------------------------------------------+
+| in_accel_z_raw                            | Raw Z-axis accelerometer channel value.                  |
++-------------------------------------------+----------------------------------------------------------+
+| in_deltavelocity_scale                    | Scale for delta velocity channels.                       |
++-------------------------------------------+----------------------------------------------------------+
+| in_deltavelocity_x_raw                    | Raw X-axis delta velocity channel value.                 |
++-------------------------------------------+----------------------------------------------------------+
+| in_deltavelocity_y_raw                    | Raw Y-axis delta velocity channel value.                 |
++-------------------------------------------+----------------------------------------------------------+
+| in_deltavelocity_z_raw                    | Raw Z-axis delta velocity channel value.                 |
++-------------------------------------------+----------------------------------------------------------+
+
++---------------------------------------+------------------------------------------------------+
+| 3-Axis Gyroscope related device files | Description                                          |
++---------------------------------------+------------------------------------------------------+
+| in_anglvel_scale                      | Scale for the gyroscope channels.                    |
++---------------------------------------+------------------------------------------------------+
+| in_anglvel_x_calibbias                | Calibration offset for the X-axis gyroscope channel. |
++---------------------------------------+------------------------------------------------------+
+| in_anglvel_calibbias_x                | x-axis gyroscope offset correction                   |
++---------------------------------------+------------------------------------------------------+
+| in_anglvel_x_raw                      | Raw X-axis gyroscope channel value.                  |
++---------------------------------------+------------------------------------------------------+
+| in_anglvel_calibbias_y                | y-axis gyroscope offset correction                   |
++---------------------------------------+------------------------------------------------------+
+| in_anglvel_y_raw                      | Raw Y-axis gyroscope channel value.                  |
++---------------------------------------+------------------------------------------------------+
+| in_anglvel_z_calibbias                | Calibration offset for the Z-axis gyroscope channel. |
++---------------------------------------+------------------------------------------------------+
+| in_anglvel_z_raw                      | Raw Z-axis gyroscope channel value.                  |
++---------------------------------------+------------------------------------------------------+
+| in_deltaangl_scale                    | Scale for delta angle channels.                      |
++---------------------------------------+------------------------------------------------------+
+| in_deltaangl_x_raw                    | Raw X-axis delta angle channel value.                |
++---------------------------------------+------------------------------------------------------+
+| in_deltaangl_y_raw                    | Raw Y-axis delta angle channel value.                |
++---------------------------------------+------------------------------------------------------+
+| in_deltaangl_z_raw                    | Raw Z-axis delta angle channel value.                |
++---------------------------------------+------------------------------------------------------+
+
++----------------------------------+-------------------------------------------+
+| Temperature sensor related files | Description                               |
++----------------------------------+-------------------------------------------+
+| in_temp0_raw                     | Raw temperature channel value.            |
++----------------------------------+-------------------------------------------+
+| in_temp0_scale                   | Scale for the temperature sensor channel. |
++----------------------------------+-------------------------------------------+
+
++-------------------------------+---------------------------------------------------------+
+| Miscellaneous device files    | Description                                             |
++-------------------------------+---------------------------------------------------------+
+| name                          | Name of the IIO device.                                 |
++-------------------------------+---------------------------------------------------------+
+| sampling_frequency            | Currently selected sample rate.                         |
++-------------------------------+---------------------------------------------------------+
+| filter_low_pass_3db_frequency | Bandwidth for the accelerometer and gyroscope channels. |
++-------------------------------+---------------------------------------------------------+
+
+The following table shows the adis16475 related device debug files, found in the
+specific device debug folder path /sys/kernel/debug/iio/iio:deviceX.
+
++----------------------+-------------------------------------------------------------------------+
+| Debugfs device files | Description                                                             |
++----------------------+-------------------------------------------------------------------------+
+| serial_number        | The serial number of the chip in hexadecimal format.                    |
++----------------------+-------------------------------------------------------------------------+
+| product_id           | Chip specific product id (e.g. 16475, 16500, 16505, etc.).              |
++----------------------+-------------------------------------------------------------------------+
+| flash_count          | The number of flash writes performed on the device.                     |
++----------------------+-------------------------------------------------------------------------+
+| firmware_revision    | String containing the firmware revision in the following format ##.##.  |
++----------------------+-------------------------------------------------------------------------+
+| firmware_date        | String containing the firmware date in the following format mm-dd-yyyy. |
++----------------------+-------------------------------------------------------------------------+
+
+Channels processed values
+-------------------------
+
+A channel value can be read from its _raw attribute. The value returned is the
+raw value as reported by the devices. To get the processed value of the channel,
+apply the following formula:
+
+.. code-block:: bash
+
+        processed value = (_raw + _offset) * _scale
+
+Where _offset and _scale are device attributes. If no _offset attribute is
+present, simply assume its value is 0.
+
+The adis16475 driver offers data for 5 types of channels, the table below shows
+the measurement units for the processed value, which are defined by the IIO
+framework:
+
++-------------------------------------+---------------------------+
+| Channel type                        | Measurement unit          |
++-------------------------------------+---------------------------+
+| Acceleration on X, Y, and Z axis    | Meters per Second squared |
++-------------------------------------+---------------------------+
+| Angular velocity on X, Y and Z axis | Radians per second        |
++-------------------------------------+---------------------------+
+| Delta velocity on X. Y, and Z axis  | Meters per Second         |
++-------------------------------------+---------------------------+
+| Delta angle on X, Y, and Z axis     | Radians                   |
++-------------------------------------+---------------------------+
+| Temperature                         | Millidegrees Celsius      |
++-------------------------------------+---------------------------+
+
+Usage examples
+--------------
+
+Show device name:
+
+.. code-block:: bash
+
+	root:/sys/bus/iio/devices/iio:device0> cat name
+        adis16505-2
+
+Show accelerometer channels value:
+
+.. code-block:: bash
+
+        root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_raw
+        -275924
+        root:/sys/bus/iio/devices/iio:device0> cat in_accel_y_raw
+        -30142222
+        root:/sys/bus/iio/devices/iio:device0> cat in_accel_z_raw
+        261265769
+        root:/sys/bus/iio/devices/iio:device0> cat in_accel_scale
+        0.000000037
+
+- X-axis acceleration = in_accel_x_raw * in_accel_scale = −0.010209188 m/s^2
+- Y-axis acceleration = in_accel_y_raw * in_accel_scale = −1.115262214 m/s^2
+- Z-axis acceleration = in_accel_z_raw * in_accel_scale = 9.666833453 m/s^2
+
+Show gyroscope channels value:
+
+.. code-block:: bash
+
+        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_x_raw
+        -3324626
+        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_raw
+        1336980
+        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_z_raw
+        -602983
+        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_scale
+        0.000000006
+
+- X-axis angular velocity = in_anglvel_x_raw * in_anglvel_scale = −0.019947756 rad/s
+- Y-axis angular velocity = in_anglvel_y_raw * in_anglvel_scale = 0.00802188 rad/s
+- Z-axis angular velocity = in_anglvel_z_raw * in_anglvel_scale = −0.003617898 rad/s
+
+Set calibration offset for accelerometer channels:
+
+.. code-block:: bash
+
+        root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
+        0
+
+        root:/sys/bus/iio/devices/iio:device0> echo 5000 > in_accel_x_calibbias
+        root:/sys/bus/iio/devices/iio:device0> cat in_accel_x_calibbias
+        5000
+
+Set calibration offset for gyroscope channels:
+
+.. code-block:: bash
+
+        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
+        0
+
+        root:/sys/bus/iio/devices/iio:device0> echo -5000 > in_anglvel_y_calibbias
+        root:/sys/bus/iio/devices/iio:device0> cat in_anglvel_y_calibbias
+        -5000
+
+Set sampling frequency:
+
+.. code-block:: bash
+
+	root:/sys/bus/iio/devices/iio:device0> cat sampling_frequency
+        2000.000000
+
+        root:/sys/bus/iio/devices/iio:device0> echo 1000 > sampling_frequency
+        1000.000000
+
+Set bandwidth for accelerometer and gyroscope:
+
+.. code-block:: bash
+
+        root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_frequency
+        720
+
+        root:/sys/bus/iio/devices/iio:device0> echo 360 > filter_low_pass_3db_frequency
+        root:/sys/bus/iio/devices/iio:device0> cat filter_low_pass_3db_frequency
+        360
+
+Show serial number:
+
+.. code-block:: bash
+
+        root:/sys/kernel/debug/iio/iio:device0> cat serial_number
+        0x04f9
+
+Show product id:
+
+.. code-block:: bash
+
+        root:/sys/kernel/debug/iio/iio:device0> cat product_id
+        16505
+
+Show flash count:
+
+.. code-block:: bash
+
+        root:/sys/kernel/debug/iio/iio:device0> cat flash_count
+        150
+
+Show firmware revision:
+
+.. code-block:: bash
+
+        root:/sys/kernel/debug/iio/iio:device0> cat firmware_revision
+        1.6
+
+Show firmware date:
+
+.. code-block:: bash
+
+        root:/sys/kernel/debug/iio/iio:device0> cat firmware_date
+        06-27-2019
+
+3. Device buffers
+=================
+
+This driver supports IIO buffers.
+
+All devices support retrieving the raw acceleration, gyroscope and temperature
+measurements using buffers.
+
+The following device families also support retrieving the delta velocity, delta
+angle and temperature measurements using buffers:
+ - ADIS16477
+ - ADIS16500
+ - ADIS16505
+ - ADIS16507
+
+However, when retrieving acceleration or gyroscope data using buffers, delta
+readings will not be available and vice versa.
+
+Usage examples
+--------------
+
+Set device trigger in current_trigger, if not already set:
+
+.. code-block:: bash
+
+        root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
+
+        root:/sys/bus/iio/devices/iio:device0> echo adis16505-2-dev0 > trigger/current_trigger
+        root:/sys/bus/iio/devices/iio:device0> cat trigger/current_trigger
+        adis16505-2-dev0
+
+Select channels for buffer read:
+
+.. code-block:: bash
+
+        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_x_en
+        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_y_en
+        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_deltavelocity_z_en
+        root:/sys/bus/iio/devices/iio:device0> echo 1 > scan_elements/in_temp0_en
+
+Set the number of samples to be stored in the buffer:
+
+.. code-block:: bash
+
+        root:/sys/bus/iio/devices/iio:device0> echo 10 > buffer/length
+
+Enable buffer readings:
+
+.. code-block:: bash
+
+        root:/sys/bus/iio/devices/iio:device0> echo 1 > buffer/enable
+
+Obtain buffered data:
+
+.. code-block:: bash
+
+        root:/sys/bus/iio/devices/iio:device0> hexdump -C /dev/iio\:device0
+        ...
+        00001680  01 1f 00 00 ff ff fe ef  00 00 47 bf 00 03 35 55  |..........G...5U|
+        00001690  01 1f 00 00 ff ff ff d9  00 00 46 f1 00 03 35 35  |..........F...55|
+        000016a0  01 1f 00 00 ff ff fe fc  00 00 46 cb 00 03 35 7b  |..........F...5{|
+        000016b0  01 1f 00 00 ff ff fe 41  00 00 47 0d 00 03 35 8b  |.......A..G...5.|
+        000016c0  01 1f 00 00 ff ff fe 37  00 00 46 b4 00 03 35 90  |.......7..F...5.|
+        000016d0  01 1d 00 00 ff ff fe 5a  00 00 45 d7 00 03 36 08  |.......Z..E...6.|
+        000016e0  01 1b 00 00 ff ff fe fb  00 00 45 e7 00 03 36 60  |..........E...6`|
+        000016f0  01 1a 00 00 ff ff ff 17  00 00 46 bc 00 03 36 de  |..........F...6.|
+        00001700  01 1a 00 00 ff ff fe 59  00 00 46 d7 00 03 37 b8  |.......Y..F...7.|
+        00001710  01 1a 00 00 ff ff fe ae  00 00 46 95 00 03 37 ba  |..........F...7.|
+        00001720  01 1a 00 00 ff ff fe c5  00 00 46 63 00 03 37 9f  |..........Fc..7.|
+        00001730  01 1a 00 00 ff ff fe 55  00 00 46 89 00 03 37 c1  |.......U..F...7.|
+        00001740  01 1a 00 00 ff ff fe 31  00 00 46 aa 00 03 37 f7  |.......1..F...7.|
+        ...
+
+See Documentation/iio/iio_devbuf.rst for more information about how buffered
+data is structured.
+
+4. IIO Interfacing Tools
+========================
+
+Linux Kernel Tools
+------------------
+
+Linux Kernel provides some user space tools that can be used to retrieve data
+from IIO sysfs:
+
+* lsiio: example application that provides a list of IIO devices and triggers
+* iio_event_monitor: example application that reads events from an IIO device
+  and prints them
+* iio_generic_buffer: example application that reads data from buffer
+* iio_utils: set of APIs, typically used to access sysfs files.
+
+LibIIO
+------
+
+LibIIO is a C/C++ library that provides generic access to IIO devices. The
+library abstracts the low-level details of the hardware, and provides a simple
+yet complete programming interface that can be used for advanced projects.
+
+For more information about LibIIO, please see:
+https://github.com/analogdevicesinc/libiio
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index 206a0aff5ca1..30b09eefe75e 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -16,5 +16,6 @@ Industrial I/O Kernel Drivers
 .. toctree::
    :maxdepth: 1

+   adis16475
    bno055
    ep93xx_adc
--
2.34.1

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

[David Lechner]

On Tue, Feb 13, 2024 at 2:19 AM 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.

Really nice to see this being added to the docs.

>
> Signed-off-by: Ramona Gradinariu <ramona.gradinariu@analog.com>
> ---
> 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.

It could be nice to use inline code format style (double-backtick,
e.g. ``/dev/iio:deviceX``) on paths like this throughout the document.

> +
> +Devices with buffer support feature an additional sub-folder in the
> +/sys/bus/iio/devices/deviceX/ folder hierarchy, called bufferY, where Y defaults

Should this be `iio:deviceX` instead of `deviceX` to match the sysfs docs?

> +to 0, for devices with a single buffer.

Is /sys/bus/iio/devices/deviceX/buffer (without the Y) for backwards
compatibility?

> +
> +2. Buffer attributes
> +====================
> +
> +An IIO buffer has an associated attributes directory under
> +/sys/bus/iio/iio:deviceX/bufferY/. The attributes are described below.
> +
> +Length
> +------

Could be nice to give the actual attribute name ``length`` here to
avoid possible case-sensitivity confusion with the section header.
Same applies to other attributes.

> +
> +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.

Could be useful here to mention that writing a non-zero value here to
enable the buffer may result in an error, such as EINVAL, e.g. if an
invalid configuration was selected, like choosing a combination of
scan elements that don't match one of the valid scan masks.

> +
> +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

Maybe say "data" instead of "reading" here since it could be writing
instead for DACs.

> +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/

Giving the directory again seems redundant here.

> +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

Isn't 0 a valid scan index? So non-negative? Or unsigned?

> +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.
> +

It would also be nice to get an example on the binary layout for
something that has multiple channels enabled. In particular with the
data alignment, e.g. when you have a 16-bit word followed by a 64-bit
word.


> +**_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

Doesn't look like this should use "bash" styling.

> +
> +          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.

Is it always assumed that scan data is `raw` and needs to be
multiplied by `scale` for that channel to convert it to SI (or IIO
standard) units?

> +
> +Please see Documentation/ABI/testing/sysfs-bus-iio for a complete description of
> +the attributes.

Is it also worth mentioning
``Documentation/ABI/testing/sysfs-bus-iio-dma-buffer`` here?

> 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
>
>

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

[Randy Dunlap]

On 2/13/24 00:17, Ramona Gradinariu 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 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

folder or directory?

> +/sys/bus/iio/devices/deviceX/ folder hierarchy, called bufferY, where Y defaults

folder or directory?

> +to 0, for devices with a single buffer.
> +
> +2. Buffer attributes
> +====================
> +
> +An IIO buffer has an associated attributes directory under

directory or folder?

Just be consistent, please.

> +/sys/bus/iio/iio:deviceX/bufferY/. The attributes are described below.
> +

What are the corresponding attribute names?

> +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.

           watermark
> +
> +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

                          than the

> +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

That line gives me -ENOPARSE. Can it be improved?

> +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

      non-zero,

> +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

                        userspace
as above.

> +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.

         no comma  ^

> +- **bits**, is the number of valid data bits.

    no comma ^

> +- **storagebits**, is the number of bits (after padding) that it occupies in the

      no comma      ^

> +  buffer.
> +- **repeat**, specifies the number of bits/storagebits repetitions. When the

  no comma     ^

> +  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

  no comma    ^

> +  masking out unused bits.
> +
> +For example, a driver for a 3-axis accelerometer with 12 bit resolution where

                                                         12-bit

> +data is stored in two 8-bits registers as follows:

                         8-bit            is 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

     userspace
for consistency.
                                                                             as two-

> +byte little endian signed data, that needs a 4 bits right shift before masking

        little-endian

> +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
> 
> 

-- 
#Randy

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

[Jonathan Cameron]

A few follow up comments on your David's review
Anything I deleted didn't need a comment as all made sense to me!

> 
> > +to 0, for devices with a single buffer.  
> 
> Is /sys/bus/iio/devices/deviceX/buffer (without the Y) for backwards
> compatibility?

Yes. For these docs I'd not mention it. New software should be aware of multiple
buffers being possible and not use it. Same is true of the scan_elements directory.
If we really want to mention it, say buffer/ and scan_elements are for backwards
compatibility and should not be used in new userspace software.

They aren't going anywhere, but better people start from a multibuffer world!

> 
> > +
> > +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.  
> 
> Could be useful here to mention that writing a non-zero value here to
> enable the buffer may result in an error, such as EINVAL, e.g. if an
> invalid configuration was selected, like choosing a combination of
> scan elements that don't match one of the valid scan masks.

Be careful to not refer to matching.  Could be a subset.  I'd refer to
"an unsupported combination of channels" or something like that.


> > +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  
> 
> Isn't 0 a valid scan index? So non-negative? Or unsigned?

Yes - unsigned would be my preference.

> 
> > +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.
> > +  
> 
> It would also be nice to get an example on the binary layout for
> something that has multiple channels enabled. In particular with the
> data alignment, e.g. when you have a 16-bit word followed by a 64-bit
> word.
> 

Agreed - the padding is sometimes not what people expect.

> 
> > +**_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  
> 
> Doesn't look like this should use "bash" styling.
> 
> > +
> > +          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.  
> 
> Is it always assumed that scan data is `raw` and needs to be
> multiplied by `scale` for that channel to convert it to SI (or IIO
> standard) units?

Definitely by far the most common case but there are a few exceptions where
there isn't a _raw attribute but only an _input one where the assumption is
processed data.  Tricky to mention that here without adding complexity.
Maybe just add some weasel words to hint there are corners not covered by
this doc.

> 
> > +
> > +Please see Documentation/ABI/testing/sysfs-bus-iio for a complete description of
> > +the attributes.  
> 
> Is it also worth mentioning
> ``Documentation/ABI/testing/sysfs-bus-iio-dma-buffer`` here?

I'd not do that until we have a section for these docs on dma buffers which
are different in a bunch of ways. Would just be a potential source of
confusion.

Jonathan