1. 课程导入
在嵌入式RTOS产品开发中，调试串口打印往往是工程师最熟悉的“第一反应”。但当产品进入小批量试产、现场部署或长期运行阶段，简单的printf会迅速暴露三大问题：阻塞实时任务、日志丢失与乱序、现场问题无法复现。本课程的目标，是把“打印调试”升级为一套可产品化的日志与诊断系统——它既能记录，又能分级过滤、异步输出、掉电保存、远程回传，还能在故障现场自动抓取任务栈、寄存器与堆信息。
本课程不是讲“如何调用一个日志库API”，而是讲清楚：在RAM只有几十KB、Flash有限、CPU主频百兆级的RTOS产品上，如何设计一套低侵入、可裁剪、可回溯、可诊断的日志基础设施。
一、学习目标：从“能打印”到“能定位问题”
完成本课程后，你应当具备以下能力：
- 能根据产品资源约束，选择同步/异步、缓冲/直写、分级/全量的日志架构；
- 能设计日志分级、模块标签、时间戳、序列号与环形缓冲区，保证日志不丢、不乱、可追溯；
- 能实现日志的Flash分区存储、掉电保护、循环覆盖与导出；
- 能结合RTOS任务状态、堆栈水位、CPU占用率、HardFault现场，构建诊断快照；
- 能通过CLI、RTT、串口、网络或文件系统，把日志接入上位机与自动化测试；
- 能对日志系统本身做性能评估：单条耗时、内存占用、中断延迟影响、Flash寿命。
二、核心价值：日志是产品的“黑匣子”
产品级日志系统的价值，不在于开发阶段方便，而在于现场故障可定位、批量问题可统计、长期运行可观测。一个成熟的RTOS日志系统通常承担四类职责：
| 职责 | 典型场景 | 关键指标 |
|---|---|---|
| 运行记录 | 任务切换、状态机迁移、通信收发 | 完整性、时间精度 |
| 故障取证 | HardFault、看门狗复位、断言失败 | 现场快照、掉电保存 |
| 性能观测 | CPU占用、堆栈水位、队列深度 | 低开销、周期采样 |
| 远程诊断 | 现场设备回传日志、OTA后验证 | 可压缩、可分级、可过滤 |
如果没有这套体系，现场返回的往往只有一句“设备死机了”。而有了日志与诊断，你能看到：死机前最后10条日志、当前任务栈使用率、堆剩余空间、中断嵌套深度、复位原因寄存器。这就是产品级与实验级的分水岭。
三、整体知识框架：五层结构
本课程的知识框架可以概括为“采集—缓冲—输出—存储—诊断”五层。下图展示了各层之间的数据流与关键对象，便于你建立全局视图。
这五层不是必须全部实现，而是按产品需求裁剪。低端产品可能只做“采集+缓冲+串口输出”；中高端产品则需要“采集+缓冲+Flash存储+诊断快照+远程回传”。课程会按这条主线逐层展开。
四、实战路线图：从最小可用到产品级
为了避免“一上来就设计大而全的日志系统”，课程采用渐进式路线：
- 阶段一：最小可用日志——实现分级宏、模块标签、串口输出，解决“能看”的问题；
- 阶段二：异步与缓冲——引入环形缓冲区与日志任务，解决“不阻塞实时任务”的问题；
- 阶段三：持久化存储——划分Flash日志区，实现循环覆盖与掉电保护，解决“现场可回溯”的问题；
- 阶段四：诊断快照——在HardFault、断言、看门狗复位时自动保存任务栈、寄存器与堆信息；
- 阶段五：远程与自动化——通过CLI、RTT、网络导出日志，接入上位机解析与自动化测试。
建议每个阶段都在真实开发板上验证，而不是只读代码。日志系统的很多问题——乱序、丢日志、格式化耗时、Flash写放大——只有在真实负载下才会暴露。
五、典型误区与复盘
在开始动手前，先看清几个常见误区：
- 误区一：日志越详细越好。高频日志会挤占CPU、Flash和带宽，必须分级、分模块、可动态开关。
- 误区二：在中断里直接打印。串口输出耗时可能达毫秒级，会破坏中断实时性，应只入队、不输出。
- 误区三：只存不诊断。日志文件很大，但缺少任务状态、堆栈、复位原因，仍然无法定位死机。
- 误区四：忽略日志系统自身的资源开销。缓冲区大小、格式化栈深度、Flash擦写寿命都要纳入设计。
下面是一段典型的最小日志接口示例，后续章节会在此基础上逐步扩展：
#define LOG_LEVEL_ERROR 0
#define LOG_LEVEL_WARN 1
#define LOG_LEVEL_INFO 2
#define LOG_LEVEL_DEBUG 3
#define LOG_E(tag, fmt, ...) log_output(LOG_LEVEL_ERROR, tag, fmt, ##__VA_ARGS__)
#define LOG_W(tag, fmt, ...) log_output(LOG_LEVEL_WARN, tag, fmt, ##__VA_ARGS__)
#define LOG_I(tag, fmt, ...) log_output(LOG_LEVEL_INFO, tag, fmt, ##__VA_ARGS__)
#define LOG_D(tag, fmt, ...) log_output(LOG_LEVEL_DEBUG, tag, fmt, ##__VA_ARGS__)
/* 使用示例 */
LOG_I("WIFI", "connect ssid=%s rssi=%d", ssid, rssi);
LOG_E("FSM", "invalid state=%d, reset", state);本课程后续每一章都会围绕一个可落地的设计点展开，并给出可编译、可裁剪的代码骨架。你不需要一次记住所有细节，但需要建立一条清晰的主线：日志不是打印，而是产品可观测性的基础设施。当你能把现场故障还原成一条完整的时间线，并附带任务、内存与中断上下文时，这套系统就真正达到了产品级要求。