How to configure TF-A FW CONFIG

1. Article Purpose[edit source]

This section details the TF-A firmware configuration file (FW_CONFIG). 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 (FCONF), it is possible to configure dynamically the BL2 stage using a configuration file. FW_CONFIG file is designed based on device tree model and parsed by the BL2 to manage the next loaded stages.
It is a key file that dynamically sets proper information to load, check size and discover the different firmware embedded 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 doesn't use the BL1 because it uses the ROM code. We have adapted the boot flow to use the FW_CONFIG. In order to keep the BL2 independent from the next stages, the FW_CONFIG file will be located into the FIP binary and loaded as the first binary in internal RAM.

The configuration description will design the internal RAM and DDR layout usage used by the next stages. For the STM32 MPU usage, all boards using same DDR size will inherit from the same FW_CONFIG.

When TRUSTED_BOARD_BOOT is enable, this FW_CONFIG file will be authenticated by a certificate describe in the CoT.

Warning

The properties described in this file will replace the hardcoded values previously defined in 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. Each node must contains:

Load address
Maximum binary size to be loaded
ID : Must match to the include/export/common/tbbr/tbbr_img_def_exp.h definition

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 allows to generate a file for OP-TEE OS support or SP_MIN management. Most of the defined values 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 is hardcoded using DDR_MAX_ADDRESS - STM32MP_DDR_S_SIZE.

4.2. Firewall management[edit source]

Depending the DDR usage on the product, the DDR firewall must be configured to restrict access to specific area. This must be done prior to binary loading. STM32 MPU extends 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 defines 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 git repository.

  git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.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 uses 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.

4.6.1. TF-A Build flags[edit source]

Here is the list of the mandatory flags that needs to be specify to complete the FW_CONFIG 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
AARCH32_SP=<sp_min/optee>: the FW_CONFIG may be associated to some BL32 specific flags (such as OP-TEE), so a AARCH32_SP must be properly selected

Optional flags:

BUILD_PLAT=<folder>: custom output folder name (default is build/<debug/release>/)
V=1: print verbose compilation traces

4.6.1. STM32MP15[edit source]

The default build command for STM32MP15 are:

  make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 AARCH32_SP=sp_min \
         DTB_FILE_NAME=<board>.dtb dtbs

or

  make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 AARCH32_SP=optee \
         DTB_FILE_NAME=<board>.dtb 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.