Difference between revisions of "How to compile the device tree with the Developer Package"

[quality revision] [quality revision]
m (extlinux basics)
m (U-Boot : regenerate fip image within new U-Boot binary)
 
Applicable for STM32MP15x lines

1 Purpose[edit]

This article explains how to update the boot chain (trusted modeOP-TEE with FIP) for a "custom" device tree.
In particular, STM32CubeMX can generate 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[edit]

There are various rationale 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 (or the oppositeand vice versa)

3 Prerequisites[edit]

Info white.png 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), uU-bootBoot, and Linux kernel.


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


  • 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
|   |-- stm32mp157cstm32mp157f-mydevicetree-mx.dts
|-- tf-a
|  |-- stm32mp15stm32mp157f-mydevicetree-mx.hdts
|  |-- stm32mp157cstm32mp157f-mydevicetree-mx-fw-config.dts
|  |-- stm32mp15-mx.dtsi
|-- u-boot
|  |-- stm32mp15stm32mp157f-mydevicetree-mx.hdts
|  |-- stm32mp157cstm32mp157f-mydevicetree-mx-u-boot.dtsi
|  |-- stm32mp157cstm32mp15-mydevicetree-mx.dtsdtsi


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

4 Preparing your environment[edit]

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 <FLASHen.FLASH-ststm32mp1-imageopenstlinux-weston5.15-openstlinuxyocto-westonkirkstone-stm32mp1.mp1-v22.11.23.tar.xz>gz -C $WORKDIR/
tar --strip-components=1 -xf <SOURCESen.SOURCES-ststm32mp1-imageopenstlinux-weston5.15-openstlinuxyocto-westonkirkstone-stm32mp1.mp1-v22.11.23.tar.xz>gz -C $WORKDIR/
tar --strip-components=1 -xf <SDK-st-image-weston-openstlinux-weston-stm32mp1.tar.xz> 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 SDK installation.


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

5 Updating the kernel device tree[edit]

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]

Info white.png Information
The procedure below is an extract of the README.HOW_HOWTOTO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/linux-stm32mp-*. Please notice a grep "$>" README_HOWTO.txt describes the few commands 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[edit]

pushd $WORKDIR
cp -r MyDeviceTree_fromCubeMX/kernel/* kernel/kernel-sources/arch/arm/boot/dts/
popd

5.3 Kernel : regenerate the kernel DTB[edit]

Info white.png Information
The procedure below is an extract of the README.HOW_HOWTOTO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/linux-stm32mp-*. Please notice a grep "$>" README_HOWTO.txt describes the few commands 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 stm32mp157cstm32mp157f-mydevicetree-mx.dtb LOADADDR=0xC2000040 O="$PWD/../build"
popd
ls -l $WORKDIR/kernel/build/arch/arm/boot/dts/stm32mp157cstm32mp157f-mydevicetree-mx.dtb

5.4 Kernel : copy the DTB into bootfs[edit]

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

Then, if needed, edit by #Updating extlinux for the target according to 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 the u-boot BOOT firmwares[edit]

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]

To update the uTF-boot A device tree, replace the DTB part of the uTF-boot A binary.
Adding a new device tree to the u-boot source code forces the Makefile to regenerate a new u-boot.stm32 containing the new DTS.
The following chapters describe the procedure to update the u-boot device tree.

6.1 U-boot 

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[edit]

Info white.png Information
The procedure below is an extract of the README.HOW_HOWTOTO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/utf-boota-stm32mp-*. Please notice a grep "$>" README_HOWTO.txt describes the few commands Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of utf-boot a
.
pushd $WORKDIR
mkdir -p u-boot tar xf pushd sources/arm-ostl-linux-gnueabi/utf-boota-stm32mp-*/vv[0-9]*
mkdir -p tf-a-sources
tar xf tf-a-stm32mp-v[0-9]*.tar.gz * -C u-boot mv u-boot/u-boot* u-boot/u-boot-sources/ pushd u-boot/u-boot-one-top-level=tf-a-sources --strip-components=1
pushd tf-a-sources
for p in `ls -1 ../../sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-*/*.patchpatch`; do patch -p1 < $p; done
popd
popd

6.1.2

U

TF-

boot 

: copy the DTS

in

into the

u-boot

source code[edit]

pushd $WORKDIR
cp -r MyDeviceTree_fromCubeMX/utf-boota/* u-bootsources/uarm-bootostl-sources/arch/arm/dts/ popd

Starting from u-boot 2019.04 version the device tree to be compiled must be explicitly added to the dts Makefile, u-boot/u-boot-sources/arch/arm/dts/Makefile:

 dtb-y += stm32mp157c-mydevicetree-mx.dtb
 targets += $(dtb-y)

6.3 U-boot : regenerate u-boot.stm32
linux-gnueabi/tf-a-stm32mp-v[0-9]*/tf-a-sources/fdts/
popd

6.1.3 TF-A : regenerate TF-A[edit]

Info white.png Information
The procedure below is an extract of the README.HOW_HOWTOTO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/utf-boota-stm32mp-*. Please notice a grep "$>" README_HOWTO.txt describes the few commands Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of utf-boot a
.

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


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>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.:
stm32mp157c
stm32mp157f-mydevicetree-mx
popd ls -l $WORKDIR/u-boot/u-boot-sources/u-boot.stm32

6.4 U-boot : copy the u-boot into the target[edit]

  • Because of 'extlinux' and before flashing the new u-boot.stm32, make sure #Updating extlinux is compliant with the 'compatible' value in the DTS file.
  • Then flash the u-boot.stm32 into the 'ssbl' partition of the target using STM32CubeProgrammer.
7 Updating the TF-A
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[edit]

To update the TFOP-A TEE device tree, replace the DTB part of the TFOP-A TEE 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:

7.1 TF-A 

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]

