Keil5中使用printf重定向到串口

Keil5中实现printf重定向到串口的深度解析与工程实践

在嵌入式开发的世界里，调试从来都不是一件轻松的事。没有显示器、没有键盘，甚至连一个像样的输出终端都没有——我们面对的往往是一块静静躺着的PCB板子，上面闪烁着几颗LED灯。当程序跑飞了、外设没响应、变量值异常时， “我到底该从哪里开始查？” 这个问题几乎每个工程师都曾深夜自问过。

而在这片黑暗中，最明亮的一束光，就是 printf 。

是的，那个你在大学C语言课上写“Hello World”时用过的函数，在裸机系统里依然能成为你最忠实的伙伴。只不过它不再打印到控制台，而是通过一根小小的串口线，把信息传送到你的电脑屏幕上。这种技术叫做 printf 重定向 ，它是嵌入式调试的基石之一。

但别以为这只是简单地“让printf输出到串口”这么简单。当你真正尝试去做的时候，可能会发现：明明写了代码，却什么都没输出；或者程序卡死不动；又或者浮点数直接导致HardFault……这些问题背后，其实藏着整个编译器、标准库、硬件初始化和链接机制之间的精密协作。

今天，我们就来彻底拆解这件事——从底层原理到编码实现，再到高级优化，带你一步步构建一个 稳定、高效、可移植且具备工程化能力的调试输出系统 。

---

一、为什么标准 printf 不能直接用？微库才是关键突破口 🧩

先问一个问题：

“我在Keil里写了个 printf("Hello"); ，为什么没反应？”

答案可能出乎意料： 因为根本没有地方可以输出。

在PC上， printf 会调用操作系统的I/O接口，最终显示在终端窗口里。但在单片机里呢？没有操作系统，没有文件系统，连最基本的“stdout”设备都不存在。那 printf 往哪儿打？

这时候就得靠 C运行时库（CRT） 来兜底了。Keil MDK默认使用ARM提供的标准C库，其中 printf 的底层依赖于几个核心函数，比如：

• fputc(int ch, FILE *f) —— 写一个字符
• fgetc(FILE *f) —— 读一个字符

这些函数原本应该由操作系统提供具体实现，但在裸机环境下，它们被定义为 弱符号（weak symbol） ，意味着你可以自己重新实现它们，从而“接管”输出行为。

但是！这里有个致命前提： 必须启用 MicroLIB。

🔍 MicroLIB 到底是什么？

MicroLIB 是 ARM 官方为资源受限环境设计的一个轻量级C库替代方案。它做了三件非常重要的事：

1. 大幅减小代码体积
   标准C库动辄几百KB，而MicroLIB通常只有几KB到几十KB，适合烧录进Flash有限的MCU。

2. 移除不必要的功能
   比如多线程支持、复杂的locale处理、完整的文件系统抽象等，在单片机上基本用不到。

3. 开放I/O接口供用户重写
   最关键的一点： fputc 和 fgetc 被声明为弱符号，允许你用自己的版本覆盖。

如果你不勾选“Use MicroLIB”，Keil就会链接完整版C库，里面的 fputc 是强符号——你再怎么写自己的 fputc ，链接器都会报错：

error: L6200E: Symbol fputc multiply defined

所以记住一句话：

✅ 想重定向printf？第一步永远是打开 Use MicroLIB。

这个选项藏在哪？很简单：

Project → Options for Target → Target → ✔ Use MicroLIB

一旦开启，你会发现编译日志里多了一行提示：

using MicroLib C library

恭喜，你现在拥有了“劫持”标准输出的能力。

---

二、准备工作远比你以为的重要 ⚙️

很多人一上来就想写 fputc ，结果程序一运行就卡住或崩溃。原因往往是忽略了前置条件。就像你想开车出门，却发现油箱是空的、轮胎没气、钥匙还没拿。

以下是四个必须完成的技术准备环节，缺一不可。

2.1 开发环境与项目配置：别让工具链拖后腿

虽然Keil支持多个版本，但我们建议使用 Keil MDK 5.20 及以上 + Arm Compiler 6 。原因如下：

特性	Arm Compiler 5	Arm Compiler 6
C99/C11 支持	基本支持	更完善
弱符号处理	有时不稳定	更可靠
内联汇编语法	AT&T风格	更接近GNU
性能优化	中等	更优

