API GUIDE / UART / LL

G32S10 UART LL 接口

LL 层接口：补充说明：

1. LL 接口规范

1.1 实例与参数检查辅助

接口	说明
`ll_uart_is_instance(const uart_regs_t *uartx)`	判断指针是否为 `UART0` ~ `UART7`
`ll_uart_is_baud_divisor_valid(uint16_t divisor)`	判断波特率 divisor 是否有效；有效范围为 1 到 `0xFFFF`
`ll_uart_is_rx_fifo_trigger_valid(uint32_t trigger)`	判断 RX FIFO 触发阈值编码是否只包含 `UFCR.RDTR` 字段

1.2 FIFO 控制与寄存器映射

接口	说明
`ll_uart_write_fifo_control(uart_regs_t *uartx, uint32_t control)`	写 `UFCR` FIFO 控制寄存器
`ll_uart_enable_baud_divisor_access(uart_regs_t *uartx)`	设置 `ULCR.DLAB`，允许访问分频锁存寄存器
`ll_uart_disable_baud_divisor_access(uart_regs_t *uartx)`	清除 `ULCR.DLAB`，返回普通寄存器映射
`ll_uart_enter_normal_register_map(uart_regs_t *uartx)`	临时清除 `DLAB`，返回进入前的 DLAB 状态
`ll_uart_restore_register_map(uart_regs_t *uartx, uint32_t dlab)`	按保存的 DLAB 状态恢复寄存器映射

补充说明：

URBR/UTHR/UDLLR 与 UIER/UDLHR 共享偏移，LL 中断 mask 相关接口会自动临时切换到普通寄存器映射。
UFCR 是写寄存器，HAL 使用 shadow 保存最近一次非 reset 位配置。

1.3 波特率与线路格式

接口	说明
`ll_uart_set_baud_divisor_low_byte(uart_regs_t *uartx, uint8_t value)`	写分频锁存低字节；调用前需已使能 DLAB 且清除 `UFCR.UME`
`ll_uart_set_baud_divisor_high_byte(uart_regs_t *uartx, uint8_t value)`	写分频锁存高字节；调用前需已使能 DLAB 且清除 `UFCR.UME`
`ll_uart_set_baud_divisor(uart_regs_t *uartx, uint16_t divisor)`	写完整分频锁存值；调用前须清除 `UFCR.UME`，内部设置 DLAB 并在返回前清除，返回时 `DLAB` 必为 0
`ll_uart_set_m_value(uart_regs_t *uartx, uint8_t m_value)`	写 `UMR.M` 字段；调用前须清除 `UFCR.UME`
`ll_uart_get_m_value(const uart_regs_t *uartx)`	读 `UMR.M` 字段
`ll_uart_set_add_cycle_mask(uart_regs_t *uartx, uint16_t add_cycle_mask)`	写 `UACR.AC` 字段；调用前须清除 `UFCR.UME`
`ll_uart_get_add_cycle_mask(const uart_regs_t *uartx)`	读 `UACR.AC` 字段
`ll_uart_set_line_format(uart_regs_t *uartx, uint32_t format_flags)`	只写数据位、停止位、校验位配置并保留当前 DLAB 状态；会清除 `ULCR.SBK`，即结束已有 break
`ll_uart_get_line_control(const uart_regs_t *uartx)`	读 `ULCR`
`ll_uart_break_enable(uart_regs_t *uartx)`	设置 `ULCR.SBK`，强制 TXD 发送 break
`ll_uart_break_disable(uart_regs_t *uartx)`	清除 `ULCR.SBK`，释放 break

1.4 TX/RX 数据与 DMA 地址

接口	说明
`ll_uart_write_tx_data(uart_regs_t *uartx, uint8_t data)`	向 `UTHR` 写 1 字节
`ll_uart_read_rx_data(const uart_regs_t *uartx)`	从 `URBR` 读 1 字节
`ll_uart_get_tx_register_address(const uart_regs_t *uartx)`	返回 `UTHR` 地址，用于 DMA 配置
`ll_uart_get_rx_register_address(const uart_regs_t *uartx)`	返回 `URBR` 地址，用于 DMA 配置

补充说明：

读 URBR 会消耗 RX 数据。
写 UTHR 前应检查 ll_uart_is_tx_ready() 或确认 FIFO 有空间。

1.5 线路状态与 FIFO 水位

