How to compile the device tree with the Developer Package

Applicable for

STM32MP15x lines

---

1. Purpose

This article explains how to update the boot chain (OP-TEE with FIP) for a "custom" device tree.
This article concentrates in particular on generating a "custom" device tree based on theSTM32CubeMX.

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

2. Rationale

There are various reasons for using a custom device tree, such as:

• the description of a new and private board
• the swapping of some internal peripherals from Cortex^®-M side to Cortex-A side (and vice versa)

3. Prerequisites

Information

Even if STMicroelectronics strongly recommends to use a Linux® environment, the steps described in this article can be executed in a WSL2 (Windows Sub-system Linux 2) environment.

Compiling a new device tree means updating three software components belonging to the complete boot chain (trusted mode), Trusted Firmware A (TF-A), U-Boot, and Linux kernel.

The material required to update the above software components is the following:

• Starter package:
  • the flashlayout as well as the images to flash, provided within the en.FLASH-stm32mp1-openstlinux-5.15-yocto-kirkstone-mp1-v22.11.23.tar.gz file
• Developer package:
  • the component sources and patches, provided within the en.SOURCES-stm32mp1-openstlinux-5.15-yocto-kirkstone-mp1-v22.11.23.tar.gz file
  • the SDK toolchain, provided within the en.SDK-x86_64-stm32mp1-openstlinux-5.15-yocto-kirkstone-mp1-v22.11.23.tar.gz file
• the STM32CubeProgrammer, which is the tool used to flash the images and binaries into the target.

• Custom device tree sources:
  • In the rest of this document, we assume that the custom device tree is generated by STM32CubeMX and stored in a MyDeviceTree_fromCubeMX.tar.xz tarball with following file tree:

MyDeviceTree_fromCubeMX
|-- kernel
|   |-- stm32mp157f-mydevicetree-mx.dts
|-- tf-a
|  |-- stm32mp157f-mydevicetree-mx.dts
|  |-- stm32mp157f-mydevicetree-mx-fw-config.dts
|  |-- stm32mp15-mx.dtsi
|-- u-boot
|  |-- stm32mp157f-mydevicetree-mx.dts
|  |-- stm32mp157f-mydevicetree-mx-u-boot.dtsi
|  |-- stm32mp15-mx.dtsi

• Make sure the hardware configuration described in the PC prerequisites article has been executed (even with a WSL2 setup)

4. Preparing your environment

It is recommended to organize the numerous inputs described in #Prerequisites in your environment.
First create a dedicated WORKDIR under your HOME folder and copy there all the inputs listed in #Prerequisites:

cd $HOME

mkdir WORKDIR

cd WORKDIR

export WORKDIR="$PWD"

tar --strip-components=1 -xf en.FLASH-stm32mp1-openstlinux-5.15-yocto-kirkstone-mp1-v22.11.23.tar.gz -C $WORKDIR/

tar --strip-components=1 -xf en.SOURCES-stm32mp1-openstlinux-5.15-yocto-kirkstone-mp1-v22.11.23.tar.gz -C $WORKDIR/

tar --strip-components=1 -xf en.SDK-x86_64-stm32mp1-openstlinux-5.15-yocto-kirkstone-mp1-v22.11.23.tar.gz -C $WORKDIR/

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

Then proceed with the STM32MP1_Developer_Package#Installing_the_SDK chapter.

