buffers.rst

  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]:[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
 52For example, a driver for a 3-axis accelerometer with 12 bit resolution where
 53data 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
 65will 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
 70A user space application will interpret data samples read from the buffer as
 71two byte little endian signed data, that needs a 4 bits right shift before
 72masking out the 12 valid bits of data.
 73
 74For implementing buffer support a driver should initialize the following
 75fields 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
 90The driver implementing the accelerometer described above will have the
 91following 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
113Here **scan_index** defines the order in which the enabled channels are placed
114inside the buffer. Channels with a lower **scan_index** will be placed before
115channels with a higher index. Each channel needs to have a unique
116**scan_index**.
117
118Setting **scan_index** to -1 can be used to indicate that the specific channel
119does not support buffered capture. In this case no entries will be created for
120the channel in the scan_elements directory.
121
122More details
123============
124.. kernel-doc:: include/linux/iio/buffer.h
125.. kernel-doc:: drivers/iio/industrialio-buffer.c
126   :export: