127 lines · plain
1=======2Buffers3=======4 5* struct iio_buffer — general buffer structure6* :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel7 is selected8* :c:func:`iio_buffer_get` — Grab a reference to the buffer9* :c:func:`iio_buffer_put` — Release the reference to the buffer10 11The Industrial I/O core offers a way for continuous data capture based on a12trigger source. Multiple data channels can be read at once from13:file:`/dev/iio:device{X}` character device node, thus reducing the CPU load.14 15IIO buffer sysfs interface16==========================17An IIO buffer has an associated attributes directory under18:file:`/sys/bus/iio/devices/iio:device{X}/buffer/*`. Here are some of the19existing attributes:20 21* :file:`length`, the total number of data samples (capacity) that can be22 stored by the buffer.23* :file:`enable`, activate buffer capture.24 25IIO buffer setup26================27 28The meta information associated with a channel reading placed in a buffer is29called a scan element. The important bits configuring scan elements are30exposed to userspace applications via the31:file:`/sys/bus/iio/devices/iio:device{X}/scan_elements/` directory. This32directory contains attributes of the following form:33 34* :file:`enable`, used for enabling a channel. If and only if its attribute35 is non *zero*, then a triggered capture will contain data samples for this36 channel.37* :file:`index`, the scan_index of the channel.38* :file:`type`, description of the scan element data storage within the buffer39 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 the46 buffer.47 * *repeat*, specifies the number of bits/storagebits repetitions. When the48 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 to50 masking out unused bits.51 52For example, a driver for a 3-axis accelerometer with 12 bit resolution where53data is stored in two 8-bits registers as follows::54 55 7 6 5 4 3 2 1 056 +---+---+---+---+---+---+---+---+57 |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)58 +---+---+---+---+---+---+---+---+59 60 7 6 5 4 3 2 1 061 +---+---+---+---+---+---+---+---+62 |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)63 +---+---+---+---+---+---+---+---+64 65will have the following scan element type for each axis::66 67 $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type68 le:s12/16>>469 70A user space application will interpret data samples read from the buffer as71two byte little endian signed data, that needs a 4 bits right shift before72masking out the 12 valid bits of data.73 74For implementing buffer support a driver should initialize the following75fields in iio_chan_spec definition::76 77 struct iio_chan_spec {78 /* other members */79 int scan_index80 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 90The driver implementing the accelerometer described above will have the91following 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) axis110 */111 }112 113Here **scan_index** defines the order in which the enabled channels are placed114inside the buffer. Channels with a lower **scan_index** will be placed before115channels with a higher index. Each channel needs to have a unique116**scan_index**.117 118Setting **scan_index** to -1 can be used to indicate that the specific channel119does not support buffered capture. In this case no entries will be created for120the channel in the scan_elements directory.121 122More details123============124.. kernel-doc:: include/linux/iio/buffer.h125.. kernel-doc:: drivers/iio/industrialio-buffer.c126 :export:127