Last edited 2 months ago

How to configure TF-A FIP

Applicable for STM32MP13x lines, STM32MP15x lines, STM32MP21x lines, STM32MP23x lines, STM32MP25x lines


1. Article purpose↑

This section details the Trusted Firmware-A FIP (Firmware Image Package) usage in the STM32 MPU boot chain. It explains how to use it in STM32 MPU context and describes the build/update process that is required to deploy it on your target.

2. Overview↑

The FIP is used by the Trusted Firmware-A BL2 firmware to load and authenticate the next stage binaries.

The FIP follows the Trusted Firmware-A specification[1].

It must contains:

Warning white.png Warning
If Trusted Firmware-A BL2 is built with TRUSTED_BOARD_BOOT enabled, the FIP must also contain:
  • Certificates (X509.3 based) for authentication.

3. Firmware Image Package creation tool↑

Trusted Firmware-A provides a dedicated tool named fiptool to create a FIP.[2]

Info white.png Information
By default, the OpenSTLinux SDK provides the fiptool command. You do not need to regenerate it to update (or create) a FIP binary.

If you want to regenerate it, you must follow the official documentation[3]
. The official documentation introduces the different available options.

Here is the list of the most useful options:

Options Description Example
help Show all available options supported fiptool help
info List the content of a FIP:
  • offset in the FIP
  • size in the FIP
  • cmdline option to modify the binary
 fiptool info fip.bin 
Secure Payload BL32 (Trusted OS): offset=0x128, size=0x2C, cmdline="--tos-fw"
Secure Payload BL32 Extra1 (Trusted OS Extra1): offset=0x154,
 size=0x18750, cmdline="--tos-fw-extra1"
Secure Payload BL32 Extra2 (Trusted OS Extra2): offset=0x188A4,
 size=0x56000, cmdline="--tos-fw-extra2"
Non-Trusted Firmware BL33: offset=0x6E8A4, size=0xECE98, cmdline="--nt-fw"
FW_CONFIG: offset=0x15B73C, size=0x1FA, cmdline="--fw-config"
HW_CONFIG: offset=0x15B936, size=0x1BC08, cmdline="--hw-config"
update Update allows one or more images to be replaced in an existing FIP binary fiptool update --tos-fw bl32.bin fip.bin
unpack Extracts all binaries from a FIP binary fiptool unpack fip.bin
remove Removes a binary from FIP binary fiptool remove --tos-fw bl32.bin fip.bin

4. FIP binary creation↑

Below the list of the different ways by which the FIP binary can be generated:

  • Using the dedicated fiptool command
  • Using the Trusted Firmware-A official Makefile options for the make target fip

4.1. STM32MP1 series↑

The OpenSTLinux boot flow requires the following stages to be loaded:

  • BL32: Secure OS OP-TEE OS
  • BL33: The non-secure firmware (recommended U-Boot)
  • HW_config: The OpenSTLinux uses the hw_config as the non-secure device tree
  • FW_config: Firmware configuration file listing the previous images and defining their size and the load address

The Trusted Firmware-A Makefile with fip target and some variables uses fiptool to automatically create the new FIP after the Trusted Firmware-A compilation.

With U-Boot as a non-secure firmware, the paths for the files used in next chapters are the following:

Description Makefile
variable		 fiptool option File path
Secure OS (OP-TEE) BL32 --tos-fw <optee_path>/tee-header_v2.bin
OP-TEE pager BL32_EXTRA1 --tos-fw-extra1 <optee_path>/tee-pager_v2.bin
OPTEE pageable BL32_EXTRA2 --tos-fw-extra2 <optee_path>/tee-pageable_v2.bin
Firmware configuration file FW_CONFIG --fw-config <tfa_path>/fdts/<board>-fw-config.dtb
U-Boot device tree BL33_CFG --hw-config <u-boot_path>/u-boot.dtb
U-Boot BL33 --nt-fw <u-boot_path>/u-boot-nodtb.bin