The commands described in the rest of the document must be run in an SDK environment context: (STM32MP1_Developer_Package#Starting_up_the_SDK).

5. Updating the kernel device tree

Since 'extlinux.conf' explicitly points to the DTB, just update the kernel device tree by replacing the DTB file of the '/boot' partition. The path used must be something like '/boot/<devicetree>.dtb'.

The following chapters describe the procedure to generate and copy the new DTB into the target.

5.1. Kernel : unpack and patch sources

Information

The procedure below is an extract of the README.HOW_TO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/linux-stm32mp-*. Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of kernel

.

Run the following command into a shell:

pushd $WORKDIR

mkdir -p kernel

tar xf sources/arm-ostl-linux-gnueabi/linux-stm32mp-*/linux-*.tar.xz -C kernel

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

pushd kernel/kernel-sources/

for p in $(ls -1 ../../sources/arm-ostl-linux-gnueabi/linux-stm32mp-*/*.patch); do patch -p1 < $p; done

popd

popd

5.2. Kernel : copy the DTS into the source code

pushd $WORKDIR

cp -r MyDeviceTree_fromCubeMX/kernel/* kernel/kernel-sources/arch/arm/boot/dts/

popd

5.3. Kernel : regenerate the kernel DTB

Information

The procedure below is an extract of the README.HOW_TO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/linux-stm32mp-*. Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of kernel

.

pushd $WORKDIR/kernel/kernel-sources

make ARCH=arm O="$PWD/../build" multi_v7_defconfig fragment*.config

for f in `ls -1 ../../sources/arm-ostl-linux-gnueabi/linux-stm32mp-*/fragment*.config`; do scripts/kconfig/merge_config.sh -m -r -O $PWD/../build $PWD/../build/.config $f; done

yes "" | make ARCH=arm oldconfig O="$PWD/../build"

make stm32mp157f-mydevicetree-mx.dtb LOADADDR=0xC2000040 O="$PWD/../build"

popd

ls -l $WORKDIR/kernel/build/arch/arm/boot/dts/stm32mp157f-mydevicetree-mx.dtb

5.4. Kernel : copy the DTB into bootfs

First, update all the #Updating bootfs with the new DTB for it to be taken it into account on the next boot of the target.

Then, if needed, edit by #Updating extlinux for the target with this new DTB filename. This is only required if the filename of the generated DTB is different from the one used by extlinux to boot.

6. Updating BOOT firmwares

The BOOT firmwares are TF-A and U-Boot and must be updated together (CubeMX provides devicetree for TF-A and U-Boot).

6.1. Updating the TF-A device tree

To update the TF-A device tree, replace the DTB part of the TF-A binary.
The TF-A binary allocates a 'fixed' area for the DTB, just after the 'mkimage" headers. If the DTB is smaller than the reserved area, the remaining memory is padded with zero.

Below the procedure to generate TF-A with a new DTB and then flash it on the target:

6.1.1. TF-A : unpack and patch sources

Information

The procedure below is an extract of the README.HOW_TO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*. Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of tf-a

.

pushd $WORKDIR

pushd sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-v[0-9]*

mkdir -p tf-a-sources

tar xf tf-a-stm32mp-v[0-9]*.tar.* --one-top-level=tf-a-sources --strip-components=1

pushd tf-a-sources

for p in `ls -1 ../*.patch`; do patch -p1 < $p; done

popd

popd

6.1.2. TF-A : copy the DTS into the source code

pushd $WORKDIR

cp -r MyDeviceTree_fromCubeMX/tf-a/* sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-v[0-9]*/tf-a-sources/fdts/

popd

6.1.3. TF-A : regenerate TF-A

Information

The procedure below is an extract of the README.HOW_TO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*. Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of tf-a

.

First only the TF-A "intermediates" artifacts are generated, the FIP image will be generated at final step (U-Boot compilation).

pushd $WORKDIR/sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-v[0-9]*/tf-a-sources

export FIP_DEPLOYDIR_ROOT=$PWD/../../FIP_artifacts

make -f ../Makefile.sdk TF_A_DEVICETREE=<devicetree_name> TF_A_CONFIG="optee emmc nand nor sdcard uart usb" DEPLOYDIR=$FIP_DEPLOYDIR_ROOT/arm-trusted-firmware stm32

<devicetree_name> : is the device tree just copied, i.e.: stm32mp157f-mydevicetree-mx

DEPLOYDIR is the path where intermediate binaries of tf-a should be deployed (requiered by fip-tools to generate fip image)

popd

6.2. Updating the OP-TEE device tree

To update the OP-TEE device tree, replace the DTB part of the OP-TEE binary.
Adding a new device tree to the OP-TEE source code forces the Makefile to regenerate new OP-TEE binaries.
The following chapters describe the procedure to update the OP-TEE device tree.

6.2.1. OP-TEE: unpack and patch sources

Information

The procedure below is an extract of the README.HOW_TO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-*. Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of OP-TEE

.

pushd $WORKDIR

pushd sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-[0-9]*

tar xf optee-os-stm32mp-[0-9]*.tar.* --one-top-level=optee-os-sources --strip-components=1

pushd optee-os-sources

tar xfz ../fonts.tar.gz

for p in `ls -1 ../*.patch`; do patch -p1 < $p; done

popd

popd

6.2.2. OP-TEE: copy the DTS in the source code

pushd $WORKDIR

cp MyDeviceTree_fromCubeMX/optee/* sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-*/optee-os-sources/core/arch/arm/dts/

popd

6.2.3. OP-TEE: regenerate fip image within new OP-TEE

Information

The procedure below is an extract of the README.HOW_TO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-*. Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of OP-TEE

.

pushd $WORKDIR/sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-[0-9]*/optee-os-sources

make -f ../Makefile.sdk CFG_EMBED_DTB_SOURCE_FILE=<device tree> OPTEE_DRAMSIZE=<RAM size> DEPLOYDIR=~/views/temp/CubeIde/WORKDIR/sources/arm-ostl-linux-gnueabi/FIP_artifacts/optee optee

<device tree> : is the device tree just copied, i.e.: stm32mp157f-mydevicetree-mx

<RAM size>  : is the RAM size of the board selected by the device treee, i.e.: 0x20000000

popd

6.3. Updating the U-Boot device tree

To update the U-Boot device tree, replace the U-Boot DTB in FIP image.

6.3.1. U-Boot : unpack and patch sources

Information

The procedure below is an extract of the README.HOW_TO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-*. Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of U-Boot

.

pushd $WORKDIR

pushd sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-v[0-9]*

tar xf u-boot-stm32mp-v[0-9]*.tar.* --one-top-level=u-boot-sources --strip-components=1

pushd u-boot-sources

for p in `ls -1 ../*.patch`; do patch -p1 < $p; done

popd

popd

6.3.2. U-Boot : copy the DTS in the U-Boot source code

pushd $WORKDIR

cp MyDeviceTree_fromCubeMX/u-boot/* sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-v[0-9]*/u-boot-sources/arch/arm/dts/

popd

6.3.3. U-Boot : regenerate fip image within new U-Boot binary

Information

The procedure below is an extract of the README.HOW_TO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-*. Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of U-Boot

.

pushd $WORKDIR/sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-v[0-9]*/u-boot-sources

make -f ../Makefile.sdk UBOOT_CONFIG=trusted UBOOT_DEFCONFIG=<stm32mpu device>_defconfig UBOOT_BINARY=u-boot.dtb FIP_CONFIG="optee" DEVICETREE=<device tree> all

<stm32mpu device> : is the targetted stm32mpu device, stm32mp13 or stm32mp15

<device tree> : is the device tree just copied, i.e.: stm32mp157f-mydevicetree-mx

popd

6.3.4. U-Boot : copy U-Boot binary into the target

• Because of 'extlinux' and before flashing the new fip image, make sure #Updating extlinux is compliant with the 'compatible' value in the DTS file.
  
• Then, using STM32CubeProgrammer, flash the tf-a-xxxx.stm32 file (generated at tf-a step) into the 'fsbl1' and 'fsbl2' partition of the target and the 'fip-a' partition with fip-stm32mpxxxx.bin file (generated just above).

7. Update methods

7.1. Updating extlinux

7.1.1. extlinux basics

extlinux describes how U-Boot boots. Updating extlinux consists in updating the extlinux.conf:

• In case of an DK-2 board booting from the sdcard. A stm32mp157f-dk2_extlinux.conf file is located in /boot/mmc0_extlinux/,
• otherwise if there is no specific extlinux.conf for your board, then the extlinux.conf is taking into account.

extlinux.conf is the description of a boot menu with one or several entries; 'DEFAULT' selects the default entry.
Below an example of extlinux.conf:

menu title Select the boot mode
MENU BACKGROUND ../splash.bmp
TIMEOUT 5
DEFAULT stm32mp157f-mydevicetree-mx
LABEL stm32mp157f-dk2-sdcard
        KERNEL /uImage
        FDTDIR /
        APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
LABEL stm32mp157f-dk2-a7-examples-sdcard
        KERNEL /uImage
        FDT /stm32mp157f-dk2-a7-examples.dtb
        APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
LABEL stm32mp157f-dk2-m4-examples-sdcard
        KERNEL /uImage
        FDT /stm32mp157f-dk2-m4-examples.dtb
        APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
LABEL stm32mp157f-mydevicetree-mx
       KERNEL /uImage
       FDT /stm32mp157f-mydevicetree-mx.dtb
       APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200

Update/add the highlighted lines according to what have been compiled in chapter 5, 6 and/or 7:

• DEFAULT: This is the default 'LABEL' to boot
• LABEL : The entry 'LABEL' is the value of 'compatible' of the DTS file used by U-Boot.

  The 'compatible' value is at head of the DTS file and looks like : "st,stm32mp157f-mydevicetree-mx"

• FDT : The path from /boot of the kernel DTB to use

7.2. Updating bootfs

There are two methods to update bootfs:

• On an up and running target

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

• Directly into 'bootfs' image

You do not need to have a target up and running. Only the "st-image-bootfs-openstlinux-weston-stm32mp1.ext4" file is required. To modify an 'ext4' file, a loopback mount, available within any Linux Distribution (even through WSL2), is required:

mkdir -p $WORKDIR/bootfs

mount -o loop <st-image-bootfs-openstlinux-weston-stm32mp1.ext4> $WORKDIR/bootfs

##Then copy the new dtb file at the root of $WORKDIR/bootfs

umount $WORKDIR/bootfs

sync

Then use STM32CubeProgrammer to update the bootfs partition.

7.2.1. Updating extlinux

Updating 'extlinux' consists in modifying the extlinux.conf. There are two ways to proceed:

• On an up and running target

Open an ssh connection to the target or use a direct connection with a tty terminal. Then use an vi editor to modify the extlinux.conf file.

Do not forget to synchronize the file system before rebooting the target:

sync

• Into 'bootfs' image directly

You do not need to have a target up and running. Only the "st-image-bootfs-openstlinux-weston-stm32mp1.ext4" file is required. To modify an 'ext4' file, a loopback mount tool, available in any Linux Distribution (even through WSL2), is needed:

mkdir -p $WORKDIR/bootfs

sudo mount -o loop <st-image-bootfs-openstlinux-weston-stm32mp1.ext4> $WORKDIR/bootfs

##Then edit the extlinux.conf file (for WSL2 use a 'Linux' type editor; vi, ...)

##Once extlinux.conf up-to-date, umount loopback and flash the bootfs into sdcard with STM32CubeProgrammer

Open portable trusted execution environment

Firmware image package is a packaging format used by TF-A

Device tree binary (or Blob)

Cortex^®

Linux^® is a registered trademark of Linus Torvalds.

Trusted firmware for Arm^® Cortex^®-A

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

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)

Random access memory (Early computer memories generally hadserial access. Memories where any given address can be accessed when desired were then called "random access" to distinguish them from the memories where contents can only be accessed in a fixed order. The term is used today for volatile random-acces ssemiconductor memories.)

Open portable trusted execution environment

Firmware image package is a packaging format used by TF-A

Device tree binary (or Blob)

Cortex^®

Linux^® is a registered trademark of Linus Torvalds.

Trusted firmware for Arm^® Cortex^®-A

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

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)

Random access memory (Early computer memories generally hadserial access. Memories where any given address can be accessed when desired were then called "random access" to distinguish them from the memories where contents can only be accessed in a fixed order. The term is used today for volatile random-acces ssemiconductor memories.)

Arm^® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.