上个项目做到联调阶段遇到一个很憋屈的问题板子上两路USART一路接了4G模组跑AT指令一路接了上位机跑Modbus协议想把调试日志打出来居然找不到一条空闲的串口线。临时飞线板子已经塞进铝合金外壳里了。SPI口倒是空着但现写一套日志协议也不现实。后来翻EVA例程时看到 SDI Printf 这个功能才发现沁恒在调试这条路上早就留了一扇门。这篇文章围绕 CH32V303RCT6 这颗RISC-V芯片上的 SDI Printf 虚拟串口调试方案展开从底层原理讲到工程配置、代码改造、实测对比和踩坑记录一次性说透。适合手里有 CH32V303、CH32V307 这类青稞V4B内核芯片的开发者也适合正纠结“调试口和业务口怎么共存”的人借鉴。哪怕你之前没接触过沁恒的工具链跟着操作一遍也能把环境跑起来。1. UART Printf的“原罪”调试口为什么总是不够用1.1 引脚占用不是小问题做嵌入式开发的人都有这种经历原理图设计阶段拍着胸脯说“串口多得是”等真正写业务代码时发现每路USART都有去处。CH32V303RCT6 虽然有5路USART但实际产品里往往要接RS485、RS232、TTL电平传感器、蓝牙模组、4G模组一路都不能少。这时候你再看调试日志需求会发现唯一的空闲串口根本没留。用物理UART做调试日志代价不只是引脚本身还有电平转换芯片、PCB走线空间、连接器引脚分配。产品定型之后想再引一路调试串口出来基本等于改版。所以我一直觉得调试口应该在系统设计初期就单独规划而不是等到联调阶段才想起来。1.2 调试信息与业务通信“抢线”就算你硬生生腾出一路UART给日志问题也不只“有没有引脚”这么简单。业务串口跑的是Modbus、AT指令、私有协议这些通信对时序敏感。调试日志如果和数据帧混在同一个物理通道里轻则日志刷屏导致通信超时重则调试信息被当成业务数据解析直接弄崩协议栈。我见过一种“土办法”把调试日志从另一个串口引出来然后外接USB转TTL模块再用串口助手看。这方案能用但缺点很明显——USB转TTL模块的地线处理不好就掉包波特率不匹配就乱码而且调试日志和在线仿真器是两套独立系统没法把“打印输出”和“变量实时状态”对应起来看。1.3 STM32玩家眼里的ITM/SWO联想用过STM32的人都熟悉ITMInstrumentation Trace Macrocell和SWOSingle Wire Output这套机制调试器通过SWD接口连接芯片不仅可以下载和单步调试还能额外输出printf数据完全不占物理UART。这在串口紧张、又想保留在线调试能力的场景下几乎是完美答案。问题在于RISC-V内核没有ARM的ITM模块直接在CH32V303上用不了这套思路。很多从STM32转过来的工程师第一反应是“这芯片不行连个printf跟踪都没有”但实际是没找到对应方案。CH32V303RCT6 上的 SDI Printf 就是沁恒对这套需求的RISC-V版本回答实现思路和ITM/SWO类似但底层走的是自家调试协议。2. SDI Printf的数据链路从MCU到PC到底走了条什么路2.1 SDI是什么它和SWD调试口是什么关系SDI全称是 Serial Debug Interface中文一般叫串行调试接口是沁恒基于RISC-V调试机制实现的一套双向数据传输通道。它复用的是调试接口的SWDIO引脚也就是你原本用来下载程序、在线仿真那根线。很多人的误区是把SDI理解成一个新的硬件外设其实它更像一个“寄生”在调试协议栈里的数据通道。MCU运行时调试接口硬件负责维护这条通道应用层代码把要打印的字符塞进SDI发送缓冲区调试器端负责把这些数据收回来并上传给PC。这么说吧SWDIO这根线平时干的是“调试员”的活现在它下班之后还兼职“送快递”打印数据就是它顺路捎出来的包裹。2.2 一条完整的数据通路SDI Printf的数据流大致可以拆成四段MCU应用代码调用printf经过重定向函数把字符交给SDI发送接口CH32V303RCT6 内部的调试接口硬件通过SWDIO引脚把数据逐字节发出去WCH-Link调试器通过SWDIO接收数据缓存后通过USB上传到PCPC端驱动把WCH-Link识别为一个虚拟COM口串口助手或者调试终端从这个COM口读数据。这个过程对应用层几乎是透明的。你在代码里只是照常写printf(hello\r\n)最终却能看到数据从“不存在的串口”里冒出来。整条链路里真正的物理串口一个都没用到。2.3 为什么这套设计会改变调试体验最直观的好处是省引脚但更深层的价值在于“调试通道与业务通道彻底隔离”。日志输出走调试口业务通信走UART两边互不干扰。你可以在主循环里放心大胆地高频打印不用担心把某个传感器数据帧冲掉。另外由于打印数据走的路径本质上是调试协议的一部分它天然和“在线调试”绑定在一起。芯片暂停在断点时SDI输出也会同步暂停恢复运行时数据接着往外送。这个特性配合断点调试非常有用你可以把某个状态变量的变化打成日志然后设断点观察临界时刻的完整上下文而不是靠UART日志盲猜。2.4 鱼和熊掌SDI Printf的限制SDI Printf带来的另一个限制是它必须依赖WCH-Link调试器。如果你手头只有USB转TTL模块没有调试器这套方案就跑不起来。毕竟数据是从SWDIO上走的必须有一个能解析这个协议的硬件适配器。传输带宽也不能跟UART比。物理UART在高速配置下能做到1.5Mbps甚至更高SDI通道的稳定吞吐量受调试器、USB传输、驱动缓存共同影响实际用下来大概也就是几十KB/s的量级。对调试日志来说这个带宽足够想拿它传文件或者刷大量二进制数据那就想多了。3. 环境准备与最小工程从硬件接线到工程配置3.1 硬件清单与接线要点我用的是 CH32V303RCT6 核心板加 WCH-Link 调试器这套组合做SDI Printf验证最省事。接线只有四根WCH-LinkCH32V303RCT6 目标板SWDIOPA13 (SWDIO)SWCLKPA14 (SWCLK)GNDGND3.3V3.3V这里有两个容易翻车的细节一是SWDIO和SWCLK不要接反反了WCH-Link连不上芯片二是目标板如果是独立供电GND必须和WCH-Link共地否则调试握手会时好时坏。我建议直接用调试器给目标板供电排除掉接地不一致的问题。CH32V303RCT6 核心板默认从WCH-Link取3.3V完全没问题但如果板子上还带着电机驱动或大电流外设就别偷这个懒老老实实外部供电并共地。3.2 软件栈MounRiver Studio、驱动和EVT例程软件方面需要三样东西MounRiver StudioMRS沁恒基于Eclipse做的IDE内置了RISC-V GCC工具链和调试配置SDI Printf相关模板可以直接用WCH-Link驱动安装后设备管理器里会出现WCH-Link设备同时会枚举出一个虚拟串口CH32V303 EVT例程包里面带了SDI_Printf的参考工程建议下载后直接对照着抄。MRS的安装过程不复杂一路Next就行。安装完驱动后插上WCH-Link再插上目标板打开设备管理器正常情况下能看到一个COM口这个就是后面SDI Printf输出的出口。3.3 新建工程时最容易忽略的选项在MRS里新建CH32V303工程时默认会生成一个基于UART的printf重定向模板也就是常见的那种USART_Printf_Init(115200)写法。如果你直接在这个模板上改SDI Printf是不会生效的。正确做法是在新建工程的时候或者直接从EVT例程包里导入SDI_Printf相关工程。以CH32V303 EVT为例例程目录下会有SDI_Printf文件夹导入MRS后直接编译下载。第一次跑通这个例程你的SDI Printf环境就算基本搭起来了。如果你手头已经有一个成熟工程想在不重开工程的情况下切到SDI Printf前提是你把底层发送函数从UART寄存器操作改成SDI发送函数并且把初始化函数替换成SDI_Printf_Init()。EVT例程里debug.h已经封装好了这些接口可以直接移植。3.4 代码层面最少需要哪几行一个最小的SDI Printf工程核心代码其实就两块。初始化阶段调用SDI打印初始化int main(void) { SystemCoreClockUpdate(); SDI_Printf_Init(); printf(SDI Printf is working\r\n); while(1) {} }底层重定向在例程的debug.c里已经处理好了它会接管标准库的printf输出把字符流交给SDI发送函数。你主程序里只管用printf不需要关心数据是怎么出去的。这里有个区别要注意传统UART printf模板里你会看到USART_Printf_Init(115200)这句换成SDI方案后这句就不需要了。因为虚拟串口的波特率是调试链路上的逻辑参数不是物理UART的波特率所以代码里做波特率初始化反而是多余的。4. 代码改造实录把现有工程的UART日志切到SDI输出4.1 从UART Printf迁移的最小改动量如果你手上已经有了一份跑通的UART日志工程迁移到SDI Printf并不需要大动干戈。整个过程可以归纳成三步把工程里的调试接口相关文件替换成EVT例程里的debug.c和debug.h在主函数初期把USART_Printf_Init(115200)替换成SDI_Printf_Init()确认链接时没有把两个printf重定向函数同时编译进去。我第一次迁移时没注意第三点结果在debug.c里保留了UART的重定向代码又在其他地方定义了SDI的重定向函数编译直接报了重复定义错误。这一类问题在Eclipse系的IDE里经常出现排查思路就是全局搜fputc或_write看看有没有重复实现。4.2 重定向函数的两种常见写法CH32V203、CH32V303这些芯片在MRS工具链下printf重定向一般有两种形态。第一种是标准C库的fputc重定向int fputc(int ch, FILE *f) { /* 调用SDI底层发送函数逐字节发送 */ return SDI_SendByte(ch); }第二种是newlib的_write重定向适用于更底层的输出场合int _write(int file, char *ptr, int len) { int i; for (i 0; i len; i) { SDI_SendByte(*ptr); } return len; }两种写法只要存在一种printf的输出就能进SDI通道。实际使用中我更推荐_write这种因为它直接处理定长输出效率比逐字符回调fputc高一些。EVT例程里默认用的是哪一种以你下载到的SDK版本为准但思路是通用的。4.3 实际业务场景下的日志改造示例光会打一句“hello world”没意思我们看点实际的东西。假设我用CH32V303RCT6做电机电流采集需要周期性打印ADC采样值、PID输出和运行状态切到SDI之后代码长这样uint16_t adc_val; int16_t pid_out; uint8_t state; while (1) { adc_val ADC_GetValue(); pid_out PID_Calculate(adc_val, target); state MOTOR_GetState(); printf([T:%lu] ADC:%u PID:%d STATE:%u\r\n, (unsigned long)Tick_GetMs(), adc_val, pid_out, state); Delay_Ms(10); }这段日志如果用物理UART输出需要一个空闲串口、一个USB转TTL模块、一根杜邦线还可能要共用GND。切到SDI之后把代码编译下载打开设备管理器对应的COM口接上串口助手数据就出来了。调试日志里加上时间戳是个好习惯。Tick_GetMs()是自己维护的毫秒计数器打印出来之后配合波形工具能直接判断某个事件的时间顺序。4.4 关于波特率的“误会”用SDI Printf的时候虚拟串口的波特率设置有没有用答案是串口助手里你随便选哪个波特率都能收到数据因为虚拟COM口本质上是USB枚举出来的逻辑串口不依赖物理UART的波特率发生器。这个特性带来一个隐藏便利你不需要像调UART那样在PC端反复尝试9600、115200、460800这些档位。只要驱动装好了虚拟串口的数据是实时打包上传的波特率只是一个兼容性参数填什么都能看到内容。第一次接触这套方案的同事问我“为什么我波特率设错了还有数据”就是被这个设计“惯坏”了。5. 实测对比UART Printf与SDI Printf的差距到底在哪5.1 一张表看明白两种方案的差异我花了一个下午把同一份日志代码分别用UART Printf和SDI Printf跑了一遍从引脚占用、外设依赖、调试耦合这几个维度做了对比对比项UART PrintfSDI Printf引脚占用至少1个TX可能还要RX0个物理UART引脚额外硬件USB转TTL模块或板载USB串口必须有WCH-Link调试器初始化配置需匹配波特率、引脚复用代码里无需配置波特率与在线调试关系无直接关系断点不影响UART输出与调试会话绑定暂停时输出暂停传输带宽高可达1Mbps以上中稳定吞吐几十KB/s量级数据隔离性日志可能与业务串口混淆独立通道隔离干净多串口产品适配需要预留调试串口不占业务串口天然适配5.2 延迟和吞吐量的实测感受我用逻辑分析仪挂在SDI的SWDIO引脚上看过波形确认数据确实是从调试口出去的不是UART绕道。在10ms打印一次的典型日志频率下SDI Printf非常稳定串口助手几乎没有任何卡顿和丢行。刷屏极限大概在每毫秒打印一行100字节左右时开始出现掉包表现为偶发的断行和时序抖动。如果你只是常规调逻辑根本到不了这个频率但要做高频率波形导出就需要控制一下输出量。顺便说一句日志打印频率不要无脑拉满。哪怕SDI不占用UART每条日志打印本身还是有CPU开销的尤其在高负载的电机控制、FFT运算任务里过密的打印会影响实时性。我常用的节奏是业务关键事件即时打周期性数据10ms到100ms打一次。5.3 调试暂停时的一个特殊现象UART Printf在芯片停下时数据还会继续从UART外设发出去串口助手上能看到数据流慢慢停了下来但不会“消失”。SDI Printf不一样芯片暂停时SWDIO引脚上的调试协议也暂停了已经发到WCH-Link缓冲区的数据可能还能传上来但新打印的数据会全部堵在MCU侧。这个特性刚开始让我以为SDI打印坏了后来才意识到这正是它和硬件调试绑定的体现。你设断点停下来看变量值看堆栈然后单步执行几行再把数据接上——整个过程的日志是“断续”的但每一段都精确对应代码执行到的位置。这种调试体验是传统UART日志给不了的。6. 进阶玩法把SDI Printf从“看日志”升级成“看波形”6.1 配合Vofa把数据变成曲线传统串口助手只能看文本但调试PID、滤波算法、电机响应时文本数字根本不够直观。Vofa这类上位机可以解析特定格式的文本流把数据画成实时曲线。SDI Printf的数据既然在PC端是个虚拟串口那自然也能接到Vofa里。我用一个简单格式打印三路数据Vofa直接识别成三通道曲线printf(adc:%u speed:%d pid:%d\r\n, adc_val, speed, pid_out);在Vofa里选择Firewater协议也就是key:value形式波特率随便选打开对应COM口就能看到三条波形实时刷新。这个组合非常适合调PID把目标值、反馈值、输出值三路打出来参数整定的时候眼睛盯着曲线调比看一串数字效率高不知道多少倍。6.2 多模块日志前缀管理工程越来越大之后日志很容易乱成一片。我用SDI Printf之后特意规定了一套日志格式每个模块一个前缀标识比如[ADC]、[USR]、[ERR]再用printf统一输出。SDI通道只有一个虚拟串口但通过前缀就能实现逻辑上的多路日志。更高级一点的做法是利用调试接口的实时性把日志按等级过滤。比如用一个全局变量控制日志级别发布模式下只打ERROR开发模式下打INFO和DEBUG。这套逻辑在UART日志时代一样能做但SDI方案的优势是不会占用业务串口所以日志代码可以更“放肆”一些。6.3 异常掉线时的“现场还原”SDI Printf和在线调试绑定这个特性还能用来做一种很讨巧的异常排查程序跑飞或硬错误之前把关键变量打印出来。芯片崩溃时WCH-Link缓冲区里可能残留最后一帧日志串口助手会显示最后打印的那几条数据。配合MRS里的硬错误中断回调你可以在进入HardFault_Handler之前打一条[ERR] crash!然后在PC端确认SDI输出的最后一条日志就能大致判断崩溃点。我在一次栈溢出排查中就是这么定位的日志规律地打印到某个函数入口就停停之前没有任何异常信息顺着最后一帧日志去检查对应函数的局部变量果然发现一个大数组越界写爆了栈。7. 我踩过的坑SDI Printf容易翻车的细节与排查思路7.1 虚拟串口死活不出现第一次接WCH-Link发现设备管理器里只有“WCH-Link”这个设备虚拟串口没有枚举出来。排查过程很简单先看WCH-Link固件版本工具软件里可以升级固件旧固件对SDI虚拟串口支持不完整再看USB连接线有些劣质线只能充电不能传数据换一根数据线就好了。如果这两个都没问题拔插一下WCH-Link或者换个USB口。我遇到过驱动装好了但系统没刷新设备列表的情况拔插一次就出来了。7.2 串口助手收到乱码虚拟串口理论上不依赖波特率但乱码还是有发生。我碰到过两种情况一种是数据线太长导致信号质量差SWDIO上的调试协议本身就传不稳打印的数据自然丢字节另一种是WCH-Link的供电不足目标板负载稍高调试口电压跌落SDI偶发错码。解决思路是缩短SWDIO杜邦线到15厘米以内确保WCH-Link用USB直连PC而不是经过HUB。用HUB时尽量选带供电的无源HUB非常容易在调试高负载目标板时出问题。7.3 SDI打印在断点后恢复不同步在线调试暂停一段时间再恢复串口助手上可能会出现一大段数据同时涌出的现象。这是正常的缓冲效应芯片暂停期间日志堆积在缓冲区恢复运行后才陆续送出来PC端看到的就是“突然刷了一屏”。不要误以为程序跑飞了这只是SDI通道在追补暂停期间的数据。如果不想看到这种堆积可以在断点调试时手动清空串口助手接收区或者把打印频率在调试会话期间降低一些。对我来说这反而是个特性暂停前的日志和暂停后的日志能清清楚楚分开上下文一目了然。7.4 高频打印导致调试器断连有一次我把printf放进了一个1ms中断里打印内容还特别长结果跑了十几分钟WCH-Link直接断开在线调试丢失目标。原因是SDI底层发送在中断里占用时间过长把调试协议本身挤爆了。遇到这种场景我的处理方法是把高频数据先在内存里攒起来主循环里定时批量输出。比如在ADC中断里只往环形缓冲区写数据主循环每50ms把缓冲区里的内容一次性打印出来。这样既不会丢数据也不会把SDI通道堵死。说到底SDI Printf是一条调试通道不是一条数据总线。你用它的目的是让调试过程更顺畅而不是替代UART做高速通信。理解了这层定位很多使用上的“怪现象”就都能解释通了。这套方案我在CH32V303RCT6上用了大半年节省的引脚和排障时间都是实打实的如果你也被“调试口不够用”折磨过值得花一个晚上把它跑通。