For example, the makefile command to generate STM32MP15F-EV1 fip is: 

make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 AARCH32_SP=optee \
BL32=<optee_path>/tee-header_v2.bin \
BL32_EXTRA1=<optee_path>/tee-pager_v2.bin \
BL32_EXTRA2=<optee_path>/tee-pageable_v2.bin \
DTB_FILE_NAME=stm32mp157f-ev1.dtb \
BL33=<u-boot_path>/u-boot-nodtb.bin \
BL33_CFG=<u-boot_path>/u-boot.dtb fip


4.2. STM32MP2 series↑

The OpenSTLinux boot flow requires the following stages to be loaded:

  • BL31: Secure Monitor BL31
  • BL31 device tree
  • BL32: Secure OS OP-TEE OS
  • BL33: The non-secure firmware (recommended U-Boot)
  • HW_config: The OpenSTLinux uses the hw_config as the non-secure device tree
  • FW_config: Firmware configuration file listing the previous images and defining their size and the load address
  • DDR firmware

The Trusted Firmware-A Makefile with fip target and some variables uses fiptool to automatically create the new FIP after the Trusted Firmware-A compilation.

With U-Boot as a non-secure firmware, the paths for the files used in next chapters are the following:

Description Makefile
variable		 fiptool option File path
Secure Monitor (BL31) BL31 --soc-fw <tfa_path>/bl31.bin
Secure Monitor device tree (BL31 DT) BL31 --soc-fw-config <tfa_path>/fdts/<board>-bl31.dtb
Secure OS (OP-TEE) BL32 --tos-fw <optee_path>/tee-header_v2.bin
OP-TEE pager BL32_EXTRA1 --tos-fw-extra1 <optee_path>/tee-pager_v2.bin
OPTEE pageable BL32_EXTRA2 --tos-fw-extra2 <optee_path>/tee-pageable_v2.bin
Firmware configuration file FW_CONFIG --fw-config <tfa_path>/fdts/<board>-fw-config.dtb
U-Boot device tree BL33_CFG --hw-config <u-boot_path>/u-boot.dtb
U-Boot BL33 --nt-fw <u-boot_path>/u-boot-nodtb.bin
DDR Firmware DDR FW --ddr-fw <tfa_sources>/drivers/st/ddr/phy/firmware/bin/stm32mp2/<ddr_type>_pmu_train.bina

a: The DDR Firmware can also be downloaded from https://github.com/STMicroelectronics/stm32-ddr-phy-binary with git. This is the default repository when using a TF-A downloaded from TrustedFirmware.org. In this case, the DDR firmware path in the fiptool command will be: <ddr_fw_sources>/stm32mp2/<ddr_type>_pmu_train.bin

For example, the makefile commande to generate STM32MP257F-EV1 fip is: 

make ARCH=aarch64 PLAT=stm32mp2 SPD=opteed STM32MP_DDR4_TYPE=1 \
DTB_FILE_NAME=stm32mp257f-ev1.dtb bl31 fip \
BL32=<optee_path>/tee-header_v2.bin \
BL32_EXTRA1=<optee_path>/tee-pager_v2.bin \
BL32_EXTRA2=<optee_path>/tee-pageable_v2.bin \
DTB_FILE_NAME=stm32mp157f-ev1.dtb \
BL33=<u-boot_path>/u-boot-nodtb.bin \
BL33_CFG=<u-boot_path>/u-boot.dtb

4.3. Trusted Boot↑

Warning white.png Warning
If Trusted Firmware-A BL2 is built with TRUSTED_BOARD_BOOT enabled, some specific options and files are required. See the Trusted boot page for more details.

4.4. Updating the FIP binary↑

When modifying a component included in the FIP binary, it is possible to update only part of the binary. To do this, use the fiptool update command.

