debug-gdb-openocd

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkDeclared1 observation
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass, no license.

Audit 0.4.1 · source sha f2eee4d05246 · 27 Oct 2026Report an issue or request a re-scan

• Publisherleokemp223 GitHub userOwner of the repository this skill is read from
• Source folderleokemp223/embed-ai-tool/skills/debug-gdb-openocdThe exact folder we audited
• LicenceNot declaredAs the repository states it
• Commit pinned for this verdictf2eee4d05246A new audit runs when the source changes
• Repository statusNot archivedLast push 68 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: 当需要通过 OpenOCD 启动或附着 GDB 会话,调用自带脚本完成固件下载、在线调试或崩溃现场检查时使用。

---
name: debug-gdb-openocd
description: 当需要通过 OpenOCD 启动或附着 GDB 会话,调用自带脚本完成固件下载、在线调试或崩溃现场检查时使用。
---

# GDB OpenOCD 调试

## 适用场景

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

## 必要输入

- 一份带符号的 `ELF`,或包含 `artifact_path` 的 `Project Profile`。
- OpenOCD 配置信息,或足以安全解析配置的工作区线索。
- 可选调试模式:`download-and-halt`、`attach-only`、`crash-context`。
- 可选的 GDB 可执行文件路径。

## 自动探测

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

## 执行步骤

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

## 失败分流

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

## 平台说明

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

## 输出约定

- 输出调试模式、OpenOCD 命令、GDB 可执行文件、`ELF` 路径和关键观察结论。
- 在 `Project Profile` 中保留 `artifact_path`、`artifact_kind`、`gdb_executable`、`openocd_config`。
- 当复位后或继续运行后下一步是观察运行行为时,推荐 `serial-monitor`。

## 交接关系

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

Excerpt, first 1,958 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/leokemp223/embed-ai-tool
git -C embed-ai-tool checkout f2eee4d05246

Works in

1. 2026-10-27
   ✓SAFE B 89 / 100

   first audit · source f2eee4d05246

Questions about debug-gdb-openocd

• github.com/leokemp223/embed-ai-tool/tree/master/skills/debug-gdb — the audited source at commit f2eee4d05246 and every finding aboveObserved · 27 Oct 2026

Spotted something wrong? Report a correction · Methodology