Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: iio: add documentation for device buffers
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>
Link: https://lore.kernel.org/r/20240221085848.991413-3-ramona.gradinariu@analog.com
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
authored by
Ramona Gradinariu
and committed by
Jonathan Cameron
d5422a85
a3e58e4a
+153
+152
Documentation/iio/iio_devbuf.rst
+152
Documentation/iio/iio_devbuf.rst
···
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.