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