xt_hal_spi - SPI 驱动

版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_hal/

---

一、概述

xt_hal_spi 是 XTINY HAL SPI Master 驱动模块，提供 SPI 总线的初始化、阻塞/非阻塞读写和全双工传输能力。非阻塞 API 使用零拷贝设计（直接传递用户缓冲区指针），传输完成后通过回调通知。

设计原则 ：

• 双传输模型 ：同时提供阻塞（ _block ）和非阻塞（ _0copy ）两套 API
• 零拷贝 ：非阻塞 API 直接使用用户缓冲区，不进行内部拷贝
• 模式组合 ：SPI 模式（CPOL/CPHA）、位序、数据帧宽度通过预定义宏组合为 mode 参数
• 3 线检测 ：MOSI 与 MISO 引脚相同时自动初始化为 3 线模式

1.1 依赖

依赖	用途
xt_hal_internal.h	错误码类型 xt_err_t 及平台内部定义

---

二、核心概念

2.1 mode 参数

SPI 模式通过以下宏按位或组合：

类别	宏	说明
帧格式	XT_HAL_SPI_CPOL0_CPHA0	CPOL=0, CPHA=0（Mode 0）
帧格式	XT_HAL_SPI_CPOL0_CPHA1	CPOL=0, CPHA=1（Mode 1）
帧格式	XT_HAL_SPI_CPOL1_CPHA0	CPOL=1, CPHA=0（Mode 2）
帧格式	XT_HAL_SPI_CPOL1_CPHA1	CPOL=1, CPHA=1（Mode 3）
位序	XT_HAL_SPI_MSB_FIRST	MSB 优先（默认）
位序	XT_HAL_SPI_LSB_FIRST	LSB 优先
数据帧	XT_HAL_SPI_DATA_BITS_8	8 位数据帧（默认）
数据帧	XT_HAL_SPI_DATA_BITS_16	16 位数据帧
数据帧	XT_HAL_SPI_DATA_BITS_32	32 位数据帧

2.2 阻塞 vs 非阻塞

特性	_block	_0copy
调用方式	同步，等待传输完成	异步，立即返回
缓冲区所有权	调用期间保持有效	传输完成前保持有效
回调通知	不需要	通过 xt_hal_spi_set_cb 注册回调
适用场景	简单快速传输	大数据量、需要并行处理

2.3 全双工传输

xt_hal_spim_txrx_0copy 和 xt_hal_spim_txrx_block 同时发送和接收数据，发送缓冲区和接收缓冲区大小相同。注意：全双工传输在 3 线模式下不支持。

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_spi（SPI 驱动） 。

3.1 生命周期

函数签名	说明
xt_err_t xt_hal_spim_setup(uint8_t spi_id, uint32_t mode, uint32_t speed, uint8_t mosi_pin, uint8_t miso_pin, uint8_t sclk_pin, uint8_t cs_pin)	初始化 SPI Master
xt_err_t xt_hal_spim_close(uint8_t spi_id)	关闭 SPI Master

3.2 回调

函数签名	说明
void xt_hal_spi_set_cb(uint8_t spi_id, xt_hal_spi_cb_t cb)	设置 SPI 传输完成回调

3.3 非阻塞传输（零拷贝）

函数签名	说明
int32_t xt_hal_spim_tx_0copy(uint8_t spi_id, const void *tx_buffer, size_t size)	非阻塞发送，零拷贝
int32_t xt_hal_spim_rx_0copy(uint8_t spi_id, void *rx_buffer, size_t size)	非阻塞接收，零拷贝
int32_t xt_hal_spim_txrx_0copy(uint8_t spi_id, const void *tx_buffer, void *rx_buffer, size_t size)	非阻塞全双工传输（3 线模式不支持）

3.4 阻塞传输

函数签名	说明
int32_t xt_hal_spim_tx_block(uint8_t spi_id, const void *tx_buffer, size_t size)	阻塞发送
int32_t xt_hal_spim_rx_block(uint8_t spi_id, void *rx_buffer, size_t size)	阻塞接收
int32_t xt_hal_spim_txrx_block(uint8_t spi_id, const void *tx_buffer, void *rx_buffer, size_t size)	阻塞全双工传输（3 线模式不支持）

---

四、编译配置

无编译配置项。

---

五、常见模式

5.1 阻塞方式读传感器寄存器

#include "xt_hal_spi.h"
 
void read_sensor_reg(uint8_t spi_id, uint8_t reg_addr, uint8_t *val) {
    uint8_t tx[2] = {reg_addr | 0x80, 0x00};
    uint8_t rx[2] = {0};
 
    xt_hal_spim_txrx_block(spi_id, tx, rx, sizeof(tx));
    *val = rx[1];
}
 
void app_init(void) {
    uint32_t mode = XT_HAL_SPI_CPOL0_CPHA0 | XT_HAL_SPI_MSB_FIRST | XT_HAL_SPI_DATA_BITS_8;
    xt_hal_spim_setup(0, mode, 10000000, 3, 4, 2, XT_HAL_GPIO_INVALID_ID);
}

5.2 非阻塞发送大块数据

#include "xt_hal_spi.h"
 
static void spi_done_cb(uint8_t spi_id, uint32_t event_id) {
    /* 传输完成，可以启动下一次传输 */
}
 
void send_large_data(uint8_t spi_id, const uint8_t *data, size_t len) {
    xt_hal_spi_set_cb(spi_id, spi_done_cb);
    xt_hal_spim_tx_0copy(spi_id, data, len);
    /* 传输进行中，回调中继续处理 */
}

---

六、已知行为与限制

行为	说明
非阻塞传输忙时返回繁忙	同一 SPI 正在传输时再次调用 _0copy 系列返回 XT_EBUSY
缓冲区有效性	非阻塞传输期间用户缓冲区必须保持有效，直到回调触发
全双工在 3 线模式不可用	MOSI 与 MISO 同引脚时全双工函数行为未定义
CS 引脚可选	cs_pin 设为 XT_HAL_GPIO_INVALID_ID 时采用手动 CS 控制模式
LSB 优先支持取决于平台	部分平台硬件不支持 LSB 优先模式
速度和分频近似	时钟速率通过分频器近似匹配，实际速率可能不等于传入值
不重复初始化	已初始化的 SPI 再次调用 setup 视为错误

---

七、示例

暂无示例。