1. Purpose[edit | edit source]
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 the STM32CubeMX.
This article describes how to update the device tree compiled (DTB) part of the boot binaries.
2. Rational[edit | edit source]
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[edit | edit source]
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 Firmware-A (TF-A), U-Boot, and Linux kernel.
The material required to update the above software components is the following:
- Starter Package:
- For STM32MP1 series: en.FLASH-stm32mp1-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06.tar.gz
- For STM32MP2 series: en.FLASH-stm32mp2-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06.tar.gz
- Developer package:
- the component sources and patches:
- For STM32MP1 series: en.SOURCES-stm32mp1-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06.tar.gz
- For STM32MP2 series: en.SOURCES-stm32mp1-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06.tar.gz
- the SDK toolchain:
- For STM32MP1 series: en.SDK-x86_64-stm32mp1-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06.tar.gz
- For STM32MP2 series: en.SDK-x86_64-stm32mp1-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06.tar.gz
- the component sources and patches:
- 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 MyDeviceTree_fromCubeMX/ ├── kernel │ └── <soc-machine>-mx.dts ├── optee-os │ └── <soc-machine>-mx.dts ├── tf-a │ ├── <soc-machine>-mx.dts │ ├── <soc-machine>-mx-fw-config.dts │ └── <soc-machine>-mx.dtsi └── u-boot ├── <soc-machine>-mx.dts └── <soc-machine>-mx-u-boot.dtsi
- Make sure the hardware configuration described in the PC prerequisites article has been executed (even with a WSL2 setup)
4. Preparing your environment[edit | edit source]
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-6.6-yocto-scarthgap-mpu-v24.11.06.tar.gz -C $WORKDIR/ tar --strip-components=1 -xf en.SOURCES-stm32mp1-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06.tar.gz -C $WORKDIR/ tar --strip-components=1 -xf en.SDK-x86_64-stm32mp1-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06.tar.gz -C $WORKDIR/ tar xf <MyDeviceTree_fromCubeMX.tar.xz> -C $WORKDIR/
Then proceed with the STM32MPU_Developer_Package#Installing_the_SDK chapter.
The commands described in the rest of the document must be run in an SDK environment context: (STM32MPU_Developer_Package#Starting_up_the_SDK).
5. Updating the kernel device tree[edit | edit source]
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[edit | edit source]
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
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series |
---|---|
arm-ostl-linux-gnueabi | aarch64-ostl-linux |
5.2. Kernel : copy the DTS into the source code[edit | edit source]
pushd $WORKDIR
cp -r MyDeviceTree_fromCubeMX/kernel/* kernel/kernel-sources/arch/arm/boot/dts/st/
popd
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series |
---|---|
arm | arm64 |
5.3. Kernel : regenerate the kernel DTB[edit | edit source]
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 |
.
For STM32MP1 series:
pushd $WORKDIR/kernel/kernel-sources export OUTPUT_BUILD_DIR=$PWD/../build mkdir -p ${OUTPUT_BUILD_DIR} make ARCH=arm O="${OUTPUT_BUILD_DIR}" 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 ${OUTPUT_BUILD_DIR} ${OUTPUT_BUILD_DIR}/.config $f; done (yes "" || true ) | make ARCH=arm oldconfig O="${OUTPUT_BUILD_DIR}" make ARCH=arm st/stm32mp135f-stm32mp135f-dk-mx.dtb LOADADDR=0xC2000040 O="${OUTPUT_BUILD_DIR}" popd ls -l $WORKDIR/kernel/build/arch/arm/boot/dts/st/stm32mp135f-stm32mp135f-dk-mx.dtb
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series |
---|---|
multi_v7_defconfig | defconfig |
arm-ostl-linux-gnueabi | aarch64-ostl-linux |
arm | arm64 |
st/stm32mp135f-stm32mp135f-dk-mx.dtb | st/stm32mp257f-stm32mp257f-dk-mx.dtb or anything else ... |
5.4. Kernel : copy the DTB into bootfs[edit | edit source]
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[edit | edit source]
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[edit | edit source]
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 STM32 image header. 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[edit | edit source]
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
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series |
---|---|
arm-ostl-linux-gnueabi | aarch64-ostl-linux |
6.1.2. TF-A : copy the DTS into the source code[edit | edit source]
pushd $WORKDIR
cp -r MyDeviceTree_fromCubeMX/tf-a/* sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-v[0-9]*/tf-a-sources/fdts/
popd
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series |
---|---|
arm-ostl-linux-gnueabi | aarch64-ostl-linux |
6.1.3. TF-A : regenerate TF-A[edit | edit source]
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="<boot scheme>-<device storage> <boot scheme>-<programmer-serialtype>" DEPLOYDIR=$FIP_DEPLOYDIR_ROOT/arm-trusted-firmware stm32 popd
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series | |
---|---|---|
arm-ostl-linux-gnueabi | aarch64-ostl-linux | |
<devicetree_name> | stm32mp135f-stm32mp135f-dk-mx | stm32mp257f-stm32mp257f-dk-mx or what else |
<boot scheme> | optee | |
<device storage> | sdcard | |
<programmer-serialtype> | programmer-usb |
6.2. Updating the OP-TEE device tree[edit | edit source]
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[edit | edit source]
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
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series |
---|---|
arm-ostl-linux-gnueabi | aarch64-ostl-linux |
6.2.2. OP-TEE: copy the DTS in the source code[edit | edit source]
pushd $WORKDIR
cp MyDeviceTree_fromCubeMX/optee-os/* sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-*/optee-os-sources/core/arch/arm/dts/
popd
For STM32MP2 series:
please replace green words:
STM32MP1 series | STM32MP2 series |
---|---|
arm-ostl-linux-gnueabi | aarch64-ostl-linux |
6.2.3. OP-TEE: regenerate OP-TEE binaries[edit | edit source]
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/sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-[0-9]*/optee-os-sources export FIP_DEPLOYDIR_ROOT=$PWD/../../FIP_artifacts make -f ../Makefile.sdk OPTEE_CONFIG="optee" CFG_EMBED_DTB_SOURCE_FILE=<device tree> CFG_DRAM_SIZE=<RAM size> DEPLOYDIR=$WORKDIR/sources/arm-ostl-linux-gnueabi/FIP_artifacts/optee optee popd
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series | |
---|---|---|
arm-ostl-linux-gnueabi | aarch64-ostl-linux | |
CFG_DRAM_SIZE=<RAM size> | CFG_DRAM_SIZE=0x20000000 (for 512MB ramsize) | (for STM32MP2 series no need to specify ramsize) |
<device tree> | stm32mp135f-stm32mp135f-dk-mx | stm32mp257f-stm32mp257f-dk-mx |
6.3. Updating the U-Boot device tree[edit | edit source]
To update the U-Boot device tree, replace the U-Boot DTB in FIP image.
6.3.1. U-Boot : unpack and patch sources[edit | edit source]
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
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series |
---|---|
arm-ostl-linux-gnueabi | aarch64-ostl-linux |
6.3.2. U-Boot : copy the DTS in the U-Boot source code[edit | edit source]
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
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series |
---|---|
arm-ostl-linux-gnueabi | aarch64-ostl-linux |
6.3.3. U-Boot : regenerate U-boot binaries and fip image[edit | edit source]
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_DEFCONFIG=<stm32mpu device>_defconfig UBOOT_BINARY=u-boot.dtb FIP_CONFIG="optee-sdcard" DEVICE_TREE=<device tree> all
- <device tree> : is the device tree just copied, i.e.: stm32mp135f-stm32mp135f-dk-mx
popd
For STM32MP2 series: please replace green words:
STM32MP1 series | STM32MP2 series | |
---|---|---|
arm-ostl-linux-gnueabi | aarch64-ostl-linux | |
<stm32mpu device> | stm32mp13 (or stm32mp15) | stm32mp23 or stm32mp25 |
<device tree> | stm32mp135f-stm32mp135f-dk-mx | stm32mp257f-stm32mp257f-dk-mx |
6.4. copy new Boot chain into the target[edit | edit source]
- 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-sdcard.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).
Information |
Note according what have been modifed in devicetree, it might be needed to reset the partition 'u-boot-env' and reflash the partition 'fsbl-boot' with tf-a-xxxx-usb.stm32 file (generated at tf-a step) and 'fip-boot' partition with fip-stm32mpxxxx.bin file (generated just above) |
7. Update methods[edit | edit source]
7.1. Updating extlinux[edit | edit source]
7.1.1. extlinux basics[edit | edit source]
extlinux describes how U-Boot boots (see Generic Distro features for details). Updating extlinux consists in updating the extlinux.conf:
- A 135f-dk board booting from the sdcard use a specific extlinux.conf file from /boot/mmc0_extlinux/ (<device tree name>_extlinux.conf),
- otherwise if there is no specific extlinux.conf for your board/device tree, 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 the content of the extlinux.conf located into /boot/mmc0_extlinux needed to boot with the device tree + boot chain just generated:
menu title Select the boot mode MENU BACKGROUND /splash_landscape.bmp TIMEOUT 20 DEFAULT stm32mp135f-stm32mp135f-dk-mx LABEL OpenSTLinux KERNEL /uImage FDTDIR / INITRD /st-image-resize-initrd APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=${console},${baudrate} LABEL stm32mp135f-stm32mp135f-dk-mx KERNEL /uImage FDT /stm32mp135f-stm32mp135f-dk-mx.dtb APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=${console},${baudrate}
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,stm32mp135f-stm32mp135f-dk-mx"
- FDT : The path from /boot of the kernel DTB to use
7.2. Updating bootfs[edit | edit source]
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[edit | edit source]
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