510 lines
18 KiB
C
510 lines
18 KiB
C
/**
|
||
******************************************************************************
|
||
* @file uart2_print.c
|
||
* @brief UART2调试打印模块实现
|
||
* @author Application Layer
|
||
* @version 1.1
|
||
******************************************************************************
|
||
* @attention
|
||
* 本模块实现基于环形缓冲区的非阻塞调试信息输出
|
||
* 关键特性：
|
||
* 1. 环形缓冲区避免数据丢失
|
||
* 2. 中断安全，支持ISR中调用
|
||
* 3. 非阻塞发送，不影响实时性
|
||
*
|
||
* 修订历史：
|
||
* v1.1 - 修复审查报告高危-1/2/3，中危-4
|
||
******************************************************************************
|
||
*/
|
||
|
||
#include "uart2_print.h"
|
||
#include "usart.h"
|
||
#include <string.h>
|
||
#include <stdio.h>
|
||
|
||
/*==============================================================================
|
||
* 调试宏定义
|
||
*============================================================================*/
|
||
/* DEBUG_PRINT_ENABLED: 调试日志开关，置1时启用模块自测日志输出 */
|
||
#define DEBUG_PRINT_ENABLED 1
|
||
|
||
#if DEBUG_PRINT_ENABLED
|
||
/* 调试日志宏，带模块前缀"[UART2]"方便过滤日志 */
|
||
#define DEBUG_LOG(fmt, ...) UART2_Print_Printf("[UART2] " fmt "\r\n", ##__VA_ARGS__)
|
||
#else
|
||
/* 禁用时为空宏，避免无用代码生成 */
|
||
#define DEBUG_LOG(fmt, ...)
|
||
#endif
|
||
|
||
/*==============================================================================
|
||
* 数据结构定义
|
||
*============================================================================*/
|
||
/**
|
||
* @brief 环形发送缓冲区数据结构
|
||
* @note 采用Ring Buffer(环形缓冲区)设计，实现FIFO队列管理
|
||
*
|
||
* 设计目的：
|
||
* 解决UART发送与CPU执行速度不匹配的问题。当UART正在发送数据时，
|
||
* 后续数据先存入缓冲区，待发送完成后再取出发送，实现异步非阻塞打印。
|
||
* 环形缓冲区相比线性缓冲区的优势是无需数据搬移，head和tail指针
|
||
* 循环递增，到达末尾后自动回绕到开头。
|
||
*
|
||
* 字段说明：
|
||
* - buffer: 存放数据的字节数组，大小由UART2_TX_BUFFER_SIZE定义
|
||
* - head: 写入位置指针，指向下一个待写入位置(生产者指针)
|
||
* - tail: 读取位置指针，指向下一个待读取位置(消费者指针)
|
||
* - count: 当前缓冲区中有效数据字节数
|
||
* - is_sending: 发送忙标志，表示UART硬件是否正在发送数据
|
||
* - overflow_count: 溢出错误计数，缓冲区满时丢弃数据的次数
|
||
*
|
||
* 索引计算规则：
|
||
* head和tail均采用模运算实现回绕: new_index = (old_index + 1) % buffer_size
|
||
* 这确保了指针在达到缓冲区末尾时自动回到开头，形成"环形"效果
|
||
*
|
||
* 线程安全说明：
|
||
* 所有修改共享资源的代码段均使用__disable_irq/__enable_irq暂时禁用中断，
|
||
* 防止在临界区内被ISR打断导致数据竞争(race condition)
|
||
*/
|
||
typedef struct {
|
||
uint8_t buffer[UART2_TX_BUFFER_SIZE]; /**< 发送数据缓冲区，静态分配避免动态内存 */
|
||
volatile uint16_t head; /**< 写指针，下一个数据写入位置 */
|
||
volatile uint16_t tail; /**< 读指针，下一个数据读取位置 */
|
||
volatile uint16_t count; /**< 缓冲区中有效数据字节计数 */
|
||
volatile bool is_sending; /**< UART发送忙标志，防止重复启动发送 */
|
||
volatile uint16_t overflow_count; /**< 溢出错误计数，统计因缓冲区满丢弃的数据 */
|
||
} ring_buffer_t;
|
||
|
||
/*==============================================================================
|
||
* 全局变量定义
|
||
*============================================================================*/
|
||
/**
|
||
* @brief 环形发送缓冲区实例
|
||
* @note static修饰确保仅本文件内可访问，初始化为全零
|
||
*/
|
||
static ring_buffer_t tx_ring = {0};
|
||
|
||
/*==============================================================================
|
||
* 公共函数实现
|
||
*============================================================================*/
|
||
/**
|
||
* @brief UART2打印模块初始化
|
||
* @note 在系统启动或UART外设初始化后调用，重置环形缓冲区状态
|
||
*
|
||
* @param 无
|
||
* @return 无
|
||
*
|
||
* 功能说明：
|
||
* 1. 重置所有指针(head/tail/count)为初始状态
|
||
* 2. 清除发送忙标志
|
||
* 3. 清零溢出错误计数器
|
||
*
|
||
* 初始化安全：
|
||
* 此函数应在UART硬件初始化完成之后调用，确保huart2已正确配置
|
||
*/
|
||
void UART2_Print_Init(void)
|
||
{
|
||
/* 重置环形缓冲区各状态变量 */
|
||
tx_ring.head = 0;
|
||
tx_ring.tail = 0;
|
||
tx_ring.count = 0;
|
||
tx_ring.is_sending = false;
|
||
tx_ring.overflow_count = 0;
|
||
|
||
/* 输出模块初始化完成日志 */
|
||
DEBUG_LOG("Init OK, buffer size: %d", UART2_TX_BUFFER_SIZE);
|
||
}
|
||
|
||
/**
|
||
* @brief 发送数据到UART2(核心写入函数)
|
||
* @note 将数据写入环形缓冲区，若UART空闲则自动启动首次发送
|
||
* 此函数是线程安全的，可从ISR或主线程调用
|
||
*
|
||
* @param data: 待发送数据缓冲区的指针(输入)
|
||
* @param len: 待发送数据字节数(输入)
|
||
* @return 无返回值
|
||
*
|
||
* 算法说明 - 生产者逻辑：
|
||
* 1. 遍历待发送数据的每个字节
|
||
* 2. 检查缓冲区是否有空间(count < buffer_size)
|
||
* 3. 如有空间，将数据写入buffer[head]，head递增并回绕
|
||
* 4. 如缓冲区满，放弃剩余数据并增加overflow_count
|
||
*
|
||
* 发送触发机制：
|
||
* - 如果缓冲区有数据且UART当前空闲(is_sending=false)，
|
||
* 设置is_sending=true并立即触发首次发送(Kickoff)
|
||
* - 后续发送由TxCpltCallback中断回调驱动，形成连续发送直到缓冲区清空
|
||
*
|
||
* 中断安全：
|
||
* - 使用__disable_irq/__enable_irq保护临界区
|
||
* - 防止在检查count和写入buffer之间被ISR打断
|
||
*/
|
||
void UART2_Print_Send(const uint8_t *data, uint16_t len)
|
||
{
|
||
/* 参数合法性检查，防止空指针或零长度 */
|
||
if (len == 0 || data == NULL) {
|
||
return;
|
||
}
|
||
|
||
uint16_t written = 0;
|
||
bool needs_kickoff = false;
|
||
|
||
/*----------------------------------------------------------
|
||
* 临界区：禁用中断，保护共享缓冲区的写入操作
|
||
*----------------------------------------------------------*/
|
||
__disable_irq();
|
||
for (uint16_t i = 0; i < len; i++) {
|
||
/* 检查缓冲区是否有空间 */
|
||
if (tx_ring.count >= UART2_TX_BUFFER_SIZE) {
|
||
/* 缓冲区已满，丢弃数据并计数 */
|
||
tx_ring.overflow_count++;
|
||
break;
|
||
}
|
||
|
||
/* 将数据写入环形缓冲区，更新写指针(模缓冲区大小回绕) */
|
||
tx_ring.buffer[tx_ring.head] = data[i];
|
||
tx_ring.head = (tx_ring.head + 1) % UART2_TX_BUFFER_SIZE;
|
||
tx_ring.count++;
|
||
written++;
|
||
}
|
||
|
||
/*----------------------------------------------------------
|
||
* 判断是否需要触发首次发送
|
||
* 条件：成功写入数据 AND UART当前处于空闲状态
|
||
*----------------------------------------------------------*/
|
||
if (written > 0 && !tx_ring.is_sending) {
|
||
tx_ring.is_sending = true;
|
||
needs_kickoff = true;
|
||
}
|
||
__enable_irq(); /* 退出临界区 */
|
||
|
||
/*----------------------------------------------------------
|
||
* 启动首次发送(Kickoff)
|
||
* 从缓冲区取出第一个字节通过DMA/中断方式发送
|
||
*----------------------------------------------------------*/
|
||
if (needs_kickoff) {
|
||
uint8_t byte;
|
||
/* 再次禁用中断以读取尾指针(消费者操作) */
|
||
__disable_irq();
|
||
byte = tx_ring.buffer[tx_ring.tail];
|
||
__enable_irq();
|
||
/* 启动UART中断发送，发送完成后会触发TxCpltCallback */
|
||
HAL_UART_Transmit_IT(&huart2, &byte, 1);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* @brief 发送字符串到UART2
|
||
* @note 封装UART2_Print_Send，自动计算字符串长度
|
||
*
|
||
* @param str: 待发送的以'\0'结尾的字符串指针(输入)
|
||
* @return 无返回值
|
||
*
|
||
* 使用说明：
|
||
* - str必须为有效指针且以'\0'结尾
|
||
* - strlen计算长度时不包括终止符，所以实际发送的也不包括
|
||
*/
|
||
void UART2_Print_String(const char *str)
|
||
{
|
||
/* 空指针保护 */
|
||
if (str == NULL) {
|
||
return;
|
||
}
|
||
/* 使用strlen获取字符串长度并发送 */
|
||
UART2_Print_Send((const uint8_t *)str, strlen(str));
|
||
}
|
||
|
||
/**
|
||
* @brief 格式化打印到UART2
|
||
* @note 仿printf风格，支持可变参数格式化输出
|
||
*
|
||
* @param fmt: 格式化字符串，与printf语法兼容(输入)
|
||
* @param ...: 可变参数列表，对应格式化字符串中的占位符(输入)
|
||
* @return 无返回值
|
||
*
|
||
* 实现说明：
|
||
* 1. 使用va_list/va_start/va_end处理可变参数
|
||
* 2. vsnprintf将格式化参数写入临时缓冲区(128字节)
|
||
* 3. 将格式化后的字符串通过UART2_Print_Send发送
|
||
*
|
||
* 缓冲区限制：
|
||
* - 最大格式化输出为127字节(128-1留作字符串终止符)
|
||
* - 超出部分会被截断，不报错
|
||
*
|
||
* 线程安全：
|
||
* 此函数本身是中断安全的，但内部调用UART2_Print_Send，
|
||
* 多线程并发调用时输出可能交叉
|
||
*/
|
||
void UART2_Print_Printf(const char *fmt, ...)
|
||
{
|
||
/* 格式化字符串合法性检查 */
|
||
if (fmt == NULL) {
|
||
return;
|
||
}
|
||
|
||
char buffer[128]; /* 临时格式化缓冲区，大小固定 */
|
||
va_list args; /* 可变参数列表变量 */
|
||
|
||
/*----------------------------------------------------------
|
||
* 可变参数处理：初始化va_list并执行格式化
|
||
*----------------------------------------------------------*/
|
||
va_start(args, fmt);
|
||
int len = vsnprintf(buffer, sizeof(buffer), fmt, args);
|
||
va_end(args);
|
||
|
||
/*----------------------------------------------------------
|
||
* 发送格式化后的字符串
|
||
* vsnprintf返回值len:
|
||
* - >=0: 成功格式化，需要发送的字符数(不含终止符)
|
||
* - <0: 格式化失败，不发送任何数据
|
||
*----------------------------------------------------------*/
|
||
if (len >= 0) {
|
||
/* 边界检查：若len超过缓冲区实际容量则截断 */
|
||
if (len >= (int)sizeof(buffer)) {
|
||
len = sizeof(buffer) - 1;
|
||
}
|
||
UART2_Print_Send((const uint8_t *)buffer, len);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* @brief UART2打印任务(轮询模式驱动)
|
||
* @note 在主循环或定时器中调用，驱动环形缓冲区数据发送
|
||
* 与TxCpltCallback配合形成轮询+中断混合发送模式
|
||
*
|
||
* @param 无
|
||
* @return 无
|
||
*
|
||
* 工作原理：
|
||
* 正常发送流程依赖TxCpltCallback中断回调驱动。但若某些平台
|
||
* 或情况下中断被屏蔽，此函数作为备用发送机制，从缓冲区取出
|
||
* 数据启动新的发送。
|
||
*
|
||
* 调用时机：
|
||
* 建议在主循环中周期性调用(如每次循环或10ms定时)，
|
||
* 配合UART空闲中断或DMA完成中断实现高效发送
|
||
*
|
||
* 中断安全：
|
||
* - 使用__disable_irq/__enable_irq保护临界区
|
||
*/
|
||
void UART2_Print_Task(void)
|
||
{
|
||
uint8_t byte;
|
||
uint16_t current_tail;
|
||
|
||
/*----------------------------------------------------------
|
||
* 临界区：检查是否可以发送
|
||
*----------------------------------------------------------*/
|
||
__disable_irq();
|
||
/* 条件：不正在发送 且 缓冲区有数据 */
|
||
if (tx_ring.is_sending || tx_ring.count == 0) {
|
||
__enable_irq();
|
||
return; /* 条件不满足，不执行发送 */
|
||
}
|
||
|
||
/*----------------------------------------------------------
|
||
* 从缓冲区取出数据，更新读指针
|
||
*----------------------------------------------------------*/
|
||
current_tail = tx_ring.tail;
|
||
tx_ring.tail = (tx_ring.tail + 1) % UART2_TX_BUFFER_SIZE; /* 环形回绕 */
|
||
tx_ring.count--;
|
||
tx_ring.is_sending = true; /* 标记为发送中，防止重复启动 */
|
||
byte = tx_ring.buffer[current_tail];
|
||
__enable_irq(); /* 退出临界区 */
|
||
|
||
/*----------------------------------------------------------
|
||
* 启动UART中断发送
|
||
*----------------------------------------------------------*/
|
||
HAL_UART_Transmit_IT(&huart2, &byte, 1);
|
||
}
|
||
|
||
/**
|
||
* @brief UART发送完成回调函数
|
||
* @note 应在UART TX完成中断中调用，负责驱动环形缓冲区连续发送
|
||
* 此函数是发送流程的核心驱动引擎
|
||
*
|
||
* @param 无
|
||
* @return 无
|
||
*
|
||
* 工作原理 - 消费者逻辑：
|
||
* 1. 清除is_sending标志，表示UART硬件已空闲
|
||
* 2. 检查环形缓冲区是否还有待发送数据
|
||
* 3. 如有，取出下一字节并启动新的发送
|
||
* 4. 重复上述过程直到缓冲区清空
|
||
*
|
||
* 中断安全：
|
||
* - 使用__disable_irq/__enable_irq保护共享数据访问
|
||
* - 在中断上下文调用，必须确保操作原子性
|
||
*
|
||
* 调用约定：
|
||
* 此函数需要与HAL库中断处理正确关联，通常在
|
||
* HAL_UART_TxCpltCallback中断回调中调用
|
||
*/
|
||
void UART2_Print_TxCpltCallback(void)
|
||
{
|
||
uint8_t byte;
|
||
uint16_t current_tail;
|
||
bool has_more = false;
|
||
|
||
/*----------------------------------------------------------
|
||
* 第一步：标记UART为空闲状态
|
||
*----------------------------------------------------------*/
|
||
__disable_irq();
|
||
tx_ring.is_sending = false;
|
||
|
||
/*----------------------------------------------------------
|
||
* 第二步：检查缓冲区是否有更多数据待发送
|
||
*----------------------------------------------------------*/
|
||
if (tx_ring.count > 0) {
|
||
/* 取出下一字节，更新读指针(环形回绕) */
|
||
current_tail = tx_ring.tail;
|
||
tx_ring.tail = (tx_ring.tail + 1) % UART2_TX_BUFFER_SIZE;
|
||
tx_ring.count--;
|
||
tx_ring.is_sending = true; /* 立即标记为发送中 */
|
||
byte = tx_ring.buffer[current_tail];
|
||
has_more = true; /* 标记有待发送数据 */
|
||
}
|
||
__enable_irq();
|
||
|
||
/*----------------------------------------------------------
|
||
* 第三步：如有待发送数据，立即启动下一次发送
|
||
*----------------------------------------------------------*/
|
||
if (has_more) {
|
||
HAL_UART_Transmit_IT(&huart2, &byte, 1);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* @brief 查询发送模块忙状态
|
||
* @note 用于判断是否有数据正在发送或缓冲区中是否有待发数据
|
||
*
|
||
* @param 无
|
||
* @return bool: true=忙(正在发送或缓冲区有数据)，false=空闲
|
||
*
|
||
* 使用场景：
|
||
* - 在进入低功耗模式前检查是否有数据待发送
|
||
* - 在系统关机前确认所有调试日志已发送完毕
|
||
*
|
||
* 中断安全：
|
||
* - 使用临界区保护，确保检查到返回之间数据不被修改
|
||
*/
|
||
bool UART2_Print_IsBusy(void)
|
||
{
|
||
bool busy;
|
||
__disable_irq();
|
||
busy = tx_ring.is_sending || (tx_ring.count > 0);
|
||
__enable_irq();
|
||
return busy;
|
||
}
|
||
|
||
/**
|
||
* @brief 查询发送缓冲区可用空间
|
||
* @note 返回环形缓冲区当前剩余可写入的空间大小
|
||
*
|
||
* @param 无
|
||
* @return uint16_t: 可用字节数
|
||
*
|
||
* 计算公式：available = buffer_size - count
|
||
*
|
||
* 使用场景：
|
||
* - 在发送大数据块前检查缓冲区是否足够容纳
|
||
* - 实现流量控制逻辑
|
||
*
|
||
* 中断安全：
|
||
* - 使用临界区保护
|
||
*/
|
||
uint16_t UART2_Print_Available(void)
|
||
{
|
||
uint16_t available;
|
||
__disable_irq();
|
||
available = UART2_TX_BUFFER_SIZE - tx_ring.count;
|
||
__enable_irq();
|
||
return available;
|
||
}
|
||
|
||
/**
|
||
* @brief 获取溢出错误计数
|
||
* @note 统计因缓冲区满导致数据丢弃的次数，用于诊断
|
||
*
|
||
* @param 无
|
||
* @return uint16_t: 溢出错误累计次数
|
||
*
|
||
* 使用说明：
|
||
* - 此计数器仅在缓冲区满时递增
|
||
* - 若计数持续增长，说明UART发送速度跟不上数据产生速度
|
||
* - 可通过增大UART2_TX_BUFFER_SIZE或降低打印频率解决
|
||
*/
|
||
uint16_t UART2_Print_GetOverflowCount(void)
|
||
{
|
||
return tx_ring.overflow_count;
|
||
}
|
||
|
||
/*==============================================================================
|
||
* 标准库printf重定向实现
|
||
*============================================================================*/
|
||
/**
|
||
* @brief printf重定向函数 (Keil MDK编译器)
|
||
* @note 将标准库printf输出重定向到UART2
|
||
*
|
||
* @param ch: 待发送字符(输入)
|
||
* @param f: 文件指针(未使用，Keil MDK参数要求)
|
||
* @return int: 发送的字符
|
||
*
|
||
* 编译器条件编译：
|
||
* 此函数仅在__CC_ARM(或__ARMCC_VERSION)定义时编译，
|
||
* 即Keil MDK-ARM/ARMCC编译器环境下生效
|
||
*
|
||
* 实现说明：
|
||
* 标准库printf最终会调用fputc输出每个字符，
|
||
* 此处重定向到UART2_Print_Send实现串口打印
|
||
*/
|
||
#if defined(__CC_ARM) || defined(__ARMCC_VERSION)
|
||
int fputc(int ch, FILE *f)
|
||
{
|
||
(void)f; /* 未使用参数，避免编译器警告 */
|
||
UART2_Print_Send((uint8_t *)&ch, 1);
|
||
return ch;
|
||
}
|
||
#endif
|
||
|
||
/**
|
||
* @brief printf重定向函数 (GCC编译器 - 单字符版本)
|
||
* @note 将标准库printf输出重定向到UART2
|
||
*
|
||
* @param ch: 待发送字符(输入)
|
||
* @return int: 发送的字符
|
||
*
|
||
* 编译器条件编译：
|
||
* 此函数仅在__GNUC__定义时编译，即GCC/Clang编译器环境下生效
|
||
*
|
||
* 实现说明：
|
||
* 新一代ARM GCC使用__io_putchar作为printf输出目标，
|
||
* 此处将其重定向到UART2_Print_Send
|
||
*/
|
||
#if defined(__GNUC__)
|
||
int __io_putchar(int ch)
|
||
{
|
||
UART2_Print_Send((uint8_t *)&ch, 1);
|
||
return ch;
|
||
}
|
||
|
||
/**
|
||
* @brief write系统调用重定向 (GCC编译器)
|
||
* @note 将文件系统write调用重定向到UART2
|
||
*
|
||
* @param file: 文件描述符(未使用，仅为兼容标准接口)
|
||
* @param ptr: 数据缓冲区指针(输入)
|
||
* @param len: 数据长度(输入)
|
||
* @return int: 已发送的字节数
|
||
*
|
||
* 实现说明：
|
||
* 有些GCC配置下printf会调用_write而非__io_putchar，
|
||
* 此函数提供完整的write接口兼容
|
||
*/
|
||
int _write(int file, char *ptr, int len)
|
||
{
|
||
(void)file; /* 忽略文件描述符，只处理标准输出 */
|
||
UART2_Print_Send((uint8_t *)ptr, len);
|
||
return len;
|
||
}
|
||
#endif
|