How to compile the device tree with the Developer Package

1. Purpose

This article explains how to update boot chain (trusted mode) in case of use of a "customised" devicetree.
As exemple, CubeMX is able to generate "customised" devicetree.

This article describes how to update the DTB (devicetree compiled) part of the boot binaries.

Information

Even if STMicroelectronics strongly recommends to use a Linux® environment, this article works in WSL2 (Windows Sub-system Linux 2) from Windows 10® (builds 2019 or later)

2. Rationale

The rationale to not use the devicetree provided by OpenSTLinux distribution and prefer a "customised" devicetree is various;

• You made your own board
• You need to swap some IPs from MCU side to MPU side (or reverse)
• For any other reason...

3. Pre-requisites

This article only need to update three software of the complete boot chain (trusted mode); Trusted Firmware A (TF-A), u-boot and the Linux kernel.
Modifying those software need to handle :

• Starter package :

• need flashlayout and images to flash provided from file IMAGES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz

• Developer package :

• Need components sources and patches of the the software to update provided in file SOURCES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz
• Need mkimage for stm32 and dtc utilities which could be provided by file SDK-x86_64-st-image-weston-openstlinux-weston-stm32mp1.tar.xz

• Notice this is optional since 'dtc' and 'mkimage for stm32' could also be provided by your Linux distribution (as Ubuntu, even Ubuntu though WSL)

• Host tools for binary manipulation : tar, patch, ssh/scp, dd and mount loop device

• Those tools are very basic and available in any Linux distribution even on WSL.
• In case of using WSL, mount loop device is only available from WSL2.

• STM32CubeProgrammer: the tool used to flash the images and binaries into target

• Custom devicetree sources:

• For the rest of document the custom devicetree are considered generated by STM32CubeMX and stored in a tarball MyDeviceTree_fromCubeMX.tar.xz with following file tree:

MyDeviceTree_fromCubeMX
|-- kernel
|   |-- stm32mp157c-mydevicetree-mx.dts
|-- tf-a
|  |-- stm32mp15-mx.h
|  |-- stm32mp157c-mydevicetree-mx.dts
|-- u-boot
|  |-- stm32mp15-mx.h
|  |-- stm32mp157c-mydevicetree-mx-u-boot.dtsi
|  |-- stm32mp157c-mydevicetree-mx.dts

4. Prepare your environnement

As seen in #Pre-requisites, there are numerus inputs so here a proposition to organize your environment.
Better is to create a dedicated WORKDIR somewhere in your HOME. Then copy all inputs quoted in #Pre-requisites in that just created WORKDIR:

cd

mkdir WORKDIR

cd WORKDIR

export WORKDIR="$PWD"

cp <IMAGES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz> $WORKDIR/

tar xf <IMAGES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz> -C $WORKDIR/

cp <SOURCES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz> $WORKDIR/

tar xf <SOURCES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz> -C $WORKDIR/

cp <MyDeviceTree_fromCubeMX.tar.xz> $WORKDIR/

tar xf <MyDeviceTree_fromCubeMX.tar.xz> -C $WORKDIR/

(optional) cp <SDK-x86_64-st-image-weston-openstlinux-weston-stm32mp1.tar.xz> $WORKDIR/

(optional) tar xf <SDK-x86_64-st-image-weston-openstlinux-weston-stm32mp1.tar.xz> -C $WORKDIR/

5. Kernel device tree update

Updating the devicetree of kernel only needs to replace the 'dtb' file of '/boot' partition.
Indeed 'extlinux.conf' explicitly points on the dtb the kernel should use (something like '/boot/<devicetree>.dtb'). Below the procedure to generate and then copy new DTB in target:

5.1. Kernel : unpack and patch sources

Run following command into a shell:

pushd $WORKDIR

mkdir -p kernel

tar xf st-image-weston-openstlinux-weston-stm32mp1/sources/arm-openstlinux_weston-linux-gnueabi/linux-stm32mp-4.19-r0/linux-4.19.*.tar.xz -C kernel

mv kernel/linux-* kernel/kernel-sources/

pushd kernel/kernel-sources/

