Modify, rebuild and reload the STM32CubeMP2 firmware for M33-TD

Applicable for

STM32MP21x lines, STM32MP23x lines, STM32MP25x lines

Trusted domain applicability

This article is only applicable to M33-TD flavor of STM32MP2 series

Important

In this article, the STM32MP215F-DK Discovery kit is taken as example. Nevertheless, it is also applicable for STM32MP257F-DK Discovery kit for STM32MP23x lines evaluation , STM32MP257F-DK Discovery kit and STM32MP257F-EV1 Evaluation board Rev D.

This article gives some guidelines to support secure project on Arm^®-Cortex^®-M33 for M33-TD flavor focuses on building secure firmware (Trusted Firmware-M) alongside nonsecure firmware, and provides guidance on how to debug both. It can be used on both Windows and Linux workstations. However, the screenshots in this article were taken on a Linux workstation.

The secure project relies on the StarterApp_M33TD project delivered in STM32CubeMP2 Package. This project offers a secure build configuration using Trusted Firmware-M (TF-M).

1. Prerequisites[edit | edit source]

1.1. Hardware prerequisites[edit | edit source]

The ST-Link V3 cable must be connected to the PC USB port to display traces.
2 consoles on your workstation are needed : one for Arm^®-Cortex^®-M33 and one for Arm^®-Cortex^®-A35.

For STM32MP215F-DK Discovery kit , 2 "USB to TTL serial cables" are needed, see STM32MP215x-DKx_-_hardware_description#Connecting USB to TTL serial cables.

1.2. Software prerequisites[edit | edit source]

Install build environment and python dependencies for TF-M as described in How_to_configure,_build_and_deploy_TF-M#Prerequisites chapter.

Warning

Be careful to clone from the STMicroelectronics Github.

Install sources of trusted-firmware-m as described in How_to_configure,_build_and_deploy_TF-M#Downloading_source chapter.

Trusted-firmware-m should be installed in STM32CubeMP2 Package, Middlewares/Third_Party/trusted-firmware-m.

Warning

Git clone under <STM32CubeMP2 Repository package>/Middlewares/Third_Party. The "trusted-firmware-m" directory will be created with the git clone already.

Go where you installed trusted-firmware-m

cd <working directory path>/STM32Cube_FW_MP2_V1.X.0/Middlewares/Third_Party/trusted-firmware-m

Install, on the workstation, python libraries, needed for TF-M signature python script.

pip install -r tools/requirements.txt

Warning

The process running STM32CubeIDE must define HTTP and HTTPS proxies for the CMake command to successfully access the network. Network access is required to download TF-M sources and dependencies during CMake configure. For help to set up proxy please read How_to_set_up_proxy_and_P2P_Ethernet_connection_with_STM32CubeIDE

On Linux^® workstation, it is recommended to launch STM32CubeIDE in command line from your terminal with configured proxy environment.

Warning

On Windows, you may need to rename the file "python.exe" as "python3.exe" to complete the build.

Warning

On Ubuntu 22.04, when compiling MCUboot BL2 after installing all required build tools and dependencies, you may encounter errors due to missing Python modules required by the scripts boot_record.py (requires cbor2) and image.py (requires intelhex) located in Third_Party/trusted-firmware-m/config_default/lib/ext/mcuboot-src/scripts/imgtool/. To resolve these issues, install the necessary packages by running: sudo pip install cbor2 intelhex imgtool in your terminal.

1.3. Import StarterApp_M33TD project into STM32CubeIDE[edit | edit source]

StarterApp_M33TD project is imported into STM32CubeIDE from STM32CubeMP2 Package using the menu File > Import....
Then, expand General, choose Existing Projects into Workspace.

StarterApp_M33TD imported project

A new window appears in Select root directory: click on Browse... and select in the STM32CubeMP2 firmware .../STM32Cube_FW_MP2_V1.X.0/Projects/STM32MP215F-DK/Demonstrations/StarterApp_M33TD/STM32CubeIDE.

Note that StarterApp_M33TD project is available from STM32CubeMPU package repository on local disk or from Projects/STM32MP215F-DK/Demonstrations/StarterApp_M33TD .

