xt_log - 日志输出

版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_log/

---

一、概述

xt_log 是 XTINY 日志输出模块，提供多级别日志过滤、十六进制数据 dump 和断言处理。底层通过平台日志输出接口输出，单条日志 ≤128 字节。

1.1 设计原则

• 级别过滤 ：日志输出前先与当前级别比较，高于阈值的日志直接跳过，零开销
• 可覆盖宏 ：便捷宏和带 tag 宏均用 #if !defined() 保护，用户可提前 #define 覆盖
• 弱断言 + 回调 ： xt_assert_failed 声明为 __weak 可重写，同时支持通过回调注册自定义处理

1.2 依赖

依赖	用途
xt_error.h	错误码类型 xt_err_t
平台日志输出接口	实际输出

---

二、核心概念

2.1 日志级别

日志级别从低到高依次为：

级别	宏	值	用途
错误	XT_LOG_ERROR	1	严重错误，影响功能
警告	XT_LOG_WARN	2	异常情况，但不影响运行
信息	XT_LOG_INFO	3	正常运行信息（默认级别）
调试	XT_LOG_DEBUG	4	详细调试信息

当前日志级别设为 N 时，只输出级别 ≤ N 的日志。默认级别为 XT_LOG_INFO ，即输出错误、警告、信息三级，调试日志被屏蔽。

xt_log_set_level 对超出 XT_LOG_DEBUG 的值自动截断，防止无效级别。

2.2 便捷宏（无 tag）

为减少重复代码，头文件提供了四个无 tag 的预定义宏（ #if !defined() 模式）：

宏	等效调用
xt_log_error(fmt, ...)	xt_log（日志输出）
xt_log_warn(fmt, ...)	xt_log（日志输出）
xt_log_info(fmt, ...)	xt_log（日志输出）
xt_log_debug(fmt, ...)	xt_log（日志输出）

2.3 带 tag 宏（标识来源模块）

带 tag 宏输出时在日志前添加 [tag] 前缀，便于过滤和定位来源：

宏	等效调用
XT_LOGE(tag, fmt, ...)	xt_log（日志输出）
XT_LOGW(tag, fmt, ...)	xt_log（日志输出）
XT_LOGI(tag, fmt, ...)	xt_log（日志输出）
XT_LOGD(tag, fmt, ...)	xt_log（日志输出）

2.4 断言机制

XT_ASSERT_MSG(expr, errcode) 宏：当 expr 为假时，通过 xt_log_error 输出失败位置（函数名、行号、错误码），然后调用 xt_assert_failed(errcode) 进入平台默认断言处理。

用户可通过 xt_assert_set_callback 注册回调，在平台默认处理前插入自定义逻辑（如保存关键数据、记录诊断信息）。回调为 NULL 时跳过。

xt_assert_failed 声明为 __WEAK ，用户可在任意位置重写整个函数。

2.5 dump_hex 双版本

• xt_log_dump_hex ：以信息级别输出十六进制数据，不受当前日志级别影响
• xt_log_dump_hex_debug ：仅当前级别为 XT_LOG_DEBUG 时输出

2.6 xt_printf / xt_vprintf

提供类似标准 C printf / vprintf 的格式化输出函数，固定以 XT_LOG_INFO 级别通过平台 SDK 输出，不受当前日志级别影响。与 xt_log 系列的区别：不检查级别、不添加 tag 前缀，适合直接替换 printf 调试代码。

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_log（日志输出） 。

3.1 初始化与配置

函数签名	说明
void xt_log_setup(uint8_t id, uint32_t baudrate, uint8_t tx_io, uint8_t rx_io)	初始化日志模块
void xt_log_set_level(uint8_t level)	设置日志输出级别
uint8_t xt_log_get_level(void)	获取当前日志级别

3.2 日志输出

函数签名	说明
void xt_log(uint8_t level, const char *tag, const char *fmt, ...)	输出格式化日志（级别过滤 + tag 前缀）
void xt_log_dump_hex(const void *ptr, uint32_t size)	以十六进制格式输出内存数据
void xt_log_dump_hex_debug(const void *ptr, uint32_t size)	以十六进制格式输出（仅 DEBUG 级别）
int xt_printf(const char *fmt, ...)	格式化字符串输出
int xt_vprintf(const char *fmt, va_list args)	格式化字符串输出（va_list 版本）

