How to configure TF-A BL2

This page is a candidate for renaming (move). The requested new name is: STM32 MPU TF-A (BL2) . The supplied reason is: Article start to be generic and split properly between BL2 & BL32 part . -- LDE. Wiki maintainers: remember to update the pages that link this page before renaming (moving) it.

1. Article Purpose

This section details the TF-A BL2 component use as FSBL. It will explain the usage in STM32 MPU context and the build process from sources and how to deploy it on your target.
The build examples are based on the OpenSTLinux environment:

• Developer Package
• Distribution Package

2. Overview

TF-A BL2 is the FSBL for the ST boot chain. It is loaded by ROM Code in internal SYSRAM.
The main goal of this stage is to start the DDR to load (and authenticate) other larger firmwares.

2.1. STM32 binary file

The TF-A BL2 firmware needs to be STM32 encapsulated to be properly loaded into SYSRAM by the ROM Code. STM32 header information are mandatory for the ROM Code to load, authenticate and start the firmware.
As the ROM code is only able to load a single binary, the STM32 file must embed in the same image the header, the device tree and the BL2 firmware.

TF-A BL2 is part of the trusted boot and can be signed to be ROM Code authenticated. See Secure boot process.

2.2. Device tree

TF-A BL2 is based on device tree configuration. It uses the same device tree than the kernel but keeping only the mandatory nodes for the boot stage (to reduce binary size). The device tree is part of the final STM32 file to be authenticated by the ROM Code and loaded at the same time in the SYSRAM.
It must be configured or updated depending on your platform.

2.3. Storage management

TF-A BL2 needs to access storage to load the FIP. It will default use the boot device selected by boot pins or OTP.
This selected device needs to be properly setup:

• Device tree configuration (all devices)
• BL2 boot device configuration for Flash memories .

Each device support needs a specific framework in the BL2 firmware.
By default, STMicroelectronics chooses to select only one device support per binary. A BL2 full storage support could not fit with the SYSRAM size.
Storage build flags allow to configure the BL2 firmware to support the requested boot storage.

2.4. DDR

TF-A BL2 needs to setup the DDR to load the next binaries. DDR settings come from device tree and need to be adapted by customer depending the DDR type, DDR configuration and boards. This can be done using STM32CubeMX DDR settings.

2.5. Clock management

An initial clock tree as to be setup to allow access to DDR and external storage.
For performance benefits, it also allows to increase the default CPU speed and increase the storage transfer speeds.

2.6. Binary mapping

Here is the TF-A BL2 with STM32 header layout.

The different size can be customized depending build options, device tree customization. All sizes can be changed in the plaftorm definition file:
STM32MP1 platform uses plat/st/stm32mp1/stm32mp1_def.h .

• STM32MP_BL2_DTB_BASE : Device tree base address in SYSRAM with its associated SIZE
• STM32MP_BL2_RO_BASE: Define the start address where the code execution will be load and executed
• STM32MP_BL2_RW_BASE: Start address of read and write data used by code. It depends on the STM32MP_BL2_RO_SIZE. The STM32MP_BL2_RW_SIZE cannot exceed SYSRAM size.

2.7. BL2 load processing

Based on FIP and firmware configuration files, the same BL2 is able to manage dynamically different binary configurations:

• TF-A SP_MIN
• OP-TEE

The BL2 process is executed as described:

File:Bl2 load fconf.png

2.7.1. BL2 load in programmer mode

The programmer mode (USB or UART boot device) required the complete FIP to start the load image process as previously explained. This is achieved by loading the complete FIP binary into DDR before starting the normal boot sequence. The FIP load address is fixed and must not override the next loaded address :
DWL_BUFFER_BASE used in plat/st/common/stm32_io_storage.c

2.7.2. Low power mode

In case of low power exit, the BL2 will have to wake up DDR from self refresh and reload only binaries that have been lost.

Warning

When OP-TEE OS is used in pager mode (using SYSRAM), it is able to restore its content itself thanks to DDR backup and backup context

.

2.8. Trusted boot support