StarterApp_M33TD imported project

Resulting project structure contains two projects:

StarterApp_M33TD_CM33_NonSecure, HAL-based project, addressing nonsecure part of application.
StarterApp_M33TD_CM33_trusted-firmware-m, pre-set CMake STM32CubeIDE project for TF-M, with link to sources: trusted-firmware-M pointing inside STM32CubeMP2 Package Middlewares/Third_Party/trusted-firmware-m

StarterApp_M33TD imported project

1.4. Set up and configure the StarterApp_M33TD_CM33_trusted-firmware-m project[edit | edit source]

1.4.1. Configure trusted-firmware-m link[edit | edit source]

Information

This section is normally not needed if you followed the #Software_prerequisites and installed the trusted-firmware-m sources in
Middlewares/Third_Party/trusted-firmware-m. You should only follow it if your trusted-firmware-m is empty:

trusted-firmware-m imported empty link

To use the Trusted Firmware-M (TF-M) source files in your project, you need to specify the path to the TF-M repository.

As shown in the screenshot below, enter the correct path to the TF-M source folder in the STM32CubeIDE project settings to properly link the repository with your CMake-based project configuration.

Right click in trusted-firmware-m -> Properties -> Resources -> Edit and provide the path to trusted-firmware-m directory .

trusted-firmware-m link to source files

To get source code, follow the instructions in How_to_configure,_build_and_deploy_TF-M#Installing_sources. You can then refresh STM32CubeIDE project and view sources.

StarterApp_M33TD imported project

1.4.2. CMake configuration[edit | edit source]

In order to check CMake command

right click on StarterApp_M33TD_CM33_trusted-firmware-m->Properties-> C/C++ build, click on CMake Settings tab, then in Other Options put your "CMake command" Apply > Apply and close

The trusted-firmware-M project is imported with pre-configured settings, but some of them can be customized.

Below an example of STM32MP215F-DK board - CMake project usage settings:

-DTFM_PLATFORM=stm/stm32mp215f_dk 
-DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake 
-DSTM32_BOOT_DEV=sdmmc1 # This option can be modified if you are not using the SD-CARD as boot memory.
-DTFM_PROFILE=profile_medium 
-DSTM32_M33TDCID=ON 
-DCMAKE_BUILD_TYPE=Relwithdebinfo 
-DNS=OFF 
-DDTS_EXT_DIR=../../../../../../../../Utilities/dt-stm32mp
-DDTS_BOARD_BL2=stm32mp2/m33-td/mcuboot/stm32mp215f-dk-cm33tdcid-ostl-sdcard-bl2.dts
-DDTS_BOARD_S=stm32mp2/m33-td/tfm/stm32mp215f-dk-cm33tdcid-ostl-sdcard-s.dts
-DDTS_BOARD_NS=stm32mp2/m33-td/tfm/stm32mp215f-dk-cm33tdcid-ostl-ns.dts
-DDEBUG_AUTHENTICATION=FULL  # Enabled for Debug Purpose, Default: this option is removed.

Warning

You must manually update DTS_EXT_DIR because the one delivered in STM32Cube_FW_MP2_V1.3.x is not correct. The path value should be ../../../../../../../../Utilities/dt-stm32mp.

Information

STM32_BOOT_DEV options

Depending of the MP2 board, for instance for the STM32MP257F-EV1:

     - default, serial nor (ospi): ``-DSTM32_BOOT_DEV=ospi``
     - sdcard (sdmmc1): ``-DSTM32_BOOT_DEV=sdmmc1``
     - emmc (sdmmc2): ``-DSTM32_BOOT_DEV=sdmmc2``

2. Build updated project[edit | edit source]

2.1. Build the StarterApp_M33TD_CM33_trusted-firmware-m project[edit | edit source]

StarterApp_M33TD_CM33_trusted-firmware-m project generates bl2.stm32 , ddr_phy_signed.bin , tfm_s.bin , tfm_s.elf and bl2.elf.
StarterApp_M33TD_CM33_NonSecure project generates StarterApp_M33TD_CM33_NonSecure.bin. The postbuild step then assembles the final signed image tfm_s_ns_signed.bin and copies all flashing-ready artifacts into the project-local bin folder.