接口	说明
`ll_uart_get_line_status(const uart_regs_t *uartx)`	读 `ULSR`
`ll_uart_is_tx_ready(const uart_regs_t *uartx)`	判断 `ULSR.TDRQ` 是否置位
`ll_uart_is_tx_idle(const uart_regs_t *uartx)`	判断 `ULSR.TEMP` 是否置位
`ll_uart_is_rx_ready(const uart_regs_t *uartx)`	判断 `ULSR.DRY` 是否置位
`ll_uart_has_rx_error(const uart_regs_t *uartx)`	判断 `ULSR` 是否包含 RX 错误位
`ll_uart_has_rx_fifo_error(const uart_regs_t *uartx)`	判断 `ULSR.FIFOE` 是否置位
`ll_uart_get_rx_fifo_count(const uart_regs_t *uartx)`	读取 RX FIFO 当前计数
`ll_uart_get_tx_fifo_count(const uart_regs_t *uartx)`	读取 TX FIFO 当前计数

RX 错误 mask 包含：

位	说明
`UART_ULSR_OVER_MASK`	RX overrun
`UART_ULSR_PARER_MASK`	Parity error
`UART_ULSR_FMER_MASK`	Frame error
`UART_ULSR_BI_MASK`	Break interrupt
`UART_ULSR_FIFOE_MASK`	RX FIFO 中存在错误字符

1.6 中断寄存器访问

接口	说明
`ll_uart_get_interrupt_mask(uart_regs_t *uartx)`	读取 `UIER` 中断使能位
`ll_uart_set_interrupt_mask(uart_regs_t *uartx, uint32_t mask)`	替换 `UIER` 中断使能位
`ll_uart_enable_interrupts(uart_regs_t *uartx, uint32_t mask)`	使能选定中断源
`ll_uart_disable_interrupts(uart_regs_t *uartx, uint32_t mask)`	禁用选定中断源
`ll_uart_mask_all_interrupts(uart_regs_t *uartx)`	禁用所有 UART 中断源
`ll_uart_get_interrupt_status(const uart_regs_t *uartx)`	读取 `UIIR`
`ll_uart_has_pending_interrupt(const uart_regs_t *uartx)`	判断 `UIIR.INPEND` 是否表示存在 pending 中断

UART_UIER_ALL_MASK 包含以下中断使能位：

位	说明
`UART_UIER_RDRIE_MASK`	RX data ready interrupt enable
`UART_UIER_TDRIE_MASK`	TX data request interrupt enable
`UART_UIER_RLSIE_MASK`	RX line status interrupt enable
`UART_UIER_MSIE_MASK`	Modem status interrupt enable
`UART_UIER_RTOIE_MASK`	RX timeout interrupt enable

1.7 Modem 控制与状态

接口	说明
`ll_uart_get_modem_control(const uart_regs_t *uartx)`	读 `UMCR`
`ll_uart_set_modem_control(uart_regs_t *uartx, uint32_t control)`	写 `UMCR` 的 RTS、loop、flow-control 和 modem-control enable 位
`ll_uart_modem_control_enable(uart_regs_t *uartx)`	设置 `UMCR.MDCE`
`ll_uart_modem_control_disable(uart_regs_t *uartx)`	清除 `UMCR.MDCE`
`ll_uart_hardware_flow_control_enable(uart_regs_t *uartx)`	设置 `UMCR.FCM`
`ll_uart_hardware_flow_control_disable(uart_regs_t *uartx)`	清除 `UMCR.FCM`
`ll_uart_loopback_enable(uart_regs_t *uartx)`	设置 `UMCR.LOOP`
`ll_uart_loopback_disable(uart_regs_t *uartx)`	清除 `UMCR.LOOP`
`ll_uart_rts_assert(uart_regs_t *uartx)`	驱动 RTS_ 为 active-low
`ll_uart_rts_deassert(uart_regs_t *uartx)`	驱动 RTS_ 为 inactive-high
`ll_uart_get_modem_status(const uart_regs_t *uartx)`	读 `UMSR`
`ll_uart_modem_status_is_cts_asserted(uint32_t modem_status)`	判断 `UMSR` 快照中 CTS_ 是否 active-low
`ll_uart_modem_status_has_cts_changed(uint32_t modem_status)`	判断 `UMSR` 快照中 CTS_ 是否发生变化

补充说明：读取 UMSR 会清除 Modem delta flags 和 Modem status interrupt。

1.8 Scratchpad 与 IrDA

