Difference between revisions of "STM32 MPU device tree"

[checked revision] [quality revision]
m (Device tree structure)
m (Device tree structure)
 
Applicable for STM32MP13x lines, STM32MP15x lines

1 Purpose and scope[edit]

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 and the device tree configuration supported by STM32MP1 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]

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.

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 README .
  • 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
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.

3 STM32CubeMX generated device tree[edit]

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

  • 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)

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 introduction). 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.


{{ApplicableFor
|MPUs list=STM32MP13x, STM32MP15x
|MPUs checklist=STM32MP13x, STM32MP15x
}}
__TOC__
== Purpose and scope ==
This article shows the structure of the device tree files as it is implemented in OpenSTLinux for [[STM32 MPU Linux kernel overview|Linux<sup>&reg;</sup> kernel]], [[U-Boot overview|U-Boot]], [[TF-A overview|TF-A]] and [[OP-TEE overview|OP-TEE]].

The purpose of this article is not to explain the [[Device tree|device tree]] concept and the [[:Category:Device tree configuration|device tree configuration]] supported by {{MicroprocessorDevice | device=1}}. A good knowledge of the concept is a prerequisite before reading this article. The articles regarding the configuration can be read afterwards.

== Device tree structure==
The device tree files are used during [[Boot chain overview|boot time]] by the FSBL (TF-A), the secure OS (OP-TEE), the SSBL (U-Boot) and, at run time, by the Linux kernel. <br />


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 {{MicroprocessorDevice | device=1}} are created in the '''Linux''' kernel.
** The source code path is {{CodeSource | Linux kernel | arch/arm/boot/dts/ | arch/arm/boot/dts/stm32mp1*}}.
* In '''U-Boot''', Linux files are copied and overloaded with U-Boot properties.
** The source code path is {{CodeSource | U-Boot | arch/arm/dts/ | 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 {{CodeSource | U-Boot | tools/binman/README | README}}.
* 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.
** The source code path is {{CodeSource | TF-A | fdts/ | fdts/stm32mp1*}}.
* In '''OP-TEE''', Linux files are reused.
** The source code path is {{CodeSource | OP-TEE_OS | core/arch/arm/dts/ | core/arch/arm/dts/stm32mp1*}}.
The figure below shows the device tree files structure for Linux, U-Boot, TF-A and OP-TEE:
[[File:Device_tree_for_Linux_U-Boot_TF-A_OP-TEE.png|center|link=]]
{{Info|
* 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 [[Which STM32MPU Embedded Software Package better suits your needs|Distribution Package]].}}
{{ReviewsComments|-- [[User:Nathalie Sangouard|Nathalie Sangouard]] ([[User talk:Nathalie Sangouard|talk]]) 11:06, 16 February 2022 (CET)<br />NSA/GBA : instead of "soc" use "SoC" in the picture above}}
== STM32CubeMX generated device tree ==
[[STM32CubeMX]] can help to '''generate''' the device tree files for a given project, for the various software components:
* '''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 overview#Firmware Configuration | 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)

The device tree files generated by STM32CubeMX can be '''built''' with the [[Which STM32MPU Embedded Software Package better suits your needs#Developer Package|Developer Package]] or [[Which STM32MPU Embedded Software Package better suits your needs#Distribution_Package|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 [[#Introduction|introduction]]). 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.
<noinclude>

[[Category:Platform configuration]]
{{PublicationRequestId | 14960 | 2019-01-31 | Previous PR: 10415 (AnneJ)}}</noinclude>
Line 29: Line 29:
 
* For the sake of simplicity, the figure only shows the '''dtsi''' & '''dts''' '''files''' structure, without showing the '''h files''' that are also included.
 
* 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 [[Which STM32MPU Embedded Software Package better suits your needs|Distribution Package]].}}
 
* The '''dtb files''', resulting from the compilation with the dtc compiler, may be named differently when the compilation is launched with the [[Which STM32MPU Embedded Software Package better suits your needs|Distribution Package]].}}
 
{{ReviewsComments|-- [[User:Nathalie Sangouard|Nathalie Sangouard]] ([[User talk:Nathalie Sangouard|talk]]) 11:06, 16 February 2022 (CET)<br />NSA/GBA : instead of "soc" use "SoC" in the picture above}}
 
   
 
== STM32CubeMX generated device tree ==
 
== STM32CubeMX generated device tree ==