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