STM32 DAPLink Debug Setup（STM32 调试环境配置）
概述
在 Windows 的 VS Code / CodeBuddy 中配置并排障 STM32 调试工具链：DAPLink（CMSIS-DAP）仿真器 +
OpenOCD + Cortex-Debug，并处理最常见的影响调试体验的两个设置问题（灰色参数名内联提示、
因优化导致无法下断点的代码行）。
本技能附带可直接复制的模板（assets/）与深入的排障手册（references/troubleshooting.md）。
快速开始
按顺序执行检查清单；工程中已有的步骤先核实再跳过，不要凭空假设。
- 确认芯片型号、调试接口（SWD 引脚）与 ELF 输出路径。
- 配置 DAPLink + OpenOCD → 见 任务 1
- 关闭内联参数提示 → 见 任务 2
- 让 Debug 构建可断点（-O0）→ 见 任务 3
任务 1 — 配置 DAPLink + OpenOCD
把 assets/openocd.cfg 复制到工程根目录，把 assets/vscode/launch.json +
assets/vscode/tasks.json 复制到工程的 .vscode/ 目录，然后按需修改：
| 占位内容 | 含义 |
|---|---|
${workspaceFolder} |
VS Code 内置变量，保持原样 |
<CHIP> |
例如 STM32F103RET6；按系列修改 openocd.cfg 的目标文件（target/stm32f1x.cfg、stm32f4x.cfg 等） |
<ELF> |
编译产物 ELF 的相对路径，例如 build/Debug/app.elf |
| openocd / gdb 路径 | 模板默认写裸命令名（依赖 PATH）；探测不到时按 工具路径探测 一节找到后填绝对路径 |
一键"编译 → 烧录 → 运行"
assets/vscode/tasks.json 的 Build and Flash (run) 任务即此模式，已实测可用：
dependsOn: "Build (Debug)"先自动编译，随后program <ELF> verify reset exit烧录；verify校验通过后reset复位芯片，目标直接开始运行，无需手动操作；- 任务已设
"group": { "kind": "build", "isDefault": true }，按Ctrl+Shift+B即一键
编译+烧录+运行；命令面板Tasks: Run Build Task等效； - 仅编译的任务（
Build (Debug)）保留但不再占用默认 build 组。
以下是真实故障中总结的硬性规则，不要违反：
- 所有 OpenOCD 任务必须用
"type": "process"+args数组。 用"type": "shell"时，
PowerShell（pwsh -Command）会吃掉-c "program x.elf verify reset exit"的引号，
OpenOCD 会报Unexpected command line argument: <elf>。 - 优先依赖 PATH 探测，探测不到再用绝对路径。 模板先用裸命令名引用
openocd/
arm-none-eabi-gdb。VS Code 缓存的是编辑器启动时的环境快照，之后才安装或加入PATH
的工具在它的终端里不可见（即使新开的系统 PowerShell 能找到）。此时要么重启 VS Code，
要么按 工具路径探测 一节定位后把绝对路径填进launch.json（serverpath/gdbPath）
和tasks.json（command）。 - 编辑器/工具进程找不到、但用户终端里能跑时，读注册表 PATH。 编辑器派生的进程拿到
的是过期 PATH 快照，且 OpenOCD 可能被装在非常规位置（实战案例：
D:\sys\zhuomian\ODrive\openocd-v0.12.0-i686-w64-mingw32\bin\openocd.exe，为 ODrive
项目装的，常规目录搜索全部落空）。此时直接读注册表里最新的用户/系统 PATH 逐目录命中，
见 工具路径探测 第 3 步。 - 仿真器的 NRST 未接线时必须用
reset_config none。 若配置成
reset_config srst_only srst_nogate connect_assert_srst且 NRST 没接，
reset halt会报Error: timed out while waiting for target halted。 - 不要在
program ... reset exit之后追加其他-c命令 —— OpenOCD 在exit处已
关闭，后面的命令静默不执行。烧录与探测分两次调用。 adapter speed从 1000 起步，连接稳定后再提高（4000~10000）。- 国产兼容芯片（CKS32、APM32 等）IDCODE 不同，放开
set CPUTAPID 0x2ba01477。
写代码前先验证配置：
& "<openocd>" -f openocd.cfg -c "exit"
预期输出：Cortex-M3 r1p1 processor detected、starting gdb server ... on 3333，
且没有 timed out while waiting for target halted。
然后烧录：
& "<openocd>" -f openocd.cfg -c "program <ELF> verify reset exit"
预期输出：** Programming Finished ** / ** Verified OK ** / ** Resetting Target **。
任务 2 — 关闭内联参数提示（Inlay Hints）
实参前插入的灰色 GPIOx: / GPIO_Pin: 文字是 Inlay Hint（内联提示），由 clangd
语言服务器渲染，只影响显示、不影响编译。
加到工程的 .vscode/settings.json（想对所有工程生效则加到用户设置）：
// off（关闭）| on（开启）| offUnlessPressed（按住 Ctrl+Alt 时显示）
"editor.inlayHints.enabled": "off"
editor.inlayHints.enabled 是编辑器级总开关，与具体语言服务器无关。若提示仍在，
执行 Developer: Reload Window。
若使用微软 C/C++ 扩展（cpptools）而非 clangd，用它自己的开关：
C_Cpp.inlayHints.parameters.enabled、C_Cpp.inlayHints.autoDeclarationTypes.enabled、
C_Cpp.inlayHints.functionLikeReturnTypes.enabled。
任务 3 — 让 Debug 构建可断点（-O0）
症状：在一条看起来很普通的语句上下断点，断点被静默挪到函数的收尾大括号处。
原因：该语句没有 DWARF 行表条目——编译器把它当作死代码删除了。典型触发场景：
值赋给局部变量后用 (void)val; 丢弃；优化等级高于 -O0（-Og 就足够触发）。
修改工具链文件（如 cmake/starm-clang.cmake、cmake/gcc-arm-none-eabi.cmake）：
set(CMAKE_C_FLAGS_DEBUG "-O0 -g3") # 原为 "-Og -g3"
set(CMAKE_CXX_FLAGS_DEBUG "-O0 -g3")
然后重新编译并重新烧录 —— 调试器从 ELF 里读行表，ELF 是旧的断点位置就是旧的。
用行表确认修复效果：
$od = "<arm-none-eabi-objdump>"
$out = & $od --dwarf=decodedline <ELF>
# 收集目标源文件 CU 的 (行号 -> 地址) 条目
凡是能下断点的行都会有自己的地址。注意 (void)val; 这类空语句在任何优化等级下都
不产生指令，其断点永远顺延到下一行。
想让某个值在任何优化等级下都可观察，把它存到文件作用域的 volatile 变量，而不是
被丢弃的局部变量：
volatile uint32_t adc1_val;
工具路径探测
模板用裸命令名（openocd、arm-none-eabi-gdb、cmake、ninja）引用工具并依赖
PATH。先在目标机器上定位工具，然后：把目录加入 PATH（推荐，之后重启 VS Code），
或把绝对路径填入 launch.json（serverpath / gdbPath / 可选 svdFile）、
tasks.json（command）。
# 1) 已在 PATH 中 → 无需处理，裸命令名直接可用
Get-Command openocd, arm-none-eabi-gdb, cmake, ninja -ErrorAction SilentlyContinue
# 2) 不在 PATH → 搜索常见安装位置
Get-ChildItem "C:\Program Files", "C:\Program Files (x86)", "C:\openocd", "$env:USERPROFILE" `
-Recurse -Depth 4 -Filter openocd.exe -ErrorAction SilentlyContinue |
Select-Object -ExpandProperty FullName
# 3) 用户终端里能跑、但常规位置搜不到 → 读注册表里最新的用户/系统 PATH
# （编辑器进程的 PATH 快照可能过期，注册表里才是当前真实值）
$dirs = ([Environment]::GetEnvironmentVariable('Path','User') + ';' +
[Environment]::GetEnvironmentVariable('Path','Machine')).Split(';') |
Where-Object { $_ }
$dirs | ForEach-Object {
$p = Join-Path $_ 'openocd.exe'
if (Test-Path $p) { $p }
}
ST 工具链 gdb 的典型位置（STM32CubeMX CMake / st-arm-clang 工程，可直接填 gdbPath）：
%USERPROFILE%\AppData\Local\stm32cube\bundles\gnu-gdb-for-stm32\<版本>\bin\arm-none-eabi-gdb.exe
值得直接检查的固定位置：
| 工具 | 常见位置 |
|---|---|
| OpenOCD (xPack) | ~\AppData\Roaming\xPacks\openocd\*\bin\openocd.exe |
| OpenOCD (PlatformIO) | ~\.platformio\packages\tool-openocd\bin\openocd.exe |
| OpenOCD (手动解压) | 任意位置，如 D:\tools\openocd\bin\openocd.exe |
| GNU ARM 工具链（gdb/objdump） | 工具链的 bin\ 目录 |
| ST 自带工具链 | ~\AppData\Local\stm32cube\bundles\{st-arm-clang,ninja,cmake,gnu-gdb-for-stm32}\<版本>\bin |
| CMSIS-SVD 文件 | ~\AppData\Local\stm32cube\packs\STMicroelectronics\<dfp>\<版本>\SVD\ |
CMSIS-SVD 等）的绝对路径可直接填入上述位置。
构建时若 shell 的 PATH 缺编译工具链，临时补上缺失的目录：
$env:Path = "<st-arm-clang>\bin;<ninja>\bin;" + $env:Path
cmake --build build/Debug
资源
assets/openocd.cfg— DAPLink + STM32 的 OpenOCD 模板（含排障注释）assets/vscode/launch.json— Cortex-Debug 启动配置（servertype: openocd）assets/vscode/tasks.json— 编译 / 烧录 / 擦除 / 服务器任务（type: process）references/troubleshooting.md— STM32 HAL 中断陷阱与修复方法
