Use Debug mode to inspect a target’s stack, variables, registers, and memory or to stop at a specific point in execution. The available operations and startup behavior depend on the selected debugger.
Prepare
- Build the matching firmware artifact with 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 select the simulator explicitly.
- Run
/debug and ask Embedder to check debugger readiness.
- Identify the exact MCU, probe, and artifact when the project has several choices.
Choose the setup guide for the tools attached to your target:
- J-Link: SEGGER device selection, SWD/JTAG, programming, and RTT sharing.
- OpenOCD: interface/target configurations, including supported ST-Link and CMSIS-DAP setups.
- TI CCS and XDS: CCS installation, TI target configurations, and probe-specific capabilities.
- XMOS xTAG and xgdb:
.xe applications, adapter selection, tiles, and threads.
- XMOS xsim: simulated execution and instruction traces without a board.
Choose programming or attachment
A normal J-Link or OpenOCD connection programs the ELF and attempts to run to main by default. Programming and debugger startup can change or halt target execution. Use attach-only to load symbols without programming or running to main.
Attach to a running target
Request no halt separately when the target needs to keep running. Attach-only and no-halt control the connection workflow; they do not guarantee that every probe and target configuration preserves execution state during startup. Check the selected setup before connecting to a live fault, and use an existing debugger session where possible. For XMOS, no-halt explicitly continues execution after connection, so it can resume a halted fault.
Program a fresh debug run
“Do not run to main” and “attach only” are different requests. Disabling run-to-main still permits programming. For J-Link and OpenOCD, a programming connection with no-halt requested resets and halts the target after loading the ELF. Use attach-only together with no-halt when requesting a live attachment, and state whether reset or halt is allowed.
Inspect a fault
For a Cortex-M target with a HardFault_Handler symbol:
You can ask for breakpoints by function, file and line, or address; continue and stepping; stack frames and locals; memory reads; and available thread or RTOS task information.
A task view depends on the debugger and firmware providing enough information. Optimized-out variables may require a debug build to inspect.
Verify peripheral state
Use register lookup to verify addresses and access rules. A reset value in a reference is not a live measurement.
Other target workflows
Use XMOS xTAG and xgdb for hardware debugging and xsim for a simulated run. Select the target explicitly and keep simulator findings distinct from board observations.
Use TI CCS and XDS for supported CCS workflows. Legacy CCS DSS sessions do not provide stack/frame inspection, and their programming/no-halt behavior differs from J-Link and OpenOCD.
For Infineon AURIX/TriCore, use Debug TriCore over TCF. There is no GDB for TriCore, so gdb.* helpers do not apply. Hardware scripts use aurix.* against Infineon’s aurix-debugger.exe.
Finish cleanly
Ask Embedder to continue or disconnect when inspection is complete. Stop active debugger or RTT sessions before a J-Trace capture takes over the probe.
Troubleshoot
- Target not found: check power, probe wiring, device spelling, and the selected interface.
- OpenOCD cannot match the MCU: use the exact target configuration; do not substitute a nearby family.
- Probe busy: close competing debug applications or stop the active hardware task.
- Wrong symbols: use the debug artifact from the installed firmware build.
- Variable unavailable: check debug information and optimization settings.
