STM32MP15 device tree

1 Purpose and scope[edit]

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

The purpose of this article is not to explain the device tree concept and the device tree configuration supported by STM32MP15. 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 for Linux, U-Boot, TF-A and OP-TEE[edit]

2.1 STMicroelectronics software delivery[edit]

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

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 STM32MP15 are created in the Linux kernel.
  • In U-Boot, Linux files are copied and overloaded with U-Boot properties (including DDR configuration).
    • The source code path is arch/arm/dts/stm32mp15* .
    • The U-Boot add-ons file, "<dts-file-name>-u-boot.dtsi", is automatically included at the end of "<dts-file-name>.dts" during device tree compilation (this is a generic U-Boot Makefile behavior).
  • In TF-A, Linux files are partly copied (for device tree blob size optimization), completed with the security configuration (firewalling) and the DDR configuration (same files as U-Boot). TF-A device tree bindings reading is needed to understand which parts of the Linux device tree must be kept or can be deleted during the partial copy.
  • In OP-TEE, TF-A files are reused, except the DDR configuration ones.

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

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

Color legend:

  •  Linux  in dark blue
  •  U-Boot  add-ons in green
  •  DDR configuration  for TF-A and U-Boot in pink
  •  STM32CubeMX generated parts  in light blue (not used above but visible in STM32CubeMX section down in this article)
  • The hashed areas on Linux device tree files represent the fact that these files are modified, so partly copied and updated

The above color codes are used for all the figures included in this article.

2.2 Upstreamed device tree[edit]

2.2.1 Overview[edit]

As explained in the STM32 MPU Embedded Software Open Source Software (OSS) philosophy, STMicroelectronics maximizes the usage of open source software and the upstreaming to the communities.

So, the device tree files supporting the evaluation board and the discovery kit are upstreamed to their official respective repositories. But waiting for the upstream process completion, STMicroelectronics latest contributions are available in advance on github in Linux , U-Boot , TF-A and OP-TEE repositories.

Info white.png Information
The figures shown below are reflecting the current implementation on github and they may be somehow in advance compare to the upstreamed version for all parts that are still under review.
Info white.png Information
For the sake of simplicity, the figures below only show the dtsi & dts files structure, without showing the h files that are also included.
Info white.png Information
The dtb files, resulting from the compilation with the dtc compiler, may be named differently when the compilation is launched with the Distribution Package.

2.2.2 Linux[edit]

Device tree Linux upstreamed.png
Device tree legend.png

2.2.3 U-Boot[edit]

Device tree U-Boot upstreamed.png
Device tree legend.png

Info white.png Information
'<board>-u-boot.dtsi' file inclusion at the end of '<board>.dts' file is not explicit (#include ...) but realized via an U-Boot generic mechanism (see README )

2.2.4 TF-A[edit]

Device tree TF-A upstreamed.png
Device tree legend.png

Note: The hashed areas on Linux device tree files represent the fact that these files are modified in TF-A.

2.2.5 OP-TEE[edit]

Device tree OP-TEE upstreamed.png
Device tree legend.png

Note: The hashed areas on Linux device tree files represent the fact that these files are modified in OP-TEE.

2.3 STM32CubeMX generated device tree[edit]

2.3.1 Overview[edit]

STM32CubeMX can be used to generate the device tree files for a given project. The tool generates the files  highlighted in light blue  in the following diagrams, including the upstreamed files shown in the previous chapter.

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

2.3.2 Linux[edit]

Device tree Linux STM32CubeMX.png

2.3.3 U-Boot[edit]

Device tree U-Boot STM32CubeMX.png

2.3.4 TF-A[edit]

Device tree TF-A STM32CubeMX.png

2.3.5 OP-TEE[edit]

STM32CubeMX does not generate any device tree source files dedicated to OP-TEE, but these can be derived from the device tree source files generated for TF-A. In OP-TEE github release , OP-TEE files are the very TF-A source files with the DDR dtsi files removed since fully unused. However, one can copy TF-A device tree source files stm32mp15* to OP-TEE dts/   source directory and build OP-TEE with.