^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) * struct iio_buffer — general buffer structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) * :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) is selected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) * :c:func:`iio_buffer_get` — Grab a reference to the buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) * :c:func:`iio_buffer_put` — Release the reference to the buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) The Industrial I/O core offers a way for continuous data capture based on a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) trigger source. Multiple data channels can be read at once from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) :file:`/dev/iio:device{X}` character device node, thus reducing the CPU load.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) IIO buffer sysfs interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) An IIO buffer has an associated attributes directory under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) :file:`/sys/bus/iio/iio:device{X}/buffer/*`. Here are some of the existing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) attributes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) * :file:`length`, the total number of data samples (capacity) that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) stored by the buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) * :file:`enable`, activate buffer capture.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) IIO buffer setup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) The meta information associated with a channel reading placed in a buffer is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) called a scan element. The important bits configuring scan elements are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) exposed to userspace applications via the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) :file:`/sys/bus/iio/iio:device{X}/scan_elements/*` directory. This file contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) attributes of the following form:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) * :file:`enable`, used for enabling a channel. If and only if its attribute
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) is non *zero*, then a triggered capture will contain data samples for this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) channel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) * :file:`type`, description of the scan element data storage within the buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) and hence the form in which it is read from user space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) * *be* or *le*, specifies big or little endian.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) * *s* or *u*, specifies if signed (2's complement) or unsigned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) * *bits*, is the number of valid data bits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) * *storagebits*, is the number of bits (after padding) that it occupies in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) * *shift*, if specified, is the shift that needs to be applied prior to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) masking out unused bits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) * *repeat*, specifies the number of bits/storagebits repetitions. When the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) repeat element is 0 or 1, then the repeat value is omitted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) For example, a driver for a 3-axis accelerometer with 12 bit resolution where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) data is stored in two 8-bits registers as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 7 6 5 4 3 2 1 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) +---+---+---+---+---+---+---+---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) +---+---+---+---+---+---+---+---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) 7 6 5 4 3 2 1 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) +---+---+---+---+---+---+---+---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) +---+---+---+---+---+---+---+---+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) will have the following scan element type for each axis::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) le:s12/16>>4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) A user space application will interpret data samples read from the buffer as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) two byte little endian signed data, that needs a 4 bits right shift before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) masking out the 12 valid bits of data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) For implementing buffer support a driver should initialize the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) fields in iio_chan_spec definition::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) struct iio_chan_spec {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) /* other members */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) int scan_index
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) char sign;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) u8 realbits;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) u8 storagebits;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) u8 shift;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) u8 repeat;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) enum iio_endian endianness;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) } scan_type;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) The driver implementing the accelerometer described above will have the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) following channel definition::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) struct iio_chan_spec accel_channels[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) .type = IIO_ACCEL,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) .modified = 1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) .channel2 = IIO_MOD_X,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) /* other stuff here */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) .scan_index = 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) .scan_type = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) .sign = 's',
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) .realbits = 12,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) .storagebits = 16,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) .shift = 4,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) .endianness = IIO_LE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) Here **scan_index** defines the order in which the enabled channels are placed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) inside the buffer. Channels with a lower **scan_index** will be placed before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) channels with a higher index. Each channel needs to have a unique
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) **scan_index**.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) Setting **scan_index** to -1 can be used to indicate that the specific channel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) does not support buffered capture. In this case no entries will be created for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) the channel in the scan_elements directory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) More details
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) .. kernel-doc:: include/linux/iio/buffer.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) .. kernel-doc:: drivers/iio/industrialio-buffer.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags