1. Purpose[edit source]
This article explains how to update the boot chain (trusted mode) for a "custom" device tree.
In paricular, STM32CubeMX can generate a "custom" device tree.
This article describes how to update the device tree compiled (DTB) part of the boot binaries.
2. Rationale[edit source]
There are various rationale 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 (or the opposite)
3. Prerequisites[edit source]
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 are the following:
- Starter package:
- the flashlayout as well as the images to flash, provided within the IMAGES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz file
- Developer package:
- the component sources and patches, provided within the SOURCES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz file
- the SDK toolchain, provided within the SDK-x86_64-st-image-weston-openstlinux-weston-stm32mp1.tar.xz file
- the STM32CubeProgrammer, which is the tool used to flash the images and binaries into the target board.
- 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 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
- Make sure the hardware configuration described in PC_prerequisites#Linux PC has been executed (even with a WSL2 setup)
4. Preparing your environment[edit source]
It is recommended to organize the numerous inputs described in #Pre-requisites in your environment.
First create a dedicated WORKDIR under your HOME folder and copy there all the inputs listed in #Pre-requisites:
- cd
- mkdir WORKDIR
- cd WORKDIR
- export WORKDIR="$PWD"
- tar --strip-components=1 -xf <IMAGES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz> -C $WORKDIR/
- tar --strip-components=1 -xf <SOURCES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz> -C $WORKDIR/
- tar --strip-components=1 -xf <SDK-st-image-weston-openstlinux-weston-stm32mp1.tar.xz> -C $WORKDIR/
- tar xf <MyDeviceTree_fromCubeMX.tar.xz> -C $WORKDIR/
Then proceed with the SDK installation.
The commands described in the rest of the document must be run in an SDK environment context: (Starting_up_the_SDK).
5. Kernel device tree update[edit source]
Updating the device tree 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[edit source]
Run following command into a shell:
- pushd $WORKDIR
- mkdir -p kernel
- tar xf 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 ../../sources/arm-openstlinux_weston-linux-gnueabi/linux-stm32mp-4.19-r0/*.patch); do patch -p1 < $p; done
- popd
- popd
5.2. Kernel : copy dts into source code[edit source]
- pushd $WORKDIR
- cp -r MyDeviceTree_fromCubeMX/kernel kernel/kernel-sources/arch/arm/boot/dts/
- popd
5.3. Kernel : regenerate kernel DTB[edit source]
- pushd $WORKDIR/kernel/kernel-sources
- make O="$PWD/../build" multi_v7_defconfig
- for f in `ls -1 ../fragment*.config`; do scripts/kconfig/merge_config.sh -m -r -O $PWD/../build $PWD/../build/.config $f; done
- make oldconfig O="$PWD/../build"
- make stm32mp157c-mydevicetree-mx LOADADDR=0xC2000040 O="$PWD/../build"
- popd
- ls -l $WORKDIR/kernel/build/arch/arm/boot/dts/stm32mp157c-mydevicetree-mx.dtb
5.4. Kernel : copy DTB into bootfs[edit source]
First of all update bootfs with the just new DTB to take it into account on next boot of the target.
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[edit source]
Updating the device tree of u-boot needs to replace the 'dtb' part of the u-boot binary.
By adding new device tree to u-boot source code, the Makefile will regenerate a new u-boot.stm32 containing the new 'dts'
6.1. U-boot : unpack and patch sources[edit source]
- pushd $WORKDIR
- mkdir -p u-boot
- tar xf sources/arm-openstlinux_weston-linux-gnueabi/u-boot-stm32mp-*/v*.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/arm-openstlinux_weston-linux-gnueabi/u-boot-stm32mp-*/*.patch); do patch -p1 < $p; done
- popd
6.2. U-boot : copy DTS in u-boot source code[edit source]
- pushd $WORKDIR
- cp MyDeviceTree_fromCubeMX/u-boot/* u-boot/u-boot-sources/arch/arm/dts/
- popd
Since u-boot 2019.04 version the device tree to compile must be explicitly wrote in dts Makefile:
- Please, add the device tree to compile into the u-boot/u-boot-sources/arch/arm/dts/Makefile file:
dtb-y += stm32mp157c-mydevicetree-mx.dtb
targets += $(dtb-y)
6.3. U-boot : regenerate u-boot.stm32[edit source]
- pushd $WORKDIR/u-boot/u-boot-sources
- make stm32mp15_<config>_defconfig
- <config> : could be trusted or basic according the boot type
- make DEVICE_TREE=<device tree> all
- <device tree> : is the device tree just copied, i.e.: stm32mp157c-mydevicetree-mx
- popd
- ls -l $WORKDIR/u-boot/u-boot-sources/u-boot.stm32
6.4. U-boot : copy u-boot on target[edit source]
- Because of 'extlinux' and before flashing the new u-boot.stm32, make sure #extlinux update is done according the 'compatible' value in DTS file.
- Then flash the u-boot.stm32 into 'ssbl' partition of the target with STM32CubeProgrammer
7. TF-A device tree update[edit source]
Updating the device tree of TF-A needs to replace the 'dtb'part of the TF-A binary.
TF-A binary allocates just after the 'mkimage" headers a 'fixed' zone for DTB. DTB is smaller than the reserved zone, padding is done with zero.
Below the procedure to generate TF-A with a new DTB and then flash it on target:
7.1. TF-A : unpack and patch sources[edit source]
- pushd $WORKDIR
- mkdir -p tf-a
- tar xf sources/arm-openstlinux_weston-linux-gnueabi/tf-a-stm32mp-*/v*.tar.gz -C tf-a
- mv tf-a/arm-trusted-firmware-* tf-a/tf-a-sources
- pushd tf-a/tf-a-sources
- for p in $(ls -1 ../../sources/arm-openstlinux_weston-linux-gnueabi/tf-a-stm32mp-*/*.patch); do patch -p1 < $p; done
- popd
- popd
7.2. TF-A : copy dts into source code[edit source]
- pushd $WORKDIR
- cp -r tf-a/MyDeviceTree_fromCubeMX/tf-a tf-a/tf-a-sources/fdts/
- popd
7.3. TF-A : regenerate TF-A.stm32[edit source]
- pushd $WORKDIR/tf-a/tf-a-sources
- make -f $PWD/../Makefile.sdk TFA_DEVICETREE=<device tree> TF_A_CONFIG=<config> all
- <config> : could be trusted or basic according the boot type
- <device tree> : is the device tree just copied, i.e.: stm32mp157c-mydevicetree-mx
- popd
- ls -l $WORKDIR/tf-a/build/<config>/tf-a-<device tree>-<config>.stm32
7.4. TF-A : copy DTB on target/bootfs[edit source]
Then flash the tf-a-*.stm32 into the 'fsbl1' and 'fsbl2' partitions of the target with STM32CubeProgrammer
8. Update methods[edit source]
8.1. bootfs update[edit source]
- On a target up and running
- scp stm32mp157c-mydevicetree-mx.dtb root@<Target_IP>:/boot/
- Into 'bootfs' image directly
This method doesn't need to have a target up and running but only need the "st-image-bootfs-openstlinux-weston-stm32mp1.ext4" file. To modify a 'ext4' file, a loopback mount tool is need which is avaible in any Linux Distribution (even through WSL2):
- mkdir -p $WORKING/bootfs
- mount -o loop <st-image-bootfs-openstlinux-weston-stm32mp1.ext4> $WORKING/bootfs
- ##Then copy the new dtb file at the root of $WORKING/bootfs
- umount $WORKING/bootfs
- sync
- dd if=<st-image-bootfs-openstlinux-weston-stm32mp1.ext4> of=/dev/mmblk0p4 conv=fdatasync
8.2. extlinux update[edit source]
8.2.1. extlinux : basics[edit source]
'extlinux' is a collection of scripts/config files describing how u-boot should boots. Updating extlinux consists in updating the extlinux.conf.
- As exemple by using a DK-2 board and booting on sdcard, then the extlinux.conf file is located in "/boot/mmc0_stm32mp157c-dk2_extlinux/".
- If "mmc0_<something>_extlinux" directory is not available, please use "/boot/extlinux/extlinux.conf" file instead.
'extlinux.conf' is the description of a boot menu with one or several entries, 'DEFAULT' selects the one to use by default .
Below an exemple of file:
menu title Select the boot mode MENU BACKGROUND ../splash.bmp TIMEOUT 5 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
In example above the highlighted lines may need to be updated/added by this wiki page:
- DEFAULT: This is the default 'LABEL' to boot
- LABEL : The entry 'LABEL' is the value of 'compatible' of the DTS file compiled with u-boot.
- The 'compatible' value is at head of the DTS file and looks like : "st,stm32mp157c-mydevicetree-mx"
- FDT : The path from /boot of the kernel DTB to use
8.2.2. extlinux : updating[edit source]
Updating 'extlinux' consists into modifying the extlinux.conf. There are 2 ways to proceed:
- On a target up and running
Open a ssh connection to the target or directly with tty terminal, and then use an editor as 'vi' to modify the extlinux.conf file.
- Do not forget to synchronize the file system before rebooting the target:
- sync
- Into 'bootfs' image directly
This method doesn't need to have a target up and running but only need the "st-image-bootfs-openstlinux-weston-stm32mp1.ext4" file. To modify a 'ext4' file, a loopback mount tool is need which is avaible in any Linux Distribution (even through WSL2):
- mkdir -p $WORKING/bootfs
- mount -o loop <st-image-bootfs-openstlinux-weston-stm32mp1.ext4> $WORKING/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