4、打印调试法：串口打印的利与弊、日志分级、环形缓冲区实现

说到嵌入式调试，打印调试法可能是最古老、也最直接的手段了。我刚开始做嵌入式那会儿，手头连个仿真器都没有，全靠一个串口和几根杜邦线过日子。说白了，就是让芯片“开口说话”，告诉我们它内部发生了什么。

但你别小看这个“说话”的过程。用好了，它是利器；用不好，它能把你坑得怀疑人生。这一章，我就跟你聊聊串口打印的门道。

4.1 串口打印：一把双刃剑

串口打印的好处，不用我多说。简单、直观、几乎任何MCU都支持。你只要初始化好UART，然后调用printf，信息就出来了。

但它的坏处，很多人一开始意识不到。我在项目中遇到过好几次，产品在实验室跑得好好的，一上产线或者到现场就出问题。查来查去，最后发现是打印语句惹的祸。

所以，我的建议是：不要把打印当成调试的“万能药”。它更适合用来观察宏观的流程、状态机的跳转、或者关键变量的变化趋势。对于微秒级的时序问题，还是得靠逻辑分析仪或者硬件断点。

4.2 日志分级：让信息“按需分配”

你想想看，如果整个工程里到处都是printf，那会是什么景象？满屏的乱码，有用的信息被淹没在垃圾里。这就是典型的“信息过载”。

解决这个问题，最好的办法就是引入日志分级。说白了，就是给每条打印信息贴个标签，告诉系统：“这条很重要，必须显示”、“这条是调试用的，正式版就别出来了”。

我个人习惯用这五个级别：

级别	宏定义	使用场景
ERROR	LOG_ERROR	系统无法恢复的致命错误，必须立即处理
WARN	LOG_WARN	异常情况，但系统还能继续运行，需要关注
INFO	LOG_INFO	关键流程信息，如系统启动、任务创建、连接成功
DEBUG	LOG_DEBUG	开发阶段的详细调试信息，正式版通常关闭
TRACE	LOG_TRACE	最详细的函数调用跟踪，只在定位棘手问题时开启

实现起来也不复杂。我们可以定义一个全局的日志级别，然后通过宏来控制：

/* log.h */
#define LOG_LEVEL_NONE     0
#define LOG_LEVEL_ERROR    1
#define LOG_LEVEL_WARN     2
#define LOG_LEVEL_INFO     3
#define LOG_LEVEL_DEBUG    4
#define LOG_LEVEL_TRACE    5

/* 当前日志级别，可以在编译时或运行时设置 */
#ifndef CURRENT_LOG_LEVEL
#define CURRENT_LOG_LEVEL   LOG_LEVEL_DEBUG
#endif