This feature is enabled by defining the TRUSTED_BOARD_BOOT build flag which is not default enabled.
As soon as the flag is enabled, authentication is enabled and certificates are mandatory into the FIP.

2.8.1. MBEDTLS

Using FIP, X509.v3 certificates are embedded in the package to authenticate all loaded binaries. The certificate parser is done using MBEDTLS. The MBEDTLS project is partially used during the trusted boot build process to retreive part of the library to parse the certificate. The project needs to be downloaded closed to TF-A sources and defined the path using the MBEDTLS_DIR variable.

2.8.2. Dynamic authentication disable

A DYN_DISABLE_AUTH flag can be used to build the full BL2 content (including the MDEBTLS files required) and allows to enable or disable authentication using a device tree property:

disable_auth = <0x0>; // To enable authentication
disable_auth = <0x1>; // To bypass authentication

This device tree property is located in the BL2 device tree (trusted boot device tree).

2.8.3. Crypto Library

STM32 MPU use its own cryptographic library (thanks to hardware accelerators or ROM Code services (STM32MP15 Only)) to verify certificate signatures: plat/st/common/stm32mp_crypto_lib.c

2.8.4. Keys

Authentication is based on different keys and certificates. The Arm TBBR CoT is used by default and topology is defined in the BL2 device tree fdts/cot_descriptors.dtsi and can be customized by used <link here to authentication article>. STM32 MPU use the default public root key hash in OTP as main root key for the CoT.
It can be redefined by customer <link to update>.

During development, the ROTK hash is not mandatory. If not fused in OTP, it will be seen as NOT DEPLOYED and the final ROTK hash control will be bypass. But the entire CoT will be verified.

Warning

The ROTK has must be in OTP before closing the chip

3. Source code access and build process

Cross compilation of TF-A BL2 is only required if it is to be modified.
By default, in the Starter Package, the TF-A BL2 images are named: tf-a-<board>-<storage>.stm32.
If changes are made, you must rebuild TF-A and update all the FSBL partitions of your boot device with this new image. A second FSBL image is used by ROM code as a backup image in case of corruption.

The build process creates a STM32 image. This binary is built in a single step during the build process.

4. Developer Package

4.1. Install sources

The Developer Package contains OpenSTLinux and TF-A sources: TF-A Installation

4.2. Official source tree

Download source code from the official Trusted Firmware-A github.

  git clone https://github.com/ARM-software/arm-trusted-firmware.git

Warning

The STM32MP1 platform is not yet fully upstreamed. Depending on the version used, some features may not be available.

For a full feature software, a STMicroelectronics github is available:

  git clone https://github.com/STMicroelectronics/arm-trusted-firmware.git

4.3. Build Process

4.3.1. Initialize the cross compile environment

Setup Cross compile environment

4.3.2. TF-A Build flags

Here is the list of the mandatory flags that needs to be specify to complete the TF-A BL2 build:

• ARM_ARCH_MAJOR=7: the major version of ARM Architecture to target (STM32MP1 is ARMv7 architecture based)
• ARCH=aarch32: specify aarch32 architecture to be built
• PLAT=stm32mp1: builds an stm32mp1 platform
• DTB_FILE_NAME=<fdt file name>.dtb: this must be defined to build the proper target and include the correct DTB file into the final file
• The boot device(s) you use, one (or more) of:
  • STM32MP_EMMC=1
  • STM32MP_SDMMC=1
  • STM32MP_RAW_NAND=1
  • STM32MP_SPI_NAND=1
  • STM32MP_SPI_NOR=1
• Or a programming interface:
  • STM32MP_UART_PROGRAMMER=1
  • STM32MP_USB_PROGRAMMER=1

Optional flags:

• DEBUG=1: add debug information in all binaries
• V=1: print verbose compilation traces
• TRUSTED_BOARD_BOOT=1: add MBEDTLS build sources and authentication framework
• DYN_DISABLE_AUTH=1: Allow to enable/disable authentication using device tree
• STM32MP_FORCE_MTD_START_OFFSET= <value>: Override the default start offset to read FIP on MTD devices (need to be aligned with FlashLayout).
• STM32MP_USE_EXTERNAL_HEAP=1: Can be enabled to define MBEDTLS heap out of BL2 sources (defined in device tree).