特别是对于现代STM32芯片（如G0、H7系列），AC6的支持更好，也能避免一些奇怪的链接问题。

📌 创建项目时注意以下几点：
- 正确选择MCU型号（例如 STM32F407VG）
- 自动生成启动文件（如 startup_stm32f407xx.s ）
- 设置晶振频率（HSE=8MHz 或其他实际值）
- 输出格式选 AXF（带调试符号）

如果从STM32CubeIDE导入工程，记得检查分散加载文件（scatter file）是否正确映射了内存段，否则可能出现 .data 未初始化的问题。

配置项	推荐值	说明
Keil MDK 版本	≥ v5.20	支持最新 CMSIS 和编译器特性
编译器版本	Arm Compiler 6 (v6.x)	更优性能与标准合规性
输出格式	AXF	调试信息完整，支持符号表
启动文件	匹配芯片型号	如 startup_stm32f407xx.s

💡 小技巧：可以在C/C++选项卡中添加宏 __MICROLIB ，这样某些头文件可以根据此宏进行条件编译。

---

2.2 MCU选型与串口初始化：硬件准备好了吗？

不是所有MCU都适合做调试输出。你需要至少一个可用的USART/UART外设，并且对应的GPIO引脚要能接出来。

推荐几款常用型号：

型号	特点	是否推荐
STM32F103C8T6	经典“蓝丸”，价格便宜	✅ 入门首选
STM32F407VGT6	多达6个串口，高性能	✅ 项目级调试
STM32G070KB	低功耗，集成度高	✅ 新架构学习

无论哪种型号， 串口初始化一定要在调用任何 printf 之前完成！

想象一下：你还没打开水龙头，就急着按水泵按钮，结果只会是堵住管道。同理，如果你在 main() 一开始就打 printf ，但此时UART时钟还没开、引脚也没配置，那 fputc 里的发送寄存器访问就会失败，甚至引发HardFault。

以STM32F4为例，使用HAL库初始化USART2的基本流程如下：

UART_HandleTypeDef huart2;

void MX_USART2_UART_Init(void)
{
    huart2.Instance = USART2;
    huart2.Init.BaudRate = 115200;
    huart2.Init.WordLength = UART_WORDLENGTH_8B;
    huart2.Init.StopBits = UART_STOPBITS_1;
    huart2.Init.Parity = UART_PARITY_NONE;
    huart2.Init.Mode = UART_MODE_TX_RX;
    huart2.Init.HwFlowCtl = UART_HWCONTROL_NONE;
    huart2.Init.OverSampling = UART_OVERSAMPLING_16;

    if (HAL_UART_Init(&huart2) != HAL_OK)
    {
        Error_Handler();
    }
}

这段代码看起来简单，但它背后触发了一系列复杂的硬件操作：

1. 开启APB1总线上USART2的时钟
2. 配置PA2(TX)和PA3(RX)为复用推挽模式
3. 设置波特率分频系数（基于PCLK）
4. 启动UART模块

⚠️ 特别提醒：如果你用了STM32CubeMX生成代码，记得确认 HAL_UART_MspInit() 是否自动调用了 __HAL_RCC_USART2_CLK_ENABLE() 和GPIO初始化函数。

---

2.3 启动文件与中断向量表：别让HardFault偷袭你 💣

很多初学者遇到这种情况：“我明明只打了两行printf，怎么突然进HardFault了？”

原因之一可能是： 全局构造函数提前调用了printf！

在C++项目中，或者某些带有全局对象初始化的C项目里，编译器会在 main() 之前执行一段初始化代码（位于启动文件中的Reset_Handler）。如果这段代码里有静态对象构造，并且其构造函数里调用了 printf ，而此时UART还没初始化——Boom！

解决办法有两个：

1. 严格禁止在全局作用域使用printf
2. 确保所有外设在Reset_Handler之后立即初始化

此外，还要检查中断向量表是否完整。比如你用了USART2中断，但在 startup_stm32f407xx.s 中忘了声明ISR：

                DCD     USART2_IRQHandler        ; USART2

如果没有这一行，当中断触发时CPU找不到入口地址，就会跳转到HardFault_Handler。

📌 所以说，启动文件不仅仅是“跳转到main”的脚本，它决定了整个系统的安全边界。