Info white.png Information
The procedure below is an extract of the README.HOW_HOWTOTO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/tfoptee-aos-stm32mp-*. Please notice a grep "$>" README_HOWTO.txt describes the few commands Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of tfOP-a TEE
.
pushd $WORKDIR
mkdir -p tf-a tar xf pushd sources/arm-ostl-linux-gnueabi/tfoptee-aos-stm32mp-*/v[0-9]*
tar xf optee-os-stm32mp-[0-9]*.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 ../../sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*/*.patchone-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

7

6.2

TF

.2 OP-

TEE: copy the DTS

into

in the source code[edit]

pushd $WORKDIR
cp -r MyDeviceTree_fromCubeMX/tf-aoptee/* tf-a/tf-a-sources/fdts/ popd
7.3 TF-A : regenerate TF-A.stm32
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[edit]

Info white.png Information
The procedure below is an extract of the README.HOW_HOWTOTO.txt file which is available in $WORKDIR/sources/arm-ostl-linux-gnueabi/tfu-aboot-stm32mp-*. Please notice a grep "$>" README_HOWTO.txt describes the few commands Note: the "README.HOW_TO.txt" file contains some useful grep "$> commands that are needed to build the artifact of tfOP-a TEE
.
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 Updating extlinux[edit]

8.2
pushd $WORKDIR/tf-a/tf-a-sources make -f ../../sources/arm-ostl-linux-gnueabi/tfoptee-aos-stm32mp-[0-9]*-r0/optee-os-sources
make -f ../Makefile.sdk TFA_DEVICETREECFG_EMBED_DTB_SOURCE_FILE=<device tree> TF_A_CONFIG=<config> all
<config> : could be trusted or serialboot according the boot type
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.: stm32mp157cstm32mp157f-mydevicetree-mx
popd ls -l $WORKDIR/tf-a/build/<config>/tf-a-<device tree>-<config>.stm32
7.4 TF-A : copy the DTB in target/bootfs[edit]

Then flash the tf-a-*.stm32 into the 'fsbl1' and 'fsbl2' partitions of the target with STM32CubeProgrammer

Warning white.png Warning
'fsbl1' and 'fsbl2' are two redondant partitions and so, they should have same content

8 Update methods[edit]

8.1 Updating bootfs[edit]

There are two methods to update bootfs

  • On an up and running target
scp stm32mp157c-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, avaible within any Linux Distribution (even through WSL2), is required:

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
<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[edit]

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]

Info white.png 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[edit]

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[edit]

Info white.png 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[edit]

  • 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[edit]

7.1 Updating extlinux[edit]

7.1.1 extlinux basics[edit]

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

  • In case of an DK-2 board booting from the sdcard. A stm32mp157cstm32mp157f-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 stm32mp157cstm32mp157f-mydevicetree-mx
LABEL stm32mp157cstm32mp157f-dk2-sdcard
        KERNEL /uImage
        FDTDIR /
        APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
LABEL stm32mp157cstm32mp157f-dk2-a7-examples-sdcard
        KERNEL /uImage
        FDT /stm32mp157cstm32mp157f-dk2-a7-examples.dtb
        APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
LABEL stm32mp157cstm32mp157f-dk2-m4-examples-sdcard
        KERNEL /uImage
        FDT /stm32mp157cstm32mp157f-dk2-m4-examples.dtb
        APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
LABEL stm32mp157cstm32mp157f-mydevicetree-mx
       KERNEL /uImage
       FDT /stm32mp157cstm32mp157f-mydevicetree-mx.dtb
       APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200

Please 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 compiled with u-bootused by U-Boot.
    The 'compatible' value is at head of the DTS file and looks like : "st,stm32mp157cstm32mp157f-mydevicetree-mx"
  • FDT : The path from /boot of the kernel DTB to use
8

7.2 Updating bootfs[edit]

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]

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

  • 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, avaible available in any Linux Distribution (even through WSL2), is needed:

mkdir -p $WORKING$WORKDIR/bootfs
sudo mount -o loop <st-image-bootfs-openstlinux-weston-stm32mp1.ext4> $WORKING $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



==<noinclude>{{ApplicableFor
|MPUs list=STM32MP15x
|MPUs checklist=STM32MP13x, STM32MP15x
}}</noinclude>


==Purpose==
This article explains how to update the [[Boot_chain_overview|boot chain]] (trusted modeOP-TEE with FIP) for a "custom" device tree. <br/>
In particular, STM32CubeMX can generate This article concentrates in particular on generating a "custom" device tree based on theSTM32CubeMX.<br/>


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

==Rationale==

There are various rationalereasons for using a custom ''device tree'', such as:
* the description of a new and private board
* the swapping of some internal peripherals from Cortex<sup>&reg;</sup>-M side to Cortex-A side (or the oppositeand vice versa)

==Prerequisites==
{{Info|Even if STMicroelectronics strongly recommends to use a Linux<sup>&reg;</sup> environment, the steps described in this article can be executed in a [[PC_prerequisites#WSL2_-28experimental-29|WSL2]] (Windows Sub-system Linux 2) environment. }}

Compiling a new device tree means updating three software components belonging to the complete [[Boot_chain_overview|boot chain]] (trusted mode), Trusted Firmware A (TF-A), u-bootU-Boot, and Linux kernel.<br/>


The material required to update the above software components is the following:
* '''[[Which STM32MPU Embedded Software Package better suits your needs#Starter_Package|Starter package]]''': 
** the flashlayout as well as the images to flash, provided within the '''en.FLASH-stm32mp1-openstlinux&lt;YY&gt;-&lt;MM&gt;-&lt;DD&gt;.tar.xz''' file (download it from [https://www.st.com/content/st_com/en/products/embedded-software/mcu-mpu-embedded-software/stm32-embedded-software/stm32-mpu-openstlinux-distribution/stm32mp1starter.html#get-software st.com])[{{EcosystemRelease/Package | revision=latest | package=Images package | request=url}}/{{EcosystemRelease/Package | revision=latest | package=Images package | request=name}} {{EcosystemRelease/Package | revision=latest | package=Images package | request=name}}]''' file* '''[[Which STM32MPU Embedded Software Package better suits your needs#Developer_Package|Developer package]]''': 
** the component sources and patches, provided within the '''en.SOURCES-stm32mp1-openstlinux-&lt;YY&gt;-&lt;MM&gt;-&lt;DD&gt;.tar.xz''' file (download it from [https://www.st.com/content/st_com/en/products/embedded-software/mcu-mpu-embedded-software/stm32-embedded-software/stm32-mpu-openstlinux-distribution/stm32mp1dev.html#get-software st.com])[{{EcosystemRelease/Package | revision=latest | package=OpenSTLinux BSP package | request=url}}/{{EcosystemRelease/Package | revision=latest | package=OpenSTLinux BSP package | request=name}} {{EcosystemRelease/Package | revision=latest | package=OpenSTLinux BSP package  | request=name}}]''' file** the SDK toolchain, provided within the '''en.SDK-x86_64-stm32mp1-openstlinux-&lt;YY&gt;-&lt;MM&gt;-&lt;DD&gt;.tar.xz''' file (download it from [https://www.st.com/content/st_com/en/products/embedded-software/mcu-mpu-embedded-software/stm32-embedded-software/stm32-mpu-openstlinux-distribution/stm32mp1dev.html#get-software st.com])[{{EcosystemRelease/Package | revision=latest | package=SDK package | request=url}}/{{EcosystemRelease/Package | revision=latest | package=SDK package | request=name}} {{EcosystemRelease/Package | revision=latest | package=SDK package | request=name}}]''' file* the '''[[STM32CubeProgrammer]]''', which is the tool used to flash the images and binaries into the target. <br/>

* '''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:<pre>MyDeviceTree_fromCubeMX
|-- kernel
|   |-- stm32mp157cstm32mp157f-mydevicetree-mx.dts
|-- tf-a
|  |-- stm32mp15-stm32mp157f-mydevicetree-mx.h
|  |-- stm32mp157c-mydevicetree-mx.dts
|-- u-boot
|  |-- stm32mp15-mx.h
|  |-- stm32mp157cdts
|  |-- stm32mp157f-mydevicetree-mx-fw-config.dts
|  |-- stm32mp15-mx.dtsi
|-- u-boot
|  |-- stm32mp157f-mydevicetree-mx.dts
|  |-- stm32mp157f-mydevicetree-mx-u-boot.dtsi
|  |-- stm32mp157c-mydevicetree-stm32mp15-mx.dtsdtsi
</pre>
<br/>

* Make sure the hardware configuration described in the '''[[PC_prerequisites#Linux PC-C2-AE_PC|PC prerequisites article]] has been executed''' (even with a  [[PC_prerequisites#WSL2_-28experimental-29|WSL2]] setup)

==Preparing your environment==
It is recommended to organize the numerous inputs described in [[#Prerequisites]] in your environment.<br/>

First create a dedicated ''WORKDIR'' under your ''HOME'' folder and copy there all the inputs listed in [[#Prerequisites]]:
:{{PC$}} cd $HOME
:{{PC$}} mkdir WORKDIR
:{{PC$}} cd WORKDIR
:{{PC$}} export WORKDIR="$PWD"
:{{PC$}} tar --strip-components=1 -xf ''<FLASH-st-image-weston-openstlinux-weston-stm32mp1.tar.xz>'' {{EcosystemRelease/Package | revision=latest | package=Images package | request=name}} -C $WORKDIR/
:{{PC$}} tar --strip-components=1 -xf ''<SOURCES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz>'' {{EcosystemRelease/Package | revision=latest | package=OpenSTLinux BSP package  | request=name}} -C $WORKDIR/
:{{PC$}} tar --strip-components=1 -xf ''<SDK-st-image-weston-openstlinux-weston-stm32mp1.tar.xz>'' {{EcosystemRelease/Package | revision=latest | package=SDK package | request=name}} -C $WORKDIR/
:{{PC$}} tar xf {{HighlightParam|''<MyDeviceTree_fromCubeMX.tar.xz>''}} -C $WORKDIR/

Then proceed with the [[Install_the_SDK#Run_the_SDK_installation_script|SDK installation]].

The commands described in the rest of the document must be run in an SDK environment context: ([[Install_the_SDK#Starting_up_SDK#Start the_ SDK up|Starting_up_the_SDK]]).

==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.
=== Kernel : unpack and patch sources ===
{{Info|The procedure below is an extract of the README_HOWTO.HOW_TO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/linux-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commandsNote: 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:
:{{PC$}} pushd $WORKDIR
:{{PC$}} mkdir -p kernel
:{{PC$}} tar xf sources/arm-ostl-linux-gnueabi/linux-stm32mp-*/linux-*.tar.xz -C kernel
:{{PC$}} mv kernel/linux-* kernel/kernel-sources/
:{{PC$}} pushd kernel/kernel-sources/
:{{PC$}} for p in $(ls -1 ../../sources/arm-ostl-linux-gnueabi/linux-stm32mp-*/*.patch); do patch -p1 < $p; done
:{{PC$}} popd
:{{PC$}} popd

=== Kernel : copy the DTS into the source code ===
:{{PC$}} pushd $WORKDIR
:{{PC$}} cp -r MyDeviceTree_fromCubeMX/kernel/* kernel/kernel-sources/arch/arm/boot/dts/
:{{PC$}} popd

=== Kernel : regenerate the kernel DTB ===
{{Info|The procedure below is an extract of the README_HOWTO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/linux-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commands < $p; done
:{{PC$}} popd
:{{PC$}} popd

=== Kernel : copy the DTS into the source code ===
:{{PC$}} pushd $WORKDIR
:{{PC$}} cp -r MyDeviceTree_fromCubeMX/kernel/* kernel/kernel-sources/arch/arm/boot/dts/
:{{PC$}} popd

=== Kernel : regenerate the kernel DTB ===
{{Info|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}}.


:{{PC$}} pushd $WORKDIR/kernel/kernel-sources
:{{PC$}} make ARCH=arm O="$PWD/../build" multi_v7_defconfig fragment*.config:{{PC$}} 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
:{{PC$}} yes "" | make ARCH=arm oldconfig O="$PWD/../build"
:{{PC$}} make stm32mp157cstm32mp157f-mydevicetree-mx.dtb LOADADDR=0xC2000040 O="$PWD/../build"
:{{PC$}} popd
:{{PC$}} ls -l $WORKDIR/kernel/build/arch/arm/boot/dts/stm32mp157cstm32mp157f-mydevicetree-mx.dtb

=== Kernel : copy the DTB into bootfs ===
First of, update all the [[#Updating bootfs]] with the new DTB so that for it is to be taken it into account aton the next boot of the target.

Then, if needed, edit by [[#Updating extlinux]] for the target according to 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.

== Updating the u-boot device tree ==
To update the u-bootUpdating 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).
===Updating the TF-A device tree ===
To update the TF-A device tree, replace the DTB part of the u-bootTF-A binary.<br/>
Adding a new device tree to the u-boot source code forces the Makefile to regenerate a new u-boot.stm32 containing the new DTS. <br/>

The following chapters describe the procedure to update the u-boot device tree.
=== U-bootThe 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:<br/>

==== TF-A : unpack and patch sources ====

{{Info|The procedure below is an extract of the README_HOWTO.HOW_TO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/u-boottf-a-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commandsNote: the "README.HOW_TO.txt" file contains some useful ''grep "$> commands that are needed to build the artifact of u-boot}}tf-a}}.


:{{PC$}} pushd $WORKDIR
:{{PC$}} mkdir -p u-boot
:{{PC$}} tar xf pushd sources/arm-ostl-linux-gnueabi/u-boottf-a-stm32mp-*/v*.tar.gz -C u-boot
:{{PC$}} mv u-boot/u-boot* u-boot/u-boot-sources/
:{{PC$}} pushd u-boot/u-boot-[0-9]*
:{{PC$}} mkdir -p tf-a-sources
:{{PC$}} tar xf tf-a-stm32mp-v[0-9]*.tar.* --one-top-level=tf-a-sources --strip-components=1
:{{PC$}} pushd tf-a-sources
:{{PC$}} for p in ../../sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-*/*.patch; do patch -p1 < $p; done
:{{PC$}} popd

=== U-boot : copy the DTS in the u-boot source code ===
:{{PC$}} pushd $WORKDIR
:{{PC$}} cp MyDeviceTree_fromCubeMX/u-boot/* u-boot/u-boot-sources/arch/arm/dts/
:{{PC$}} popd

'''Starting from ''u-boot'' 2019.04 version the device tree to be compiled must be explicitly added to the ''dts Makefile''''', ''u-boot/u-boot-sources/arch/arm/dts/Makefile'':
  dtb-y += {{highlight|stm32mp157c-mydevicetree-mx.dtb}}
  targets += $(dtb-y)

=== U-boot : regenerate u-boot.stm32 ===
{{Info|The procedure below is an extract of the README_HOWTO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commands `ls -1 ../*.patch`; do patch -p1 < $p; done
:{{PC$}} popd
:{{PC$}} popd

==== TF-A : copy the DTS into the source code ====
:{{PC$}}  pushd $WORKDIR
:{{PC$}}  cp -r MyDeviceTree_fromCubeMX/tf-a/* sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-v[0-9]*/tf-a-sources/fdts/
:{{PC$}}  popd

==== TF-A : regenerate TF-A ====
{{Info|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 u-boot}}

:{{PC$}} pushd $WORKDIR/u-boot/u-boot-sources
:{{PC$}} make stm32mp15_''<config>''_defconfig
: ''<config>'' : could be ''trusted'' or ''basic'' according the boot type
:{{PC$}} make DEVICE_TREE=''<device tree>'' all
: ''<device tree>''tf-a}}.
First only the TF-A "intermediates" artifacts are generated, the FIP image will be generated at final step (U-Boot compilation).