3.3 断言处理

函数签名	说明
void xt_assert_failed(xt_err_t errcode)	断言失败处理（ __weak 可重写）
void xt_assert_set_callback(xt_assert_cb_t cb)	注册断言失败回调

四、编译配置

无编译配置项。日志级别通过运行时 xt_log_set_level 调整，便捷宏可通过 #define 覆盖。

五、常见模式

5.1 基本使用——便捷宏

#include "xt_log.h"
 
void app_init(void) {
    xt_log_setup(0, 115200, 1, 2);
    xt_log_set_level(XT_LOG_DEBUG);
}
 
void app_run(void) {
    xt_log_info("系统启动完成");
    xt_log_warn("电量低于 20%%");
    xt_log_error("传感器读取失败，错误码 %d", -1);
    xt_log_debug("内部变量 x=%d, y=%d", 10, 20);
}

5.2 带 tag 宏——标识来源模块

#include "xt_log.h"
 
void sensor_init(void) {
    XT_LOGI("SENSOR", "初始化传感器");
    XT_LOGD("SENSOR", "寄存器配置: 0x%02X", reg_val);
}
 
void comm_on_recv(const uint8_t *data, size_t len) {
    if (len == 0) {
        XT_LOGW("COMM", "收到空数据包");
        return;
    }
    XT_LOGI("COMM", "收到 %u 字节", len);
}

5.3 直接使用 xt_log——自定义 tag

#include "xt_log.h"
 
typedef enum { MODULE_A = 1, MODULE_B, MODULE_C } module_id_t;
 
void dispatch(module_id_t mod) {
    const char *tag = (mod == MODULE_A) ? "A" : (mod == MODULE_B) ? "B" : "C";
    xt_log(XT_LOG_INFO, tag, "开始处理模块 %d", mod);
}

5.4 十六进制 dump 数据包

#include "xt_log.h"
 
void dump_packet(const uint8_t *pkt, size_t len) {
    xt_log_info("收到数据包，长度: %u", len);
    xt_log_dump_hex(pkt, len);           // 总是输出
    xt_log_dump_hex_debug(pkt, len);     // 仅 DEBUG 级别输出
}

5.5 断言与自定义回调

#include "xt_log.h"
 
static void my_assert_cb(xt_err_t errcode) {
    xt_log_error("断言失败，错误码 %d，正在保存关键数据...", errcode);
    save_critical_data();
}
 
void app_init(void) {
    xt_log_setup(0, 115200, 1, 2);
    xt_assert_set_callback(my_assert_cb);
}
 
void process_data(int *buf, size_t idx) {
    XT_ASSERT_MSG(idx < MAX_SIZE, XT_EINVAL);  // 条件失败时触发断言
    buf[idx] = 0;
}

5.6 切换日志级别（开发/生产）

#include "xt_log.h"
 
void app_init(bool debug_mode) {
    xt_log_setup(0, 115200, 1, 2);
    if (debug_mode) {
        xt_log_set_level(XT_LOG_DEBUG);
    } else {
        xt_log_set_level(XT_LOG_INFO);
    }
}

---

六、已知行为与限制

行为	说明
单条日志 ≤128 字节	buffer 固定 128 字节，超长内容截断
默认级别 XT_LOG_INFO	DEBUG 日志默认不输出，需调 xt_log_set_level(XT_LOG_DEBUG)
xt_log_setup 参数未使用	当前实现中仅记录 id ， baudrate / tx_io / rx_io 预留未使用
xt_log_set_level 范围限制	超过 XT_LOG_DEBUG 的值自动截断为 XT_LOG_DEBUG
tag 为 NULL 时无前缀	调用 xt_log(level, NULL, "...") 不添加 [tag] 前缀
便捷宏可覆盖	所有 xt_log_* 和 XT_LOG* 宏均用 #if !defined() 保护
dump_hex 当前为空实现	头文件声明但 .c 中函数体为空
断言回调为 NULL 时跳过	直接进入平台默认断言处理
xt_printf / xt_vprintf 固定 INFO 级别	不受 xt_log_set_level 影响
xt_assert_failed 为 __WEAK	用户可在任意源文件重写整个函数

七、示例

示例代码位于 examples/system/log/。

cd examples/system/log
xt --target windows/simulator fullclean build
xt --target windows/simulator run