GDB OpenOCD Debugging

Applicable Scenarios

Users want to debug Cortex-M targets via OpenOCD.
The workspace already has an
```
ELF
```
and probe information compatible with OpenOCD.
The flashing or serial monitoring process indicates that further inspection of breakpoints, core halt control, registers, or backtrace information is required.
Need to confirm whether the OpenOCD and GDB environment is ready before debugging.

A symbol-containing
```
ELF
```
, or a
```
Project Profile
```
that includes
```
artifact_path
```
.
OpenOCD configuration information, or workspace clues sufficient to safely parse the configuration.

Optional debugging modes:

download-and-halt

attach-only

crash-context

The default mode is
```
download-and-halt
```
; it only switches when the user explicitly requests attach debugging or crash scene inspection.
GDB is automatically detected by the script, with priority: explicit user input,
```
Project Profile
```
,
```
arm-none-eabi-gdb
```
,
```
gdb-multiarch
```
.
Probes are automatically detected by the script, with the same priority as
```
flash-openocd
```
.
Symbol-level debugging requires an
```
ELF
```
. If only
```
HEX
```
or
```
BIN
```
is available, the process should be blocked and a matching
```
ELF
```
should be requested.

First read the decision tree in [references/debug-playbook.md] to determine whether to use conditional breakpoints, regular breakpoints, or OpenOCD Telnet.
Then read [references/usage.md] to confirm whether this is environment detection or a debugging session execution.
If unsure whether the environment is ready, first run the
```
--detect
```
mode of the built-in script [scripts/gdb_debugger.py] to confirm.
Select the debugging mode according to the user's intention:
```
download-and-halt
```
(default),
```
attach-only
```
or
```
crash-context
```
.
Use
```
--elf
```
to specify the symbol file, and start debugging with
```
--interface
```
+
```
--target
```
or
```
--config
```
.
Read the debugging results output by the script, focusing on register status, backtrace frames, and Fault registers (in crash-context mode).
Write the debugging configuration and key observations back to the
```
Project Profile
```
, and hand it over to downstream skills when needed.

Returns
```
environment-missing
```
when
```
openocd
```
or compatible GDB is missing.
Returns
```
artifact-missing
```
when no available
```
ELF
```
exists.
Returns
```
connection-failure
```
when OpenOCD or GDB cannot connect to the target board.
Returns
```
project-config-error
```
when the OpenOCD configuration or symbol file is inconsistent with the target.
Returns
```
target-response-abnormal
```
when the session can be established but cannot halt the core, load, or obtain a reliable backtrace.
Returns
```
ambiguous-context
```
when there are multiple equally reasonable probes, configurations, or symbol files.

The built-in script uses Python standard libraries and subprocess to call openocd and gdb, so the debugging scheduling path itself is cross-platform.
The output should list OpenOCD and GDB commands separately to facilitate users to reproduce them in other shells or IDEs.
Windows hosts may need to parse the
```
.exe
```
suffix, but the logical flow is consistent with other platforms.

Output the debugging mode, OpenOCD command, GDB executable,
```
ELF
```
path, and key observation conclusions.

Retain

artifact_path

artifact_kind

gdb_executable

openocd_config

in the

Project Profile

When the next step after reset or continued operation is to observe running behavior,
```
serial-monitor
```
is recommended.

When the target resumes operation and runtime logs need to be continuously observed, hand over the successful session to
```
serial-monitor
```
.