Stm32 debug
Debug STM32 firmware on real hardware through stm32-gdb-mcp. Use for flash, execution control, memory/register/RTOS inspection, HardFaults, hangs, and reproducible hardware bugs. / 通过 stm32-gdb-mcp 在真实硬件上调试 STM32,适用于烧录、执行控制、内存/寄存器/RTOS 检查、HardFault、卡死和可复现硬件故障。From its SKILL.md
npx -y skills add Zeraissh/stm32-gdb-mcp --skill stm32-debugAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
11.3 KB, as published. Nobody here has run it
STM32 hardware debugging / STM32 硬件调试
Drive stm32-gdb-mcp as a senior embedded-debug loop:
observe → orient (symbolize) → hypothesize → act safely → verify.
按资深嵌入式工程师的闭环使用 stm32-gdb-mcp:
观察 → 定位(符号化)→ 提出假设 → 安全操作 → 验证。
Golden rules / 核心规则
- Run
self_checkimmediately afterstart_debug_session. It validates byte order, Cortex-M core, and expected MCU family before later evidence is trusted. /start_debug_session后立即运行self_check。 在信任后续证据前先验证字节序、 Cortex-M 内核和预期 MCU 系列。 - Reads require a HALTED core. If a read returns
target_unresponsive, callhalt_executionfirst.run_and_waitleaves the core running on timeout. / 读取要求内核已暂停。 遇到target_unresponsive先调用halt_execution;run_and_wait超时后内核仍在运行。 - A breakpoint timeout means the path was not reached. Halt, run
capture_state, inspectbreakpoint(action=list)and itshit_count, then read the gating state. Move the breakpoint earlier, drive the required stimulus, or use a condition; do not repeat the same wait. / 断点超时表示代码路径未到达。 暂停后执行capture_state,检查断点hit_count和门控状态,再前移断点、驱动输入或使用条件断点;不要原样重试。 - Prefer composites such as
flash_and_run,debug_until,capture_state, andrun_for_durationto reduce round trips. / 优先使用组合工具,减少 MCP 往返和中间状态。 - Writes are guarded. Option bytes, IWDG, and WWDG are blocked by default.
Use
write_guard(action=policy)for explicit access or dry-run simulation, andwrite_guard(action=audit)for the record. / 写操作受保护。 option bytes、IWDG 和 WWDG 默认禁止;显式放行或模拟时使用write_guard(action=policy),审计记录使用write_guard(action=audit)。 - On
probe_unavailableorconnection_lost, userecover_session. Aprobe_busyerror means another process owns the probe.target_unreachable,debug_auth_required, andinvalid_target_configneed changed conditions, not an identical retry. / 遇到probe_unavailable或connection_lost使用recover_session;probe_busy表示探针被占用。target_unreachable、debug_auth_required和invalid_target_config需要改变条件,不能同参重试。 - ST-Link SWD is exclusive. Do not start a second OpenOCD/GDB while a session is
active. Reset with
reset_target. The ST-Link virtual COM port is a separate endpoint and can coexist with SWD. / ST-Link SWD 是独占连接。 会话活跃时不要启动第二个 OpenOCD/GDB;使用reset_target复位。ST-Link 虚拟串口是独立端点,可与 SWD 共存。 - Follow
suggested_next_actions. Reach hidden tools withcall, inspect schemas withtool_help, and report an apparent MCP defect withreport_issue. / 遵循suggested_next_actions;用call调用隐藏工具、用tool_help查询 schema, 疑似 MCP 缺陷使用report_issue。
Bring-up from ELF / 从 ELF 启动调试
Use the profile as the single source of truth. A one-round-trip recipe is:
以调试 profile 作为唯一事实源。单轮往返配方:
batch(steps=[
{"tool": "debug_config", "args": {"action": "load", "path": "mcp/board.yaml"}},
{"tool": "start_debug_session", "args": {}},
{"tool": "self_check", "args": {}}
], stop_on_error=true)
If no config exists, call detect_probe, then obtain validated OpenOCD arguments with
suggest_server_args, start the session, run self_check, and set
debug_profile(action=set, mcu=..., elf_path=..., svd_path=...). Auto-selection is allowed
only for one detected probe. Only call flash_and_run after flashing is explicitly intended.
若没有配置文件,先调用 detect_probe,再用 suggest_server_args 获取已验证的 OpenOCD 参数,
启动后立即 self_check,再设置 MCU、ELF 和 SVD profile。只有检测到唯一探针时才允许自动选择;
只有明确要烧录时才调用 flash_and_run。
See / 参见:scenarios/bringup.json。
HardFault or crash / HardFault 或崩溃
- Break on
HardFault_Handler(or the relevant handler), thenrun_and_wait; if the target is already faulted, halt it. / 在HardFault_Handler或对应处理函数设置断点并运行;若目标已故障则直接暂停。 - Run
reconstruct_fault_context. It decodes fault registers, selects MSP/PSP through EXC_RETURN, reconstructs the stacked frame, recovers the true faulting PC, and resolves it tofile:line. / 运行reconstruct_fault_context:解码故障寄存器,通过 EXC_RETURN 选择 MSP/PSP, 重建异常栈帧并把真实故障 PC 解析到源码行。 - Inspect
frame(action=source),frame(action=variables), andread_call_stackaround that PC. Explain the root cause from evidence, not only the handler location. / 围绕该 PC 检查源码、局部变量和调用栈;根因必须来自证据,不能只报告处理函数位置。
See / 参见:scenarios/hardfault.json。
Hang or livelock / 卡死或活锁
- If running, call
halt_execution, thencapture_stateandread_call_stack. / 若目标仍运行,先暂停,再采集状态和调用栈。 - For RTOS firmware, use
snapshot(scope=rtos)andread_freertos(what="tasks"); inspect queues, mutexes, and heap for blockers. / RTOS 固件使用snapshot(scope=rtos)和任务列表,并检查队列、互斥量和堆。 - Use
sample_pcfor a non-intrusive, symbolized PC hot-spot histogram. A highunsampleablecount usually means the target is halted or asleep. / 使用sample_pc获取非侵入式符号化热点;unsampleable很高通常表示目标暂停或休眠。 - For SWO text, run
setup_swo(hclk_hz=<actual HCLK>), thenlogging(action=start, channel="swo", file="swo_itm.log"). / SWO 文本先按实际 HCLK 配置setup_swo,再启动 SWO 日志。
Stack overflow / 栈溢出
A large local buffer or deep recursion can drive SP below the stack limit and later cause a stacking fault. Do not single-step blindly.
大局部数组或深递归会让 SP 越过栈边界,并在之后触发压栈故障。不要盲目单步。
- Orient with
inspect_project, load the ELF, and find likely functions usinginspect_symbol(what=functions, regex="Flash|Write|Read"). / 用项目检查、ELF 符号和函数搜索定位可疑函数。 - Catch
HardFault_Handler, or set a write watchpoint at the stack limit to stop at the overflow moment. / 捕获 HardFault,或在栈边界设置写 watchpoint 以抓住越界瞬间。 - Reproduce the operation, then run
analyze_stack(stack_size=<map value>). A breakpoint at function entry may stop before the prologue allocates the local array; break inside the function or step past the prologue. / 复现后按 map 中的栈大小运行analyze_stack。函数入口断点可能停在栈帧分配前, 应在函数内部断下或越过 prologue。 - Confirm with
reconstruct_fault_context(STKERR/MSTKERR),read_call_stack, and FreeRTOS stack high-water marks. / 用故障标志、调用栈和 FreeRTOS 栈余量交叉确认。 - Move large buffers to static storage or increase the proven stack budget, rebuild, flash with approval, and rerun the saved scenario. / 将大缓冲区移到静态存储或增加有依据的栈预算;经批准后重建烧录并回放场景。
See / 参见:scenarios/stack_overflow.json。
Peripheral not working / 外设不工作
Most dead peripherals reduce to clock, pin mux, or control-register configuration.
大多数外设失效可归结为时钟、引脚复用或控制寄存器配置。
- Load the profile SVD so registers decode by name. / 加载 profile 中的 SVD。
- Check the RCC enable bit first. A clock-gated peripheral often reads zero and cannot accept configuration. / 先检查 RCC 使能位;时钟关闭时外设通常读零且配置不生效。
- Check GPIO
MODERandAFRL/AFRHagainst the intended pin and AF number. / 核对 GPIO 模式、引脚和 AF 编号。 - Decode the peripheral control/status registers and compare baud, prescaler, enable, and status fields with the intended setup. / 解码外设控制/状态寄存器,并核对波特率、分频、使能和状态字段。
See / 参见:scenarios/peripheral_check.json。
Heap exhaustion or leak / 堆耗尽或泄漏
- For FreeRTOS, run
read_freertos(what="heap"); near-zero minimum-ever-free bytes prove that exhaustion occurred. / FreeRTOS 使用堆检查;历史最小剩余空间接近零可证明曾发生耗尽。 - Trend a free-byte counter with
run_for_duration(..., sample={...}). A monotonic decline under a repeatable workload is leak evidence. Use SWO/ring-buffer telemetry if running-target reads disturb timing. / 在可重复负载下采样空闲字节;单调下降是泄漏证据。若调试器读取影响时序,改用 SWO 或环形缓冲。 - Trap allocator/free calls or watch the free-heap counter to locate unmatched allocations. / 在分配/释放点断下,或 watch 空闲堆计数以定位未配对分配。
See / 参见:scenarios/heap_check.json。
Assert or configASSERT / 断言触发
Break on assert_failed, __aeabi_assert, vAssertCalled, or the project's
configASSERT target. Run to it, inspect frame(action=variables) for file/line/expression,
then use read_call_stack to find the caller.
在项目实际使用的断言处理函数上设置断点,命中后读取 file/line/expression 参数,再通过调用栈定位调用者。
See / 参见:scenarios/assert_check.json。
Minimal reproducible logic bug / 最小化复现逻辑故障
- Use
debug_until(location="fn", condition="state == BAD")to set the hypothesis trap, run, and return decoded context in one call. / 用debug_until一次完成假设断点、运行和上下文采集。 - Save the sequence as
run_scenariosteps and export a sanitized report withexport_debug_report. / 将序列保存为可回放场景,并导出脱敏报告。
Verify the fix / 验证修复
Use expressions(action=compare) or expressions(action=assert) and replay the same
scenario. Do not rely on visual inspection alone.
使用表达式比较/断言并回放同一场景;不要只凭肉眼判断。
Determinism and evidence / 可复现性与证据
Every tool call is journaled. Review get_session(view="timeline") or
get_session(view="metrics"), then use export_debug_report for a shareable,
sanitized artifact.
所有工具调用都会记入日志。通过 timeline/metrics 复核过程,再导出可共享且已脱敏的报告。
Reference / 参考
reference/tool-map.md: tools grouped by purpose / 按用途整理的工具索引scenarios/*.json: replayable templates / 可回放场景模板