Oberon RTK

Build, Load & Debug: RP2040

Build, load, and debug programs on RP2040

Overview

This document describes how to build, load, and run RTK-based programs for the RP2040 for debugging.

  • RP2040 is single-image only (Cortex-M0+, no TrustZone).

  • For debugging, ELF binaries are the only option to include DWARF debug data.

  • make-elf creates the ELF file. 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.

  • Other guides:

See also Practical Notes.

Prerequisites

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

Steps

Please refer to Compile and Link: RP2040.

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

2. Create the Absolute Assembly Listings

gen-rdb creates an .alst file for each module in the 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.

python -m gen-rdb <program>.map

gen-rdb uses configuration data directly from the program's map file, hence no command line options are required.

By default, the .alst files are created in directory rdb in the project directory. To use another directory, please refer to the manual page gen-rdb.

3. Make the ELF File

make-elf embeds the program binary into an ELF file, together with the debug data and symbols generated from the .alst files. The --boot2 option prepends the RP2040 boot2 stage-2 loader (256 bytes), so the ELF is bootable on flash.

python -m make-elf <program>.bin --boot2 --debug

make-elf uses configuration data directly from the program's map file.

The ELF file can be inspected using the standard tool readelf. Run readelf -S <program>.elf to list all sections.

4. Load the ELF File

The ELF file is 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

Last updated: 15 May 2026