# 日志

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

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

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

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

### log宏函数定义

```c
#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日志输出 |

## 函数详解

### 日志控制位掩码定义

```c
/* 日志控制掩码位定义 */
#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

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

- **函数原型**

```c
qosa_uint32_t qosa_log_control_get(void)
```

- **参数说明**  
  无

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

### qosa_log_control_set

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

- **函数原型**

```c
qosa_log_error_e qosa_log_control_set(qosa_uint32_t mask)
```

- **参数说明**

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

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

### qosa_log_printf

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

- **函数原型**

```c
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

- **功能描述**  
  获取电池充电状态、剩余电量百分比和电池电压。

- **函数原型**

```c
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

结果码枚举定义如下：

```c
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

日志级别枚举定义如下：

```c
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* | 最大级别 |

# 应用逻辑流程图

#### 日志输出流程

```{figure} images/board_O2wiwc899hmoSnbLj1VcQ0lUnmd.jpg
:align: center
:alt: image
```

# 示例代码

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