Difference between revisions of "TAMP device tree configuration"

[unchecked revision] [quality revision]
m (DT bindings documentation)
m (DT bindings documentation)
 

1 Article purpose[edit]

This article explains how to configure TAMP internal peripheral.
This article describes the TAMP configuration performed using the device tree mechanism, which provides an hardware description of the TAMP peripheral.

2 DT bindings documentation[edit]

The following binding-related documentation explains how to write device tree files for TAMP:

  • TF-A: Tamper related part: tf-a/docs/devicetree/bindings/soc/st,stm32-tamp.txt"[1]
  • Linux Kernel: Backup register management: Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.txtyaml'[2]

3 DT configuration[edit]

This hardware description is a combination of the STM32 microprocessor device tree files (.dtsi extension) and board device tree files (.dts extension). See the Device tree for an explanation of the device-tree file split.

STM32CubeMX can be used to generate the board device tree. Refer to How to configure the DT using STM32CubeMX for more details.

3.1 DT configuration (STM32 level)[edit]

The STM32MP1 TAMP node is located in the file stm32mp151.dtsi[3] (see Device tree for further explanation). TAMP is used in the Linux context to access to the backup registers.

  / {
  ...
  	soc {
  ...
  		tamp: tamp@5c00a000 {
			compatible = "simple-bus", "syscon", "simple-mfd";
			reg = <0x5c00a000 0x400>;

                                reboot-mode {
				        compatible = "syscon-reboot-mode";
				        offset = <0x150>; /* reg20 */
				        mask = <0xff>;
				        mode-normal = <0>;
				        mode-fastboot = <0x1>;
				        mode-recovery = <0x2>;
				        mode-stm32cubeprogrammer = <0x3>;
				        mode-ums_mmc0 = <0x10>;
				        mode-ums_mmc1 = <0x11>;
				        mode-ums_mmc2 = <0x12>;
                                };
		};
  ...
  	};
  ...
  };

3.2 DT configuration (board level)[edit]

3.2.1 STM32MP1 TAMP node append[edit]

The board definition in the device tree may include some additional board-specific pin control management.

Warning white.png Warning
By default, no pinctrl description is required for tamper, the associated GPIO pin is reserved for the tamper usage, preempting the current GPIO pin configuration. Despite of the hardware management, It may be better to describe the pinctrl to avoid any software double pin request.
 &tamp {
            pinctrl-0 = <&tamp1_pins_a>;              // Must be defined in the pinctrl corresponding to the board
            wakeup-source;                            // Enable the tamper as wake up source
 };

3.2.2 STM32MP1 TAMP node append (bootloader specific)[edit]

The bootloader-specific STM32MP1 TAMP node append data is located in the file stm32mp151.dtsi [4] for TF-A (see Device tree for further explanation).

tamp: tamp@5c00a000 {
     compatible = "st,stm32-tamp", "simple-bus", "syscon", "simple-mfd";
     reg = <0x5c00a000 0x400>;
     secure-interrupts = <GIC_SPI 197 IRQ_TYPE_LEVEL_HIGH>;
     clocks = <&rcc RTCAPB>;
};

4 How to configure the DT using STM32CubeMX[edit]

The STM32CubeMX tool can be used to configure the STM32MPU device and get the corresponding platform configuration device tree files.
STM32CubeMX may not support all the properties described in the documents listed in DT bindings documentation above. If so, the tool inserts user sections in the generated device tree. These sections can then be edited to add some properties that are preserved from one generation to another. Refer to the STM32CubeMX user manual for further information.

5 References[edit]

Please refer to the following links for additional information:


== Article purpose ==
This article explains how to configure [[TAMP_internal_peripheral|TAMP internal peripheral]].<br>

This article describes the [[TAMP internal peripheral|TAMP]] configuration performed using the [[Device tree|device tree]] mechanism, which provides an hardware description of the [[TAMP_internal_peripheral|TAMP]] peripheral.

== DT bindings documentation ==
The following binding-related documentation explains how to write device tree files for TAMP:
* [[TF-A overview|TF-A]]: Tamper related part: ''tf-a/docs/devicetree/bindings/soc/st,stm32-tamp.txt"<ref name="st,stm32-tamp.txt"> {{CodeSource | TF-A | docs/devicetree/bindings/soc/st,stm32-tamp.txt}} [[TF-A overview|TF-A]] TAMP binding information file</ref>

* Linux Kernel: Backup register management: ''Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.txtyaml'<ref name="syscon-reboot-mode.txt"> {{CodeSource | Linux kernel | Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.yaml}}</ref>


== DT configuration ==
This hardware description is a combination of the '''STM32 microprocessor''' device tree files (''.dtsi'' extension) and '''board''' device tree files (''.dts'' extension). See the [[Device tree]] for an explanation of the device-tree file split.

