Documentation/driver-api/iio/buffers.rst

   1 =======
   2 Buffers
   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
  11 The Industrial I/O core offers a way for continuous data capture based on a
  12 trigger 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
  15 IIO buffer sysfs interface
  16 ==========================
  17 An IIO buffer has an associated attributes directory under
  18 :file:`/sys/bus/iio/devices/iio:device{X}/buffer/*`. Here are some of the
  19 existing 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
  25 IIO buffer setup
  26 ================
  27
  28 The meta information associated with a channel reading placed in a buffer is
  29 called a scan element. The important bits configuring scan elements are
  30 exposed to userspace applications via the
  31 :file:`/sys/bus/iio/devices/iio:device{X}/scan_elements/` directory. This
  32 directory 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
  52 For example, a driver for a 3-axis accelerometer with 12 bit resolution where
  53 data 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
  65 will 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
  70 A user space application will interpret data samples read from the buffer as
  71 two byte little endian signed data, that needs a 4 bits right shift before
  72 masking out the 12 valid bits of data.
  73
  74 For implementing buffer support a driver should initialize the following
  75 fields 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
  90 The driver implementing the accelerometer described above will have the
  91 following 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
 113 Here **scan_index** defines the order in which the enabled channels are placed
 114 inside the buffer. Channels with a lower **scan_index** will be placed before
 115 channels with a higher index. Each channel needs to have a unique
 116 **scan_index**.
 117
 118 Setting **scan_index** to -1 can be used to indicate that the specific channel
 119 does not support buffered capture. In this case no entries will be created for
 120 the channel in the scan_elements directory.
 121
 122 More details
 123 ============
 124 .. kernel-doc:: include/linux/iio/buffer.h
 125 .. kernel-doc:: drivers/iio/industrialio-buffer.c
 126    :export: