CH32V303调试新思路：SDI Printf虚拟串口，让调试口不再短缺

上个项目做到联调阶段，遇到一个很憋屈的问题：板子上两路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的人都熟悉ITM（Instrumentation Trace Macrocell）和SWO（Single 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的数据流大致可以拆成四段：

1. MCU应用代码调用printf，经过重定向函数把字符交给SDI发送接口；
2. CH32V303RCT6 内部的调试接口硬件通过SWDIO引脚把数据逐字节发出去；
3. WCH-Link调试器通过SWDIO接收数据，缓存后通过USB上传到PC；
4. PC端驱动把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验证最省事。接线只有四根：

这里有两个容易翻车的细节：一是SWDIO和SWCLK不要接反，反了WCH-Link连不上芯片；二是目标板如果是独立供电，GND必须和WCH-Link共地，否则调试握手会时好时坏。我建议直接用调试器给目标板供电，排除掉接地不一致的问题。CH32V303RCT6 核心板默认从WCH-Link取3.3V完全没问题，但如果板子上还带着电机驱动或大电流外设，就别偷这个懒，老老实实外部供电并共地。

3.2 软件栈：MounRiver Studio、驱动和EVT例程

软件方面需要三样东西：

• MounRiver Studio（MRS）：沁恒基于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并不需要大动干戈。整个过程可以归纳成三步：

1. 把工程里的调试接口相关文件替换成EVT例程里的debug.c和debug.h；
2. 在主函数初期把USART_Printf_Init(115200)替换成SDI_Printf_Init()；
3. 确认链接时没有把两个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跑了一遍，从引脚占用、外设依赖、调试耦合这几个维度做了对比：

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上用了大半年，节省的引脚和排障时间都是实打实的，如果你也被“调试口不够用”折磨过，值得花一个晚上把它跑通。