---

2.4 头文件管理与宏抽象：别让重复定义搞崩编译

良好的头文件组织能让代码更健壮。尤其是在混合使用HAL库、标准外设库和自定义驱动时，顺序很重要。

❌ 错误示范：

#include <stdio.h>
#include "stm32f4xx_hal.h"

stdio.h 里可能包含一些类型定义（如 size_t ），如果后续HAL头文件也试图定义，就会冲突。

✅ 正确做法：

#include "main.h"      // 包含所有HAL和设备相关头文件
#include <stdio.h>     // 最后引入标准库

同时，为了提高可移植性，建议将调试串口抽象成宏：

#define DEBUG_USART          USART2
#define DEBUG_USART_CLK_EN() __USART2_CLK_ENABLE()
#define DEBUG_USART_TX_PIN   GPIO_PIN_2
#define DEBUG_USART_GPIO_PORT GPIOA
#define DEBUG_USART_AF       GPIO_AF7_USART2
#define DEBUG_BAUDRATE       115200

这样换一块板子，只需要改这几个宏即可，无需修改 fputc 逻辑。

---

三、动手实现：三种不同层级的 fputc 写法 💻

现在终于到了最激动人心的部分：写代码！

我们将从三个层次逐步深入，展示如何写出既高效又灵活的 fputc 函数。

3.1 层次一：基于HAL库的安全封装（适合新手）

这是最推荐给初学者的方式。利用HAL库的高度抽象，让你专注于逻辑而非寄存器细节。

#include <stdio.h>
#include "main.h"

extern UART_HandleTypeDef huart2;  // 由MX_USART2_UART_Init()创建

int fputc(int ch, FILE *f)
{
    uint8_t temp = (uint8_t)ch;

    // 处理换行符 \n -> \r\n
    if (ch == '\n')
    {
        HAL_UART_Transmit(&huart2, (uint8_t*)"\r", 1, 100);
    }

    HAL_UART_Transmit(&huart2, &temp, 1, 100);

    return ch;
}

亮点解析：

• 自动补 \r ：Windows串口助手需要 \r\n 才能换行，而 printf 只输出 \n ，所以手动补一个回车。
• 超时设置为100ms ：防止无限等待，增强鲁棒性。
• 返回原字符 ：符合ISO C标准，告诉上层函数“我成功了”。

🎯 适用场景：快速原型验证、教学演示、非实时任务。

---

3.2 层次二：寄存器直写，极致效率（适合性能敏感系统）

当你对延迟极其敏感时（比如电机控制、高速采样），每一次函数调用都是奢侈。这时可以直接操作寄存器。

int fputc(int ch, FILE *f)
{
    // 等待发送数据寄存器空
    while (!(USART2->SR & USART_SR_TXE))
    {
        // 可加入超时判断
    }

    // 发送字符
    USART2->DR = (uint8_t)ch;

    // 补\r
    if (ch == '\n')
    {
        while (!(USART2->SR & USART_SR_TXE));
        USART2->DR = (uint8_t)'\r';
    }

    return ch;
}

寄存器说明：

寄存器	功能
USART2->SR	状态寄存器，TXE位表示TDR空
USART2->DR	数据寄存器，写入即开始发送

⚡ 优势：无函数调用开销，执行速度极快。
⛔ 缺点：硬编码了USART2，移植性差。

🔧 改进建议：用宏封装，提升通用性：

#define DEBUG_UART   USART2
#define TX_EMPTY     USART_SR_TXE
#define STATUS_REG   SR
#define DATA_REG     DR

while (!(DEBUG_UART->STATUS_REG & TX_EMPTY));
DEBUG_UART->DATA_REG = ch;

这样一来，换个芯片只需改宏定义。

---

3.3 层次三：极简独立模块，适用于Bootloader等场景

在某些极端环境中（比如Bootloader、安全固件），你甚至不能依赖CMSIS或HAL库。这时候就需要一个完全自包含的最小化实现。

我们可以做一个头文件+源文件的组合：

// minimal_uart_printf.h
#ifndef MINIMAL_UART_PRINTF_H
#define MINIMAL_UART_PRINTF_H

#include <stdio.h>

#ifndef DEBUG_USART_BASE
#error "Please define DEBUG_USART_BASE, e.g., (0x40004400 for USART2)"
#endif

