Last edited one week ago

How to configure, build and deploy TF-M

Applicable for STM32MP21x lines, STM32MP23x lines, STM32MP25x lines

1. Article purpose[edit | edit source]

This section details the TF-M stage (Trusted Firmware-M). It explains how to configure and build TF-M in the STM32 MPU context, describes the build process from sources, and shows how to deploy it on the target device.

2. Build with a bare environment or STM32CubeIDE[edit | edit source]

2.1. Prerequisites[edit | edit source]

2.1.1. Linux® PC[edit | edit source]

2.1.1.1. Installing the build environment[edit | edit source]

Install the dependencies:

sudo apt-get install -y git curl wget build-essential libssl-dev python3 \
           python3-pip cmake make

Then add the CMake path to the environment:

export PATH=<CMake path>/bin:$PATH
2.1.1.2. Installing a toolchain[edit | edit source]

If using STM32CubeIDE to build TF-M, installing a toolchain is not necessary, since STM32CubeIDE comes with a built-in toolchain.

If using a command-line interface, download the toolchain and add the GNU Arm toolchain path to the environment:

export PATH=$PATH:<toolchain installation directory>/sysroots/x86_64-ostl_sdk-linux/usr/share/gcc-arm-none-eabi/bin

2.1.2. Windows® PC[edit | edit source]

2.1.2.1. Installing the build environment[edit | edit source]

Install the dependencies:

Important
It is recommended to install GNU make in a path without any space characters. Avoid /c/Program Files/, for example.

Then add the CMake path to the environment:

set PATH=<CMake_Path>/bin;%PATH%
2.1.2.2. Installing a toolchain[edit | edit source]

If using STM32CubeIDE to build TF-M, installing a toolchain is not necessary, since STM32CubeIDE comes with a built-in toolchain.

If using a command-line interface, use the toolchain from STM32CubeIDE and update the path in .bashrc as follows:

PATH="/c/ST/<STM32 CubeIDE path>/STM32CubeIDE/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.11.3.rel1.win32_1.1.2.202309201523/tools/bin":$PATH
Information
The plugin version may differ from one STM32CubeIDE version to another, so modify it accordingly.

2.2. Installing sources[edit | edit source]

2.2.1. Downloading source[edit | edit source]

For the full-featured software, go to the STMicroelectronics github:

 git clone https://github.com/STMicroelectronics/trusted-firmware-m.git
Warning
The STM32MP2 platform is not upstreamed.

For the record, the official Trusted Firmware-M git repository (without STM32MP2 support) can be downloaded there:

 git clone https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/
Warning
To run TF-M application with STM32CubeMP2 package, install the TF-M source inside STM32CubeMP2 Package Middlewares/Third_Party/.

2.3. Installing Python dependencies[edit | edit source]

From the TF-M source code installed on the PC:

pip3 install --upgrade pip \
           pip3 install -r tools/requirements.txt

2.4. Build process[edit | edit source]

Important
STMicroelectronics implementation uses the medium profile by default. See TF-M profile page for more information.
Only medium and large profile are supported for M33-TD flavor . Indeed, CONFIG_TFM_SPM_BACKEND set to IPC is mandatory for IPCC mailbox used by SCMI and PSA services. And by definition, CONFIG_TFM_SPM_BACKEND set to SFN is mandatory for small profile.

2.4.1. STM32CubeIDE[edit | edit source]

There is one Cortex®-M33 nonsecure STM32Cube firmware example that uses TF-M services and builds TF-M using STM32CubeIDE.
Refer to the How to build and debug secure project on Cortex-M33 coprocessor in STM32CubeIDE wiki page for a step-by-step build-and-load example with TF-M.

2.4.2. Build command lines[edit | edit source]

You can also use TF-M-tests for the tests and non-secure software example. Starting from ecosystem release v6.1.0 , TF-M is based on official release v2.1, for which build system has changed. You will need to fetch TF-M-tests:

 git clone https://github.com/STMicroelectronics/tf-m-tests.git ${TF-M-TESTS_DIRECTORY}


See the Github pages for compilation steps and the different possible build options for STM32MP257-EV1 or STM32MP215F-DK

2.4.3. External device tree for the STM32MP2 series[edit | edit source]

STMicroelectronics provides device tree configurations for others boards in a dedicated git repository: stm32mp2/a35-td/tfm/ .

The repository can be used to store custom configurations. Use the following command to build with this external dt repository:

 git clone https://github.com/STMicroelectronics/dt-stm32mp.git ${DT_PATH}

Depending on your configuration, you will need to add build options for the external DT files.

For A35-TD flavor and M33-TD flavor , more information is also given on Github pages for STM32MP257-EV1 or STM32MP215F-DK


2.4.3.1. Example for A35-TD flavor [edit | edit source]

DT_PATH can be set to any path, but it must not be a relative path.

       -DDTS_EXT_DIR=${DT_PATH}/stm32mp2/a35-td \
       -DDTS_BOARD_S=tfm/stm32mp257f-ev1-ca35tdcid-ostl-s.dts

