Log系统基础：Log等级定义、输出机制与格式规范
在HAL驱动调试中，Log系统是工程师的“眼睛”。一套结构清晰、等级分明的Log系统，能够帮助开发者从海量信息中快速定位问题根源。本章将深入讲解Log的等级定义、输出机制以及标准格式规范，为后续的卡顿故障排查打下坚实基础。
1. Log等级定义（Error / Warning / Info / Debug）
Log等级用于标识一条日志的严重程度或详细程度。合理的等级划分可以让你在调试时快速过滤无关信息，聚焦关键线索。常见的嵌入式Log等级从高到低定义如下：
| 等级 | 关键字 | 含义 | 典型场景 |
|---|---|---|---|
| 1 (最高) | Error | 致命错误，系统无法正常运行 | DMA传输超时、外设初始化失败、内存分配失败 |
| 2 | Warning | 非致命异常，但可能导致功能降级 | 帧率低于预期阈值、缓存未命中、重试次数过多 |
| 3 | Info | 关键状态信息，用于追踪系统流程 | 驱动初始化完成、模式切换成功、帧同步信号到达 |
| 4 (最低) | Debug | 详细调试信息，用于深入分析 | 寄存器读写值、中断触发计数、缓冲区指针变化 |
调试建议：在预览卡顿问题排查初期，建议将Log等级设置为 Info 或 Warning，避免Debug信息刷屏导致关键时序丢失。当锁定可疑模块后，再开启Debug等级进行细粒度分析。
下图展示了Log等级在系统中的过滤与输出逻辑：
2. Log输出机制（串口 / 网络 / 文件）
不同的调试阶段和硬件环境，需要选择不同的Log输出通道。下表对比了三种主流输出机制的优缺点：
| 输出机制 | 实时性 | 带宽 | 持久性 | 典型应用场景 |
|---|---|---|---|---|
| 串口 (UART) | 高 | 低 (115200 bps ~ 2 Mbps) | 无（依赖上位机） | 早期驱动调试、中断上下文打印 |
| 网络 (Ethernet/WiFi) | 中 | 高 (10/100 Mbps) | 可选（远程存储） | 多设备联调、长时间压力测试 |
| 文件 (Flash/SD卡) | 低 | 中 (受存储介质限制) | 强（掉电不丢失） | 现场故障复现、离线分析 |
注意：在中断服务函数（ISR）中，严禁使用阻塞式文件写入或网络发送，这会导致系统响应延迟甚至死锁。ISR中应仅使用无锁环形缓冲区暂存Log，待退出中断后再由任务线程统一输出。
下图展示了一个典型的Log输出架构，支持多通道并发输出：
3. Log格式规范
统一的Log格式是自动化分析和人工阅读的基础。一个规范的Log条目应包含以下字段：
- 时间戳：系统启动后的相对毫秒数（ms）或绝对时间（RTC），精度至少到毫秒级。
- 等级标签：[ERR]、[WRN]、[INF]、[DBG]，用于快速视觉区分。
- 模块名称：如 [CSI]、[ISP]、[DMA]，标识日志来源。
- 函数名/行号：便于定位代码位置。
- 核心消息：描述事件或数据，支持格式化参数。
推荐格式示例：
[时间戳] [等级] [模块] [函数:行号] 消息内容
[ 12345] [ERR] [CSI] [csi_dma_start:256] DMA传输超时，通道0状态=0x03
[ 12346] [WRN] [ISP] [isp_frame_sync:102] 帧间隔异常，当前间隔=45ms，预期=33ms
[ 12350] [INF] [APP] [preview_start:88] 预览模式已启动，分辨率=1920x1080
[ 12400] [DBG] [DMA] [dma_callback:45] 完成中断，剩余字节数=0
最佳实践：在HAL驱动中，建议使用宏定义封装Log输出函数，自动捕获
__FUNCTION__ 和 __LINE__，减少手动输入错误。例如：
#define LOG_ERR(fmt, ...) \
log_output(LOG_LEVEL_ERROR, "[ERR] [%s:%d] " fmt, \
__FUNCTION__, __LINE__, ##__VA_ARGS__)下图展示了标准Log格式的字段结构：