1. 串口重定向不是“让 printf 能打印”,而是把调试流从半主机黑匣子里拽出来:STM32U5 上零依赖、低开销、可量产的诊断通道重建
你在 STM32U5 的 main() 里写了一句 printf("ADC: %d mV\n", adc_val);,编译通过,调试器一连,串口助手果然刷出数字——恭喜,你完成了半主机模式下的“Hello World”。但当你拔掉 ST-Link,把固件烧进板子单独上电,串口助手里只剩一片死寂。这不是 bug,是设计:ARM libc 默认把 printf 绑定到 Semihosting(半主机),它本质是借调试器在芯片和 PC 之间打的一条虚拟隧道,所有输出都得经过 JTAG/SWD 接口触发软件中断、切换上下文、再转发——这在实验室里很优雅,但在产线老化测试、现场设备复位日志抓取、或是客户投诉“灯不亮但没报错”时,就是一道无法逾越的墙。更糟的是,一次 printf 可能拖慢几十微秒,在 100kHz ADC 采样循环里插入一句调试输出,整个时序就崩了。所以,串口重定向不是锦上添花的技巧,它是嵌入式工程师的生存技能:它把 printf 从调试器的寄生虫,变成 UART 外设的原生子民。它不依赖任何调试硬件,不增加额外芯片成本,不破坏实时性,且一旦配置成功,就能随固件一起发布、部署、长期运行。本文只讲一件事:在 STM32U5 上,用最精简、最可控、最贴近寄存器本质的方式,把 printf 的输出流,一针一线地缝进 UART1 的发送移位寄存器里。不碰 HAL,不靠 CubeMX 自动生成的巨量胶水代码,所有关键位、所有重载函数、所有时序边界,都摊开给你看。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 重定向的底层契约:理解 _write 是如何被 printf 调用的,以及为什么必须重写它
2.1 printf 到 UART 的调用链:从格式化字符串到字节流的七层地狱
printf 看似简单,实则是 C 标准库中链条最长、最易被误解的函数之一。当你写下 printf("Temp: %.2f°C\n", temp);,编译器不会直接生成 UART 发送指令。它走的是这样一条路径:
- 格式化阶段:
printf函数解析格式字符串"Temp: %.2f°C\n",将浮点数temp按照%.2f规则转换为 ASCII 字符串"Temp: 23.45°C\n"(注意:这个过程本身不涉及 I/O,纯 CPU 运算); - 缓冲与分发阶段:格式化后的字符串被交给一个内部缓冲区,然后调用
_IO_putc或类似函数,试图将每个字符c写入一个“文件描述符”(file descriptor); - 系统调用拦截点:在裸机嵌入式环境(无操作系统),这个“写入文件描述符”的操作最终会落到
_write函数上。_write是 ARM libc(或 Newlib)提供的一个弱符号(weak symbol)函数,其默认实现就是半主机调用__semihosting_write。这就是整个链条的命门——_write是printf与物理世界唯一的、可编程的接口。
提示:
_write的函数签名是int _write(int fd, char *ptr, int len)。其中fd是文件描述符(对标准输出stdout,通常是1),ptr是待发送字符数组的首地址,len是字符个数。你的重定向工作,就是提供一个强定义的_write,让它不再调用半主机,而是驱动 UART 发送。
2.2 为什么不能只重写 fputc?——标准库的“双保险”陷阱
很多教程会告诉你:“重写 fputc 就行了!”。这是个危险的简化。fputc 确实是 printf 在某些路径下可能调用的函数,但它并非唯一入口。标准库为了兼容性和效率,常常会绕过 fputc,直接调用 _write 来批量发送数据(尤其是当 printf 输出较长字符串时)。如果你只重写了 fputc,而 printf 的内部逻辑恰好选择了 _write 路径,那么你的重定向就会彻底失效,输出依然走半主机。
因此,必须重写 _write。这是 ARM libc 官方文档明确要求的、最可靠、最底层的重定向方式。fputc 可以作为 _write 的一个辅助函数存在,但绝不能替代它。
2.3 STM32U5 的 UART1 初始化:精简到只保留重定向必需的三件事
重定向的核心是“发送”,所以我们只需初始化 UART 的发送功能,其他如接收、DMA、中断等,全部按需开启,绝不冗余。以下是针对 STM32U575 的最小初始化代码(使用标准外设库风格,便于理解寄存器含义):
c复制#include "stm32u5xx.h"
#include "stm32u5xx_ll_rcc.h"
#include "stm32u5xx_ll_bus.h"
#include "stm32u5xx_ll_usart.h"
#include "stm32u5xx_ll_gpio.h"
void UART1_Init_ForPrintf(void)
{
// 1. 使能 GPIOA 和 USART1 的时钟(这是所有操作的前提)
LL_AHB2_GRP1_EnableClock(LL_AHB2_GRP1_PERIPH_GPIOA);
LL_APB1_GRP1_EnableClock(LL_APB1_GRP1_PERIPH_USART1);
// 2. 配置 PA9 为复用推挽输出(USART1_TX)
LL_GPIO_SetPinMode(GPIOA, LL_GPIO_PIN_9, LL_GPIO_MODE_ALTERNATE);
LL_GPIO_SetPinOutputType(GPIOA, LL_GPIO_PIN_9, LL_GPIO_OUTPUT_PUSHPULL);
LL_GPIO_SetPinSpeed(GPIOA, LL_GPIO_PIN_9, LL_GPIO_SPEED_FREQ_HIGH);
LL_GPIO_SetPinPull(GPIOA, LL_GPIO_PIN_9, LL_GPIO_PULL_NO);
// 设置复用功能:PA9 -> USART1_TX (AF7)
LL_GPIO_SetAFPin_8_15(GPIOA, LL_GPIO_PIN_9, LL_GPIO_AF_7);
// 3. 配置 USART1:波特率115200,8N1,使能发送器,禁用接收器(我们只发不收)
LL_USART_InitTypeDef USART_InitStruct = {0};
USART_InitStruct.BaudRate = 115200;
USART_InitStruct.DataWidth = LL_USART_DATAWIDTH_8B;
USART_InitStruct.StopBits = LL_USART_STOPBITS_1;
USART_InitStruct.Parity = LL_USART_PARITY_NONE;
USART_InitStruct.TransferDirection = LL_USART_DIRECTION_TX;
USART_InitStruct.HardwareFlowControl = LL_USART_HWCONTROL_NONE;
USART_InitStruct.OverSampling = LL_USART_OVERSAMPLING_16;
LL_USART_Init(USART1, &USART_InitStruct);
// 4. 使能 USART1
LL_USART_Enable(USART1);
// 5. (可选但强烈推荐)等待发送器就绪,确保第一个字符不丢
while (!LL_USART_IsActiveFlag_TC(USART1));
}
这段代码的关键在于极度克制:没有配置 NVIC 中断,没有启用接收功能,没有设置 DMA。它只做三件事:打开时钟、配置引脚复用、初始化 UART 发送器。LL_USART_DIRECTION_TX 明确告诉外设“我只要发”,这能节省功耗,也避免了接收缓冲区溢出等干扰。
3. _write 函数的两种实现:阻塞式与非阻塞式,以及它们在真实场景中的血泪选择
3.1 阻塞式 _write:最简单,也最容易在中断里翻车
这是新手入门的首选,逻辑清晰,代码短小:
c复制// 全局变量,用于在中断中判断 UART 是否空闲
volatile uint8_t uart1_tx_busy = 0;
int _write(int fd, char *ptr, int len)
{
int i;
// 只处理 stdout (fd == 1) 和 stderr (fd == 2),忽略其他文件描述符
if ((fd != 1) && (fd != 2)) {
return -1;
}
for (i = 0; i < len; i++) {
// 等待 UART 发送完成标志(TC: Transmission Complete)
while (!LL_USART_IsActiveFlag_TC(USART1));
// 将字符写入发送数据寄存器
LL_USART_TransmitData8(USART1, (uint8_t)(*ptr++));
}
return len;
}
原理:LL_USART_IsActiveFlag_TC(USART1) 检查的是“发送完成”标志。这个标志在当前字节被完全移出移位寄存器、TXE(发送数据寄存器空)和 TC(传输完成)都置位后才为真。所以,每次 while 循环都在等前一个字节彻底发完,再发下一个。
优点:绝对可靠,不会丢字符,代码逻辑一目了然。
致命缺点:它会在中断服务程序(ISR)中导致死锁。想象一下,你的 TIM2_IRQHandler 里有一句 printf("IRQ: %d\n", counter);。当 printf 调用 _write 时,它会进入 while (!LL_USART_IsActiveFlag_TC(USART1))。如果此时 UART 正在发送前一个字符(比如主循环里的 printf),TC 标志为假,while 就会无限等待。而 TC 标志的更新需要 UART 外设的时钟周期,这个过程本身又可能被更高优先级的中断打断……结果就是,整个系统卡死在 while 里,TIM2_IRQHandler 永远无法退出。这是嵌入式开发中最经典的“玄学死锁”之一。
3.2 非阻塞式 _write + 中断发送:用状态机换自由,代价是多 30 行代码
要解决阻塞问题,就必须把“等待”这件事从 _write 函数里剥离出去。思路是:_write 只负责把字符拷贝进一个发送缓冲区(FIFO),然后立即返回;真正的发送工作,交给 UART 的发送完成中断(TC Interrupt) 在后台慢慢完成。
c复制#define UART_TX_BUFFER_SIZE 64
static uint8_t uart_tx_buffer[UART_TX_BUFFER_SIZE];
static volatile uint16_t uart_tx_head = 0; // 下一个要写入的位置
static volatile uint16_t uart_tx_tail = 0; // 下一个要读出的位置
static volatile uint8_t uart1_tx_busy = 0; // 发送器是否正忙
// 初始化发送缓冲区
void UART1_TxBuffer_Init(void)
{
uart_tx_head = 0;
uart_tx_tail = 0;
uart1_tx_busy = 0;
}
// 检查缓冲区是否为空
static inline uint8_t UART1_TxBuffer_IsEmpty(void)
{
return (uart_tx_head == uart_tx_tail);
}
// 检查缓冲区是否已满
static inline uint8_t UART1_TxBuffer_IsFull(void)
{
return ((uart_tx_head + 1) % UART_TX_BUFFER_SIZE == uart_tx_tail);
}
// 向缓冲区写入一个字符(非阻塞)
static uint8_t UART1_TxBuffer_Put(uint8_t c)
{
uint16_t next_head = (uart_tx_head + 1) % UART_TX_BUFFER_SIZE;
if (next_head == uart_tx_tail) {
return 0; // 缓冲区满,写入失败
}
uart_tx_buffer[uart_tx_head] = c;
uart_tx_head = next_head;
return 1; // 写入成功
}
// 从缓冲区读取一个字符(非阻塞)
static uint8_t UART1_TxBuffer_Get(uint8_t *c)
{
if (uart_tx_tail == uart_tx_head) {
return 0; // 缓冲区空
}
*c = uart_tx_buffer[uart_tx_tail];
uart_tx_tail = (uart_tx_tail + 1) % UART_TX_BUFFER_SIZE;
return 1;
}
// 非阻塞式 _write 实现
int _write(int fd, char *ptr, int len)
{
int i;
if ((fd != 1) && (fd != 2)) {
return -1;
}
for (i = 0; i < len; i++) {
// 尝试将字符放入发送缓冲区
if (!UART1_TxBuffer_Put((uint8_t)(*ptr++))) {
// 缓冲区已满,可以选择丢弃或等待(这里选择丢弃,避免阻塞)
// 也可以在此处添加一个超时等待,但会牺牲非阻塞特性
}
}
// 如果发送器当前空闲,手动触发一次发送(启动状态机)
if (!uart1_tx_busy) {
uint8_t c;
if (UART1_TxBuffer_Get(&c)) {
LL_USART_TransmitData8(USART1, c);
uart1_tx_busy = 1;
// 使能 TC 中断,以便在发送完成后继续发送下一个字符
LL_USART_EnableIT_TC(USART1);
}
}
return len;
}
// UART1 TC 中断服务程序
void USART1_IRQHandler(void)
{
uint8_t c;
// 检查是否是 TC 中断(发送完成)
if (LL_USART_IsEnabledIT_TC(USART1) && LL_USART_IsActiveFlag_TC(USART1)) {
// 尝试从缓冲区获取下一个字符
if (UART1_TxBuffer_Get(&c)) {
// 有字符,继续发送
LL_USART_TransmitData8(USART1, c);
} else {
// 缓冲区空了,关闭 TC 中断,标记发送器空闲
LL_USART_DisableIT_TC(USART1);
uart1_tx_busy = 0;
}
}
}
原理:这是一个典型的生产者-消费者模型。_write 是生产者,它把 printf 的字符“扔”进缓冲区就走人;USART1_IRQHandler 是消费者,它在每次发送完成时,自动从缓冲区“拿”一个字符发出去。uart1_tx_busy 标志是协调两者的关键。
优点:彻底解决了中断中死锁问题。_write 函数执行时间极短(纳秒级),无论在主循环还是任何中断里调用,都安全可靠。
代价:代码量增加,需要管理缓冲区和中断。但这是专业嵌入式开发的必经之路。
4. 避坑 / 常见问题 / 排查:那些让你对着示波器抓狂、却只因一个位没设对的瞬间
4.1 现象:串口助手显示乱码(如 ),但波特率计算确认无误
原因:LL_USART_InitTypeDef 结构体中的 OverSampling 字段设置错误。STM32U5 的 USART 支持 16 倍和 8 倍过采样。如果你的波特率是 115200,而 OverSampling 错误地设为了 LL_USART_OVERSAMPLING_8,那么实际波特率会变成 115200 * 2 = 230400,导致接收端采样点偏移,解码出错。
解决:严格对照参考手册(RM0453)第 42.4.11 节的波特率计算公式。对于大多数应用,务必使用 LL_USART_OVERSAMPLING_16。这是最稳定、误差最小的模式。检查你的初始化代码,确保 USART_InitStruct.OverSampling = LL_USART_OVERSAMPLING_16; 这一行存在且未被注释。
4.2 现象:printf 输出偶尔丢失最后几个字符(如 printf("Done!"); 只显示 Don)
原因:_write 函数返回后,printf 认为输出已完成,但此时最后一个字符可能还卡在 UART 的发送数据寄存器(TDR) 或移位寄存器里,尚未真正发出。printf 的缓冲区已经清空,程序继续执行,而 UART 还在后台默默工作。
解决:在 main() 函数的末尾,或者在你认为“所有调试输出都该结束”的地方,添加一个强制等待发送完成的语句:
c复制// 在 main() 的 return 0; 之前加入
while (!LL_USART_IsActiveFlag_TC(USART1)); // 等待最后一个字符发送完毕
这行代码确保了程序退出前,UART 的“最后一口气”已经呼出。对于非阻塞式实现,你可以在 main() 结束前,先关闭 UART 中断,然后轮询 TC 标志直到为真。
4.3 现象:在 SysTick_Handler 中调用 printf,系统崩溃或进入 HardFault
原因:_write 函数(尤其是非阻塞式)内部调用了 UART1_TxBuffer_Put 等函数,这些函数访问了全局变量 uart_tx_head 和 uart_tx_tail。在 SysTick_Handler 这种高优先级中断里,如果此时主循环也正在修改这些变量(例如另一个 printf 正在往缓冲区写),就会发生竞态条件(Race Condition),导致缓冲区指针错乱,后续发送逻辑崩溃。
解决:在所有访问共享缓冲区的临界区(Critical Section)内,临时关闭全局中断。修改 UART1_TxBuffer_Put 和 UART1_TxBuffer_Get 函数:
c复制static uint8_t UART1_TxBuffer_Put(uint8_t c)
{
__disable_irq(); // 关闭全局中断
uint16_t next_head = (uart_tx_head + 1) % UART_TX_BUFFER_SIZE;
uint8_t result = 0;
if (next_head != uart_tx_tail) {
uart_tx_buffer[uart_tx_head] = c;
uart_tx_head = next_head;
result = 1;
}
__enable_irq(); // 恢复全局中断
return result;
}
// 同理,修改 UART1_TxBuffer_Get 函数,也在临界区内加 __disable_irq() / __enable_irq()
这是保护共享资源最直接有效的方法。虽然会短暂影响实时性,但对于调试信息这种非关键任务,是完全可以接受的代价。
4.4 现象:printf 输出正常,但 scanf 或 getchar() 完全不工作
原因:你只实现了 _write,而没有实现 _read。scanf 的底层依赖 _read 函数来从 stdin(文件描述符 0)读取数据。_read 的默认实现同样是半主机,所以它依然需要调试器。
解决:如果你确实需要输入功能,必须同时实现 _read。但这会显著增加复杂度(需要处理接收中断、接收缓冲区、超时等)。对于绝大多数调试场景,printf 单向输出已足够。请明确你的需求:是“诊断”还是“交互”?前者只需 _write,后者才需 _read。不要为了一个用不到的功能,给代码增加不必要的风险和维护成本。
4.5 现象:使用 printf 输出浮点数(%f)时,编译报错 undefined reference to _printf_float``
原因:ARM libc 的 printf 浮点支持是一个独立的、体积庞大的链接单元。默认情况下,链接器为了节省 Flash 空间,会将其排除在外。
解决:在你的工程链接脚本(.ld 文件)或 IDE 的链接器设置中,强制链接浮点 printf 库。在 Keil MDK 中,勾选 Use MicroLIB 选项(它不支持浮点)或在 Options for Target -> Linker -> Library Configuration 中选择 Use Full Library。在 STM32CubeIDE 中,在 Project Properties -> C/C++ Build -> Settings -> Tool Settings -> MCU GCC Linker -> Libraries 中,添加 -u _printf_float 到 Other flags。记住,这会增加约 4-6KB 的 Flash 占用,务必权衡利弊。
5. 进阶技巧:用 __attribute__((section(".my_printf_section"))) 把 printf 输出重定向到任意内存区域,实现“日志快照”
5.1 为什么需要内存重定向?——当串口线缆成为瓶颈时
在某些极端场景下,比如你需要记录长达 10 秒的高速传感器数据(每毫秒一个 printf("X:%d,Y:%d,Z:%d\n", x,y,z);),即使波特率设为 921600,串口的物理带宽(约 115KB/s)也会成为瓶颈,导致大量数据丢失或 printf 被阻塞。这时,把日志“暂存”到 RAM 里,等采集结束后再一次性通过 USB 或 SD 卡导出,就成了唯一可行的方案。
5.2 实现:自定义 _write,将字符写入指定内存段
核心思想是:修改 _write,让它不调用 UART,而是把字符追加到一块预分配的 RAM 缓冲区里。我们可以利用 GCC 的 section 属性,将这块缓冲区放在一个独立的、易于识别的内存段中。
c复制// 在 .c 文件顶部,定义一个 4KB 的日志缓冲区,并将其放在名为 ".log_ram" 的段中
#define LOG_BUFFER_SIZE (4*1024)
__attribute__((section(".log_ram"))) static uint8_t log_buffer[LOG_BUFFER_SIZE];
static volatile uint32_t log_write_ptr = 0;
static volatile uint32_t log_read_ptr = 0;
// 自定义的内存重定向 _write
int _write(int fd, char *ptr, int len)
{
int i;
if ((fd != 1) && (fd != 2)) {
return -1;
}
for (i = 0; i < len; i++) {
// 简单的环形缓冲区写入
if (log_write_ptr < LOG_BUFFER_SIZE) {
log_buffer[log_write_ptr++] = (uint8_t)(*ptr++);
} else {
// 缓冲区满,可以选择覆盖最老的数据(实现为环形)
log_buffer[log_read_ptr++ % LOG_BUFFER_SIZE] = (uint8_t)(*ptr++);
}
}
return len;
}
// 提供一个函数,用于将当前日志内容复制到外部存储(如 USB CDC 的 IN 端点)
uint32_t Log_Buffer_GetData(uint8_t *dest, uint32_t max_len)
{
uint32_t available = (log_write_ptr >= log_read_ptr) ?
(log_write_ptr - log_read_ptr) :
(LOG_BUFFER_SIZE - log_read_ptr + log_write_ptr);
uint32_t copy_len = (available < max_len) ? available : max_len;
if (log_write_ptr >= log_read_ptr) {
// 数据是连续的
memcpy(dest, &log_buffer[log_read_ptr], copy_len);
} else {
// 数据是环形的,需要分两段拷贝
uint32_t first_part = LOG_BUFFER_SIZE - log_read_ptr;
memcpy(dest, &log_buffer[log_read_ptr], first_part);
memcpy(dest + first_part, log_buffer, copy_len - first_part);
}
log_read_ptr = (log_read_ptr + copy_len) % LOG_BUFFER_SIZE;
return copy_len;
}
5.3 如何在链接脚本中为 .log_ram 段分配内存?
你需要编辑你的 .ld 链接脚本(如 STM32U575ZITX_FLASH.ld),在 MEMORY 区域中为 RAM 分配一块空间,并在 SECTIONS 中声明该段:
ld复制/* 在 MEMORY 区域中,确保有足够的 RAM */
MEMORY
{
RAM (xrw) : ORIGIN = 0x20000000, LENGTH = 512K
/* 为日志缓冲区单独划出 4KB */
LOG_RAM (rw) : ORIGIN = 0x2007F000, LENGTH = 4K
}
/* 在 SECTIONS 中,将 .log_ram 段映射到 LOG_RAM 区域 */
SECTIONS
{
.log_ram (NOLOAD) :
{
. = ALIGN(4);
*(.log_ram)
. = ALIGN(4);
} > LOG_RAM
}
这样,log_buffer 就会被精确地放置在 RAM 的 0x2007F000 地址开始的 4KB 空间里,不会与堆栈或其他变量冲突。
5.4 最后的实战验证:用逻辑分析仪抓取 printf 的真实波形,确认你没被库函数“骗”
理论再完美,也要用仪器说话。这是检验你重定向是否成功的终极手段。拿出你的 Saleae 或类似的逻辑分析仪,探头接在 PA9(UART1_TX)上,设置采样率为 1MS/s,捕获一段 printf("OK\n"); 的波形。
你应该看到:
- 一个起始位(低电平,约 8.68μs @115200bps);
- 8 个数据位(
O的 ASCII 是0x4F,二进制01001111,LSB 在前,所以波形应为11110010); - 一个停止位(高电平,约 8.68μs);
- 紧接着是
\n(0x0A,二进制00001010,波形01010000); - 最后是另一个停止位。
关键观察点:两个字符之间的间隔。如果是阻塞式 _write,你会看到 OK 之间几乎没有间隔(因为 while 等待 TC,而 TC 在停止位结束时就置位了)。如果是非阻塞式,间隔会稍长一些,因为中间有缓冲区操作和中断响应的时间。
从那以后我每次在新项目里接入 printf,都强制走一遍这个流程:先用阻塞式快速验证硬件连接和基础配置,再立刻切换到非阻塞式+中断+临界区保护的完整方案,并用逻辑分析仪抓一次波形。这三步做完,我才敢说,“我的调试通道,是真正属于这块芯片的,而不是属于那个随时可能被拔掉的调试器的”。希望帮到你。
