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