Last edited 2 weeks ago

STM32 MPU device tree

Applicable for STM32MP13x lines, STM32MP15x lines, STM32MP23x lines, STM32MP25x lines

This article describes how the device tree files for STM32MPU are organized for Linux®, U-Boot, TF-A and OP-TEE, but also how they are organized when they are generated from STM32CubeMX.

1. Purpose and scope[edit | edit source]

This article shows the structure of the device tree files as it is implemented in OpenSTLinux for Linux® kernel, U-Boot, TF-A and OP-TEE.

The purpose of this article is not to explain the device tree concept but the device tree configuration supported by the STM32MP1 series and the STM32MP2 series. A good knowledge of the concept is a prerequisite before reading this article. The articles regarding the configuration can be read afterwards.

2. Device tree structure[edit | edit source]

The device tree files are used during boot time by the FSBL (TF-A), the secure OS (OP-TEE), the SSBL (U-Boot) and, at run time, by the Linux kernel.

2.1. STM32MP1 series[edit | edit source]

These files are stored in different github repositories (one for each first level bullet below), but source code reuse is maximized from one repository to another:

  • The initial device tree files supporting STM32MP1 series are created in the Linux kernel.
  • In U-Boot, Linux files are copied and overloaded with U-Boot properties.
    • The source code path is arch/arm/dts/stm32mp1* .
    • The U-Boot add-ons file, "<dts-file-name>-u-boot.dtsi", is automatically included at the end of "<board>.dts" during device tree compilation: this is a generic U-Boot Makefile behavior, see binman.rst .
  • In TF-A, Linux files are copied, completed with the security configuration (firewalling) and the DDR configuration. TF-A BL2 is applying some 'delete-property' on useless nodes, to lighten the final dtb file.
  • In OP-TEE, Linux files are reused.

The figure below shows the device tree files structure for Linux, U-Boot, TF-A and OP-TEE:

Device tree for Linux U-Boot TF-A OP-TEE.png

2.2. STM32MP2 series[edit | edit source]

These files are stored in different github repositories (one for each first level bullet below), but source code reuse is maximized from one repository to another:

  • The initial device tree files supporting STM32MP2 series are created in the Linux kernel.
  • In U-Boot, Linux files are copied and overloaded with U-Boot properties.
    • The source code path is arch/arm/dts/stm32mp2* .
    • The U-Boot add-ons file, "<dts-file-name>-u-boot.dtsi", is automatically included at the end of "<board>.dts" during device tree compilation: this is a generic U-Boot Makefile behavior, see binman.rst .
  • In TF-A, Linux files are copied, completed with the security configuration (firewalling) and limited clock tree required for boot and the DDR configuration. TF-A BL2 is applying some 'delete-property' on useless nodes, to lighten the final dtb file. TF-A BL3 device tree is a subset from TF-A BL2 one.
  • In OP-TEE, Linux files are reused, completed with clock tree and security configuration required to configure the complete system.

The figure below shows the device tree files structure for Linux, U-Boot, TF-A and OP-TEE:

Device tree for Linux U-Boot TF-A OP-TEE STM32MP2.png
Info white.png Information
  • The board level device tree file completes and/or overloads the default peripherals nodes configuration, defined in the included SoC dtsi file.
  • The above figure reflects the current implementation on github and may be somehow in advance compare to the upstreamed version for all parts that are still under review.
  • For the sake of simplicity, the figure only shows the dtsi & dts files structure, without showing the h files that are also included.
  • The dtb files, resulting from the compilation with the dtc compiler, may be named differently when the compilation is launched with the Distribution Package.
  • In TF-M, SoC, pinctrl and package dtsi files are reused. Other dedicated TF-M files are added. Devicetree usage in TF-M differs compared to other components listed above. TF-M uses devicetree to create header files used by TF-M code.
Device tree for TF M STM32MP2.png

3. STM32CubeMX generated device tree[edit | edit source]

STM32CubeMX can help to generate the device tree files for a given project, for the various software components:

