debug-gdb-openocd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GDB OpenOCD 调试

GDB OpenOCD Debugging

适用场景

Applicable Scenarios

用户希望通过 OpenOCD 调试 Cortex-M 类目标。
工作区中已有
```
ELF
```
和与 OpenOCD 兼容的探针信息。
烧录或串口监视流程表明，需要进一步查看断点、停核控制、寄存器或回溯信息。
需要在调试前确认 OpenOCD 和 GDB 环境是否就绪。

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.

必要输入

Required Inputs

一份带符号的
```
ELF
```
，或包含
```
artifact_path
```
的
```
Project Profile
```
。
OpenOCD 配置信息，或足以安全解析配置的工作区线索。

可选调试模式：

download-and-halt

、

attach-only

、

crash-context

。

可选的 GDB 可执行文件路径。

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

Optional path to the GDB executable file.

自动探测

Auto Detection

默认模式为
```
download-and-halt
```
；只有用户显式要求附着调试或崩溃现场检查时才切换。
GDB 由脚本自动探测，优先级为：显式用户输入、
```
Project Profile
```
、
```
arm-none-eabi-gdb
```
、
```
gdb-multiarch
```
。
探针由脚本自动探测，优先级与
```
flash-openocd
```
保持一致。
做符号级调试必须有
```
ELF
```
。若只有
```
HEX
```
或
```
BIN
```
，应阻塞并要求提供匹配
```
ELF
```
。

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.

执行步骤

Execution Steps

先阅读 references/debug-playbook.md 中的决策树，判断应使用条件断点、普通断点还是 OpenOCD Telnet。
再阅读 references/usage.md，确认本次是环境探测，还是执行调试会话。
若不确定环境是否就绪，先运行自带脚本 scripts/gdb_debugger.py 的
```
--detect
```
模式确认。
根据用户意图选择调试模式：
```
download-and-halt
```
（默认）、
```
attach-only
```
或
```
crash-context
```
。
使用
```
--elf
```
指定符号文件，配合
```
--interface
```
+
```
--target
```
或
```
--config
```
启动调试。
读取脚本输出的调试结果，重点关注寄存器状态、回溯帧和 Fault 寄存器（crash-context 模式）。
将调试配置和关键观察写回
```
Project Profile
```
，并在需要时交给下游 skill。

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.

失败分流

Failure Diversion

当缺少
```
openocd
```
或兼容 GDB 时，返回
```
environment-missing
```
。
当没有可用的
```
ELF
```
时，返回
```
artifact-missing
```
。
当 OpenOCD 或 GDB 无法连接目标板时，返回
```
connection-failure
```
。
当 OpenOCD 配置或符号文件与目标不一致时，返回
```
project-config-error
```
。
当会话可以建立，但无法停核、加载或得到可信回溯时，返回
```
target-response-abnormal
```
。
当存在多个同样合理的探针、配置或符号文件时，返回
```
ambiguous-context
```
。

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.

平台说明

Platform Notes

自带脚本使用 Python 标准库和 subprocess 调用 openocd 和 gdb，因此调试调度路径本身是跨平台的。
输出中应将 OpenOCD 与 GDB 命令分开列出，方便用户在其他 shell 或 IDE 中复现。
Windows 宿主机可能需要解析
```
.exe
```
后缀，但逻辑流程与其他平台一致。

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 Conventions

输出调试模式、OpenOCD 命令、GDB 可执行文件、
```
ELF
```
路径和关键观察结论。

在

Project Profile

中保留

artifact_path

、

artifact_kind

、

gdb_executable

、

openocd_config

。

当复位后或继续运行后下一步是观察运行行为时，推荐
```
serial-monitor
```
。

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.

交接关系

Handover Relationships

当目标恢复运行后，需要继续观察运行期日志时，将成功会话交给
```
serial-monitor
```
。

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