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