🎬 渡水无言 ：个人主页渡水无言
❄专栏传送门 ： 《linux专栏》《嵌入式linux驱动开发》《linux系统移植专栏》
❄专栏传送门 ： 《freertos专栏》 《STM32 HAL库专栏》《linux裸机开发专栏》
⭐️流水不争先，争的是滔滔不绝
📚博主简介：第二十届中国研究生电子设计竞赛全国二等奖 |国家奖学金 | 省级三好学生
| 省级优秀毕业生获得者 | csdn新星杯TOP18 | 半导纵横专栏博主 | 211在读研究生
在这里主要分享自己学习的linux嵌入式领域知识；有分享错误或者不足的地方欢迎大佬指导，也欢迎各位大佬互相三连
目录
[一、LogTask 日志任务概述](#一、LogTask 日志任务概述)
[4.1、日志等级 （LogLevel_t）](#4.1、日志等级 （LogLevel_t）)
[4.2.2、等级动态设置 / 获取](#4.2.2、等级动态设置 / 获取)
[4.3.2、队列单条日志记录 LogRec_t](#4.3.2、队列单条日志记录 LogRec_t)
[五、PANIC 故障保底机制](#五、PANIC 故障保底机制)
前言
在本系列前面的文章中，我们已经完成了机器人下位机五大核心业务任务的搭建：CommTask指令解析、ControlTask运动控制、SensorTask状态采集、UplinkTask数据上报、MonitorTask系统监控。
这些任务构建了机器人的完整业务与监控闭环，但在开发和调试阶段，我们还需要一个强大的辅助工具 ------日志系统。日志系统的设计直接影响着开发效率和问题定位能力。
本章我们就来实现 LogTask 日志任务，为整套项目提供高效的调试与问题定位支持。
一、LogTask 日志任务概述
我们在开发小型项目时，我们习惯使用 printf 来打印变量、状态信息或调试流程，这种方式简单直接，足以应对小规模项目的测试需求。
但如果是开发大型项目时，项目往往包含成百上千个文件、成千上万行代码，无法每次测试都把所有日志都打出来。
此时需要用到日志等级（Log Level）机制：根据日志的重要程度划分等级，例如只保留ERROR等日志用于日常运行，而将大量DEBUG级别的细节日志关闭，仅在定位问题时临时打开。这种做法能在保证系统稳定性的同时，为调试和问题排查提供足够的信息支持。
因此，我们也设定了一个专门的日志任务 LogTask，用于异步地收集和输出各功能模块的日志信息。
二、日志系统的核心作用
辅助调试和问题定位 ：日志系统可以输出详细的测试信息。遇到Bug时，没有日志信息往往难以定位问题；而有了日志，问题排查会变得直观快捷。
监控系统运行状态： 日志可以周期性或事件驱动地记录系统状态和关键事件，帮助我们实时或事后了解设备的运行情况。例如，可以在日志中看到任务切换、外设变化或传感器数据等，便于发现异常状态。
记录历史信息： 通过包含时间戳、模块标识、代码行号等上下文信息，日志保留了运行轨迹和事件顺序。开发者可以通过分析历史日志重现问题发生的过程，进行故障诊断和回溯分析。
性能分析： 日志中通常会记录操作耗时或资源使用情况，结合时间戳可以做性能分析和优化。比如，通过日志对比任务执行时间，找出系统瓶颈。
**分级管理输出：**日志系统常根据重要程度分级（如 DEBUG、INFO、WARNING、ERROR 等），这样可以灵活过滤信息、集中关注关键日志。不同场景下，只输出高优先级日志，有助于减少干扰。
三、日志系统的总体时序流程图
主要流程：
业务投递阶段： 业务任务调用Log_Post时，仅做等级过滤和参数解析，非阻塞投递到队列，不影响实时性。
日志格式化阶段：日志任务 App_LogTask负责从队列取出记录（LogRec_t ），调用format_line()函数将LogRec_t 统一格式化为标准日志行写入环形缓冲区。
DMA 环形缓冲发送阶段： 格式化后的日志写入环形缓冲区，由 DMA 自动搬运发送，发送完成中断回调会自动续发剩余数据。
**故障保底阶段：**当系统进入PANIC模式（如 HardFault、栈溢出），会直接切换为寄存器轮询方式发送，脱离 RTOS/DMA 依赖，保证关键故障日志能被打印出来。
四、日志任务代码的实现
日志任务 App_LogTask负责从队列取出记录（LogRec_t ），调用format_line()函数将LogRec_t统一格式化为标准日志行写入环形缓冲区。
4.1、日志等级 （LogLevel_t）
日志等级用于区分消息的重要性，数字越小，日志越重要；数字越大，日志优先级越低。定义如下：
| 等级 | 说明 | 使用场景 |
|---|---|---|
ERROR |
严重错误 | 功能无法正常工作时输出 |
WARN |
警告信息 | 发生意外但系统仍可继续运行时输出 |
INFO |
普通信息 | 记录正常事件与状态变更 |
DEBUG |
调试信息 | 提供详细诊断信息，正常运行时可忽略 |
为了实现编译期与运行期的灵活控制，代码中定义了以下机制：
用枚举类型 LogLevel_t 统一表示日志等级。
通过编译宏 LOG_COMPILE_LEVEL 实现编译期过滤：高于设置级别的日志会被直接剔除，可在发布版中移除调试信息。
提供 Log_SetLevel() 接口，支持运行时动态设置输出最低等级，便于调试阶段灵活控制日志输出量。
具体定义在log_task.h文件中，如下所示：
cpp
// log_task.h
typedef enum {
LOG_LVL_ERROR = 0,
LOG_LVL_WARN = 1,
LOG_LVL_INFO = 2,
LOG_LVL_DEBUG = 3,
} LogLevel_t;4.2、日志接口和宏
日志接口是一组专用函数，负责对日志信息进行格式化、封装与分级，并最终输出到串口或其他目标介质。业务代码只需调用这些接口，即可安全可靠地发送日志，无需关心底层串口、中断、DMA 等复杂实现细节。
4.2.1、日志初始化
初始化日志系统，创建静态队列、清空环形缓冲区与 DMA 状态，上电调用一次即可：
xQueueCreateStatic（）为静态创建队列函数。
cpp
void Log_Init(void)
{
if (!s_q) {
s_q = xQueueCreateStatic(LOG_Q_DEPTH, sizeof(LogRec_t), s_qbuf, &s_qcb);
}
taskENTER_CRITICAL();
s_head = 0; s_tail = 0; s_dma_len = 0; s_dma_busy = 0;
s_runtime_level = LOG_RUNTIME_LEVEL;
taskEXIT_CRITICAL();
}4.2.2、等级动态设置 / 获取
运行时设置或查询当前最低输出的日志级别。
cpp
void Log_SetLevel(LogLevel_t lvl) { s_runtime_level = lvl; }
LogLevel_t Log_GetLevel(void) { return s_runtime_level; }4.2.3、业务日志投递接口
业务侧调用，发送一个日志消息到队列中，自动等级过滤、不做字符串格式化，仅打包参数等信息拷贝到LogRec_t，非阻塞投递，队列满直接丢弃，不影响业务任务：
cpp
bool Log_Post(LogLevel_t lvl, const char *tag, const char *fmt, ...)
{
if (!s_q || !fmt) return false;
// 运行时等级过滤：数字越大越"啰嗦"
if (lvl > s_runtime_level) return true;
LogRec_t r;
memset(&r, 0, sizeof(r));
r.lvl = (uint8_t)lvl;
r.tag = tag; // 可选: NULL 表示无 tag
r.fmt = fmt;
va_list ap;
va_start(ap, fmt);
va_list ap2;
va_copy(ap2, ap);
parse_args(&r, ap2);
va_end(ap2);
va_end(ap);
// 非阻塞：队列满就丢（不拖慢业务任务）
return (xQueueSend(s_q, &r, 0) == pdPASS);
}直接调用 Log_Post() 虽然能完成日志输出，但每次都写完整参数：
cpp
Log_Post(LOG_LVL_WARN, NULL, "x=%d", x)这较为繁琐；更关键的是，大量调试日志若在正式发布版中保留，会严重影响系统性能。
为此，项目中定义了一系列日志宏 （预处理器代码替换工具），既简化了调用写法，又能根据日志等级在编译阶段自动剔除低优先级日志，兼顾了开发便利性与发布性能。
项目中的日志宏包括：
cpp
#define LOGERROR(fmt, ...) // 打印 ERROR 级别日志
#define LOGWARN(fmt, ...) // 打印 WARN 级别日志
#define LOGINFO(fmt, ...) // 打印 INFO 级别日志
#define LOGDEBUG(fmt, ...) // 打印 DEBUG 级别日志带标签版的日志宏包括：
cpp
#define LOGERROR_T(tag, fmt, ...) // 带标签的 ERROR 日志
#define LOGINFO_T(tag, fmt, ...) // 带标签的 INFO 日志
// 其他等级的带标签宏可按相同模式扩展宏实现示例
cpp
#define LOGERROR_T(tag, fmt, ...) do { \
if (Log_IsPanic()) { Log_Error((tag), (fmt), ##__VA_ARGS__); } \
else { (void)Log_Post(LOG_LVL_ERROR, (tag), (fmt), ##__VA_ARGS__); } \
} while(0)该实现通过 do { ... } while(0) 保证宏在所有语法场景下的安全性，同时区分了系统 panic 状态下的紧急日志处理与普通状态下的异步入队逻辑。
4.3、核心数据结构设计
日志系统并非简单的 "打印信息"，而是需要完成日志信息的打包、排队、格式化、发送等一系列操作。为支撑这些功能，需要设计一套合理的数据结构，来表示 "日志记录""参数类型" 等核心要素。
在代码实现中，最关键的三个数据结构为：
LogLevel_t：日志等级枚举。
Arg_t：日志参数的通用表示。
LogRec_t：一条完整的日志记录。
4.3.1、参数通用结构Arg_t
日志中可能包含各种类型的参数（整形，浮点等等），因此不能只用int之类的来表示，结构体如下：
cpp
typedef enum {
ARG_I32, /**< int32_t / %d %i */
ARG_U32, /**< uint32_t / %u */
ARG_HEX32, /**< uint32_t / %x %X */
ARG_CHAR, /**< char / %c */
ARG_STR, /**< const char* / %s */
ARG_F64, /**< double / %f %F */
} ArgType_t;
typedef struct {
ArgType_t t; /**< 参数类型 */
union {
int32_t i32; /**< 有符号整型 */
uint32_t u32; /**< 无符号整型/HEX */
char ch; /**< 字符 */
const char *s; /**< 字符串指针 */
double f64; /**< 双精度浮点 */
} v;
} Arg_t;4.3.2、队列单条日志记录 LogRec_t
这是日志队列中每条日志记录的完整结构体，不做现场格式化，只保存等级、标签、格式串、参数列表，交给日志任务统一处理：
cpp
typedef struct {
uint8_t lvl; /**< 日志等级 */
const char *tag; /**< 日志来源模块标签，比如COMM */
const char *fmt; /**< 格式字符串 */
uint8_t argc; /**< 有效参数数量 */
Arg_t args[LOG_MAX_ARGS]; /**< 打包好的参数数组 */
} LogRec_t;举例：
如果写了条日志如下：
cpp
LOGINFO_T("CTRL", "当前速度=%d, 加速度=%.2f", speed, accel);
//这条日志会被打包成一个 LogRec_t 结构体，其成员如下：
lvl = LOG_LVL_INFO（日志等级为 INFO）
tag = "CTRL"（模块标签）
fmt = "当前速度=%d, 加速度=%.2f"（格式化字符串）
argc = 2（参数个数为 2）
args[0] = ARG_I32，值为 speed（第一个参数为 32 位整数）
args[1] = ARG_F64，值为 accel（第二个参数为 64 位浮点数）4.4、队列的使用
4.4.1、队列的基本概念
在 FreeRTOS 中，队列（Queue） 是一种用于任务间通信的数据结构。本质上，它像一个 "带锁的管道" 或 "安全的消息邮箱"，允许一个任务发送数据、另一个任务接收数据，且不会发生数据冲突。队列是线程安全的。
队列中，数据的读写本质就是环形缓冲区，在此基础上增加了互斥措施、阻塞 - 唤醒机制。
如果队列不传输数据，仅调整 "数据个数"（只传递状态），它就是信号量（semaphore）。
如果信号量中限定 "数据个数" 的最大值为 1，它就是互斥量（mutex）。
日志系统的前端（业务代码）可能在多个任务中并发执行，而日志的输出（如串口打印）却只能串行进行。如果所有任务都直接打印，会造成串口输出混乱甚至系统阻塞。
因此，这里采用前端投递日志记录 → 后端集中输出 的模型：日志记录结构 LogRec_t 会被封装好，投递进日志队列 s_q，然后由专门的日志任务在后台逐个取出、格式化并发送。
这种情况就最适合使用队列的形式了。如下所示：
队列一般是静态定义的：
cpp
/** @brief 静态队列控制块 */
static StaticQueue_t s_qcb;
/** @brief 静态队列存储区 */
static uint8_t s_qbuf[LOG_Q_DEPTH * sizeof(LogRec_t)];
/** @brief 队列句柄 */
static QueueHandle_t s_q = NULL;4.4.2、队列的初始化
然后在**Log_Init（）**中进行初始化。
初始化时调用**xQueueCreateStatic**创建队列：
cpp
xQueueCreateStatic(LOG_Q_DEPTH, sizeof(LogRec_t), s_qbuf, &s_qcb);
//
LOG_Q_DEPTH：队列最大可容纳的日志条目数（如 32）。
sizeof(LogRec_t)：单条日志记录结构体的大小。
s_qbuf：队列实际存储日志数据的内存缓冲区。
s_qcb：队列控制块（FreeRTOS 用于管理队列的元数据结构）。4.4.3、队列的写和读
前端业务代码通过 Log_Post() 投递日志记录，底层调用 xQueueSend() 进行非阻塞发送，避免阻塞业务任务：
cpp
xQueueSend(s_q, &r, 0); // 非阻塞发送日志任务通过 xQueueReceive() 从队列中阻塞式等待：队列无数据时任务会挂起，一旦有日志投递，会立即唤醒并处理。
cpp
xQueueReceive(s_q, &r, portMAX_DELAY);五、PANIC 故障保底机制
在这个日志系统中，panic 部分是一个非常重要的 "保底机制"。它主要用于系统发生严重异常（如栈溢出、硬件故障、断言失败）时的应急日志输出。
5.1、Panic概述
panic 通常指的是系统进入了一种不可恢复的严重错误状态，比如：
任务堆栈溢出（Stack Overflow）。
断言失败（Assertion Failed）。
HardFault 异常（硬件访问非法）。
调试阶段刻意触发的 "死前记录"。
此时，RTOS 可能已经无法调度任务、队列可能失效、DMA / 中断可能无法正常工作。如果还依赖日志任务和队列机制输出信息，可能会什么也打不出来。
因此我们需要一个与 RTOS 和中断系统完全脱钩的紧急通道，能保证哪怕系统 "半死不活"，也尽可能把一条关键日志发出来。
5.2、panic模式
当系统出现致命错误（如 assert/hardfault）时调用Log_EnterPanic()进入panic模式，设置 s_panic = 1，进入保底模式。
cpp
static volatile uint8_t s_panic = 0;
void Log_EnterPanic(void) { s_panic = 1; }
bool Log_IsPanic(void) { return (s_panic != 0); }
日志宏（如 LOGERROR()）内部都会判断是否已经 panic：
cpp
if (Log_IsPanic()) {
Log_Error(NULL, fmt, ...); // 走 panic 输出
} else {
Log_Post(...); // 走正常队列
}在 panic 模式下，日志会调用 uart2_poll_putc()，通过轮询寄存器的方式，逐字节发送日志内容到串口，不依赖队列、DMA、中断、RTOS。这部分代码操作的是 STM32 的 USART2 寄存器，确保最底层也能发出字符。
cpp
static inline void uart2_poll_putc(char c)
{
USART_TypeDef *U = USART2;
while ((U->SR & USART_SR_TXE) == 0) { }
U->DR = (uint8_t)c;
while ((U->SR & USART_SR_TC) == 0) { }
}总结
本期博客主要完成了LogTask日志系统的设计。