Documentation/iio/iio_devbuf.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =============================
   4 Industrial IIO device buffers
   5 =============================
   6
   7 1. Overview
   8 ===========
   9
  10 The Industrial I/O core offers a way for continuous data capture based on a
  11 trigger source. Multiple data channels can be read at once from
  12 ``/dev/iio:deviceX`` character device node, thus reducing the CPU load.
  13
  14 Devices with buffer support feature an additional sub-directory in the
  15 ``/sys/bus/iio/devices/iio:deviceX/`` directory hierarchy, called bufferY, where
  16 Y defaults to 0, for devices with a single buffer.
  17
  18 2. Buffer attributes
  19 ====================
  20
  21 An IIO buffer has an associated attributes directory under
  22 ``/sys/bus/iio/iio:deviceX/bufferY/``. The attributes are described below.
  23
  24 ``length``
  25 ----------
  26
  27 Read / Write attribute which states the total number of data samples (capacity)
  28 that can be stored by the buffer.
  29
  30 ``enable``
  31 ----------
  32
  33 Read / Write attribute which starts / stops the buffer capture. This file should
  34 be written last, after length and selection of scan elements. Writing a non-zero
  35 value may result in an error, such as EINVAL, if, for example, an unsupported
  36 combination of channels is given.
  37
  38 ``watermark``
  39 -------------
  40
  41 Read / Write positive integer attribute specifying the maximum number of scan
  42 elements to wait for.
  43
  44 Poll will block until the watermark is reached.
  45
  46 Blocking read will wait until the minimum between the requested read amount or
  47 the low watermark is available.
  48
  49 Non-blocking read will retrieve the available samples from the buffer even if
  50 there are less samples than the watermark level. This allows the application to
  51 block on poll with a timeout and read the available samples after the timeout
  52 expires and thus have a maximum delay guarantee.
  53
  54 Data available
  55 --------------
  56
  57 Read-only attribute indicating the bytes of data available in the buffer. In the
  58 case of an output buffer, this indicates the amount of empty space available to
  59 write data to. In the case of an input buffer, this indicates the amount of data
  60 available for reading.
  61
  62 Scan elements
  63 -------------
  64
  65 The meta information associated with a channel data placed in a buffer is called
  66 a scan element. The scan elements attributes are presented below.
  67
  68 **_en**
  69
  70 Read / Write attribute used for enabling a channel. If and only if its value
  71 is non-zero, then a triggered capture will contain data samples for this
  72 channel.
  73
  74 **_index**
  75
  76 Read-only unsigned integer attribute specifying the position of the channel in
  77 the buffer. Note these are not dependent on what is enabled and may not be
  78 contiguous. Thus for userspace to establish the full layout these must be used
  79 in conjunction with all _en attributes to establish which channels are present,
  80 and the relevant _type attributes to establish the data storage format.
  81
  82 **_type**
  83
  84 Read-only attribute containing the description of the scan element data storage
  85 within the buffer and hence the form in which it is read from userspace. Format
  86 is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift], where:
  87
  88 - **be** or **le** specifies big or little-endian.
  89 - **s** or **u** specifies if signed (2's complement) or unsigned.
  90 - **bits** is the number of valid data bits.
  91 - **storagebits** is the number of bits (after padding) that it occupies in the
  92   buffer.
  93 - **repeat** specifies the number of bits/storagebits repetitions. When the
  94   repeat element is 0 or 1, then the repeat value is omitted.
  95 - **shift** if specified, is the shift that needs to be applied prior to
  96   masking out unused bits.
  97
  98 For example, a driver for a 3-axis accelerometer with 12-bit resolution where
  99 data is stored in two 8-bit registers is as follows::
 100
 101           7   6   5   4   3   2   1   0
 102         +---+---+---+---+---+---+---+---+
 103         |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
 104         +---+---+---+---+---+---+---+---+
 105
 106           7   6   5   4   3   2   1   0
 107         +---+---+---+---+---+---+---+---+
 108         |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
 109         +---+---+---+---+---+---+---+---+
 110
 111 will have the following scan element type for each axis:
 112
 113 .. code-block:: bash
 114
 115         $ cat /sys/bus/iio/devices/iio:device0/buffer0/in_accel_y_type
 116         le:s12/16>>4
 117
 118 A userspace application will interpret data samples read from the buffer as
 119 two-byte little-endian signed data, that needs a 4 bits right shift before
 120 masking out the 12 valid bits of data.
 121
 122 It is also worth mentioning that the data in the buffer will be naturally
 123 aligned, so the userspace application has to handle the buffers accordingly.
 124
 125 Take for example, a driver with four channels with the following description:
 126 - channel0: index: 0, type: be:u16/16>>0
 127 - channel1: index: 1, type: be:u32/32>>0
 128 - channel2: index: 2, type: be:u32/32>>0
 129 - channel3: index: 3, type: be:u64/64>>0
 130
 131 If all channels are enabled, the data will be aligned in the buffer as follows::
 132
 133           0-1   2   3   4-7  8-11  12  13  14  15  16-23   -> buffer byte number
 134         +-----+---+---+-----+-----+---+---+---+---+-----+
 135         |CHN_0|PAD|PAD|CHN_1|CHN_2|PAD|PAD|PAD|PAD|CHN_3|  -> buffer content
 136         +-----+---+---+-----+-----+---+---+---+---+-----+
 137
 138 If only channel0 and channel3 are enabled, the data will be aligned in the
 139 buffer as follows::
 140
 141           0-1   2   3   4   5   6   7  8-15    -> buffer byte number
 142         +-----+---+---+---+---+---+---+-----+
 143         |CHN_0|PAD|PAD|PAD|PAD|PAD|PAD|CHN_3|  -> buffer content
 144         +-----+---+---+---+---+---+---+-----+
 145
 146 Typically the buffered data is found in raw format (unscaled with no offset
 147 applied), however there are corner cases in which the buffered data may be found
 148 in a processed form. Please note that these corner cases are not addressed by
 149 this documentation.
 150
 151 Please see ``Documentation/ABI/testing/sysfs-bus-iio`` for a complete
 152 description of the attributes.