开篇先讲个真实场景。我用WSL2做STM32的C开发平时编译、链接、看反汇编全在Linux侧完成顺手得很。直到有一天我写好一段新的串口驱动准备把它烧进板子验证插上ST-Link和开发板Windows那边弹出设备已就绪WSL里执行lsusb却一片空。那一瞬间脑子里就三个字我板子呢后来把整个折腾过程理顺了才发现WSL里烧录STM32其实不复杂只是需要先绕过一个核心障碍——WSL2默认根本不给你直通USB设备。这篇文章就把这套完整方案写清楚从原理到踩坑给同样在WSL里做嵌入式开发的人一条能直接走通的路。1. 先搞清楚你的板子去哪了WSL的设备隔离机制1.1 WSL2为什么看不见USB设备很多人第一次在WSL里插开发板最直观的困惑是Windows上明明识别到了设备WSL里却什么都看不到。这不是驱动问题也不是板子坏了而是WSL2的架构导致的。WSL2跑在一个轻量级虚拟机里通过虚拟网络和宿主机通信。这个虚拟机默认没有挂载任何USB控制器所以你在物理机上插的USB设备对WSL2来说就像插在另一台电脑上一样完全不可见。你可以在WSL里执行ls /dev/ttyUSB*、lsusb结果都是空的——不是命令打错而是设备根本没进到这个系统里。WSL1倒是没有这个问题因为WSL1是系统调用翻译层设备文件直接映射USB串口能直接用。但WSL1不支持真正的Linux内核很多嵌入式编译链、性能敏感的工具跑起来不方便。我早期图省事用WSL1后来编译一个带模板元编程的C项目编译速度实在难受就彻底迁到WSL2了。迁完之后要烧程序就撞上了USB设备不可见这堵墙。解决思路其实很朴素既然WSL2是虚拟机那就让宿主机把USB设备让给这个虚拟机。这个让的动作行业里叫USB设备透传WSL2生态里最通用的实现方式是USB/IP协议配合usbipd-win。1.2 先自查用lsusb和dmesg确认环境在动手改方案之前我建议你花两分钟做一次环境自查确认问题到底出在哪层。步骤就三步在WSL里跑lsusb看有没有任何USB设备列表。如果输出空说明设备确实没透传进来。在WSL里跑dmesg | grep -i usb看内核有没有识别到USB控制器。WSL2默认会有一个虚拟的USB控制器但通常没有任何设备挂上去。在Windows的PowerShell里跑usbipd list这一步需要你装好usbipd-win之后才能用它能列出宿主机上所有USB设备的总线ID和连接状态。我当时做完这三步结论非常清晰Windows里ST-Link状态正常总线ID是1-4设备名显示为STMicroelectronics STLink DongleWSL里lsusb干干净净——问题就出在透传环节。还有个值得留意的点如果你用的是串口模块比如CH340或CP2102转出来的USB转串口即便不透传WSL2里也能通过一些间接手段访问但稳定性很差。做嵌入式开发尤其涉及SWD调试、复位、读取芯片ID这类操作必须走USB透传把调试器完整送进WSL不能只想着通个串口就完事。2. 方案选型把USB设备透传进WSL的几条路2.1 主力方案usbipd-win的USB/IP转发当前WSL2下访问USB设备最成熟的方案是微软官方在README里推荐的usbipd-win。它做的事情本质上是利用USB/IP协议把宿主机上的某个USB设备共享出来再让WSL2这个虚拟机把设备接进去。名字听着复杂用起来逻辑很清楚宿主机上选定一个设备执行绑定然后WSL里执行连接设备就从Windows侧拔出去、在Linux侧插进来。绑定的粒度是设备级不是接口级所以对于ST-Link这种复合设备既有调试接口又有虚拟串口透传后两边功能在Linux里都会可见调试和串口监视可以同时做。我遇到过一个问题需要提前说明绑定某个设备后Windows侧会立即失去这个设备。如果你习惯了在Windows的CubeProgrammer里烧录绑定的瞬间那个工具会直接报设备丢失。这不是故障而是设备被移交了。反过来在WSL里断开之后Windows侧又恢复正常。所以习惯上你要决定某一时间段设备归Windows还是归WSL不能两边同时抢。2.2 备选方案WSL1直连与串口转接如果你只是偶尔烧个程序不想装usbipd-win有两条备选路线。第一条是切回WSL1。WSL1对串口设备可以直接访问最常见的就是接CH340模块的串口在WSL1里能看到/dev/ttyUSB0。但WSL1跑不了OpenOCD这种依赖完整内核驱动能力的程序吗其实OpenOCD在WSL1里也能跑但坑不少。比如WSL1缺少完整的USB HID访问语义ST-Link的SWIM模式、JTAG时序在某些版本上会有兼容性问题是能用但不稳定的状态。加上WSL1的编译性能确实拉胯我不建议为了烧录单独维护一个WSL1发行版。第二条是走串口层面不碰USB。有些板子自带串口下载模式比如通过BOOT引脚进入系统Bootloader你可以把它当成一个串口设备处理。但这条路和SWD调试相比信息量少太多只能烧固件不能调试出了问题你没法在线看寄存器、打断点体验打折扣。所以我的结论很直接既然都做到系列第7篇了说明你已经投入精力在WSL里搭嵌入式C工具链那USB透传是绕不开的必修课直接上usbipd-win一劳永逸。2.3 调试器选型对透传的影响透传方案定了之后调试器本身也会影响体验。我前后用过三种设备原装ST-Link、某宝上的ST-Link V2克隆版以及一个带板载调试器的开发板板上直接焊着ST-Link。原装ST-Link在透传后OpenOCD识别得非常干净命令openocd -f interface/stlink.cfg基本不需要额外参数直接能找到设备。克隆版就麻烦一些它在USB枚举时上报的厂商信息、序列号经常不规范OpenOCD有时会因为设备权限或者描述符解析失败而拒绝连接。解决办法一般是追加上报ID或改udev规则具体我在第4节里展开。板载调试器的情况要特别注意很多开发板的板载ST-Link同时扮演调试器和虚拟串口两个角色透传之后它会作为一个复合设备出现在Linux里通常能看到/dev/ttyACM0和调试器节点两个入口。这种方案实际用起来最舒服因为调试和串口日志不用切换设备都在WSL里完成。3. 实操记录完成一次完整的WSL内烧录STM32流程3.1 宿主机侧安装usbipd-win并绑定ST-Link环境假设Windows 11已装WSL2和一个Ubuntu发行版。第一次做先装usbipd-win。安装方式我推荐用winget。在PowerShell里执行winget install usbipd装完需要管理员权限才能操作设备的绑定和共享所以后面的操作记得用管理员身份的PowerShell。安装完成后先查看当前所有USB设备usbipd list输出会显示类似这样1-4 STMicroelectronics STLink Dongle Not shared 2-2 USB Serial Device Not shared这里1-4是总线IDSTMicroelectronics STLink Dongle是设备描述Not shared表示当前没有共享。注意看设备描述别认错。比如有的CH340串口模块显示USB Serial你如果把串口模块透传进去而调试器留在Windows那就白折腾了。确认设备后先绑定再共享两步可以合成一步usbipd bind --busid 1-4 usbipd attach --wsl --busid 1-4bind的作用是把设备标记为可共享这一步的效果是持久的重启后依然生效。attach才是真正把设备送到WSL里。如果WSL里有多个发行版attach后面要加--distribution参数指定目标发行版。这里有个细节attach执行完并不是永远保持WSL重启之后需要重新执行attach。bind是一次性的attach不是。所以后面我做了脚本来自动处理第3.4节会说。3.2 WSL侧安装usbip客户端与OpenOCD设备从Windows透传过来WSL侧还得有配套的客户端工具否则设备到了门口也进不来。在WSL的终端里执行sudo apt install linux-tools-generic hwdata安装完成后usbip工具通常会被安装到/usr/lib/linux-tools/版本号/usbip但路径不直接暴露在PATH里。每次用都要敲全路径很烦我直接建了个软链接sudo ln -s /usr/lib/linux-tools/*/usbip /usr/local/sbin/usbip这时候在WSL里执行lsusb应该能看到ST-Link了。如果看不到大概率是权限问题或者内核模块没加载排查方法在第4节。接下来装OpenOCD。Ubuntu的软件源里有OpenOCD直接sudo apt install openocd这里有个经验版本别追求新稳定第一。Ubuntu源里的OpenOCD可能不是最新版但对ST-Link V2的支持已经非常成熟新版本在JTAG时序、速度设置上确实有提升但源码编译OpenOCD的依赖多、功耗大如果不是需要新的目标芯片配置用发行版自带版本就够了。我顺手还装了stlink-tools因为有时候只想单纯读个芯片ID或者备份固件没必要启动完整的OpenOCD服务sudo apt install stlink-tools3.3 开始烧录从ELF到开发板环境打通之后烧录这个动作本身反而不复杂。假设你的项目用CMake构建编译产物是一个ELF文件比如build/stm32_fw.elf。先验证OpenOCD能不能看到调试器openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c init; halt解释一下这两行配置interface/stlink.cfg告诉OpenOCD用ST-Link作为调试器target/stm32f4x.cfg告诉它目标芯片是什么型号如果你的芯片是STM32F103那就是stm32f1x.cfg选对应的就行。init; halt让OpenOCD初始化调试链路并在目标芯片复位时立刻暂停防止在篡改Flash时芯片还在跑旧程序。正常情况下OpenOCD会输出类似这样的日志Info : STLINK V2 J17S4 (API v2) VID:PID 0483:3748 Info : Target voltage: 3.3 V Info : clock speed 4000 kHz Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints看到这些说明链路通畅可以烧录了。完整烧录命令openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c program build/stm32_fw.elf verify reset exit这条命令的含义把build/stm32_fw.elf写入芯片Flash写完自动校验然后复位芯片让新固件跑起来最后退出OpenOCD。verify必加它能立刻发现写入错误省得你烧完发现板子没反应还要分心排除是写入问题还是代码问题。如果项目还生成了hex或bin文件也可以用openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c program build/stm32_fw.bin 0x08000000 verify reset exitbin文件没有地址信息必须显式给出烧录地址。STM32的Flash起始地址通常是0x08000000针对的是主Flash区。如果你用的是OTA架构应用程序放后面地址就要对应调整比如从0x08008000开始。3.4 把烧录用脚本固化下来人工敲命令总会敲错而且每次烧录都要开一个终端跑OpenOCD体验比较原始。我把烧录流程固化成了一个脚本flash.sh放在项目根目录下#!/usr/bin/env bash set -euo pipefail BUILD_DIR${BUILD_DIR:-build} TARGET_CFG${TARGET_CFG:-target/stm32f4x.cfg} ELF_FILE${ELF_FILE:-${BUILD_DIR}/stm32_fw.elf} if [ ! -f ${ELF_FILE} ]; then echo [ERROR] ELF file not found: ${ELF_FILE} echo Run cmake --build ${BUILD_DIR} first. exit 1 fi echo [INFO] Starting OpenOCD flash: ${ELF_FILE} openocd -f interface/stlink.cfg \ -f ${TARGET_CFG} \ -c program ${ELF_FILE} verify reset exit把脚本放到/usr/local/bin或者加个alias都行。实测下来配合CMake的ninja构建整个流程就是改代码 → 编译 → 执行./flash.sh→ 看板子跑起来一气呵成。另外一个小技巧每次手动执行usbipd attach很烦我写了一个Windows侧的批处理开机后执行方便快速把调试器让给WSLusbipd attach --wsl --busid 1-4不过在WSL里用到Device TPM等需要设备独占的场景时记得解除attach否则Windows侧程序访问不到设备。4. 常见问题与排查技巧实录4.1 绑定成功后WSL里还是看不到设备这是最让人崩溃的情况Windows侧usbipd list显示AttachedWSL里lsusb却还是空白。第一排查点是内核模块。usbip-client需要加载vhci-hcd模块执行sudo modprobe vhci-hcd如果提示modprobe: FATAL: Module not found说明内核里没有这个模块。WSL2默认内核是微软提供的版本功能裁剪过。解决方式是更新WSL内核或者手动编译一个开启usbip的内核。手动编译内核对于大多数人不现实优先尝试wsl --update把内核升级到最新版再查看是否自带vhci-hcd支持。第二个坑是Windows侧的安全中心拦截了设备重分配。有些设备绑定之后Windows的安全软件会因为设备被移除而触发保护把attach操作回滚。在Windows事件查看器里能看到相关日志。这种情况我遇到一次把安全软件对USB设备的实时保护关掉之后解决具体策略看你用的什么软件这就不展开了。第三个坑在权限。WSL里lsusb能看到设备但OpenOCD打开设备时报权限错误。这个很常见因为设备文件默认属于root用户组。看一眼ls -l /dev/bus/usb/001/如果设备节点是root:root普通用户跑OpenOCD就得加sudo。更优雅的方式是配udev规则见4.4节。4.2 OpenOCD连接调试器报错OpenOCD启动时报Error: open failed或unable to open CMSIS-DAP device多数情况是权限但我还遇到过一次很有意思的情况克隆版ST-Link在透传后USB端口路径发生了变化OpenOCD内部缓存的VID:PID解析失败了。排查步骤先确认WSL侧能看到设备且权限正确lsusb用st-info --probe尝试直接探测如果能读到芯片信息说明ST-Link本身没坏问题出在OpenOCD和调试器的握手环节。如果是克隆版OpenOCD里可以尝试降低连接速度或者在配置里显式指定适配器驱动openocd -f interface/stlink.cfg -c adapter speed 1000; init; halt有些克隆版对高速握手支持不好把1000 kHz降下来握手成功率会高不少。还有一个非常容易被忽略的问题目标板供电不足。ST-Link从USB取电透传后如果USB口经过扩展坞转发供电能力可能跟不上OpenOCD探测时目标电压只有1.8V直接报电压异常。这种情况换一个直连的USB口或者给板子单独供电立刻就能解决。4.3 烧录进去后程序不跑烧录时报verify failed是最直接的问题说明Flash写入数据对不上。常见原因地址写错了。比如给STM32F103烧一个本该从0x08008000启动的带Bootloader程序你直接烧到0x08000000verify大概率失败即便侥幸通过运行也会乱。芯片读保护开启了。STM32有RDPRead Out Protection等级等级一及以上时OpenOCD能连接但无法写入Flash报Cannot access memory。解决方法是先用STM32官方工具或者OpenOCD命令解除保护但注意解除保护通常会擦除整个Flash板子里的Bootloader也没了操作前务必确认。烧录成功但板子没反应优先检查启动方式。以STM32F4为例BOOT0和BOOT1引脚决定从哪里启动。如果两个引脚状态不对芯片可能跳进系统Bootloader而不是你写的Flash程序。用万用表量一下引脚电平或者直接看开发板上的跳线帽位置就能排除掉这个因素。程序跑起来但行为不对这种情况我建议用串口输出加灯闪烁来定位。WSL里直接看/dev/ttyACM0的串口日志很方便用minicom或者screenscreen /dev/ttyACM0 115200透传之后虚拟串口也在WSL里这一步完全不需要回到Windows。4.4 权限与udev规则备忘在WSL里折腾ST-Link不写udev规则的话每次都要sudo非常影响心情。我用的规则文件放在/etc/udev/rules.d/99-stlink.rules内容如下SUBSYSTEMusb, ATTR{idVendor}0483, ATTR{idProduct}3748, MODE06660483是ST-Link的厂商ID3748是常见的ST-Link V2产品ID。克隆版的产品ID可能不同先用lsusb查一下实际的值再写。写完执行sudo udevadm control --reload-rules sudo udevadm trigger加载之后插拔一次设备或重新attach一次普通用户就能直接访问了。顺带提一种更好查的规则思路不要锁死某个产品ID而是针对整个厂商ID开放。做个人开发环境无所谓但如果你在团队共享机器上还是锁具体产品ID比较安全避免误开放其他USB设备权限。5. 后续扩展把烧录整合进自动化流程既然已经能在WSL里烧录了再往前走一步可以把它整合到CI或者一键构建流程里。我在项目里加了一个make flash目标本质上就是调用第3.4节的脚本同时把CMake的构建路径、目标芯片配置统一收口到CMakeLists里add_custom_target(flash COMMAND bash ${CMAKE_SOURCE_DIR}/flash.sh DEPENDS stm32_fw COMMENT Flash firmware via OpenOCD )这样改完代码只需要make flash编译和烧录自动串联写代码的节奏顺畅多了。另一个实用的扩展是版本校验。在烧录前自动读取当前芯片内固件的版本如果固件里烧了版本号存在固定Flash地址和目标版本做对比不一致才烧录。这个改动对量产场景价值更大个人开发时做个简单的目标文件存在性校验就够了。我个人在实际操作中还有一个习惯烧录前总是先看一眼OpenOCD输出的目标电压和芯片ID。电压低于3.0V我不烧芯片ID和配置里不一致我不烧。等过几次因为电压低导致写入异常的情况你就能理解这个习惯了。做嵌入式开发板子事小时间成本事大宁可多花十秒确认也不要盲目操作然后排查半天。最后分享一个小技巧WSL里跑OpenOCD时如果感觉烧录速度慢看看是不是USB透传的链路经过USB 2.0的HubHUB转发会拉低事务速率。把ST-Link插到直连的USB 3.0口烧录一个512KB的固件体感速度能差出一倍。这个差异虽然不是决定性的但每次省下的几秒钟累积起来也是不少时间。