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