:{{PC$}} pushd $WORKDIR/sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-v[0-9]*/tf-a-sources
:{{PC$}} export FIP_DEPLOYDIR_ROOT=$PWD/../../FIP_artifacts
:{{PC$}} make -f ../Makefile.sdk TF_A_DEVICETREE={{HighlightParam|''<devicetree_name>''}} TF_A_CONFIG="optee  emmc nand nor sdcard  uart usb" DEPLOYDIR=$FIP_DEPLOYDIR_ROOT/arm-trusted-firmware '''stm32'''
::{{HighlightParam|''<devicetree_name>''}} : is the device tree just copied, i.e.: stm32mp157c-mydevicetree-mx
:{{PC$}} popd
:{{PC$}} ls -l $WORKDIR/u-boot/u-boot-sources/'''u-boot.stm32'''

=== U-boot : copy the u-boot into the target ===
* Because of 'extlinux' and before flashing the new u-boot.stm32, make sure [[#Updating extlinux]] is compliant with the 'compatible' value in the DTS file.<br/>


* Then flash the u-boot.stm32 into the 'ssbl' partition of the target using [[STM32CubeProgrammer]].

==Updating the TF-A device tree ==
To update the TF-A'''''stm32mp157f-mydevicetree-mx'''''
::''DEPLOYDIR'' is the path where intermediate binaries of tf-a should be deployed (requiered by fip-tools to generate fip image)
:{{PC$}} popd

=== Updating the OP-TEE device tree ===
To update the OP-TEE device tree, replace the DTB part of the TF-AOP-TEE binary.<br/>
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:<br/>

=== TF-A Adding a new device tree to the OP-TEE source code forces the Makefile to regenerate new OP-TEE binaries. <br/>

The following chapters describe the procedure to update the OP-TEE device tree.

==== OP-TEE: unpack and patch sources ====

{{Info|The procedure below is an extract of the README_HOWTO.HOW_TO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/tf-aoptee-os-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commandsNote: the "README.HOW_TO.txt" file contains some useful ''grep "$> commands that are needed to build the artifact of tf-a}}
OP-TEE}}. 
:{{PC$}} pushd $WORKDIR
:{{PC$}}  mkdir -p tf-a
:{{PC$}}  tar xf sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*/v*.tar.gz -C tf-a
:{{PC$}}  mv tf-a/arm-trusted-firmware-* tf-a/tf-a-sources
:{{PC$}}  pushd tf-a/tf-a-sources
:{{PC$}}  for p in ../../sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*/*.patch; do patch -p1 < $p; done
:{{PC$}}  popd
:{{PC$}}  popd

=== TF-A : copy the DTS into the source code ===
:{{PC$}}  pushd $WORKDIR
:{{PC$}}  cp -r MyDeviceTree_fromCubeMX/tf-a/* tf-a/tf-a-sources/fdts/
:{{PC$}}  popd

=== TF-A : regenerate TF-A.stm32 ===
{{Info|The procedure below is an extract of the README_HOWTO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commands pushd sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-[0-9]*
:{{PC$}} tar xf optee-os-stm32mp-[0-9]*.tar.* --one-top-level=optee-os-sources --strip-components=1
:{{PC$}} pushd optee-os-sources
:{{PC$}} tar xfz ../fonts.tar.gz
:{{PC$}} for p in `ls -1 ../*.patch`; do patch -p1 < $p; done
:{{PC$}} popd
:{{PC$}} popd

==== OP-TEE: copy the DTS in the source code ====
:{{PC$}} pushd $WORKDIR
:{{PC$}} cp MyDeviceTree_fromCubeMX/optee/* sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-*/optee-os-sources/core/arch/arm/dts/
:{{PC$}} popd

==== OP-TEE: regenerate fip image within new OP-TEE ====
{{Info|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 tf-a}}
OP-TEE}}.
:{{PC$}} pushd $WORKDIR/tf-a/tf-a-sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-[0-9]*/optee-os-sources
:{{PC$}} make -f ../../sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*-r0/Makefile.sdk TFA_DEVICETREE=''<device tree>'' TF_A_CONFIG=''<config>'' all
::''<config>'' : could be '''''trusted''''' or ''serialboot'' according the boot type
::''<device tree>'' : is the device tree just copied, i.e.: '''''stm32mp157c-mydevicetree-mx'''''
:{{PC$}} popd
:{{PC$}} ls -l $WORKDIR/tf-a/build/''<config>''/tf-a-''<device tree>''-''<config>''.stm32