And optionally, the nonsecure DT

       -DDTS_BOARD_NS=tfm/stm32mp257f-ev1-ca35tdcid-ostl-ns.dts
2.4.3.2. Example for M33-TD flavor [edit | edit source]

DT_PATH can be set to any path, but it must not be a relative path.

       -DDTS_EXT_DIR=${DT_PATH}/stm32mp2/m33-td \
       -DDTS_BOARD_S=tfm/stm32mp257f-ev1-cm33tdcid-ostl-sdcard-s.dts \
       -DDTS_BOARD_BL2=mcuboot/stm32mp257f-ev1-cm33tdcid-ostl-sdcard-bl2.dts

And optionally, the nonsecure DT

       -DDTS_BOARD_NS=tfm/stm32mp257f-ev1-cm33tdcid-ostl-sdcard-ns.dts

2.5. Extra compilation flags[edit | edit source]

2.5.1. Flags to debug TF-M faults[edit | edit source]

TF-M can print secure-partition and Secure Partition Manager (SPM) diagnostics when investigating a fault in an application using TF-M services. Add the following options to the TF-M secure-image CMake configuration command described above:

-DTFM_PARTITION_LOG_LEVEL=TFM_PARTITION_LOG_LEVEL_DEBUG \
-DTFM_SPM_LOG_LEVEL=TFM_SPM_LOG_LEVEL_DEBUG \
-DTFM_EXCEPTION_INFO_DUMP=ON \
-DTFM_LOG_FATAL_ERRORS=ON \
-DTFM_LOG_NONFATAL_ERRORS=ON \
-DTFM_LOG_ERR_FILE_AND_LINE=ON \
-DCONFIG_TFM_BACKTRACE_ON_CORE_PANIC=ON
  • TFM_PARTITION_LOG_LEVEL=TFM_PARTITION_LOG_LEVEL_DEBUG: Prints debug messages from secure partitions.
  • TFM_SPM_LOG_LEVEL=TFM_SPM_LOG_LEVEL_DEBUG: Prints debug messages from the SPM.
  • TFM_EXCEPTION_INFO_DUMP=ON: Captures exception context and prints it when the configured SPM logging level permits.
  • TFM_LOG_FATAL_ERRORS=ON: Logs fatal errors when they occur.
  • TFM_LOG_NONFATAL_ERRORS=ON: Logs nonfatal errors when they occur.
  • TFM_LOG_ERR_FILE_AND_LINE=ON: Adds source filenames and line numbers to fatal and nonfatal error logs.
  • CONFIG_TFM_BACKTRACE_ON_CORE_PANIC=ON: Prints a backtrace on a secure core panic, then halts.
Important
The STM32MP2 TF-M platform configuration forces the SPM and partition log levels to INFO. Passing the two DEBUG options above is therefore not sufficient on its own. For a local debug build, change their values from TFM_SPM_LOG_LEVEL_INFO and TFM_PARTITION_LOG_LEVEL_INFO to the corresponding ..._DEBUG values in platform/ext/target/stm/common/stm32mp2xx/config.cmake , then reconfigure and rebuild. Restore the platform configuration after debugging.

The STM32MP2 platform configuration already enables exception information dumps and core-panic backtraces. Reconfigure and rebuild the secure image, deploy it using the same procedure as for the original build, and inspect the TF-M console output when reproducing the fault. Check the effective values in <BUILD_DIRECTORY>/build_spe/CMakeCache.txt if the expected logs do not appear.

Warning
Verbose diagnostics can disclose information about secure execution. Use this configuration for development and restore production logging settings before distributing firmware.

2.5.2. SoC revision flags[edit | edit source]

TF-M supports 2 SoC revisions for STM32MP23x lines  and STM32MP25x lines , Rev Y and Rev X. There are flags in TF-M to choose the revision: STM32_STM32MP23_SOC_REV for STM32MP23x lines  and STM32_STM32MP23_SOC_REV for STM32MP25x lines . They are set by default to revY. If your SoC is a revision X, you can update the flag in the TF-M compilation command line, depending on the SoC:

-DSTM32_STM32MP23_SOC_REV=revX

or

-DSTM32_STM32MP25_SOC_REV=revX

This allows skipping the workarounds done for SoC revision Y.

3. Build with Developer package[edit | edit source]

For the A35-TD flavor , only CubeIDE is supported to build TF-M
For the M33-TD flavor , TF-M is managed by Developper package. please refer to the following article to understand how to install & develop: STM32MPU Developer Package

4. Build with Distribution package[edit | edit source]

The Linux Yocto-based distribution package (STM32MPU distribution package) integrates the TF-M components source code in a dedicated recipe in the OpenSTLinux distribution.
To generate the three required binaries for M33TD flavor — **MCUBoot**, **DDR firmware** and **M33 firmware** — use the command:

bitbake m33fw-stm32mp2

If you need to build them individually, use the following commands:

bitbake tf-m-stm32mp 
bitbake m33tdprojects-starter-stm32mp2 
bitbake m33fw-stm32mp2