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 conti
11 trigger source. Multiple data channels can be
12 ``/dev/iio:deviceX`` character device node, th
13
14 Devices with buffer support feature an additio
15 ``/sys/bus/iio/devices/iio:deviceX/`` director
16 Y defaults to 0, for devices with a single buf
17
18 2. Buffer attributes
19 ====================
20
21 An IIO buffer has an associated attributes dir
22 ``/sys/bus/iio/iio:deviceX/bufferY/``. The att
23
24 ``length``
25 ----------
26
27 Read / Write attribute which states the total
28 that can be stored by the buffer.
29
30 ``enable``
31 ----------
32
33 Read / Write attribute which starts / stops th
34 be written last, after length and selection of
35 value may result in an error, such as EINVAL,
36 combination of channels is given.
37
38 ``watermark``
39 -------------
40
41 Read / Write positive integer attribute specif
42 elements to wait for.
43
44 Poll will block until the watermark is reached
45
46 Blocking read will wait until the minimum betw
47 the low watermark is available.
48
49 Non-blocking read will retrieve the available
50 there are less samples than the watermark leve
51 block on poll with a timeout and read the avai
52 expires and thus have a maximum delay guarante
53
54 Data available
55 --------------
56
57 Read-only attribute indicating the bytes of da
58 case of an output buffer, this indicates the a
59 write data to. In the case of an input buffer,
60 available for reading.
61
62 Scan elements
63 -------------
64
65 The meta information associated with a channel
66 a scan element. The scan elements attributes a
67
68 **_en**
69
70 Read / Write attribute used for enabling a cha
71 is non-zero, then a triggered capture will con
72 channel.
73
74 **_index**
75
76 Read-only unsigned integer attribute specifyin
77 the buffer. Note these are not dependent on wh
78 contiguous. Thus for userspace to establish th
79 in conjunction with all _en attributes to esta
80 and the relevant _type attributes to establish
81
82 **_type**
83
84 Read-only attribute containing the description
85 within the buffer and hence the form in which
86 is [be|le]:[s|u]bits/storagebits[Xrepeat][>>sh
87
88 - **be** or **le** specifies big or little-end
89 - **s** or **u** specifies if signed (2's comp
90 - **bits** is the number of valid data bits.
91 - **storagebits** is the number of bits (after
92 buffer.
93 - **repeat** specifies the number of bits/stor
94 repeat element is 0 or 1, then the repeat va
95 - **shift** if specified, is the shift that ne
96 masking out unused bits.
97
98 For example, a driver for a 3-axis acceleromet
99 data is stored in two 8-bit registers is as fo
100
101 7 6 5 4 3 2 1 0
102 +---+---+---+---+---+---+---+---+
103 |D3 |D2 |D1 |D0 | X | X | X | X | (LOW
104 +---+---+---+---+---+---+---+---+
105
106 7 6 5 4 3 2 1 0
107 +---+---+---+---+---+---+---+---+
108 |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIG
109 +---+---+---+---+---+---+---+---+
110
111 will have the following scan element type for
112
113 .. code-block:: bash
114
115 $ cat /sys/bus/iio/devices/iio:device0
116 le:s12/16>>4
117
118 A userspace application will interpret data sa
119 two-byte little-endian signed data, that needs
120 masking out the 12 valid bits of data.
121
122 It is also worth mentioning that the data in t
123 aligned, so the userspace application has to h
124
125 Take for example, a driver with four channels
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
132
133 0-1 2 3 4-7 8-11 12 13 14
134 +-----+---+---+-----+-----+---+---+---
135 |CHN_0|PAD|PAD|CHN_1|CHN_2|PAD|PAD|PAD
136 +-----+---+---+-----+-----+---+---+---
137
138 If only channel0 and channel3 are enabled, the
139 buffer as follows::
140
141 0-1 2 3 4 5 6 7 8-15
142 +-----+---+---+---+---+---+---+-----+
143 |CHN_0|PAD|PAD|PAD|PAD|PAD|PAD|CHN_3|
144 +-----+---+---+---+---+---+---+-----+
145
146 Typically the buffered data is found in raw fo
147 applied), however there are corner cases in wh
148 in a processed form. Please note that these co
149 this documentation.
150
151 Please see ``Documentation/ABI/testing/sysfs-b
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.