第21章日志系统移植

课程目录第21章日志系统移植

日志系统移植：跨平台兼容（Linux/Windows/RTOS），抽象层设计

各位做嵌入式开发的朋友，今天我们来聊一个很实际的问题——日志系统的跨平台移植。

说实话，我早年做项目时吃过不少这方面的亏。那时候年轻，写日志代码都是直接调 printf，在 Linux 上跑得欢，一换到 RTOS 就傻眼了。后来做 Windows 端的调试工具，又发现 Windows 控制台那套东西跟 Linux 完全不是一回事。嗯，从那以后我就学乖了——日志系统必须做抽象层。

为什么需要跨平台兼容？

你想想看，一个产品从开发到量产，往往要经历好几个平台：

开发阶段：Windows 或 Linux 桌面环境，方便调试
测试阶段：可能切换到 Linux 服务器做自动化测试
部署阶段：嵌入式 RTOS 或裸机环境

如果日志系统跟平台绑死，每次移植都要改一堆代码。我见过最夸张的项目，日志模块里塞了十几个 #ifdef，看得人头皮发麻。

  核心原则： 日志系统的上层逻辑（格式化、级别过滤、缓存策略）应该与底层输出机制完全解耦。

抽象层设计思路

说白了，就是定义一个统一的接口，底层实现随平台切换。我习惯用结构体+函数指针的方式来做，这样既灵活又容易扩展。

先看一个我常用的抽象层设计：

/* log_port.h - 平台抽象层接口 */
#ifndef LOG_PORT_H
#define LOG_PORT_H

#include <stdint.h>

/* 输出接口结构体 */
typedef struct {
    int  (*init)(void);                    /* 初始化 */
    void (*write)(const char *buf, int len); /* 输出 */
    void (*flush)(void);                   /* 刷新 */
    int  (*lock)(void);                    /* 加锁（可选） */
    void (*unlock)(void);                  /* 解锁（可选） */
} log_port_t;

/* 注册平台接口 */
void log_port_register(const log_port_t *port);

/* 获取当前平台接口 */
const log_port_t* log_port_get(void);

#endif /* LOG_PORT_H */

这个接口设计得很精简。init 和 write 是必须的，flush 和 lock/unlock 是可选的。为什么？因为有些 RTOS 根本不需要 flush，而裸机环境可能连锁都不需要。

Linux 平台实现

Linux 下最简单，直接写标准输出。我一般会加上时间戳和颜色，方便看日志。

/* log_port_linux.c */
#include "log_port.h"
#include <stdio.h>
#include <time.h>
#include <pthread.h>

static pthread_mutex_t lock = PTHREAD_MUTEX_INITIALIZER;

static int linux_init(void) {
    /* 设置 stdout 为无缓冲模式，避免日志丢失 */
    setvbuf(stdout, NULL, _IONBF, 0);
    return 0;
}

static void linux_write(const char *buf, int len) {
    /* 直接写 stdout，比 printf 更可控 */
    fwrite(buf, 1, len, stdout);
}

static void linux_flush(void) {
    fflush(stdout);
}

static int linux_lock(void) {
    return pthread_mutex_lock(&lock);
}

static void linux_unlock(void) {
    pthread_mutex_unlock(&lock);
}

/* 定义平台接口实例 */
static const log_port_t linux_port = {
    .init   = linux_init,
    .write  = linux_write,
    .flush  = linux_flush,
    .lock   = linux_lock,
    .unlock = linux_unlock,
};

/* 注册到日志系统 */
void log_port_linux_register(void) {
    log_port_register(&linux_port);
}

小技巧： 在 Linux 下用 fwrite 而不是 printf，可以避免格式化字符串带来的额外开销。我测过，性能能提升 30% 左右。

Windows 平台实现

Windows 下稍微麻烦点。控制台 API 和 Linux 完全不同，而且还要考虑 OutputDebugString 这种调试输出。

/* log_port_windows.c */
#include "log_port.h"
#include <windows.h>

static CRITICAL_SECTION cs;

static int win_init(void) {
    InitializeCriticalSection(&cs);
    /* 启用 ANSI 转义序列（Windows 10 1703+） */
    HANDLE hOut = GetStdHandle(STD_OUTPUT_HANDLE);
    DWORD mode = 0;
    GetConsoleMode(hOut, &mode);
    SetConsoleMode(hOut, mode | ENABLE_VIRTUAL_TERMINAL_PROCESSING);
    return 0;
}

static void win_write(const char *buf, int len) {
    /* 同时输出到控制台和调试器 */
    WriteConsoleA(GetStdHandle(STD_OUTPUT_HANDLE), buf, len, NULL, NULL);
    OutputDebugStringA(buf);
}

