126 lines
4.5 KiB
ReStructuredText
126 lines
4.5 KiB
ReStructuredText
=======
|
|
Buffers
|
|
=======
|
|
|
|
* struct :c:type:`iio_buffer` — general buffer structure
|
|
* :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel
|
|
is selected
|
|
* :c:func:`iio_buffer_get` — Grab a reference to the buffer
|
|
* :c:func:`iio_buffer_put` — Release the reference to the buffer
|
|
|
|
The Industrial I/O core offers a way for continuous data capture based on a
|
|
trigger source. Multiple data channels can be read at once from
|
|
:file:`/dev/iio:device{X}` character device node, thus reducing the CPU load.
|
|
|
|
IIO buffer sysfs interface
|
|
==========================
|
|
An IIO buffer has an associated attributes directory under
|
|
:file:`/sys/bus/iio/iio:device{X}/buffer/*`. Here are some of the existing
|
|
attributes:
|
|
|
|
* :file:`length`, the total number of data samples (capacity) that can be
|
|
stored by the buffer.
|
|
* :file:`enable`, activate buffer capture.
|
|
|
|
IIO buffer setup
|
|
================
|
|
|
|
The meta information associated with a channel reading placed in a buffer is
|
|
called a scan element . The important bits configuring scan elements are
|
|
exposed to userspace applications via the
|
|
:file:`/sys/bus/iio/iio:device{X}/scan_elements/*` directory. This file contains
|
|
attributes of the following form:
|
|
|
|
* :file:`enable`, used for enabling a channel. If and only if its attribute
|
|
is non *zero*, then a triggered capture will contain data samples for this
|
|
channel.
|
|
* :file:`type`, description of the scan element data storage within the buffer
|
|
and hence the form in which it is read from user space.
|
|
Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] .
|
|
* *be* or *le*, specifies big or little endian.
|
|
* *s* or *u*, 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 the
|
|
buffer.
|
|
* *shift*, if specified, is the shift that needs to be applied prior to
|
|
masking out unused bits.
|
|
* *repeat*, specifies the number of bits/storagebits repetitions. When the
|
|
repeat element is 0 or 1, then the repeat value is omitted.
|
|
|
|
For example, a driver for a 3-axis accelerometer with 12 bit resolution where
|
|
data is stored in two 8-bits registers 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/scan_elements/in_accel_y_type
|
|
le:s12/16>>4
|
|
|
|
A user space application will interpret data samples read from the buffer as
|
|
two byte little endian signed data, that needs a 4 bits right shift before
|
|
masking out the 12 valid bits of data.
|
|
|
|
For implementing buffer support a driver should initialize the following
|
|
fields in iio_chan_spec definition::
|
|
|
|
struct iio_chan_spec {
|
|
/* other members */
|
|
int scan_index
|
|
struct {
|
|
char sign;
|
|
u8 realbits;
|
|
u8 storagebits;
|
|
u8 shift;
|
|
u8 repeat;
|
|
enum iio_endian endianness;
|
|
} scan_type;
|
|
};
|
|
|
|
The driver implementing the accelerometer described above will have the
|
|
following channel definition::
|
|
|
|
struct struct iio_chan_spec accel_channels[] = {
|
|
{
|
|
.type = IIO_ACCEL,
|
|
.modified = 1,
|
|
.channel2 = IIO_MOD_X,
|
|
/* other stuff here */
|
|
.scan_index = 0,
|
|
.scan_type = {
|
|
.sign = 's',
|
|
.realbits = 12,
|
|
.storagebits = 16,
|
|
.shift = 4,
|
|
.endianness = IIO_LE,
|
|
},
|
|
}
|
|
/* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1)
|
|
* and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis
|
|
*/
|
|
}
|
|
|
|
Here **scan_index** defines the order in which the enabled channels are placed
|
|
inside the buffer. Channels with a lower **scan_index** will be placed before
|
|
channels with a higher index. Each channel needs to have a unique
|
|
**scan_index**.
|
|
|
|
Setting **scan_index** to -1 can be used to indicate that the specific channel
|
|
does not support buffered capture. In this case no entries will be created for
|
|
the channel in the scan_elements directory.
|
|
|
|
More details
|
|
============
|
|
.. kernel-doc:: include/linux/iio/buffer.h
|
|
.. kernel-doc:: drivers/iio/industrialio-buffer.c
|
|
:export:
|
|
|