So when bl2 or tfm-s are rebuilt, you need to rebuild StarterApp_M33TD_CM33_NonSecure project in order to link and sign secure tfm_s.bin and StarterApp_M33TD_CM33_NonSecure.bin thanks to "postbuild" command, explained below in the article.

You can configure your project doing right click to your StarterApp_M33TD_CM33_trusted-firmware-m > CMake configure.

Information

If you already made the CMake configuration in the past, you can override it by selecting Delete and Reconfigure.

Then run the build of StarterApp_M33TD_CM33_trusted-firmware-m by cliking on the hammer build icon from eclipse.

The generated ELF files tfm_s.elf and bl2.elf, are needed to debug. They can be found in:

StarterApp_M33TD_CM33_trusted-firmware-m/trusted-firmware-m/config_default/api_ns/bin/ tfm_s.elf
StarterApp_M33TD_CM33_trusted-firmware-m/trusted-firmware-m/config_default/api_ns/bin/ bl2.elf

2.2. Build the StarterApp_M33TD_CM33_NonSecure project[edit | edit source]

2.2.1. Activate generation of .bin[edit | edit source]

To generate the raw nonsecure binary StarterApp_M33TD_CM33_NonSecure.bin used by the postbuild step, you need to activate the generation of the .bin from

right click StarterApp_M33TD_CM33_NonSecure > Properties > C/C++ Build > Settings > MCU/MPU Post build outputs > select covert to binary file(-O binary ):

2.2.2. Select Build Config[edit | edit source]

Before starting build of the StarterApp_M33TD_CM33_NonSecure project, we need to select the config best applicable for our usecase.

There are 3 configurations available for user:

DYNAMIC_SPLASH_StarterApp_build_ns: display path enabled, with animated splash screen while boot continues. It corresponds to a BUILD_CONFIG=FULL profile with dynamic splash enabled.

MINIMUM_StarterApp_build_ns: display path disabled. Linux initializes the display later on Cortex-A35. It corresponds to a BUILD_CONFIG=MINIMUM profile.

STATIC_SPLASH_StarterApp_build_ns: display path enabled, with static splash screen while boot continues. It corresponds to a BUILD_CONFIG=FULL profile with static splash enabled.

Information

In ecosystem release v6.2.0 , the default StarterApp_M33TD profile did not support the firmware update manager task and the low-power manager task. The task profile described below applies to ecosystem release v6.2.1 .

In the current StarterApp_M33TD profile, the NS Application Manager baseline keeps the core system tasks enabled and also enables the OpenAMP, button monitor, low-power manager and firmware update manager paths by default. The selected STM32CubeIDE build configuration mainly controls whether the display path is included.

Current StarterApp_M33TD projects also expose other build options through CMake, including REMOTE_PROC_AUTO_START and LOW_POWER_DEFAULT_POLICY_ENABLE. These options also change the generated application behavior.

Select StarterApp_M33TD_CM33_NonSecure project. This project has only one build configuration: CM33TDCID_m33_ns_tfm_s_sign.
Build can be done using standard eclipse Build icon. It generates StarterApp_M33TD_CM33_NonSecure_tfm_s_ns_signed.bin, visible after a project refresh.

2.2.3. Postbuild[edit | edit source]

The StarterApp_M33TD_CM33_NonSecure project uses the postbuild utility to assemble and sign secure tfm_s.bin with non secure StarterApp_M33TD_CM33_NonSecure.bin. The resulting signed image is tfm_s_ns_signed.bin. The same postbuild step also copies the flashing-ready artifacts to the project-local bin folder. The configured command is visible in C/C++ Build > Settings > Build Steps:

A cmake command is invoked:

