xt_hal_uart - UART 驱动

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

---

一、概述

xt_hal_uart 是 XTINY HAL 层的 UART 驱动模块，提供串口初始化、关闭、三种发送模式（阻塞/零拷贝/流式）、流式接收和缓冲区管理。所有平台都必须实现此模块。

1.1 设计原则

• 发送多模式 ：提供阻塞、零拷贝和流式三种发送方式，覆盖不同实时性和内存需求
• 缓冲区独立管理 ：收发缓冲区由用户分配并通过 set_rx_buf / set_tx_buf 注入，模块不内部分配
• 回调驱动接收 ：数据到达和发送完成通过回调通知上层，不阻塞任务
• 预设配置宏 ：通过 XT_HAL_UART_8N1 等预设宏简化常见串口参数配置

1.2 依赖

依赖	用途
xt_hal_internal.h	HAL 内部类型与工具宏

---

二、核心概念

2.1 预设配置

UART 参数（数据位、校验、停止位）通过预设宏打包为一个 uint32_t 值传入 setup ：

预设宏	说明
XT_HAL_UART_8N1	8 位数据，无校验，1 位停止位
XT_HAL_UART_8E1	8 位数据，偶校验，1 位停止位
XT_HAL_UART_8O1	8 位数据，奇校验，1 位停止位
XT_HAL_UART_8N2	8 位数据，无校验，2 位停止位
XT_HAL_UART_8E2	8 位数据，偶校验，2 位停止位
XT_HAL_UART_8O2	8 位数据，奇校验，2 位停止位

也可通过 XT_HAL_UART_PRESET(_word, _parity, _stop) 宏自定义组合。

2.2 三种发送模式

模式	函数	行为
阻塞发送	xt_hal_uart_tx_block	阻塞等待全部数据发送完成，返回实际发送字节数
零拷贝发送	xt_hal_uart_tx_0copy	非阻塞启动 DMA 传输，完成前不可复用 tx_buffer
流式发送	xt_hal_uart_tx	非阻塞写入发送环形缓冲区，可能只写入部分数据

2.3 初始化顺序

必须按以下顺序调用：

1. xt_hal_uart_set_rx_buf — 设置接收缓冲区（在 setup 前）
2. xt_hal_uart_set_tx_buf — 设置发送缓冲区（如需流式/零拷贝发送）
3. xt_hal_uart_set_cb — 设置回调（可选）
4. xt_hal_uart_setup — 初始化 UART 硬件

2.4 回调事件

事件	说明
XT_HAL_UART_EVENT_RX	接收到数据，可调用 xt_hal_uart_rx 读取
XT_HAL_UART_EVENT_TX_DONE	发送完成（仅零拷贝模式触发）

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_uart（UART 驱动） 。

3.1 生命周期

函数签名	说明
xt_err_t xt_hal_uart_setup(uint8_t uart_id, uint32_t preset, uint32_t baudrate, uint8_t tx_pin, uint8_t rx_pin)	初始化 UART
xt_err_t xt_hal_uart_close(uint8_t uart_id)	关闭 UART，释放硬件资源

3.2 缓冲区配置

函数签名	说明
xt_err_t xt_hal_uart_set_rx_buf(uint8_t uart_id, void *buffer, size_t size)	设置接收缓冲区（必须在 setup 前调用）
xt_err_t xt_hal_uart_set_tx_buf(uint8_t uart_id, void *buffer, size_t size)	设置发送缓冲区（流式/零拷贝发送前必须调用）

3.3 回调

函数签名	说明
xt_err_t xt_hal_uart_set_cb(uint8_t uart_id, xt_hal_uart_cb_t cb)	设置事件回调函数

3.4 数据收发

函数签名	说明
int32_t xt_hal_uart_tx_block(uint8_t uart_id, const void *tx_buffer, size_t size)	阻塞发送
int32_t xt_hal_uart_tx_0copy(uint8_t uart_id, const void *tx_buffer, size_t size)	零拷贝非阻塞发送
int32_t xt_hal_uart_tx(uint8_t uart_id, const void *tx_buffer, size_t size)	流式非阻塞发送
int32_t xt_hal_uart_rx(uint8_t uart_id, void *rx_buffer, size_t size)	流式非阻塞接收

3.5 缓冲区状态

函数签名	说明
int32_t xt_hal_uart_get_rx_count(uint8_t uart_id)	获取接收缓冲区可读字节数
xt_err_t xt_hal_uart_flush_rx(uint8_t uart_id)	清空接收缓冲区
int32_t xt_hal_uart_get_tx_free(uint8_t uart_id)	获取发送缓冲区剩余空闲字节数

3.6 类型

类型签名	说明
xt_hal_uart_cb_t	回调函数类型： void (*)(uint8_t uart_id, uint32_t event_id)
enum xt_hal_uart_event_id	事件 ID 枚举（ XT_HAL_UART_EVENT_RX / XT_HAL_UART_EVENT_TX_DONE ）

---

四、常见模式

4.1 阻塞发送（最简单）

#include "xt_hal_uart.h"
 
void uart_send_hello(void) {
    xt_hal_uart_setup(0, XT_HAL_UART_8N1, 115200, 1, 2);
    xt_hal_uart_tx_block(0, "hello", 5);
    xt_hal_uart_close(0);
}

4.2 流式接收——回调驱动

#include "xt_hal_uart.h"
 
static uint8_t rx_buf[256];
 
static void uart_cb(uint8_t uart_id, uint32_t event_id) {
    if (event_id == XT_HAL_UART_EVENT_RX) {
        uint8_t data[64];
        int32_t len = xt_hal_uart_rx(uart_id, data, sizeof(data));
        if (len > 0) {
            /* 处理 data[0..len-1] */
        }
    }
}
 
void uart_rx_init(void) {
    xt_hal_uart_set_rx_buf(0, rx_buf, sizeof(rx_buf));
    xt_hal_uart_set_cb(0, uart_cb);
    xt_hal_uart_setup(0, XT_HAL_UART_8N1, 115200, 1, 2);
}

4.3 流式发送——非阻塞

#include "xt_hal_uart.h"
 
static uint8_t tx_buf[512];
 
void uart_stream_init(void) {
    xt_hal_uart_set_tx_buf(0, tx_buf, sizeof(tx_buf));
    xt_hal_uart_setup(0, XT_HAL_UART_8N1, 115200, 1, 2);
}
 
void uart_send_data(const uint8_t *data, size_t len) {
    int32_t wrote = xt_hal_uart_tx(0, data, len);
    if (wrote < (int32_t)len) {
        /* 缓冲区满，部分数据未写入 */
    }
}

---

五、已知行为与限制

行为	说明
rx_buf 必须在 setup 前设置	初始化后设置无效
tx_buf 用于流式/零拷贝	仅 tx_block 不需要 tx_buf
tx 可能只写入部分数据	返回实际写入字节数，需检查
tx_0copy 使用中不可复用 buffer	需等待 XT_HAL_UART_EVENT_TX_DONE 回调
tx_block 阻塞当前任务	实时性敏感场景使用流式发送替代