Difference between revisions of "STM32MP15 device tree"

[quality revision] [quality revision]
m
m

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 and TF-A.

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 and TF-A[edit]

2.1 Introduction[edit]

The device tree files are used during boot time by the FSBL (TF-A / U-Boot SPL), the SSBL (U-Boot), and eventually by the Linux kernel.
These files are stored in different repositories, 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).
  • In TF-A, Linux files are partly copied (for device tree blob size optimization), and then completed with the DDR configuration copied from U-Boot, and with the security configuration (firewalling).


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

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

Color legend:

  •  Linux  in dark blue
  •  U-Boot  in green
  •  TF-A  in pink
  •  STM32CubeMX generated parts  in light blue

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.

As a result, the device tree files supporting the evaluation board and the Discovery kit are upstreamed to Linux , U-Boot and TF-A repositories.

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

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 partly copied in TF-A.


2.3 Manual customization of STM32MP15 reference device tree[edit]

As explained in the above sections, the current device tree structure is based on STM32MP157C configuration, so one could wonder how to proceed for another STM32MP15 part number (see STM32MP15 microprocessor diversity for details).
Below guidelines on how to customize the device tree for another STM32MP15 MPU device.

2.3.1 Generic setup[edit]

This first step enables to boot with any STM32MP15 MPU. Warning or error messages are displayed on the console without any consequences with the boot success.

2.3.1.1 Include "stm32mp157c.dtsi", whatever your device part number[edit]

This is the superset of device tree declaration corresponding to the largest set of STM32MP15 microprocessor features.

2.3.1.2 Include the pinctrl reference file corresponding to your package size (a, b, c or d)[edit]
  • stm32mp157caa-pinctrl.dtsi for 18x18 package
  • stm32mp157cab-pinctrl.dtsi for 16x16 package
  • stm32mp157cac-pinctrl.dtsi for 14x14 package
  • stm32mp157cad-pinctrl.dtsi for 12x12 package

2.3.2 Clean up your configuration[edit]

2.3.2.1 Customize your "stm32mp157c.dtsi" file to remove all the configurations that are not relevant for your STM32MP15 part number[edit]

For example, remove cpu1 core if it is not relevant.

All the peripherals available on STM32MP15 MPU devices are configured but not activated, so no need to remove any of them in stm32mp157c.dtsi.

2.3.2.2 Activate only the peripherals available on your STM32MP15 part number on your board[edit]

For example:

  • Activate the peripherals linked to security and cryptography on secure microprocessors (STM32MP157D).
  • Activate FDCAN on STM32MP153x, and DSI and GPU on STM32MP157x.

2.4 STM32CubeMX generated device tree[edit]

2.4.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.4.2 Linux[edit]

Device tree Linux STM32CubeMX.png

2.4.3 U-Boot[edit]

Device tree U-Boot STM32CubeMX.png

2.4.4 TF-A[edit]

Device tree TF-A STM32CubeMX.png


== Purpose and scope ==
This article shows the structure of the device tree files as it is implemented in STM32MP15 for the following software components: [[STM32MP15 Linux kernel overview|Linux<sup>&reg;</sup> kernel]], [[U-Boot overview|U-Boot]] and [[TF-A overview|TF-A]].

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 STM32MP15. 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 for Linux, U-Boot and TF-A ==

=== Introduction ===
The device tree files are used during [[Boot chains overview|boot time]] by the FSBL (TF-A / U-Boot SPL), the SSBL (U-Boot), and eventually by the Linux kernel. <br />

These files are stored in different repositories, but source code reuse is maximized from one repository to another:
* The initial device tree files supporting STM32MP15 are created in the '''Linux''' kernel.
** The source code path is {{CodeSource | Linux kernel | arch/arm/boot/dts/ | arch/arm/boot/dts/stm32mp15*}}.
* In '''U-Boot''', Linux files are copied and overloaded with U-Boot properties (including DDR configuration).
** The source code path is {{CodeSource | U-Boot | arch/arm/dts/ | arch/arm/dts/stm32mp15*}}.
* In '''TF-A''', Linux files are partly copied (for device tree blob size optimization), and then completed with the DDR configuration copied from U-Boot, and with the security configuration (firewalling).
** The source code path is {{CodeSource | TF-A | fdts/ | fdts/stm32mp15*}}.<br />


The figure below shows the device tree creation flow for Linux, U-Boot and TF-A:
[[File:Device_tree_for_Linux_U-Boot_TF-A.png|center|link=]]
Color legend: 
* <span style="color:#FFFFFF; background:{{STDarkBlue}};">&nbsp;Linux&nbsp;</span> in dark blue
* <span style="color:#FFFFFF; background:{{STLightGreen}};">&nbsp;U-Boot&nbsp;</span> in green
* <span style="color:#FFFFFF; background:{{STPink}};">&nbsp;TF-A&nbsp;</span> in pink
* <span style="color:#FFFFFF; background:{{STLightBlue}};">&nbsp;STM32CubeMX generated parts&nbsp;</span> in light blue
The above color codes are used for all the figures included in this article.

