Topics

STM32: Moving devices pin configuration to device tree


Erwan Gouriou
 

TL;DR:
- Upcoming device tree based pin configuration for STM32 based boards
- Script generated, SoC package specific *-pinctrl.dtsi files are available in hal_stm32 modules
- Each *.pcintrl.dtsi file provides a complete set of valid pin configurations for targeted STM32
package
- Generation script is provided and can be used to generate new pin configuration variants (low
power, ...)
- One driver (STM32 serial) and two boards converted today as proof of concept
- Contributions are welcome to achieve deprecation of existing pinmux.c files within V2.5.0 
merge window


To all STM32 users and developers,

We're in the final step of reviewing PR #25996 "stm32: devices signals configuration from dt
This PR introduces the required material to enable device pin configuration using device tree.

With this method, device pin configuration should no longer be done in pinmux.c board file, but
in .dts file. For instance, to enable PB6 as TX and PB7 as RX on USART1, the following lines
should be added in .dts board file, in usart1 node:

 &usart1 {
        current-speed = <115200>;
+      pinctrl-0 = <&usart1_tx_pb6 &usart1_rx_pb7>;
+      pinctrl-names = "default";
        status = "okay";
 };

As a consequence, pin configuration can now be done at device driver level, opening the way
to dynamic pin configuration, which could be useful in various fields such as low power
management. Also, it provides flexibility in application configuration as pin configurations could
then be modified in using overlays.

Pin control nodes are defined using Linux pinctrl bindings. For instance, usart1_tx_pb6 is
defined as
+usart1_tx_pb6: usart1_tx_pb6 {
+       pinmux = <STM32_PINMUX('B', 6, AF7)>;
+       bias-pull-up;
+};

Definition of nodes usart1_tx_pb6 and usart1_rx_pb7 could be provided manually but to assist
in board configuration, SoC variant package specific -pinctrl.dtsi files are provided and should
be included in the board dts files.

For instance, for board disco_l475_iot1:
 #include <st/l4/stm32l475Xg.dtsi>
+#include <st/l4/stm32l475r(c-e-g)tx-pinctrl.dtsi>
 #include "arduino_r3_connector.dtsi"

*-pinctrl.dtsi files provide known working pin configurations which could be overwritten at
board level to fit a specific need. These files are hosted in hal_stm32 module (under dts/st/),
one for each STM32 SoC package. These files are generated from STM32 .xml description files
(currently delivered in ST STM32CubeMx tool). Using the appropriate -pinctrl.dtsi file allows
benefiting from the full list of valid pinctrl nodes for a SoC package that is used on a board,
reducing the risk of pin misconfiguration.
The -pinctrl.dtsi generation script is also provided and could be used to add or modify pinctrl
node variants, or to provide a new set of -pinctrl.dtsi files if a new STM32 SoC shows up.

This new method could coexist with current pinmux.c configuration (beware of the pin conflicts
as usual, though). 

For now, PR #25996 only provides the tooling for dts based pin configuration. Only one driver
(STM32 serial) and 2 boards have been modified as proof of concept (cf PR for more details).
Next step is to extend its usage to existing STM32 boards and drivers. Target is to get rid of in
tree pinmux.c files for V2.5.0, so their usage could be deprecated.
I invite STM32 codeowners and contributors to help us in this task. Out of tree users are also
encouraged to perform this change on their respective boards.

Big thanks to Gerard Marull-Paretas (@gmarull) who helped me with this PR and provided the
pinctrl.dtsi files generation script.

Cheers
Erwan