Set-up: Debugging on RP

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

Overview

This is the second of two set-up stages for RP targets, layered on top of Set-up: Build Scripts on RP. 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.

For STM32, see Set-up: Debugging on STM32.

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 RP completed and verified.
A CMSIS-DAP debug probe – the Raspberry Pi Debug Probe is the reference option (around 15 EUR); a second Pico running Picoprobe firmware works too.
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.
Raspberry Pi OpenOCD – the RPi fork; required for RP2040 and RP2350 because xPack OpenOCD lacks RP2350 target support. Install per External Tools § Raspberry Pi OpenOCD.
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 Raspberry Pi OpenOCD Install Path

The RPi OpenOCD archive likewise extracts to a directory of your choice. The relevant entries are:

<rpi-openocd-root>\openocd.exe – goes into RTK_OPENOCD_RPI
<rpi-openocd-root>\scripts – goes into RTK_OPENOCD_RPI_SCRIPTS

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
RTK_OPENOCD_RPI
RTK_OPENOCD_RPI_SCRIPTS

Also uncomment the derived SVD variables (no edit needed – they compose from RTK_REPO_ROOT):

RTK_SVD_RP2040
RTK_SVD_RP2350

Then uncomment the corresponding setx lines at the bottom of the script.

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, RTK_OPENOCD_RPI, RTK_OPENOCD_RPI_SCRIPTS, RTK_SVD_RP2040, and RTK_SVD_RP2350. Spot-check that the paths point to existing files and directories.

A quick functional check:

"%RTK_GDB%" --version
"%RTK_OPENOCD_RPI%" --version

Both should print version information. The GDB output should include a Python version string – that's the -py3 variant needed for the GDB test engine.

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.