[thirdparty/kernel/stable.git] / Documentation / iio / iio_devbuf.rst

.. 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-directory in the
``/sys/bus/iio/devices/iio:deviceX/`` directory 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. Writing a non-zero
value may result in an error, such as EINVAL, if, for example, an unsupported
combination of channels is given.

``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 watermark is available.

Non-blocking read will retrieve the available samples from the buffer even if
there are less samples than the 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 data placed in a buffer is called
a scan element. 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 unsigned 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 userspace 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 userspace. 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-bit registers is as follows::

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

It is also worth mentioning that the data in the buffer will be naturally
aligned, so the userspace application has to handle the buffers accordingly.

Take for example, a driver with four channels with the following description:
- channel0: index: 0, type: be:u16/16>>0
- channel1: index: 1, type: be:u32/32>>0
- channel2: index: 2, type: be:u32/32>>0
- channel3: index: 3, type: be:u64/64>>0

If all channels are enabled, the data will be aligned in the buffer as follows::

          0-1   2   3   4-7  8-11  12  13  14  15  16-23   -> buffer byte number
        +-----+---+---+-----+-----+---+---+---+---+-----+
        |CHN_0|PAD|PAD|CHN_1|CHN_2|PAD|PAD|PAD|PAD|CHN_3|  -> buffer content
        +-----+---+---+-----+-----+---+---+---+---+-----+

If only channel0 and channel3 are enabled, the data will be aligned in the
buffer as follows::

          0-1   2   3   4   5   6   7  8-15    -> buffer byte number
        +-----+---+---+---+---+---+---+-----+
        |CHN_0|PAD|PAD|PAD|PAD|PAD|PAD|CHN_3|  -> buffer content
        +-----+---+---+---+---+---+---+-----+

Typically the buffered data is found in raw format (unscaled with no offset
applied), however there are corner cases in which the buffered data may be found
in a processed form. Please note that these corner cases are not addressed by
this documentation.

Please see ``Documentation/ABI/testing/sysfs-bus-iio`` for a complete
description of the attributes.
Commit	Line	Data
d5422a85 RG	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	=============================
	4	Industrial IIO device buffers
	5	=============================
	6
	7	1. Overview
	8	===========
	9
	10	The Industrial I/O core offers a way for continuous data capture based on a
	11	trigger source. Multiple data channels can be read at once from
	12	``/dev/iio:deviceX`` character device node, thus reducing the CPU load.
	13
	14	Devices with buffer support feature an additional sub-directory in the
	15	``/sys/bus/iio/devices/iio:deviceX/`` directory hierarchy, called bufferY, where
	16	Y defaults to 0, for devices with a single buffer.
	17
	18	2. Buffer attributes
	19	====================
	20
	21	An IIO buffer has an associated attributes directory under
	22	``/sys/bus/iio/iio:deviceX/bufferY/``. The attributes are described below.
	23
	24	``length``
	25	----------
	26
	27	Read / Write attribute which states the total number of data samples (capacity)
	28	that can be stored by the buffer.
	29
	30	``enable``
	31	----------
	32
	33	Read / Write attribute which starts / stops the buffer capture. This file should
	34	be written last, after length and selection of scan elements. Writing a non-zero
	35	value may result in an error, such as EINVAL, if, for example, an unsupported
	36	combination of channels is given.
	37
	38	``watermark``
	39	-------------
	40
	41	Read / Write positive integer attribute specifying the maximum number of scan
	42	elements to wait for.
	43
	44	Poll will block until the watermark is reached.
	45
	46	Blocking read will wait until the minimum between the requested read amount or
	47	the low watermark is available.
	48
	49	Non-blocking read will retrieve the available samples from the buffer even if
	50	there are less samples than the watermark level. This allows the application to
	51	block on poll with a timeout and read the available samples after the timeout
	52	expires and thus have a maximum delay guarantee.
	53
	54	Data available
	55	--------------
	56
	57	Read-only attribute indicating the bytes of data available in the buffer. In the
	58	case of an output buffer, this indicates the amount of empty space available to
	59	write data to. In the case of an input buffer, this indicates the amount of data
	60	available for reading.
	61
	62	Scan elements
	63	-------------
	64
