API GUIDE / UART / OVERVIEW

G32S10 UART API 概述

模块概述：本文档定义 G32S10 SDK 当前 UART 模块的 HAL 与 LL 正式接口，覆盖以下两层：

1. 文档范围

本文档定义 G32S10 SDK 当前 UART 模块的 HAL 与 LL 正式接口，覆盖以下两层：

HAL UART：面向驱动适配层、BSP 和上层模块的硬件抽象接口
LL UART：面向 UART 寄存器与位操作的低层 static inline 接口

本文档基于以下实现与头文件编写：

code/include/drivers/g32s10/uart/hal_uart.h
code/include/drivers/g32s10/uart/ll_uart.h
code/include/drivers/g32s10/uart/uart_regs.h
code/drivers/g32s10/uart/hal_uart.c

补充说明：

HAL 层当前负责 UART 控制器初始化、绑定已运行的端口、使能/禁用、波特率、线路格式、FIFO 单步读写、UART 中断源配置、IRQ 回调分发和 RX DMA 硬件请求辅助。
HAL 层公开的接口不包含阻塞收发、超时等待、SoC IRQ 注册和 DMA channel 生命周期管理。
LL 层公开接口均为 static inline，直接访问寄存器，不维护软件状态，不做完整业务语义判断。
UART HAL 当前采用 handle 模型，公开接口通过 hal_uart_handle_t * 访问已初始化端口。

2. 分层关系

APPLICATION Application / BSP / Driver 业务代码、板级支持与示例入口

↓

HAL HAL UART 模块级配置、状态管理与硬件访问

↓

LL LL UART 寄存器访问与字段级控制

↓

HARDWARE REGISTERS UART Registers 实例地址、寄存器布局与位域定义

分层职责如下：

HAL UART

封装 UART 控制器资源表、CPM clock gate、波特率表、线路格式、FIFO、UART 本地中断 mask、状态读取和 DMA request/address 查询
维护单个 hal_uart_handle_t 的初始化状态、寄存器实例、配置副本、FIFO shadow、中断 mask 和回调
不注册 SoC IRQ，不拥有 DMA channel，不做完整 TX/RX 传输调度

LL UART

提供寄存器位级访问入口
不维护软件状态，不处理上层传输流程
调用方必须保证实例指针、参数范围和并发访问安全

uart_regs.h

定义 UART 实例、寄存器结构体、位域 mask、中断 ID、FIFO 与线路状态位

3. 资源模型与公开类型

3.1 模块基地址与实例

当前 HAL/LL 支持 8 个 UART 控制器：

HAL 端口	实例宏	基地址宏	基地址	IRQ	CPM gate	RX DMA request
`HAL_UART_PORT_0`	`UART0`	`UART0_IOBASE`	`0x100C8000`	`IRQ_UART0`	`HAL_CPM_ID_GATE_UART0`	`HAL_DMA_REQUEST_UART0_RX`
`HAL_UART_PORT_1`	`UART1`	`UART1_IOBASE`	`0x100C9000`	`IRQ_UART1`	`HAL_CPM_ID_GATE_UART1`	`HAL_DMA_REQUEST_UART1_RX`
`HAL_UART_PORT_2`	`UART2`	`UART2_IOBASE`	`0x10007000`	`IRQ_UART2`	`HAL_CPM_ID_GATE_UART2`	`HAL_DMA_REQUEST_UART2_RX`
`HAL_UART_PORT_3`	`UART3`	`UART3_IOBASE`	`0x10008000`	`IRQ_UART3`	`HAL_CPM_ID_GATE_UART3`	`HAL_DMA_REQUEST_UART3_RX`
`HAL_UART_PORT_4`	`UART4`	`UART4_IOBASE`	`0x10009000`	`IRQ_UART4`	`HAL_CPM_ID_GATE_UART4`	`HAL_DMA_REQUEST_UART4_RX`
`HAL_UART_PORT_5`	`UART5`	`UART5_IOBASE`	`0x1000A000`	`IRQ_UART5`	`HAL_CPM_ID_GATE_UART5`	`HAL_DMA_REQUEST_UART5_RX`
`HAL_UART_PORT_6`	`UART6`	`UART6_IOBASE`	`0x1000B000`	`IRQ_UART6`	`HAL_CPM_ID_GATE_UART6`	`HAL_DMA_REQUEST_UART6_RX`
`HAL_UART_PORT_7`	`UART7`	`UART7_IOBASE`	`0x1000C000`	`IRQ_UART7`	`HAL_CPM_ID_GATE_UART7`	`HAL_DMA_REQUEST_UART7_RX`

