length¶

Read / Write attribute which states the total number of data samples (capacity)that can be stored by the buffer.

enable¶

Read / Write attribute which starts / stops the buffer capture. This file shouldbe written last, after length and selection of scan elements. Writing a non-zerovalue may result in an error, such as EINVAL, if, for example, an unsupportedcombination of channels is given.

watermark¶

Read / Write positive integer attribute specifying the maximum number of scanelements to wait for.

Poll will block until the watermark is reached.

Blocking read will wait until the minimum between the requested read amount orthe low watermark is available.

Non-blocking read will retrieve the available samples from the buffer even ifthere are less samples than the watermark level. This allows the application toblock on poll with a timeout and read the available samples after the timeoutexpires and thus have a maximum delay guarantee.

Data available¶

Read-only attribute indicating the bytes of data available in the buffer. In thecase of an output buffer, this indicates the amount of empty space available towrite data to. In the case of an input buffer, this indicates the amount of dataavailable for reading.

Scan elements¶

The meta information associated with a channel data placed in a buffer is calleda scan element. The scan elements attributes are presented below.

_en

Read / Write attribute used for enabling a channel. If and only if its valueis non-zero, then a triggered capture will contain data samples for thischannel.

_index

Read-only unsigned integer attribute specifying the position of the channel inthe buffer. Note these are not dependent on what is enabled and may not becontiguous. Thus for userspace to establish the full layout these must be usedin conjunction with all _en attributes to establish which channels are present,and the relevant _type attributes to establish the data storage format.

_type

Read-only attribute containing the description of the scan element data storagewithin the buffer and hence the form in which it is read from userspace. Formatis [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift], where:

• be orle specifies big or little-endian.

• s oru specifies if signed (2’s complement) or unsigned.

• bits is the number of valid data bits.

• storagebits is the number of bits (after padding) that it occupies in thebuffer.

• repeat specifies the number of bits/storagebits repetitions. When therepeat element is 0 or 1, then the repeat value is omitted.

• shift if specified, is the shift that needs to be applied prior tomasking out unused bits.

For example, a driver for a 3-axis accelerometer with 12-bit resolution wheredata is stored in two 8-bit registers is as follows:

  7   6   5   4   3   2   1   0+---+---+---+---+---+---+---+---+|D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)+---+---+---+---+---+---+---+---+  7   6   5   4   3   2   1   0+---+---+---+---+---+---+---+---+|D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)+---+---+---+---+---+---+---+---+

will have the following scan element type for each axis:

$cat/sys/bus/iio/devices/iio:device0/buffer0/in_accel_y_typele:s12/16>>4

A userspace application will interpret data samples read from the buffer astwo-byte little-endian signed data, that needs a 4 bits right shift beforemasking out the 12 valid bits of data.

It is also worth mentioning that the data in the buffer will be naturallyaligned, so the userspace application has to handle the buffers accordingly.

Take for example, a driver with four channels with the following description:- channel0: index: 0, type: be:u16/16>>0- channel1: index: 1, type: be:u32/32>>0- channel2: index: 2, type: be:u32/32>>0- channel3: index: 3, type: be:u64/64>>0

If all channels are enabled, the data will be aligned in the buffer as follows:

  0-1   2   3   4-7  8-11  12  13  14  15  16-23   -> buffer byte number+-----+---+---+-----+-----+---+---+---+---+-----+|CHN_0|PAD|PAD|CHN_1|CHN_2|PAD|PAD|PAD|PAD|CHN_3|  -> buffer content+-----+---+---+-----+-----+---+---+---+---+-----+

If only channel0 and channel3 are enabled, the data will be aligned in thebuffer as follows:

  0-1   2   3   4   5   6   7  8-15    -> buffer byte number+-----+---+---+---+---+---+---+-----+|CHN_0|PAD|PAD|PAD|PAD|PAD|PAD|CHN_3|  -> buffer content+-----+---+---+---+---+---+---+-----+

Typically the buffered data is found in raw format (unscaled with no offsetapplied), however there are corner cases in which the buffered data may be foundin a processed form. Please note that these corner cases are not addressed bythis documentation.

Please seeABI file testing/sysfs-bus-iio for a completedescription of the attributes.