1 ======= 1 =======
2 Buffers 2 Buffers
3 ======= 3 =======
4 4
5 * struct iio_buffer — general buffer structu 5 * struct iio_buffer — general buffer structure
6 * :c:func:`iio_validate_scan_mask_onehot` — 6 * :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel
7 is selected 7 is selected
8 * :c:func:`iio_buffer_get` — Grab a referenc 8 * :c:func:`iio_buffer_get` — Grab a reference to the buffer
9 * :c:func:`iio_buffer_put` — Release the ref 9 * :c:func:`iio_buffer_put` — Release the reference to the buffer
10 10
11 The Industrial I/O core offers a way for conti 11 The Industrial I/O core offers a way for continuous data capture based on a
12 trigger source. Multiple data channels can be 12 trigger source. Multiple data channels can be read at once from
13 :file:`/dev/iio:device{X}` character device no 13 :file:`/dev/iio:device{X}` character device node, thus reducing the CPU load.
14 14
15 IIO buffer sysfs interface 15 IIO buffer sysfs interface
16 ========================== 16 ==========================
17 An IIO buffer has an associated attributes dir 17 An IIO buffer has an associated attributes directory under
18 :file:`/sys/bus/iio/devices/iio:device{X}/buff 18 :file:`/sys/bus/iio/devices/iio:device{X}/buffer/*`. Here are some of the
19 existing attributes: 19 existing attributes:
20 20
21 * :file:`length`, the total number of data sam 21 * :file:`length`, the total number of data samples (capacity) that can be
22 stored by the buffer. 22 stored by the buffer.
23 * :file:`enable`, activate buffer capture. 23 * :file:`enable`, activate buffer capture.
24 24
25 IIO buffer setup 25 IIO buffer setup
26 ================ 26 ================
27 27
28 The meta information associated with a channel 28 The meta information associated with a channel reading placed in a buffer is
29 called a scan element. The important bits conf 29 called a scan element. The important bits configuring scan elements are
30 exposed to userspace applications via the 30 exposed to userspace applications via the
31 :file:`/sys/bus/iio/devices/iio:device{X}/scan 31 :file:`/sys/bus/iio/devices/iio:device{X}/scan_elements/` directory. This
32 directory contains attributes of the following 32 directory contains attributes of the following form:
33 33
34 * :file:`enable`, used for enabling a channel. 34 * :file:`enable`, used for enabling a channel. If and only if its attribute
35 is non *zero*, then a triggered capture will 35 is non *zero*, then a triggered capture will contain data samples for this
36 channel. 36 channel.
37 * :file:`index`, the scan_index of the channel 37 * :file:`index`, the scan_index of the channel.
38 * :file:`type`, description of the scan elemen 38 * :file:`type`, description of the scan element data storage within the buffer
39 and hence the form in which it is read from 39 and hence the form in which it is read from user space.
40 Format is [be|le]:[s|u]bits/storagebits[Xrep 40 Format is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift] .
41 41
42 * *be* or *le*, specifies big or little endi 42 * *be* or *le*, specifies big or little endian.
43 * *s* or *u*, specifies if signed (2's compl 43 * *s* or *u*, specifies if signed (2's complement) or unsigned.
44 * *bits*, is the number of valid data bits. 44 * *bits*, is the number of valid data bits.
45 * *storagebits*, is the number of bits (afte 45 * *storagebits*, is the number of bits (after padding) that it occupies in the
46 buffer. 46 buffer.
47 * *repeat*, specifies the number of bits/sto 47 * *repeat*, specifies the number of bits/storagebits repetitions. When the
48 repeat element is 0 or 1, then the repeat 48 repeat element is 0 or 1, then the repeat value is omitted.
49 * *shift*, if specified, is the shift that n 49 * *shift*, if specified, is the shift that needs to be applied prior to
50 masking out unused bits. 50 masking out unused bits.
51 51
52 For example, a driver for a 3-axis acceleromet 52 For example, a driver for a 3-axis accelerometer with 12 bit resolution where
53 data is stored in two 8-bits registers as foll 53 data is stored in two 8-bits registers as follows::
54 54
55 7 6 5 4 3 2 1 0 55 7 6 5 4 3 2 1 0
56 +---+---+---+---+---+---+---+---+ 56 +---+---+---+---+---+---+---+---+
57 |D3 |D2 |D1 |D0 | X | X | X | X | (LOW b 57 |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
58 +---+---+---+---+---+---+---+---+ 58 +---+---+---+---+---+---+---+---+
59 59
60 7 6 5 4 3 2 1 0 60 7 6 5 4 3 2 1 0
61 +---+---+---+---+---+---+---+---+ 61 +---+---+---+---+---+---+---+---+
62 |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH 62 |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
63 +---+---+---+---+---+---+---+---+ 63 +---+---+---+---+---+---+---+---+
64 64
65 will have the following scan element type for 65 will have the following scan element type for each axis::
66 66
67 $ cat /sys/bus/iio/devices/iio:device0/s 67 $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type
68 le:s12/16>>4 68 le:s12/16>>4
69 69
70 A user space application will interpret data s 70 A user space application will interpret data samples read from the buffer as
71 two byte little endian signed data, that needs 71 two byte little endian signed data, that needs a 4 bits right shift before
72 masking out the 12 valid bits of data. 72 masking out the 12 valid bits of data.
73 73
74 For implementing buffer support a driver shoul 74 For implementing buffer support a driver should initialize the following
75 fields in iio_chan_spec definition:: 75 fields in iio_chan_spec definition::
76 76
77 struct iio_chan_spec { 77 struct iio_chan_spec {
78 /* other members */ 78 /* other members */
79 int scan_index 79 int scan_index
80 struct { 80 struct {
81 char sign; 81 char sign;
82 u8 realbits; 82 u8 realbits;
83 u8 storagebits; 83 u8 storagebits;
84 u8 shift; 84 u8 shift;
85 u8 repeat; 85 u8 repeat;
86 enum iio_endian endianness; 86 enum iio_endian endianness;
87 } scan_type; 87 } scan_type;
88 }; 88 };
89 89
90 The driver implementing the accelerometer desc 90 The driver implementing the accelerometer described above will have the
91 following channel definition:: 91 following channel definition::
92 92
93 struct iio_chan_spec accel_channels[] = { 93 struct iio_chan_spec accel_channels[] = {
94 { 94 {
95 .type = IIO_ACCEL, 95 .type = IIO_ACCEL,
96 .modified = 1, 96 .modified = 1,
97 .channel2 = IIO_MOD_X, 97 .channel2 = IIO_MOD_X,
98 /* other stuff here */ 98 /* other stuff here */
99 .scan_index = 0, 99 .scan_index = 0,
100 .scan_type = { 100 .scan_type = {
101 .sign = 's', 101 .sign = 's',
102 .realbits = 12, 102 .realbits = 12,
103 .storagebits = 16, 103 .storagebits = 16,
104 .shift = 4, 104 .shift = 4,
105 .endianness = IIO_L 105 .endianness = IIO_LE,
106 }, 106 },
107 } 107 }
108 /* similar for Y (with channel2 = I 108 /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1)
109 * and Z (with channel2 = IIO_MOD_Z 109 * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis
110 */ 110 */
111 } 111 }
112 112
113 Here **scan_index** defines the order in which 113 Here **scan_index** defines the order in which the enabled channels are placed
114 inside the buffer. Channels with a lower **sca 114 inside the buffer. Channels with a lower **scan_index** will be placed before
115 channels with a higher index. Each channel nee 115 channels with a higher index. Each channel needs to have a unique
116 **scan_index**. 116 **scan_index**.
117 117
118 Setting **scan_index** to -1 can be used to in 118 Setting **scan_index** to -1 can be used to indicate that the specific channel
119 does not support buffered capture. In this cas 119 does not support buffered capture. In this case no entries will be created for
120 the channel in the scan_elements directory. 120 the channel in the scan_elements directory.
121 121
122 More details 122 More details
123 ============ 123 ============
124 .. kernel-doc:: include/linux/iio/buffer.h 124 .. kernel-doc:: include/linux/iio/buffer.h
125 .. kernel-doc:: drivers/iio/industrialio-buffe 125 .. kernel-doc:: drivers/iio/industrialio-buffer.c
126 :export: 126 :export:
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.