cmake -G "Unix Makefiles" -S ../../../../../../../../Utilities/M33TD_NSAppCore/postbuild -B M33TD_NSAppCore_postbuild -DPROJECT_NAME=${BuildArtifactFileBaseName} -DTFM_BUILD_DIR="${workspace_loc:/StarterApp_M33TD_CM33_trusted-firmware-m/trusted-firmware-m/config_default}" -DBASE_DIR=../../../../ && cmake --build M33TD_NSAppCore_postbuild --target M33TD_NSAppCore_postbuild

2.3. Using STM32CubeProgrammer to flash the new binaries[edit | edit source]

2.3.1. Copy the Firmware Images generated in previous step to the correct locations[edit | edit source]

STM32CubeProgrammer GUI can read a tsv file and flash the binaries mentioned in correct partitions on the external memories (sdcard, eMMC, sNOR etc)
OSTL starter package comes with pre-compiled binaries for M33-TD flavor .
To be able to flash the external memory with our newly compiled binaries we need to replace them.
copy our newly compiled images to the correct directory as shown in the tsv file below.
- bl2.stm32 :: By default generated in STM32Cube_FW_MP2_V1.X.0/Middlewares/Third_Party/trusted-firmware-m/config_default/api_ns/bin/,
- ddr_phy_signed.bin :: By default generated in STM32Cube_FW_MP2_V1.X.0/Middlewares/Third_Party/trusted-firmware-m/config_default/api_ns/bin/
- StarterApp_M33TD_CM33_NonSecure_tfm_s_ns_signed.bin :: By default generated in STM32Cube_FW_MP2_V1.X.0/Projects/STM32MP215F-DK/Demonstrations/StarterApp_M33TD/STM32CubeIDE/CM33/NonSecure/DYNAMIC_SPLASH_StarterApp_build_ns/

TSV file update for ecosystem release v6.2.0 and ecosystem release v6.2.1

Copy the new binaries generated with STM32CubeIDE to the locations (folders) specified in the tsv file:
- Replace fsblm1 and fsblm2 binary present at arm-trusted-firmware-m/bl2/bl2-stm32mp215f-dk-cm33tdcid-ostl-sdcard.stm32 with the newly generated bl2.stm32
- Replace m33ddr-a binary present at m33-firmware/ddr_phy-stm32mp215f-dk-cm33tdcid-ostl-sdcard_Signed.bin with the newly generated ddr_phy_signed.bin
- Replace m33fw-a binary present at m33-firmware/tfm-starterapp-stm32mp215f-dk-cm33tdcid-ostl-sdcard-sdcard_s_ns_Signed.bin with the newly generated StarterApp_M33TD_CM33_NonSecure_tfm_s_ns_signed.bin

Update .tsv file with generated binaries

2.3.2. Flashing with STM32CubeProgrammer GUI Application[edit | edit source]

Run STM32CubeProgrammer GUI Application

Updating target with stm32cubeprog application ...

Fill Binaries Directory with the path to binaries inside OpenSTLinux images: <working directory path>/Starter-Package/stm32mp2-m33td-openstlinux-6.6-yocto-scarthgap-mpu-vxx.xx.xx/images/stm32mp2-m33td/.
Fill TSV File with the updated .tsv file.
Connect to the target through USB
Click on Download button.

3. How to debug[edit | edit source]

3.1. Prerequisites to debug[edit | edit source]

Once the download is completed, you must configure again the Boot Pin for M33-TD flavor boot. You must refer to STM32MP215x-DKx_-_hardware_description#Boot_switches / STM32MP257x-DKx_-_hardware_description#Boot_switches / STM32MP257x-EV1_-_hardware_description#Boot-related_switches

3.2. Debug bl2[edit | edit source]

Open a console in STM32CubeIDE and reboot the board, you should see logs like this:

BL2 waiting for debugger in Arm^®-Cortex^®-M33 Console

By default the code should be stuck in the bl2.

Select StarterApp_M33TD_CM33_trusted-firmware-m project and right click to get Debug As > Debug configurations....

Double click STM32 C/C++ Application and create debug configuration:

In main tabulation, Search Project and select bl2.elf.
In Debugger tabulation:
- Load Mode and select thru JTAG/SWD link (Engineering mode).
In Startup tabulation:
- Remove all the Initialization Commands
- Disable in Runtime Options the Resume checkbox.
- Select the Load Image and Symbols element click Edit and disable Download.