#define LOG_ERROR(fmt, ...) \
    do { if (CURRENT_LOG_LEVEL >= LOG_LEVEL_ERROR) \
        printf("[ERROR] " fmt "\r\n", ##__VA_ARGS__); \
    } while(0)

#define LOG_WARN(fmt, ...)  \
    do { if (CURRENT_LOG_LEVEL >= LOG_LEVEL_WARN) \
        printf("[WARN]  " fmt "\r\n", ##__VA_ARGS__); \
    } while(0)

#define LOG_INFO(fmt, ...)  \
    do { if (CURRENT_LOG_LEVEL >= LOG_LEVEL_INFO) \
        printf("[INFO]  " fmt "\r\n", ##__VA_ARGS__); \
    } while(0)

#define LOG_DEBUG(fmt, ...) \
    do { if (CURRENT_LOG_LEVEL >= LOG_LEVEL_DEBUG) \
        printf("[DEBUG] " fmt "\r\n", ##__VA_ARGS__); \
    } while(0)

#define LOG_TRACE(fmt, ...) \
    do { if (CURRENT_LOG_LEVEL >= LOG_LEVEL_TRACE) \
        printf("[TRACE] " fmt "\r\n", ##__VA_ARGS__); \
    } while(0)

4.3 环形缓冲区：让打印不再阻塞

日志分级解决了信息筛选的问题，但阻塞的问题还在。尤其是当你需要在中断服务函数里打印信息时，直接调用printf几乎等于自杀。

怎么办？答案是：生产者-消费者模型。中断服务函数只管把日志“扔”到一个缓冲区里，然后由后台的某个低优先级任务或者主循环，慢慢地把缓冲区里的数据通过串口发出去。

这个缓冲区，最常用的就是环形缓冲区（Ring Buffer）。它就像一个循环的队列，写指针和读指针在内存里追着跑。

下面是一个简单的实现，我曾在多个项目里用过，稳定可靠：

/* ringbuf.h */
typedef struct {
    uint8_t *buffer;
    uint32_t head;      /* 写指针 */
    uint32_t tail;      /* 读指针 */
    uint32_t max_len;   /* 缓冲区总大小 */
} ringbuf_t;

/* 初始化 */
void ringbuf_init(ringbuf_t *rb, uint8_t *buf, uint32_t len);

/* 写入一个字节，返回0成功，-1表示缓冲区满 */
int32_t ringbuf_put(ringbuf_t *rb, uint8_t data);

/* 读取一个字节，返回0成功，-1表示缓冲区空 */
int32_t ringbuf_get(ringbuf_t *rb, uint8_t *data);

/* 查询当前已用空间 */
uint32_t ringbuf_used(ringbuf_t *rb);

/* ringbuf.c */
void ringbuf_init(ringbuf_t *rb, uint8_t *buf, uint32_t len) {
    rb->buffer  = buf;
    rb->head    = 0;
    rb->tail    = 0;
    rb->max_len = len;
}

int32_t ringbuf_put(ringbuf_t *rb, uint8_t data) {
    uint32_t next_head = (rb->head + 1) % rb->max_len;
    /* 如果下一个写指针追上了读指针，说明缓冲区满了 */
    if (next_head == rb->tail) {
        return -1; /* 缓冲区满 */
    }
    rb->buffer[rb->head] = data;
    rb->head = next_head;
    return 0;
}

int32_t ringbuf_get(ringbuf_t *rb, uint8_t *data) {
    if (rb->head == rb->tail) {
        return -1; /* 缓冲区空 */
    }
    *data = rb->buffer[rb->tail];
    rb->tail = (rb->tail + 1) % rb->max_len;
    return 0;
}

uint32_t ringbuf_used(ringbuf_t *rb) {
    return (rb->head - rb->tail + rb->max_len) % rb->max_len;
}

嗯，这里要注意一个细节：判断“满”和“空”。上面的实现里，我们故意浪费了一个字节的空间。当head == tail时，我们认为缓冲区是空的；当(head + 1) % max_len == tail时，我们认为缓冲区是满的。这样做的好处是，不需要额外的变量来记录状态，避免了多任务环境下的竞态条件。

我曾经在一个电机控制项目里，用这个环形缓冲区配合DMA，实现了“零开销”的日志输出。中断里只做ringbuf_put，然后DMA自动从缓冲区取数据发送。CPU几乎感觉不到打印的存在。

4.4 知识体系：打印调试法全景图

下面这张图，帮你把这一章的核心逻辑串起来。从原始的串口打印，到分级管理，再到用环形缓冲区解决阻塞问题，这是一个层层递进的过程。

4.5 避坑指南：我踩过的那些坑

最后，分享几个我亲身经历过的教训，希望能帮你少走弯路。

• 我曾经在一个中断里直接调用了printf，结果导致系统频繁死机。后来用逻辑分析仪一看，一个打印语句占用了将近5毫秒，把下一个中断给活活堵死了。从那以后，我定了个规矩：中断里绝对不允许直接打印。
• 我曾经在调试一个低功耗产品时，开了全级别的日志打印。结果发现，设备永远无法进入休眠模式。查了半天，原来是串口在发送数据时，会阻止系统进入低功耗状态。解决方案很简单：在进入休眠前，关闭串口发送，或者等缓冲区空了再睡。
• 我曾经遇到过环形缓冲区数据被覆盖的问题。排查后发现，是中断和主循环同时访问了同一个缓冲区，没有做保护。解决办法是：在单核MCU上，关闭中断再操作缓冲区；在多核或RTOS环境下，使用临界区或互斥锁。

嗯，打印调试法就聊到这儿。它虽然“土”，但只要你用得巧，它依然是你调试工具箱里最趁手的一把扳手。