Set-up: Debugging on STM32

Step-by-step set-up for debugging RTK programs on STM32U585 and STM32H573 with GDB, OpenOCD, and VS Code + Cortex-Debug

Overview

This is the second of two set-up stages for STM32 targets, layered on top of Set-up: Build Scripts on STM32. It adds the GDB / OpenOCD toolchain needed to debug RTK programs on hardware – via command-line GDB, via the framework's OpenOCD server scripts, or via Cortex-Debug in VS Code.

The two STM32 MCUs supported by the framework use different OpenOCD servers:

STM32U585 – xPack OpenOCD (works with both ST-LINK and J-Link probes).
STM32H573 – ST OpenOCD (bundled with STM32CubeIDE); xPack OpenOCD lacks the stm32h5x.cfg target configuration.

Both are wired up below. If you target only one of the two, leave the other's variables commented out.

For RP2040 / RP2350, see Set-up: Debugging on RP.

This guide configures the additional variables in the With debugging tier of <repo>/tools/setup/set-rtk-env.cmd (Windows) or set-rtk-env.sh (macOS / Git Bash). The script ships with these variables commented out; this guide walks through enabling them.

Prerequisites

Set-up: Build Scripts on STM32 completed and verified.
A debug probe:
- ST-LINK – built into most STM32 development boards, no extra hardware needed.
- J-Link (STM32U585 only) – if you have a SEGGER probe and prefer it over ST-LINK.
xPack ARM GNU Toolchain – provides arm-none-eabi-gdb-py3 (GDB with embedded Python, required for the GDB test engine) and arm-none-eabi-objdump. Install per External Tools § xPack ARM GNU Toolchain.
xPack OpenOCD – required for STM32U585 (works with both ST-LINK and J-Link probes). Install per External Tools § xPack OpenOCD.
ST OpenOCD – required for STM32H573 (bundled with STM32CubeIDE). Install per External Tools § ST OpenOCD (from STM32CubeIDE).
SEGGER J-Link Software – required only if you use a J-Link probe; provides USB drivers and firmware updater. Install per External Tools § SEGGER J-Link Software.
VS Code + Cortex-Debug – for graphical debugging with variable, register, and memory views. Install per External Tools § VS Code + Cortex-Debug. Per-project launch.json configuration is covered in Debugging.

Steps

1. Note Your xPack ARM Toolchain Install Path

The xPack toolchain ships as a self-contained archive extracted to a location of your choice. The relevant binaries are in <xpack-root>\bin\:

arm-none-eabi-gdb-py3.exe – goes into RTK_GDB
arm-none-eabi-objdump.exe – goes into RTK_OBJDUMP

Note the absolute paths to use in step 3.

2. Note Your OpenOCD Install Paths

STM32U585: xPack OpenOCD

xPack OpenOCD extracts to a directory of your choice. The executable lives at:

<xpack-openocd-root>\bin\openocd.exe

This path goes into RTK_OPENOCD_XPACK in step 3.

The project supplies its own probe interface wrappers (stlink-swd.cfg, jlink-swd.cfg) in <repo>/tools/server-scripts/openocd/, composed inline from RTK_REPO_ROOT at server start time – no separate scripts-directory variable is needed for xPack OpenOCD.

STM32H573: ST OpenOCD

ST OpenOCD ships inside STM32CubeIDE. After installing CubeIDE, both the OpenOCD binary and its scripts directory sit deep within the plugins tree, eg.:

<cubeide-root>\plugins\com.st.stm32cube.ide.mcu.externaltools.openocd.win32_<ver>\tools\bin\openocd.exe
<cubeide-root>\plugins\com.st.stm32cube.ide.mcu.debug.openocd_<ver>\resources\openocd\st_scripts

The <ver> segments depend on your CubeIDE version. The executable path goes into RTK_OPENOCD_STM; the st_scripts directory goes into RTK_OPENOCD_STM_SCRIPTS. The latter supplies the stlink-dap interface configuration used for ST-LINK debugging on STM32H5.

3. Edit `set-rtk-env.cmd`

Open <repo>/tools/setup/set-rtk-env.cmd in a text editor. Uncomment the following set lines in the [EDIT] sections and fill in the paths from steps 1 and 2:

RTK_GDB
RTK_OBJDUMP

For STM32U585:

RTK_OPENOCD_XPACK
RTK_SVD_STM32U585 (derived from RTK_REPO_ROOT; no edit needed)

For STM32H573:

RTK_OPENOCD_STM
RTK_OPENOCD_STM_SCRIPTS
RTK_SVD_STM32H573 (derived from RTK_REPO_ROOT; no edit needed)

Then uncomment the corresponding setx lines at the bottom of the script. If you target only one of the two STM32 MCUs, leave the other's lines commented out.

RTK_GDB_HOST is needed only by the framework's test engines.

For the meaning of each variable, see Environment Variables.

On macOS or Git Bash, the same uncommenting applies to set-rtk-env.sh.

4. Run the Script

Open a cmd window (not admin) and run:

tools\setup\set-rtk-env.cmd

5. Verify

In a freshly launched cmd window:

set RTK_

In addition to the build-stage variables, you should now see RTK_GDB, RTK_OBJDUMP, and the OpenOCD / SVD variables for the MCU(s) you enabled. Spot-check that the paths point to existing files and directories.

A quick functional check:

"%RTK_GDB%" --version

For STM32U585:

"%RTK_OPENOCD_XPACK%" --version

For STM32H573:

"%RTK_OPENOCD_STM%" --version

All should print version information. The xPack OpenOCD output is prefixed with "xPack"; the ST OpenOCD output is not – if in doubt, verify the correct binary by its path.

Next Steps

To debug a program from the command line: see Debugging § GDB Command Line.
To debug with VS Code + Cortex-Debug: see Debugging § VS Code + Cortex-Debug.
To start an OpenOCD server manually: see External Tools § GDB Server Scripts.