device tree hierarchy

For the STM32MP157D-EV1 board, the following is first draft of the include hierarchy of the device tree.

I’ve not worked on a giant embedded linux device before. I figure it’s a good idea to take some very terse notes and maybe it’ll be useful to someone else (but most likely me!)

And besides, who doesn’t like ascii art and incomplete sentences?

NOTE! This is for the Linux kernel! Not U-Boot, OP-TEE or TF-A! (Although, admittedly, there are only a couple of extra files that each includes and a few that they exclude.) In fact, why don’t we just say it here.

The U-Boot device tree includes a couple files for configuring the DDR and a couple files for u-boot specific stuff. These files are included at the board level (i.e. either in the daughterboard or mainboard):

stm32mp15-ddr.dtsi
stm32mp15-<DDR type>.dtsi
stm32mp15-u-boot.dtsi
<board>-u-boot.dtsi

The TF-A tree includes the 2 DDR files but excludes the “coprocessor resource” files. Additionally the DDR files are included by the “board factorization” files.

Finally, the OP-TEE tree is just a stripped down version of the Linux tree without the “coprocessor resources” files.

Some halfway decent pictures of this can be seen here.

Anyhow, on with the show.

* stm32mp157d-ev1.dts
+-->* stm32mp157d-ed1.dts
|   +-->* stm32mp157.dtsi
|   |   +-->* stm32mp153.dtsi
|   |       +-->* stm32mp151.dtsi
|   |           +-->* dt-bindings/interrupt-controller/arm-gic.h
|   |           +-->* dt-bindings/clock/stm32mp1-clks.h
|   |           +-->* dt-bindings/gpio/gpio.h
|   |           +-->* dt-bindings/reset/stm32mp1-resets.h
|   |           +-->* dt-bindings/thermal/thermal.h
|   +-->* stm32mp15xd.dtsi
|   +-->* stm32mp15-pinctrl.dtsi
|   |   +-->* dt-bindings/pinctrl/stm32-pinfunc.h
|   +-->* stm32mp15xxaa-pinctrl.dtsi
|   +-->* stm32mp15xx-edx.dtsi
|       +-->* stm32mp15-m4-srm.dtsi
|       +-->* stm32mp15-m4-srm-pinctrl.dtsi
|       +-->* dt-bindings/gpio/gpio.h
|       +-->* dt-bindings/mfd/st,stpmic1.h
+-->* stm32mp15xx-evx.dtsi
    +-->* dt-bindings/input/input.h
    +-->* dt-bindings/soc/stm32-hdp.h

DTS file naming conventions

File names are important for understanding what part of the system a particular device tree file affects. The organization of the DTS files for the STM32MP157D-EV1 evaluation board can be broken up into a few different bits.

The ST doco references various peripherals and the device tree files where they are configured by sometimes referring to the “level” at whcih the configuation may be found. This is what the text in the parenthesis in each heading is about.

DTS files for the SOC chip itself (stm32 level)

stm32mp15[1,3,7].dtsi

All three of these files are included by the main daughterboard file.

These files configure all (i think?) of the peripherals on the SOC chip. Note that not all peripherals are enabled in the default ST kernel.

DTS files for the SOC daughterboard (board level)

This is the smallish board containing a few LEDs, the DDR, some MMC, etc. They are named as follows (for the 157):

stm32mp157d-ed1.dts

(Note the “-ed1” suffix.)

There are additionally 3 other “ed1” files for the other chip types “a”, “c” and “f”.

This file has the GPU and memory layout information in it.

It also includes many of the other device tree files.

DTS files for the main evaluation board (board level)

This is the BIG boy with the ethernet, screen, camera and other accoutrements. This is specific to the EV1 evaluation board. The DK1 discovery kit files are named slightly different.

stm32mp157d-ev1.dts

(Note the “-ev1” suffix.)

Again, there are 3 other files for the specific type of SOC chip.

This is the device tree files that is at the top of the include hierarchy. It includes overlays for a couple of board peripherals.

Additional files

SOC extension files (SOC extension level)

I’m not sure what these files exactly encompass (yet!) but they are named as such:

stm32mp15xd.dtsi

Note the “x” for “extension”, duh.

This is included by the daughterboard DTS file.

Once again, these are 3 other files for the specific type of SOC chip.

Includes overlays for a couple CPU properties, OPP table and thermal.

pinctrl and pinctrl packages files

These are included by the daughterboard file.

stm32mp15-pinctrl.dtsi
stm32mp15xxaa-pinctrl.dtsi

There are 3 other files xxab, xxac and xxad.

The “aa”, “ab”, etc…are for the various part packages.

The “xxaa” file contains a pinctrl overlay that defines the GPIO banks. For example:

	gpioa: gpio@50002000 {
		status = "okay";
		ngpios = <16>;
		gpio-ranges = <&pinctrl 0 0 16>;
	};

The other file contains a pinctrl overlay which defines the actual pin functions.

	adc1_in6_pins_a: adc1-in6-0 {
		pins {
			pinmux = <STM32_PINMUX('F', 12, ANALOG)>;
		};
	};

Board factorization

The board factorization files

stm32mp15xx-edx.dtsi
stm32mp15xx-evx.dtsi

Ethernet and some other board level device are defined here.

The “edx” file is included by the SOC level file, stm32mp157.dts. It contains some definitions for memory, voltage, and the “heartbeat” LED as well as some overlays for more specific configuration of some peripherals. Of interest is that the ADC is configured here. It is specific to the peripherals located on the daughterboard.

The “evx” file is included by the daughterboard file, stm32mp157-ed1.dts. It contains a few definitions as well as overlays for mainboard peripherals. (It looks like, anyhow?)

coprocessor resources (a.k.a. the M4 files)

stm32mp157-m4-srm.dtsi
stm32mp157-m4-srm-pinctrl.dtsi

Included by the stm32mp15xx-edx.dtsi factorization file.

That’s all for now….

…..