API GUIDE / SPI / OVERVIEW

G32S10 SPI API 概述

模块概述：本文档定义 G32S10 SDK 当前 SPI 模块的 HAL 和 LL 接口、硬件资源模型及使用约束：

1. 文档范围

本文档定义 G32S10 SDK 当前 SPI 模块的 HAL 和 LL 接口、硬件资源模型及使用约束：

SPI 中间件的类型、状态机、Polling/IRQ/DMA 传输模式、统一 bus/device 接口和 API 使用说明已经独立放入：

code/middleware/spi/example/README.md

GPIO 模拟 SPI 的驱动和中间件适配 API 见：

code/middleware/spi/example/gpio_spi/README.md

本文档基于以下代码和规格编写：

本文中的“SPI 模块”包含 Motorola SPI、TI SSP 和 National Microwire 三类硬件协议能力。普通应用应优先使用中间件；HAL 和 LL 面向需要自行编排传输、IRQ 或 DMA 的高级调用方。

APPLICATION SPI Middleware / Advanced Driver 总线抽象、设备访问或直接使用 HAL

↓

PIN CONTROL GPIO pinmux 选择 SPI 信号引脚与复用功能

INTERRUPT SoC IRQ request / routing 把 SPI 中断接入统一中断分发

↓ 平台资源就绪后进入 SPI 数据通路

HAL HAL SPI 控制、FIFO、IRQ 源与 DMA 请求语义

↓

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

↓

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

层次	负责内容	不负责内容
Platform/Application	GPIO pinmux、控制器选择、SoC IRQ 申请和路由	SPI 寄存器细节和 HAL 内部状态
HAL SPI	CPM module clock/gate、参数校验、寄存器组合、FIFO、状态、控制器 IRQ source、DMA request 语义和 callback 分发	SoC `im_irq_request()`、板级 pinmux、完整传输状态机和 timeout
LL SPI	寄存器位级读写	参数保护、软件状态、传输流程和并发保护

重要边界：

hal_spi_init() 要求平台已准备 GPIO pinmux；HAL 配置并使能对应 CPM module clock/gate，但保持 SPI 控制器 disabled。
hal_spi_irq_config() 只控制 SPI 模块内部中断源，不申请或使能 SoC IRQ。
hal_spi_dma_request_config() 只维护 DMA request 语义，不申请 DMA 通道，也不通过 TIE/RIE 模拟 DMA enable。
HAL 只记录 TX underrun 和 RX overrun 等硬件错误，不表达完整传输的 busy、timeout 或完成状态机。

文件	说明
`code/include/drivers/g32s10/spi/hal_spi.h`	HAL 公开配置、句柄、状态、IRQ、DMA request 和 FIFO 接口
`code/drivers/g32s10/spi/hal_spi.c`	HAL 参数检查和 LL 组合实现
`code/include/drivers/g32s10/spi/ll_spi.h`	SPI 寄存器位操作 helper
`code/include/drivers/g32s10/spi/spi_regs.h`	SPI0/SPI1 实例、寄存器布局和位域宏
`code/bsp/g32s10/*/board_pinmux.c`	所选板卡的全板 pinmux

code/drivers/g32s10/spi/CMakeLists.txt 在 CONFIG_DRIVER_SPI 生效时编译 hal_spi.c。LL 全部位于头文件中，不产生单独目标文件。

实例	基地址	说明
`SPI0`	`0x100CB000`	SPI 控制器 0
`SPI1`	`0x1000D000`	SPI 控制器 1

能力	当前接口定义
协议	Motorola SPI、TI SSP、National Microwire 1/2
工作方向	全双工、仅发送、仅接收
FIFO	TX/RX 各 128 个 32 bit word
帧长	2 到 32 bit
CPOL/CPHA	SPI 格式支持四种组合
Endian	TX 和 RX 可独立配置四种模式
片选	SPI0 支持硬件 CS0/CS1；SPI1 HAL 当前只接受硬件 CS0；软件片选由上层通过 GPIO 实现，不属于 HAL 片选功能
间隔传输	支持 interval time、连续帧数和 interval 期间保持 CS
回环	支持控制器内部 loopback
中断	TX threshold、RX threshold、TX underrun、RX overrun、END
DMA	SPI0/SPI1 分别映射独立 TX/RX DMA request

TTRG 和 RTRG 是 4 bit 原始寄存器字段：

字段值	TX threshold 条件	RX threshold 条件
`0`	TX FIFO 数量小于等于 1	RX FIFO 数量大于等于 1
`N`	TX FIFO 数量小于等于 `N * 8`	RX FIFO 数量大于等于 `N * 8`

规格书不建议把阈值配置为 0。HAL 接收的是原始字段值 0..15，不是直接的 FIFO frame 数。