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