查看“STM32MP15 device tree”的源代码

== 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 [[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.

==== 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>