How to configure TF-A FW CONFIG

1. Article Purpose[edit source]

This section details the TF-A FW_CONFIG file. It will explain how to configure it to update 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]

Thanks to TF-A Firmware configuration framework, it is possible to configure firmware using a configuration file. FW_CONFIG file is designed to be used by the BL2 to configure the next stages to be loaded.
It is a key file that dynamically set proper information to load, check size and discovered the different firmware embed in the FIP binary.

3. Configuration[edit source]

Each board must embed the FW_CONFIG file in the FIP binary. Originally, this file is loaded from BL1 and given to the BL2 through arguments.
STM32 MPU limitation using the ROM code will not use the FW_CONFIG file in this way. In order to make keep the BL2 independent from the next stages, the FW_CONFIG file will be located into the FIP binary and loaded at the first binary in internal RAM.

Content described in this file will describe the bootchain.

It will design the internal RAM and DDR layout usage during the boot process. For the STM32 MPU usage, all boards using same DDR will inherit from the same FW_CONFIG.

When TRUSTED_BOARD_BOOT is enable, this FW_CONFIG file must be authenticated and will be signed by a certificate.

Warning

The properties describe in this file will replace the hardcoded values previously defined in static the bl2_mem_param_desc structure in include/common/desc_image_load.h . The FW_CONFIG file must reflect the defined structure.

4. Structure[edit source]

4.1. Image properties[edit source]

This part is the generic part of the FW_CONFIG.

As defined in the FCONF device tree bindings docs/components/fconf/fconf_properties.rst , this part will describe the firmware to be loaded and their properties.

Here is an example used with STM32MP15 (Eval board with 1GB DDR):
fdts/stm32mp15-ddr-512m-fw-config.dts

  dtb-registry {
          compatible = "fconf,dyn_cfg-dtb_registry";
          hw-config {                                            HW_CONFIG file section
                  load-address = <0x0 STM32MP_HW_CONFIG_BASE>;   // STM32MP_HW_CONFIG_BASE and SIZE 
                  max-size = <STM32MP_HW_CONFIG_MAX_SIZE>;       // are defined in platform definition file
                  id = <HW_CONFIG_ID>;                           // Unique ID defined in
                                                                 // include/export/common/tbbr/tbbr_img_def_exp.h 
           };
           ...
  #ifdef AARCH32_SP_OPTEE                                          OP-TEE specific 
           tos_fw {
                   load-address = <0x0 0x2FFC0000>;                // Load address in SYSRAM
                   max-size = <0x0001F000>;                        // Maximum firmware size
                   id = <BL32_IMAGE_ID>;                           // Unique ID
           };
  #else

In this example, the file used allow to generate a file for OP-TEE OS support or SP_MIN management. Most of the defined use the generic enum from TF-A source code but they can be replaced by hardcoded values.

In the OP-TEE usage, the tos_fw is related to the tee_header AND tee_pager part. As explain in the OP-TEE page, the header_v2 will also indicate the pager_v2.bin startup address and the pageable part (when enable) is platform specific. The header_v2 will only indicate the binary size. In STM32MP15, as the pager mode is used, the pageable start address hardcoded using DDR_MAX_ADDRESS - STM32MP_DDR_S_SIZE.

4.2. Firewall management[edit source]

For some hardware loading management, the firmwall have to be prepared prior loading the images in DDR. STM32 MPU extend the FW_CONFIG file to manage the firewall access.

The associated definitions and macros are defined in include/dt-bindings/soc/stm32mp1-tzc400.h

   compatible = "st,mem-firewall";
        memory-ranges = <
               0xc0000000 0x1e000000 TZC_REGION_S_NONE TZC_REGION_NSEC_ALL_ACCESS_RDWR
               0xde000000 0x01e00000 TZC_REGION_S_RDWR 0
               0xdfe00000 0x00200000 TZC_REGION_S_NONE
               TZC_REGION_ACCESS_RDWR(STM32MP1_TZC_A7_ID)>;

The previous example defined 3 regions:

Start at 0xc0000000 : Size is 480MB where secure access is forbidden and all non secure peripheral can access
Start at 0xde000000 : Size is 30MB where only secure access is allowed
Start at 0xdfe00000 : Size is 2M where secure access is forbidden and non secure access is only possible by A7 CPU

4.3. Install sources[edit source]

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

4.4. Official source tree[edit source]

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.5. Initialize the cross compile environment[edit source]

Setup Cross compile environment

4.6. Build command[edit source]

FW_CONFIG file are device tree files located in the ftds folder.
FW_CONFIG file must be built using the TF-A Makefile.

You must add your own environment flags:

  unset LDFLAGS;
  unset CFLAGS;

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

As previously described, the FW_CONFIG may be associated to some BL32 specific flags (such as OP-TEE), so a AARCH32_SP can be used:

4.6.1. STM32MP15[edit source]

The default build command for STM32MP15 are:

  make -j4 ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 AARCH32_SP=sp_min \
         DTB_FILE_NAME=<board_name>.dtb BUILD_PLAT=build/sp_min dtbs

or

  make -j4 ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 AARCH32_SP=optee \
         DTB_FILE_NAME=<board_name>.dtb BUILD_PLAT=build/optee dtbs

4.7. Final image[edit source]

Final images are available for updating the FIP binary (including the associated firmware configuration file):

<BUILD_PLAT>/fdts/<board>-fw-config.dtb

4.8. Distribution Package[edit source]

For an OpenSTLinux distribution, the TF-A FW_CONFIG file 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 FW_CONFIG code source, use the following steps starting from an already downloaded and built OpenSTLinux distribution.

4.8.1. Access sources[edit source]

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.

4.9. Update software[edit source]

FW_CONFIG file is part of the FIP binary. The next step to deploy the FW_CONFIG firmware is to update the FIP binary following the FIP update process.