0001 =======
0002 Buffers
0003 =======
0004
0005 * struct iio_buffer — general buffer structure
0006 * :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel
0007 is selected
0008 * :c:func:`iio_buffer_get` — Grab a reference to the buffer
0009 * :c:func:`iio_buffer_put` — Release the reference to the buffer
0010
0011 The Industrial I/O core offers a way for continuous data capture based on a
0012 trigger source. Multiple data channels can be read at once from
0013 :file:`/dev/iio:device{X}` character device node, thus reducing the CPU load.
0014
0015 IIO buffer sysfs interface
0016 ==========================
0017 An IIO buffer has an associated attributes directory under
0018 :file:`/sys/bus/iio/iio:device{X}/buffer/*`. Here are some of the existing
0019 attributes:
0020
0021 * :file:`length`, the total number of data samples (capacity) that can be
0022 stored by the buffer.
0023 * :file:`enable`, activate buffer capture.
0024
0025 IIO buffer setup
0026 ================
0027
0028 The meta information associated with a channel reading placed in a buffer is
0029 called a scan element. The important bits configuring scan elements are
0030 exposed to userspace applications via the
0031 :file:`/sys/bus/iio/iio:device{X}/scan_elements/` directory. This directory contains
0032 attributes of the following form:
0033
0034 * :file:`enable`, used for enabling a channel. If and only if its attribute
0035 is non *zero*, then a triggered capture will contain data samples for this
0036 channel.
0037 * :file:`index`, the scan_index of the channel.
0038 * :file:`type`, description of the scan element data storage within the buffer
0039 and hence the form in which it is read from user space.
0040 Format is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift] .
0041
0042 * *be* or *le*, specifies big or little endian.
0043 * *s* or *u*, specifies if signed (2's complement) or unsigned.
0044 * *bits*, is the number of valid data bits.
0045 * *storagebits*, is the number of bits (after padding) that it occupies in the
0046 buffer.
0047 * *repeat*, specifies the number of bits/storagebits repetitions. When the
0048 repeat element is 0 or 1, then the repeat value is omitted.
0049 * *shift*, if specified, is the shift that needs to be applied prior to
0050 masking out unused bits.
0051
0052 For example, a driver for a 3-axis accelerometer with 12 bit resolution where
0053 data is stored in two 8-bits registers as follows::
0054
0055 7 6 5 4 3 2 1 0
0056 +---+---+---+---+---+---+---+---+
0057 |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
0058 +---+---+---+---+---+---+---+---+
0059
0060 7 6 5 4 3 2 1 0
0061 +---+---+---+---+---+---+---+---+
0062 |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
0063 +---+---+---+---+---+---+---+---+
0064
0065 will have the following scan element type for each axis::
0066
0067 $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type
0068 le:s12/16>>4
0069
0070 A user space application will interpret data samples read from the buffer as
0071 two byte little endian signed data, that needs a 4 bits right shift before
0072 masking out the 12 valid bits of data.
0073
0074 For implementing buffer support a driver should initialize the following
0075 fields in iio_chan_spec definition::
0076
0077 struct iio_chan_spec {
0078 /* other members */
0079 int scan_index
0080 struct {
0081 char sign;
0082 u8 realbits;
0083 u8 storagebits;
0084 u8 shift;
0085 u8 repeat;
0086 enum iio_endian endianness;
0087 } scan_type;
0088 };
0089
0090 The driver implementing the accelerometer described above will have the
0091 following channel definition::
0092
0093 struct iio_chan_spec accel_channels[] = {
0094 {
0095 .type = IIO_ACCEL,
0096 .modified = 1,
0097 .channel2 = IIO_MOD_X,
0098 /* other stuff here */
0099 .scan_index = 0,
0100 .scan_type = {
0101 .sign = 's',
0102 .realbits = 12,
0103 .storagebits = 16,
0104 .shift = 4,
0105 .endianness = IIO_LE,
0106 },
0107 }
0108 /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1)
0109 * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis
0110 */
0111 }
0112
0113 Here **scan_index** defines the order in which the enabled channels are placed
0114 inside the buffer. Channels with a lower **scan_index** will be placed before
0115 channels with a higher index. Each channel needs to have a unique
0116 **scan_index**.
0117
0118 Setting **scan_index** to -1 can be used to indicate that the specific channel
0119 does not support buffered capture. In this case no entries will be created for
0120 the channel in the scan_elements directory.
0121
0122 More details
0123 ============
0124 .. kernel-doc:: include/linux/iio/buffer.h
0125 .. kernel-doc:: drivers/iio/industrialio-buffer.c
0126 :export:
