How to configure TF-A FIP

Revision as of 10:10, 10 March 2021 by Registered User
This message will disappear after all relevant tasks have been resolved.
Semantic MediaWiki
There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

1. Article Purpose[edit source]

This section details the TF-A FIP binary management for the STM32 MPU boot chain. It will explain the usage in STM32 MPU context and the build/update process that is required to deploy on your target.

2. Overview[edit source]

As explained in the TF-A Overview, this binary is used by the TF-A BL2 to load and authenticate the next stage binaries. It can contains:

  • Boot stage binaries
  • Configuration file (Device tree)
  • Certificate (X509.3 based) for authentication

3. Package structure[edit source]

The FIP binary use a specific layout that is parse by the BL2 during the load processing.

File:FIP layout.png

The FIP binary starts with a Table of Contents (ToC) that is recognized by the BL2. Each entry is identified with its UUID, offset in the package, size and flags. The end ToC marker is used to define the start of the binary section. All corresponding binaries are appended corresponding to the defined offset in the ToC entry.

This structure is automatically built using the fiptool command. It will append all the binaries and create the associated ToC.

4. Fiptool command[edit source]

fiptool is a host tool that must be used to generate the proper FIP binary.

OpenSTLinux SDK will provide the fiptool by default. You don't need to regenerate it if you want to update (or create) a FIP binary.

fiptool provides a set of useful commands to manage the FIP binary. All options can be listed using: 

   fiptool help
  • info : The fiptool info will provide information on a generated FIP binary
   fiptool info fip.bin 
    Secure Payload BL32 (Trusted OS): offset=0x100, size=0x1347C, cmdline="--tos-fw"
    Non-Trusted Firmware BL33: offset=0x1357C, size=0xEDDE2, cmdline="--nt-fw"
    FW_CONFIG: offset=0x10135E, size=0x226, cmdline="--fw-config"
    HW_CONFIG: offset=0x101584, size=0x1E412, cmdline="--hw-config"
    TOS_FW_CONFIG: offset=0x11F996, size=0x45AC, cmdline="--tos-fw-config"
  • update : Update allow to replace one or more images into an existing FIP binary
   fiptool update --tos-fw bl32.bin fip.bin

Optional argument can be used to avoid erasing the initial FIP binary 

   fiptool update --tos-fw bl32.bin --out new_fip.bin fip.bin
  • unpack : Extract all binaries from a FIP binary
   fiptool unpack fip.bin
  • remove : Remove a binary from FIP binary
   fiptool remove --tos-fw bl32.bin fip.bin

4.1. Generate the tool[edit source]

The tool is provided within the TF-A sources tools/fiptool . The tool can be build for Linux or Windows platform. A dedicate rule is available to generate the tool: 

   make fiptool

It will generate the tool in tools/fiptool/fiptool source path.

4.2. TF-A build[edit source]

In case of a TF-A component complete build process, it is possible to automatically generate the FIP binary. In this case the fiptool will be automatically generated too and the FIP binaries will be part of the output folder.

5. Cert_create command[edit source]

In case of TRUSTED_BOARD_BOOT feature enabled, the FIP must contain the binaries and their associated certificate as described in the TBBR[1] Chain of Trust (CoT). These certificate can be created using the cert_create command that is provided in the TF-A sources tools/cert_create .

OpenSTLinux SDK will provide the cert_create by default. You don't need to regenerate it if you want to regenerate certificates.

The cert_create tool is able to generate self-signed certificate used to complete the trusted boot chain and requires a large set of arguments linked to the CoT. 

   cert_create --help

cert_create will create certificate if not existing or use the given one to generate the CoT. In case of certificate content, they must be regenerated in case of associated binary update.

5.1. TF-A build[edit source]

TF-A generic Makefile can help to construct automatically the certificate with some dedicated flags that must be enabled to generate certificate and append them into the FIP.

  • GENERATE_COT=1 : Enable the cert_create tool
  • ROT_KEY : Specify the root private key to be used

6. FIP binary creation[edit source]

We will list below the different way to generate the FIP binary:

  • Using the dedicated fiptool command
  • Using the TF-A official Makefile

The FIP binary content may depend on the TRUSTED_BOARD_BOOT feature enable. In this case, a prior certificate generation is mandatory to include them into the FIP binary.