4.4. Build command

As previously explained, the BL2 generation depends on selected storage, default is to only support one storage.

Warning

The DTB_FILE_NAME flag and the selected storage must be set to select the correct board configuration. The device tree file for the target must be located in fdts folder (<board>.dts)

You must add your own environment flags:

  unset LDFLAGS;
  unset CFLAGS;

Then you will have to compile the TF-A BL2.
To avoid binary override, it is recommended to specify BUILD_PLAT per selected storage.

The default build command for STM32MP15 is

  make -j4 ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 <Selected storage> DTB_FILE_NAME=<board_name>.dtb BUILD_PLAT=build/<storage>

Here are build commands for the stm32mp157c-ev1 board (which support different storage):

• Flash programming support

  make -j4 ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_USB_PROGRAMMER=1 DTB_FILE_NAME=stm32mp157c-ev1.dtb BUILD_PLAT=build/usb 
  make -j4 ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_UART_PROGRAMMER=1 DTB_FILE_NAME=stm32mp157c-ev1.dtb BUILD_PLAT=build/uart

• Dedicated boot storage

  make -j4 ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_SDMMC=1 DTB_FILE_NAME=stm32mp157c-ev1.dtb BUILD_PLAT=build/sdmmc
  make -j4 ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_EMMC=1 DTB_FILE_NAME=stm32mp157c-ev1.dtb BUILD_PLAT=build/emmc
  make -j4 ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_RAW_NAND=1 DTB_FILE_NAME=stm32mp157c-ev1.dtb BUILD_PLAT=build/raw_nand
  make -j4 ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_SPI_NOR=1 DTB_FILE_NAME=stm32mp157c-ev1.dtb BUILD_PLAT=build/spi_nor
 Not available on board
  make -j4 ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_SPI_NAND=1 DTB_FILE_NAME=stm32mp157c-ev1.dtb BUILD_PLAT=build/spi_nand
 

From the Developer Package tarball, a Makefile.sdk is present and must be used to build the target. It automatically sets the proper configuration for the TF-A build.

  make -f Makefile.sdk TF_A_CONFIG=<to be completed>

The latest version of the helper file is also available in GitHub: README_HOWTO.txt .

4.5. Final image

Final image is available for Flash or SD card update in the corresponding folder:

<BUILD_PLAT>/<target>/tf-a-<target>.stm32
Ex:
build/sdmmc/stm32mp157c-ev1/tf-a-stm32mp157c-ev1.stm32

5. Distribution Package

For an OpenSTLinux distribution, the TF-A image is built in release mode by default. The yocto recipe can be found in:

meta-st/meta-st-stm32mp/recipes-bsp/trusted-firmware-a/tf-a-stm32mp_<version>.bb

If you want to modify the TF-A BL2 code source, use the following steps starting from an already downloaded and built OpenSTLinux distribution.

5.1. Access sources

You can use devtool to access the source.

  cd <baseline root directory>
  devtool modify tf-a-stm32mp sources/boot/tf-a

By going to the sources/boot/tf-a folder, you can manage and modify the TF-A sources. To rebuild it, go back to the build-<distribution> folder and launch the TF-A recipe:

  bitbake tf-a-stm32mp

The final image is deployed in the image default output folder.

6. Update software on board

6.1. Partitioning of binaries

The TF-A build provides a binary named tf-a-stm32mp157c-<board>.stm32 (or tf-a-stm32mp157c-<board>-storage.stm32 from Makefile.sdk) that MUST be copied to a dedicated partition named "fsblX" (X depends on the number of needed backups in the Flash).

Warning

TF-A must be located in the first partition of your boot device. You can just update the first partition for a simple test, but all backup partitions must contain the same image at the end.

6.2. Update via SDCARD

