企业官网建设流程全解析

🎬渡水无言：个人主页渡水无言

❄专栏传送门：《linux专栏》《嵌入式linux驱动开发》《linux系统移植专栏》

❄专栏传送门：《freertos专栏》 《STM32 HAL库专栏》《linux裸机开发专栏》

❄专栏传送门：《产品测评专栏》《Ai智能体专栏）
⭐️流水不争先，争的是滔滔不绝

📚博主简介：第二十届中国研究生电子设计竞赛全国二等奖 |国家奖学金 | 省级三好学生

| 省级优秀毕业生获得者 | csdn新星杯TOP18 | 半导纵横专栏博主 | 211在读研究生

在这里主要分享自己学习的linux嵌入式领域知识；有分享错误或者不足的地方欢迎大佬指导，也欢迎各位大佬互相三连

​

目录

前言

一、LogTask 日志任务概述

二、日志系统的核心作用

三、日志系统的总体时序流程图

四、日志任务代码的实现

4.1、日志等级 （LogLevel_t）

4.2、日志接口和宏

4.2.1、日志初始化

4.2.2、等级动态设置 / 获取

4.2.3、业务日志投递接口

4.3、核心数据结构设计

4.3.1、参数通用结构Arg_t

4.3.2、队列单条日志记录 LogRec_t

4.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）

日志等级用于区分消息的重要性，数字越小，日志越重要；数字越大，日志优先级越低。定义如下：

为了实现编译期与运行期的灵活控制，代码中定义了以下机制：
用枚举类型 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()）内部都会判断是否已经 panic：

if (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日志系统的设计。