And click on Apply.

Launching debug session

Warning

Click on "Expand", visible on the right side of the page, to view Warnings related to STM32MP21.

Configuration file error

If you run the debug on STM32MP21, you will encounter an error. This is due to an error in the generated cfg file.

In the project explorer, in the root of the project, click on StarterApp_M33TD_CM33_trusted-firmware-m config_default.cfg, copy it and paste it to duplicate it. You can call it StarterApp_M33TD_CM33_trusted-firmware-m config_default_user.cfg. Then open the new file and replace the last line with:

source [find target/stm32mp21x.cfg]

For STM32MP25x or STM32MP23x, replace the above by source [find target/stm32mp25x.cfg] or source [find target/stm32mp23x.cfg]

Then we need to modify again the debug configuration. Select StarterApp_M33TD_CM33_trusted-firmware-m project and right click to get Debug As > Debug configurations.... Click on the configuration created previously, by default it should be StarterApp_M33TD_CM33_trusted-firmware-m config_default

In Debugger tabulation:
- In configuration Script area, select User Defined and point to your updated cfg file.

Click on Debug and you should see that you are in /StarterApp_M33TD_CM33_trusted-firmware-m/trusted-firmware-m/platform/ext/target/stm/common/stm32mp2xx/bl2/boot_hal.c.

You can just use the step into button to continue your debug in the BL2.

BL2 could be step-by-step debugged until the code jumps to TF-M code. To debug the TF-M code, follow the procedure below.

3.3. Debug TF-M secure[edit | edit source]

Information

A way to control entry point of the TF-M debug session could be to add a debug loop. For instance in the tfm_hal_platform.c located in: <STM32CubeMP2-1.x.x>/Middlewares/Third_Party/trusted-firmware-m/platform/ext/target/stm/common/stm32mp2xx/secure/tfm_hal_platform.c

enum tfm_hal_status_t tfm_hal_platform_init(void)
{
   // Debug loop entry
   volatile int i=1;
   while(i);

The debug session starts inside this debug loop. In variable tab, you can modify the value of “i” to 0 to unlock the loop and then it become possible to step into TF-M initialization code.

When debugging TF-M Secure and nonsecure firmware, please note that both run with cache enabled (D-Cache and I-Cache) by default. Because of this, standard breakpoints and variable modifications may not work as expected during debugging.

To avoid these limitations and to make easier the debug, you can disable the cache for debug purpose.

3.3.1. Disabling Cache[edit | edit source]

You need to modify your CMake settings and add at the beginning:

-DSTM32_CACHE_ENABLED=OFF

The explanation to reach the CMake settings is available here: CMake_configuration

Then run the CMake Configure and the build of the trusted-firmware-m Build_the_StarterApp_M33TD_CM33_trusted-firmware-m_project

Build the NonSecure project Build_the_StarterApp_M33TD_CM33_NonSecure_project

Flash the new binaries Populate_board_with_the_created_project

3.3.2. Create the TF-M debug configuration[edit | edit source]

Select StarterApp_M33TD_CM33_trusted-firmware-m project and right click to get Debug As > Debug configurations. Double click STM32 C/C++ Application and edit debug configuration:

Rename it with _tfm at the end of the name
InMain tabulation:
- Search Project and select tfm_s.elf.
- Choose the Build Configuration: config_default

Information

the same tfm_s.elf can be found both in:
- StarterAppM33TD_CM33_trusted-firmware-m/trusted-firmware-m/config_default/api_ns/bin/
- StarterAppM33TD_CM33_trusted-firmware-m/trusted-firmware-m/config_default/bin/

InDebugger tabulation:
- Load Mode and select thru JTAG/SWD link (Engineering mode).
In Startup tabulation:
- Disable Resume.
- Remove monitor halt & monitor reset
- Select the Load Image and Symbols element click Edit and disable Download.

Warning

Click on "Expand", visible on the right side of the page, to view Without Disabling Cache.

Without disabling the cache, you will be limited and will have to use hardware breakpoints (limited to 8). To allow the Hardware breakpoint, it will be necessary to modify two fields in the debug configuration.

InDebugger tabulation:
- In Openocd Options, add -bc "gdb_breakpoint_override hard"
In Startup tabulation:
- In Initialization Commands , add monitor gdb_breakpoint_override hard

Warning

Click on "Expand", visible on the right side of the page, to view Warnings related to STM32MP21.

Configuration file error

If you run the debug on STM32MP21, you will encounter an error. This is due to an error in the generated cfg file.

Select StarterApp_M33TD_CM33_trusted-firmware-m project and right click to get Debug As > Debug configurations....

Click on the configuration that you created.
In Debugger tabulation:
- In configuration Script area, select User Defined and point to your updated cfg file created during the chapter Debug_bl2

Apply and Debug.

Information

Each time you want to debug the TF-M, you should first debug the BL2 to pass the __WFI(); in the code.

This Waiting for Interrupt is there to help to debug the BL2, but it can be commented for being able to load the TF-M directly. Go inside /StarterApp_M33TD_CM33_trusted-firmware-m/trusted-firmware-m/platform/ext/target/stm/common/stm32mp2xx/bl2/boot_hal.c In int stm32mp2_init_debug(void), replace

