G32S10 SPI Slave API 概述

1. 文档范围

本文档描述 G32S10 SPI_SLV 模块当前 SDK 中对外提供的 HAL 层与 LL 层正式接口， 包括公开类型、接口行为、参数约束、返回值约定、寄存器语义、典型使用流程以及当前 实现限制。

本文档基于以下文件编写：

• code/include/drivers/g32s10/spi_slv/spi_slv_regs.h

• code/include/drivers/g32s10/spi_slv/ll_spi_slv.h

• code/include/drivers/g32s10/spi_slv/hal_spi_slv.h

• code/drivers/g32s10/spi_slv/hal_spi_slv.c

2. 分层关系

HAL 面向应用、BSP 和 middleware 使用；LL 面向寄存器级控制、底层适配和调试使用。 通常应优先使用 HAL。直接使用 LL 时，调用方必须自行保证实例、参数、时序和并发访问 合法。

3. 资源模型与公开类型

3.1 模块实例与基地址

当前 HAL/LL 支持两个 SPI_SLV 实例。

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

#define SPI_SLV0  ((spi_slv_regs_t *)(uintptr_t)SPI_SLV0_IOBASE)
#define SPI_SLV1  ((spi_slv_regs_t *)(uintptr_t)SPI_SLV1_IOBASE)

3.2 硬件能力摘要

3.3 状态标志

hal_spi_slv_status_get() 返回由 hal_spi_slv_status_flag_t 组成的逻辑 bitmask。

HAL 状态 bit 与 SSLVCTRL[24:13] 的原始位位置不同。需要寄存器原始位时使用ll_spi_slv_get_raw_status()；应用侧应使用 HAL 状态定义。

3.4 HAL 返回值约定

hal_spi_slv_init() 和 hal_spi_slv_deinit() 还会透传 CPM 接口返回的错误码。

4. 典型用法

4.1 轮询式全双工从机准备

以下代码只展示 HAL 调用顺序。BSP 引脚初始化和主机启动应由系统在相应位置完成。

hal_spi_slv_handle_t hspi_slv;
hal_spi_slv_fifo_level_t level;
uint32_t rx_word;
error_code_t ret;

ret = hal_spi_slv_handle_init(&hspi_slv, SPI_SLV1);
if (ret != IM_OK) {
    return ret;
}

hspi_slv.init.cpol = HAL_SPI_SLV_CLOCK_POLARITY_LOW;
hspi_slv.init.cpha = HAL_SPI_SLV_CLOCK_PHASE_FIRST_EDGE;
hspi_slv.init.rx_channel = HAL_SPI_SLV_CHANNEL_SINGLE;
hspi_slv.init.tx_channel = HAL_SPI_SLV_CHANNEL_SINGLE;
hspi_slv.init.rx_bitwidth = 8U;
hspi_slv.init.tx_bitwidth = 8U;

ret = hal_spi_slv_init(&hspi_slv);
if (ret != IM_OK) {
    return ret;
}

ret = hal_spi_slv_transfer_count_set(&hspi_slv, 64U, 64U);
if (ret != IM_OK) {
    goto out_deinit;
}

(void)hal_spi_slv_irq_clear(&hspi_slv);
ret = hal_spi_slv_enable(&hspi_slv, HAL_SPI_SLV_DIRECTION_TX_RX);
if (ret != IM_OK) {
    goto out_deinit;
}

/* 在主机开始 CS/SCLK 前，按 TX 可用水位写入待发 frame。 */
ret = hal_spi_slv_fifo_level_get(&hspi_slv, &level);
if ((ret == IM_OK) && (level.tx_available_count != 0U)) {
    ret = hal_spi_slv_fifo_write(&hspi_slv, 0x5AU);
}

/* 主机开始传输后，轮询 RX 水位并读取。 */
if (ret == IM_OK) {
    ret = hal_spi_slv_fifo_level_get(&hspi_slv, &level);
}
if ((ret == IM_OK) && (level.rx_fill_count != 0U)) {
    ret = hal_spi_slv_fifo_read(&hspi_slv, &rx_word);
}

(void)hal_spi_slv_disable(&hspi_slv, HAL_SPI_SLV_DIRECTION_TX_RX);
out_deinit:
(void)hal_spi_slv_deinit(&hspi_slv);
return ret;

实际轮询流程应增加超时、循环填充/读取、错误状态检查和完整帧数校验。仓库中的code/examples/hal/spi_slv_hal_example.c 提供 SPI_SLV1 与 SSI1 互收发的完整示例。

4.2 IRQ 回调配置

static void spi_slv_rx_ready(hal_spi_slv_handle_t *hspi_slv,
                             void *user_data)
{
    uint32_t word;

    (void)user_data;
    while (hal_spi_slv_fifo_read(hspi_slv, &word) == IM_OK) {
        /* 将 word 放入非阻塞软件队列。 */
    }
}

static void spi_slv_error(hal_spi_slv_handle_t *hspi_slv,
                          void *user_data)
{
    uint32_t status;

    (void)user_data;
    (void)hal_spi_slv_status_get(hspi_slv, &status);
}

(void)hal_spi_slv_callback_register(&hspi_slv,
                                    HAL_SPI_SLV_CALLBACK_RX_READY,
                                    spi_slv_rx_ready);
(void)hal_spi_slv_callback_register(&hspi_slv,
                                    HAL_SPI_SLV_CALLBACK_ERROR,
                                    spi_slv_error);

(void)hal_spi_slv_irq_config(
    &hspi_slv,
    HAL_SPI_SLV_IRQ_READ_FLAG |
        HAL_SPI_SLV_IRQ_READ_EMPTY_ERR |
        HAL_SPI_SLV_IRQ_WRITE_FULL_ERR,
    HAL_SPI_SLV_IRQ_READ_EMPTY_ERR |
        HAL_SPI_SLV_IRQ_WRITE_FULL_ERR,
    1U);

SoC IRQ 入口仍需由上层注册，并在入口中调用：

hal_spi_slv_irq_handler(&hspi_slv);

5. 使用检查表

• BSP 已为目标实例配置 CLK、CS 和所需数据线；dual/quad 模式配置了足够的数据引脚。

• 已在使用 HAL 前完成系统 tick 初始化，以便 HAL 硬件复位超时逻辑工作。

• 主机和 SPI_SLV 的 CPOL、CPHA、位宽、端序及通道模式一致。

• 在 RX/TX 均关闭时设置 RXN/TXN，并在主机开始 SCLK 前将 SPI_SLV armed。

• FIFO 访问前检查 fill/unfill 水位，避免读空和写满。

• HAL IRQ enable mask 与 LL 硬件 mask 的相反语义没有混用。

• IRQ 回调只执行短小、非阻塞操作；任务间共享句柄和 FIFO 时有明确同步。

• DMA 模式同时正确配置 request、数据寄存器地址、宽度、长度和固定外设地址。

• 传输结束或异常退出时关闭 RX/TX，并按生命周期调用 reset 或 deinit。