1. Purpose[edit | edit source]
The purpose of this article is to explain how to configure the GPIO internal peripheral through the GPIOLib framework when this peripheral is assigned to Linux® OS. The configuration is performed using the device tree[1].
To better understand I/O management, it is recommended to read the I/O pins overview article [2].
This article also provides an example explaining how to add a new GPIO in the device tree.
If the peripheral is assigned to another execution context, refer to How to assign an internal peripheral to an execution context article for guidelines on peripheral assignment and configuration.
2. DT bindings documentation[edit | edit source]
The STM32 GPIO bindings are composed of:
- Bindings for GPIO controller [3]
- Bindings for devices using a GPIO [4]
It is recommended to read these reference documents if you have never played with GPIO DT.
3. DT configuration[edit | edit source]
3.1. DT configuration (STM32 level)[edit | edit source]
The GPIO controller node (gpio controller) is located in the pin controller node that is declared Inside the SoC dtsi file:
- stm32mp131.dtsi[5] for STM32MP13x lines
. - stm32mp151.dtsi[6] for STM32MP15x lines .
- stm32mp211.dtsi[7] for STM32MP21x lines .
- stm32mp231.dtsi[8] for STM32MP23x lines .
- stm32mp251.dtsi[9] for STM32MP25x lines .
See Device tree for more explanations about device tree files split.
There is one gpio controller node per GPIO bank.
Refer to Pin controller configuration and to GPIO controller node bindings[3] for explanations on the gpio controller node.
3.2. DT configuration (board level)[edit | edit source]
Generic guidelines for adding a GPIO to a client device can be found in the document "GPIO bindings for board" [4].
- Below an example of basic GPIO usage extracted from "GPIO bindings for board" [4]:
GPIO mappings are defined in the consumer device node, through a property named <function>-gpios, where <function> is requested by the Linux driver through gpiod_get().
foo_device {
...
led-gpios = <&gpioa 15 GPIO_ACTIVE_HIGH>, /* red */
<&gpioa 16 GPIO_ACTIVE_HIGH>, /* green */
<&gpioa 17 GPIO_ACTIVE_HIGH>; /* blue */
power-gpios = <&gpiob 1 GPIO_ACTIVE_LOW>;
};
Where:
- - &gpiox: phandle on gpio-controller node.
- - 15: line offset in gpio-controller.
- - GPIO_ACTIVE_HIGH: flag to be used for the GPIO. The list of all available GPIO flags can be found in Linux kernel source code[10].
3.2.1. Secure GPIO configuration[edit | edit source]
GPIO banks may contain some specific secure settings. A peripheral set as secure MUST use secure GPIOs.
A specific binding is used in OP-TEE device tree to set the security at boot time, preventing non secure to use it, by defining the st,protreg property. It is defined at board level:
- For STM32MP1 series :
&gpiox {
--> pins 1 and 6 are configured as secure
st,protreg = <(TZPROT(1)|TZPROT(6))>;
};
- For STM32MP2 series :
&gpiox {
--> configure RIFSC for pin 0 and 1
st,protreg = <
RIFPROT(RIF_IOPORT_PIN(0), EMPTY_SEMWL, RIF_UNLOCK, RIF_NSEC, RIF_NPRIV, RIF_CID0, RIF_SEM_DIS, RIF_CFDIS)
RIFPROT(RIF_IOPORT_PIN(1), EMPTY_SEMWL, RIF_UNLOCK, RIF_NSEC, RIF_NPRIV, RIF_CID0, RIF_SEM_DIS, RIF_CFDIS)
[...]
>;
};
Where:
- - &gpiox: phandle on gpio-controller node.
- - TZPROT: Macro use to define the PIN number to be set as secure.
- - RIFPROT: Macro use to configure RIFSC. See RIFSC device tree bindings RIFSC bindings for more information.
3.3. DT configuration examples[edit | edit source]
3.3.1. How to add a GPIO dedicated to a device connected on the board[edit | edit source]
The example below shows how to add a GPIOB5 (PB5 on schematics) to a foo_device.
foo_device {
...
x-gpios = <&gpiob 5 (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>; /* x function */
...
};
Note: GPIO_ACTIVE_HIGH means that the GPIO line is driven by the logical level 1 (while GPIO_ACTIVE_LOW means that it is driven by the logical level 0). GPIO_PULL_UP means that the internal pull-up resistor is enabled.
4. How to configure GPIOs using STM32CubeMX[edit | edit source]
The STM32CubeMX tool can be used to configure the STM32MPU device and get the corresponding platform configuration device tree files.
The STM32CubeMX may not support all the properties described in the above DT bindings documentation paragraph. If so, the tool inserts user sections in the generated device tree. These sections can then be edited to add some properties and they are preserved from one generation to another. Refer to STM32CubeMX user manual for further information.
5. References[edit | edit source]
Please refer to the following links for additional information:
- ↑ Device tree, Device tree mechanism
- ↑ Overview of GPIO pins, Overview of GPIO pins article
- ↑ 3.0 3.1 Kernel device tree bindings documentation - gpio.txt, GPIO device tree bindings
- ↑ 4.0 4.1 4.2 GPIO bindings for board
- ↑ stm32mp131.dtsi , STM32MP131 device tree file
- ↑ stm32mp151.dtsi , STM32MP151 device tree file
- ↑ stm32mp211.dtsi , STM32MP211 device tree file
- ↑ stm32mp231.dtsi , STM32MP231 device tree file
- ↑ stm32mp251.dtsi , STM32MP251 device tree file
- ↑ include/dt-bindings/gpio/gpio.h
}}