日志¶

功能概述¶

本章围绕UniRTOS日志管理模块，系统介绍其功能特性、API 使用方法及典型应用示例，旨在帮助开发者快速上手，高效利用日志输出控制功能，提升嵌入式软件的调试与运维效率。

在嵌入式系统开发中，日志是故障定位、性能分析和运行行为追踪不可或缺的手段。UniRTOS日志管理模块从实际工程需求出发，设计为 轻量、灵活、可配置 的子系统，它支持编译期和运行期两级日志开关控制，允许开发者根据不同阶段（调试、测试、量产）动态调整日志输出量，避免冗余信息干扰。同时，模块提供了多种输出端口选择（如串口（UART）、调试（SWO/JTAG）、网络（UDP）、甚至LCD显示等），方便将日志定向到最合适的观察通道，并支持日志级别过滤（ERROR / WARN / INFO / DEBUG / TRACE），实现细粒度管控。

本章后续将依次给出核心log宏接口及API的详细说明、配置示例，以及常见应用场景（如多任务调试、异常现场记录、性能统计）的完整代码演示，使您能够快速将日志模块集成到自己的工程中，并灵活定制输出策略。

log宏函数定义¶

#define QLOGE(...)    QOSA_LOG_E(QOS_LOG_TAG, ##__VA_ARGS__)
#define QLOGW(...)    QOSA_LOG_W(QOS_LOG_TAG, ##__VA_ARGS__)
#define QLOGI(...)    QOSA_LOG_I(QOS_LOG_TAG, ##__VA_ARGS__)
#define QLOGD(...)    QOSA_LOG_D(QOS_LOG_TAG, ##__VA_ARGS__)
#define QLOGV(...)    QOSA_LOG_V(QOS_LOG_TAG, ##__VA_ARGS__)
#define QLOGV_EX(...) QOSA_LOG_NO_F(QOS_LOG_TAG, ##__VA_ARGS__)

定义详解：

宏定义	日志级别	说明
QLOGE(…)	ERROR	错误级别日志，用于记录严重错误
QLOGW(…)	WARN	警告级别日志，用于记录潜在问题
QLOGI(…)	INFO	信息级别日志，用于记录重要业务流程
QLOGD(…)	DEBUG	调试级别日志，用于调试信息输出
QLOGV(…)	VERBOSE	详细级别日志，输出最详细的调试信息
QLOGV_EX(…)	VERBOSE	详细级别日志（无函数名信息）

日志级别优先级：ERROR > WARN > INFO > DEBUG > VERBOSE > NEVER

日志API¶

头文件¶

qosa_log.h

函数概览¶

函数	说明
qosa_log_control_get()	获取当前log日志控制掩码
qosa_log_control_set()	设置log日志控制掩码
qosa_log_printf()	格式化log日志输出
qosa_log_vprintf()	可变参数列表格式log日志输出

函数详解¶

日志控制位掩码定义¶

/* 日志控制掩码位定义 */
#define QOSA_LOG_BIT_MASTER_ENABLE    (1U << 0)  /*!< Bit 0: 总开关 */
#define QOSA_LOG_BIT_DEBUG            (1U << 1)  /*!< Bit 1: DEBUG 串口输出 */
#define QOSA_LOG_BIT_USB              (1U << 2)  /*!< Bit 2: USB 端口输出 */
#define QOSA_LOG_BIT_SDCARD           (1U << 3)  /*!< Bit 3: SD 卡输出 */
#define QOSA_LOG_BIT_FLASH            (1U << 4)  /*!< Bit 4: FLASH 输出 */

qosa_log_control_get¶

功能描述
获取当前日志控制的掩码值，包含总开关状态和各输出端口使能状态。
函数原型

qosa_uint32_t qosa_log_control_get(void)

参数说明
无
返回值说明
当前日志控制掩码（qosa_uint32_t类型）
- 位0：总开关状态（1=开启，0=关闭）
- 位1：DEBUG端口使能状态
- 位2：USB端口使能状态

qosa_log_control_set¶

功能描述
设置日志控制掩码，控制日志总开关及输出端口，配置会自动保存到Flash 。
函数原型