If you use an SD card, you can simply update TF-A using 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 "fsbl1" partition is partition 1:

 - SDCARD: /dev/mmcblkXp1 (where X is the instance number)
 - SDCARD via USB reader: /dev/sdX1 (where X is the instance number)

• Linux

  dd if=<tf-a file>.stm32 of=/dev/<device partition> bs=1M conv=fdatasync

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 fip -> ../../mmcblk0p3 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 userfs -> ../../mmcblk0p6

• Windows

CoreUtils that includes the dd command is available for Windows.

6.3. Update via USB mass storage on U-boot

See How to use USB mass storage in U-Boot

Follow the previous section to put tf-a-<board>-<storage>.stm32 onto SDCard/USB disk

6.4. Update your boot device via STM32CubeProgrammer

Refer to the STM32CubeProgrammer documentation to update your target.

7. Secure secret provisioning

Warning

This feature is only available for STM32 MPU with cryptographic accelerators

STM32 MPU support SSP feature. One part of this feature is based on TF-A BL2.

• Exchange with STM32_CubeProgrammer
• Program OTPs

A specific TF-A BL2 build is required to manage SSP.

Warning

This STM32 output file must be signed to complete the SSP feature

Dedicated files are delivered in the platform folder that contains the specific Makefile and platform_setup for the TF-A SSP.
The TF-A SSP is a subset part of the standard TF-A BL2 that only includes:

• BL2 device tree
• BL2 image with limited support to the serial link device.

7.1. Developer Package

7.1.1. Install sources

The Developer Package contains OpenSTLinux and TF-A-SSP sources: TF-A-SSP Installation

Warning

The SSP is a specific ST feature and will never be upstreamed.

7.1.2. Additional Flags

Mandatory flags to build the TF-A SSP are:

• STM32MP_SSP=1

For the serial link (exclusive)

• STM32MP_UART_PROGRAMMER=1
• STM32MP_USB_PROGRAMMER=1

7.1.3. Build command

  make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_SSP=1 STM32MP_USB_PROGRAMMER=1 DTB_FILE_NAME=<board>.dtb BUILD_PLAT=build/ssp_usb
 or 
  make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_SSP=1 STM32MP_UART_PROGRAMMER=1 DTB_FILE_NAME=<board>.dtb BUILD_PLAT=build/ssp_uart 

7.1.4. Final image

Final image is available in the corresponding folder:

<BUILD_PLAT>/<target>/tf-a-ssp-<target>.stm32
Ex:
build/ssp_usb/stm32mp157c-ev1/tf-a-ssp-stm32mp157c-ev1-usb.stm32

7.2. Distribution Package

For an OpenSTLinux distribution, the TF-A SSP image is not built in release mode by default. The yocto recipe can be found in:

meta-st/meta-st-stm32mp/recipes-bsp/trusted-firmware-a/tf-a-stm32mp-ssp_<version>.bb

If you want to modify the TF-A SSP code source, use the following steps starting from an already downloaded and built OpenSTLinux distribution.

7.2.1. Access sources

You can use devtool to access the source.

  cd <baseline root directory>
  devtool modify tf-a-stm32mp-ssp sources/boot/tf-a_ssp

By going to the sources/boot/tf-a_ssp folder, you can manage and modify the TF-A sources. To rebuild it, go back to the build-<distribution> folder and launch the TF-A recipe:

  bitbake tf-a-stm32mp-ssp

The final image is deployed in the image default output folder.

Microprocessor unit

Trusted firmware for Arm^® Cortex^®-A

Boot loader stage 2

Boot loader stage 3-2

First stage boot loader

Doubledata rate (memory domain)

Read only memory

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

Central processing unit

Device tree binary (or Blob)

Universal asynchronous receiver/transmitter

Open portable trusted execution environment

Operating system

Arm^® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

Chain of trust

One time programmed

Serial peripheral interface

Memory technology device

Flash memory shortened to gain space in titles, tables and block diagrams

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

Linux^® is a registered trademark of Linus Torvalds.

Secure secret provisioning