openocd-mcu-debug

name	openocd-mcu-debug
description	OpenOCD-based MCU probing, CMSIS-SVD register decoding, and embedded debug diagnosis for Cortex-M/RISC-V targets. Use when working with connected MCU hardware, OpenOCD, JTAG/SWD, SVD files, chip identification, register decoding, HardFault/crash/hang diagnosis, peripheral/clock/memory debugging, or ELF symbol/source lookup.

OpenOCD MCU Debug - 芯片探测与寄存器解读

连接目标 MCU 后，通过 OpenOCD 读取 CPU/芯片 ID，加载本地 SVD 文件，解读外设寄存器，并辅助 HardFault、挂死、外设、时钟、内存和 ELF 源码级调试。

前置要求

硬件操作依赖一个正在运行的 OpenOCD 会话。若当前环境已安装 openocd-mcu MCP，优先调用 MCP 工具；否则使用 scripts/openocd_client.py 连接默认 telnet 端口 4444：

python .\scripts\openocd_client.py connect

如果 OpenOCD 尚未启动，先读 openocd-debugging-workflow.md。

OpenOCD MCP

本技能带一个无第三方依赖的 stdio MCP server：

python .\tools\openocd-mcu-mcp\server.py

工具名：

• connect
• halt
• resume
• reset_halt
• register_read
• registers
• memory_read
• memory_write
• raw_command
• probe_chip
• find_svd
• decode_register

按用户要求，MCP 工具会真实执行 resume、reset_halt、memory_write 等操作，不再做二次确认拦截。脚本 CLI 仍保留确认参数，适合作为手工保护层。

核心流程

OpenOCD MCP connect 或 openocd_client.py connect/start
    ↓
halt
    ↓
probe_chip.py 读取 CPUID/DBGMCU/FICR/CSR
    ↓
find_svd.py 或 fetch_svd.py 找到 SVD
    ↓
openocd_client.py mdw 读取寄存器
    ↓
decode_register.py 按 SVD 位域解码

工作流路由

场景	参考流程	可执行工具
启动/连接 OpenOCD	openocd-debugging-workflow.md	scripts/openocd_client.py
连接后识别芯片	chip-probing-workflow.md	scripts/probe_chip.py
查看/解读寄存器	register-decoding.md	scripts/find_svd.py, scripts/decode_register.py
芯片ID速查	chip-id-reference.md	人工核对表
ELF符号/源码调试	elf-debugging-workflow.md	scripts/elf_lookup.py

芯片探测与寄存器

现象	诊断流程	核心策略
HardFault/崩溃/异常	hardfault-diagnosis.md	读CFSR+栈回溯+Fault地址
程序挂死/跑飞/不响应	hang-diagnosis.md	多次PC采样+死循环定位
外设不工作	peripheral-diagnosis.md	时钟→GPIO→外设寄存器逐层排查
时钟/波特率异常	clock-diagnosis.md	RCC时钟树分析+频率计算
栈溢出/内存踩踏	memory-diagnosis.md	SP检查+栈canary+内存填充对比

SVD文件查找

SVD 文件存放在 svd/ 目录下，可能按厂商子目录组织（如 svd/arm/STMicro/STM32F103xx.svd）。本技能不强行内置完整 SVD 库，优先查找本地文件，缺失时可用 scripts/fetch_svd.py 从 cmsis-svd/cmsis-svd-data 下载。

确定芯片型号后：

python .\scripts\find_svd.py STM32F103 --json
rg --files .\svd | rg -i "STM32F103.*\.svd$"

如果未命中：

python .\scripts\fetch_svd.py STM32F103 --download .\svd\arm

SVD 文件来源：

• cmsis-svd-data: https://github.com/cmsis-svd/cmsis-svd-data
• 各芯片厂商 SDK / CMSIS Pack

快速开始

用户说“识别一下连接的芯片”、“读 RCC 寄存器”、“查看 PC 指针”等任何涉及硬件操作时：

1. 运行 python .\scripts\openocd_client.py connect，失败则按 openocd-debugging-workflow.md 启动 OpenOCD。
2. 运行 python .\scripts\probe_chip.py --halt 识别芯片。
3. 运行 python .\scripts\find_svd.py <芯片型号> 找 SVD；缺失时运行 fetch_svd.py 或提示用户放入 SVD。
4. 用 openocd_client.py mdw 读寄存器值。
5. 用 decode_register.py 按 SVD 位域解码。

如果存在 MCP 工具 connect / memory_read 等，优先用 MCP；没有 MCP 时使用 scripts/。