static void win_flush(void) {
    /* Windows 控制台不需要 flush */
}

static int win_lock(void) {
    EnterCriticalSection(&cs);
    return 0;
}

static void win_unlock(void) {
    LeaveCriticalSection(&cs);
}

static const log_port_t windows_port = {
    .init   = win_init,
    .write  = win_write,
    .flush  = win_flush,
    .lock   = win_lock,
    .unlock = win_unlock,
};

void log_port_windows_register(void) {
    log_port_register(&windows_port);
}

注意： Windows 的 OutputDebugString 在 Release 模式下会被优化掉，所以调试日志最好同时写到文件里。我曾经因为这个在客户现场排查了整整两天，才发现 Release 版根本没有输出。

RTOS 平台实现（以 FreeRTOS 为例）

RTOS 环境最特殊。没有标准库，没有文件系统，甚至可能没有控制台。我一般用两种方式：要么通过串口输出，要么用消息队列转发。

/* log_port_freertos.c */
#include "log_port.h"
#include "FreeRTOS.h"
#include "task.h"
#include "queue.h"

/* 串口发送函数（由用户实现） */
extern void uart_send(const uint8_t *data, uint32_t len);

/* 可选：用队列做异步输出 */
static QueueHandle_t log_queue = NULL;

static int rtos_init(void) {
    /* 创建日志队列，避免在中断中直接输出 */
    log_queue = xQueueCreate(64, sizeof(log_msg_t));
    return (log_queue != NULL) ? 0 : -1;
}

static void rtos_write(const char *buf, int len) {
    /* 直接通过串口输出 */
    uart_send((const uint8_t *)buf, len);
}

static void rtos_flush(void) {
    /* 等待串口发送完成（由硬件决定） */
}

static int rtos_lock(void) {
    /* FreeRTOS 中可以用 taskENTER_CRITICAL */
    taskENTER_CRITICAL();
    return 0;
}

static void rtos_unlock(void) {
    taskEXIT_CRITICAL();
}

static const log_port_t freertos_port = {
    .init   = rtos_init,
    .write  = rtos_write,
    .flush  = rtos_flush,
    .lock   = rtos_lock,
    .unlock = rtos_unlock,
};

void log_port_freertos_register(void) {
    log_port_register(&freertos_port);
}

  关键点： RTOS 下一定要考虑中断安全。不要在中断服务函数里直接调用日志输出，最好用队列或信号量做异步处理。我见过有人直接在中断里调 printf，结果系统直接死锁。

抽象层核心流程图

下面这张图展示了日志系统跨平台移植的整体架构。我画得比较简洁，但核心逻辑都在里面了。

如何选择输出方式？

不同场景下，输出方式的选择也有讲究。我整理了一个表格，方便大家参考：

平台	推荐输出方式	优点	缺点
Linux	fwrite + syslog	性能好，支持重定向	依赖 glibc
Windows	WriteConsole + OutputDebugString	调试器可见，支持颜色	Release 模式需额外处理
FreeRTOS	UART DMA + 消息队列	中断安全，不阻塞任务	需要硬件支持
裸机	直接写寄存器 + 轮询	无依赖，最轻量	会阻塞 CPU

避坑指南

最后分享几个我踩过的坑，希望能帮大家少走弯路：

不要用 printf 做日志输出——printf 内部有锁，在多线程环境下容易死锁。我遇到过最诡异的情况是，日志打印把自己给打印死了。
注意缓冲区大小——RTOS 下栈空间有限，日志缓冲区别开太大。我一般设 256 字节，够用就行。
考虑日志丢失的情况——在极端负载下，日志可能来不及输出。加一个丢弃策略，别让日志拖垮系统。
统一时间戳格式——不同平台的时间获取方式不同，但输出格式要统一。我习惯用 [YYYY-MM-DD HH:MM:SS.mmm] 这种格式。

我的习惯： 在项目初期就把日志抽象层搭好，哪怕一开始只用一个平台。后面移植的时候，只需要写一个新的 log_port_xxx.c 文件，注册一下就行。这个习惯帮我省了至少一半的移植时间。

好了，关于日志系统的跨平台移植，核心就是抽象层设计。记住一句话：上层写逻辑，底层写实现，中间用接口隔开。这样不管换什么平台，你的日志系统都能稳稳地跑起来。

📚 课程目录

日志系统移植：跨平台兼容（Linux/Windows/RTOS），抽象层设计

为什么需要跨平台兼容？

抽象层设计思路

Linux 平台实现

Windows 平台实现

RTOS 平台实现（以 FreeRTOS 为例）

抽象层核心流程图

如何选择输出方式？

避坑指南