6.1. STM32MP1[edit source]

OpenSTLinux boot flow requires to load the following stages:

  • BL32: Secure OS and Secure Monitor (Could be SP-MIN or OP-TEE OS)
  • BL33: The non secure firmware (Recommended U-Boot)
  • HW_config: 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

To create the FIP binary, it is required to have all the required binaries built:

Info white.png Information
* Could be made in a single step using the TF-A Makefile

When TRUSTED_BOARD_BOOT feature is enabled in BL2, you must generate the associated certificate as per the TBBR CoT requirement.

The fiptool is used to create or update a FIP file.

The TF-A Makefile with fip target and with some variable use fiptool to create automatically the new FIP after the TF-A compilation.

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

Description Makefile
variable		 fiptool option file path for OP-TEE file path for SP_MIN
Secure OS (OP-TEE)
or Secure Monitor (SPMIN)		 BL32 --tos-fw <optee_path>/tee-header_v2.bin <tfa_path>/bl32.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 -
The firmware configuration file FW_CONFIG --fw-config <tfa_path>/fw-config.dtb
The 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

In the next chapter, all the files are assumed present in the current directory.

6.1.1. Trusted Bootchain[edit source]

6.1.1.1. Non Secure Boot[edit source]

The following command will generate the FIP package that is required by BL2 to boot. You can create the FIP binary using the fiptool command: 

   fiptool create --fw-config fw-config.dtb \
          --hw-config u-boot.dtb \
          --tos-fw-config bl32.dtb \
          --tos-fw bl32.bin \ 
          --nt-fw u-boot-nodtb.bin \
          fip.bin

You can also use the TF-A Makefile: 

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
          BL33=<u-boot_path>/u-boot-nodtb.bin \
          BL33_CFG=<u-boot_path>/u-boot.dtb \
          BL32=<tfa_path>/bl32.bin \
          FW_CONFIG=<tfa_path>/fw-config.dtb \
          fip

Adding the AARCH32_SP=sp_min will automatically manage the BL32 and FW_CONFIG path: 

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
          AARCH32_SP=sp_min \
          BL33=<u-boot_path>/u-boot-nodtb.bin \
          BL33_CFG=<u-boot_path>/u-boot.dtb \
          fip
6.1.1.2. Secure Boot[edit source]

You can create certificate and FIP binary using the cert_create and fiptool command: 

   cert_create \
          -n --tfw-nvctr 0 --ntfw-nvctr 0 \
          --key-alg ecdsa --hash-alg sha256 \
          --rot-key privateKey.pem \
          --tb-fw bl2.bin \
          --tb-fw-cert tb_fw.crt \
          --tos-fw-config bl32.dtb \
          --fw-config fw-config.dtb \
          --hw-config u-boot.dtb \
          --trusted-key-cert trusted_key.crt \
          --tos-fw-key-cert tos_fw_key.crt \
          --tos-fw-cert tos_fw_content.crt \
          --tos-fw bl32.bin \
          --nt-fw-key-cert nt_fw_key.crt \
          --nt-fw-cert nt_fw_content.crt \
          --nt-fw u-boot-nodtb.bin

You can now generate the FIP trusted package: 

   fiptool create \
          --tb-fw-cert tb_fw.crt \
          --fw-config fw-config.dtb \
          --hw-config u-boot.dtb \
          --trusted-key-cert trusted_key.crt \
          --tos-fw-key-cert tos_fw_key.crt \
          --tos-fw-config bl32.dtb \
          --tos-fw-cert tos_fw_content.crt \
          --tos-fw bl32.bin \
          --nt-fw-cert nt_fw_content.crt \
          --nt-fw-key-cert nt_fw_key.crt \
          --nt-fw u-boot-nodtb.bin \
          fip-trusted.bin

You can also use the TF-A Makefile: 

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
          BL33=<u-boot_path>/u-boot-nodtb.bin \
          BL33_CFG=<u-boot_path>/u-boot.dtb \
          BL32=<tfa_path>/bl32.bin \
          FW_CONFIG=<tfa_path>/fw-config.dtb \
          TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 ROT_KEY=<path_to_private_key>.pem \
          fip

