单片机与物联网 / 系统课时

串口日志调试

串口日志调试

本课完成一套适用于 STM32 HAL 工程的最小串口日志方案:将 printf 输出重定向到 UART,增加日志级别和模块标签,并分析阻塞发送对实时任务的影响。完成后,你可以用终端连续观察程序状态,同时知道何时应升级为中断或 DMA 日志。

学习目标

  • 将标准输出重定向到 STM32 串口
  • 设计可筛选的分级日志格式
  • 识别并降低日志阻塞、丢失和干扰时序的风险

建立最小日志通道

示例假设 STM32CubeMX 已生成 USART2,句柄名称为 huart2,编译器使用 GCC/Newlib,串口终端参数与 CubeMX 保持一致。下面代码可放入 main.c 的用户代码区,它依赖 HAL 工程,不能脱离具体芯片独立运行。

c
#include "main.h"
#include <stdarg.h>
#include <stdio.h>

extern UART_HandleTypeDef huart2;

typedef enum {
    LOG_LEVEL_ERROR = 0,
    LOG_LEVEL_WARN,
    LOG_LEVEL_INFO,
    LOG_LEVEL_DEBUG
} LogLevel;

static LogLevel current_level = LOG_LEVEL_INFO;

int _write(int file, char *ptr, int len)
{
    (void)file;

    // 阻塞发送适合低频调试,超时用于避免永久卡死
    HAL_StatusTypeDef status = HAL_UART_Transmit(
        &huart2,
        (uint8_t *)ptr,
        (uint16_t)len,
        100
    );

    return status == HAL_OK ? len : -1;
}

static const char *level_name(LogLevel level)
{
    static const char *names[] = {"ERROR", "WARN", "INFO", "DEBUG"};
    return names[level];
}

void log_print(LogLevel level, const char *module, const char *format, ...)
{
    if (level > current_level) {
        return;
    }

    char message[128];
    va_list args;
    va_start(args, format);
    vsnprintf(message, sizeof(message), format, args);
    va_end(args);

    printf("[%lu][%s][%s] %s\r\n",
           (unsigned long)HAL_GetTick(),
           level_name(level),
           module,
           message);
}

void log_demo(void)
{
    log_print(LOG_LEVEL_INFO, "APP", "system started");
    log_print(LOG_LEVEL_DEBUG, "ADC", "raw=%u", 2048U);
    log_print(LOG_LEVEL_ERROR, "SENSOR", "read timeout");
}

预期输出

text
[<TIME>][INFO][APP] system started
[<TIME>][ERROR][SENSOR] read timeout

在 main() 完成外设初始化后调用 log_demo()。<TIME> 是 HAL_GetTick() 返回的毫秒计数,实际值会不同。当前级别为 INFO,因此 DEBUG 日志被过滤。

设计格式并控制输出开销

一条实用日志至少应包含时间、级别、模块和事件。错误日志记录导致功能失败的信息;警告日志记录可恢复但值得关注的异常;信息日志记录启动、连接和状态切换;调试日志记录内部数据。发布版本通常关闭 DEBUG,以减少带宽和格式化计算。

日志文本应包含对象、动作、结果和关键参数。sensor read failed, status=3 比单独输出“失败”更容易检索,也能直接支持根因判断。固定字段顺序还能让终端脚本或日志工具稳定解析。

串口常用的 8N1 格式每个字符需要 10 位。一条 100 字节日志在 115200 bit/s 下,理论发送时间约为:

t=100×10115200≈8.68 mst = \frac{100 \times 10}{115200} \approx 8.68\text{ ms}

如果控制任务每 1 ms 执行一次,直接调用阻塞式 printf 会明显破坏调度。浮点格式化还会增加 CPU 开销和固件体积,因此嵌入式日志应限制长度、频率和数据类型。

STM32 串口日志数据流

避免阻塞并验证可靠性

中断服务函数中不应调用阻塞式 printf。发送可能持续数毫秒,还可能依赖中断推进,造成优先级反转、嵌套延迟甚至死锁。更安全的做法是在中断中只记录事件码或写入环形缓冲区,由主循环或低优先级任务统一发送。

高频日志应采用“生产者写缓冲区,UART 中断或 DMA 消费”的结构。缓冲区满时必须明确选择丢弃最新日志、覆盖最旧日志或累计丢弃计数,不能让关键任务无限等待。多个 RTOS 任务同时写日志时,可用互斥锁保护格式化与入队,但中断中不得获取普通互斥锁。

验证时先把级别设为 DEBUG,确认三条日志都出现;再改回 INFO,确认 DEBUG 被过滤。随后连续输出多条短日志,检查乱码、缺行和卡顿。乱码通常来自波特率、时钟或帧格式不一致,缺行常见于缓冲区溢出,卡顿则多由阻塞发送引起。

还应暂时关闭终端或断开接收端,确认 HAL_UART_Transmit() 超时后程序仍能继续。若日志失败会阻断核心业务,应改为忽略单次发送错误并累计故障计数。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

串口日志调试

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通