接口	说明
`ll_uart_set_scratch_data(uart_regs_t *uartx, uint8_t data)`	写 `USPR` scratchpad 数据
`ll_uart_get_scratch_data(const uart_regs_t *uartx)`	读 `USPR` scratchpad 数据
`ll_uart_set_irda_control(uart_regs_t *uartx, uint32_t control)`	写 `ISR` IrDA 控制位
`ll_uart_get_irda_control(const uart_regs_t *uartx)`	读 `ISR` IrDA 控制位
`ll_uart_irda_tx_enable(uart_regs_t *uartx)`	使能 SIR transmit mode
`ll_uart_irda_tx_disable(uart_regs_t *uartx)`	禁用 SIR transmit mode
`ll_uart_irda_rx_enable(uart_regs_t *uartx)`	使能 SIR receive mode
`ll_uart_irda_rx_disable(uart_regs_t *uartx)`	禁用 SIR receive mode
`ll_uart_irda_fixed_pulse_enable(uart_regs_t *uartx)`	选择固定 1.6 us SIR TX pulse width
`ll_uart_irda_fixed_pulse_disable(uart_regs_t *uartx)`	选择 3/16 bit-time SIR TX pulse width

2. 寄存器映射与位域约定

2.1 共享偏移与 DLAB

UART 前三个偏移存在访问方向和 ULCR.DLAB 复用：

偏移	`DLAB=0`	`DLAB=1`	说明
`0x000`	`URBR`/`UTHR`	`UDLLR`	普通模式下读 RX、写 TX；DLAB 模式下访问 divisor low
`0x004`	`UIER`	`UDLHR`	普通模式下访问中断使能；DLAB 模式下访问 divisor high
`0x008`	`UIIR`/`UFCR`	`UIIR`/`UFCR`	读中断识别，写 FIFO 控制

2.2 `ULCR` 线路控制位

位域	说明
`WLS`	数据位选择：5/6/7/8 bit
`SBLS`	停止位选择
`PARE`	校验使能
`PARM`	校验模式
`STPAR`	固定校验控制
`SBK`	break 控制
`DLAB`	divisor latch access bit

HAL 校验映射：

HAL 校验	`PARE`	`PARM`	`STPAR`	说明
`HAL_UART_PARITY_NONE`	0	0	0	无校验
`HAL_UART_PARITY_ODD`	1	0	0	奇校验
`HAL_UART_PARITY_EVEN`	1	1	0	偶校验
`HAL_UART_PARITY_MARK`	1	0	1	校验位固定 1
`HAL_UART_PARITY_SPACE`	1	1	1	校验位固定 0

2.3 `UFCR` FIFO 控制位

位	说明
`FME`	FIFO mode enable
`RFRT`	RX FIFO reset，写 1 触发
`TFRT`	TX FIFO reset，写 1 触发
`DME`	DMA mode enable
`UME`	UART module enable
`RDTR`	RX FIFO trigger level

说明：

HAL 使用 fifo_control_shadow 保存 UFCR 的稳态配置。
RFRT/TFRT 为触发位，不保存在 shadow 中。 UART 本地中断。两者都是幂等的：句柄已经是目标状态时直接返回，不重写寄存器。disable / enable 可以把上游留下的 FIFO 配置原样重放进 UFCR。

2.4 `UIER/UIIR` 中断位

UART_UIER_ALL_MASK 包含以下中断使能位：

位	对应 HAL 中断源
`UART_UIER_TDRIE_MASK`	`HAL_UART_IRQ_TX_READY`
`UART_UIER_RDRIE_MASK`	`HAL_UART_IRQ_RX_READY`
`UART_UIER_RTOIE_MASK`	`HAL_UART_IRQ_RX_TIMEOUT`
`UART_UIER_RLSIE_MASK`	`HAL_UART_IRQ_LINE_STATUS`
`UART_UIER_MSIE_MASK`	`HAL_UART_IRQ_MODEM_STATUS`

UIIR.INPEND 语义：

值	说明
0	存在 pending 中断
1	无 pending 中断

2.5 `UMCR/UMSR` Modem 位

寄存器位	说明
`UMCR.RTS`	RTS_ 输出控制
`UMCR.LOOP`	内部 loopback
`UMCR.FCM`	硬件流控模式
`UMCR.MDCE`	Modem control enable
`UMSR.CCTS`	CTS_ 变化标志
`UMSR.CTS`	CTS_ 当前状态

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

3.1 LL 接口不做参数保护

LL 接口除少数 is_* helper 外不做参数校验。调用者必须保证：

uartx 是有效 UART 实例
写入值已按寄存器位域约束裁剪
与同一 UART 实例相关的并发访问已被上层串行化
读 URBR、读 UMSR 这类有副作用访问符合业务预期