=== TF-A : copy the DTB in target/bootfs ===
Then flash the tf-a-*.stm32 into the 'fsbl1' and 'fsbl2' partitions of the target with [[STM32CubeProgrammer]]
{{warning|'fsbl1' and 'fsbl2' are two redondant partitions and so, they should have same content}}

= Update methods =
== Updating bootfs ==
There are two methods to update bootfs 
* <u>{{STDarkBlue|On an up and running target}}</u>

:{{PC$}} scp stm32mp157c-mydevicetree-mx.dtb root@<Target_IP>:/boot/
* <u>{{STDarkBlue|Directly into 'bootfs' image}}</u>

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, avaible within any Linux Distribution (even through [[PC_prerequisites#WSL2_-28experimental-29|WSL2]]), is required:
:{{PC$}} mkdir -p $WORKING/bootfs
:{{PC$}} mount -o loop {{HighlightParam|&lt;st-image-bootfs-openstlinux-weston-stm32mp1.ext4&gt;}} $WORKING/bootfs
:{{grey|##Then copy the new dtb file at the root of $WORKING/bootfs}}
:{{PC$}} umount $WORKING/bootfs
:{{PC$}} sync
:{{PC$}} dd if={{HighlightParam|&lt;st-image-bootfs-openstlinux-weston-stm32mp1.ext4&gt;}} of={{HighlightParam|/dev/mmblk0p4}} conv=fdatasync
:{{info|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.}}

== Makefile.sdk CFG_EMBED_DTB_SOURCE_FILE={{HighlightParam|''<device tree>''}}  OPTEE_DRAMSIZE={{HighlightParam|''<RAM size>''}} DEPLOYDIR=~/views/temp/CubeIde/WORKDIR/sources/arm-ostl-linux-gnueabi/FIP_artifacts/optee optee
::{{HighlightParam|''<device tree>''}} : is the device tree just copied, i.e.: stm32mp157f-mydevicetree-mx
::{{HighlightParam|''<RAM size>''}}   : is the RAM size of the board selected by the device treee, i.e.: 0x20000000
:{{PC$}} popd

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

==== U-Boot : unpack and patch sources ====
{{Info|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}}. 

:{{PC$}} pushd $WORKDIR
:{{PC$}} pushd sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-v[0-9]*
:{{PC$}} tar xf u-boot-stm32mp-v[0-9]*.tar.* --one-top-level=u-boot-sources --strip-components=1
:{{PC$}} pushd u-boot-sources
:{{PC$}} for p in `ls -1 ../*.patch`; do patch -p1 < $p; done
:{{PC$}} popd
:{{PC$}} popd

==== U-Boot : copy the DTS in the U-Boot source code ====
:{{PC$}} pushd $WORKDIR
:{{PC$}} cp MyDeviceTree_fromCubeMX/u-boot/* sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-v[0-9]*/u-boot-sources/arch/arm/dts/
:{{PC$}} popd

==== U-Boot : regenerate fip image within new U-Boot binary====
{{Info|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}}. 

:{{PC$}} pushd $WORKDIR/sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-v[0-9]*/u-boot-sources
:{{PC$}} make -f ../Makefile.sdk  UBOOT_CONFIG=trusted UBOOT_DEFCONFIG={{HighlightParam|''<stm32mpu device>''}}_defconfig UBOOT_BINARY=u-boot.dtb FIP_CONFIG="optee" DEVICETREE={{HighlightParam|''<device tree>''}} all
::{{HighlightParam|''<stm32mpu device>''}} : is the targetted stm32mpu device, '''stm32mp13''' or '''stm32mp15'''
::{{HighlightParam|''<device tree>''}} : is the device tree just copied, i.e.: stm32mp157f-mydevicetree-mx
:{{PC$}} popd

==== 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.<br/>

* 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).

= Update methods =
== Updating extlinux ==
=== extlinux basics ===
'''extlinux''' describes how u-bootU-Boot boots. Updating '''extlinux''' consists in updating the extlinux.conf:
* In case of an DK-2 board booting from the sdcard. A '''stm32mp157cstm32mp157f-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.<br/>

Below an example of '''extlinux.conf''':
 menu title Select the boot mode
 MENU BACKGROUND ../splash.bmp
 TIMEOUT 5
 {{red|{{highlight|DEFAULT}} stm32mp157cstm32mp157f-mydevicetree-mx}}
 LABEL stm32mp157cstm32mp157f-dk2-sdcard
         KERNEL /uImage
         FDTDIR /
         APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
 LABEL stm32mp157cstm32mp157f-dk2-a7-examples-sdcard
         KERNEL /uImage
         FDT /stm32mp157cstm32mp157f-dk2-a7-examples.dtb
         APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
 LABEL stm32mp157cstm32mp157f-dk2-m4-examples-sdcard
         KERNEL /uImage
         FDT /stm32mp157cstm32mp157f-dk2-m4-examples.dtb
         APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
 {{red|{{highlight|LABEL}} stm32mp157cstm32mp157f-mydevicetree-mx
        KERNEL /uImage
        {{highlight|FDT}} /stm32mp157cstm32mp157f-mydevicetree-mx.dtb
        APPEND root&#61;PARTUUID&#61;e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console&#61;ttySTM0,115200}}

Please update/add the highlighted lines according to what have been compiled in chapter 5, 6 and/or 7:
* {{highlight|DEFAULT}}: This is the default 'LABEL' to boot
* {{highlight|LABEL}} : The entry 'LABEL' is the value of 'compatible' of the DTS file compiled with u-bootused by U-Boot.
*: The 'compatible' value is at head of the DTS file and looks like : "st,stm32mp157cstm32mp157f-mydevicetree-mx"
* {{highlight|FDT}} : The path from /boot of the kernel DTB to use

===  Updating bootfs ==
There are two methods to update bootfs: 
* <u>{{STDarkBlue|On an up and running target}}</u>

:{{PC$}} scp stm32mp157f-mydevicetree-mx.dtb root@{{HighlightParam|''<Target_IP>''}}:/boot/
* <u>{{STDarkBlue|Directly into 'bootfs' image}}</u>

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 [[PC_prerequisites#WSL2_-28experimental-29|WSL2]]), is required:
:{{PC$}} mkdir -p $WORKDIR/bootfs
:{{PC$}} mount -o loop {{HighlightParam|''&lt;st-image-bootfs-openstlinux-weston-stm32mp1.ext4&gt;''}} $WORKDIR/bootfs
:{{grey|##Then copy the new dtb file at the root of $WORKDIR/bootfs}}
:{{PC$}} umount $WORKDIR/bootfs
:{{PC$}} sync
Then use [[STM32CubeProgrammer]] to update the bootfs partition.

=== Updating extlinux ===
Updating 'extlinux' consists in modifying the extlinux.conf. There are two ways to do thisproceed:
* <u>{{STDarkBlue|On an up and running target}}</u>

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.<br/>

:{{highlight| Do not forget to synchronize the file system before rebooting the target:}}
:{{Board$}} sync

* <u>{{STDarkBlue|Into 'bootfs' image directly}}</u>

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, avaibleavailable in any Linux Distribution (even through [[PC_prerequisites#WSL2_-28experimental-29|WSL2]]), is needed:
:{{PC$}} mkdir -p $WORKING$WORKDIR/bootfs
:{{PC$}} sudo mount -o loop {{HighlightParam|&lt;st-image-bootfs-openstlinux-weston-stm32mp1.ext4&gt;}} $WORKING$WORKDIR/bootfs
:{{grey|##Then edit the extlinux.conf file (for WSL2 use a 'Linux' type editor; vi, ...)}}
:{{grey|##Once extlinux.conf up-to-date, umount loopback and flash the bootfs into sdcard with [[STM32CubeProgrammer]]}}
<noinclude>
{{PublicationRequestId | 24428| 2022-08-29 | }}[[Category:How to build software]]</noinclude>
(91 intermediate revisions by 9 users not shown)
Line 1: Line 1:
  +
<noinclude>{{ApplicableFor
  +
|MPUs list=STM32MP15x
  +
|MPUs checklist=STM32MP13x, STM32MP15x
  +
}}</noinclude>
  +
 
==Purpose==
 
==Purpose==
This article explains how to update the [[Boot_chain_overview|boot chain]] (trusted mode) for a "custom" device tree. <br/>
+
This article explains how to update the [[Boot_chain_overview|boot chain]] (OP-TEE with FIP) for a "custom" device tree. <br/>
In particular, STM32CubeMX can generate a "custom" device tree.<br/>
+
This article concentrates in particular on generating a "custom" device tree based on theSTM32CubeMX.<br/>
   
 
This article describes how to update the device tree compiled (DTB) part of the boot binaries.
 
This article describes how to update the device tree compiled (DTB) part of the boot binaries.
Line 7: Line 12:
 
==Rationale==
 
==Rationale==
   
There are various rationale for using a custom ''device tree'', such as:
+
There are various reasons for using a custom ''device tree'', such as:
 
* the description of a new and private board
 
* the description of a new and private board
* the swapping of some internal peripherals from Cortex<sup>&reg;</sup>-M side to Cortex-A side (or the opposite)
+
* the swapping of some internal peripherals from Cortex<sup>&reg;</sup>-M side to Cortex-A side (and vice versa)
   
 
==Prerequisites==
 
==Prerequisites==
 
{{Info|Even if STMicroelectronics strongly recommends to use a Linux<sup>&reg;</sup> environment, the steps described in this article can be executed in a [[PC_prerequisites#WSL2_-28experimental-29|WSL2]] (Windows Sub-system Linux 2) environment. }}
 
{{Info|Even if STMicroelectronics strongly recommends to use a Linux<sup>&reg;</sup> environment, the steps described in this article can be executed in a [[PC_prerequisites#WSL2_-28experimental-29|WSL2]] (Windows Sub-system Linux 2) environment. }}
   
Compiling a new device tree means updating three software components belonging to the complete [[Boot_chain_overview|boot chain]] (trusted mode), Trusted Firmware A (TF-A), u-boot, and Linux kernel.<br/>
+
Compiling a new device tree means updating three software components belonging to the complete [[Boot_chain_overview|boot chain]] (trusted mode), Trusted Firmware A (TF-A), U-Boot, and Linux kernel.<br/>
   
   
 
The material required to update the above software components is the following:
 
The material required to update the above software components is the following:
 
* '''[[Which STM32MPU Embedded Software Package better suits your needs#Starter_Package|Starter package]]''':  
 
* '''[[Which STM32MPU Embedded Software Package better suits your needs#Starter_Package|Starter package]]''':  
** the flashlayout as well as the images to flash, provided within the '''en.FLASH-stm32mp1-openstlinux&lt;YY&gt;-&lt;MM&gt;-&lt;DD&gt;.tar.xz''' file (download it from [https://www.st.com/content/st_com/en/products/embedded-software/mcu-mpu-embedded-software/stm32-embedded-software/stm32-mpu-openstlinux-distribution/stm32mp1starter.html#get-software st.com])
+
** the flashlayout as well as the images to flash, provided within the '''[{{EcosystemRelease/Package | revision=latest | package=Images package | request=url}}/{{EcosystemRelease/Package | revision=latest | package=Images package | request=name}} {{EcosystemRelease/Package | revision=latest | package=Images package | request=name}}]''' file
 
* '''[[Which STM32MPU Embedded Software Package better suits your needs#Developer_Package|Developer package]]''':  
 
* '''[[Which STM32MPU Embedded Software Package better suits your needs#Developer_Package|Developer package]]''':  
** the component sources and patches, provided within the '''en.SOURCES-stm32mp1-openstlinux-&lt;YY&gt;-&lt;MM&gt;-&lt;DD&gt;.tar.xz''' file (download it from [https://www.st.com/content/st_com/en/products/embedded-software/mcu-mpu-embedded-software/stm32-embedded-software/stm32-mpu-openstlinux-distribution/stm32mp1dev.html#get-software st.com])
+
** the component sources and patches, provided within the '''[{{EcosystemRelease/Package | revision=latest | package=OpenSTLinux BSP package | request=url}}/{{EcosystemRelease/Package | revision=latest | package=OpenSTLinux BSP package | request=name}} {{EcosystemRelease/Package | revision=latest | package=OpenSTLinux BSP package  | request=name}}]''' file
** the SDK toolchain, provided within the '''en.SDK-x86_64-stm32mp1-openstlinux-&lt;YY&gt;-&lt;MM&gt;-&lt;DD&gt;.tar.xz''' file (download it from [https://www.st.com/content/st_com/en/products/embedded-software/mcu-mpu-embedded-software/stm32-embedded-software/stm32-mpu-openstlinux-distribution/stm32mp1dev.html#get-software st.com])
+
** the SDK toolchain, provided within the '''[{{EcosystemRelease/Package | revision=latest | package=SDK package | request=url}}/{{EcosystemRelease/Package | revision=latest | package=SDK package | request=name}} {{EcosystemRelease/Package | revision=latest | package=SDK package | request=name}}]''' file
 
* the '''[[STM32CubeProgrammer]]''', which is the tool used to flash the images and binaries into the target.  
 
* the '''[[STM32CubeProgrammer]]''', which is the tool used to flash the images and binaries into the target.  
 
<br/>
 
<br/>
Line 29: Line 34:
 
<pre>MyDeviceTree_fromCubeMX
 
<pre>MyDeviceTree_fromCubeMX
 
|-- kernel
 
|-- kernel
|   |-- stm32mp157c-mydevicetree-mx.dts
+
|   |-- stm32mp157f-mydevicetree-mx.dts
 
|-- tf-a
 
|-- tf-a
|  |-- stm32mp15-mx.h
+
|  |-- stm32mp157f-mydevicetree-mx.dts
|  |-- stm32mp157c-mydevicetree-mx.dts
+
|  |-- stm32mp157f-mydevicetree-mx-fw-config.dts
  +
|  |-- stm32mp15-mx.dtsi
 
|-- u-boot
 
|-- u-boot
|  |-- stm32mp15-mx.h
+
|  |-- stm32mp157f-mydevicetree-mx.dts
|  |-- stm32mp157c-mydevicetree-mx-u-boot.dtsi
+
|  |-- stm32mp157f-mydevicetree-mx-u-boot.dtsi
|  |-- stm32mp157c-mydevicetree-mx.dts
+
|  |-- stm32mp15-mx.dtsi
 
</pre>
 
</pre>
 
<br/>
 
<br/>
* Make sure the hardware configuration described in '''[[PC_prerequisites#Linux PC]] has been executed''' (even with a  [[PC_prerequisites#WSL2_-28experimental-29|WSL2]] setup)
+
* Make sure the hardware configuration described in the '''[[PC_prerequisites#Linux-C2-AE_PC|PC prerequisites article]] has been executed''' (even with a  [[PC_prerequisites#WSL2_-28experimental-29|WSL2]] setup)
   
 
==Preparing your environment==
 
==Preparing your environment==
Line 48: Line 54:
 
:{{PC$}} cd WORKDIR
 
:{{PC$}} cd WORKDIR
 
:{{PC$}} export WORKDIR="$PWD"
 
:{{PC$}} export WORKDIR="$PWD"
:{{PC$}} tar --strip-components=1 -xf ''<FLASH-st-image-weston-openstlinux-weston-stm32mp1.tar.xz>'' -C $WORKDIR/
+
:{{PC$}} tar --strip-components=1 -xf {{EcosystemRelease/Package | revision=latest | package=Images package | request=name}} -C $WORKDIR/
:{{PC$}} tar --strip-components=1 -xf ''<SOURCES-st-image-weston-openstlinux-weston-stm32mp1.tar.xz>'' -C $WORKDIR/
+
:{{PC$}} tar --strip-components=1 -xf {{EcosystemRelease/Package | revision=latest | package=OpenSTLinux BSP package  | request=name}} -C $WORKDIR/
:{{PC$}} tar --strip-components=1 -xf ''<SDK-st-image-weston-openstlinux-weston-stm32mp1.tar.xz>'' -C $WORKDIR/
+
:{{PC$}} tar --strip-components=1 -xf {{EcosystemRelease/Package | revision=latest | package=SDK package | request=name}} -C $WORKDIR/
:{{PC$}} tar xf ''<MyDeviceTree_fromCubeMX.tar.xz>'' -C $WORKDIR/
+
:{{PC$}} tar xf {{HighlightParam|''<MyDeviceTree_fromCubeMX.tar.xz>''}} -C $WORKDIR/
   
 
Then proceed with the [[Install_the_SDK#Run_the_SDK_installation_script|SDK installation]].
 
Then proceed with the [[Install_the_SDK#Run_the_SDK_installation_script|SDK installation]].
   
   
The commands described in the rest of the document must be run in an SDK environment context: ([[Install_the_SDK#Starting_up_the_SDK|Starting_up_the_SDK]]).
+
The commands described in the rest of the document must be run in an SDK environment context: ([[Install_the_SDK#Start the SDK up|Starting_up_the_SDK]]).
   
 
==Updating the kernel device tree ==
 
==Updating the kernel device tree ==
Line 63: Line 69:
 
The  following chapters describe the procedure to generate and copy the new DTB into the target.
 
The  following chapters describe the procedure to generate and copy the new DTB into the target.
 
=== Kernel : unpack and patch sources ===
 
=== Kernel : unpack and patch sources ===
{{Info|The procedure below is an extract of the README_HOWTO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/linux-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commands needed to build the artifact of kernel}}
+
{{Info|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:
 
Run the following command into a shell:
Line 81: Line 87:
   
 
=== Kernel : regenerate the kernel DTB ===
 
=== Kernel : regenerate the kernel DTB ===
{{Info|The procedure below is an extract of the README_HOWTO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/linux-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commands needed to build the artifact of kernel}}
+
{{Info|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}}.
   
 
:{{PC$}} pushd $WORKDIR/kernel/kernel-sources
 
:{{PC$}} pushd $WORKDIR/kernel/kernel-sources
:{{PC$}} make O="$PWD/../build" multi_v7_defconfig
+
:{{PC$}} make ARCH=arm O="$PWD/../build" multi_v7_defconfig fragment*.config
 
:{{PC$}} 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
 
:{{PC$}} 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
 
:{{PC$}} yes "" | make ARCH=arm oldconfig O="$PWD/../build"
 
:{{PC$}} yes "" | make ARCH=arm oldconfig O="$PWD/../build"
:{{PC$}} make stm32mp157c-mydevicetree-mx.dtb LOADADDR=0xC2000040 O="$PWD/../build"
+
:{{PC$}} make stm32mp157f-mydevicetree-mx.dtb LOADADDR=0xC2000040 O="$PWD/../build"
 
:{{PC$}} popd
 
:{{PC$}} popd
:{{PC$}} ls -l $WORKDIR/kernel/build/arch/arm/boot/dts/stm32mp157c-mydevicetree-mx.dtb
+
:{{PC$}} ls -l $WORKDIR/kernel/build/arch/arm/boot/dts/stm32mp157f-mydevicetree-mx.dtb
   
 
=== Kernel : copy the DTB into bootfs ===
 
=== Kernel : copy the DTB into bootfs ===
First of all [[#Updating bootfs]] with the new DTB so that it is taken it into account at the next boot of the target.
+
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, [[#Updating extlinux]] for the target according to 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.
+
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.
  +
 
  +
==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).
  +
===Updating the TF-A device tree ===
  +
To update the TF-A device tree, replace the DTB part of the TF-A binary.<br/>
  +
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.
   
== Updating the u-boot device tree ==
+
Below the procedure to generate TF-A with a new DTB and then flash it on the target:<br/>
To update the u-boot device tree, replace the DTB part of the u-boot binary.<br/>
+
==== TF-A : unpack and patch sources ====
Adding a new device tree to the u-boot source code forces the Makefile to regenerate a new u-boot.stm32 containing the new DTS. <br/>
+
{{Info|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}}.
The following chapters describe the procedure to update the u-boot device tree.
 
=== U-boot : unpack and patch sources ===
 
{{Info|The procedure below is an extract of the README_HOWTO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commands needed to build the artifact of u-boot}}
 
   
 
:{{PC$}} pushd $WORKDIR
 
:{{PC$}} pushd $WORKDIR
:{{PC$}} mkdir -p u-boot
+
:{{PC$}} pushd sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-v[0-9]*
:{{PC$}} tar xf sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-*/v*.tar.gz -C u-boot
+
:{{PC$}} mkdir -p tf-a-sources
:{{PC$}} mv u-boot/u-boot* u-boot/u-boot-sources/
+
:{{PC$}} tar xf tf-a-stm32mp-v[0-9]*.tar.* --one-top-level=tf-a-sources --strip-components=1
:{{PC$}} pushd u-boot/u-boot-sources
+
:{{PC$}} pushd tf-a-sources
:{{PC$}} for p in ../../sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-*/*.patch; do patch -p1 < $p; done
+
:{{PC$}} for p in `ls -1 ../*.patch`; do patch -p1 < $p; done
 
:{{PC$}} popd
 
:{{PC$}} popd
  +
:{{PC$}} popd
  +
  +
==== TF-A : copy the DTS into the source code ====
  +
:{{PC$}}  pushd $WORKDIR
  +
:{{PC$}}  cp -r MyDeviceTree_fromCubeMX/tf-a/* sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-v[0-9]*/tf-a-sources/fdts/
  +
:{{PC$}}  popd
  +
  +
==== TF-A : regenerate TF-A ====
  +
{{Info|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).
  +
   
=== U-boot : copy the DTS in the u-boot source code ===
+
:{{PC$}} pushd $WORKDIR/sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-v[0-9]*/tf-a-sources
:{{PC$}} pushd $WORKDIR
+
:{{PC$}} export FIP_DEPLOYDIR_ROOT=$PWD/../../FIP_artifacts
:{{PC$}} cp MyDeviceTree_fromCubeMX/u-boot/* u-boot/u-boot-sources/arch/arm/dts/
+
:{{PC$}} make -f ../Makefile.sdk TF_A_DEVICETREE={{HighlightParam|''<devicetree_name>''}} TF_A_CONFIG="optee  emmc nand nor sdcard  uart usb" DEPLOYDIR=$FIP_DEPLOYDIR_ROOT/arm-trusted-firmware '''stm32'''
  +
::{{HighlightParam|''<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)
 
:{{PC$}} popd
 
:{{PC$}} popd
   
'''Starting from ''u-boot'' 2019.04 version the device tree to be compiled must be explicitly added to the ''dts Makefile''''', ''u-boot/u-boot-sources/arch/arm/dts/Makefile'':
+
=== Updating the OP-TEE device tree ===
  dtb-y += {{highlight|stm32mp157c-mydevicetree-mx.dtb}}
+
To update the OP-TEE device tree, replace the DTB part of the OP-TEE binary.<br/>
  targets += $(dtb-y)
+
Adding a new device tree to the OP-TEE source code forces the Makefile to regenerate new OP-TEE binaries. <br/>
  +
The following chapters describe the procedure to update the OP-TEE device tree.
   
=== U-boot : regenerate u-boot.stm32 ===
+
==== OP-TEE: unpack and patch sources ====
{{Info|The procedure below is an extract of the README_HOWTO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commands needed to build the artifact of u-boot}}
+
{{Info|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}}.
   
:{{PC$}} pushd $WORKDIR/u-boot/u-boot-sources
+
:{{PC$}} pushd $WORKDIR
:{{PC$}} make stm32mp15_''<config>''_defconfig
+
:{{PC$}} pushd sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-[0-9]*
: ''<config>'' : could be ''trusted'' or ''basic'' according the boot type
+
:{{PC$}} tar xf optee-os-stm32mp-[0-9]*.tar.* --one-top-level=optee-os-sources --strip-components=1
:{{PC$}} make DEVICE_TREE=''<device tree>'' all
+
:{{PC$}} pushd optee-os-sources
: ''<device tree>'' : is the device tree just copied, i.e.: stm32mp157c-mydevicetree-mx
+
:{{PC$}} tar xfz ../fonts.tar.gz
  +
:{{PC$}} for p in `ls -1 ../*.patch`; do patch -p1 < $p; done
  +
:{{PC$}} popd
 
:{{PC$}} popd
 
:{{PC$}} popd
:{{PC$}} ls -l $WORKDIR/u-boot/u-boot-sources/'''u-boot.stm32'''
 
   
=== U-boot : copy the u-boot into the target ===
+
==== OP-TEE: copy the DTS in the source code ====
* Because of 'extlinux' and before flashing the new u-boot.stm32, make sure [[#Updating extlinux]] is compliant with the 'compatible' value in the DTS file.<br/>
+
:{{PC$}} pushd $WORKDIR
  +
:{{PC$}} cp MyDeviceTree_fromCubeMX/optee/* sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-*/optee-os-sources/core/arch/arm/dts/
  +
:{{PC$}} popd
   
* Then flash the u-boot.stm32 into the 'ssbl' partition of the target using [[STM32CubeProgrammer]].
+
==== OP-TEE: regenerate fip image within new OP-TEE ====
  +
{{Info|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}}.
   
==Updating the TF-A device tree ==
+
:{{PC$}} pushd $WORKDIR/sources/arm-ostl-linux-gnueabi/optee-os-stm32mp-[0-9]*/optee-os-sources
To update the TF-A device tree, replace the DTB part of the TF-A binary.<br/>
+
:{{PC$}} make -f ../Makefile.sdk CFG_EMBED_DTB_SOURCE_FILE={{HighlightParam|''<device tree>''}}  OPTEE_DRAMSIZE={{HighlightParam|''<RAM size>''}} DEPLOYDIR=~/views/temp/CubeIde/WORKDIR/sources/arm-ostl-linux-gnueabi/FIP_artifacts/optee optee
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.
+
::{{HighlightParam|''<device tree>''}} : is the device tree just copied, i.e.: stm32mp157f-mydevicetree-mx
  +
::{{HighlightParam|''<RAM size>''}}  : is the RAM size of the board selected by the device treee, i.e.: 0x20000000
  +
:{{PC$}} popd
  +
 
  +
=== Updating the U-Boot device tree ===
  +
To update the U-Boot device tree, replace the U-Boot DTB in FIP image.
   
Below the procedure to generate TF-A with a new DTB and then flash it on the target:<br/>
+
==== U-Boot : unpack and patch sources ====
=== TF-A : unpack and patch sources ===
+
{{Info|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}}.
{{Info|The procedure below is an extract of the README_HOWTO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commands needed to build the artifact of tf-a}}
 
   
 
:{{PC$}} pushd $WORKDIR
 
:{{PC$}} pushd $WORKDIR
:{{PC$}} mkdir -p tf-a
+
:{{PC$}} pushd sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-v[0-9]*
:{{PC$}}  tar xf sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*/v*.tar.gz -C tf-a
+
:{{PC$}} tar xf u-boot-stm32mp-v[0-9]*.tar.* --one-top-level=u-boot-sources --strip-components=1
:{{PC$}} mv tf-a/arm-trusted-firmware-* tf-a/tf-a-sources
+
:{{PC$}} pushd u-boot-sources
:{{PC$}} pushd tf-a/tf-a-sources
+
:{{PC$}} for p in `ls -1 ../*.patch`; do patch -p1 < $p; done
:{{PC$}} for p in ../../sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*/*.patch; do patch -p1 < $p; done
+
:{{PC$}} popd
:{{PC$}} popd
+
:{{PC$}} popd
:{{PC$}} popd
 
   
=== TF-A : copy the DTS into the source code ===
+
==== U-Boot : copy the DTS in the U-Boot source code ====
:{{PC$}} pushd $WORKDIR
+
:{{PC$}} pushd $WORKDIR
:{{PC$}} cp -r MyDeviceTree_fromCubeMX/tf-a/* tf-a/tf-a-sources/fdts/
+
:{{PC$}} cp MyDeviceTree_fromCubeMX/u-boot/* sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-v[0-9]*/u-boot-sources/arch/arm/dts/
:{{PC$}} popd
+
:{{PC$}} popd
   
=== TF-A : regenerate TF-A.stm32 ===
+
==== U-Boot : regenerate fip image within new U-Boot binary====
{{Info|The procedure below is an extract of the README_HOWTO.txt file which is available in ''$WORKDIR/sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*''. Please notice a ''grep "$>" README_HOWTO.txt'' describes the few commands needed to build the artifact of tf-a}}
+
{{Info|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}}.
   
  +
:{{PC$}} pushd $WORKDIR/sources/arm-ostl-linux-gnueabi/u-boot-stm32mp-v[0-9]*/u-boot-sources
  +
:{{PC$}} make -f ../Makefile.sdk  UBOOT_CONFIG=trusted UBOOT_DEFCONFIG={{HighlightParam|''<stm32mpu device>''}}_defconfig UBOOT_BINARY=u-boot.dtb FIP_CONFIG="optee" DEVICETREE={{HighlightParam|''<device tree>''}} all
  +
::{{HighlightParam|''<stm32mpu device>''}} : is the targetted stm32mpu device, '''stm32mp13''' or '''stm32mp15'''
  +
::{{HighlightParam|''<device tree>''}} : is the device tree just copied, i.e.: stm32mp157f-mydevicetree-mx
  +
:{{PC$}} popd
   
:{{PC$}} pushd $WORKDIR/tf-a/tf-a-sources
+
==== U-Boot : copy U-Boot binary into the target ====
:{{PC$}} make -f ../../sources/arm-ostl-linux-gnueabi/tf-a-stm32mp-*-r0/Makefile.sdk TFA_DEVICETREE=''<device tree>'' TF_A_CONFIG=''<config>'' all
 
::''<config>'' : could be '''''trusted''''' or ''serialboot'' according the boot type
 
::''<device tree>'' : is the device tree just copied, i.e.: '''''stm32mp157c-mydevicetree-mx'''''
 
:{{PC$}} popd
 
:{{PC$}} ls -l $WORKDIR/tf-a/build/''<config>''/tf-a-''<device tree>''-''<config>''.stm32
 
   
=== TF-A : copy the DTB in target/bootfs ===
+
* Because of 'extlinux' and before flashing the new ''fip image'', make sure [[#Updating extlinux]] is compliant with the 'compatible' value in the DTS file.<br/>
Then flash the tf-a-*.stm32 into the 'fsbl1' and 'fsbl2' partitions of the target with [[STM32CubeProgrammer]]
+
* 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).
{{warning|'fsbl1' and 'fsbl2' are two redondant partitions and so, they should have same content}}
 
   
 
= Update methods =
 
= Update methods =
== Updating bootfs ==
 
There are two methods to update bootfs
 
* <u>{{STDarkBlue|On an up and running target}}</u>
 
:{{PC$}} scp stm32mp157c-mydevicetree-mx.dtb root@<Target_IP>:/boot/
 
* <u>{{STDarkBlue|Directly into 'bootfs' image}}</u>
 
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, avaible within any Linux Distribution (even through [[PC_prerequisites#WSL2_-28experimental-29|WSL2]]), is required:
 
:{{PC$}} mkdir -p $WORKING/bootfs
 
:{{PC$}} mount -o loop {{HighlightParam|&lt;st-image-bootfs-openstlinux-weston-stm32mp1.ext4&gt;}} $WORKING/bootfs
 
:{{grey|##Then copy the new dtb file at the root of $WORKING/bootfs}}
 
:{{PC$}} umount $WORKING/bootfs
 
:{{PC$}} sync
 
:{{PC$}} dd if={{HighlightParam|&lt;st-image-bootfs-openstlinux-weston-stm32mp1.ext4&gt;}} of={{HighlightParam|/dev/mmblk0p4}} conv=fdatasync
 
:{{info|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.}}
 
 
 
== Updating extlinux ==
 
== Updating extlinux ==
 
=== extlinux basics ===
 
=== extlinux basics ===
'''extlinux''' describes how u-boot boots. Updating '''extlinux''' consists in updating the extlinux.conf:
+
'''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 '''stm32mp157c-dk2_extlinux.conf''' file is located in ''/boot/mmc0_extlinux/'',
+
* 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.
+
* 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.<br/>
 
'''extlinux.conf''' is the description of a boot menu with one or several entries; 'DEFAULT' selects the default entry.<br/>
Line 200: Line 214:
 
  MENU BACKGROUND ../splash.bmp
 
  MENU BACKGROUND ../splash.bmp
 
  TIMEOUT 5
 
  TIMEOUT 5
  {{red|{{highlight|DEFAULT}} stm32mp157c-mydevicetree-mx}}
+
  {{red|{{highlight|DEFAULT}} stm32mp157f-mydevicetree-mx}}
  LABEL stm32mp157c-dk2-sdcard
+
  LABEL stm32mp157f-dk2-sdcard
 
         KERNEL /uImage
 
         KERNEL /uImage
 
         FDTDIR /
 
         FDTDIR /
 
         APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
 
         APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
  LABEL stm32mp157c-dk2-a7-examples-sdcard
+
  LABEL stm32mp157f-dk2-a7-examples-sdcard
 
         KERNEL /uImage
 
         KERNEL /uImage
         FDT /stm32mp157c-dk2-a7-examples.dtb
+
         FDT /stm32mp157f-dk2-a7-examples.dtb
 
         APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
 
         APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
  LABEL stm32mp157c-dk2-m4-examples-sdcard
+
  LABEL stm32mp157f-dk2-m4-examples-sdcard
 
         KERNEL /uImage
 
         KERNEL /uImage
         FDT /stm32mp157c-dk2-m4-examples.dtb
+
         FDT /stm32mp157f-dk2-m4-examples.dtb
 
         APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
 
         APPEND root=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console=ttySTM0,115200
  {{red|{{highlight|LABEL}} stm32mp157c-mydevicetree-mx
+
  {{red|{{highlight|LABEL}} stm32mp157f-mydevicetree-mx
 
         KERNEL /uImage
 
         KERNEL /uImage
         {{highlight|FDT}} /stm32mp157c-mydevicetree-mx.dtb
+
         {{highlight|FDT}} /stm32mp157f-mydevicetree-mx.dtb
 
         APPEND root&#61;PARTUUID&#61;e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console&#61;ttySTM0,115200}}
 
         APPEND root&#61;PARTUUID&#61;e91c4e10-16e6-4c0e-bd0e-77becf4a3582 rootwait rw console&#61;ttySTM0,115200}}
   
 
Please update/add the highlighted lines according to what have been compiled in chapter 5, 6 and/or 7:
 
Please update/add the highlighted lines according to what have been compiled in chapter 5, 6 and/or 7:
 
* {{highlight|DEFAULT}}: This is the default 'LABEL' to boot
 
* {{highlight|DEFAULT}}: This is the default 'LABEL' to boot
* {{highlight|LABEL}} : The entry 'LABEL' is the value of 'compatible' of the DTS file compiled with u-boot.
+
* {{highlight|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,stm32mp157c-mydevicetree-mx"
+
*: The 'compatible' value is at head of the DTS file and looks like : "st,stm32mp157f-mydevicetree-mx"
 
* {{highlight|FDT}} : The path from /boot of the kernel DTB to use
 
* {{highlight|FDT}} : The path from /boot of the kernel DTB to use
  +
  +
== Updating bootfs ==
  +
There are two methods to update bootfs:
  +
* <u>{{STDarkBlue|On an up and running target}}</u>
  +
:{{PC$}} scp stm32mp157f-mydevicetree-mx.dtb root@{{HighlightParam|''<Target_IP>''}}:/boot/
  +
* <u>{{STDarkBlue|Directly into 'bootfs' image}}</u>
  +
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 [[PC_prerequisites#WSL2_-28experimental-29|WSL2]]), is required:
  +
:{{PC$}} mkdir -p $WORKDIR/bootfs
  +
:{{PC$}} mount -o loop {{HighlightParam|''&lt;st-image-bootfs-openstlinux-weston-stm32mp1.ext4&gt;''}} $WORKDIR/bootfs
  +
:{{grey|##Then copy the new dtb file at the root of $WORKDIR/bootfs}}
  +
:{{PC$}} umount $WORKDIR/bootfs
  +
:{{PC$}} sync
  +
Then use [[STM32CubeProgrammer]] to update the bootfs partition.
   
 
=== Updating extlinux ===
 
=== Updating extlinux ===
Updating 'extlinux' consists in modifying the extlinux.conf. There are two ways to do this:
+
Updating 'extlinux' consists in modifying the extlinux.conf. There are two ways to proceed:
 
* <u>{{STDarkBlue|On an up and running target}}</u>
 
* <u>{{STDarkBlue|On an up and running target}}</u>
 
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.<br/>
 
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.<br/>
Line 233: Line 261:
 
* <u>{{STDarkBlue|Into 'bootfs' image directly}}</u>
 
* <u>{{STDarkBlue|Into 'bootfs' image directly}}</u>
 
You do not need to have a target up and running. Only the "st-image-bootfs-openstlinux-weston-stm32mp1.ext4" file is required.
 
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, avaible in any Linux Distribution (even through [[PC_prerequisites#WSL2_-28experimental-29|WSL2]]), is needed:
+
To modify an 'ext4' file, a loopback mount tool, available in any Linux Distribution (even through [[PC_prerequisites#WSL2_-28experimental-29|WSL2]]), is needed:
:{{PC$}} mkdir -p $WORKING/bootfs
+
:{{PC$}} mkdir -p $WORKDIR/bootfs
:{{PC$}} mount -o loop {{HighlightParam|&lt;st-image-bootfs-openstlinux-weston-stm32mp1.ext4&gt;}} $WORKING/bootfs
+
:{{PC$}} sudo mount -o loop {{HighlightParam|&lt;st-image-bootfs-openstlinux-weston-stm32mp1.ext4&gt;}} $WORKDIR/bootfs
 
:{{grey|##Then edit the extlinux.conf file (for WSL2 use a 'Linux' type editor; vi, ...)}}
 
:{{grey|##Then edit the extlinux.conf file (for WSL2 use a 'Linux' type editor; vi, ...)}}
 
:{{grey|##Once extlinux.conf up-to-date, umount loopback and flash the bootfs into sdcard with [[STM32CubeProgrammer]]}}
 
:{{grey|##Once extlinux.conf up-to-date, umount loopback and flash the bootfs into sdcard with [[STM32CubeProgrammer]]}}
   
 
<noinclude>
 
<noinclude>
  +
{{PublicationRequestId | 24428| 2022-08-29 | }}
 
[[Category:How to build software]]
 
[[Category:How to build software]]
 
</noinclude>
 
</noinclude>