Template:ArticleMainWriter Template:ArticleFirstDraftVersion Template:ReviewersList
1. Purpose[edit source]
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[edit source]
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[edit source]
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 :
- need flashlayout and images to flash provided from file IMAGES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz
- 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[edit source]
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[edit source]
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[edit source]
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[edit source]
- 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
- Template:Highlight3
- popd
- popd
5.3. Kernel : copy DTB on target/bootfs[edit source]
- 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[edit source]
Updating the devicetree of u-boot needs to replace the 'dtb'part of the u-boot binary.
Indeed u-boot binary is the "concatenation' of the 'dtb' and the 'u-boot' and then packaged with 'mkimage' for stm32.
Below the procedure to generate u-boot with a new DTB and then flash it on "u-boot" partition:
6.1. U-boot : unpack and patch sources[edit source]
- pushd $WORKDIR
- mkdir -p u-boot
- tar xf st-image-weston-openstlinux-weston-stm32mp1/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 ../../st-image-weston-openstlinux-weston-stm32mp1/sources/arm-openstlinux_weston-linux-gnueabi/u-boot-stm32mp-*/*.patch); do patch -p1 < $p; done
- popd
6.2. U-boot : generate DTB[edit source]
- pushd $WORKDIR/u-boot
- cp -r ../MyDeviceTree_fromCubeMX/u-boot dts
- ls -1 dts
- stm32mp157c-mydevicetree-mx.dts
- stm32mp157c-mydevicetree-mx-u-boot.dtsi
- stm32mp15-mx.h
- ## Need to 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
- popd
6.3. U-boot : regenerate u-boot.stm32[edit source]
- pushd $WORKDIR/u-boot
- cat st-image-weston-openstlinux-weston-stm32mp1/sources/arm-openstlinux_weston-linux-gnueabi/u-boot-stm32mp-*/intermediate-binaries/trusted/u-boot-nodtb.bin u-boot.dtb > u-boot-dtb.bin
- #464650
- export SYS_TEXT_BASE=0xC0100000
- mkimage -T stm32image -a $SYS_TEXT_BASE -e $SYS_TEXT_BASE -d u-boot-dtb.bin 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 the 'extlinux.conf' file, present in '/boot' and used for boot, has an entry ('LABEL') according the 'compatible' value in DTS file.
The 'compatible' value is at head of the DTS file. The compatible should looks like something as : "st,stm32mp157c-mydevicetree-mx"
- For exemple if you are 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, add an entry in "/boot/extlinux/extlinux.conf" file instead.
- If needed update 'DEFAULT' value also.
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
At least 2 methods exist to update the "/boot" filesystem partition, please refer to #update bootfs chapter.
7. TF-A device tree update[edit source]
Updating the devicetree 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 st-image-weston-openstlinux-weston-stm32mp1/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 ../../st-image-weston-openstlinux-weston-stm32mp1/sources/arm-openstlinux_weston-linux-gnueabi/tf-a-stm32mp-*/*.patch); do patch -p1 < $p; done
- popd
- popd
7.2. TF-A : generate DTB[edit source]
- pushd $WORKDIR/tf-a
- cp -r ../MyDeviceTree_fromCubeMX/tf-a dts
- ls -1 dts/
- stm32mp157c-mydevicetree-mx.dts
- stm32mp15-mx.h
- gcc -E -nostdinc -I tf-a-sources/include/ -I tf-a-sources/fdts -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 tf-a.dtb stm32mp157c-mydevicetree-mx.dts.tmp
- popd
7.3. TF-A : regenerate TF-A.stm32[edit source]
- ## OFFSET of DTB in tf-a.bin (fixed offset) : 0xBB00 (47872 in decimal)
- ## OFFSET of BL2 in tf-a.bin (fixed offset) : 0x17B00 (97024 in decimal)
- cp st-image-weston-openstlinux-weston-stm32mp1/sources/arm-openstlinux_weston-linux-gnueabi/tf-a-stm32mp-*/intermediate-binaries/trusted/tf-a-Template:LightBlue.bin tf-a.bin
- # Delete dtb from tf-a.bin
- dd conv=notrunc if=/dev/zero of=tf-a.bin bs=97024 count=1
- # copy new dtb into tf-a.bin
- dd conv=notrunc if=tf-a.dtb of=tf-a.bin seek=47872 obs=1
- ## SYS_TEXT_DATA=0x2FFC2500 is the addr of tf-a in memory (could be found in tf-a.map address of '.data' section)
- ## SYS_TEXT_BL2=0x2FFD4000 is the entry point of tf-a (could be found in tf-a.map address of '.bl2_image' section)
- mkimage -T stm32image -a $SYS_TEXT_DATA -e $SYS_TEXT_BL2 -d tf-a.bin tf-a.stm32
7.4. TF-A : copy DTB on target/bootfs[edit source]
To flash the tf-a.stm32 into target you can use STM32CubeProgrammer or use 'dd' to only flash the TF-A partition:
- dd if=tf-a.stm32 of=/dev/mmcblk0p1 conv=fdatasync
- dd if=tf-a.stm32 of=/dev/mmcblk0p2 conv=fdatasync
Information |
The '/dev/mmcblk0pX' are in case of the sdcard is inserted in dedicated drive of the PC, using an USB sdcard reader will probably create /dev/sdX entries. |