3.1. STM32MP1 series[edit | edit source]

  • TF-A: STM32CubeMX generates three files:
  • 'stm32mp15-mx.dtsi' is equivalent to 'stm32mp1*-<DDR type>.dtsi' in the diagram above, embedding DDR settings
  • 'stm32mp1*-<your_project_name>-mx.dts' is the board device tree file, that includes all dtsi files (directly or not)
  • 'stm32mp1*-<your_project_name>-mx-fw-config.dts' file corresponds to the TF-A firmware configuration and is out of the file structure shown in the previous paragraph
  • U-Boot:
  • 'stm32mp1*-<your_project_name>-mx.dts' is the board device tree file, that includes all dtsi files (directly or not)
  • 'stm32mp1*-<your_project_name>-mx-u-boot.dts' is equivalent to the '<board>-u-boot.dtsi' file in the diagram above
  • Linux:
  • 'stm32mp1*-<your_project_name>-mx.dts' is the board device tree file, that includes all dtsi files (directly or not)
  • OP-TEE:
  • 'stm32mp1*-<your_project_name>-mx.dts' is the board device tree file, that includes all dtsi files (directly or not)

3.2. STM32MP2 series[edit | edit source]

STM32CubeMX can help to generate the device tree files for a given project, for the various software components:

  • TF-A: STM32CubeMX generates three files:
  • 'stm32mp25-mx.dtsi' is equivalent to 'stm32mp1*-<DDR type>.dtsi' in the diagram above, embedding DDR settings
  • 'stm32mp2*-<your_project_name>-mx.dts' is the board device tree file, that includes all dtsi files (directly or not)
  • 'stm32mp2*-<your_project_name>-mx-fw-config.dts' file corresponds to the TF-A firmware configuration and is out of the file structure shown in the previous paragraph
  • 'stm32mp2*-<your_project_name>-mx-rcc.dts' is the TF-A clock tree device tree file.
  • U-Boot:
  • 'stm32mp2*-<your_project_name>-mx.dts' is the board device tree file, that includes all dtsi files (directly or not)
  • 'stm32mp2*-<your_project_name>-mx-u-boot.dts' is equivalent to the '<board>-u-boot.dtsi' file in the diagram above
  • 'stm32mp2*-<your_project_name>-mx-resmem.dts' is the U-Boot memory mapping device tree file.
  • Linux:
  • 'stm32mp2*-<your_project_name>-mx.dts' is the board device tree file, that includes all dtsi files (directly or not)
  • 'stm32mp2*-<your_project_name>-mx-resmem.dts' is the Linux memory mapping device tree file.
  • OP-TEE:
  • 'stm32mp2*-<your_project_name>-mx.dts' is the board device tree file, that includes all dtsi files (directly or not)
  • 'stm32mp2*-<your_project_name>-mx-resmem.dts' is the OP-TEE memory mapping device tree file.
  • 'stm32mp2*-<your_project_name>-mx-rcc.dts' is the OP-TEE clock tree device tree file.
  • 'stm32mp2*-<your_project_name>-mx-rif.dts' is the OP-TEE RIF device tree file.
  • TF-M:
  • 'stm32mp2*-<your_project_name>-mx.dts' is the board device tree file, that includes all dtsi files (directly or not)
  • 'stm32mp2*-<your_project_name>-mx-resmem.dts' is the TF-M memory mapping device tree file.
  • 'stm32mp2*-<your_project_name>-mx-rcc.dts' is the TF-M clock tree device tree file.

3.3. Using the generated files[edit | edit source]

The device tree files generated by STM32CubeMX can be built with the Developer Package or Distribution Package:

  • Use the Developer Package to store the STM32CubeMX-generated files in the folder of your choice. Then, manually copy or link them into Linux, U-Boot and TF-A device tree folders (see Device tree structure). Do not forget to add your device tree file name in ../Makefile.sdk (for TF-A SDK and U-Boot SDK) and in arch/arm/boot/dts/Makefile (for Linux kernel SDK), before compiling them as explained in How to cross-compile with the Developer Package.
  • Use the Distribution Package to store the STM32CubeMX-generated files in meta-st/meta-st-stm32mp-addons/mx, as explained in the How to create your own machine article. This article also describes how to build the complete image. Examples of Linux (device tree), U-Boot and TF-A individual compiling can be found in the How to cross-compile with the Distribution Package article.