65	The meta information associated with a channel data placed in a buffer is called
66	a scan element. The scan elements attributes are presented below.
67
68	_en
69
70	Read / Write attribute used for enabling a channel. If and only if its value
71	is non-zero, then a triggered capture will contain data samples for this
72	channel.
73
74	_index
75
76	Read-only unsigned integer attribute specifying the position of the channel in
77	the buffer. Note these are not dependent on what is enabled and may not be
78	contiguous. Thus for userspace to establish the full layout these must be used
79	in conjunction with all _en attributes to establish which channels are present,
80	and the relevant _type attributes to establish the data storage format.
81
82	_type
83
84	Read-only attribute containing the description of the scan element data storage
85	within the buffer and hence the form in which it is read from userspace. Format
86	is [be\|le]:[s\|u]bits/storagebits[Xrepeat][>>shift], where:
87
88	- be or le specifies big or little-endian.
89	- s or u specifies if signed (2's complement) or unsigned.
90	- bits is the number of valid data bits.
91	- storagebits is the number of bits (after padding) that it occupies in the
92	buffer.
93	- repeat specifies the number of bits/storagebits repetitions. When the
94	repeat element is 0 or 1, then the repeat value is omitted.
95	- shift if specified, is the shift that needs to be applied prior to
96	masking out unused bits.
97
98	For example, a driver for a 3-axis accelerometer with 12-bit resolution where
99	data is stored in two 8-bit registers is as follows::
100
101	7 6 5 4 3 2 1 0
102	+---+---+---+---+---+---+---+---+
103	\|D3 \|D2 \|D1 \|D0 \| X \| X \| X \| X \| (LOW byte, address 0x06)
104	+---+---+---+---+---+---+---+---+
105
106	7 6 5 4 3 2 1 0
107	+---+---+---+---+---+---+---+---+
108	\|D11\|D10\|D9 \|D8 \|D7 \|D6 \|D5 \|D4 \| (HIGH byte, address 0x07)
109	+---+---+---+---+---+---+---+---+
110
111	will have the following scan element type for each axis:
112
113	.. code-block:: bash
114
115	$ cat /sys/bus/iio/devices/iio:device0/buffer0/in_accel_y_type
116	le:s12/16>>4
117
118	A userspace application will interpret data samples read from the buffer as
119	two-byte little-endian signed data, that needs a 4 bits right shift before
120	masking out the 12 valid bits of data.
121
122	It is also worth mentioning that the data in the buffer will be naturally
123	aligned, so the userspace application has to handle the buffers accordingly.
124
125	Take for example, a driver with four channels with the following description:
126	- channel0: index: 0, type: be:u16/16>>0
127	- channel1: index: 1, type: be:u32/32>>0
128	- channel2: index: 2, type: be:u32/32>>0
129	- channel3: index: 3, type: be:u64/64>>0
130
131	If all channels are enabled, the data will be aligned in the buffer as follows::
132
133	0-1 2 3 4-7 8-11 12 13 14 15 16-23 -> buffer byte number
134	+-----+---+---+-----+-----+---+---+---+---+-----+
135	\|CHN_0\|PAD\|PAD\|CHN_1\|CHN_2\|PAD\|PAD\|PAD\|PAD\|CHN_3\| -> buffer content
136	+-----+---+---+-----+-----+---+---+---+---+-----+
137
138	If only channel0 and channel3 are enabled, the data will be aligned in the
139	buffer as follows::
140
141	0-1 2 3 4 5 6 7 8-15 -> buffer byte number
142	+-----+---+---+---+---+---+---+-----+
143	\|CHN_0\|PAD\|PAD\|PAD\|PAD\|PAD\|PAD\|CHN_3\| -> buffer content
144	+-----+---+---+---+---+---+---+-----+
145
146	Typically the buffered data is found in raw format (unscaled with no offset
147	applied), however there are corner cases in which the buffered data may be found
148	in a processed form. Please note that these corner cases are not addressed by
149	this documentation.
150
151	Please see ``Documentation/ABI/testing/sysfs-bus-iio`` for a complete
152	description of the attributes.