GDB debugging

Use Debug mode when you need to stop the target at a specific point, or inspect its stack, variables, registers, and memory. Embedder starts the debug server for your probe, connects to it, and reports what it finds. Switch with /debug. In VS Code, Debug mode also adds a Debug Output tab to the Embedder Monitor.

Prepare

Build the firmware artifact with debug symbols: an ELF for J-Link or OpenOCD, the CCS debug artifact for TI, or a .xe application for XMOS.
Connect and power the target and probe, or choose the simulator explicitly.
Run /debug and ask Embedder to check debugger readiness.
Name the exact MCU, probe, and artifact when the project has several. If the project has more than one platform, Embedder asks which one to debug.

Then follow the setup guide for your probe or target:

Probe or target	Guide	Covers
SEGGER J-Link	J-Link	Device names, SWD or JTAG, programming, and RTT sharing
ST-Link, CMSIS-DAP, or another OpenOCD adapter	OpenOCD	Interface and target configurations
TI XDS probe and a target with a `.ccxml` configuration	TI CCS and XDS	Headless CCS, target configurations, multicore, and probe differences
XMOS xTAG	XMOS xTAG and xgdb	`.xe` applications, adapter selection, tiles, and threads
XMOS simulator	XMOS xsim	Simulated runs and instruction traces without a board
Infineon AURIX (TriCore)	Debug TriCore over TCF	AURIX debugging, which doesn’t use GDB

Two other probe guides cover work that isn’t interactive debugging: SEGGER J-Trace for Arm ETM instruction trace and coverage, and probe-rs for programming a board on a remote bridge.

How Embedder picks a debugger

Unless you ask for a specific debugger, Embedder chooses in this order:

The Debug Interface value in EMBEDDER.md:
- jlink selects J-Link, when the SEGGER software is installed.
- st-link or cmsis-dap selects OpenOCD with that adapter.
- xgdb selects XMOS xgdb. An XMOS platform or a .embedder/xmos.json file selects it too.
- xds110, xds100, xds100v1, xds100v2, xds100v3, or ccs selects TI CCS.
A connected J-Link probe, when the J-Link software is installed.
OpenOCD. If no OpenOCD is installed, Embedder downloads its own copy on supported hosts.

Embedder also downloads its own GDB client for J-Link and OpenOCD. See J-Link or OpenOCD for the supported hosts.

Choose programming or attachment

A normal J-Link or OpenOCD connection programs the ELF and tries to run to main. Programming and debugger startup change or halt target execution. Ask for attach-only to load symbols without programming or running to main.

Embedder asks you to approve before it starts a debug server or runs a debugging script, unless your approval settings already allow it. Check the request before you approve: approving is what lets Embedder program or halt the target. Say which behavior you want. The options also appear as arguments in hardware scripts:

Request	Script options	J-Link and OpenOCD	TI CCS
Normal connection	Defaults	Programs the ELF, then runs to `main`	Loads and verifies the program, then runs to `main`
Program without running to `main`	`run_to_main=False`	Programs the ELF and leaves the target halted	Loads the program and leaves the target halted
Program with no halt	`no_halt=True`	Programs the ELF, then resets and halts the target	Loads the program, then starts execution
Attach only	`attach=True`	Loads symbols only; the debugger halts the target when it connects	Loads symbols only, then halts the target
Attach only, no halt	`attach=True, no_halt=True`	Loads symbols and connects without requesting a halt	Loads symbols without requesting a halt

XMOS behaves differently: no-halt continues execution after connecting, which can resume a halted fault. See XMOS xTAG and xgdb.

Program a fresh debug run

Program build/app.elf through the selected J-Link, run to main, and stop at
uart_init. Show the current frame and relevant registers.

If the target doesn’t reach main within about 5 seconds, Embedder halts it where it is. Check the reported stop location before you rely on the result.

Attach to a running target

Use attach-only with no-halt to look at firmware that’s already running, such as a board that just faulted. These options control what Embedder requests. They don’t guarantee that every probe and target configuration leaves execution untouched during startup. Before connecting to a live fault:

Check the setup guide for your probe, and reuse an existing debugger session where possible.
State whether a reset or halt is acceptable.
Expect to halt the target to read state. Registers, memory, and the stack are read from a halted target, so a running target has to be interrupted first.

Check whether the selected probe and target configuration support attachment
without reset or halt. If they do, use attach-only with no halt and
build/app.elf for symbols. Do not program or run to main.

“Don’t run to main” and “attach only” are different requests. Turning off run-to-main still programs the target.

Inspect a fault

For a Cortex-M target with a HardFault_Handler symbol:

Break at HardFault_Handler. When it stops, read the stack, PC, SP, LR, CFSR,
and HFSR. Do not reset the target afterward.

Once connected, you can ask for:

Breakpoints by function, file and line, or address.
Continue, interrupt, step, step over, and step out.
Stack frames and local variables.
Register and memory reads, and expression evaluation.
Thread or RTOS task information, when available.

Set breakpoints by asking in chat, as in the examples above, or with gdb.breakpoint() in a hardware script. Embedder doesn’t add a debugger to VS Code’s Run and Debug view, and it doesn’t use breakpoints you set in the editor gutter. A task view depends on the debugger and firmware providing enough information. Variables that are optimized out may need a debug build. TI CCS sessions have no thread or task view, and whether they show the call stack depends on the probe and CCS version; see Supported probes.

Verify peripheral state

Look up RCC CR for the selected MCU, attach without programming, read the live
value once, and decode its fields. Do not write the register.

