CLion OpenOCD CMSIS-DAP 配置记录本文档针对当前工程stm32_px4_rtos目标板为STM32F103调试器为ATK-HS-V3-CMSIS-DAP。1. 先说结论这个调试器不是按 OpenOCD 0.11 默认偏好的 bulk 端点工作而是走 HID 端点。因此有两个关键点OpenOCD 建议使用0.12.0或更高版本。配置里必须显式指定cmsis_dap_backend hid。本工程已经提供了可直接使用的 OpenOCD 配置文件openocd/stm32f103-cmsis-dap.cfg内容如下source [find interface/cmsis-dap.cfg] cmsis_dap_vid_pid 0x04d8 0x00df cmsis_dap_backend hid transport select swd adapter speed 1000 source [find target/stm32f1x.cfg]2. 当前工程里的关键路径OpenOCD 配置文件openocd/stm32f103-cmsis-dap.cfg调试 ELFbuild/Debug/stm32_px4_rtos.elfCMake presetDebugGDBarm-none-eabi-gdb先构建cmake--presetDebug cmake--build--presetDebug3. 安装 OpenOCD3.1 不建议继续用 0.11.0如果你看到下面这种情况基本就是版本太老Error: unable to find a matching CMSIS-DAP device或者invalid command name cmsis_dap_backend这说明当前 OpenOCD 版本太旧不能正确处理这个 HID 型 CMSIS-DAP 设备。3.2 Ubuntu 不同版本的区别针对ATK-HS-V3-CMSIS-DAP这类 HID 型 CMSIS-DAPUbuntu 版本的关键区别主要是系统仓库里的 OpenOCD 版本。根据 Ubuntu 包信息Ubuntu 20.04 Focalopenocd 0.10.0-6build1Ubuntu 22.04 Jammyopenocd 0.11.0-1Ubuntu 24.04 Nobleopenocd 0.12.0-1build2结论可以直接这么看Ubuntu 20.04太旧不建议直接用系统包。Ubuntu 22.04默认还是0.11.0大概率会卡在你现在这个问题上。Ubuntu 24.04系统仓库通常已经是0.12.0多数情况下直接apt install openocd就够了。对这块 DAP 来说真正的分界线不是 Ubuntu 名字本身而是 OpenOCD 有没有到0.12.0以及配置里有没有cmsis_dap_backend hid。3.3 依赖安装sudoaptupdatesudoaptinstallbuild-essential libtool pkg-config autoconf automake texinfo\libusb-1.0-0-dev libhidapi-dev libftdi1-dev libcapstone-dev\libjaylink-dev libgpiod-dev3.4 用本工程脚本安装本工程已经提供了安装脚本tools/install_openocd_0.12.0.sh脚本默认行为安装版本v0.12.0安装目录$HOME/.local/openocd源码缓存目录$HOME/.cache/openocd-src自动安装依赖自动下载源码、编译并安装直接执行cd/home/sg/SG/stm32_px4_rtos_db ./tools/install_openocd_0.12.0.sh安装完成后OpenOCD 在这里$HOME/.local/openocd/bin/openocd检查版本$HOME/.local/openocd/bin/openocd--version如果想让 CLion 和终端都优先使用这个版本可以把它加到PATHexportPATH$HOME/.local/openocd/bin:$PATH如果要长期生效把上面这行追加到~/.bashrc。3.5 脚本的常见用法3.5.1 默认安装./tools/install_openocd_0.12.0.sh3.5.2 指定安装目录INSTALL_PREFIX$HOME/opt/openocd-0.12.0./tools/install_openocd_0.12.0.sh3.5.3 指定国内镜像或自定义下载地址OPENOCD_ARCHIVE_URLhttps://ghproxy.com/https://github.com/openocd-org/openocd/releases/download/v0.12.0/openocd-0.12.0.tar.gz\./tools/install_openocd_0.12.0.sh3.5.4 指定其他版本OPENOCD_VERSIONv0.12.0./tools/install_openocd_0.12.0.sh这个脚本虽然名字写的是0.12.0但它本身支持通过环境变量覆盖版本号。3.6 脚本安装后怎么用安装完成后推荐直接用脚本安装出来的 OpenOCD 跑本工程配置$HOME/.local/openocd/bin/openocd\-f/home/sg/SG/stm32_px4_rtos_db/openocd/stm32f103-cmsis-dap.cfg烧录当前工程$HOME/.local/openocd/bin/openocd\-f/home/sg/SG/stm32_px4_rtos_db/openocd/stm32f103-cmsis-dap.cfg\-cprogram /home/sg/SG/stm32_px4_rtos_db/build/Debug/stm32_px4_rtos.elf verify reset exitCLion 里如果不想依赖系统自带的旧版本OpenOCD executable就填/home/sg/.local/openocd/bin/openocd3.7 手动源码编译如果你是git clone下来的源码不要跳过子模块和bootstrapgitsubmodule update--init--recursive./bootstrap ./configure --enable-cmsis-dapmake-j$(nproc)sudomakeinstall安装后检查版本openocd--version建议至少是0.12.0。3.8 国内网络慢时如果 GitHub 很慢可以换成这两种思路用镜像仓库拉取源码再执行同样的submodule、bootstrap、configure、make。直接下载 release 源码压缩包再在解压目录里执行./bootstrap、./configure --enable-cmsis-dap、make。注意如果只执行了./configure但没先跑./bootstrap通常会缺jimtcl。如果是git clone的源码但没拉子模块也会在configure阶段失败。如果你已经用了本工程的tools/install_openocd_0.12.0.sh优先给它传OPENOCD_ARCHIVE_URL比手动折腾更省事。4. Linux 下权限如果 OpenOCD 已经升级但普通用户仍然打不开 USB 设备再加 udev 规则。ATK-HS-V3-CMSIS-DAP的 VID/PID 是04d8:00df。sudotee/etc/udev/rules.d/99-openocd.rulesEOF SUBSYSTEMusb, ATTR{idVendor}04d8, ATTR{idProduct}00df, MODE666 EOFsudoudevadm control --reload-rulessudoudevadm trigger重新插拔调试器后再试。4.1 这次实际遇到的问题被mcp2200错绑这次排查里真正的根因不是OpenOCD 语法写错板子没插好cmsis_dap_backend hid没配置而是 Linux 把ATK-HS-V3-CMSIS-DAP的 HID 接口错误地绑定到了mcp2200驱动。现象是lsusb能看到设备04d8:00df Microchip Technology, Inc. ATK-HS-V3-CMSIS-DAPOpenOCD 0.12.0 也已经安装好了。配置文件里也已经显式写了cmsis_dap_vid_pid 0x04d8 0x00df cmsis_dap_backend hid但仍然报Error: unable to find a matching CMSIS-DAP device继续往下查/sys/bus/hid/devices后可以看到类似DRIVERmcp2200 HID_NAMEATK ATK-HS-V3-CMSIS-DAP这说明系统把这个设备当成了MCP2200相关设备而不是交给hid-generic。4.2 为什么会这样ATK-HS-V3-CMSIS-DAP的 USB VID/PID 是VID:04d8PID:00df其中04d8是 Microchip 的厂商 ID。Linux 内核里的mcp2200/hid_mcp2200驱动会匹配到这类设备于是把这只本来应该给OpenOCD cmsis-dap hid使用的 HID 接口抢走。一旦被它抢走会出现两个直接后果OpenOCD虽然能在lsusb层面看到设备但无法把它当成 CMSIS-DAP HID 正常打开。设备不会按预期暴露为hidraw供用户态调试工具访问或者即使暴露流程存在也不是OpenOCD想要的那条路径。所以这个问题的本质不是“OpenOCD 不支持正点原子”而是“Linux 把正点原子这只 DAP 绑到了错误驱动上”。4.3 怎么确认是不是这个问题先查 USB 是否存在lsusb|grep04d8:00df如果能看到ATK-HS-V3-CMSIS-DAP再查 HID 设备绑定到了谁udevadm info-qproperty-p/sys/bus/hid/devices/0003:04D8:00DF.xxxx或者自动找fordin/sys/bus/hid/devices/*;doif[-f$d/modalias]grep-qv000004D8p000000DF$d/modalias;thenechoHID node:$(basename$d)udevadm info-qproperty-p$dfidone如果输出里有DRIVERmcp2200那就说明已经命中这个问题。4.4 临时解决方案先把错误驱动解绑再强制改用hid-generic。本工程已经提供了脚本tools/fix_atk_dap_hid_binding.sh它会自动查找当前04D8:00DF的 HID 节点如果当前驱动是mcp2200先解绑优先通过driver_override强制绑定hid-generic打印当前驱动和hidraw节点执行cd/home/sg/SG/stm32_px4_rtos_db ./tools/fix_atk_dap_hid_binding.sh修复后再测试./tools/openocd.sh-fopenocd/stm32f103-cmsis-dap.cfg4.5 手动修复命令如果你不想走脚本可以手工执行。建议用自动发现 HID 节点的方式而不要手写.0019、.001B这类编号因为它每次重插都可能变化。HID_ID$(fordin/sys/bus/hid/devices/*;do[-f$d/modalias]grep-qv000004D8p000000DF$d/modaliasbasename$dbreakdone)echoHID_ID$HID_IDsudobash-c if [ -e /sys/bus/hid/drivers/mcp2200/\$HID_ID]; then echo \$HID_ID /sys/bus/hid/drivers/mcp2200/unbind fi echo hid-generic /sys/bus/hid/devices/\$HID_ID/driver_override echo \$HID_ID /sys/bus/hid/drivers_probe 然后检查readlink-f/sys/bus/hid/devices/$HID_ID/driverfind/sys/bus/hid/devices/$HID_ID-maxdepth3-typed-namehidraw*预期结果驱动从mcp2200变成hid-generic能看到对应的hidraw节点4.6 永久解决方案如果确认这只 DAP 长期都应该给 OpenOCD 使用而不是给mcp2200驱动使用那么更稳妥的做法是直接禁止这个错误驱动自动抢占。可以先临时卸载sudomodprobe-rhid_mcp2200如果确认没有副作用再做永久黑名单echoblacklist hid_mcp2200|sudotee/etc/modprobe.d/blacklist-hid_mcp2200.confsudoupdate-initramfs-u然后重新插拔 DAP或者重启。4.7 这个修复会不会影响烧录不会直接影响目标板STM32 / PX4的 Flash 内容。这里修复的是主机侧 Linux 对ATK-HS-V3-CMSIS-DAP这只调试器的驱动绑定不是目标板上的固件OpenOCD 的烧录数据STM32 的 Flash 内容需要注意的是这个探针本身同时还带有别的 USB 接口例如cdc_acm虚拟串口接口HID 接口这次处理的只是其中的 HID 接口让它回到CMSIS-DAP应该走的hid-generic路径。对 SWD 烧录/调试是修复不是破坏。4.8 推荐排查顺序针对ATK-HS-V3-CMSIS-DAP推荐按这个顺序排查openocd --version是否已经到0.12.0配置里是否显式写了cmsis_dap_backend hidlsusb | grep 04d8:00df是否能看到设备是否加过 udev 权限规则/sys/bus/hid/devices/...当前驱动是不是mcp2200很多时候第 1 到第 4 步都没问题最后仍然失败真正原因就是第 5 步。5. 命令行验证先确认设备在线lsusb应能看到类似ID 04d8:00df Microchip Technology, Inc. ATK-HS-V3-CMSIS-DAP再直接用本工程的配置文件测试openocd-fopenocd/stm32f103-cmsis-dap.cfg如果只是想烧录当前 Debug ELFopenocd-fopenocd/stm32f103-cmsis-dap.cfg\-cprogram build/Debug/stm32_px4_rtos.elf verify reset exit6. 在 CLion 里配置下面按本工程实际路径来填。6.1 Toolchain / CMake先确保 CLion 能正常构建工程打开Settings | Build, Execution, Deployment | ToolchainsC Compiler / C Compiler 走你的 ARM 工具链GDB 填arm-none-eabi-gdb打开Settings | Build, Execution, Deployment | CMake选择Debugpreset或者保证构建目录为build/Debug如果build/Debug/stm32_px4_rtos.elf没生成后面的调试配置都不会工作。6.2 推荐方式用 OpenOCD 作为 GDB Server在 CLion 新建一个基于 OpenOCD 的嵌入式调试配置核心信息如下Executable / Binary$ProjectFileDir$/build/Debug/stm32_px4_rtos.elfGDBarm-none-eabi-gdbOpenOCD executable你的openocd可执行文件路径OpenOCD arguments-f $ProjectFileDir$/openocd/stm32f103-cmsis-dap.cfg如果界面里有这些选项建议同时开启Download executableReset / Halt after connect调试时的典型流程是CLion 先启动 OpenOCDOpenOCD 加载openocd/stm32f103-cmsis-dap.cfgGDB 连接 OpenOCD下载build/Debug/stm32_px4_rtos.elf在main或断点处停住6.3 如果你的 CLion 没有现成 OpenOCD 模板可以退一步用“手动启动 OpenOCD GDB Remote Debug”的方式先在终端启动openocd-f/home/sg/SG/stm32_px4_rtos_db/openocd/stm32f103-cmsis-dap.cfg然后在 CLion 里建一个远程 GDB 调试配置Symbol file/home/sg/SG/stm32_px4_rtos_db/build/Debug/stm32_px4_rtos.elfGDBarm-none-eabi-gdbTarget remotelocalhost:3333常用初始化命令可填monitor reset halt load monitor reset halt7. 推荐的 CLion 调试参数如果 CLion 支持 GDB 启动命令常用这一组就够了monitor reset halt load monitor reset halt开始运行时continue如果只想连接不重新下载程序可以去掉load。8. 常见报错对照8.1unable to find a matching CMSIS-DAP device优先检查OpenOCD 是否还是0.11.0配置里是否缺了cmsis_dap_backend hidlsusb是否能看到04d8:00df是否用了错误的接口文件比如把 CMSIS-DAP 当成 ST-Link8.2invalid command name cmsis_dap_backend说明 OpenOCD 太旧升级到0.12.0。8.3jimtcl is required but not found说明源码构建步骤不完整通常是没执行git submodule update --init --recursive没执行./bootstrap9. 本工程建议这个工程里建议统一使用OpenOCD 配置openocd/stm32f103-cmsis-dap.cfg调试 ELFbuild/Debug/stm32_px4_rtos.elfGDBarm-none-eabi-gdb不建议继续使用根目录那个daplink.cfg作为主配置文件因为它当前内容不适合这个 STM32F103 工程也没有显式处理ATK-HS-V3的 HID 后端。