Summary
This article provides a detailed guide on using VS Code to debug code running from external serial flash on the STM32N6. It covers setting up the development environment, setting up the project with CMake, configuring the debugger within VS Code, and validating the setup.
- Summary
- Introduction
- 1. Prerequisites
- 2. Hardware setup
- 3. Create an STM32N6 CMake project
- 4. Code editing and post build commands
- 4.1 Edit the FSBL post build
- 4.2 Edit the Appli post build
- 4.3 Linker script for execute in place (XIP)
- 5. Build the project
- 6. Create and modify the launch.json file
- 6.1 Explanation of the launch.json file changes
- 7. Start debugging
- Conclusion
- Related links
Introduction
To debug code running from external serial flash effectively, the external memory must be configured in memory-mapped mode. The first stage bootloader (FSBL), running from AXI-SRAM2, initializes the XSPI interface, enables memory-mapped mode, and jumps to the application stored in external flash. Debugging starts with placing the debugger program on this external memory, allowing seamless execution and inspection directly from flash.
A key limitation to be aware of is that breakpoints cannot be set in application code located in external memory before the FSBL configures the memory mapping. Once the FSBL completes this setup and the debugger enters debug mode, breakpoints function normally. This guide covers environment setup, debugger configuration, project setup with CMake, and tips to work around these constraints for an efficient debugging workflow in VS Code.
1. Prerequisites
This article requires that you have the following installed:
- Visual Studio Code
- STM32CubeExtension
- STM32CubeProgrammer
- STM32CubeCLT
- STM32CubeMX
- The latest version of the STM32N6 HAL driver
2. Hardware setup
The hardware used to showcase is the STM32N6570-DK. Make sure that you have it in DEV boot mode to program the code.
3. Create an STM32N6 CMake project
- Create a new STM32CubeMX project, open VS Code, and click on [Launch STM32CubeMX]:
- Select the [STM32N657X0H3Q]:
- Select [Secure domain only]:
Configure the project to execute code from the external serial NOR flash. If you need assistance with this setup, we have published an article that explains the process in detail. You can find it here: How to execute code from the external serial NOR using the STM32N6.
- Before the code generation, select the CMake toolchain:
- In VS Code, import the project folder:
- Configure the preset [Debug] by pressing Ctrl+Shift+P and type/select [Select Configure Preset] then click on [Debug]:
- Configure CMake discovered Project as STM32Cube Project:
- Add [PROJECT_NAME_Appli] and [PROJECT_NAME_FSBL] to your environment, save and close:
4. Code editing and post build commands
In the [Appli] project, locate the main.c file and add the toggle LED function call in its main loop:
/* Infinite loop */
/* USER CODE BEGIN WHILE */
while (1)
{
/* USER CODE END WHILE */
HAL_GPIO_TogglePin(GREEN_LED_GPIO_Port, GREEN_LED_Pin);
HAL_Delay(200);
/* USER CODE BEGIN 3 */
}
/* USER CODE END 3 */
}As described here, it is possible to add postbuild steps to generate the *.bin files and sign the binaries for both projects. However, in VS Code the launch.json configuration used for debugging embedded applications only supports *.elf files. To address this limitation, a custom postbuild command is included in the build process:
# Convert the signed Appli .bin back to .elf
add_custom_command(
TARGET ${CMAKE_PROJECT_NAME}
POST_BUILD
COMMAND ${CMAKE_OBJCOPY} -I binary -O elf32-littlearm -B arm --change-addresses=0x70100000 ${APPLI_OUTPUT} ${CMAKE_BINARY_DIR}/Appli-trusted.elf
COMMENT "Converting signed .bin back to .elf in address [0x70100000]"
)This custom command converts the signed *.bin output back into an *.elf file, mapping it to the correct memory addresses (in this case 0x70100000 for [Appli]). This ensures that the resulting .elf file contains the necessary information for proper debugger functionality.
In short, these postbuild commands can be added to the CMakeLists.txt files of [FSBL] and [Appli] projects:
4.1 Edit the FSBL post build
Starting from STM32CubeProgrammer version 2.21.0 a new parameter is needed "-align". Please make sure you use the updated command, as follows:
# Specify the output ELF file
set(TARGET_ELF "${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.elf")
# Command to generate .bin file
add_custom_command(
TARGET ${CMAKE_PROJECT_NAME}
POST_BUILD
COMMAND ${CMAKE_OBJCOPY}
-O binary ${TARGET_ELF} ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.bin
COMMENT "Generating .bin file"
)
# Define the paths to the STM32 Signing Tool and the input/output files
set(SIGNING_TOOL "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/STM32_SigningTool_CLI.exe")
# Define the input and output files for FSBL
set(FSBL_INPUT "${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.bin")
set(FSBL_OUTPUT "${CMAKE_BINARY_DIR}/FSBL-trusted.bin")
# Add a post-build step to sign the FSBL binary
add_custom_command(
TARGET ${CMAKE_PROJECT_NAME}
POST_BUILD
COMMAND ${CMAKE_COMMAND} -E echo y > input.txt
COMMAND "${SIGNING_TOOL}" -bin "${FSBL_INPUT}" -nk -of 0x80000000 -t fsbl -o "${FSBL_OUTPUT}" -hv 2.3 -align -dump "${FSBL_OUTPUT}" < input.txt
WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
COMMENT "Signing FSBL binary: ${FSBL_INPUT} -> ${FSBL_OUTPUT}"
)
# Convert the signed FSBL .bin back to .elf
add_custom_command(
TARGET ${CMAKE_PROJECT_NAME}
POST_BUILD
COMMAND ${CMAKE_OBJCOPY} -I binary -O elf32-littlearm -B arm --change-addresses=0x70000000 ${FSBL_OUTPUT} ${CMAKE_BINARY_DIR}/FSBL-trusted.elf
COMMENT "Converting signed FSBL .bin back to .elf in address [0x70000000]"
)4.2 Edit the Appli post build
Starting from STM32CubeProgrammer version 2.21.0 a new parameter is needed "-align". Please make sure you use the updated command, as follows:
# Specify the output ELF file
set(TARGET_ELF "${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.elf")
# Command to generate .bin file
add_custom_command(
TARGET ${CMAKE_PROJECT_NAME}
POST_BUILD
COMMAND ${CMAKE_OBJCOPY} -O binary ${TARGET_ELF} ${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.bin
COMMENT "Generating .bin file"
)
# Define the paths to the STM32 Signing Tool and the input/output files
set(SIGNING_TOOL "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/STM32_SigningTool_CLI.exe")
# Define the input and output files for Appli
set(APPLI_INPUT "${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.bin")
set(APPLI_OUTPUT "${CMAKE_BINARY_DIR}/Appli-trusted.bin")
# Add a post-build step to sign the Appli binary
add_custom_command(
TARGET ${CMAKE_PROJECT_NAME}
POST_BUILD
# Step 1: Create a file with 'y'
COMMAND ${CMAKE_COMMAND} -E echo y > "${CMAKE_BINARY_DIR}/input.txt"
# Step 2: Run the signing tool, redirecting input from the file
COMMAND "${SIGNING_TOOL}" -bin "${APPLI_INPUT}" -nk -of 0x80000000 -t fsbl -o "${APPLI_OUTPUT}" -hv 2.3 -align -dump "${APPLI_OUTPUT}" < "${CMAKE_BINARY_DIR}/input.txt"
WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
COMMENT "Signing Appli binary: ${APPLI_INPUT} -> ${APPLI_OUTPUT}"
)
# Convert the signed Appli .bin back to .elf
add_custom_command(
TARGET ${CMAKE_PROJECT_NAME}
POST_BUILD
COMMAND ${CMAKE_OBJCOPY} -I binary -O elf32-littlearm -B arm --change-addresses=0x70100000 ${APPLI_OUTPUT} ${CMAKE_BINARY_DIR}/Appli-trusted.elf
COMMENT "Converting signed .bin back to .elf in address [0x70100000]"
)4.3 Linker script for execute in place (XIP)
The default linker script generated by the CMake for the [Appli] project is configured for the selected operation configured in the STM32CubeMX’s EXTMEM_MANAGER, where the selected was XIP. Double check that the linker script used in [Appli] CMakeLists.txt is indeed the correct one:
Note: STM32CubeMX version 6.15 has a minor bug on the linker script creation for CMake that causes a build error on VS Code. I recommend changing the content of said linker script with the equivalent one available in our GitHub here or use the attached on in this article (available at the end of the article.)
5. Build the project
Now that all steps are configured, it is time to build the application, locate the [CMake] icon on the left, then expand the [PROJECT STATUS] to locate the [Build] [All] to rebuild the projects. Alternatively, press Ctrl+Shift+P and then type/click [CMake: Clean Rebuild] for a clean and rebuild action.
6. Create and modify the launch.json file
- Open the [Run and Debug] view (Ctrl+Shift+D.)
- Click create a launch.json file.
- Select STM32Cube: STLink GDB Server from the list of debuggers provided by STM32CubeExtension.
- The extension generates a default launch.json with configurations tailored for STLINK debugging.
Edit the generated launch.json to support debugging with all features enabled:
{
"version": "0.2.0",
"configurations": [
{
"type": "stlinkgdbtarget",
"request": "launch",
"name": "STM326570-DK Debug",
"origin": "snippet",
"cwd": "${workspaceFolder}",
"preBuild": "${command:st-stm32-ide-debug-launch.build}",
"runEntry": "BOOT_Application", // Set in BOOT_Application
"svdPath": "C:/ST/STM32CubeCLT_1.18.0/STMicroelectronics_CMSIS_SVD/STM32N657.svd", // Replace with your .svd path
"imagesAndSymbols": [
{
"symbolFileName": "${workspaceFolder}/Appli/build/XIP_Appli.elf", // Replace this with your path and your_Appli.elf symbol
"imageFileName": "${workspaceFolder}/Appli/build/Appli-trusted.elf",
},
{
"symbolFileName": "${workspaceFolder}/FSBL/build/XIP_FSBL.elf", // Replace this with your path and your_FSBL.elf symbol
"imageFileName": "${workspaceFolder}/FSBL/build/XIP_FSBL.elf", // Replace this with your path and your_FSBL.elf image
}
],
"serverExtLoader": [
{
"loader": "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/ExternalLoader/MX66UW1G45G_STM32N6570-DK.stldr", // Replace with your external loader path
"initialize": false
}
]
}
]
}6.1 Explanation of the launch.json file changes
- Changed the debug configuration name:
The "name" field was updated from a generic label to "STM326570-DK Debug" to identify the target board clearly and make the configuration easier to recognize in the VS Code interface.
- Changed the runEntry function:
As placing breakpoints in code positioned in the external memory region before the memory is configured in memory-mapped mode, a change on the entry point has to be made. Set the first breakpoint in the FSBL's function called “BOOT_Application” instead of the usual "main" as this is the first function after the memory is in memory-mapped mode.
- Added svdPath:
A new "svdPath" field was introduced, pointing to the SVD (system view description) file for the STM32N657 device. This enables the debugger to display peripheral registers and improves the debugging experience by providing detailed hardware information in the UI.
- Explicitly defined imagesAndSymbols:
Instead of using a dynamic command to resolve the binary, the configuration now explicitly lists both "symbolFileName" and "imageFileName" for two separate images (application and FSBL). This allows for multi-image debugging and ensures that the correct symbol and image files are used, which is especially important when dealing with signed binaries.
- Added serverExtLoader:
A "serverExtLoader" section was added, specifying the path to an external loader (*.stldr file). This is required for programming external memory so that the debugger can access and debug code stored outside the MCUs.
7. Start debugging
- Connect your STM32 board to your PC using the STLINK debugger.
- In VS Code, select the debug configuration you created.
- Press F5 or click the green [Start Debugging] button.
- The application should halt at the breakpoint set in the BOOT_Application:
By pausing the code execution, you can confirm that it is running from the external flash by inspecting the function addresses in the call stack. At this stage, all standard debugging features become available, allowing you to:
- Set breakpoints.
- Step through your program.
- Inspect variables, registers, and memory.
- View call stacks.
Note: Remember that keeping existing breakpoints between debug sessions can cause failure messages when entering debug mode. If a failure message appears when attempting to enter debug mode, try power cycling the board.
Conclusion
By following these steps, you can successfully debug code running on the STM32N6 using VS Code. This tutorial provides a practical approach, covering environment setup, debugger configuration, and validation to ensure a smooth and effective debugging experience.
Related links
- Knowledge article: How to debug STM32N6 using STM32CubeIDE
- Knowledge article: How to add post build commands in VS Code
- Knowledge article: How to execute code from the external serial NOR using the STM32N6
- Knowledge article: How to debug an external .elf file in VS Code
- User manual 3249: Getting started with STM32CubeN6 for STM32N6 series
- User manual 3234: How to proceed with boot ROM on STM32N6 MCUs
- User manual 3300: Discovery kit with STM32N657X0 MCU
- Reference manual 0486: STM32N647/657xx Arm®-based 32-bit MCUs
Hi @Mikk Leini
Yes, debugging in Flash Boot Mode (BOOT1=0, BOOT0=0) is possible on the STM32N6, but it requires a specific workflow. You cannot rely on the standard "one-click" F5 launch in VS Code for two main reasons:
-
Flashing Failure: The VS Code debugger (GDB Server) fails to flash the FSBL-trusted.elf file.
-
Debug Failure: In Flash Boot Mode (BOOT1=0), the BootROM can lock or restrict the debug port, so a normal connect‑and‑reset debug session may fail.
To succeed, you must separate the flashing process from the debugging process and manually re-open the debug port in your firmware.
Why it was failing
-
"Failed to erase memory": This error occurs because the ST-LINK GDB Server (used by VS Code's launch.json) fails to correctly parse or flash the signed FSBL-trusted.elf. The GDB Server struggles with the specific headers of the trusted ELF or loses the External Loader context when trying to program it, leading to a failure before the write even begins.
-
"Cannot access memory at 0xe000ed14": This error is a direct side effect of the GDB Server failing to handle the signed FSBL-trusted.elf. When the GDB Server attempts to process the signed binary and fails, it loses synchronization with the debug probe or leaves the session in an undefined state. As a result, subsequent commands fail with a generic "Cannot access memory" error, even though the hardware itself is in an open (DEVBOOT) state.
-
"Debug Authentication": When switching to Flash Boot Mode (BOOT1=0, BOOT0=0), the BootROM enforces debug restrictions. If no debug authentication or explicit unlock is performed, both VS Code and STM32CubeProgrammer can show a Debug Authentication error and fail to connect or reset.
Solution
Step A: Modify FSBL to re-enable Debug
Since Flash Boot mode can restrict debug, your FSBL should explicitly re‑allow debug access at startup.
At the beginning of main() (or very early in FSBL init), you can add this:
/* Unlock BSEC Access Port */
BSEC->AP_UNLOCK = 0xB4;
/* Enable Non-Secure and Secure Debug (Mimics DEVBOOT state) */
BSEC->DBGCR = 0xB451B400;
/* Optional: Blink an LED here to visually confirm FSBL is running */This way, when the BootROM has finished authenticating and jumps into FSBL, your FSBL “reopens” the debug port, making Hotplug attach feasible in Flash Boot mode.
Step B: Flash using a VS Code Task (DEVBOOT only)
Flashing signed images via the ST‑LINK GDB server in VS Code is fragile in this scenario, especially with external flash and trusted ELFs. A more robust approach is to:
-
Put the board in DEVBOOT (BOOT1=1),
-
Use STM32_Programmer_CLI with the external loader and explicit addresses,
-
And run that via a VS Code task.
Example .vscode/tasks.json:
{
"version": "2.0.0",
"tasks": [
// =========================================================================
// This task invokes the STM32CubeProgrammer CLI to program the board.
// REQUIREMENT: Board must be in DEVBOOT mode (BOOT1=1) for this to succeed.
// =========================================================================
{
"label": "Flash STM32N6 (DEVBOOT)",
"type": "process",
"command": "STM32_Programmer_CLI",
// AUTOMATION: Automatically runs the "Clean Rebuild" task first.
// If the rebuild fails, this flash command will not execute.
"dependsOn": [
"CMake: clean rebuild"
],
"args": [
// CONNECTION: Use SWD port and connect 'Under Reset' (UR)
"-c", "port=SWD", "mode=UR",
// EXTERNAL LOADER: Required to program the external Octal-SPI/HyperFlash.
// Ensure this path points to the correct loader for the STM32N6 DK.
"-el", "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/ExternalLoader/MX66UW1G45G_STM32N6570-DK.stldr",
// FLASHING FSBL (First Stage Boot Loader):
// Using flat binary (.bin) format requires explicit start address (0x70000000).
"-d", "${workspaceFolder}/FSBL/build/FSBL-trusted.bin", "0x70000000", "-v", // Verify after write
// FLASHING APPLI (Main Application):
// Using flat binary (.bin) format requires explicit start address (0x70100000).
"-d", "${workspaceFolder}/Appli/build/Appli-trusted.bin", "0x70100000", "-v" // Verify after write
],
"problemMatcher": []
}
]
}
After saving tasks.json, run it via:
-
Ctrl+Shift+P → Tasks: Run Task → Flash STM32N6 (DEVBOOT)
Step C: Debug using Hotplug (Attach-like)
Once the images are flashed and verified:
-
Switch the board to Flash Boot mode (BOOT1=0, BOOT0=0).
-
Power cycle the board so that the BootROM authenticates the FSBL and jumps into it.
-
FSBL runs, executes your debug‑unlock sequence, then continues.
Now you want a launch configuration that only attaches and does not reset the target or try to re‑flash anything.
Example .vscode/launch.json:
{
"version": "0.2.0",
"configurations": [
// ====================================================================
// CONFIGURATION: HOTPLUG / ATTACH MODE
// Use this when the board is in FLASHBOOT (BOOT1=0).
// It connects to the running target without resetting it, allowing you to debug in
//FLASHBOOT mode
// ====================================================================
{
"name": "STM32N6-DK Hotplug/Debug",
"type": "stlinkgdbtarget",
"request": "launch", // logic acts as 'attach' due to serverReset: None
"origin": "snippet",
"deviceName": "STM32N657",
"deviceCore": "Cortex-M55",
// CRITICAL: Tells the debugger NOT to reset the chip upon connection.
// This preserves the state set by the Boot ROM and your FSBL unlock code.
"serverReset": "None",
"cwd": "${workspaceFolder}",
"svdPath": "C:/ST/STM32CubeCLT_1.20.0/STMicroelectronics_CMSIS_SVD/STM32N657.svd",
// SYMBOLS ONLY: notice 'imageFileName' is missing.
// This ensures VS Code knows the variable names/line numbers
// but DOES NOT attempt to flash the code (which would fail in Secure Boot).
"imagesAndSymbols": [
{
"symbolFileName": "${workspaceFolder}/Appli/build/STM32N6_ExecuteInPlace_Appli.elf"
},
{
"symbolFileName": "${workspaceFolder}/FSBL/build/STM32N6_ExecuteInPlace_FSBL.elf"
}
],
// LOADER WORKAROUND: The extension requires this block to be present.
// We set 'initialize: false' to prevent the debugger from trying to
// configure the external flash (which runs safely in the background).
"serverExtLoader": [
{
"loader": "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin/ExternalLoader/MX66UW1G45G_STM32N6570-DK.stldr",
"initialize": false
}
]
}
]
}
With this setup:
-
VS Code will not reprogram anything.
-
It will attempt to attach to the running core, leaving the FSBL‑based debug unlock logic in place.
-
Once attached, you can set breakpoints in FSBL and Appli (both symbol files are loaded).
The Workflow Steps
-
Flash in DEV Mode:
-
Set Switch to DEVBOOT mode (BOOT1=1).
-
Run Task: "Flash STM32N6 (DEVBOOT)".
-
Result: FSBL-trusted.bin and Appli-trusted.bin are correctly written to External Flash.
-
Boot in FLASHBOOT Mode:
-
Set Switch to FLASHBOOT mode (BOOT1=0, BOOT0=0).
-
Power cycle the board.
-
Result: Boot ROM validates FSBL → FSBL runs → FSBL re-enables debug.
-
Debug via Hotplug:
-
Press F5 on "STM32N6-DK Hotplug/Debug".
-
Result: Debugging with FLASHBOOT mode (BOOT1=0, BOOT0=0) is now possible.
Questions
Q: Is it possible to debug (and program) in Flash boot mode (BOOT1 = 0)?
-
Debug: Yes, but only if your FSBL manually unlocks the BSEC registers as shown above.
-
Program: Not easily via standard tools. Always program in DEVBOOT (BOOT1 = 1), then switch modes to test.
Q: I cannot connect with STM32CubeProgrammer in that mode…
Without FSBL re‑enabling debug, that is expected. After you flash a FSBL that reopens debug, and once it is running, you can use Hotplug/attach from STM32CubeProgrammer as well.
Q: How do I program signature and encryption keys (OTP)?
We do not have a specific tutorial for programming these exact keys, but we are working to improve our documentation in this area and plan to provide more detailed application notes and examples in future releases.
