1. 为什么要重定向printf和串口之间的那堵墙刚用Keil做STM32项目的时候几乎每个人都干过这么一件事在main函数里写了printf然后打开串口助手发现什么都收不到。我当年也一样实验板上电DebugprintfViewer窗口里确实能看到打印但串口那头就是一声不吭。后来才搞清楚Keil下printf的默认输出通道根本就不是串口它走的是调试器的半主机通道。你要想让它从串口出去必须做“重定向”也就是把printf的输出链路重新指到串口上。这篇文章把我调试这一路反复试过的三种方案都放出来包括网上流传的MicroLIB勾选大法、标准库模式下半主机处理、以及我自己后来最喜欢的vsnprintf自封装方案。三种方法各有各的适应场景我会把配置步骤、原理、坑点都讲透最后再给一份MicroLIB开关的横向对比。无论你是刚入门的新手还是被项目里printf卡住的老兵这篇应该都能帮你省下不少时间。1.1 printf从被调用到字符送出中间发生了什么先说个最简单的事实printf不是一个硬件相关的函数它压根不知道你的单片机里有个叫USART1的东西也不知道波特率是什么。printf的工作是“格式化”把你要打印的数据转成一串字符然后这串字符要交给一个底层函数去真正送出去。在ARM的C标准库里这一级的字符发送接口就是fputc。标准库内部有一个默认的fputc实现它做的事情是把字符送到“调试通道”也就是半主机机制所指向的Debug Viewer窗口。所以在你不做任何处理的前提下printf打出来的内容去了调试器界面而不是你的串口外设。半主机机制是ARM调试环境里一个很有历史的设计它让目标板上跑的代码可以通过某种软中断调用去使用PC端调试主机提供的资源比如往IDE的Console窗口打印字符串、从键盘读输入、读写宿主机的文件。这在仿真调试阶段很方便但一旦你要把程序独立跑起来、用真实的串口通信这条默认链路就完全不对路了。理解了这条链路你就明白了所谓“重定向”到底在重定向什么把fputc这个字符出口从默认的调试通道改成你的串口发送寄存器。只要能把这个底层出口改掉printf就像换了条水管水流方向立刻就变了。这也是后面所有方法的理论根基。1.2 三种重定向方案的选型思路改fputc是最直接的做法但围绕着“怎么改”和“改完之后库怎么编”衍生出了几条不同的路线。第一种方案是使用Keil自带的MicroLIB微库配合重写fputc。微库是ARM专门为嵌入式设备裁剪出来的轻量级C库它对底层半主机的依赖很少所以你只需要重写fputc就可以直接工作这是绝大多数STM32教程里的标准做法也是最快能见到效果的一条路。第二种方案是坚持使用标准C库不勾MicroLIB同时重写fputc并手动关闭半主机模式。标准库功能完整、行为最接近桌面C语言环境但它内部对半主机机制的重度依赖要求你必须补全几个底层接口否则程序会直接卡死甚至进入硬件错误中断。第三种方案不是改fputc而是绕开标准库的输出链路用vsnprintf自己完成格式化再把格式化后的字符串交给自定义的串口发送函数。这一招表面上看起来绕了远路但实际上是最稳定、最可控的做法尤其在RTOS或复杂日志系统里它的优势是前两种方法没法比的。我在工程里三种都用过快速验证用方法一需要完整C库项目用方法二产品级代码我长期用的是方法三。接下来逐一展开讲。2. 方法一MicroLIB fputc重定向新手首选2.1 勾选MicroLIB并改写fputc这个方案的操作步骤非常少以STM32 HAL库工程为例整个过程就两步。第一步在Keil的魔术棒选项卡里打开Options for Target切到Target页在Code Generation分组下面勾选Use MicroLIB。这一步的作用是把标准的ARM C库替换成微库版本微库为了适应单片机环境砍掉了文件系统、信号等一大票用不到的功能同时也不再依赖半主机通道。第二步在你工程中任意一个C文件里写一个fputc函数函数名和参数必须严格这么写这是C库定义好的接口#include stdio.h int fputc(int ch, FILE *f) { while (__HAL_UART_GET_FLAG(huart1, UART_FLAG_TXE) RESET) {} huart1.Instance-DR (uint8_t)ch; return ch; }这段代码的逻辑很直接等待发送数据寄存器为空然后把字符ch写入串口数据寄存器。这里用的串口是USART1对应的句柄是huart1。如果你用的是标准外设库把这个函数体换成USART_SendData(USART1, (uint8_t)ch)配合while(USART_GetFlagStatus(USART1, USART_FLAG_TXE) RESET)就行。写完之后你在main函数里调用printf(hello\r\n)大概率就能在串口助手上看到输出了。HAL库用户也可以把while等待那段换成HAL_UART_Transmit(huart1, (uint8_t *)ch, 1, HAL_MAX_DELAY)效果一样只是HAL的阻塞式发送会有超时判断代码稍慢一点。这里有个容易被忽略的细节fputc必须返回ch。C库的字符输出函数要求把实际输出的字符作为返回值如果你随手写成return 0之类的虽然很多情况下printf照样能工作但不符合标准在某些优化级别或者库版本下会出怪问题。2.2 微库方式的好处和注意点用MicroLIB配fputc最大好处就是两个字省事。不需要处理半主机模式不需要补那么多底层函数也不容易出现“莫名其妙卡死”的情况。对于刚接触单片机的朋友这是最不容易踩坑的入口。但微库也是有代价的。第一它对标准C的支持是不完整的某些边界行为跟标准库有差异。比如在微库里printf默认不带缓冲每个字符都会直接调fputc而标准库在部分场景下会有缓冲行为。绝大多数日志打印场景不涉及这些差异但如果你从桌面C环境移植一段对格式有特殊依赖的复杂代码微库可能会给你惊喜。第二微库对浮点格式的支持在不同编译器版本下表现不太一样。有的版本里printf(%.2f, 3.14)能正常输出有的版本会打出奇怪的内容。这个我一般建议不管用不用微库在做串口日志打印浮点前先花一分钟实测一下别默认它能工作。第三从代码体积角度看微库确实能帮你省下不少Flash。同样一个HAL工程不开微库标准库版本编译出来可能要多占几KB甚至十几KB的空间这在Flash紧张的芯片上是个实打实的优势。所以方法一的适用场景很明确芯片Flash容量敏感、项目不需要太多标准C库特性、调试阶段想快速打通串口打印。它不是什么高深技巧但也是最稳的地基。3. 方法二标准库重定向 关闭半主机模式3.1 标准库模式下的底层补全比微库麻烦一点的是坚持不勾Use MicroLIB用完整的标准C库来做重定向。为什么有人非要用标准库因为标准库功能全、行为规范代码在PC和单片机之间移植时不用反复适配库差异。但代价就是你必须自己关掉半主机并把标准库依赖的几个底层函数补上。我用过的标准库重定向标准写法是这样的直接在某个.c文件里放上完整的一段#include stdio.h #pragma import(__use_no_semihosting) struct __FILE { int handle; }; FILE __stdout; void _sys_exit(int x) { x x; } void _ttywrch(int ch) { ch ch; } int fputc(int ch, FILE *f) { while (__HAL_UART_GET_FLAG(huart1, UART_FLAG_TXE) RESET) {} huart1.Instance-DR (uint8_t)ch; return ch; }这里面最关键的是第一行#pragma import(__use_no_semihosting)。它的意思是告诉ARM链接器我这个程序不需要半主机机制你不要链接那些依赖半主机的库函数。但这样做的后果是标准库里有些函数本身的实现就依赖半主机接口特别是与标准输出、错误退出相关的这几个。你强行不链接它们就必须自己提供替代品。于是就有了后面几个我们自己补的桩函数struct __FILE和FILE __stdout标准库内部用__stdout来代表标准输出流printf最终要走这个对象去调用fputc。如果这个对象没定义链接阶段就会报__stdout未定义。_sys_exit(int x)系统退出函数。单片机上的程序正常情况下不会退出但这个符号必须存在否则链接不过。里面写x x;是为了防止编译器报警告实际什么都没干。_ttywrch(int ch)老式字符输出辅助函数某些库内部路径会用到同样只做桩处理。这五个部分任何一个缺失都可能让你卡在链接错误或者程序运行时的半主机陷阱里。补全之后标准库的printf输出链路就完整地走我们的fputc了。3.2 半主机模式常见报错和处理标准库模式下见得最多的一个现象是程序编译下载都没问题但是一跑到printf就卡死。你在调试器里暂停发现PC指针停在了一个BKPT指令上旁边还可能显示0xAB。这就是半主机模式没关干净的典型症状。为什么会这样因为你的库里还有部分代码路径想去调半主机服务而当前调试会话没有建立半主机通道或者你根本没有接调试器运行那这条指令就会触发一个异常让程序停摆。如果你按上面的代码补好了一般不会再碰到这个情况。但如果你的工程是从网上或者别人那里拷来的可能只重写了fputc而没有加#pragma import(__use_no_semihosting)也没有提供_sys_exit这些桩函数那就很有可能会踩到这个BKPT卡死坑里。另外一个常见问题是编译器版本带来的差异。目前Keil MDK常见的编译器有AC5armcc和AC6armclang。AC6对半主机处理跟AC5不完全一致在一些库函数路径上对底层接口的需求更多。如果你的工程用的是AC6跑标准库重定向时遇到奇怪的链接错误我建议先去确认一下自己编译器的版本再搜索对应的处理代码。AC6下也有一股做法是用__asm(.global __use_no_semihosting);配合其他一些重定向函数但我个人体验是AC5下这段代码最省心AC6下如果碰壁直接转用方法三或方法一能省很多时间。方法二最大的价值在于它让你的工程保持完整标准库对后续扩展第三方库、移植复杂模块更友好。缺点也很明显门槛高调试起来不如方法一那么“一把梭”。4. 方法三vsnprintf自封装日志函数最可控4.1 用可变参数自己实现一个log_printf如果说前两种方法是“改造流水的管道”那这第三种方法就是直接“另起一条流水线”。心思完全绕开标准库的printf链路自己用vsnprintf把内容格式化到一块内存缓冲区然后把缓冲区里的内容通过串口发出去。核心代码是这样#include stdarg.h #include stdio.h #include stm32f1xx_hal.h extern UART_HandleTypeDef huart1; void uart_send_str(char *str) { while (*str) { while (__HAL_UART_GET_FLAG(huart1, UART_FLAG_TXE) RESET) {} huart1.Instance-DR (uint8_t)(*str); } } void log_printf(const char *fmt, ...) { char buf[128]; va_list args; va_start(args, fmt); vsnprintf(buf, sizeof(buf), fmt, args); va_end(args); uart_send_str(buf); }使用时把printf(hello\r\n)换成log_printf(hello\r\n)就行。注意文件头要包含stdarg.h其他跟普通printf没有区别。这个方案的原理不难理解vsnprintf继承了完整的格式化能力能把%d、%s、%f都正确处理成字符串放进buf串口发送完全由自己写的uart_send_str控制。它和标准库的fputc链路彻底解耦半主机模式影响不到它编译器版本差异影响不到它RTOS重入问题也能通过加锁来处理。缓冲区buf的大小根据你的日志需求来定。常规128字节够用如果你有很长的调试打印建议定义成256但要注意栈空间。在裸机工程里char buf[128]会占用调用者函数的栈空间在RTOS里这个数组占用的是当前任务自己的栈任务栈太小的话会溢出务必按最大日志长度评估。4.2 扩展日志级别、多路输出、时间戳这第三招真正的价值不在“能用”而在“好用”。一旦你不再依赖printf这个名字你就可以像写一套完整的日志系统一样随意扩展它。举一个我常用的扩展例子加日志级别。#define LOG_DEBUG 0 #define LOG_INFO 1 #define LOG_WARN 2 #define LOG_ERROR 3 static int g_log_level LOG_INFO; void log_set_level(int level) { g_log_level level; } void log_printf(int level, const char *fmt, ...) { char buf[128]; va_list args; if (level g_log_level) return; va_start(args, fmt); vsnprintf(buf, sizeof(buf), fmt, args); va_end(args); uart_send_str(buf); }这样你就可以在代码里写log_printf(LOG_WARN, voltage too low: %.2f\r\n, voltage);然后通过log_set_level随时切换打印的详细程度。产品发布时把日志级别调到ERROR调试时再调回DEBUG不需要改代码。甚至可以在uart_send_str里挂一个计数器做时间戳前缀或者把输出同时导向串口和Flash。这些在标准printf链路上实现起来很麻烦在自封装方案里只是几行代码的事。当然这个方案的缺点也很明显它不再使用printf这个名字不方便直接套用别人的printf代码每次日志都要消耗一块缓冲区在函数栈较小的场景下你需要特别留意缓冲区大小。但如果你愿意修改代码中的打印调用这种方案带来的长期收益是很高的。我在带FreeRTOS的项目里基本都采用这个做法配合互斥量或关闭调度器多任务下打印再也不会互相穿插。5. MicroLIB开关对比到底该不该用很多人问过我MicroLIB到底要不要勾其实这个问题没有标准答案它取决于你项目的具体需求。我把两种状态下的差异列了份对照方便大家直接判断。对比项使用MicroLIB使用标准库不勾选printf重定向复杂度低重写fputc即可高需要处理半主机并补齐底层函数编译后代码体积明显更小适合Flash紧张较大标准C特性支持裁剪版部分行为与标准有差异完整半主机模式依赖基本无感必须显式关闭否则卡死浮点%f打印部分版本实测可用建议实测通常需要额外处理行为依赖编译器版本第三方库兼容性可能因缺少库功能而报错兼容性更好运行时期行为无缓冲字符直通fputc有缓冲机制行为更接近桌面C环境我自己的经验是如果是快速验证、学习调试、资源受限的小产品直接勾选MicroLIB省心又省Flash。如果项目规模大、要移植第三方协议栈或数学库或者对C标准行为有硬性要求那就用标准库老老实实把半主机关掉。还有一个小细节在Keil的“魔术棒”里不勾选MicroLIB的情况下有的项目打印%f时还需要在Target页勾选Use Single Precision或者在代码里合理处理浮点数。这个问题在不同芯片、不同编译器版本上表现不一致我建议遇到浮点打印异常时优先用二分法测试先单独打印%f再打印整数看问题范围别在大概率无效的配置上死磕太久。如果你已经尝试了方法一和方法二发现都不是很顺手那方法三的思路其实是最能绕开所有这些库差异的。vsnprintf本身就是标准库函数你只要确保它能正常工作剩下的格式处理全交给你自己不用管fputc不用管半主机不用管微库行为差异。6. 常见问题与排查技巧6.1 printf无输出与乱码无论用哪种重定向方法printf串口输出最经典的坑就是这俩没有输出、输出乱码。先排查没有输出。第一步确认串口本身是通的。可以先在代码里直接调用串口发送一个固定字符串不用printf比如写一个短循环把“OK\r\n”逐字节发出去然后看串口助手里有没有。如果这都没有先查串口初始化参数、引脚配置、波特率甚至硬件连接不要急着怀疑重定向代码。第二步如果串口直发正常但printf不行在fputc函数里打一个断点看程序有没有跑进来。如果没进来说明printf的调用路径有问题检查有没有把printf优化掉比如打印内容永远不变化某些优化级别下可能被裁掉、头文件有没有包含stdio.h。如果进来了但串口没数据多半是fputc内部的等待条件写反了或者占用了错误的串口句柄。再说乱码。这是更玄学的问题通常有三个来源。第一波特率不匹配电脑上串口助手设置值和代码里初始化串口的值不一致最常见的是115200和9600搞混。第二系统时钟不对芯片实际工作频率跟HAL配置不一致导致串口波特率计算出现偏差。第三编码问题Keil环境下源文件可能是UTF-8编码某些中文在串口助手里如果选了GBK或者ASCII显示就会是一串乱码。解决中文乱码的办法是建议开发时串口日志统一用英文或者保证源文件编码和串口助手的编码设置一致。6.2 卡死、HardFault与重入问题程序一调printf就卡死是第二种高频问题。如果程序卡在BKPT一条指令上那就是半主机模式的锅按第3节讲的方式处理。如果程序直接进入了HardFault_Handler先别急着重定向代码在hard fault里把栈回溯出来看压栈的PC地址指向哪里。如果PC指向printf相关代码段大概率还是库函数底层问题可以尝试换成MicroLIB或者方法三把问题面缩窄。还有一个非常多但容易被忽视的问题是RTOS重入。在FreeRTOS、RT-Thread这类多任务环境里如果多个任务同时调用printf底层fputc共享同一个串口很可能出现字符穿插甚至因为发送等待期间任务被切换产生死锁。方法一和方法二在裸机环境下很爽但上了RTOS之后要格外小心。方法三借助互斥量就很容易解决在log_printf前后加锁即可。这也是我在产品代码里长期使用方法三的根本原因它不是为了花哨而是为了在多任务环境下依然可靠。最后再提一个跟缓冲区相关的坑使用vsnprintf时如果格式化后的字符串长度刚好等于或超过缓冲区大小vsnprintf会进行截断并在末尾写入\0这是安全的行为。但你要是用sprintf就危险了缓冲区溢出会静默地破坏栈上其他变量。封装日志函数时永远用vsnprintf别用sprintf。这是我踩完血坑后最想强调的一点。