=== Upstreamed device tree ===
==== Overview ====
As explained in the STM32 MPU Embedded Software [[STM32MPU_Embedded_Software_architecture_overview#Open_Source_Software_(OSS)_philosophy| Open Source Software (OSS) philosophy]], STMicroelectronics maximizes the usage of open source software and the upstreaming to the communities.

As a result, the device tree files supporting the [[STM32MP157xSTM32MP157C-EV1 - hardware description|evaluation board]] and the [[STM32MP157x-DKxSTM32MP157X-DKX - hardware description|Discovery kit]] are '''upstreamed''' to {{CodeSource | Linux kernel | arch/arm/boot/dts/ | Linux}}, {{CodeSource | U-Boot | arch/arm/dts/ | U-Boot}} and {{CodeSource | TF-A | fdts/ | TF-A}} repositories.

==== Linux ====
[[File:Device tree Linux upstreamed.png|center|link=]]
[[File:Device tree legend.png|center|link=]]<br />


==== U-Boot ====
[[File:Device tree U-Boot upstreamed.png|center|link=]]
[[File:Device tree legend.png|center|link=]]<br />


==== TF-A ====

[[File:Device tree TF-A upstreamed.png|center|link=]]
[[File:Device tree legend.png|center|link=]]<br />

Note: The hashed areas on Linux device tree files represent the fact that these files are partly copied in TF-A.<br />

{{ReviewsComments | YGA: You don't mention the .h files in include/dt-bindings?}}
{{ReviewsComments | YGA: When compiling TF-A (outside yocto) the dtb files are stm32mp157c-ev1.dtb and so on. I don't know if that should be changed in the image?}}

=== Manual customization of STM32MP15 reference device tree ===
As explained in the above sections, the current device tree structure is based on STM32MP157C configuration, so one could wonder how to proceed for another STM32MP15 part number (see [[STM32MP15 microprocessor]] diversity for details).<br>

Below guidelines on how to customize the device tree for another STM32MP15 MPU device.
==== Generic setup ====
This first step enables to boot with any STM32MP15 MPU. Warning or error messages are displayed on the console without any consequences with the boot success.
===== Include "stm32mp157c.dtsi", whatever your device part number ===== 
This is the superset of device tree declaration corresponding to the largest set of STM32MP15 microprocessor features.
===== Include the pinctrl reference file corresponding to your package size (a, b, c or d) ===== 
* stm32mp157caa-pinctrl.dtsi for 18x18 package
* stm32mp157cab-pinctrl.dtsi for 16x16 package
* stm32mp157cac-pinctrl.dtsi for 14x14 package
* stm32mp157cad-pinctrl.dtsi for 12x12 package

==== Clean up your configuration====
===== Customize your "stm32mp157c.dtsi" file to remove all the configurations that are not relevant for your STM32MP15 part number===== 
For example, remove cpu1 core if it is not relevant. <br>


All the peripherals available on STM32MP15 MPU devices are configured but not activated, so no need to remove any of them in stm32mp157c.dtsi.

=====  Activate only the peripherals available on your STM32MP15 part number on your board ===== 
For example:
* Activate the peripherals linked to security and cryptography on secure microprocessors (STM32MP157D).
* Activate FDCAN on STM32MP153x, and DSI and GPU on STM32MP157x.

=== STM32CubeMX generated device tree ===
==== Overview ====
[[STM32CubeMX]] can be used to '''generate''' the device tree files for a given project. The tool generates the files <span style="color:#FFFFFF; background:{{STLightBlue}};">&nbsp;highlighted in light blue&nbsp;</span> in the following diagrams, including the upstreamed files shown in the previous chapter.<br />
<br />

{{ReviewsComments| CMO w845.1, during latest discussion/meeting with SVA/CubeMX team, we keep ProjectName in the name of dts file}}

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 [[STM32MP15_device_tree#Introduction|introduction]]). Do not forget to add your device tree file name in '''../Makefile.sdk''' (for [[STM32MP1 Developer Package - TF-A|TF-A SDK]] and [[STM32MP1 Developer Package - U-Boot|U-Boot SDK]]) and in '''arch/arm/boot/dts/Makefile''' (for [[STM32MP1 Developer Package - Linux kernel|Linux kernel SDK]]), before compiling them as expalined 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.

==== Linux ====
[[File:Device tree Linux STM32CubeMX.png|center|link=]]<br />


==== U-Boot ====
[[File:Device tree U-Boot STM32CubeMX.png|center|link=]]<br />


==== TF-A ====
[[File:Device tree TF-A STM32CubeMX.png|center|link=]]<br />

<noinclude>

[[Category:STM32MP15 platform configuration|6]]
{{PublicationRequestId | 14960 | 2019-01-31 | Previous PR: 10415 (AnneJ)}}</noinclude>
Line 31: Line 31:
 
As explained in the STM32 MPU Embedded Software [[STM32MPU_Embedded_Software_architecture_overview#Open_Source_Software_(OSS)_philosophy| Open Source Software (OSS) philosophy]], STMicroelectronics maximizes the usage of open source software and the upstreaming to the communities.
 
As explained in the STM32 MPU Embedded Software [[STM32MPU_Embedded_Software_architecture_overview#Open_Source_Software_(OSS)_philosophy| Open Source Software (OSS) philosophy]], STMicroelectronics maximizes the usage of open source software and the upstreaming to the communities.
   
As a result, the device tree files supporting the [[STM32MP157C-EV1 - hardware description|evaluation board]] and the [[STM32MP157X-DKX - hardware description|Discovery kit]] are '''upstreamed''' to {{CodeSource | Linux kernel | arch/arm/boot/dts/ | Linux}}, {{CodeSource | U-Boot | arch/arm/dts/ | U-Boot}} and {{CodeSource | TF-A | fdts/ | TF-A}} repositories.
+
As a result, the device tree files supporting the [[STM32MP157x-EV1 - hardware description|evaluation board]] and the [[STM32MP157x-DKx - hardware description|Discovery kit]] are '''upstreamed''' to {{CodeSource | Linux kernel | arch/arm/boot/dts/ | Linux}}, {{CodeSource | U-Boot | arch/arm/dts/ | U-Boot}} and {{CodeSource | TF-A | fdts/ | TF-A}} repositories.
   
 
==== Linux ====
 
==== Linux ====