Adding the AARCH32_SP=sp_min will automatically manage the BL32 and FW_CONFIG path: 

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
          AARCH32_SP=sp_min \
          BL33=<u-boot_path>/u-boot-nodtb.bin \
          BL33_CFG=<u-boot_path>/u-boot.dtb
          TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 ROT_KEY=<path_to_private_key>.pem \
          fip

6.1.2. OP-TEE Bootchain[edit source]

6.1.2.1. Non Secure Boot[edit source]

You can create the FIP binary using the fiptool command: 

   fiptool create --fw-config fw-config.dtb \
               --hw-config u-boot.dtb \
               --nt-fw u-boot-nodtb.bin \
               --tos-fw tee-header_v2.bin \
               --tos-fw-extra1 tee-pager_v2.bin \
               --tos-fw-extra2 tee-pageable_v2.bin \
               fip-optee.bin

You can also use the TF-A Makefile: 

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
           BL33=<u-boot_path>/u-boot-nodtb.bin BL33_CFG=<u-boot_path>/u-boot.dtb \
           BL32=<optee_path>/tee_header_v2.bin BL32_EXTRA1=<optee_path>/tee_pager_v2.bin \
           BL32_EXTRA2=<optee_path>/tee_pageable_v2.bin FW_CONFIG=<tfa_path>/fw-config.dtb fip

Adding the AARCH32_SP=optee will automatically manage the FW_CONFIG path: 

   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 fip


6.1.2.2. Secure Boot[edit source]

You can create certificate and FIP binary using the cert_create and fiptool command: 

   cert_create \
          -n --tfw-nvctr 0 --ntfw-nvctr 0 \
          --key-alg ecdsa --hash-alg sha256 \
          --rot-key privateKey.pem \
          --tb-fw bl2.bin \
          --tb-fw-cert tb_fw.crt \
          --tos-fw tee-header_v2.bin \
          --tos-fw-extra1 tee-pager_v2.bin \
          --tos-fw-extra2 tee-pageable_v2.bin \
          --fw-config fw-config.dtb \
          --hw-config u-boot.dtb \
          --trusted-key-cert trusted_key.crt \
          --tos-fw-key-cert tos_fw_key.crt \
          --tos-fw-cert tos_fw_content.crt \
          --nt-fw-key-cert nt_fw_key.crt \
          --nt-fw-cert nt_fw_content.crt \
          --nt-fw u-boot-nodtb.bin

You can now generate the FIP trusted package: 

   fiptool create \
          --tb-fw-cert tb_fw.crt \
          --fw-config fw-config.dtb \
          --hw-config u-boot.dtb \
          --trusted-key-cert trusted_key.crt \
          --tos-fw-key-cert tos_fw_key.crt \
          --tos-fw-cert tos_fw_content.crt \
          --tos-fw tee-header_v2.bin \
          --tos-fw-extra1 tee-pager_v2.bin \
          --tos-fw-extra2 tee-pageable_v2.bin \
          --nt-fw-cert nt_fw_content.crt \
          --nt-fw-key-cert nt_fw_key.crt \
          --nt-fw u-boot-nodtb.bin \
          fip-optee-trusted.bin

You can also use the TF-A Makefile: 

   make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 \
           BL33=<u-boot_path>/u-boot-nodtb.bin BL33_CFG=<u-boot_path>/u-boot.dtb \
           BL32=<optee_path>/tee_header_v2.bin BL32_EXTRA1=<optee_path>/tee_pager_v2.bin \
           BL32_EXTRA2=<optee_path>/tee_pageable_v2.bin FW_CONFIG=<tfa_path>/fw-config.dtb \
           TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 ROT_KEY=<path_to_private_key>.pem fip

Adding the AARCH32_SP=optee will automatically manage the FW_CONFIG path: 

   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 \
       TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 ROT_KEY=<path_to_private_key>.pem fip

6.2. Update FIP binary[edit source]

When modifying a component included in the FIP binary, it is possible to just update part of the binary. In this case the fiptool update command must be used:

Warning white.png Warning
When updating a binary in the FIP when the TRUSTED_BOARD_BOOT is enabled, the content certificate must be updated too. In this case the cert_create must be called with the previous generated certificate to avoid a complete CoT regeneration.

6.2.1. Updating TF-A SP-MIN[edit source]