Example when a new U-Boot is generated, the FIP must be updated using the following commands:

  • Full U-Boot update (U-Boot Binary and U-Boot Device tree)
fiptool update --nt-fw <u-boot_path>/u-boot-nodtb.bin --hw-config <u-boot_path>/u-boot.dtb fip.bin
Warning white.png Warning
When updating a binary in the FIP when the Trusted Firmware-A BL2 is built with TRUSTED_BOARD_BOOT enabled, the content certificate must be updated too. See the Trusted Board Boot for more details.

5. Updating the software on board↑

5.1. Partitioning of binaries↑

The FIP build provides a binary named fip.bin (or fip-<board-name>-<bootchain>.bin from official release). It MUST be copied to a dedicated partition for which the partition type GUID is 19d5df83-11b0-457b-be2c-7559c13142a5 (STM32MP_FIP_GUID in plat/st/common/include/stm32mp_efi.h ). As a fallback, TF-A will look for a partition named fip. When Secure Firmware Update is enabled, the 2 partitions are named fip-a and fip-b, but those names won't be used by TF-A.

5.2. Updating via SDCard↑

If you use an SDCard, simply update the FIP binary by using the dd command on your host.
Plug your SDCard into the computer and copy the binary to the dedicated partition; on an SDCard/USB disk the fip partition or fip-a/fip-b when Secure Firmware Update is enabled: 

 - SDCard: /dev/mmcblkXpY (where X is the instance number, Y is the partition number of the FIP)
 - SDCard via USB reader: /dev/sdXY (where X is the instance number, Y is the partition number of the FIP))
  • Under Linux®
  dd if=<fip binary file> of=/dev/<device partition> bs=1M conv=fdatasync
Info white.png Information
To find the partition associated to a specific label, just plug the SDCard/USB disk into your PC and call the following command: 
  ls -l /dev/disk/by-partlabel/
 total 0
 lrwxrwxrwx 1 root root 10 May  3 15:14 bootfs -> ../../sda8
 lrwxrwxrwx 1 root root 10 May  3 15:14 fip-a -> ../../sda5           FIP (Image A)
 lrwxrwxrwx 1 root root 10 May  3 15:14 fip-b -> ../../sda6           FIP (Image B)
 lrwxrwxrwx 1 root root 10 May  3 15:14 fsbl1 -> ../../sda1           FSBL1 (Trusted Firmware-A BL2)
 lrwxrwxrwx 1 root root 10 May  3 15:14 fsbl2 -> ../../sda2           FSBL2 (Trusted Firmware-A BL2 backup)
 lrwxrwxrwx 1 root root 10 May  3 15:14 metadata1 -> ../../sda3
 lrwxrwxrwx 1 root root 10 May  3 15:14 metadata2 -> ../../sda4
 lrwxrwxrwx 1 root root 11 May  3 15:14 rootfs -> ../../sda10
 lrwxrwxrwx 1 root root 10 May  3 15:14 u-boot-env -> ../../sda7
 lrwxrwxrwx 1 root root 11 May  3 15:14 userfs -> ../../sda11
 lrwxrwxrwx 1 root root 10 May  3 15:14 vendorfs -> ../../sda9


  • Under Windows®

CoreUtils [4] that includes the dd command is available for Windows.

5.3. Updating via USB mass storage on U-boot↑

See How to use USB mass storage in U-Boot.

Refer to the previous section to put FIP binary into SDCard/USB disk.

5.4. Updating your boot device via STM32CubeProgrammer↑

Refer to the STM32CubeProgrammer documentation for details on how to update your target.

6. References↑

  1. ↑ Firmware Image Package design
  2. ↑ Firmware Image Package tool
  3. ↑ Building and using the fiptool
  4. ↑ http://gnuwin32.sourceforge.net/packages/coreutils.htm


Retrieved from "https://wiki.st.com/stm32mpu/index.php?title=How_to_configure_TF-A_FIP&oldid=114722"