qosa_log_error_e qosa_log_control_set(qosa_uint32_t mask)

参数说明

参数名	输入/输出	类型	说明
mask	输入	qosa_log_error_e	期望设置的日志控制掩码 QOSA_LOG_BIT_MASTER_ENABLE：开启总开关 QOSA_LOG_BIT_DEBUG：使能DEBUG串口输出 QOSA_LOG_BIT_USB：使能USB端口输出

返回值说明
QOSA_LOG_ERRID_SUCCESS：设置成功
QOSA_LOG_ERRID_NOT_SUPPORT：设置了不支持的功能（SD卡或Flash）

qosa_log_printf¶

功能描述
格式化输出日志信息，自动添加函数名和行号，通过 ECPLAT_PRINTF 输出。
函数原型

void qosa_log_printf(int level, int tag, const char* funcname, int line, const char* fmt, ...)

参数说明

参数名	输入/输出	类型	说明
level	输入	int	日志级别（DEBUG/INFO/WARN/ERROR）
tag	输入	int	日志标签（通常为 LOG_TAG 宏定义）
funcname	输入	const char*	调用函数的函数名（通常传入_FUNCTION_）
line	输入	int	调用位置的行号（通常传入_LINE_）
fmt	输入	const char*	格式化字符串
…	…	…	可变参数，根据fmt传入对应参数

返回值说明
无

qosa_log_vprintf¶

功能描述
获取电池充电状态、剩余电量百分比和电池电压。
函数原型

void qosa_log_vprintf(int level, int tag, const char* funcname, int line, const char* fmt, va_list args)

参数说明

参数名	输入/输出	类型	说明
level	输入	int	日志级别（DEBUG/INFO/WARN/ERROR）
tag	输入	int	日志标签（通常为 LOG_TAG 宏定义）
funcname	输入	const char*	调用函数的函数名（通常传入_FUNCTION_ ）
line	输入	int	调用位置的行号（通常传入_LINE_ ）
fmt	输入	const char*	格式化字符串
args	输入	va_list	可变参数列表（ va_list类型）

返回值说明
始终返回 QOSA_POWER_SUCCESS：函数执行成功

枚举定义¶

qosa_log_error_e¶

结果码枚举定义如下：

typedef enum
{
    QOSA_LOG_ERRID_SUCCESS = 0,                            
    QOSA_LOG_ERRID_NOT_SUPPORT = 1 | (QOSA_COMPONENT_LOG << 16), 
    QOSA_LOG_ERRID_INVALID_PARAM,                          
} qosa_log_error_e;

成员	说明
QOSA_LOG_ERRID_SUCCESS	函数执行成功
QOSA_LOG_ERRID_NOT_SUPPORT	功能不支持
QOSA_LOG_ERRID_INVALID_PARAM	无效参数

qosa_log_level_e¶

日志级别枚举定义如下：

typedef enum
{
    QOSA_LOG_LEVEL_NEVER = 0,    /*!< 永不输出（关闭日志） */
    QOSA_LOG_LEVEL_ERROR,        /*!< 错误级别 */
    QOSA_LOG_LEVEL_WARN,         /*!< 警告级别 */
    QOSA_LOG_LEVEL_INFO,         /*!< 信息级别 */
    QOSA_LOG_LEVEL_DEBUG,        /*!< 调试级别 */
    QOSA_LOG_LEVEL_VERBOSE,      /*!< 详细级别 */
    QOSA_LOG_LEVEL_MAX           /*!< 最大级别 */
} qosa_log_level_e;

成员	说明
QOSA_LOG_LEVEL_NEVER	永不输出（关闭日志）
QOSA_LOG_LEVEL_NEVER	错误级别
QOSA_LOG_LEVEL_WARN	警告级别
QOSA_LOG_LEVEL_INFO	信息级别
QOSA_LOG_LEVEL_DEBUG	调试级别
QOSA_LOG_LEVEL_VERBOSE	详细级别
QOSA_LOG_LEVEL_MAX	最大级别

应用逻辑流程图¶

日志输出流程¶

示例代码¶

完整示例代码请查看https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/system/log/log.c

日志¶