When a modification is made in the SP-MIN binary (or its device tree), the SP-MIN must be update in the FIP binary.

  • Full SP-MIN update
   fiptool update --tos-fw BL32=<tfa_path>/bl32.bin --tos-fw-config <tfa_path>/bl32.dtb fip.bin
  • SP-MIN core binary
   fiptool update --tos-fw BL32=<tfa_path>/bl32.bin fip.bin
  • SP-MIN device tree update
   fiptool update --tos-fw-config <tfa_path>/bl32.dtb fip.bin

6.2.2. Updating U-Boot[edit source]

When a new U-Boot is generated, the FIP must be updated with the following commands:

  • Full U-Boot update
   fiptool update --nt-fw <u-boot_path>/u-boot-nodtb.bin --hw-config u-boot.dtb fip.bin
  • U-Boot core binary
   fiptool update --nt-fw <u-boot_path>/u-boot-nodtb.bin fip.bin
  • U-Boot device tree update
   fiptool update --hw-config u-boot.dtb fip.bin

6.2.3. Updating OP-TEE[edit source]

OP-TEE OS rebuild required to update the FIP package.

Warning white.png Warning
It is recommended to update all OP-TEE OS images rather than trying to just update the required one 
   fiptool update --tos-fw <optee_path>/tee-header_v2.bin \
          --tos-fw-extra1 <optee_path>/tee-pager_v2.bin \
          --tos-fw-extra2 <optee_path>/tee-pageable_v2.bin \
          fip-optee.bin

OP-TEE OS build process generate static binary location.
In case of mapping modification, the firmware configuration file must be adapted accordingly

6.2.4. Updating FW_CONFIG[edit source]

In case of change in the firmware configuration file, you must also update the FIP binary: 

   fiptool update --fw-config fw-config.dtb fip.bin

7. Update software on board[edit source]

7.1. Partitioning of binaries[edit source]

The FIP build provides a binary named fip.bin (or fip-<board-name>-<bootchain>.bin from official release) that MUST be copied to a dedicated partition named "fip".

7.2. Update via SDCARD[edit source]

If you use an SD card, you can simply update FIP binary the dd command on your host.
Plug your SD card into the computer and copy the binary to the dedicated partition; on an SDCard/USB disk the "fip" partition is partition 3: 

 - SDCARD: /dev/mmcblkXp3 (where X is the instance number)
 - SDCARD via USB reader: /dev/sdX3 (where X is the instance number)
  • 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 Jan 17 17:38 bootfs -> ../../mmcblk0p4
 lrwxrwxrwx 1 root root 10 Jan 17 17:38 fsbl1 -> ../../mmcblk0p1           FSBL1 (TF-A)
 lrwxrwxrwx 1 root root 10 Jan 17 17:38 fsbl2 -> ../../mmcblk0p2           FSBL2 (TF-A backup / same content as FSBL)
 lrwxrwxrwx 1 root root 10 Jan 17 17:38 rootfs -> ../../mmcblk0p5
 lrwxrwxrwx 1 root root 10 Jan 17 17:38 fip -> ../../mmcblk0p3            FIP
 lrwxrwxrwx 1 root root 10 Jan 17 17:38 userfs -> ../../mmcblk0p6


  • Windows

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

7.3. Update via USB mass storage on U-boot[edit source]

See How to use USB mass storage in U-Boot

Follow the previous section to put FIP binary onto SDCard/USB disk

7.4. Update your boot device via STM32CubeProgrammer[edit source]

Refer to the STM32CubeProgrammer documentation to update your target.

8. References[edit source]

  1. ↑ https://developer.arm.com/documentation/den0006/latest/
  2. ↑ http://gnuwin32.sourceforge.net/packages/coreutils.htm


Trusted firmware for Arm® Cortex®-A

Firmware image package is a packaging format used by TF-A

Microprocessor unit

Boot loader stage 2

Software development kit (A programming package that enables a programmer to develop applications for a specific platform.)

Boot loader stage 3-2

Operating system

Boot loader stage 3-3

Linux® is a registered trademark of Linus Torvalds.

Chain of trust

Open portable trusted execution environment

Das U-Boot -- the universal boot loader (see U-Boot)

Secure payload minimal

SD memory card (https://www.sdcard.org)

First stage boot loader

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