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.
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:
- Secure OS or Secure Monitor
- U-Boot.
- Firmware configuration file related to the loaded binaries*.
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:
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.
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
- 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]