Use register lookup to check addresses and access rules first. A reset value in a reference is not a live measurement.

Script helpers

For a repeatable check, a hardware script opens the connection with gdb.jlink_connect(), gdb.openocd_connect(), gdb.ccs_connect(), or gdb.xmos_connect(). Each probe’s guide lists the connection options. These helpers then control and inspect the target:

Helper	Use
`gdb.breakpoint(location)`	Set a breakpoint at a function, a `file.c:42` line, or an address such as `*0x08000100`.
`gdb.continue_until_break(timeout_seconds=15)`	Resume and wait for the target to stop. Check `timed_out` in the result before you read state.
`gdb.interrupt()`	Halt a running target.
`gdb.step()`, `gdb.next()`, `gdb.finish()`	Step into, step over, or run until the current function returns.
`gdb.stack()`, `gdb.frame(frame=0)`	Read the call stack, or one frame with its local variables.
`gdb.read_register(name)`, `gdb.read_registers()`	Read one register, or all of them as a dict.
`gdb.read_memory(address, size)`	Read `size` bytes.
`gdb.eval(expression)`	Evaluate an expression, such as a variable name or `(uint32_t)0x20000000`.
`gdb.threads()`, `gdb.tasks()`	List threads or RTOS tasks. Not available in CCS sessions.
`gdb.execute(command)`	Run a GDB command, such as `disassemble main`. Not available in CCS sessions.
`gdb.disconnect()`	End the debug session.

gdb.openocd_connect(elf="build/app.elf", mcu="stm32f407vg")
gdb.breakpoint("uart_init")
stop = gdb.continue_until_break(timeout_seconds=5)
if stop["timed_out"]:
    raise RuntimeError("uart_init was not reached")
print(gdb.frame())
print(gdb.read_registers())

After gdb.jlink_connect(), gdb.openocd_connect(), or gdb.ccs_connect(), these helpers are available too. Other debuggers report them as unsupported.

Helper	Use
`gdb.status()`	Read the actual connection and execution state. `halted` is `None` when the state is unknown.
`gdb.capabilities()`	Check which operations the session supports before optional calls.
`gdb.list_cores()`	List configured CCS cores, or describe the single J-Link or OpenOCD target.
`gdb.resume()`	Start execution without waiting for a breakpoint.
`gdb.wait_for_halt(timeout_seconds=15, halt_on_timeout=False)`	Wait for the target to stop without resuming it. A timeout leaves it running unless `halt_on_timeout=True`.
`gdb.load_symbols(path)`	Replace symbols without programming the target.
`gdb.list_registers(group=None)`	Discover register names.
`gdb.write_register(name, value)`	Write a register.
`gdb.memory_pages()`	List memory pages. J-Link and OpenOCD report one `"default"` address space.
`gdb.read_memory_elements(address, count, bit_size, page=None)`	Read `count` elements of `bit_size` bits.
`gdb.write_memory_elements(address, values, bit_size, page=None)`	Write elements with the same address and page rules.
`gdb.list_breakpoints()`	List breakpoints set by the current script.
`gdb.remove_breakpoint(id)`	Remove a breakpoint by the ID it returned.
`gdb.list_resets()`	List the reset IDs the target offers.
`gdb.reset(reset_id)`	Run a reset. It can affect other cores and peripherals.
`gdb.restart()`	Restart the loaded program. Supported on CCS only; J-Link and OpenOCD report it as unsupported, so use `reset()` there.
`gdb.read_console()`	Drain target output, debugger console, and log text. CCS returns CIO output when available. This doesn’t capture UART, RTT, or semihosting.

Breakpoints belong to the script that set them. Embedder removes them when the script exits, including after a failure. J-Link exposes the "default" reset. OpenOCD exposes "halt" and "init", and resets all configured targets. On J-Link and OpenOCD, a reset leaves the target halted, so call gdb.resume() to run. CCS lists the resets its runtime offers.

gdb.openocd_connect(elf="build/app.elf", mcu="stm32f407vg")
gdb.resume()
stop = gdb.wait_for_halt(timeout_seconds=5, halt_on_timeout=True)
print(stop)
print(gdb.read_memory_elements(0x20000000, 4, 32))

Finish cleanly

Tell Embedder whether to leave the firmware running or halted, then ask it to disconnect. Other probe operations take over the probe:

Flashing closes an open debugger session first.
A J-Trace capture closes open debugger and RTT sessions before it starts.

Troubleshoot

No debug server found: install the J-Link software, or let Embedder download OpenOCD on a supported host. If that download fails or your host isn’t supported, install OpenOCD yourself. See the guide for your probe.
Target not found: check power, probe wiring, device spelling, and the selected interface.
OpenOCD can’t match the MCU: use the exact target configuration. Don’t substitute a nearby family.
Several platforms: name the MCU you want to debug.
Probe busy: close competing debug applications, stop the active hardware task, or run /hardware-queue to check other chats.
Target is running: ask Embedder to interrupt it before reading registers, memory, or the stack.
Wrong symbols: use the debug artifact from the firmware build that’s on the board.
Variable unavailable: check debug information and optimization settings.

Get started

Set up a project

Work with Embedder

Workflow guides

Monitor and debug

Code analysis

Automation

Settings and help

Reference

Prepare

How Embedder picks a debugger

Choose programming or attachment

Program a fresh debug run

Attach to a running target

Inspect a fault

Verify peripheral state

Script helpers

Finish cleanly

Troubleshoot