Build, Load & Debug: STM32 (S/NS)

Build, load, and debug programs with S/NS segregation on STM32

Overview

This document describes how to build, load, and run RTK-based programs with S/NS segregation for the Cortex-M33 STM32 series of MCUs for debugging.

• Tested with STM32U585 and STM32H573.

• The native binary file format is ELF, both with or without debugging.

• S/NS programs comprise two ELF files, one for the Secure program and the NSC veneers, one for the Non-secure program.

• make-elf creates the ELF files. It creates and embeds the necessary DWARF debug data. Note that the executable binaries are 100% the same with or without debug data, and consequently there is no "debug overhead" with debug data included if run outside a debugger.

• The suite of tools used is Astrobe for RP2350 – despite its name, at its core it is a compiler and linker for processors based on Cortex-M33, which work well for the STM32U585 and STM32H573. Specific .ini config files are needed with the correct address ranges, and the framework provides the STM32-specific modules.

• Other guides:

  • Secure/Non-secure without debugging: Build & Load: STM32 (S/NS)
  • Non-S/NS, without debugging: Build & Load: STM32
  • Non-S/NS, with debugging: Build, Load & Debug: STM32

See also Practical Notes.

Set-up

Prerequisites

The build and debug tools must be set up as explained in:

• Set-up: Build Scripts on STM32
• Set-up: Debugging on STM32

STM32 Configuration

The following MCU configuration is assumed:

• TrustZone is enabled

• the 2MB flash memory has been configured, via option bytes

  • block 1 of 1 MB is Secure (address alias: 0C000000H)
  • block 2 of 1 MB is Non-secure (address alias: 08100000H)

Project

• Directories:

  • S program in <project-dir>/sec
  • NS program in <project-dir>/nonsec

• Commands as shown are run with cwd = <project-dir>.

• Two Astrobe configuration files are required, one for the Secure and one for the Non-secure program. An easy way to provide the configuration files is to place them directly in the project directories sec and nonsec, where they can be picked up by the build scripts.

• Refer to Compile and Link: STM32 for the address ranges as used by the example programs.

Steps

1. Build the ELF Files

Building the two debug ELF files for the Secure and the Non-secure program is a multi-step process, which is best implemented and executed using a build script.

The S/NS example programs provide build-db-elf.cmd, which builds both the Secure and Non-secure debug ELF binaries, called S-program.elf and NS-program.elf below. This script can serve as basis for your own projects and programs.

To continue, the build must complete without errors or alerts; warnings are OK.

2. Load the ELF Files

The ELF files are loaded by the debugger:

• GUI: Cortex-Debug inside Visual Studio Code – see Debugging § VS Code + Cortex-Debug
• command line: OpenOCD and GDB – see Debugging § GDB Command Line

Inside the Build Script

The build script executes the following steps. Upon error, the script terminates.

The two build-clean steps are required because the Secure and Non-secure sides use different alias address spaces for flash and SRAM. Compiled modules embed those addresses, so every imported module has to be re-built for the side currently being linked; otherwise AstrobeLink reports "wrong version" errors.

1. Run build-clean to clear any framework objects left from a previous Non-secure build of the same project.

2. Compile the Secure program, running AstrobeBuild, which recursively compiles all modules as needed.

3. Run sec-epilogue to add the Secure epilogues to all procedures that are exposed to the Non-secure world.

4. Re-compile the Secure program to ensure that it contains the Secure epilogues.

5. Link the Secure program, running AstrobeLink.

6. Run gen-secure to create the Non-secure Callable (NSC) binary, containing one gateway veneer block per procedure exposed to the Non-secure world, plus the interface modules for the Non-secure code to call into the Secure world via the gateways.

7. Run gen-rdb to create an .alst file for each module in the Secure program, plus _startup.alst for the start-up sequence inserted by the linker at the end of the program; make-elf requires the .alst files to create symbols and DWARF debug data.

8. Run make-elf to create the Secure debug ELF binary in sec, with the NSC binary embedded, DWARF debug data, and symbol prefix S.

9. Run build-clean to remove the just-built Secure-side framework objects, so the Non-secure compile gets fresh artefacts.

10. Compile the Non-secure program, running AstrobeBuild.

11. Link the Non-secure program, running AstrobeLink.

12. Run gen-rdb to create the .alst files for the Non-secure program.

13. Run make-elf to create the Non-secure debug ELF binary in nonsec, with DWARF debug data and symbol prefix NS.

Last updated: 16 May 2026