#ifdef USART_ISR_TXE  // Newer chips (G0/H7)
  #define REG_SR   ISR
  #define REG_DR   TDR
  #define FLAG_TXE USART_ISR_TXE
#else                 // Older (F4/F1)
  #define REG_SR   SR
  #define REG_DR   DR
  #define FLAG_TXE USART_SR_TXE
#endif

int fputc(int ch, FILE *f);

#endif

配套的 .c 文件：

// minimal_uart_printf.c
#include "minimal_uart_printf.h"

#define DEBUG_USART ((USART_TypeDef *)DEBUG_USART_BASE)

int fputc(int ch, FILE *f)
{
    uint32_t timeout = 10000;

    while ((DEBUG_USART->REG_SR & FLAG_TXE) == 0)
    {
        if (--timeout == 0) return EOF;
    }
    DEBUG_USART->REG_DR = (uint8_t)ch;

    if (ch == '\n')
    {
        timeout = 10000;
        while ((DEBUG_USART->REG_SR & FLAG_TXE) == 0)
        {
            if (--timeout == 0) return EOF;
        }
        DEBUG_USART->REG_DR = (uint8_t)'\r';
    }

    return ch;
}

📌 使用方式：

#define DEBUG_USART_BASE  ((uint32_t)USART2)
#include "minimal_uart_printf.h"

这套方案完全脱离HAL/CMSIS，仅依赖基础类型定义，非常适合资源极度紧张的环境。

---

四、不只是串口：扩展你的输出通道 🌐

fputc 的强大之处在于它的抽象性。只要你能“放一个字符”，就可以把它变成输出设备。

4.1 输出到LCD屏幕（伪代码示例）

extern void LCD_DrawChar(int x, int y, char c);
static int cursor_x = 0, cursor_y = 0;

int fputc(int ch, FILE *f)
{
    if (ch == '\n')
    {
        cursor_x = 0;
        cursor_y += 16;
    }
    else
    {
        LCD_DrawChar(cursor_x, cursor_y, ch);
        cursor_x += 8;
    }
    return ch;
}

从此，你的GUI界面也可以接收日志了！

---

4.2 USB虚拟串口（CDC）重定向

结合STM32的USB CDC功能，可以把日志通过USB传到电脑，免去额外串口线。

extern USBD_HandleTypeDef hUsbDeviceFS;

int fputc(int ch, FILE *f)
{
    uint8_t data[1] = { (uint8_t)ch };
    USBD_CDC_SetTxBuffer(&hUsbDeviceFS, data, 1);
    USBD_CDC_TransmitPacket(&hUsbDeviceFS);
    return ch;
}

⚠️ 注意：USB传输有最小间隔限制（约1ms），不适合高频日志。

---

4.3 多串口动态路由：按需输出到不同端口

随着系统复杂化，你可能希望：

• LOG_ERROR → 串口1（连接PLC）
• LOG_DEBUG → 串口2（连接PC）
• LOG_TRACE → DMA上传到云端

这可以通过 FILE* 指针区分目标流来实现：

#define STREAM_DEBUG  ((FILE*)0x1234)
#define STREAM_TRACE  ((FILE*)0x5678)

int fputc(int ch, FILE *f)
{
    UART_HandleTypeDef *huart;

    if (f == STREAM_DEBUG) huart = &huart1;
    else if (f == STREAM_TRACE) huart = &huart2;
    else return EOF;

    HAL_UART_Transmit(huart, (uint8_t*)&ch, 1, 100);

    if (ch == '\n') {
        HAL_UART_Transmit(huart, (uint8_t*)"\r", 1, 100);
    }

    return ch;
}

调用方式：

fprintf(STREAM_DEBUG, "Error occurred at line %d\n", __LINE__);

是不是有点像Linux下的 syslog 了？

---

五、实战测试：看看效果究竟如何？🧪

一切准备就绪，来跑个真实例子吧！

int main(void)
{
    HAL_Init();
    SystemClock_Config();
    MX_USART2_UART_Init();

    printf("🎉 Hello from STM32! Built on %s %s\n", __DATE__, __TIME__);

    int val = 42;
    float pi = 3.1415926f;
    printf("🔢 数值测试: dec=%d, hex=0x%08X, float=%.3f\n", val, val, pi);

    while (1)
    {
        printf("⏱️ Tick: %lu ms\n", HAL_GetTick());
        HAL_Delay(1000);
    }
}

