Registered User mNo edit summary |
Registered User No edit summary |
||
(17 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
{{ApplicableFor | |||
|MPUs list=STM32MP13x, STM32MP15x, STM32MP21x, STM32MP23x, STM32MP25x | |||
|MPUs checklist=STM32MP13x, STM32MP15x, STM32MP21x, STM32MP23x, STM32MP25x | |||
}} | |||
<noinclude> | |||
</noinclude> | |||
This article gives information about the Linux<sup>®</sup> IIO framework.<br /> | This article gives information about the Linux<sup>®</sup> IIO framework.<br /> | ||
It explains how to activate the IIO interface and, based on examples, how to use it.<br /> | It explains how to activate the IIO interface and, based on examples, how to use it.<br /> | ||
Line 21: | Line 28: | ||
IIO can be used in many different use cases, as mentioned in [[#How to use the framework|How to use the framework]] section: | IIO can be used in many different use cases, as mentioned in [[#How to use the framework|How to use the framework]] section: | ||
* Low speed acquisition for slow varying input signal (example: log temperature to a file) | * Low speed acquisition for slow varying input signal (example: log temperature to a file) | ||
* High speed acquisition using [[ADC internal peripheral|ADC]], [[DFSDM internal peripheral|DFSDM]] or external devices (example: audio, power meter) | * High speed acquisition using [[ADC internal peripheral|ADC]], [[DFSDM internal peripheral|DFSDM]] ({{MicroprocessorDevice | device=1}}), [[MDF internal peripheral|MDF]] ({{MicroprocessorDevice | device=2}}), or external devices (example: audio, power meter) | ||
* Read the position of a rotary element using [[TIM internal peripheral|TIM]] or [[LPTIM internal peripheral|LPTIM]] quadrature encoder interface | * Read the position of a rotary element using [[TIM internal peripheral|TIM]] or [[LPTIM internal peripheral|LPTIM]] quadrature encoder interface | ||
* Driving an analog source through a [[DAC internal peripheral|DAC]] | * Driving an analog source through a [[DAC internal peripheral|DAC]] | ||
Line 30: | Line 37: | ||
{{ | {{ | ||
ImageMap|Image:IIO-overview.png {{!}} frame {{!}} center{{!}} IIO Implementation architecture | ImageMap|Image:IIO-overview.png {{!}} frame {{!}} center{{!}} IIO Implementation architecture | ||
rect | rect 343 128 465 161 [[IIO libiio|libiio]] | ||
rect | rect 832 183 954 216 [[IIO libiio|libiio]] | ||
rect | rect 271 273 585 311 [[#User_space_interface|User space interface]] | ||
rect | rect 617 369 744 400 [[#Kernel_space_interface|Kernel space interface]] | ||
rect | rect 588 308 701 364 [[#How_to_use_IIO_kernel_API|Kernel space user]] | ||
rect | rect 214 494 309 534 [[DAC Linux driver]] | ||
rect | rect 322 494 417 534 [[ADC OpenSTLinux drivers]] | ||
rect | rect 429 494 525 515 [[DFSDM Linux driver]] | ||
rect 534 | rect 429 515 525 535 [[MDF Linux driver]] | ||
rect | rect 537 494 634 534 [[How to use the IIO user space interface#How to set up a TIM or LPTIM trigger using the sysfs interface | IIO timers triggers]] | ||
rect | rect 647 494 740 534 [[#How to write a kernel IIO device driver | kernel IIO device driver]] | ||
rect | rect 214 582 309 622 [[DAC internal peripheral]] | ||
rect | rect 322 582 417 622 [[ADC internal peripheral]] | ||
rect 537 582 634 622 [[:Category:Timers peripherals|Timer internal peripherals]] | |||
rect | rect 647 582 740 622 [[:Category:Low speed interface peripherals|I2C or SPI internal peripherals]] | ||
rect 431 583 526 604 [[DFSDM internal peripheral]] | |||
rect 431 604 526 622 [[MDF internal peripheral]] | |||
}} | }} | ||
Line 59: | Line 68: | ||
* '''User Space interface''': It is composed of a standard '''char device''', '''sysfs''', '''configfs''' and [[Debugfs|debugfs]] (see [[#API description|API description]]). | * '''User Space interface''': It is composed of a standard '''char device''', '''sysfs''', '''configfs''' and [[Debugfs|debugfs]] (see [[#API description|API description]]). | ||
* '''Kernel Space user''': It can be any kernel space IIO consumer, like STM32 DFSDM audio driver or IIO hwmon driver (See [[#How_to_use_IIO_kernel_API|How to use IIO kernel API]]). | * '''Kernel Space user''': It can be any kernel space IIO consumer, like STM32 DFSDM ({{MicroprocessorDevice | device=1}}) audio driver, STM32 MDF ({{MicroprocessorDevice | device=2}}) audio driver or IIO hwmon driver (See [[#How_to_use_IIO_kernel_API|How to use IIO kernel API]]). | ||
* '''Kernel Space interface''': It is composed of a standard [[#Kernel space interface|API]] | * '''Kernel Space interface''': It is composed of a standard [[#Kernel space interface|API]] | ||
Line 65: | Line 74: | ||
* '''IIO framework''' (Kernel Space): It's composed of a core. It manages data buffers, userspace events, triggers. It also handles clients (either in kernel or in User Space). | * '''IIO framework''' (Kernel Space): It's composed of a core. It manages data buffers, userspace events, triggers. It also handles clients (either in kernel or in User Space). | ||
* '''IIO drivers''' (Kernel Space): Linux kernel drivers to handle internal peripherals or external devices. They includes an interface that provides controls and data to the user (examples: [[ADC Linux driver]], [[ | * '''IIO drivers''' (Kernel Space): Linux kernel drivers to handle internal peripherals or external devices. They includes an interface that provides controls and data to the user (examples: [[ADC OpenSTLinux drivers]], [[DAC Linux driver]], [[DFSDM Linux driver]] ({{MicroprocessorDevice | device=1}}), [[MDF Linux driver]] ({{MicroprocessorDevice | device=2}}), [[TIM Linux driver]], [[LPTIM Linux driver]], [[#How to write a kernel IIO device driver | IIO device driver]] connected on [[SPI overview| SPI]] or [[I2C overview | I2C]]). | ||
* '''STM32 peripherals''' (Hardware): connected to the external devices through a specific interface (examples: [[ADC internal peripheral|ADC]], [[DAC internal peripheral|DAC]], [[DFSDM internal peripheral| DFSDM ]], [[TIM internal peripheral|TIM]], [[LPTIM internal peripheral|LPTIM]], [[SPI internal peripheral| SPI]], or [[I2C internal peripheral| I2C]]) | * '''STM32 peripherals''' (Hardware): connected to the external devices through a specific interface (examples: [[ADC internal peripheral|ADC]], [[DAC internal peripheral|DAC]], [[DFSDM internal peripheral| DFSDM ]] ({{MicroprocessorDevice | device=1}}), [[MDF internal peripheral| MDF ]] ({{MicroprocessorDevice | device=2}}), [[TIM internal peripheral|TIM]], [[LPTIM internal peripheral|LPTIM]], [[SPI internal peripheral| SPI]], or [[I2C internal peripheral| I2C]]) | ||
* '''External devices''' (Hardware): connected to the STM32 front-end through a specific interface. These can be analog devices (such as accelerometers, Inertial Measurement Units...), a Sigma Delta ADC Modulator (for audio record, energy measurements...), IIO devices on SPI or I2C... | * '''External devices''' (Hardware): connected to the STM32 front-end through a specific interface. These can be analog devices (such as accelerometers, Inertial Measurement Units...), a Sigma Delta ADC Modulator (for audio record, energy measurements...), IIO devices on SPI or I2C... | ||
Line 81: | Line 90: | ||
==== User space interface ==== | ==== User space interface ==== | ||
The IIO framework provides several interfaces: | The IIO framework provides several interfaces: | ||
* | * {{DocSource | domain=Linux kernel | path=driver-api/iio/core.html#iio-device-sysfs-interface | text='''iio device sysfs interface'''}}: It is used to '''configure which events and data''' should come out of the character device, e.g. ''/sys/bus/iio/devices/iio:deviceX''.<br/> It can be used to '''read''' (poll) or '''write data''' directly '''at low rates'''.<br/>The IIO sysfs ABI is documented in: ''Documentation/ABI/testing/sysfs-bus-iio''<ref>[https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-bus-iio sysfs-bus-iio ABI], Linux standard sysfs IIO interface</ref>.<br/>See [[How to use the IIO user space interface]] and [[How to access information in sysfs]] for further details. | ||
* '''character device'''<ref>[https://bootlin.com/doc/training/linux-kernel/linux-kernel-slides.pdf character device interface], ''Linux Kernel and Driver Development'' training document, see '''Character drivers''' and '''Kernel frameworks for device drivers''' chapter</ref>: It is optional in IIO. It is used to output '''events and sensor data''', e.g. ''/dev/iio:deviceX''.<br/> It is basically a file from application point of view. Standard file API allows to access it: open(), read(), write(), close()...<br/> See [[How to use the IIO user space interface#Convert one or more channels using triggered buffer mode|How to use triggered buffer mode]] and | * '''character device'''<ref>[https://bootlin.com/doc/training/linux-kernel/linux-kernel-slides.pdf character device interface], ''Linux Kernel and Driver Development'' training document, see '''Character drivers''' and '''Kernel frameworks for device drivers''' chapter</ref>: It is optional in IIO. It is used to output '''events and sensor data''', e.g. ''/dev/iio:deviceX''.<br/> It is basically a file from application point of view. Standard file API allows to access it: open(), read(), write(), close()...<br/> See [[How to use the IIO user space interface#Convert one or more channels using triggered buffer mode|How to use triggered buffer mode]] and {{DocSource | domain=Linux kernel | path=driver-api/iio/buffers.html#iio-buffer-sysfs-interface | text=The Linux driver implementer’s API guide - Industrial I/O Buffers}} for further details. | ||
* '''configfs''': It allows to configure additional IIO features like ''software and hrtimer triggers''.<br/>The IIO configfs interface is documented in: ''Documentation/ABI/testing/configfs-iio''<ref>[https://www.kernel.org/doc/Documentation/ABI/testing/configfs-iio configfs-iio ABI], Linux standard configfs IIO interface</ref> and ''Documentation/iio/iio_configfs.txt''<ref>[https://www.kernel.org/doc/Documentation/iio/iio_configfs.txt iio_configfs interface], Linux standard configfs interface</ref>.<br/>Note: STM32 already provides ''hardware triggers'' (See [[How_to_use_the_IIO_user_space_interface#How_to_set_up_a_TIM_or_LPTIM_trigger_using_the_sysfs_interface|How to use the IIO timers triggers]]). | * '''configfs''': It allows to configure additional IIO features like ''software and hrtimer triggers''.<br/>The IIO configfs interface is documented in: ''Documentation/ABI/testing/configfs-iio''<ref>[https://www.kernel.org/doc/Documentation/ABI/testing/configfs-iio configfs-iio ABI], Linux standard configfs IIO interface</ref> and ''Documentation/iio/iio_configfs.txt''<ref>[https://www.kernel.org/doc/Documentation/iio/iio_configfs.txt iio_configfs interface], Linux standard configfs interface</ref>.<br/>Note: STM32 already provides ''hardware triggers'' (See [[How_to_use_the_IIO_user_space_interface#How_to_set_up_a_TIM_or_LPTIM_trigger_using_the_sysfs_interface|How to use the IIO timers triggers]]). | ||
Line 139: | Line 148: | ||
IIO supports several types of sensors and devices. User can select from there any driver among the supported devices. | IIO supports several types of sensors and devices. User can select from there any driver among the supported devices. | ||
Please refer to [[ADC Linux driver]], [[ | Please refer to [[ADC OpenSTLinux drivers]], [[DAC Linux driver]], [[DFSDM Linux driver]] ({{MicroprocessorDevice | device=1}}), [[MDF Linux driver]] ({{MicroprocessorDevice | device=2}}), [[TIM Linux driver]], [[LPTIM Linux driver]] articles for each peripheral. | ||
===Device tree configuration=== | ===Device tree configuration=== | ||
''IIO bindings''<ref name="IIO bindings"> | ''IIO bindings'' <ref name="IIO bindings">https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/iio/iio.yaml, Linux Foundation, IIO Generic DT bindings</ref> documentation deals with all required or optional IIO generic DT properties. | ||
It also introduces '''IIO providers''' and '''IIO consumers'''.<br> | It also introduces '''IIO providers''' and '''IIO consumers''' <ref name="IIO consumers">https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/iio/iio-consumer.yaml, Linux Foundation, IIO Consumer DT bindings</ref>.<br> | ||
Example with STM32 ADC: | Example with STM32 ADC: | ||
Line 151: | Line 160: | ||
... | ... | ||
#io-channel-cells = <1>; | #io-channel-cells = <1>; | ||
channel@12 { | |||
reg = <{{highlight|12}}>; {{highlight|/* channel 12 in use */}} | |||
}; | |||
}; | }; | ||
}; | }; | ||
Line 169: | Line 180: | ||
* [[ADC device tree configuration]] | * [[ADC device tree configuration]] | ||
* [[DAC device tree configuration]] | * [[DAC device tree configuration]] | ||
* [[DFSDM device tree configuration]] | * [[DFSDM device tree configuration]] ({{MicroprocessorDevice | device=1}}) | ||
* [[MDF device tree configuration]] ({{MicroprocessorDevice | device=2}}) | |||
* [[TIM device tree configuration]] | * [[TIM device tree configuration]] | ||
* [[LPTIM device tree configuration]] | * [[LPTIM device tree configuration]] | ||
Linux kernel provides many other supported devices<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/iio | Kernel DT documentation IIO bindings}}, Linux Foundation, IIO DT bindings documents included in the Kernel sources</ref> in '''Documentation/devicetree/bindings/iio''' directory. | Linux kernel provides many other supported devices<ref>{{CodeSource | Linux kernel | Documentation/devicetree/bindings/iio/ | Kernel DT documentation IIO bindings}}, Linux Foundation, IIO DT bindings documents included in the Kernel sources</ref> in '''Documentation/devicetree/bindings/iio''' directory. | ||
== How to use the framework == | == How to use the framework == | ||
Line 186: | Line 198: | ||
* How to setup a trigger source: [[How to use the IIO user space interface#How to set up a TIM or LPTIM trigger using the sysfs interface|How to set up a TIM or LPTIM trigger using the sysfs interface]] | * How to setup a trigger source: [[How to use the IIO user space interface#How to set up a TIM or LPTIM trigger using the sysfs interface|How to set up a TIM or LPTIM trigger using the sysfs interface]] | ||
* How to use a trigger source: [[How to use the IIO user space interface#How to perform multiple ADC conversions in triggered buffer mode|How to perform multiple ADC conversions in triggered buffer mode]] | * How to use a trigger source: [[How to use the IIO user space interface#How to perform multiple ADC conversions in triggered buffer mode|How to perform multiple ADC conversions in triggered buffer mode]] | ||
* How to use quadrature encoder: [[How to use the IIO user space interface#How to use the quadrature encoder with the sysfs interface|How to use the quadrature encoder with the sysfs interface]] | * How to use quadrature encoder: [[How to use the IIO user space interface#How to use the quadrature encoder with the sysfs interface|How to use the quadrature encoder with the sysfs interface]] | ||
=== How to use IIO kernel API === | === How to use IIO kernel API === | ||
Several in-kernel drivers use [[#Kernel_space_interface|kernel IIO API]]. See HWMON client example for IIO devices, and STM32 DFSDM audio ALSA IIO client: | Several in-kernel drivers use [[#Kernel_space_interface|kernel IIO API]]. See HWMON client example for IIO devices, and STM32 DFSDM ({{MicroprocessorDevice | device=1}}) or STM32 MDF ({{MicroprocessorDevice | device=2}}) audio ALSA IIO client: | ||
* iio_hwmon: ''drivers/hwmon/iio_hwmon.c''<ref name="iio_hwmon"/>. See also [[#Device Tree configuration|device tree configuration]] example to read voltage from ADC. | * iio_hwmon: ''drivers/hwmon/iio_hwmon.c''<ref name="iio_hwmon"/>. See also [[#Device Tree configuration|device tree configuration]] example to read voltage from ADC. | ||
$ cat /sys/class/hwmon/hwmon0/in1_input | $ cat /sys/class/hwmon/hwmon0/in1_input | ||
1809 # '''iio_hwmon''' calls '''iio_read_channel_processed()''': ADC result is in mV. | 1809 # '''iio_hwmon''' calls '''iio_read_channel_processed()''': ADC result is in mV. | ||
* stm32-adfsdm: See [[DFSDM Linux driver]] and [[ALSA overview]] for further details | * stm32-adfsdm ({{MicroprocessorDevice | device=1}}): See [[DFSDM Linux driver]] and [[ALSA overview]] for further details | ||
* stm32-amdf ({{MicroprocessorDevice | device=2}}): See [[MDF Linux driver]] and [[ALSA overview]] for further details | |||
==How to trace and debug the framework== | ==How to trace and debug the framework== | ||
Line 200: | Line 212: | ||
=== How to trace with dynamic debug === | === How to trace with dynamic debug === | ||
By default there is no kernel log that shows activity on IIO. However the user could enable dynamic debug for the IIO core and the IIO drivers. | By default there is no kernel log that shows activity on IIO. However the user could enable dynamic debug for the IIO core and the IIO drivers. | ||
{{Board$}} dmesg -n8 | {{Board$}}dmesg -n8 | ||
{{Board$}} echo "file drivers/iio/* +p" > /sys/kernel/debug/dynamic_debug/control | {{Board$}}echo "file drivers/iio/* +p" > /sys/kernel/debug/dynamic_debug/control | ||
{{Board$}} echo "file drivers/iio/adc/* +p" > /sys/kernel/debug/dynamic_debug/control | {{Board$}}echo "file drivers/iio/adc/* +p" > /sys/kernel/debug/dynamic_debug/control | ||
{{Board$}} echo "file drivers/iio/dac/* +p" > /sys/kernel/debug/dynamic_debug/control | {{Board$}}echo "file drivers/iio/dac/* +p" > /sys/kernel/debug/dynamic_debug/control | ||
See [[How to use the kernel dynamic debug|dynamic debug]] for more details. | See [[How to use the kernel dynamic debug|dynamic debug]] for more details. | ||
Line 223: | Line 235: | ||
The Linux Kernel community provides all the documents needed to develop an IIO device driver : | The Linux Kernel community provides all the documents needed to develop an IIO device driver : | ||
* The Linux driver implementer’s API guide - Industrial I/O<ref> | * The Linux driver implementer’s API guide - Industrial I/O<ref>{{DocSource | domain=Linux kernel | path=driver-api/iio/index.html | text=Industrial I/O}}, The Linux driver implementer’s API guide</ref>: This guide provides the API provided by kernel IIO core components. | ||
* IIO staging documentation<ref>{{CodeSource | Linux kernel | drivers/staging/iio/Documentation | IIO staging documentation}}, Linux Foundation, IIO documents included in the Kernel sources</ref>, included in the Kernel sources ('''drivers/staging/iio/Documentation'''). | * IIO staging documentation<ref>{{CodeSource | Linux kernel | drivers/staging/iio/Documentation/ | IIO staging documentation}}, Linux Foundation, IIO documents included in the Kernel sources</ref>, included in the Kernel sources ('''drivers/staging/iio/Documentation'''). | ||
* Linux Kernel IIO dummy driver example source code<ref>{{CodeSource | Linux kernel | drivers/iio/dummy/iio_simple_dummy.c}}, Linux Foundation, IIO dummy driver example source code</ref>: Dummy driver source code, included in the kernel sources ('''drivers/iio/dummy/iio_simple_dummy.c'''). | * Linux Kernel IIO dummy driver example source code<ref>{{CodeSource | Linux kernel | drivers/iio/dummy/iio_simple_dummy.c}}, Linux Foundation, IIO dummy driver example source code</ref>: Dummy driver source code, included in the kernel sources ('''drivers/iio/dummy/iio_simple_dummy.c'''). | ||
===Trainings documents=== | ===Trainings documents=== | ||
* IIO a new subsystem<ref>[https://archive.fosdem.org/2012/schedule/event/693/127_iio-a-new-subsystem.pdf IIO a new subsystem], Free Electrons, Presentation of Kernel IIO subsystem</ref> : Presentation of Kernel IIO subsystem | * IIO a new subsystem<ref>[https://archive.fosdem.org/2012/schedule/event/693/127_iio-a-new-subsystem.pdf IIO a new subsystem], Free Electrons, Presentation of Kernel IIO subsystem</ref> : Presentation of Kernel IIO subsystem | ||
* Industrial I/O Subsystem: The Home of Linux Sensors<ref>[ | * Industrial I/O Subsystem: The Home of Linux Sensors<ref>[https://events.static.linuxfound.org/sites/events/files/slides/lceu15_baluta.pdf Industrial I/O Subsystem: The Home of Linux Sensors], Linux Foundation, IIO training</ref>: Why IIO? What is it? Sensor types... | ||
* Software Defined Radio using the Linux Industrial IO framework<ref>[https://archive.fosdem.org/2015/schedule/event/iiosdr/attachments/slides/708/export/events/attachments/iiosdr/slides/708/fosdem_2015_iio_sdr.pdf Software Defined Radio using the Linux Industrial IO framework], Linux Foundation, User Guide describing how to implement an application by using Linux Industrial IO framework</ref> : User Guide describing how to implement an application by using Linux Industrial IO framework | * Software Defined Radio using the Linux Industrial IO framework<ref>[https://archive.fosdem.org/2015/schedule/event/iiosdr/attachments/slides/708/export/events/attachments/iiosdr/slides/708/fosdem_2015_iio_sdr.pdf Software Defined Radio using the Linux Industrial IO framework], Linux Foundation, User Guide describing how to implement an application by using Linux Industrial IO framework</ref> : User Guide describing how to implement an application by using Linux Industrial IO framework | ||
* Linux Device Drivers, Third Edition<ref>[https://lwn.net/Kernel/LDD3/ Linux Device Drivers, Third Edition], Pdf book, Authors Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman </ref> : Reference book for linux device drivers development, for IIO see Chapter 3, Char Drivers. | * Linux Device Drivers, Third Edition<ref>[https://lwn.net/Kernel/LDD3/ Linux Device Drivers, Third Edition], Pdf book, Authors Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman </ref> : Reference book for linux device drivers development, for IIO see Chapter 3, Char Drivers. |
Latest revision as of 13:40, 23 October 2024
This article gives information about the Linux® IIO framework.
It explains how to activate the IIO interface and, based on examples, how to use it.
1. Framework purpose[edit | edit source]
IIO (Industrial I/O) is a subsystem for Analog to Digital Converters (ADCs), Digital to Analog Converters (DACs) and various types of sensors. It can be used on high speed, high data rates industrial devices. Until recently, it was mostly focused on user-space abstraction. It also includes in-kernel API for other drivers.
The Industrial I/O Linux® subsystem offers a unified framework to communicate (read and write) with drivers covering many different types of embedded sensors and a few actuators. It also offers a standard interface to user space applications manipulating sensors through sysfs and devfs.
Here are some examples of supported sensor types in IIO:
- ADC / DAC
- accelerometers
- magnetometers
- gyroscopes
- pressure
- humidity
- temperature
- light and proximity
IIO can be used in many different use cases, as mentioned in How to use the framework section:
- Low speed acquisition for slow varying input signal (example: log temperature to a file)
- High speed acquisition using ADC, DFSDM (STM32MP1 series), MDF (STM32MP2 series), or external devices (example: audio, power meter)
- Read the position of a rotary element using TIM or LPTIM quadrature encoder interface
- Driving an analog source through a DAC
- External devices connected via SPI or I2C.
2. System overview[edit | edit source]
2.1. Components description[edit | edit source]
From client application to hardware
- Client Application (User Space): An application that configures, read or write data samples to/from IIO device(s) via libiio.
- iiod server (User Space): It is optional. Applications based on libiio can benefit from a remote access via IIO Daemon server, to IIO "local" backend through a network link.
- libiio (User Space): libiio is a complete library offering an API for developping an application. It's composed of a high-level API, and two backends:
- The “local” backend, interfacing with the Linux kernel through the IIO API
- The “network” backend, interfacing with the iiod server through a network link.
- User Space interface: It is composed of a standard char device, sysfs, configfs and debugfs (see API description).
- Kernel Space user: It can be any kernel space IIO consumer, like STM32 DFSDM (STM32MP1 series) audio driver, STM32 MDF (STM32MP2 series) audio driver or IIO hwmon driver (See How to use IIO kernel API).
- Kernel Space interface: It is composed of a standard API
- IIO framework (Kernel Space): It's composed of a core. It manages data buffers, userspace events, triggers. It also handles clients (either in kernel or in User Space).
- IIO drivers (Kernel Space): Linux kernel drivers to handle internal peripherals or external devices. They includes an interface that provides controls and data to the user (examples: ADC OpenSTLinux drivers, DAC Linux driver, DFSDM Linux driver (STM32MP1 series), MDF Linux driver (STM32MP2 series), TIM Linux driver, LPTIM Linux driver, IIO device driver connected on SPI or I2C).
- STM32 peripherals (Hardware): connected to the external devices through a specific interface (examples: ADC, DAC, DFSDM (STM32MP1 series), MDF (STM32MP2 series), TIM, LPTIM, SPI, or I2C)
- External devices (Hardware): connected to the STM32 front-end through a specific interface. These can be analog devices (such as accelerometers, Inertial Measurement Units...), a Sigma Delta ADC Modulator (for audio record, energy measurements...), IIO devices on SPI or I2C...
2.2. API description[edit | edit source]
Depending on needs and location (Kernel Space or User Space), several APIs are available to control an IIO device.
2.2.1. libiio[edit | edit source]
Libiio provides a user space high-level API for client applications[1]. The library abstracts the low-level details of the hardware, and provides a simple yet complete programming interface that can be used for advanced projects.
It is a wrapper on the user space interface (sysfs and char device) provided by the kernel.
2.2.2. User space interface[edit | edit source]
The IIO framework provides several interfaces:
- iio device sysfs interface: It is used to configure which events and data should come out of the character device, e.g. /sys/bus/iio/devices/iio:deviceX.
It can be used to read (poll) or write data directly at low rates.
The IIO sysfs ABI is documented in: Documentation/ABI/testing/sysfs-bus-iio[2].
See How to use the IIO user space interface and How to access information in sysfs for further details.
- character device[3]: It is optional in IIO. It is used to output events and sensor data, e.g. /dev/iio:deviceX.
It is basically a file from application point of view. Standard file API allows to access it: open(), read(), write(), close()...
See How to use triggered buffer mode and The Linux driver implementer’s API guide - Industrial I/O Buffers for further details.
- configfs: It allows to configure additional IIO features like software and hrtimer triggers.
The IIO configfs interface is documented in: Documentation/ABI/testing/configfs-iio[4] and Documentation/iio/iio_configfs.txt[5].
Note: STM32 already provides hardware triggers (See How to use the IIO timers triggers).
- Debugfs: May provide some debug conveniences (like direct_reg_access entry to read/write registers) depending on the IIO device driver in use.
2.2.3. Kernel space interface[edit | edit source]
Useful kernel API for users:
- devm_iio_channel_get_all() or iio_channel_get_all() / iio_channel_release_all(): Used to lookup, get, then release IIO channels.
- iio_get_channel_type(): get the type of a channel, such as IIO_VOLTAGE, IIO_TEMP...
- iio_read_channel_processed(): read channel processed value, e.g. like in micro-volts for voltage, milli-degree for temperature...
- ...
Available routines can be found in kernel header file: include/linux/iio/consumer.h[6].
3. Configuration[edit | edit source]
3.1. Kernel configuration[edit | edit source]
IIO is activated by default in ST deliveries. Nevertheless, if a specific configuration is needed, this section indicates how IIO can be activated/deactivated in the kernel.
Activate IIO in kernel configuration with Linux Menuconfig tool: Menuconfig or how to configure kernel
IIO < > IIO callback buffer used for push in-kernel interfaces <*> Industrial I/O HW buffering <*> Industrial I/O buffering based on kfifo < > Enable IIO configuration via configfs [*] Enable triggered sampling support (2) Maximum number of consumers per trigger < > Enable software triggers support Accelerometers ---> Analog to digital converters ---> Amplifiers ---> Chemical Sensors ---> Hid Sensor IIO Common ---- SSP Sensor Common ---> Digital to analog converters ---> IIO dummy driver ---> Frequency Synthesizers DDS/PLL ---> Digital gyroscope sensors ---> Health Sensors ---> Humidity sensors ---> Inertial measurement units ---> Light sensors ---> Magnetometer sensors ---> Inclinometer sensors ---- Triggers - standalone ---> Digital potentiometers ---> Pressure sensors ---> Lightning sensors ---> Proximity sensors ---> Temperature sensors --->Device Drivers ---> <*> Industrial I/O support ---> [*] Enable buffer support within
IIO supports several types of sensors and devices. User can select from there any driver among the supported devices.
Please refer to ADC OpenSTLinux drivers, DAC Linux driver, DFSDM Linux driver (STM32MP1 series), MDF Linux driver (STM32MP2 series), TIM Linux driver, LPTIM Linux driver articles for each peripheral.
3.2. Device tree configuration[edit | edit source]
IIO bindings [7] documentation deals with all required or optional IIO generic DT properties.
It also introduces IIO providers and IIO consumers [8].
Example with STM32 ADC:
adc2: adc@100 { /* IIO provider example */ ... #io-channel-cells = <1>; channel@12 { reg = <12>; /* channel 12 in use */ }; }; }; / { consumer_device { /* IIO consumer example */ io-channels = <&adc2 12>; io-channel-names = "example"; /* IIO consumer driver side: devm_iio_channel_get(&dev, "example"); */ }; iio-hwmon { /* iio_hwmon[9] is another consumer example (See SENSORS_IIO_HWMON in kernel configuration) */ compatible = "iio-hwmon"; /* See Documentation/devicetree/bindings/iio/iio-bindings.txt[7] io-channels = <&adc2 12>; }; };&adc {
Detailed DT configuration for STM32 internal peripherals:
- ADC device tree configuration
- DAC device tree configuration
- DFSDM device tree configuration (STM32MP1 series)
- MDF device tree configuration (STM32MP2 series)
- TIM device tree configuration
- LPTIM device tree configuration
Linux kernel provides many other supported devices[10] in Documentation/devicetree/bindings/iio directory.
4. How to use the framework[edit | edit source]
This section describes how to use the IIO framework from:
- User space interface: Please refer to libiio and IIO Linux kernel tools that run on top of sysfs and character device (How to use the IIO user space interface)
- Kernel space interface: How to use IIO kernel API
4.1. How to use the IIO user space interface[edit | edit source]
Please see examples based on the following use cases:
- How to read a data: How to do a simple ADC conversion using the sysfs interface
- How to write a data: How to do a simple DAC conversion using the sysfs interface
- How to setup a trigger source: How to set up a TIM or LPTIM trigger using the sysfs interface
- How to use a trigger source: How to perform multiple ADC conversions in triggered buffer mode
- How to use quadrature encoder: How to use the quadrature encoder with the sysfs interface
4.2. How to use IIO kernel API[edit | edit source]
Several in-kernel drivers use kernel IIO API. See HWMON client example for IIO devices, and STM32 DFSDM (STM32MP1 series) or STM32 MDF (STM32MP2 series) audio ALSA IIO client:
- iio_hwmon: drivers/hwmon/iio_hwmon.c[9]. See also device tree configuration example to read voltage from ADC.
ADC result is in mV.$ cat /sys/class/hwmon/hwmon0/in1_input 1809 # iio_hwmon calls iio_read_channel_processed():
- stm32-adfsdm (STM32MP1 series): See DFSDM Linux driver and ALSA overview for further details
- stm32-amdf (STM32MP2 series): See MDF Linux driver and ALSA overview for further details
5. How to trace and debug the framework[edit | edit source]
5.1. How to trace with dynamic debug[edit | edit source]
By default there is no kernel log that shows activity on IIO. However the user could enable dynamic debug for the IIO core and the IIO drivers.
dmesg -n8
echo "file drivers/iio/* +p" > /sys/kernel/debug/dynamic_debug/control
echo "file drivers/iio/adc/* +p" > /sys/kernel/debug/dynamic_debug/control
echo "file drivers/iio/dac/* +p" > /sys/kernel/debug/dynamic_debug/control
See dynamic debug for more details.
5.2. How to debug with debugfs[edit | edit source]
IIO proposes an optional debugfs entry to access registers. It is up to the IIO device driver to implement it (e.g. debugfs_reg_access()). When it is available:
$ cd /sys/kernel/debug/iio/iio:deviceX
To read a register from the device:
$ echo [register offset] > direct_reg_access
$ cat direct_reg_access
0xhhhh # Register content
To write a register:
$ echo [register offset] [register value] > direct_reg_access
6. To go further[edit | edit source]
6.1. How to write a kernel IIO device driver[edit | edit source]
The Linux Kernel community provides all the documents needed to develop an IIO device driver :
- The Linux driver implementer’s API guide - Industrial I/O[11]: This guide provides the API provided by kernel IIO core components.
- IIO staging documentation[12], included in the Kernel sources (drivers/staging/iio/Documentation).
- Linux Kernel IIO dummy driver example source code[13]: Dummy driver source code, included in the kernel sources (drivers/iio/dummy/iio_simple_dummy.c).
6.2. Trainings documents[edit | edit source]
- IIO a new subsystem[14] : Presentation of Kernel IIO subsystem
- Industrial I/O Subsystem: The Home of Linux Sensors[15]: Why IIO? What is it? Sensor types...
- Software Defined Radio using the Linux Industrial IO framework[16] : User Guide describing how to implement an application by using Linux Industrial IO framework
- Linux Device Drivers, Third Edition[17] : Reference book for linux device drivers development, for IIO see Chapter 3, Char Drivers.
7. References[edit | edit source]
- ↑ libiio High-Level API, libiio API Documentation (Library for interfacing with IIO devices)
- ↑ sysfs-bus-iio ABI, Linux standard sysfs IIO interface
- ↑ character device interface, Linux Kernel and Driver Development training document, see Character drivers and Kernel frameworks for device drivers chapter
- ↑ configfs-iio ABI, Linux standard configfs IIO interface
- ↑ iio_configfs interface, Linux standard configfs interface
- ↑ include/linux/iio/consumer.h , IIO 'inkern' API
- ↑ Jump up to: 7.0 7.1 https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/iio/iio.yaml, Linux Foundation, IIO Generic DT bindings
- ↑ https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/iio/iio-consumer.yaml, Linux Foundation, IIO Consumer DT bindings
- ↑ Jump up to: 9.0 9.1 drivers/hwmon/iio_hwmon.c IIO HWMON, consumer driver example (kernel space)
- ↑ Kernel DT documentation IIO bindings , Linux Foundation, IIO DT bindings documents included in the Kernel sources
- ↑ Industrial I/O, The Linux driver implementer’s API guide
- ↑ IIO staging documentation , Linux Foundation, IIO documents included in the Kernel sources
- ↑ drivers/iio/dummy/iio_simple_dummy.c , Linux Foundation, IIO dummy driver example source code
- ↑ IIO a new subsystem, Free Electrons, Presentation of Kernel IIO subsystem
- ↑ Industrial I/O Subsystem: The Home of Linux Sensors, Linux Foundation, IIO training
- ↑ Software Defined Radio using the Linux Industrial IO framework, Linux Foundation, User Guide describing how to implement an application by using Linux Industrial IO framework
- ↑ Linux Device Drivers, Third Edition, Pdf book, Authors Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman