How to compile the device tree with the Developer Package

Revision as of 10:16, 11 September 2019 by Registered User (→‎Kernel : unpack and patch sources)

Template:ArticleMainWriter Template:ArticleProposedVersion Template:ReviewersList


Warning white.png Warning
This page need to be renamed. Do you have any suggestion ?
My proposal is: HowTo update devicetree of bootchain

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.

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]


Info white.png Information
Even if STMicroelectronics strongly recommends to use a Linux® environment, this article works in WSL2 (Windows Sub-system Linux 2) environment. WSL2 is available on Windows 10® since builds 18917.

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 which are provided by file SOURCES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz
    • Need SDK toolchain which is provided by file SDK-x86_64-st-image-weston-openstlinux-weston-stm32mp1.tar.xz
  • (optionnal) 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"
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 in the SDK installation.


Commands of the rest of the document should be run in a SDK environment context (Starting_up_the_SDK).

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 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 : 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 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 devicetree of u-boot needs to replace the 'dtb' part of the u-boot binary.
By adding new devicetree 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 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 : copy DTS in u-boot source code[edit source]

pushd $WORKDIR/u-boot/u-boot-sources
cp ../../MyDeviceTree_fromCubeMX/u-boot/* arch/arm/dts/
popd

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 devicetree 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 else using 'dd' as following :
dd if=u-boot.stm32 of=Template:Highlight3 conv=fdatasync
Info white.png Information
The '/dev/mmcblk0p3' is in case of the sdcard is inserted in dedicated drive of the PC, using an USB sdcard reader will probably create /dev/sdb3 entry.

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]

Info white.png Information
The procedure below is equivalent to chapter 3 of the README_HOWTO.txt file available in $WORKDIR/st-image-weston-openstlinux-weston-stm32mp1/sources/arm-openstlinux_weston-linux-gnueabi/tf-a-stm32mp-*
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 : copy dts into source code[edit source]

pushd $WORKDIR/tf-a
cp -r ../MyDeviceTree_fromCubeMX/tf-a tf-a-sources/fdts/
popd

7.3. TF-A : regenerate TF-A.stm32[edit source]

Info white.png Information
The procedure below is equivalent to chapter 5 of the README_HOWTO.txt file available in $WORKDIR/st-image-weston-openstlinux-weston-stm32mp1/sources/arm-openstlinux_weston-linux-gnueabi/tf-a-stm32mp-*
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 devicetree 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 else use 'dd' as follow:

dd if=tf-a.stm32 of=Template:Highlight3 conv=fdatasync
dd if=tf-a.stm32 of=Template:Highlight3 conv=fdatasync
Warning white.png Warning
'fsbl1' and 'fsbl2' are two redondant partitions and so, they should have same content
Info white.png 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/sdbX entries.

8. Update methods[edit source]

8.1. bootfs update[edit source]

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

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 Windows 10 via WSL2):

mkdir -p $WORKING/bootfs
mount -o loop Template:Highlight3 $WORKING/bootfs
##Then copy the new dtb file at the root of $WORKING/bootfs
umount $WORKING/bootfs
sync
dd if=Template:Highlight3 of=Template:Highlight3 conv=fdatasync
Info white.png Information
The '/dev/mmcblk0p4' is in case of the sdcard is inserted in dedicated drive of the PC, using an USB sdcard reader will probably create /dev/sdb4 entry.

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_Template:Highlight3_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:

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

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 Windows 10 via WSL2):

mkdir -p $WORKING/bootfs
mount -o loop Template:Highlight3 $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 or 'dd' :
umount $WORKING/bootfs
sync
dd if=Template:Highlight3 of=Template:Highlight3 conv=fdatasync
Info white.png Information
The '/dev/mmcblk0p4' is in case of the sdcard is inserted in dedicated drive of the PC, using an USB sdcard reader will probably create /dev/sdb4 entry.