渡水无言个人主页渡水无言❄专栏传送门《linux专栏》《嵌入式linux驱动开发》《linux系统移植专栏》❄专栏传送门《freertos专栏》 《STM32 HAL库专栏》《linux裸机开发专栏》❄专栏传送门《产品测评专栏》《Ai智能体专栏⭐️流水不争先争的是滔滔不绝博主简介第二十届中国研究生电子设计竞赛全国二等奖 |国家奖学金 | 省级三好学生| 省级优秀毕业生获得者 | csdn新星杯TOP18 | 半导纵横专栏博主 | 211在读研究生在这里主要分享自己学习的linux嵌入式领域知识有分享错误或者不足的地方欢迎大佬指导也欢迎各位大佬互相三连​目录前言一、LogTask 日志任务概述二、日志系统的核心作用三、日志系统的总体时序流程图四、日志任务代码的实现4.1、日志等级 LogLevel_t4.2、日志接口和宏4.2.1、日志初始化4.2.2、等级动态设置 / 获取4.2.3、业务日志投递接口4.3、核心数据结构设计4.3.1、参数通用结构Arg_t4.3.2、队列单条日志记录 LogRec_t4.4、队列的使用4.4.1、队列的基本概念4.4.2、队列的初始化4.4.3、队列的写和读五、PANIC 故障保底机制5.1、Panic概述5.2、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文件中如下所示// 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为静态创建队列函数。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、等级动态设置 / 获取运行时设置或查询当前最低输出的日志级别。void Log_SetLevel(LogLevel_t lvl) { s_runtime_level lvl; } LogLevel_t Log_GetLevel(void) { return s_runtime_level; }4.2.3、业务日志投递接口业务侧调用发送一个日志消息到队列中自动等级过滤、不做字符串格式化仅打包参数等信息拷贝到LogRec_t非阻塞投递队列满直接丢弃不影响业务任务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()虽然能完成日志输出但每次都写完整参数Log_Post(LOG_LVL_WARN, NULL, x%d, x)这较为繁琐更关键的是大量调试日志若在正式发布版中保留会严重影响系统性能。为此项目中定义了一系列日志宏预处理器代码替换工具既简化了调用写法又能根据日志等级在编译阶段自动剔除低优先级日志兼顾了开发便利性与发布性能。项目中的日志宏包括#define LOGERROR(fmt, ...) // 打印 ERROR 级别日志 #define LOGWARN(fmt, ...) // 打印 WARN 级别日志 #define LOGINFO(fmt, ...) // 打印 INFO 级别日志 #define LOGDEBUG(fmt, ...) // 打印 DEBUG 级别日志带标签版的日志宏包括#define LOGERROR_T(tag, fmt, ...) // 带标签的 ERROR 日志 #define LOGINFO_T(tag, fmt, ...) // 带标签的 INFO 日志 // 其他等级的带标签宏可按相同模式扩展宏实现示例#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之类的来表示结构体如下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这是日志队列中每条日志记录的完整结构体不做现场格式化只保存等级、标签、格式串、参数列表交给日志任务统一处理typedef struct { uint8_t lvl; /** 日志等级 */ const char *tag; /** 日志来源模块标签比如COMM */ const char *fmt; /** 格式字符串 */ uint8_t argc; /** 有效参数数量 */ Arg_t args[LOG_MAX_ARGS]; /** 打包好的参数数组 */ } LogRec_t;举例如果写了条日志如下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然后由专门的日志任务在后台逐个取出、格式化并发送。这种情况就最适合使用队列的形式了。如下所示队列一般是静态定义的/** 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创建队列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()进行非阻塞发送避免阻塞业务任务xQueueSend(s_q, r, 0); // 非阻塞发送日志任务通过xQueueReceive()从队列中阻塞式等待队列无数据时任务会挂起一旦有日志投递会立即唤醒并处理。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进入保底模式。​ static volatile uint8_t s_panic 0; void Log_EnterPanic(void) { s_panic 1; } bool Log_IsPanic(void) { return (s_panic ! 0); } ​日志宏如LOGERROR()内部都会判断是否已经 panicif (Log_IsPanic()) { Log_Error(NULL, fmt, ...); // 走 panic 输出 } else { Log_Post(...); // 走正常队列 }在 panic 模式下日志会调用uart2_poll_putc()通过轮询寄存器的方式逐字节发送日志内容到串口不依赖队列、DMA、中断、RTOS。这部分代码操作的是 STM32 的 USART2 寄存器确保最底层也能发出字符。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日志系统的设计。