G32S10 UART HAL 接口

1. 资源模型与公开类型

1.1 Kconfig 选项

1.2 UART 硬件能力摘要

1.3 UART 端口标识

typedef enum {
    HAL_UART_PORT_0 = 0,
    HAL_UART_PORT_1,
    HAL_UART_PORT_2,
    HAL_UART_PORT_3,
    HAL_UART_PORT_4,
    HAL_UART_PORT_5,
    HAL_UART_PORT_6,
    HAL_UART_PORT_7,
    HAL_UART_PORT_COUNT,
} hal_uart_port_t;

说明：

• HAL_UART_PORT_COUNT 是端口数量枚举值，不是可初始化端口。

• 当前 HAL handle 只通过 handle->is_initialized 和 handle->instance 判断有效性，不再维护全局端口 owner 绑定表。

• 调用方应避免多个 handle 并发操作同一个 UART 端口。

1.4 数据格式与流控

校验位：

typedef enum {
    HAL_UART_PARITY_NONE = 0,
    HAL_UART_PARITY_ODD,
    HAL_UART_PARITY_EVEN,
    HAL_UART_PARITY_MARK,
    HAL_UART_PARITY_SPACE,
} hal_uart_parity_t;

流控：

typedef enum {
    HAL_UART_FLOW_CONTROL_NONE = 0,
    HAL_UART_FLOW_CONTROL_CTS_RTS,
} hal_uart_flow_control_t;

说明：

• 旧的 hal_uart_transfer_mode_t 已从 HAL 删除。

• HAL 不再通过配置字段选择 POLL/IRQ/DMA 传输路径。

• TX/RX 传输策略由调用方组合 FIFO、IRQ、DMA 辅助接口实现。

字段约束如下：

1.5 FIFO 触发阈值

typedef enum {
    HAL_UART_RX_FIFO_TRIGGER_1_BYTE = UART_UFCR_RDTR_1_BYTE,
    HAL_UART_RX_FIFO_TRIGGER_8_BYTES = UART_UFCR_RDTR_8_BYTES,
    HAL_UART_RX_FIFO_TRIGGER_16_BYTES = UART_UFCR_RDTR_16_BYTES,
    HAL_UART_RX_FIFO_TRIGGER_32_BYTES = UART_UFCR_RDTR_32_BYTES,
} hal_uart_rx_fifo_trigger_t;

说明：

• rx_fifo_trigger 只在 FIFO 模式启用时有效。

• hal_uart_config_struct_init() 的默认阈值为 HAL_UART_RX_FIFO_TRIGGER_32_BYTES。

1.6 状态与中断源

UART 逻辑状态：

typedef enum {
    HAL_UART_STATUS_TX_IDLE = 1U << 0,
    HAL_UART_STATUS_RX_READY = 1U << 1,
    HAL_UART_STATUS_OVERRUN = 1U << 2,
    HAL_UART_STATUS_PARITY_ERROR = 1U << 3,
    HAL_UART_STATUS_FRAME_ERROR = 1U << 4,
    HAL_UART_STATUS_BREAK = 1U << 5,
} hal_uart_status_t;

UART 中断源 mask：

typedef enum {
    HAL_UART_IRQ_TX_READY = 1U << 0,
    HAL_UART_IRQ_RX_READY = 1U << 1,
    HAL_UART_IRQ_RX_TIMEOUT = 1U << 2,
    HAL_UART_IRQ_LINE_STATUS = 1U << 3,
    HAL_UART_IRQ_MODEM_STATUS = 1U << 4,
} hal_uart_irq_source_t;

说明：

• hal_uart_irq_config() 的参数是上述 HAL_UART_IRQ_* 组成的 mask。

• hal_uart_irq_handler() 只处理当前最高优先级 pending 中断源。

• HAL_UART_IRQ_LINE_STATUS 回调的 status 参数为 hal_uart_status_get() 生成的逻辑状态 mask。

• HAL_UART_IRQ_MODEM_STATUS 回调的 status 参数为 UMSR 快照；读取 UMSR 会清除 Modem 变化标志。

• 其他中断源回调的 status 当前为 0。

1.7 公开结构体

1.7.1 hal_uart_baud_config_t

1.7.2 hal_uart_config_t

hal_uart_config_struct_init() 默认值：

1.7.3 hal_uart_fifo_level_t

1.7.4 hal_uart_handle_t

1.7.5 hal_uart_callback_t

typedef void (*hal_uart_callback_t)(hal_uart_handle_t *handle,
                                    hal_uart_irq_source_t source,
                                    uint32_t status,
                                    void *user_data);

说明：

• 回调在 UART IRQ 上下文运行，不能阻塞。

• source 是单个 HAL UART 中断源，不是多个源的组合。

• user_data 来自 hal_uart_callback_register()。

2. HAL 接口规范

2.1 初始化与生命周期

2.1.1 hal_uart_config_struct_init

void hal_uart_config_struct_init(hal_uart_config_t *config);

功能说明：使用安全默认值填充 UART HAL 配置。

返回值：无。config == NULL 时直接返回。

2.1.2 hal_uart_init

error_code_t hal_uart_init(hal_uart_handle_t *handle,
                           const hal_uart_config_t *config);

功能说明：初始化一个 UART 控制器，打开所需时钟，配置线路格式、modem 控制、波特率、FIFO shadow，并保持 UART 未使能状态。若 config->preinitialized 为真，则只调用 hal_uart_bind() 绑定句柄、完全不碰端口硬件，句柄直接按「上游已经把端口跑起来」的状态返回。

补充说明：

• 成功后 handle->is_initialized == true。

• 成功后 UART 仍处于 disabled 状态，需要调用 hal_uart_enable() 后才开始工作。

• 初始化期间会清空 UART 中断 mask，并通过 UFCR.RFRT/TFRT 复位 FIFO。

• config->preinitialized == true 时上述三条都不适用：不打开时钟、不配置线路/FIFO、不复位 FIFO，handle->is_initialized 与 handle->is_enabled 都直接为 true（端口由上游负责，见hal_uart_bind()）；此时再调 hal_uart_enable() 是 no-op。

2.1.3 hal_uart_bind

error_code_t hal_uart_bind(hal_uart_handle_t *handle,
                           const hal_uart_config_t *config);

功能说明：把一个句柄绑定到已经被上游配好并正在运行的端口。只做句柄绑定（记录 port_id、 寄存器块、配置和 FIFO shadow），不打开时钟、不配置线路/波特率、不复位 FIFO。

补充说明：

• 成功后 handle->is_initialized 与 handle->is_enabled 都等于 config->preinitialized； 典型用法（preinit 路径）传 true，句柄直接可用。

• FIFO 字段只记录进 handle->fifo_control_shadow，不写寄存器 —— 后续hal_uart_disable() / hal_uart_enable() 一对调用可以把它重放进 UFCR。

• 它是 hal_uart_init() 在 preinitialized 下的等价体：不引用初始化链，所以波特率表和 CPM 时钟链不会被链进镜像（只和已运行的端口打交道的固件可以省掉这部分）。

• 端口必须真的已经在跑且已使能，否则写出去的数据不会出现在线上。

2.1.4 hal_uart_deinit

error_code_t hal_uart_deinit(hal_uart_handle_t *handle);

功能说明：禁用 UART，刷新 FIFO，关闭时钟，并清零 handle。

2.1.5 hal_uart_enable

error_code_t hal_uart_enable(hal_uart_handle_t *handle);

功能说明：写入 UFCR.UME，使能已初始化 UART 控制器。已经是使能状态（handle->is_enabled == true）时直接返回，不重写寄存器。

返回值：IM_OK 或 IM_ERR_INVALID_PARAM。

2.1.6 hal_uart_disable

error_code_t hal_uart_disable(hal_uart_handle_t *handle);

功能说明：禁用 UART 本地中断，清除 UFCR.UME，保留 FIFO 稳态配置。已经是禁用状态时直接返回。

返回值：IM_OK 或 IM_ERR_INVALID_PARAM。

2.2 波特率与调试辅助

2.2.1 hal_uart_set_baud

error_code_t hal_uart_set_baud(hal_uart_handle_t *handle,
                               uint32_t baud_rate_bps);

功能说明：根据内置白名单表配置 UART 波特率寄存器。

2.2.2 hal_uart_set_baud_manually

error_code_t hal_uart_set_baud_manually(hal_uart_handle_t *handle,
                                        const hal_uart_baud_config_t *config);

功能说明：根据调用者提供的硬件字段配置 UART 波特率寄存器。

2.2.3 hal_uart_dump_regs

void hal_uart_dump_regs(const hal_uart_handle_t *handle);

功能说明：将 UART 控制器关键寄存器状态输出到日志。

补充说明：

• 只有同时启用 CONFIG_SDK_ENABLE_DEBUG_HELPERS 和 CONFIG_UART_ENABLE_DEBUG_HELPERS 时才实际输出日志。

• 当前输出 ULCR、UMCR、ULSR、UIIR。

• 为避免读取 URBR 消耗 RX 数据，且 UTHR 为只写寄存器，本接口不会转储 URBR/UTHR。

2.3 FIFO 与状态接口

2.3.1 hal_uart_fifo_write

error_code_t hal_uart_fifo_write(hal_uart_handle_t *handle, uint8_t data);

功能说明：向 UART TX FIFO/holding register 写入 1 字节。