for p in $(ls -1 ../../st-image-weston-openstlinux-weston-stm32mp1/sources/arm-openstlinux_weston-linux-gnueabi/linux-stm32mp-4.19-r0/*.patch); do patch -p1 < $p; done

popd

popd

5.2. Kernel : generate DTB

pushd $WORKDIR

cp -r MyDeviceTree_fromCubeMX/kernel kernel/dts

ls kernel/dts/

stm32mp157c-mydevicetree-mx.dts

pushd $WORKDIR

gcc -E -nostdinc -I kernel-sources/include/ -I kernel-sources/arch/arm/boot/dts -I dts -undef -D__DTS__ -x assembler-with-cpp -o stm32mp157c-mydevicetree-mx.dts.tmp dts/stm32mp157c-mydevicetree-mx.dts

dtc -I dts -O dtb -o stm32mp157c-mydevicetree-mx.dtb stm32mp157c-mydevicetree-mx.dts.tmp

popd

popd

5.3. Kernel : copy DTB on target/bootfs

• SCP method (require a up and running target with ssh service):

scp stm32mp157c-mydevicetree-mx.dtb root@<Target_IP>:/boot/

• mount loop device method:

Coming soon

Then if needed [#update extlinux] of target according this new dtb filename. This is only needed if the filename of the dtb generated is diferent from the one used by extlinux to boot.

6. U-Boot device tree update

This operation depends on the use of a mkimage with stm32 support for Windows^® which is not officially available.

• The usage of a a cross-compiler for Windows^® and mingw64, the latest mkimage version (provided by U-Boot) will allow you to generate a mkimage version
• Upon request, STMicroelectronics may provide an executable binary, without warranty nor support.

Here a procedure to rebuild U-Boot with a new DTS (generated with CubeMX for exemple).

Warning

Please notice only trusted mode is supported

• inputs: u-boot sources + patches, u-boot-nodtb.bin, u-boot dts
• host tools required: tar, patch, gcc (anyone), mkimage (with stm32 support), dtc

Here a zipfile with all inputs files used for testing Below the procedure with a mkimage with support of stm32image:

• U-Boot trusted

#########################################
#########################################
######################################### UBOOT
#########################################
#########################################
###################
################### UNPACK + PATCH
###################
[frq09494@lmecxl0985 ~/views/DTC]
$ mkdir -p u-boot
$ tar xf SOURCES-st-image-weston-openstlinux-weston-stm32mp1-openstlinux-4.19-thud-mp1-19-05-31/st-image-weston-openstlinux-weston-stm32mp1-openstlinux-4.19-thud-mp1-19-05-31/sources/arm-openstlinux_weston-linux-gnueabi/u-boot-stm32mp-2018.11-r0/v2018.11.tar.gz -C u-boot
$ mv u-boot/u-boot* u-boot/u-boot-sources/
$ pushd u-boot/u-boot-sources
for p in $(ls -1 ../../SOURCES-st-image-weston-openstlinux-weston-stm32mp1-openstlinux-4.19-thud-mp1-19-05-31/st-image-weston-openstlinux-weston-stm32mp1-openstlinux-4.19-thud-mp1-19-05-31/sources/arm-openstlinux_weston-linux-gnueabi/u-boot-stm32mp-2018.11-r0/*.patch); do patch -p1 < $p; done
$ popd

###################
################### GENERATE DTB
###################
[frq09494@lmecxl0985 ~/views/DTC/u-boot]
$ mkdir -p u-boot
$ pushd u-boot
$ cp -r ../MyDeviceTree_fromCubeMX/u-boot dts
[frq09494@lmecxl0985 ~/views/DTC/u-boot]
$ ll dts
total 36
-rw-r--r-- 1 frq09494 frq09494 25968 Jun  7 17:32 stm32mp157c-mydevicetree-mx.dts
-rw-r--r-- 1 frq09494 frq09494  3642 Jun  7 17:32 stm32mp157c-mydevicetree-mx-u-boot.dtsi
-rw-r--r-- 1 frq09494 frq09494  3511 Jun  7 17:32 stm32mp15-mx.h

## include dtsi u-boot file into dts of u-boot
$ echo '#include "stm32mp157c-mydevicetree-mx-u-boot.dtsi"' >> dts/stm32mp157c-mydevicetree-mx.dts

$ gcc -E -nostdinc -I u-boot-sources/include/ -I u-boot-sources/arch/arm/dts -I dts -undef -D__DTS__ -x assembler-with-cpp -o stm32mp157c-mydevicetree-mx.dts.tmp dts/stm32mp157c-mydevicetree-mx.dts
$ dtc -I dts -O dtb -o u-boot.dtb stm32mp157c-mydevicetree-mx.dts.tmp

###################
################### REBUILD UBOOT.stm32
###################
[frq09494@lmecxl0985 ~/views/DTC/u-boot]
$ cat SOURCES-st-image-weston-openstlinux-weston-stm32mp1-openstlinux-4.19-thud-mp1-19-05-31/st-image-weston-openstlinux-weston-stm32mp1-openstlinux-4.19-thud-mp1-19-05-31/sources/arm-openstlinux_weston-linux-gnueabi/u-boot-stm32mp-2018.11-r0/intermediate-binaries/trusted/u-boot-nodtb.bin u-boot.dtb > u-boot-dtb.bin
## SYS_TEXT_BASE=0xC0100000 is the addr of u-boot in memory (should never change)
$ export SYS_TEXT_BASE=0xC0100000
$ mkimage -T stm32image -a $SYS_TEXT_BASE -e $SYS_TEXT_BASE -d u-boot-dtb.bin u-boot.stm32

• Because of 'extlinux' before flashing the new u-boot.stm32, an extlinux entry should be add in bootfs to be able to boot on new devicetree

First get the 'compatible' of the devicetree from dts file. At the head of the file, look for the 'compatible = ' line. The compatible should looks like something as : "st,stm32mp157c-mydevicetree-mx"

* Add a new entry in extlinux.conf file located in /boot/mmc0_stm32mp157c-dk2_extlinux/.
:If the mmc0_<something> directory is not available, add the new entry in /boot/extlinux/extlinux.conf.

 menu title Select the boot mode
 MENU BACKGROUND ../splash.bmp
 TIMEOUT 20
 DEFAULT stm32mp157c-mydevicetree-mx
 LABEL stm32mp157c-dk2-sdcard
         KERNEL /uImage
         FDT /stm32mp157c-dk2.dtb
         APPEND root=/dev/mmcblk0p6 rootwait rw console=ttySTM0,115200
 LABEL stm32mp157c-dk2-a7-examples-sdcard
         KERNEL /uImage
         FDT /stm32mp157c-dk2-a7-examples.dtb
         APPEND root=/dev/mmcblk0p6 rootwait rw console=ttySTM0,115200
 LABEL stm32mp157c-dk2-m4-examples-sdcard
         KERNEL /uImage
         FDT /stm32mp157c-dk2-m4-examples.dtb
         APPEND root=/dev/mmcblk0p6 rootwait rw console=ttySTM0,115200
 LABEL stm32mp157c-mydevicetree-mx
        KERNEL /uImage
        FDT /stm32mp157c-mydevicetree-mx.dtb
        APPEND root=/dev/mmcblk0p6 rootwait rw console=ttySTM0,115200

Warning

Do not forget to synchronize the file system before rebooting the board sync

7. TF-A device tree update

This operation is not supported. It is currently not possible to modify TF-A device tree without recompiling TF-A module.

Device tree binary (or Blob)

Linux^® is a registered trademark of Linus Torvalds.

Microcontroller unit (MCUs have internal flash memory and are intended to operate with a minimum amount of external support ICs. They commonly are a self-contained, system-on-chip (SoC) designs.)

Microprocessor unit

Trusted firmware for Arm^® Cortex^®-A

Software development kit (A programming package that enables a programmer to develop applications for a specific platform.)

Device tree source (in software context) or digital temperature sensor (in peripheral context)

Secure coprocessor

Das U-Boot -- the universal boot loader (see U-Boot)