嵌入式开发中printf重定向与环形缓冲区实现非阻塞串口日志-育师

1. 为什么要在嵌入式里折腾printf？

在嵌入式开发里，尤其是用Keil、IAR这类IDE玩51、STM32、AVR单片机时，调试是个老大难。串口打印信息是最直接、最有效的调试手段，没有之一。但原生的printf函数，在资源受限的MCU上，常常是个“性能杀手”。

最典型的问题就是阻塞。当你调用printf向串口发送一个字符串时，程序会卡在那里，等待串口一个字节一个字节地发完。如果波特率是115200，发一句“Hello World”可能就要等上近1毫秒。在实时性要求高的系统里，比如一个电机控制中断服务函数（ISR）里，这1毫秒的阻塞足以让系统失控。更糟的是，如果串口发送被意外阻塞（比如线没接好），整个程序都可能挂起。

另一个问题是中断安全。想象一下，主循环和定时器中断都在调用printf打印日志，如果没有保护机制，两边的数据会搅在一起，输出一堆乱码，调试信息完全不可读。

所以，老手们常干一件事：重定向printf。也就是把C标准库里的printf输出，从默认的控制台（PC上）改道到我们的串口。但仅仅重定向还不够，我们得给它加个“缓冲队列”，这就是环形缓冲区（Circular Buffer）的用武之地。它的核心思想是：printf不再直接、阻塞地操作硬件串口，而是把要打印的字符串快速扔进一个先入先出（FIFO）的软件缓冲区，然后由一个后台任务（或中断）不紧不慢地从缓冲区取出数据，发送给串口。这样，调用printf的函数几乎可以瞬间返回，把耗时且可能阻塞的硬件操作留给后台。

结合网络上的热词，大家关心的无非是几件事：怎么在Keil里让printf支持负数（这涉及到底层putchar的实现和格式库选择）；怎么用GCC/Clang的函数属性来安全地封装我们自定义的printf风格函数，让编译器帮我们检查格式字符串和参数是否匹配；以及，如何构建一个高效、线程/中断安全的环形缓冲区来承载这些数据。接下来，我们就一步步拆解，把这套机制从原理到代码，彻底搞明白。

2. 环形缓冲区：核心数据结构与操作原理解析

环形缓冲区，也叫循环缓冲区，是一种非常经典的数据结构，特别适合解决生产者-消费者问题。在我们的场景里，printf是生产者，负责往缓冲区里写数据；串口发送中断（或后台任务）是消费者，负责从缓冲区里读数据并发送。

2.1 环形缓冲区的结构设计

一个最简单的环形缓冲区通常需要以下几个成员：

一个数组：buffer[BUFFER_SIZE]，用于存储数据（通常是uint8_t类型，对应字节）。
两个索引：write_index（写指针）和read_index（读指针）。
一个缓冲区大小：BUFFER_SIZE。

它的工作原理很像一个圆环。写指针指向下一个要写入的位置，读指针指向下一个要读取的位置。初始时，两者都指向0。