打开串口助手（推荐 XCOM / PuTTY / CoolTerm），设置：

参数	值
波特率	115200
数据位	8
停止位	1
校验	None
流控	None
显示模式	文本

你应该能看到类似这样的输出：

🎉 Hello from STM32! Built on Oct 20 2023 14:30:00
🔢 数值测试: dec=42, hex=0x0000002A, float=3.142
⏱️ Tick: 1000 ms
⏱️ Tick: 2000 ms
...

如果浮点数输出乱码或卡死，请检查：

Project → Options for Target → Target → ✔ Use float in printf

这个选项会启用浮点格式化支持，代价是增加约2–4KB代码空间。

---

六、性能优化：别让 printf 拖慢系统 ⚡

虽然方便，但 printf 是个“重量级选手”。我们来做个实测（STM32F407 @ 168MHz）：

调用	平均耗时
printf("OK\r\n")	~1.2ms
printf("%d", 12345)	~1.8ms
printf("%.2f", 3.14)	~3.5ms

这意味着：每秒最多只能打800条纯文本日志。如果频率更高，CPU将长时间阻塞。

优化策略一览：

方法	CPU占用降低	实现难度	推荐指数
关闭浮点支持	~30%	★☆☆	⭐⭐⭐⭐
使用 sprintf + DMA	~70%	★★★	⭐⭐⭐⭐⭐
定制简化函数（如 printi ）	~50%	★★☆	⭐⭐⭐
异步队列 + 空闲中断	~85%	★★★★	⭐⭐⭐⭐⭐

示例：基于DMA的异步输出

char log_buf[128];
uint8_t idx = 0;

int fputc(int ch, FILE *f)
{
    log_buf[idx++] = ch;

    if (ch == '\n' || idx >= 127)
    {
        log_buf[idx] = '\0';
        HAL_UART_Transmit_DMA(&huart2, (uint8_t*)log_buf, idx);
        idx = 0;
    }
    return ch;
}

这种方式把多次小数据合并成一次DMA传输，极大减轻CPU负担。

---

七、工程化封装：打造专业的调试日志系统 🛠️

在大型项目中，我们应该把调试输出做成一个独立模块。

设计一个现代化的日志系统：

// debug_log.h
#ifndef __DEBUG_LOG_H
#define __DEBUG_LOG_H

#include <stdio.h>

typedef enum {
    LOG_LEVEL_ERROR,
    LOG_LEVEL_WARN,
    LOG_LEVEL_INFO,
    LOG_LEVEL_DEBUG
} LogLevel;

void Debug_Init(void);
void Debug_SetLevel(LogLevel level);
int  Debug_Printf(const char* fmt, ...);

#ifdef DEBUG_ENABLE
    #define LOGI(fmt, ...) Debug_Printf("[INFO] " fmt "\r\n", ##__VA_ARGS__)
    #define LOGE(fmt, ...) Debug_Printf("[ERROR] " fmt "\r\n", ##__VA_ARGS__)
    #define LOGD(fmt, ...) Debug_Printf("[DEBUG] " fmt "\r\n", ##__VA_ARGS__)
#else
    #define LOGI(fmt, ...)
    #define LOGE(fmt, ...)
    #define LOGD(fmt, ...)
#endif

#endif

配合RTOS还能实现完全异步的日志队列：

QueueHandle_t log_queue;

void LogTask(void *pvParameters)
{
    char msg[64];
    for (;;)
    {
        if (xQueueReceive(log_queue, msg, portMAX_DELAY))
        {
            printf("%s", msg);  // 在单独任务中输出
        }
    }
}

主任务再也不用担心被I/O卡住了。

---

结语：让 printf 成为你的超级武器 🔫

看到这里，你应该已经掌握了从零搭建一套完整 printf 重定向系统的能力。这不是一个简单的“重写fputc”技巧，而是一种贯穿编译器、库、硬件、软件架构的综合能力体现。

下次当你面对一个“莫名其妙”的bug时，不妨试试：

LOGD("进入状态机，当前状态：%d", state);

也许就在那一瞬间，真相大白。

毕竟，在嵌入式世界里， 最强大的调试工具，往往是最简单的那一行 printf 。 😎