2.3.2 hal_uart_fifo_read

error_code_t hal_uart_fifo_read(hal_uart_handle_t *handle,
                                uint8_t *data_out);

功能说明：从 UART RX FIFO/receive buffer 读取 1 字节。

2.3.3 hal_uart_fifo_level_get

error_code_t hal_uart_fifo_level_get(const hal_uart_handle_t *handle,
                                     hal_uart_fifo_level_t *level_out);

功能说明：读取当前 UART FIFO 占用情况。

补充说明：

• FIFO 模式启用时，tx_count 和 rx_count 来自 UTCR/URCR。

• 非 FIFO 模式下，HAL 根据 ULSR.TDRQ/DRY 返回 0 或 1 的等效水位。

2.3.4 hal_uart_fifo_flush

error_code_t hal_uart_fifo_flush(hal_uart_handle_t *handle);

功能说明：通过 UFCR.RFRT/TFRT 同时清空 RX 和 TX FIFO。

2.3.5 hal_uart_status_get

error_code_t hal_uart_status_get(const hal_uart_handle_t *handle,
                                 uint32_t *status_out);

功能说明：读取 ULSR 并转换为 HAL_UART_STATUS_* 逻辑状态 mask。

2.4 中断与回调接口

2.4.1 hal_uart_irq_config

error_code_t hal_uart_irq_config(hal_uart_handle_t *handle,
                                 uint32_t irq_enable_mask);

功能说明：配置 UART 控制器本地中断使能位。

补充说明：

• irq_enable_mask 只能包含 HAL_UART_IRQ_TX_READY、HAL_UART_IRQ_RX_READY、HAL_UART_IRQ_RX_TIMEOUT、HAL_UART_IRQ_LINE_STATUS、HAL_UART_IRQ_MODEM_STATUS。

• 本接口只配置 UART UIER，不注册或使能 SoC IRQ。

2.4.2 hal_uart_callback_register

error_code_t hal_uart_callback_register(hal_uart_handle_t *handle,
                                        hal_uart_callback_t callback,
                                        void *user_data);

功能说明：注册或注销 UART 中断回调。callback == NULL 时表示注销。

返回值：IM_OK 或 IM_ERR_INVALID_PARAM。

2.4.3 hal_uart_irq_id_get

error_code_t hal_uart_irq_id_get(const hal_uart_handle_t *handle,
                                 uint32_t *irq_id_out);

功能说明：查询当前 UART 端口对应的 SoC IRQ ID。

2.4.4 hal_uart_irq_handler

void hal_uart_irq_handler(hal_uart_handle_t *handle);

功能说明：处理当前 UART pending 中断源，并按需调用已注册回调。

补充说明：

• 调用方应在 SoC IRQ 分发入口中调用本接口。

• 当前实现一次只处理当前最高优先级 pending 中断源。

• 若中断源未包含在 handle->irq_enable_mask 中，直接返回。

• line status 中断会传入 hal_uart_status_get() 的逻辑状态 mask。

• modem status 中断会读取并传入 UMSR 快照。

2.5 TX/RX DMA 硬件辅助接口

2.5.1 hal_uart_tx_dma_address_get

error_code_t hal_uart_tx_dma_address_get(const hal_uart_handle_t *handle,
                                         uintptr_t *address_out);

功能说明：返回 UART TX data register（UTHR）地址，用于 TX DMA 配置。

2.5.2 hal_uart_tx_dma_request_get

error_code_t hal_uart_tx_dma_request_get(const hal_uart_handle_t *handle,
                                         hal_dma_request_t *request_out);

功能说明：返回当前 UART 端口对应的 TX DMA request source。

2.5.3 hal_uart_rx_dma_address_get

error_code_t hal_uart_rx_dma_address_get(const hal_uart_handle_t *handle,
                                         uintptr_t *address_out);

功能说明：返回 UART RX data register（URBR）地址，用于 RX DMA 配置。

2.5.4 hal_uart_rx_dma_request_get

error_code_t hal_uart_rx_dma_request_get(const hal_uart_handle_t *handle,
                                         hal_dma_request_t *request_out);

功能说明：返回当前 UART 端口对应的 RX DMA request source。

2.5.5 hal_uart_dma_config

error_code_t hal_uart_dma_config(hal_uart_handle_t *handle, bool enable);

功能说明：设置或清除 UFCR.DME。DME 是 UART TX/RX 共用的 DMA 模式使能位，使能后 TX request 和 RX request 均可输出；TX/RX request source 本身相互独立。

2.5.6 hal_uart_rx_dma_config

error_code_t hal_uart_rx_dma_config(hal_uart_handle_t *handle, bool enable);

功能说明：兼容旧接口，等价于 hal_uart_dma_config()。