typedef struct { uint8_t buffer[BUFFER_SIZE]; volatile size_t write_index; // 生产者修改 volatile size_t read_index; // 消费者修改 // 注意：在中断与主程序共享的场景下，必须加volatile防止编译器优化 } circular_buffer_t;

这里的关键是索引的增长方式。不是简单的++，而是(index + 1) % BUFFER_SIZE。这确保了当索引到达数组末尾时，会绕回到开头，形成一个“环”。

write_index = (write_index + 1) % BUFFER_SIZE;

2.2 空与满的状态判断

这是环形缓冲区最容易出错的地方。一个常见的陷阱是：当写指针追赶上读指针时，表示缓冲区已满；当读指针追赶上写指针时，表示缓冲区为空。但如果只用相等来判断，你会发现“空”和“满”的状态无法区分（都是write_index == read_index）。

方案一：保留一个空位最经典和可靠的方法是永远让缓冲区至少保留一个空位。我们定义：

空：write_index == read_index
满：(write_index + 1) % BUFFER_SIZE == read_index

这意味着，一个大小为BUFFER_SIZE的缓冲区，实际只能存储BUFFER_SIZE - 1个字节。虽然牺牲了一个字节的空间，但换来了逻辑的清晰和判断的简单，在嵌入式这种追求确定性的环境中，这是值得的。

方案二：使用一个独立的计数器另一种方法是增加一个count变量，记录缓冲区中当前有效数据的数量。

空：count == 0
满：count == BUFFER_SIZE

这种方法逻辑直观，但需要多维护一个变量，并且在多生产者/消费者场景下，对这个count的读写也需要保护。

对于我们的printf重定向场景，我强烈推荐方案一。原因有三：1）逻辑简单，不易出错；2）在中断服务函数中执行的操作越少越好，方案一只需比较两个索引，速度快；3）在8位、32位MCU上，对两个整数的比较和取模运算是原子操作（或可视为原子），而方案二对count的修改（++或--）可能不是原子的，需要额外的保护（如关中断），增加了复杂度。

2.3 关键操作：写与读

写操作（生产者，即我们的printf封装函数）：

检查缓冲区是否已满。
如果未满，将数据写入buffer[write_index]。
更新write_index = (write_index + 1) % BUFFER_SIZE。
如果消费者（如串口发送中断）在等待数据，此时需要“唤醒”它。在我们的场景下，就是检查串口发送数据寄存器是否为空，如果为空且之前缓冲区是空的，则立刻启动一次发送。

读操作（消费者，通常在串口发送完成中断中）：

检查缓冲区是否为空。
如果不为空，从buffer[read_index]读取数据。
将读取的数据写入串口的数据寄存器（如USART_DR）。
更新read_index = (read_index + 1) % BUFFER_SIZE。

这里有一个非常重要的细节：索引的更新时机。必须在数据确实被放入缓冲区或从缓冲区取出之后，才能更新索引。这个顺序不能错，否则会导致数据丢失或重复。

注意：中断与主循环的数据竞争在我们的设计里，printf可能在主循环中被调用，也可能在任何一个中断服务函数中被调用。而串口发送完成中断是另一个中断。这就构成了一个“多生产者（任何调用printf的地方）-单消费者（串口发送中断）”的模型。保护共享资源（环形缓冲区）最简单粗暴也最有效的方法是：在写操作时关中断。因为写操作非常快（只是存一个字节和更新索引），关中断的时间极短，通常不会影响系统实时性。具体操作是：在printf向缓冲区写入数据前，关闭全局中断，写入完成后立即打开。而读操作在串口中断里进行，中断本身具有排他性，所以不需要额外保护。

3. 重定向printf：打通库函数到硬件的桥梁

C标准库中的printf最终会调用一个名为_write或fputc的低级函数（取决于工具链和库的实现），将字符输出到文件描述符。我们的目标就是“劫持”这个函数，让它把字符送到我们的环形缓冲区，而不是默认的标准输出。

3.1 针对ARM Cortex-M（如STM32，使用GCC/ARMCC）

在ARM开发中，常用的是重写_write系统调用或fputc。

方法A：重写_write（使用ARM MicroLib或newlib-nano时）如果你的工程使用了Keil的MicroLib或者GCC的newlib-nano，可以重写这个函数。

#include <unistd.h> // 提供STDOUT_FILENO等定义 #include “circular_buffer.h” // 你的环形缓冲区头文件 extern circular_buffer_t tx_buffer; // 声明全局的发送缓冲区 int _write(int file, char *ptr, int len) { int i; if (file == STDOUT_FILENO || file == STDERR_FILENO) { // 只处理标准输出和错误输出 for (i = 0; i < len; i++) { // 调用环形缓冲区的写函数（该函数内部应有关中断保护） if (circular_buffer_put(&tx_buffer, ptr[i]) == BUFFER_FULL) { // 缓冲区满，可以在这里选择等待或丢弃字符。 // 对于调试日志，丢弃尾部数据可能是可接受的。 break; } } // 尝试启动发送（如果串口空闲） uart_start_tx_if_needed(); return i; // 返回成功写入的字符数 } return -1; // 对其他文件描述符返回错误 }

方法B：重写fputc（更通用）有些库的实现会调用fputc。

#include <stdio.h> #include “circular_buffer.h” extern circular_buffer_t tx_buffer; int fputc(int ch, FILE *f) { (void)f; // 避免未使用参数警告 // 将字符送入缓冲区 if (circular_buffer_put(&tx_buffer, (uint8_t)ch) != BUFFER_OK) { return EOF; // 写入失败 } // 尝试启动发送 uart_start_tx_if_needed(); return ch; // 成功则返回字符本身 }

3.2 针对8051（如Keil C51）

在Keil C51中，情况比较特殊。它的printf默认通过串口0输出，但格式处理库是裁剪版的，默认可能不支持浮点数或长整型。你需要做两件事：

确保链接了正确的库：在Keil的Target Options -> Target中，勾选“Use MicroLIB”可能有助于减小代码体积，但有时需要手动在项目中添加printf相关的源文件（如printf.c）来获得完整功能，特别是打印负数(%d)和长整型(%ld)的支持。网上热词“keil51 printf打印负数”的问题，根源往往就在这里。
重定向putchar：Keil C51的printf底层会调用putchar函数。你只需要重写它。

#include <stdio.h> #include “circular_buffer.h” extern circular_buffer_t tx_buffer; char putchar(char c) { while (circular_buffer_put(&tx_buffer, (uint8_t)c) == BUFFER_FULL) { // 缓冲区满，可以选择忙等待（不推荐）或丢弃。 // 对于51，关中断保护可能用 `EA = 0;` ... `EA = 1;` } uart_start_tx_if_needed(); // 启动发送 return c; }

3.3 解决printf变参传递与编译器检查

我们常常想封装一个自己的打印函数，比如log_printf(“Value: %d”, value)，它内部调用我们缓冲区的版本。这里就涉及到网络热词中的“如何用 gcc/clang 的函数属性”。

GCC和Clang提供了__attribute__((format(printf, m, n)))属性。m是格式字符串参数的位置（从1开始计数），n是第一个可变参数的位置。

// 在头文件中声明 void log_printf(const char *format, ...) __attribute__((format(printf, 1, 2))); // 在.c文件中实现 void log_printf(const char *format, ...) { va_list args; va_start(args, format); // 关键：使用vsnprintf或类似的函数，将格式化的结果输出到我们的缓冲区 int needed = vsnprintf(NULL, 0, format, args); // 第一次调用，计算所需长度 va_end(args); if (needed < 0) return; char *temp_buffer = malloc(needed + 1); // 临时分配内存（嵌入式慎用malloc！） if (!temp_buffer) return; va_start(args, format); vsnprintf(temp_buffer, needed + 1, format, args); va_end(args); // 将temp_buffer中的字符逐个放入环形缓冲区 for (int i = 0; i < needed; i++) { circular_buffer_put(&tx_buffer, temp_buffer[i]); } free(temp_buffer); uart_start_tx_if_needed(); }

重要提示：在资源极度紧张的嵌入式系统（如无动态内存分配的RTOS环境）中，应避免使用malloc。替代方案是使用一个在栈上分配的固定大小的临时数组，但需要小心缓冲区溢出。更稳健的做法是，实现一个vsnprintf到环形缓冲区的直接写入版本，这需要更深入的定制。

添加了format属性后，如果你调用log_printf(“%s”, 123)，编译器就会给出警告，提示格式字符串与参数类型不匹配，这能极大减少运行时错误。

4. 串口驱动与中断的协同设计

环形缓冲区是数据的仓库，串口中断是搬运工。如何高效、可靠地驱动这个搬运工，是系统稳定的关键。

4.1 发送启动与中断触发策略

我们的目标是：只要有数据在缓冲区，就尽量让串口处于发送状态。

初始化：

配置串口为发送使能，但先不使能发送完成中断。
初始化环形缓冲区为空。

写入数据后的启动流程（在_write或fputc中调用）：

void uart_start_tx_if_needed(void) { // 关中断以保证判断和操作的原子性 uint32_t primask = __get_PRIMASK(); // ARM Cortex-M __disable_irq(); // 如果串口发送数据寄存器为空（TC或TXE标志为1），且缓冲区有数据 if ((USART1->SR & USART_SR_TXE) && !circular_buffer_is_empty(&tx_buffer)) { uint8_t data; circular_buffer_get(&tx_buffer, &data); // 从缓冲区取一个字节 USART1->DR = data; // 写入数据寄存器，启动发送 // 此时，一旦这个字节发送完成，TXE会再次置1，但我们还没开中断，所以不会进入中断 } // 现在，使能发送数据寄存器空中断（TXEIE）。 // 这样，当前字节发送完成后，或如果当前没有在发送，就会立即进入中断。 USART1->CR1 |= USART_CR1_TXEIE; __set_PRIMASK(primask); // 恢复中断状态 }

串口发送中断服务函数：

void USART1_IRQHandler(void) { // 检查是否是发送数据寄存器空中断 if (USART1->SR & USART_SR_TXE) { uint8_t data; if (circular_buffer_get(&tx_buffer, &data) == BUFFER_OK) { // 缓冲区还有数据，取出下一个并写入DR USART1->DR = data; } else { // 缓冲区已空，禁止发送数据寄存器空中断，防止持续进入中断 USART1->CR1 &= ~USART_CR1_TXEIE; // 可以在这里置一个标志，通知主循环“发送完毕” } } // ... 可能还需要处理其他中断（如接收中断） }

这个设计的精妙之处在于中断的按需启用/禁用。只有当缓冲区有数据需要发送时，才打开TXE中断。一旦缓冲区清空，立即关闭中断。这避免了在无事可做时，串口硬件持续产生中断，浪费CPU资源。

4.2 处理缓冲区满与数据流控

当生产速度（调用printf的频率）持续高于消费速度（串口波特率）时，缓冲区最终会满。这时circular_buffer_put会返回BUFFER_FULL。你有几种策略：

丢弃新数据：最简单的做法，直接丢弃无法写入的字符。对于调试日志，丢失一些最新的信息有时是可以接受的，毕竟最旧的日志可能更重要。可以在_write函数中记录一个丢弃计数器。
忙等待：在put函数里循环等待，直到有空间空出。这非常危险，如果消费者因为某种原因停止（如串口故障），会导致整个系统死锁。绝对要避免在主循环或高优先级中断中忙等待。
阻塞式等待（带超时）：在RTOS环境中，可以让任务在缓冲区满时挂起，等待一个信号量。当消费者从缓冲区取走数据后，释放信号量唤醒生产者任务。这需要集成RTOS的同步机制。
增加缓冲区大小：最直接的物理方案。根据你的最坏情况数据产生速率和消费速率，计算所需的缓冲区大小。例如，最高频率的中断每秒调用printf1000次，每次平均10字节，那么1秒需要10000字节。如果波特率是115200（约每秒11520字节），那么缓冲区至少需要能容纳约1秒的数据量（10000字节）。考虑到峰值，可以再乘以一个安全系数（如1.5）。

对于大多数裸机嵌入式应用，策略1（丢弃）结合策略4（合理设计缓冲区大小）是务实的选择。可以在_write函数中实现一个简单的“丢弃”逻辑，并输出一个警告标记，如<OVERFLOW>，让开发者知道发生了数据丢失。

5. 实战步骤：从零构建定制化printf系统

现在，我们把所有模块组合起来，形成七个清晰的步骤。

5.1 步骤一：定义环形缓冲区结构与API

在circular_buffer.h中：

#ifndef CIRCULAR_BUFFER_H #define CIRCULAR_BUFFER_H #include <stdint.h> #include <stdbool.h> #include <stddef.h> #define BUFFER_SIZE 256 // 根据实际需求调整，建议为2的幂次方，便于优化 typedef enum { BUFFER_OK, BUFFER_FULL, BUFFER_EMPTY } buffer_status_t; typedef struct { uint8_t data[BUFFER_SIZE]; volatile size_t write_index; volatile size_t read_index; } circular_buffer_t; void circular_buffer_init(circular_buffer_t *cb); buffer_status_t circular_buffer_put(circular_buffer_t *cb, uint8_t byte); buffer_status_t circular_buffer_get(circular_buffer_t *cb, uint8_t *byte); bool circular_buffer_is_empty(circular_buffer_t *cb); bool circular_buffer_is_full(circular_buffer_t *cb); size_t circular_buffer_available(circular_buffer_t *cb); // 可读数据量 size_t circular_buffer_free(circular_buffer_t *cb); // 剩余空间 #endif

在circular_buffer.c中实现。注意put和get函数内部需要关中断保护（以ARM Cortex-M为例）：

buffer_status_t circular_buffer_put(circular_buffer_t *cb, uint8_t byte) { uint32_t primask = __get_PRIMASK(); __disable_irq(); buffer_status_t status = BUFFER_OK; size_t next_write = (cb->write_index + 1) % BUFFER_SIZE; if (next_write == cb->read_index) { status = BUFFER_FULL; } else { cb->data[cb->write_index] = byte; cb->write_index = next_write; } __set_PRIMASK(primask); return status; }

5.2 步骤二：初始化硬件串口

在你的uart.c中，初始化串口引脚、时钟、波特率等。关键点：初始化时只使能发送功能(TE)，不要使能发送中断(TXEIE)。中断由我们的软件逻辑控制。

5.3 步骤三：实现串口发送中断服务函数

如上文4.1节所示，实现USARTx_IRQHandler。其核心就是从环形缓冲区取数据，如果取到就发送，取不到就关闭中断。

5.4 步骤四：实现启动发送函数

实现uart_start_tx_if_needed()函数。这个函数在每次向环形缓冲区写入数据后都可能被调用。它的职责是：如果串口发送器空闲（TXE为1）且缓冲区有数据，则手动取出第一个字节启动发送，并确保发送中断是使能的，以便后续字节由中断自动处理。

5.5 步骤五：重定向printf底层函数

根据你的编译器和目标芯片，选择重写_write、fputc或putchar。在这个函数里，将字符ch通过circular_buffer_put放入缓冲区，然后调用uart_start_tx_if_needed()。记得处理缓冲区满的情况（例如，记录丢弃或直接返回错误）。

5.6 步骤六：封装自定义日志函数（可选但推荐）

使用__attribute__((format(printf, 1, 2)))封装一个更安全的log_printf。如果你无法使用动态内存，可以定义一个足够大的栈上字符数组作为临时格式化缓冲区。

#define LOG_BUFFER_SIZE 128 void log_printf(const char *format, ...) __attribute__((format(printf, 1, 2))); void log_printf(const char *format, ...) { va_list args; char temp_buf[LOG_BUFFER_SIZE]; va_start(args, format); int len = vsnprintf(temp_buf, LOG_BUFFER_SIZE, format, args); va_end(args); if (len > 0 && len < LOG_BUFFER_SIZE) { for (int i = 0; i < len; i++) { // 这里可以加入日志等级过滤、时间戳等 circular_buffer_put(&tx_buffer, temp_buf[i]); } uart_start_tx_if_needed(); } else { // 处理截断或错误 const char err[] = “[LOG TRUNC]”; for (size_t i = 0; i < sizeof(err)-1; i++) { circular_buffer_put(&tx_buffer, err[i]); } uart_start_tx_if_needed(); } }

5.7 步骤七：集成与测试

在main.c中，初始化环形缓冲区、初始化串口。
在需要打印的地方，放心地使用printf或log_printf。
在main函数的超级循环中，你几乎不需要再为串口发送操心。中断会处理好一切。
进行压力测试：在一个定时器中断里以最高频率调用printf打印一段信息，观察串口输出是否连续、是否正确，以及系统其他关键任务（如LED闪烁、按键扫描）是否受影响。

6. 避坑指南与性能优化要点

在实际项目中，我踩过不少坑，这里总结几个关键点：

坑一：缓冲区大小选择不当一开始我用了128字节的缓冲区，在一个电机控制项目中，ISR里偶尔会打印调试信息。平时没事，一旦电机堵转，ISR打印频率暴增，缓冲区瞬间写满，导致后续重要的错误信息丢失。后来我根据最坏情况计算了数据量，将缓冲区扩大到1024字节，问题解决。建议：缓冲区大小应大于“最大突发数据量”。可以写一个函数circular_buffer_get_usage_peak()来在调试阶段监测缓冲区的历史最高使用率。

坑二：关中断时间过长早期版本的circular_buffer_put函数，我为了保护临界区，关了中断后还做了一些非必要的计算和检查，导致关中断时间超过10微秒，影响了另一个需要精确定时的PWM中断。优化后：关中断的区域内只做最核心的“检查-写入-更新索引”操作，任何可以移到临界区外的计算（比如判断下一个索引位置）都先算好。将关中断时间压缩到最少。

坑三：在中断服务函数中使用printf这本身不是坑，而是我们设计要支持的特性。但要注意，中断里的printf要尽可能简短。避免在中断里打印很长的字符串或进行复杂的格式化（如浮点数%f），因为格式化函数（如vsnprintf）本身可能比较耗时。如果一定要在中断中打印，可以考虑先只将原始数据和格式代码存入另一个缓冲区，由主循环进行实际的格式化输出。

坑四：多个串口输出如果系统有多个串口（如UART1用于调试，UART2用于通信），需要为每个串口维护独立的环形缓冲区和中断服务函数。全局的printf通常只重定向到一个主要调试串口。对于其他串口，应使用独立的封装函数，如uart2_printf。

性能优化建议：

使用2的幂次方作为缓冲区大小：这样可以将取模运算index % BUFFER_SIZE优化为位与运算index & (BUFFER_SIZE - 1)，速度更快。但前提是BUFFER_SIZE是2的幂次方（如256，512，1024）。
使用内存屏障：在Cortex-M等架构上，对于volatile变量的访问，有时编译器优化仍可能带来意外顺序。在put和get函数的临界区开始和结束，可以使用__DSB()、__ISB()等内存屏障指令，确保内存操作的顺序性。
提供非阻塞API：除了circular_buffer_put，可以提供circular_buffer_try_put，它在缓冲区满时立即返回BUFFER_FULL，而不是等待。这在实时性要求极高的代码段中非常有用。

7. 进阶扩展：添加时间戳与日志等级

一个工业级的日志输出系统，光有printf还不够。我们通常需要知道日志发生的时间，以及它的严重程度（调试信息、警告、错误）。

时间戳：可以在log_printf函数内部，在格式化字符串之前，读取一个系统时钟计数（如SysTick计数器、或一个由定时器维护的32位毫秒计数器），然后将其格式化为字符串插入到日志开头。

uint32_t timestamp = get_system_tick_ms(); char prefix[32]; snprintf(prefix, sizeof(prefix), “[%08lu] “, timestamp); // 将prefix写入缓冲区，再将格式化后的消息写入缓冲区

日志等级：定义几个宏，如LOG_DEBUG,LOG_INFO,LOG_WARN,LOG_ERROR。在编译时可以通过宏定义（如-DLOG_LEVEL=LOG_LEVEL_INFO）来过滤掉低于该等级的日志。在log_printf函数中，首先判断等级，如果低于全局设定等级，则直接返回，不进行任何格式化或缓冲操作，这几乎零开销。

#define LOG_LEVEL_DEBUG 0 #define LOG_LEVEL_INFO 1 #define LOG_LEVEL_WARN 2 #define LOG_LEVEL_ERROR 3 #define LOG_LEVEL_NONE 4 #ifndef LOG_LEVEL #define LOG_LEVEL LOG_LEVEL_DEBUG #endif #define LOG(level, format, ...) do { \ if (level >= LOG_LEVEL) { \ log_printf_internal(level, format, ##__VA_ARGS__); \ } \ } while(0) #define LOG_DEBUG(format, ...) LOG(LOG_LEVEL_DEBUG, “[D] “ format, ##__VA_ARGS__) #define LOG_INFO(format, ...) LOG(LOG_LEVEL_INFO, “[I] “ format, ##__VA_ARGS__)

这样，在代码中就可以使用LOG_INFO(“System started.”)，输出类似[I] System started.的格式化信息，并且在发布版本中通过设置LOG_LEVEL为LOG_LEVEL_ERROR来屏蔽所有调试和信息日志，只保留错误信息，既保证了调试的便利性，又不会影响最终产品的性能。