'''STM32CubeMX''' can be used to generate the board device tree. Refer to [[#How_to_configure_the_DT_using_STM32CubeMX|How to configure the DT using STM32CubeMX]] for more details.

=== DT configuration (STM32 level) ===
The STM32MP1 [[TAMP_internal_peripheral|TAMP]] node is located in the file ''stm32mp151.dtsi''<ref name="stm32mp151_kernel_dtsi">{{CodeSource | Linux kernel | arch/arm/boot/dts/stm32mp151.dtsi}} : STM32MP151 kernel device tree files</ref> (see [[Device tree]] for further explanation).
[[TAMP_internal_peripheral|TAMP]] is used in the Linux context to access to the backup registers.
<pre>

  / {
  ...
  	soc {
  ...
  		tamp: tamp@5c00a000 {
			compatible = "simple-bus", "syscon", "simple-mfd";
			reg = <0x5c00a000 0x400>;

                                reboot-mode {
				        compatible = "syscon-reboot-mode";
				        offset = <0x150>; /* reg20 */
				        mask = <0xff>;
				        mode-normal = <0>;
				        mode-fastboot = <0x1>;
				        mode-recovery = <0x2>;
				        mode-stm32cubeprogrammer = <0x3>;
				        mode-ums_mmc0 = <0x10>;
				        mode-ums_mmc1 = <0x11>;
				        mode-ums_mmc2 = <0x12>;
                                };
		};
  ...
  	};
  ...
  };</pre>

=== DT configuration (board level) ===
==== STM32MP1 TAMP node append ====
The board definition in the device tree may include some additional board-specific pin control management.
{{Warning |By default, no pinctrl description is required for tamper, the associated GPIO pin is reserved for the tamper usage, preempting the current GPIO pin configuration. Despite of the hardware management, It may be better to describe the pinctrl to avoid any software double pin request.}}
{{ReviewsComments|-- [[User:Emmanuel Combette|Emmanuel Combette]] ([[User talk:Emmanuel Combette|talk]]) 11:01, 28 June 2021 (CEST)<br />Insert your review comment here" 
may be more explicit if 
 "the associated GPIO pin is reserved for the tamper usage, preempting the current GPIO pin configuration" is replaced by
 "the associated GPIO pins are configured by RTC/TAMP settings that take over the current GPIO pin configuration"}}
  &tamp {
             pinctrl-0 = <&tamp1_pins_a>;              // Must be defined in the pinctrl corresponding to the board
             wakeup-source;                            // Enable the tamper as wake up source
  };

==== STM32MP1 TAMP node append (bootloader specific) ====
The bootloader-specific STM32MP1 [[TAMP_internal_peripheral|TAMP]] node append data is located in the file ''stm32mp151.dtsi'' <ref name="stm32mp151_tfa_dtsi">{{CodeSource | TF-A | fdts/stm32mp151.dtsi}} STM32MP151 TF-A device tree files</ref> for [[TF-A overview|TF-A]] (see [[Device tree]] for further explanation).<br />

<pre>

tamp: tamp@5c00a000 {
     compatible = "st,stm32-tamp", "simple-bus", "syscon", "simple-mfd";
     reg = <0x5c00a000 0x400>;
     secure-interrupts = <GIC_SPI 197 IRQ_TYPE_LEVEL_HIGH>;
     clocks = <&rcc RTCAPB>;
};</pre>


==How to configure the DT using STM32CubeMX==
The [[STM32CubeMX]] tool can be used to configure the STM32MPU device and get the corresponding [[Device_tree#STM32|platform configuration device tree]] files.<br />

STM32CubeMX may not support all the properties described in the documents listed in [[#DT bindings documentation|DT bindings documentation]] above. If so, the tool inserts '''user sections''' in the generated device tree. These sections can then be edited to add some properties that are preserved from one generation to another. Refer to the [[STM32CubeMX]] user manual for further information.

==References==
Please refer to the following links for additional information:
<references />
<noinclude>

[[Category:Device tree configuration]]
[[Category:Platform security]]
{{ArticleBasedOnModel | Peripheral or framework device tree configuration model}}</noinclude>
Line 6: Line 6:
 
The following binding-related documentation explains how to write device tree files for TAMP:
 
The following binding-related documentation explains how to write device tree files for TAMP:
 
* [[TF-A overview|TF-A]]: Tamper related part: ''tf-a/docs/devicetree/bindings/soc/st,stm32-tamp.txt"<ref name="st,stm32-tamp.txt"> {{CodeSource | TF-A | docs/devicetree/bindings/soc/st,stm32-tamp.txt}} [[TF-A overview|TF-A]] TAMP binding information file</ref>
 
* [[TF-A overview|TF-A]]: Tamper related part: ''tf-a/docs/devicetree/bindings/soc/st,stm32-tamp.txt"<ref name="st,stm32-tamp.txt"> {{CodeSource | TF-A | docs/devicetree/bindings/soc/st,stm32-tamp.txt}} [[TF-A overview|TF-A]] TAMP binding information file</ref>
* Linux Kernel: Backup register management: ''Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.txt'<ref name="syscon-reboot-mode.txt"> {{CodeSource | Linux kernel | Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.yaml}}</ref>
+
* Linux Kernel: Backup register management: ''Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.yaml'<ref name="syscon-reboot-mode.txt"> {{CodeSource | Linux kernel | Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.yaml}}</ref>
   
 
== DT configuration ==
 
== DT configuration ==