1 ======= 1 =======
2 Buffers 2 Buffers
3 ======= 3 =======
4 4
5 * struct iio_buffer — general buffer structu !! 5 * struct :c:type:`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/iio:device{X}/buffer/*`. Here are some of the existing
19 existing attributes: !! 19 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/iio:device{X}/scan_elements/*` directory. This file contains
32 directory contains attributes of the following !! 32 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 <<
38 * :file:`type`, description of the scan elemen 37 * :file:`type`, description of the scan element data storage within the buffer
39 and hence the form in which it is read from 38 and hence the form in which it is read from user space.
40 Format is [be|le]:[s|u]bits/storagebits[Xrep !! 39 Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] .
41 <<
42 * *be* or *le*, specifies big or little endi 40 * *be* or *le*, specifies big or little endian.
43 * *s* or *u*, specifies if signed (2's compl 41 * *s* or *u*, specifies if signed (2's complement) or unsigned.
44 * *bits*, is the number of valid data bits. 42 * *bits*, is the number of valid data bits.
45 * *storagebits*, is the number of bits (afte 43 * *storagebits*, is the number of bits (after padding) that it occupies in the
46 buffer. !! 44 buffer.
47 * *repeat*, specifies the number of bits/sto <<
48 repeat element is 0 or 1, then the repeat <<
49 * *shift*, if specified, is the shift that n 45 * *shift*, if specified, is the shift that needs to be applied prior to
50 masking out unused bits. !! 46 masking out unused bits.
>> 47 * *repeat*, specifies the number of bits/storagebits repetitions. When the
>> 48 repeat element is 0 or 1, then the repeat value is omitted.
51 49
52 For example, a driver for a 3-axis acceleromet 50 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 51 data is stored in two 8-bits registers as follows::
54 52
55 7 6 5 4 3 2 1 0 53 7 6 5 4 3 2 1 0
56 +---+---+---+---+---+---+---+---+ 54 +---+---+---+---+---+---+---+---+
57 |D3 |D2 |D1 |D0 | X | X | X | X | (LOW b 55 |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
58 +---+---+---+---+---+---+---+---+ 56 +---+---+---+---+---+---+---+---+
59 57
60 7 6 5 4 3 2 1 0 58 7 6 5 4 3 2 1 0
61 +---+---+---+---+---+---+---+---+ 59 +---+---+---+---+---+---+---+---+
62 |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH 60 |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
63 +---+---+---+---+---+---+---+---+ 61 +---+---+---+---+---+---+---+---+
64 62
65 will have the following scan element type for 63 will have the following scan element type for each axis::
66 64
67 $ cat /sys/bus/iio/devices/iio:device0/s 65 $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type
68 le:s12/16>>4 66 le:s12/16>>4
69 67
70 A user space application will interpret data s 68 A user space application will interpret data samples read from the buffer as
71 two byte little endian signed data, that needs 69 two byte little endian signed data, that needs a 4 bits right shift before
72 masking out the 12 valid bits of data. 70 masking out the 12 valid bits of data.
73 71
74 For implementing buffer support a driver shoul 72 For implementing buffer support a driver should initialize the following
75 fields in iio_chan_spec definition:: 73 fields in iio_chan_spec definition::
76 74
77 struct iio_chan_spec { 75 struct iio_chan_spec {
78 /* other members */ 76 /* other members */
79 int scan_index 77 int scan_index
80 struct { 78 struct {
81 char sign; 79 char sign;
82 u8 realbits; 80 u8 realbits;
83 u8 storagebits; 81 u8 storagebits;
84 u8 shift; 82 u8 shift;
85 u8 repeat; 83 u8 repeat;
86 enum iio_endian endianness; 84 enum iio_endian endianness;
87 } scan_type; 85 } scan_type;
88 }; 86 };
89 87
90 The driver implementing the accelerometer desc 88 The driver implementing the accelerometer described above will have the
91 following channel definition:: 89 following channel definition::
92 90
93 struct iio_chan_spec accel_channels[] = { 91 struct iio_chan_spec accel_channels[] = {
94 { 92 {
95 .type = IIO_ACCEL, 93 .type = IIO_ACCEL,
96 .modified = 1, 94 .modified = 1,
97 .channel2 = IIO_MOD_X, 95 .channel2 = IIO_MOD_X,
98 /* other stuff here */ 96 /* other stuff here */
99 .scan_index = 0, 97 .scan_index = 0,
100 .scan_type = { 98 .scan_type = {
101 .sign = 's', 99 .sign = 's',
102 .realbits = 12, 100 .realbits = 12,
103 .storagebits = 16, 101 .storagebits = 16,
104 .shift = 4, 102 .shift = 4,
105 .endianness = IIO_L 103 .endianness = IIO_LE,
106 }, 104 },
107 } 105 }
108 /* similar for Y (with channel2 = I 106 /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1)
109 * and Z (with channel2 = IIO_MOD_Z 107 * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis
110 */ 108 */
111 } 109 }
112 110
113 Here **scan_index** defines the order in which 111 Here **scan_index** defines the order in which the enabled channels are placed
114 inside the buffer. Channels with a lower **sca 112 inside the buffer. Channels with a lower **scan_index** will be placed before
115 channels with a higher index. Each channel nee 113 channels with a higher index. Each channel needs to have a unique
116 **scan_index**. 114 **scan_index**.
117 115
118 Setting **scan_index** to -1 can be used to in 116 Setting **scan_index** to -1 can be used to indicate that the specific channel
119 does not support buffered capture. In this cas 117 does not support buffered capture. In this case no entries will be created for
120 the channel in the scan_elements directory. 118 the channel in the scan_elements directory.
121 119
122 More details 120 More details
123 ============ 121 ============
124 .. kernel-doc:: include/linux/iio/buffer.h 122 .. kernel-doc:: include/linux/iio/buffer.h
125 .. kernel-doc:: drivers/iio/industrialio-buffe 123 .. kernel-doc:: drivers/iio/industrialio-buffer.c
126 :export: 124 :export:
>> 125
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.