补充说明：上述配置接口不申请 DMA channel、不创建 descriptor、不维护 DMA buffer 读写指针。

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

3.1 HAL 初始化不自动 enable

hal_uart_init() 成功后只完成寄存器配置和 FIFO reset，UART 仍处于 disabled 状态。调用方需要显式调用 hal_uart_enable()。

例外：config->preinitialized == true 时 hal_uart_init() 只调用 hal_uart_bind() 绑定句柄、 完全不碰端口，handle->is_enabled 直接为 true（上游已经把口跑起来了），此时不需要（调了也是 no-op）再 hal_uart_enable()。这条路径下 CONFIG_DRIVER_CONSOLE_UART_BAUD_RATE_BPS 之类的 速率配置不生效——端口速率由上游决定。

3.2 HAL 不再提供传输 API

以下旧接口已从 HAL 删除：

• hal_uart_open()

• hal_uart_close()

• hal_uart_start()

• hal_uart_stop()

• hal_uart_send()

• hal_uart_receive()

• hal_uart_send_async()

• hal_uart_flush()

• hal_uart_get_tx_free_space()

• hal_uart_read_byte()

• hal_uart_get_rx_fifo_count()

• hal_uart_get_tx_fifo_count()

• hal_uart_clear_rx_fifo()

• hal_uart_clear_tx_fifo()

• hal_uart_get_readable_count()

• hal_uart_register_rx_callback()

• hal_uart_register_tx_callback()

• hal_uart_register_modem_status_callback()

• hal_uart_register_event_callback()

• hal_uart_enable_rx_irq()

• hal_uart_disable_rx_irq()

• hal_uart_get_pending_irq()

• hal_uart_get_modem_status()

当前 HAL 保留单字节 FIFO 访问、FIFO 水位读取、FIFO flush、状态读取、中断源配置和统一回调分发。

3.3 RX DMA channel 生命周期由调用方管理

HAL 只提供：

• hal_uart_rx_dma_address_get()

• hal_uart_rx_dma_request_get()

• hal_uart_rx_dma_config()

DMA channel open/close、descriptor、buffer 对齐、cache 管理、循环读指针和超时等待均由调用方负责。

4. 典型 HAL 用法

4.1 初始化、使能和单字节轮询发送

hal_uart_handle_t handle;
hal_uart_config_t config;
error_code_t ret;

hal_uart_config_struct_init(&config);
config.port_id = HAL_UART_PORT_2;
config.baud_rate_bps = 115200U;

ret = hal_uart_init(&handle, &config);
if (ret != IM_OK) {
    return ret;
}

ret = hal_uart_enable(&handle);
if (ret != IM_OK) {
    (void)hal_uart_deinit(&handle);
    return ret;
}

while (hal_uart_fifo_write(&handle, (uint8_t)'A') == IM_ERR_BUSY) {
}

(void)hal_uart_deinit(&handle);
return IM_OK;

端口已经由上游配好并正在运行（例如 SPL 或另一个核已经把 UART 跑起来）时，只绑句柄即可， 不要再去配置/使能端口：

hal_uart_config_struct_init(&config);
config.port_id = HAL_UART_PORT_0;
config.preinitialized = true;

ret = hal_uart_init(&handle, &config);   /* 等价于 hal_uart_bind(&handle, &config) */
if (ret != IM_OK) {
    return ret;
}

/* handle->is_enabled 已经是 true，这里不需要（调了也是 no-op）再 hal_uart_enable() */

4.2 UART 本地中断回调

static void uart_cb(hal_uart_handle_t *handle,
                    hal_uart_irq_source_t source,
                    uint32_t status,
                    void *user_data)
{
    (void)handle;
    (void)status;
    (void)user_data;

    if (source == HAL_UART_IRQ_RX_READY) {
        /* Read available bytes with hal_uart_fifo_read(). */
    }
}

error_code_t uart_irq_prepare(hal_uart_handle_t *handle)
{
    error_code_t ret;

    ret = hal_uart_callback_register(handle, uart_cb, NULL);
    if (ret != IM_OK) {
        return ret;
    }

    return hal_uart_irq_config(handle,
                               (uint32_t)HAL_UART_IRQ_RX_READY |
                               (uint32_t)HAL_UART_IRQ_LINE_STATUS);
}

SoC IRQ 入口中应调用：

hal_uart_irq_handler(handle);

4.3 RX DMA 硬件参数查询

uintptr_t rx_addr;
hal_dma_request_t request;
error_code_t ret;

ret = hal_uart_rx_dma_address_get(handle, &rx_addr);
if (ret != IM_OK) {
    return ret;
}

ret = hal_uart_rx_dma_request_get(handle, &request);
if (ret != IM_OK) {
    return ret;
}

return hal_uart_rx_dma_config(handle, true);