uart_regs.h 中提供如下实例宏：

#define UART0  ((uart_regs_t *)(uintptr_t)UART0_IOBASE)
#define UART1  ((uart_regs_t *)(uintptr_t)UART1_IOBASE)
#define UART2  ((uart_regs_t *)(uintptr_t)UART2_IOBASE)
#define UART3  ((uart_regs_t *)(uintptr_t)UART3_IOBASE)
#define UART4  ((uart_regs_t *)(uintptr_t)UART4_IOBASE)
#define UART5  ((uart_regs_t *)(uintptr_t)UART5_IOBASE)
#define UART6  ((uart_regs_t *)(uintptr_t)UART6_IOBASE)
#define UART7  ((uart_regs_t *)(uintptr_t)UART7_IOBASE)

HAL 层通过 HAL_UART_IS_INSTANCE(INSTANCE) 检查实例合法性，该宏映射到 ll_uart_is_instance()。

3.2 HAL 公开宏

宏	说明	取值/约束
`HAL_UART_IS_INSTANCE(INSTANCE)`	判断 `uart_regs_t *` 是否为受支持实例	映射到 `ll_uart_is_instance()`
`HAL_UART_FIFO_DEPTH`	硬件 TX/RX FIFO 深度，单位字节	64

3.3 HAL 返回状态约定

HAL 层可失败接口统一返回 SDK 公共错误码类型：

error_code_t

常用返回值如下：

返回值	说明
`IM_OK`	操作成功
`IM_ERR_INVALID_PARAM`	参数为空、端口号非法、handle 非法、枚举非法或波特率硬件字段非法
`IM_ERR_UNSUPPORTED`	请求波特率不在当前 EXTAL 白名单表中，或 FIFO/DMA 辅助接口在 FIFO 关闭时不可用
`IM_ERR_NOT_READY`	RX FIFO 当前无可读字节
`IM_ERR_BUSY`	TX FIFO 当前不可写
其他错误码	可能来自 CPM 或其他底层硬件配置接口

HAL 当前不返回传输超时错误；超时语义由调用方或上层模块实现。

4. 当前实现约束与行为说明

4.1 SoC IRQ 由调用方注册

HAL 不调用 im_irq_request()、im_irq_enable() 或 im_irq_release()。调用方需要：

通过 hal_uart_irq_id_get() 获取 IRQ ID。
注册 SoC IRQ 入口。
在 IRQ 入口中调用 hal_uart_irq_handler(handle)。

4.2 FIFO 专用接口要求

以下接口要求 handle->config.fifo_enable == true，否则返回 IM_ERR_UNSUPPORTED：

hal_uart_fifo_flush()
hal_uart_rx_dma_config()

hal_uart_fifo_level_get() 在 FIFO 关闭时仍可返回 0/1 的等效水位。

5. 推荐关注的错误码

场景	推荐关注错误码	说明
波特率不在当前 EXTAL 白名单中	`IM_ERR_UNSUPPORTED`	使用支持速率或改用 `hal_uart_set_baud_manually()`
FIFO 关闭时调用 FIFO reset 或 RX DMA request 配置	`IM_ERR_UNSUPPORTED`	初始化时设置 `fifo_enable = true`
TX FIFO 满	`IM_ERR_BUSY`	稍后重试或等待 `HAL_UART_IRQ_TX_READY`
RX FIFO 空	`IM_ERR_NOT_READY`	稍后重试或等待 `HAL_UART_IRQ_RX_READY`
handle 非法或未初始化	`IM_ERR_INVALID_PARAM`	检查 `hal_uart_init()` 是否成功，以及 handle 是否被 `hal_uart_deinit()` 清零