Pinctrl device tree configuration

Applicable for

STM32MP13x lines, STM32MP15x lines

---

1. Purpose

The purpose of this article is to explain how to configure the GPIO internal peripheral through the pin controller (pinctrl) framework, when this peripheral is assigned to Linux^® OS (Cortex-A). The configuration is performed using the Device tree.

To better understand I/O management, it is recommended to read the Overview of GPIO pins article.

This article also provides an example explaining how to add a new pin in the device tree.

If the peripheral is assigned to another execution context, refer to How to assign an internal peripheral to a runtime context article for guidelines on peripheral assignment and configuration.

2. DT bindings documentation

The Pinctrl device tree bindings are composed of:

• generic DT bindings used by the pinctrl framework.

• vendor pinctrl DT bindings used by the stm32-pinctrl driver: this binding document explains how to write device tree files for pinctrl.

3. DT configuration

3.1. DT configuration (STM32 level)

The pin controller node is composed of several parts:

3.1.1. STM32 pin controller information

The pin controller node is located in the SOC dtsi file

• for STM32MP13x lines  stm32mp131.dtsi
• for STM32MP15x lines  stm32mp151.dtsi

For example:

pinctrl: pinctrl@50002000 {                 Template:Highlight
 	#address-cells = <1>;              
 	#size-cells = <1>;                 
 	ranges = <0 0x50002000 0xa400>;    Template:Highlight
 	interrupt-parent = <&exti>;        Template:Highlight
 	st,syscfg = <&exti 0x60 0xff>;     Template:Highlight
 	pins-are-numbered;
	
        ...
};

Template:Warning

3.1.2. GPIO bank information

The GPIO bank information nodes are located in the SOC dtsi file

• for STM32MP13x lines  stm32mp131.dtsi
• for STM32MP15x lines  stm32mp151.dtsi

For example:

pinctrl: pinctrl@50002000 {                 Template:Highlight
 	...

	gpioa: gpio@50002000 {
		gpio-controller;           
		#gpio-cells = <2>;
		interrupt-controller;      Template:Highlight
		#interrupt-cells = <2>;
		reg = <0x0 0x400>;         Template:Highlight
		clocks = <&rcc GPIOA>;     Template:Highlight
		st,bank-name = "GPIOA";
		status = "disabled";
	};

	gpiob: gpio@50003000 {
		gpio-controller;
		#gpio-cells = <2>;
		interrupt-controller;
		#interrupt-cells = <2>;
		reg = <0x1000 0x400>;
		clocks = <&rcc GPIOB>;
		st,bank-name = "GPIOB";
		status = "disabled";
	};

        ...
};

The GPIO bank definition may be completed by the pinctrl package dtsi files, as, for example for STM32MP15x lines  stm32mp15xxaa-pinctrl.dtsi.

&pinctrl {
	st,package = <STM32MP_PKG_AA>;

	gpioa: gpio@50002000 {
		status = "okay";
		ngpios = <16>;
		gpio-ranges = <&pinctrl 0 0 16>;
	};

	gpiob: gpio@50003000 {
		status = "okay";
		ngpios = <16>;
		gpio-ranges = <&pinctrl 0 16 16>;
	};

Template:Warning

3.1.3. Pin state definition

The pin states are defined in the pinctrl dtsi file

• for STM32MP13x lines  stm32mp13-pinctrl.dtsi
• for STM32MP15x lines  stm32mp15-pinctrl.dtsi

For example:

&pinctrl {
        ...
         usart3_pins_a: usart3@0 {                                                   Template:Highlight
	        pins1 {
		        pinmux = <STM32_PINMUX('B', 10, AF7)>, /* USART3_TX */      Template:Highlight
			         <STM32_PINMUX('G', 8, AF8)>; /* USART3_RTS */      Template:Highlight
		        bias-disable;                                               Template:Highlight
		        drive-push-pull;                                            Template:Highlight
		        slew-rate = <0>;                                            Template:Highlight
	        };
	        pins2 {
		        pinmux = <STM32_PINMUX('B', 12, AF8)>, /* USART3_RX */
			         <STM32_PINMUX('I', 10, AF8)>; /* USART3_CTS_NSS */
		        bias-disable;
	        };
       };
       ...
};

- Refer to GPIO internal peripheral for more details on hardware pin configuration.

3.2. DT configuration (board level)

3.2.1. Pin state selection

As seen in Pin controller configuration (pin state definition part), all pin states are defined inside the pin controller node.

Each device that requires pins has to select the desired pin state phandle inside the board device tree file (see Device tree for more explanations about device tree file split).

The STM32MP1 devices feature a lot of possible pin combinations for a given internal peripheral. From one board to another, different sets of pins can consequently be used for an internal peripheral. Note that "_a", "_b" suffixes are used to identify pin muxing combinations in the device tree pinctrl file. The right suffixed combination must then be used in the device tree board file.

• Example:

&usart3 {
        ...
	pinctrl-names = "default","sleep";
	pinctrl-0 = <&usart3_pins_a>;
	pinctrl-1 = <&usart3_sleep_pins_a>;
	...
};

3.2.2. GPIO bank secure information (OP-TEE device tree)

The secure aware GPIO banks (see Security support) may contain some specific secure settings. A peripheral set as secure MUST use secure GPIOs.

The specific st,protreg binding defined in the OP-TEE device tree sets the security at boot time and prevents non secure peripherals from using pins.

For example:

&gpiob {
	st,protreg = <(TZPROT(1)|TZPROT(6))>;    Template:Highlight
};

Template:Warning

3.3. DT configuration examples

3.3.1. How to add new pin states

To add new pin states and affect them to a foo_device, proceed as follows:

1. Find the pins you need:

In the example below, the foo_device needs to configure PC13, PG8 and PI2.

AF2 is selected as alternate function on PC13, and AF5 on PG8 and PI2.

Each pin requires an internal pull-up.

2. Write your pin state phandle in stm32mp15-pinctrl.dtsi.

 &pinctrl {
         ...
          foo_pins_a: foo@0 {
 	        pins {
 		        pinmux = <STM32_PINMUX('C', 13, AF2)>,
                                 <STM32_PINMUX('G', 8, AF5)>,
 			         <STM32_PINMUX('I', 2, AF5)>; 
 		        bias-pull-up;
 	        };
        };
        ...
 };

All the possible settings are described in GPIO internal peripheral.

3. Select the pin state phandle required for your device in the board file.

&foo {
        ...
	pinctrl-names = "default";
	pinctrl-0 = <&foo_pins_a>;
	...
};

4. How to configure GPIOs using STM32CubeMX

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

Please refer to the following links for additional information:

Template:ArticleBasedOnModel

Linux^® is a registered trademark of Linus Torvalds.

Operating system

Cortex^®

Device tree

General-purpose input/output (A realization of open ended transmission between devices on an embedded level. These pins available on a processor can be programmed to be used to either accept input or provide output to external devices depending on user desires and applications requirements.)

Transmit

Receive

Compatibility test suite (Android specific) or clear to send (in UART context)

Open portable trusted execution environment