	__WFI();

with

// 	__WFI();

Rebuild everything
Flash the new binaries.

Information

There is also the possibility to cascade the debug configuration without modifying the source code. Proceed with the BL2 debug, then click on the run button, then terminate the debugger and Open the TF-M debug to reach the TF-M secured entry point.

3.4. Debug StarterApp_M33TD_CM33_NonSecure[edit | edit source]

Information

Example of a way to control entry point of the CM33 Non Secure debug session. Comment the waiting point (while) that we added in Debug_TF-M_secure and instead edit StarterApp_M33TD_CM33_NonSecure/Application/User/Core/Src/main.c:

In the function main, replace:

#ifdef DEBUG

with

#ifndef DEBUG

Build the updated project Build_updated_project

Flash the new binaries Populate_board_with_the_created_project

The debug session starts inside this debug loop. In variable tab, you can modify the value of “debug” to 0 to unlock the loop and then it become possible to step into TF-M initialization code.

SelectStarterApp_M33TD_CM33_NonSecure project and right click to get Debug As > Debug configurations. Double click STM32 C/C++ Application and edit debug configuration:

In main tabulation, Search Project and select StarterApp_M33TD_CM33_NonSecure.elf.
In Debugger tabulation, Load Mode and select thru JTAG/SWD link (Engineering mode).
- In configuration Script select User Defined and point to your updated cfg
In Startup tabulation:
- Disable Resume.
- Remove monitor halt & monitor reset
- Select the Load Image and Symbols element click Edit and disable Download.

Warning

Click on "Expand", visible on the right side of the page, to view Without Disabling Cache.

If you kept the cache when following Disabling_Cache, you will be limited and will have to use hardware breakpoints (limited to 8).
To allow the Hardware breakpoint, it will be necessary to modify two fields in the debug configuration.

InDebugger tabulation:
- In Openocd Options, add -bc "gdb_breakpoint_override hard"
In Startup tabulation:
- In Initialization Commands , add monitor gdb_breakpoint_override hard

Warning

Click on "Expand", visible on the right side of the page, to view Warnings related to STM32MP21.

Configuration file error

If you run the debug on STM32MP21, you will encounter an error. This is due to an error in the generated cfg file.

Select StarterApp_M33TD_CM33_trusted-firmware-m project and right click to get Debug As > Debug configurations....

Click on the configuration that you created.
In Debugger tabulation:
- In configuration Script area, select User Defined and point to your updated cfg file created during the chapter Debug_bl2

Apply and Debug.

Information

Compiler Optimization settings

If you encounter an issue when starting a debug session, always confirm that the compiler optimization is set to Debug.

In Properties -> C/C++ Build -> Settings -> MCU GCC Compiler -> Debugging -> Debug level should be set at Maximum (-g3)