core.rst 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182
  1. =============
  2. Core elements
  3. =============
  4. The Industrial I/O core offers both a unified framework for writing drivers for
  5. many different types of embedded sensors and a standard interface to user space
  6. applications manipulating sensors. The implementation can be found under
  7. :file:`drivers/iio/industrialio-*`
  8. Industrial I/O Devices
  9. ----------------------
  10. * struct iio_dev - industrial I/O device
  11. * iio_device_alloc() - allocate an :c:type:`iio_dev` from a driver
  12. * iio_device_free() - free an :c:type:`iio_dev` from a driver
  13. * iio_device_register() - register a device with the IIO subsystem
  14. * iio_device_unregister() - unregister a device from the IIO
  15. subsystem
  16. An IIO device usually corresponds to a single hardware sensor and it
  17. provides all the information needed by a driver handling a device.
  18. Let's first have a look at the functionality embedded in an IIO device
  19. then we will show how a device driver makes use of an IIO device.
  20. There are two ways for a user space application to interact with an IIO driver.
  21. 1. :file:`/sys/bus/iio/iio:device{X}/`, this represents a hardware sensor
  22. and groups together the data channels of the same chip.
  23. 2. :file:`/dev/iio:device{X}`, character device node interface used for
  24. buffered data transfer and for events information retrieval.
  25. A typical IIO driver will register itself as an :doc:`I2C <../i2c>` or
  26. :doc:`SPI <../spi>` driver and will create two routines, probe and remove.
  27. At probe:
  28. 1. Call iio_device_alloc(), which allocates memory for an IIO device.
  29. 2. Initialize IIO device fields with driver specific information (e.g.
  30. device name, device channels).
  31. 3. Call iio_device_register(), this registers the device with the
  32. IIO core. After this call the device is ready to accept requests from user
  33. space applications.
  34. At remove, we free the resources allocated in probe in reverse order:
  35. 1. iio_device_unregister(), unregister the device from the IIO core.
  36. 2. iio_device_free(), free the memory allocated for the IIO device.
  37. IIO device sysfs interface
  38. ==========================
  39. Attributes are sysfs files used to expose chip info and also allowing
  40. applications to set various configuration parameters. For device with
  41. index X, attributes can be found under /sys/bus/iio/iio:deviceX/ directory.
  42. Common attributes are:
  43. * :file:`name`, description of the physical chip.
  44. * :file:`dev`, shows the major:minor pair associated with
  45. :file:`/dev/iio:deviceX` node.
  46. * :file:`sampling_frequency_available`, available discrete set of sampling
  47. frequency values for device.
  48. * Available standard attributes for IIO devices are described in the
  49. :file:`Documentation/ABI/testing/sysfs-bus-iio` file in the Linux kernel
  50. sources.
  51. IIO device channels
  52. ===================
  53. struct iio_chan_spec - specification of a single channel
  54. An IIO device channel is a representation of a data channel. An IIO device can
  55. have one or multiple channels. For example:
  56. * a thermometer sensor has one channel representing the temperature measurement.
  57. * a light sensor with two channels indicating the measurements in the visible
  58. and infrared spectrum.
  59. * an accelerometer can have up to 3 channels representing acceleration on X, Y
  60. and Z axes.
  61. An IIO channel is described by the struct iio_chan_spec.
  62. A thermometer driver for the temperature sensor in the example above would
  63. have to describe its channel as follows::
  64. static const struct iio_chan_spec temp_channel[] = {
  65. {
  66. .type = IIO_TEMP,
  67. .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),
  68. },
  69. };
  70. Channel sysfs attributes exposed to userspace are specified in the form of
  71. bitmasks. Depending on their shared info, attributes can be set in one of the
  72. following masks:
  73. * **info_mask_separate**, attributes will be specific to
  74. this channel
  75. * **info_mask_shared_by_type**, attributes are shared by all channels of the
  76. same type
  77. * **info_mask_shared_by_dir**, attributes are shared by all channels of the same
  78. direction
  79. * **info_mask_shared_by_all**, attributes are shared by all channels
  80. When there are multiple data channels per channel type we have two ways to
  81. distinguish between them:
  82. * set **.modified** field of :c:type:`iio_chan_spec` to 1. Modifiers are
  83. specified using **.channel2** field of the same :c:type:`iio_chan_spec`
  84. structure and are used to indicate a physically unique characteristic of the
  85. channel such as its direction or spectral response. For example, a light
  86. sensor can have two channels, one for infrared light and one for both
  87. infrared and visible light.
  88. * set **.indexed** field of :c:type:`iio_chan_spec` to 1. In this case the
  89. channel is simply another instance with an index specified by the **.channel**
  90. field.
  91. Here is how we can make use of the channel's modifiers::
  92. static const struct iio_chan_spec light_channels[] = {
  93. {
  94. .type = IIO_INTENSITY,
  95. .modified = 1,
  96. .channel2 = IIO_MOD_LIGHT_IR,
  97. .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
  98. .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
  99. },
  100. {
  101. .type = IIO_INTENSITY,
  102. .modified = 1,
  103. .channel2 = IIO_MOD_LIGHT_BOTH,
  104. .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
  105. .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
  106. },
  107. {
  108. .type = IIO_LIGHT,
  109. .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),
  110. .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
  111. },
  112. }
  113. This channel's definition will generate two separate sysfs files for raw data
  114. retrieval:
  115. * :file:`/sys/bus/iio/iio:device{X}/in_intensity_ir_raw`
  116. * :file:`/sys/bus/iio/iio:device{X}/in_intensity_both_raw`
  117. one file for processed data:
  118. * :file:`/sys/bus/iio/iio:device{X}/in_illuminance_input`
  119. and one shared sysfs file for sampling frequency:
  120. * :file:`/sys/bus/iio/iio:device{X}/sampling_frequency`.
  121. Here is how we can make use of the channel's indexing::
  122. static const struct iio_chan_spec light_channels[] = {
  123. {
  124. .type = IIO_VOLTAGE,
  125. .indexed = 1,
  126. .channel = 0,
  127. .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
  128. },
  129. {
  130. .type = IIO_VOLTAGE,
  131. .indexed = 1,
  132. .channel = 1,
  133. .info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
  134. },
  135. }
  136. This will generate two separate attributes files for raw data retrieval:
  137. * :file:`/sys/bus/iio/devices/iio:device{X}/in_voltage0_raw`, representing
  138. voltage measurement for channel 0.
  139. * :file:`/sys/bus/iio/devices/iio:device{X}/in_voltage1_raw`, representing
  140. voltage measurement for channel 1.
  141. More details
  142. ============
  143. .. kernel-doc:: include/linux/iio/iio.h
  144. .. kernel-doc:: drivers/iio/industrialio-core.c
  145. :export: