buffers.rst 4.4 KB

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