跳转至
项目
版本
全文检索

SPI

SPI（Serial Peripheral Interface）提供串行外设接口的主机与从机模式数据收发能力，支持轮询、DMA（Direct Memory Access）、中断三种传输模式以及轮询与 DMA 自动切换模式，并支持 QSPI（Quad SPI）帧格式、CRC（Cyclic Redundancy Check）校验、环回测试与低功耗挂起恢复等配置。

模块公共头文件

#include "include/driver/spi.h"

接口清单

接口名称 功能简述
uapi_spi_init 初始化指定的 SPI 总线
uapi_spi_deinit 去初始化指定的 SPI 总线
uapi_spi_set_tmod 设置 SPI 传输模式及接收数据帧数
uapi_spi_set_attr 设置 SPI 基础配置参数
uapi_spi_get_attr 读取 SPI 基础配置参数
uapi_spi_set_extra_attr 设置 SPI 高级配置参数
uapi_spi_get_extra_attr 读取 SPI 高级配置参数
uapi_spi_select_slave 主机模式下选择对通的从机设备
uapi_spi_master_write 主机模式向从机写入数据
uapi_spi_master_read 主机模式从从机读取数据
uapi_spi_master_writeread 主机模式同时写入与读取数据
uapi_spi_slave_write 从机模式向主机写入数据
uapi_spi_slave_read 从机模式从主机读取数据
uapi_spi_slave_writeread 从机模式同时写入与读取数据
uapi_spi_set_dma_mode 使能或去使能 DMA 模式传输
uapi_spi_set_irq_mode 使能或去使能中断模式传输并注册回调
uapi_spi_set_loop_back_mode 使能或去使能环回测试模式
uapi_spi_set_crc_mode 设置 SPI 收发 CRC 校验模式
uapi_spi_suspend 挂起所有 SPI 通道
uapi_spi_resume 恢复所有 SPI 通道

Functions

uapi_spi_init 

errcode_t uapi_spi_init(spi_bus_t bus, spi_attr_t *attr, spi_extra_attr_t *extra_attr)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 初始化指定 SPI 总线，按入参应用基础与高级配置参数。
  • 对已初始化的总线重复调用时直接返回成功，不重复执行初始化流程。

前置条件

  • 调用时序约束：调用本模块其他接口前必须先调用本接口成功返回。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待初始化的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
attr spi_attr_t * SPI 基础配置参数指针 不为 NULL
extra_attr spi_extra_attr_t * SPI 高级配置参数指针 -

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且初始化成功，或总线已初始化
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 大于等于 SPI_BUS_MAX_NUM 或 attr 为空
Other 其他错误码，参考 errcode_t HAL 初始化失败

参考案例

  • src/application/samples/peripheral/spi/spi_master_demo.c
  • src/application/samples/peripheral/spi/spi_slave_demo.c

uapi_spi_deinit 

errcode_t uapi_spi_deinit(spi_bus_t bus)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 去初始化指定 SPI 总线，释放相关资源。
  • 对未初始化的总线调用时直接返回成功。

前置条件

  • 调用时序约束：应在 uapi_spi_init 成功返回后调用。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待去初始化的 SPI 总线编号 小于 SPI_BUS_MAX_NUM

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且去初始化成功，或总线未初始化
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 大于等于 SPI_BUS_MAX_NUM
Other 其他错误码，参考 errcode_t HAL 去初始化失败

uapi_spi_set_tmod 

errcode_t uapi_spi_set_tmod(spi_bus_t bus, hal_spi_trans_mode_t tmod, uint8_t data_frame_num)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 设置指定 SPI 总线的传输模式与接收数据帧数。
  • 传输模式与接收数据帧数通过属性结构体配置。
  • 用于在运行时切换收发模式、发送模式、接收模式、EEPROM 读模式。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待设置的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
tmod hal_spi_trans_mode_t SPI 传输模式 HAL_SPI_TRANS_MODE_TXRX：0；
HAL_SPI_TRANS_MODE_TX：1；
HAL_SPI_TRANS_MODE_RX：2；
HAL_SPI_TRANS_MODE_EEPROM：3。
data_frame_num uint8_t SPI 接收数据帧数量 0 ~ 255

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且设置成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 大于等于 SPI_BUS_MAX_NUM 或 tmod 大于等于 HAL_SPI_TRANS_MODE_MAX
Other 其他错误码，参考 errcode_t HAL 控制接口执行失败

uapi_spi_set_attr 

errcode_t uapi_spi_set_attr(spi_bus_t bus, spi_attr_t *attr)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 设置指定 SPI 总线的基础配置参数。
  • 基础配置参数通过硬件控制接口下发。
  • 用于运行时更新主机从机模式、时钟极性相位、帧格式、帧长度等参数。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待设置的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
attr spi_attr_t * SPI 基础配置参数指针 不为 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且设置成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 大于等于 SPI_BUS_MAX_NUM 或 attr 为空
Other 其他错误码，参考 errcode_t HAL 控制接口执行失败

uapi_spi_get_attr 

errcode_t uapi_spi_get_attr(spi_bus_t bus, spi_attr_t *attr)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 读取指定 SPI 总线的基础配置参数。
  • 参数由硬件控制接口拷贝到调用方提供的结构体。
  • 用于运行时获取当前主机从机模式、时钟极性相位、帧格式、帧长度等参数。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待读取的 SPI 总线编号 小于 SPI_BUS_MAX_NUM

出参

名称 数据类型 输出说明
attr spi_attr_t * 输出当前 SPI 基础配置参数，由调用方分配内存、接口填充

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且读取成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 大于等于 SPI_BUS_MAX_NUM 或 attr 为空
Other 其他错误码，参考 errcode_t HAL 控制接口执行失败

uapi_spi_set_extra_attr 

errcode_t uapi_spi_set_extra_attr(spi_bus_t bus, spi_extra_attr_t *extra_attr)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 设置指定 SPI 总线的高级配置参数。
  • 高级配置参数通过硬件控制接口下发。
  • 用于运行时更新 DMA 收发使用、QSPI 参数、Single SPI 参数等配置。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待设置的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
extra_attr spi_extra_attr_t * SPI 高级配置参数指针 不为 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且设置成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 大于等于 SPI_BUS_MAX_NUM 或 extra_attr 为空
Other 其他错误码，参考 errcode_t HAL 控制接口执行失败

uapi_spi_get_extra_attr 

errcode_t uapi_spi_get_extra_attr(spi_bus_t bus, spi_extra_attr_t *extra_attr)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 读取指定 SPI 总线的高级配置参数。
  • 参数由硬件控制接口拷贝到调用方提供的结构体。
  • 用于运行时获取当前 DMA 收发使用、QSPI 参数、Single SPI 参数等配置。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待读取的 SPI 总线编号 小于 SPI_BUS_MAX_NUM

出参

名称 数据类型 输出说明
extra_attr spi_extra_attr_t * 输出当前 SPI 高级配置参数，由调用方分配内存、接口填充

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且读取成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 大于等于 SPI_BUS_MAX_NUM 或 extra_attr 为空
Other 其他错误码，参考 errcode_t HAL 控制接口执行失败

uapi_spi_select_slave 

errcode_t uapi_spi_select_slave(spi_bus_t bus, spi_slave_t cs)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 主机模式下选择指定 SPI 总线需要对通的从机设备。
  • 通过硬件控制接口完成从机选择。
  • 仅在主机模式下有效。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：总线必须配置为主机模式。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待操作的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
cs spi_slave_t 被选中的从机设备 spi_slave_t 全体成员

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且选择成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 大于等于 SPI_BUS_MAX_NUM 或 cs 大于等于 SPI_SLAVE_MAX_NUM
ERRCODE_SPI_MODE_MISMATCH：0x80001332 模式不匹配 总线未配置为主机模式
Other 其他错误码，参考 errcode_t HAL 控制接口执行失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_MASTER 特性宏 支持 SPI 主机功能（接口级，包裹接口声明与实现） y

uapi_spi_master_write 

errcode_t uapi_spi_master_write(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 主机模式下将数据写入到从机。
  • 支持轮询、DMA、中断三种手动切换传输模式以及轮询与 DMA 自动切换模式。
  • 自动切换模式下根据数据长度与阈值比较结果选择轮询或 DMA 模式。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：总线必须配置为主机模式，传输模式不能与读取模式冲突。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待操作的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
data const spi_xfer_data_t * 数据传输结构体指针，包含发送缓冲区与字节数 不为 NULL
timeout uint32_t 当前传输的超时时间，轮询模式下为轮询次数，DMA 模式下为超时时间，单位 ms，中断模式下不生效 -

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且写入成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 越界、data 为空、DMA 下发送缓冲区为空或字节数对齐不合法
ERRCODE_SPI_MODE_MISMATCH：0x80001332 模式不匹配 总线未配置为主机模式
ERRCODE_SPI_INVALID_TMODE：0x8000133E 传输模式无效 当前传输模式与读取模式相同
ERRCODE_SPI_TIMEOUT：0x80001333 传输超时 FIFO 忙碌检查或并发锁等待超时
ERRCODE_SPI_DMA_CONFIG_ERROR：0x80001336 DMA 配置错误 DMA 通道配置或握手选择失败
ERRCODE_SPI_DMA_TRANSFER_ERROR：0x80001337 DMA 传输错误 DMA 传输超时或传输未成功
ERRCODE_SPI_ADD_QUEUE_FAIL：0x8000133B 入队失败 中断模式下发送片段队列已满
Other 其他错误码，参考 errcode_t HAL 写入接口执行失败

参考案例

  • src/application/samples/peripheral/spi/spi_master_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_MASTER 特性宏 支持 SPI 主机功能（接口级，包裹接口声明与实现） y

uapi_spi_master_read 

errcode_t uapi_spi_master_read(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 主机模式下从从机读取数据。
  • 支持轮询、DMA、中断三种手动切换传输模式以及轮询与 DMA 自动切换模式。
  • 自动切换模式下根据数据长度与阈值比较结果选择轮询或 DMA 模式。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：总线必须配置为主机模式，传输模式不能与发送模式冲突。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待操作的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
data const spi_xfer_data_t * 数据传输结构体指针，包含接收缓冲区与字节数 不为 NULL，且 rx_buff 不为 NULL、rx_bytes 大于 0
timeout uint32_t 当前传输的超时时间，轮询模式下为轮询次数，DMA 模式下为超时时间，单位 ms，中断模式下不生效 -

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且读取成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 越界、data 为空、rx_buff 为空、rx_bytes 为 0，或 DMA 下字节数对齐不合法
ERRCODE_SPI_MODE_MISMATCH：0x80001332 模式不匹配 总线未配置为主机模式
ERRCODE_SPI_INVALID_TMODE：0x8000133E 传输模式无效 当前传输模式与发送模式相同
ERRCODE_SPI_TIMEOUT：0x80001333 传输超时 FIFO 忙碌检查或并发锁等待超时
ERRCODE_SPI_CONFIG_FAIL：0x80001330 配置失败 DMA 读路径下帧字节数为 0 或属性设置失败
ERRCODE_SPI_DMA_CONFIG_ERROR：0x80001336 DMA 配置错误 DMA 通道配置或握手选择失败
ERRCODE_SPI_DMA_TRANSFER_ERROR：0x80001337 DMA 传输错误 DMA 传输超时或传输未成功
Other 其他错误码，参考 errcode_t HAL 读取接口执行失败

参考案例

  • src/application/samples/peripheral/spi/spi_master_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_MASTER 特性宏 支持 SPI 主机功能（接口级，包裹接口声明与实现） y

uapi_spi_master_writeread 

errcode_t uapi_spi_master_writeread(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 主机模式下同时写入与读取数据。
  • 支持轮询、DMA 两种传输模式以及轮询与 DMA 自动切换模式。
  • 自动切换模式下根据数据长度与阈值比较结果选择轮询或 DMA 模式。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：总线必须配置为主机模式，传输模式不能与发送模式冲突。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待操作的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
data const spi_xfer_data_t * 数据传输结构体指针，同时承载发送与接收缓冲区及字节数 不为 NULL，且 rx_buff 不为 NULL、rx_bytes 大于 0
timeout uint32_t 当前传输的超时时间，轮询模式下为轮询次数，DMA 模式下为超时时间，单位 ms，中断模式下不生效 -

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且写入读取成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 越界、data 为空、rx_buff 为空、rx_bytes 为 0，或 DMA 下发送缓冲区为空、字节数对齐不合法
ERRCODE_SPI_MODE_MISMATCH：0x80001332 模式不匹配 总线未配置为主机模式
ERRCODE_SPI_INVALID_TMODE：0x8000133E 传输模式无效 当前传输模式与发送模式相同
ERRCODE_SPI_TIMEOUT：0x80001333 传输超时 FIFO 忙碌检查或并发锁等待超时
ERRCODE_SPI_DMA_CONFIG_ERROR：0x80001336 DMA 配置错误 DMA 通道配置或握手选择失败
ERRCODE_SPI_DMA_TRANSFER_ERROR：0x80001337 DMA 传输错误 DMA 传输超时或传输未成功
Other 其他错误码，参考 errcode_t HAL 写入或读取接口执行失败

参考案例

  • src/application/samples/peripheral/spi/spi_master_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_MASTER 特性宏 支持 SPI 主机功能（接口级，包裹接口声明与实现） y

uapi_spi_slave_write 

errcode_t uapi_spi_slave_write(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 从机模式下向主机写入数据。
  • 支持轮询、DMA、中断三种手动切换传输模式以及轮询与 DMA 自动切换模式。
  • 自动切换模式下根据数据长度与阈值比较结果选择轮询或 DMA 模式。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：总线必须配置为从机模式，传输模式不能与读取模式冲突。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待操作的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
data const spi_xfer_data_t * 数据传输结构体指针，包含发送缓冲区与字节数 不为 NULL，且 tx_buff 不为 NULL、tx_bytes 大于 0
timeout uint32_t 当前传输的超时时间，轮询模式下为轮询次数，DMA 模式下为超时时间，单位 ms，中断模式下不生效 -

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且写入成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 data 为空、tx_buff 为空、tx_bytes 为 0，或 DMA 下字节数对齐不合法
ERRCODE_SPI_MODE_MISMATCH：0x80001332 模式不匹配 总线未配置为从机模式
ERRCODE_SPI_INVALID_TMODE：0x8000133E 传输模式无效 当前传输模式与读取模式相同
ERRCODE_SPI_TIMEOUT：0x80001333 传输超时 FIFO 忙碌检查或并发锁等待超时
ERRCODE_SPI_DMA_CONFIG_ERROR：0x80001336 DMA 配置错误 DMA 通道配置或握手选择失败
ERRCODE_SPI_DMA_TRANSFER_ERROR：0x80001337 DMA 传输错误 DMA 传输超时或传输未成功
ERRCODE_SPI_ADD_QUEUE_FAIL：0x8000133B 入队失败 中断模式下发送片段队列已满
Other 其他错误码，参考 errcode_t HAL 写入接口执行失败

参考案例

  • src/application/samples/peripheral/spi/spi_slave_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_SLAVE 特性宏 支持 SPI 从机功能（接口级，包裹接口声明与实现） y

uapi_spi_slave_read 

errcode_t uapi_spi_slave_read(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 从机模式下从主机读取数据。
  • 支持轮询、DMA、中断三种手动切换传输模式以及轮询与 DMA 自动切换模式。
  • 自动切换模式下根据数据长度与阈值比较结果选择轮询或 DMA 模式。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：总线必须配置为从机模式，传输模式不能与发送模式冲突。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待操作的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
data const spi_xfer_data_t * 数据传输结构体指针，包含接收缓冲区与字节数 不为 NULL，且 rx_buff 不为 NULL、rx_bytes 大于 0
timeout uint32_t 当前传输的超时时间，轮询模式下为轮询次数，DMA 模式下为超时时间，单位 ms，中断模式下不生效 -

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且读取成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 越界、data 为空、rx_buff 为空、rx_bytes 为 0，或 DMA 下字节数对齐不合法
ERRCODE_SPI_MODE_MISMATCH：0x80001332 模式不匹配 总线未配置为从机模式
ERRCODE_SPI_INVALID_TMODE：0x8000133E 传输模式无效 当前传输模式与发送模式相同
ERRCODE_SPI_TIMEOUT：0x80001333 传输超时 FIFO 忙碌检查或并发锁等待超时
ERRCODE_SPI_DMA_CONFIG_ERROR：0x80001336 DMA 配置错误 DMA 通道配置或握手选择失败
ERRCODE_SPI_DMA_TRANSFER_ERROR：0x80001337 DMA 传输错误 DMA 传输超时或传输未成功
Other 其他错误码，参考 errcode_t HAL 读取接口执行失败

参考案例

  • src/application/samples/peripheral/spi/spi_slave_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_SLAVE 特性宏 支持 SPI 从机功能（接口级，包裹接口声明与实现） y

uapi_spi_slave_writeread 

errcode_t uapi_spi_slave_writeread(spi_bus_t bus, const spi_xfer_data_t *data, uint32_t timeout)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 从机模式下同时写入与读取数据。
  • 支持轮询、DMA 两种传输模式以及轮询与 DMA 自动切换模式。
  • 自动切换模式下根据数据长度与阈值比较结果选择轮询或 DMA 模式。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：总线必须配置为从机模式，传输模式不能与发送模式冲突。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待操作的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
data const spi_xfer_data_t * 数据传输结构体指针，同时承载发送与接收缓冲区及字节数 不为 NULL，且 rx_buff 不为 NULL、rx_bytes 大于 0
timeout uint32_t 当前传输的超时时间，轮询模式下为轮询次数，DMA 模式下为超时时间，单位 ms，中断模式下不生效 -

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且写入读取成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 越界、data 为空、rx_buff 为空、rx_bytes 为 0，或 DMA 下字节数对齐不合法
ERRCODE_SPI_MODE_MISMATCH：0x80001332 模式不匹配 总线未配置为从机模式
ERRCODE_SPI_INVALID_TMODE：0x8000133E 传输模式无效 当前传输模式与发送模式相同
ERRCODE_SPI_TIMEOUT：0x80001333 传输超时 FIFO 忙碌检查或并发锁等待超时
ERRCODE_SPI_DMA_CONFIG_ERROR：0x80001336 DMA 配置错误 DMA 通道配置或握手选择失败
ERRCODE_SPI_DMA_TRANSFER_ERROR：0x80001337 DMA 传输错误 DMA 传输超时或传输未成功
Other 其他错误码，参考 errcode_t HAL 写入或读取接口执行失败

参考案例

  • src/application/samples/peripheral/spi/spi_slave_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_SLAVE 特性宏 支持 SPI 从机功能（接口级，包裹接口声明与实现） y

uapi_spi_set_dma_mode 

errcode_t uapi_spi_set_dma_mode(spi_bus_t bus, bool en, const spi_dma_config_t *dma_cfg)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 使能或去使能指定 SPI 总线的 DMA 模式传输。
  • 使能时按入参 DMA 配置生效。
  • 去使能时清零 DMA 收发数据电平。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用，使能 DMA 模式前需完成 DMA 初始化与打开。
  • 依赖关系：中断模式下使能 DMA 会被拒绝。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待设置的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
en bool 是否使能 DMA 传输 true；
false。
dma_cfg const spi_dma_config_t * DMA 配置结构体指针，去使能时配置为 NULL 使能时不为 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且设置成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 大于等于 SPI_BUS_MAX_NUM
ERRCODE_SPI_DMA_IRQ_MODE_MUTEX：0x8000133C DMA 与中断模式互斥 中断模式已使能时使能 DMA

参考案例

  • src/application/samples/peripheral/spi/spi_master_demo.c
  • src/application/samples/peripheral/spi/spi_slave_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_DMA 特性宏 支持 SPI DMA 模式传输功能（接口级，包裹接口声明） n
CONFIG_SPI_SUPPORT_POLL_AND_DMA_AUTO_SWITCH 特性宏 支持轮询与 DMA 自动切换特性（接口级，取反条件：未启用时接口可用） n

uapi_spi_set_irq_mode 

errcode_t uapi_spi_set_irq_mode(spi_bus_t bus, bool irq_en, spi_rx_callback_t rx_callback, spi_tx_callback_t tx_callback)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 使能或去使能指定 SPI 总线的中断模式传输。
  • 使能时注册接收完成回调与发送完成回调。
  • 去使能时清空已注册的接收与发送回调。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：DMA 模式已使能时使能中断会被拒绝。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待设置的 SPI 总线编号 小于 SPI_BUS_MAX_NUM
irq_en bool 是否使用中断模式 true；
false。
rx_callback spi_rx_callback_t 接收完成回调函数，在中断上下文中调用 使能时不为 NULL
tx_callback spi_tx_callback_t 发送完成回调函数，在中断上下文中调用 使能时不为 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 参数合法且设置成功
ERRCODE_INVALID_PARAM：0x80000001 参数无效 bus 大于等于 SPI_BUS_MAX_NUM
ERRCODE_SPI_DMA_IRQ_MODE_MUTEX：0x8000133C DMA 与中断模式互斥 DMA 模式已使能时使能中断

参考案例

  • src/application/samples/peripheral/spi/spi_master_demo.c
  • src/application/samples/peripheral/spi/spi_slave_demo.c

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_INTERRUPT 特性宏 支持 SPI 中断模式传输功能（接口级，包裹接口声明） n
CONFIG_SPI_SUPPORT_POLL_AND_DMA_AUTO_SWITCH 特性宏 支持轮询与 DMA 自动切换特性（接口级，取反条件：未启用时接口可用） n

uapi_spi_set_loop_back_mode 

errcode_t uapi_spi_set_loop_back_mode(spi_bus_t bus, bool loopback_en)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 设置指定 SPI 总线是否进入环回测试模式。
  • 调用后直接返回成功，不改变硬件配置。
  • 用于预留环回测试能力。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：需开启 CONFIG_SPI_SUPPORT_LOOPBACK 配置项接口才可见。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待设置的 SPI 总线编号 -
loopback_en bool 环回模式使能或去使能 true；
false。

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 调用即返回成功

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_LOOPBACK 特性宏 支持环回测试模式（接口级，包裹函数声明与实现体） n

uapi_spi_set_crc_mode 

errcode_t uapi_spi_set_crc_mode(spi_bus_t bus, const spi_crc_config_t *crc_config, spi_crc_err_callback_t cb)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 设置指定 SPI 总线的发送与接收 CRC 校验模式。
  • 注册 CRC 校验错误回调函数。
  • 调用后直接返回成功，不改变硬件配置。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：需开启 CONFIG_SPI_SUPPORT_CRC 配置项接口才可见。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
bus spi_bus_t 指定待设置的 SPI 总线编号 -
crc_config const spi_crc_config_t * CRC 配置参数指针 -
cb spi_crc_err_callback_t CRC 校验错误回调函数 -

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 调用即返回成功

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_CRC 特性宏 支持 CRC 校验（接口级，包裹函数声明与实现体） n

uapi_spi_suspend 

errcode_t uapi_spi_suspend(uintptr_t arg)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 挂起所有 SPI 通道。
  • 通过硬件控制接口完成挂起操作。
  • 在开启低功耗时钟控制或 DMA 时联动执行对应的关闭动作。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用。
  • 依赖关系：需开启 CONFIG_SPI_SUPPORT_LPM 配置项接口才可见。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
arg uintptr_t 挂起参数，实际作为 SPI 总线编号使用 小于 SPI_BUS_MAX_NUM

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 总线未初始化或挂起成功
ERRCODE_FAIL：0xFFFFFFFF 执行失败 HAL 挂起控制接口执行失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_LPM 特性宏 支持低功耗模式挂起与恢复（接口级，包裹函数声明与实现体） n

uapi_spi_resume 

errcode_t uapi_spi_resume(uintptr_t arg)

声明头文件

#include "include/driver/spi.h"

功能说明

  • 恢复所有 SPI 通道。
  • 通过硬件控制接口完成恢复操作。
  • 在开启低功耗时钟控制或 DMA 时联动执行对应的恢复动作。

前置条件

  • 调用时序约束：必须在 uapi_spi_init 成功返回后调用，且应先调用过 uapi_spi_suspend。
  • 依赖关系：需开启 CONFIG_SPI_SUPPORT_LPM 配置项接口才可见。
  • 上下文限制：需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
arg uintptr_t 恢复参数，实际作为 SPI 总线编号使用 小于 SPI_BUS_MAX_NUM

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 总线未初始化或恢复成功
ERRCODE_FAIL：0xFFFFFFFF 执行失败 HAL 恢复控制接口执行失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_SPI_SUPPORT_LPM 特性宏 支持低功耗模式挂起与恢复（接口级，包裹函数声明与实现体） n

Type definitions

spi_attr_t 

typedef hal_spi_attr_t spi_attr_t;

使用说明

用于 uapi_spi_init、uapi_spi_set_attr、uapi_spi_get_attr 的基础配置参数载体。

spi_extra_attr_t 

typedef hal_spi_extra_attr_t spi_extra_attr_t;

使用说明

用于 uapi_spi_init、uapi_spi_set_extra_attr、uapi_spi_get_extra_attr 的高级配置参数载体。

spi_xfer_data_t 

typedef hal_spi_xfer_data_t spi_xfer_data_t;

使用说明

用于主从机读写接口的数据传输结构体载体。

spi_rx_callback_t 

typedef void (*spi_rx_callback_t)(const void *buffer, uint32_t length, bool error);

使用说明

通过 uapi_spi_set_irq_mode 注册，在中断上下文中被调用。buffer 指向接收缓冲区，由读取接口的参数传入；length 为已接收的数据长度；error 表示 SPI 传输是否存在错误，包括接收上限溢出错误与接收下限溢出错误。

spi_tx_callback_t 

typedef void (*spi_tx_callback_t)(const void *buffer, uint32_t length);

使用说明

通过 uapi_spi_set_irq_mode 注册，在中断上下文中被调用。buffer 指向写入缓冲区，由写接口的参数传入；length 为已写入的数据长度。

spi_crc_err_callback_t 

typedef void (*spi_crc_err_callback_t)(spi_bus_t bus);

使用说明

通过 uapi_spi_set_crc_mode 注册，用于 CRC 校验错误时的回调通知，参数 bus 为发生错误的 SPI 总线编号。

typedef_errcode_t 

typedef uint32_t errcode_t;

使用说明

本模块返回类型为 errcode_t 的对外接口的返回值类型。

Enumerations

enum spi_bus_t 

typedef enum {
    SPI_BUS_0 = 0,         // SPI
    SPI_BUS_MAX = SPI_BUS_0,
    SPI_BUS_1 = 1,         // QSPI
    QSPI_BUS_1 = SPI_BUS_1,
    SPI_BUS_NONE = SPI_BUS_MAX_NUMBER
} spi_bus_t;
枚举成员 取值 描述
SPI_BUS_0 0 SPI 总线 0
SPI_BUS_MAX 0 SPI 总线数量上限（等同 SPI_BUS_0）
SPI_BUS_1 1 QSPI 总线 1
QSPI_BUS_1 1 QSPI 总线 1（等同 SPI_BUS_1）
SPI_BUS_NONE 2 无效/未指定的 SPI 总线编号（等同 SPI_BUS_MAX_NUMBER）

enum spi_slave_t 

typedef enum spi_slave {
    SPI_SLAVE0 = 0,         /*!< SPI Slave index 0. */
    SPI_SLAVE_MAX_NUM,
    SPI_SLAVE_NONE = SPI_SLAVE_MAX_NUM
} spi_slave_t;
枚举成员 取值 描述
SPI_SLAVE0 0 SPI 从机索引 0
SPI_SLAVE_MAX_NUM 1 SPI 从机数量上限
SPI_SLAVE_NONE 1 无效/未指定的从机编号（等同 SPI_SLAVE_MAX_NUM）

hal_spi_cfg_frame_format_t 

typedef enum hal_spi_cfg_frame_format {
    SPI_CFG_FRAME_FORMAT_MOTOROLA_SPI,
    SPI_CFG_FRAME_FORMAT_TEXAS_SSP,
    SPI_CFG_FRAME_FORMAT_NS_MICROWIRE,
    SPI_CFG_FRAME_FORMAT_MAX
} hal_spi_cfg_frame_format_t;
枚举成员 取值 描述
SPI_CFG_FRAME_FORMAT_MOTOROLA_SPI 0 Motorola SPI 帧格式
SPI_CFG_FRAME_FORMAT_TEXAS_SSP 1 Texas Instruments SSP 帧格式
SPI_CFG_FRAME_FORMAT_NS_MICROWIRE 2 National Microwire 帧格式
SPI_CFG_FRAME_FORMAT_MAX 3 配置帧格式上限值

hal_spi_cfg_clk_cpol_t 

typedef enum hal_spi_cfg_clk_cpol {
    SPI_CFG_CLK_CPOL_0,
    SPI_CFG_CLK_CPOL_1,
    SPI_CFG_CLK_CPOL_MAX
} hal_spi_cfg_clk_cpol_t;
枚举成员 取值 描述
SPI_CFG_CLK_CPOL_0 0 串行时钟空闲状态为低电平
SPI_CFG_CLK_CPOL_1 1 串行时钟空闲状态为高电平
SPI_CFG_CLK_CPOL_MAX 2 时钟极性上限值

hal_spi_cfg_clk_cpha_t 

typedef enum hal_spi_cfg_clk_cpha {
    SPI_CFG_CLK_CPHA_0,
    SPI_CFG_CLK_CPHA_1,
    SPI_CFG_CLK_CPHA_MAX
} hal_spi_cfg_clk_cpha_t;
枚举成员 取值 描述
SPI_CFG_CLK_CPHA_0 0 串行时钟在第一个数据位中间切换
SPI_CFG_CLK_CPHA_1 1 串行时钟在第一个数据位开始时切换
SPI_CFG_CLK_CPHA_MAX 2 时钟相位上限值

hal_spi_cfg_sste_t 

typedef enum hal_spi_cfg_sste {
    SPI_CFG_SSTE_DISABLE,
    SPI_CFG_SSTE_ENABLE,
    SPI_CFG_SSTE_MAX
} hal_spi_cfg_sste_t;
枚举成员 取值 描述
SPI_CFG_SSTE_DISABLE 0 不使能从机选择切换
SPI_CFG_SSTE_ENABLE 1 使能从机选择切换
SPI_CFG_SSTE_MAX 2 从机选择切换配置上限值

hal_spi_trans_mode_t 

typedef enum hal_spi_trans_mode {
    HAL_SPI_TRANS_MODE_TXRX = 0,
    HAL_SPI_TRANS_MODE_TX,
    HAL_SPI_TRANS_MODE_RX,
    HAL_SPI_TRANS_MODE_EEPROM,
    HAL_SPI_TRANS_MODE_MAX
} hal_spi_trans_mode_t;
枚举成员 取值 描述
HAL_SPI_TRANS_MODE_TXRX 0 收发模式
HAL_SPI_TRANS_MODE_TX 1 发送模式
HAL_SPI_TRANS_MODE_RX 2 接收模式
HAL_SPI_TRANS_MODE_EEPROM 3 EEPROM 读模式
HAL_SPI_TRANS_MODE_MAX 4 传输模式上限值

hal_spi_frame_size_t 

typedef enum hal_spi_frame_size {
    HAL_SPI_FRAME_SIZE_8    = 0x07,
    HAL_SPI_FRAME_SIZE_16   = 0x0F,
    HAL_SPI_FRAME_SIZE_24   = 0x17,
    HAL_SPI_FRAME_SIZE_32   = 0x1F
} hal_spi_frame_size_t;
枚举成员 取值 描述
HAL_SPI_FRAME_SIZE_8 0x07 8 位串行数据传输
HAL_SPI_FRAME_SIZE_16 0x0F 16 位串行数据传输，当前暂不支持
HAL_SPI_FRAME_SIZE_24 0x17 24 位串行数据传输，当前暂不支持
HAL_SPI_FRAME_SIZE_32 0x1F 32 位串行数据传输

hal_spi_frame_format_t 

typedef enum hal_spi_frame_format {
    HAL_SPI_FRAME_FORMAT_STANDARD = 0,
    HAL_SPI_FRAME_FORMAT_DUAL,
    HAL_SPI_FRAME_FORMAT_QUAD,
    HAL_SPI_FRAME_FORMAT_OCTAL,
    HAL_SPI_FRAME_FORMAT_DOUBLE_OCTAL,
    HAL_SPI_FRAME_FORMAT_SIXT,
    HAL_SPI_FRAME_FORMAT_MAX_NUM,
    HAL_SPI_FRAME_FORMAT_NONE = HAL_SPI_FRAME_FORMAT_MAX_NUM
} hal_spi_frame_format_t;
枚举成员 取值 描述
HAL_SPI_FRAME_FORMAT_STANDARD 0 标准单线 SPI 帧格式
HAL_SPI_FRAME_FORMAT_DUAL 1 双线 SPI 帧格式
HAL_SPI_FRAME_FORMAT_QUAD 2 四线 SPI 帧格式
HAL_SPI_FRAME_FORMAT_OCTAL 3 八线 SPI 帧格式
HAL_SPI_FRAME_FORMAT_DOUBLE_OCTAL 4 十六线 SPI 帧格式
HAL_SPI_FRAME_FORMAT_SIXT 5 保留的帧格式值
HAL_SPI_FRAME_FORMAT_MAX_NUM 6 SPI 帧格式数量上限
HAL_SPI_FRAME_FORMAT_NONE 6 无效/未指定的 SPI 帧格式，等同 HAL_SPI_FRAME_FORMAT_MAX_NUM

hal_spi_trans_type_t 

typedef enum hal_spi_trans_type {
    HAL_SPI_TRANS_TYPE_INST_S_ADDR_S = 0,
    HAL_SPI_TRANS_TYPE_INST_S_ADDR_Q,
    HAL_SPI_TRANS_TYPE_INST_Q_ADDR_Q,
    HAL_SPI_TRANS_TYPE_MAX = HAL_SPI_TRANS_TYPE_INST_Q_ADDR_Q
} hal_spi_trans_type_t;
枚举成员 取值 描述
HAL_SPI_TRANS_TYPE_INST_S_ADDR_S 0 指令和地址均使用单线 SPI 传输
HAL_SPI_TRANS_TYPE_INST_S_ADDR_Q 1 指令使用单线 SPI 传输，地址按照帧格式寄存器配置传输
HAL_SPI_TRANS_TYPE_INST_Q_ADDR_Q 2 指令和地址均按照帧格式寄存器配置传输
HAL_SPI_TRANS_TYPE_MAX 2 传输类型上限值

hal_spi_inst_len_t 

typedef enum hal_spi_inst_len {
    HAL_SPI_INST_LEN_0 = 0,
    HAL_SPI_INST_LEN_4,
    HAL_SPI_INST_LEN_8,
    HAL_SPI_INST_LEN_16,
    HAL_SPI_INST_LEN_MAX = HAL_SPI_INST_LEN_16
} hal_spi_inst_len_t;
枚举成员 取值 描述
HAL_SPI_INST_LEN_0 0 不携带指令
HAL_SPI_INST_LEN_4 1 4 位指令
HAL_SPI_INST_LEN_8 2 8 位指令
HAL_SPI_INST_LEN_16 3 16 位指令
HAL_SPI_INST_LEN_MAX 3 指令长度上限值

hal_spi_addr_len_t 

typedef enum hal_spi_addr_len {
    HAL_SPI_ADDR_LEN_0 = 0,
    HAL_SPI_ADDR_LEN_4,
    HAL_SPI_ADDR_LEN_8,
    HAL_SPI_ADDR_LEN_12,
    HAL_SPI_ADDR_LEN_16,
    HAL_SPI_ADDR_LEN_20,
    HAL_SPI_ADDR_LEN_24,
    HAL_SPI_ADDR_LEN_28,
    HAL_SPI_ADDR_LEN_32,
    HAL_SPI_ADDR_LEN_36,
    HAL_SPI_ADDR_LEN_40,
    HAL_SPI_ADDR_LEN_44,
    HAL_SPI_ADDR_LEN_48,
    HAL_SPI_ADDR_LEN_52,
    HAL_SPI_ADDR_LEN_56,
    HAL_SPI_ADDR_LEN_60,
    HAL_SPI_ADDR_LEN_MAX = HAL_SPI_ADDR_LEN_60
} hal_spi_addr_len_t;
枚举成员 取值 描述
HAL_SPI_ADDR_LEN_0 0 0 位地址长度
HAL_SPI_ADDR_LEN_4 1 4 位地址长度
HAL_SPI_ADDR_LEN_8 2 8 位地址长度
HAL_SPI_ADDR_LEN_12 3 12 位地址长度
HAL_SPI_ADDR_LEN_16 4 16 位地址长度
HAL_SPI_ADDR_LEN_20 5 20 位地址长度
HAL_SPI_ADDR_LEN_24 6 24 位地址长度
HAL_SPI_ADDR_LEN_28 7 28 位地址长度
HAL_SPI_ADDR_LEN_32 8 32 位地址长度
HAL_SPI_ADDR_LEN_36 9 36 位地址长度
HAL_SPI_ADDR_LEN_40 10 40 位地址长度
HAL_SPI_ADDR_LEN_44 11 44 位地址长度
HAL_SPI_ADDR_LEN_48 12 48 位地址长度
HAL_SPI_ADDR_LEN_52 13 52 位地址长度
HAL_SPI_ADDR_LEN_56 14 56 位地址长度
HAL_SPI_ADDR_LEN_60 15 60 位地址长度
HAL_SPI_ADDR_LEN_MAX 15 地址长度上限值

Structures

spi_dma_config_t 

typedef struct spi_dma_config {
    uint8_t src_width;
    uint8_t dest_width;
    uint8_t burst_length;
    uint8_t priority;
} spi_dma_config_t;

成员说明

成员名称 数据类型 描述
src_width uint8_t 源端传输数据宽度，0 为 1 Bytes；
1 为 2 Bytes；
2 为 4 Bytes。
dest_width uint8_t 目的端传输数据宽度，0 为 1 Bytes；
1 为 2 Bytes；
2 为 4 Bytes。
burst_length uint8_t 每次目的 burst 请求写入的数据量，0 为 1；
1 为 4；
2 为 8；
3 为 16。
priority uint8_t 传输通道优先级，范围为 0 ~ 3

spi_crc_config_t 

typedef struct spi_crc_config {
    uint32_t  tx_crc_len;
    uint32_t  rx_crc_len;
    uint32_t  tx_crc_ini;
    uint32_t  rx_crc_ini;
    uint32_t  tx_crc_poly;
    uint32_t  rx_crc_poly;
    uint32_t  tx_crc_xor_out;
    uint32_t  rx_crc_xor_out;
    bool      tx_crc_refin;
    bool      tx_crc_refout;
    bool      rx_crc_refin;
    bool      rx_crc_refout;
} spi_crc_config_t;

成员说明

成员名称 数据类型 描述
tx_crc_len uint32_t 发送方向在此长度之前发送 CRC 校验数据
rx_crc_len uint32_t 接收方向在此长度之前接收 CRC 校验数据
tx_crc_ini uint32_t 发送方向 CRC 初始化值
rx_crc_ini uint32_t 接收方向 CRC 初始化值
tx_crc_poly uint32_t 发送方向 CRC 多项式
rx_crc_poly uint32_t 接收方向 CRC 多项式
tx_crc_xor_out uint32_t 发送方向 CRC 结果异或配置
rx_crc_xor_out uint32_t 接收方向 CRC 结果异或配置
tx_crc_refin bool 发送方向 CRC 输入值翻转配置
tx_crc_refout bool 发送方向 CRC 输出值翻转配置
rx_crc_refin bool 接收方向 CRC 输入值翻转配置
rx_crc_refout bool 接收方向 CRC 输出值翻转配置

hal_spi_xfer_qspi_param_t 

typedef struct hal_spi_xfer_qspi_param {
    hal_spi_trans_type_t trans_type;
    hal_spi_inst_len_t   inst_len;
    hal_spi_addr_len_t   addr_len;
    uint32_t             wait_cycles;
} hal_spi_xfer_qspi_param_t;

成员说明

成员名称 数据类型 描述
trans_type hal_spi_trans_type_t 传输类型，用于指定指令和地址的传输方式
inst_len hal_spi_inst_len_t 指令长度，支持 0、4、8、16 位
addr_len hal_spi_addr_len_t 地址长度，支持 0、8、16、24、32 位
wait_cycles uint32_t 等待的周期数

hal_spi_xfer_sspi_param_t 

typedef struct hal_spi_xfer_sspi_param {
    uint32_t             wait_cycles;
} hal_spi_xfer_sspi_param_t;

成员说明

成员名称 数据类型 描述
wait_cycles uint32_t 等待的周期数

hal_spi_attr_t 

typedef struct hal_spi_attr {
    bool is_slave;
    uint32_t slave_num;
    uint32_t bus_clk;
    uint32_t freq_mhz;
    uint32_t clk_polarity;
    uint32_t clk_phase;
    uint32_t frame_format;
    uint32_t spi_frame_format;
    uint32_t frame_size;
    uint32_t tmod;
    uint32_t ndf;
    uint32_t sste;
} hal_spi_attr_t;

成员说明

成员名称 数据类型 描述
is_slave bool SPI 工作模式，true 表示从机模式，false 表示主机模式
slave_num uint32_t 选择从机时的索引，0 表示不选择，1 表示从机索引 0，2 表示从机索引 1，依此类推
bus_clk uint32_t 用于计算 SPI 时钟分频系数的输入时钟
freq_mhz uint32_t SPI 的工作频率
clk_polarity uint32_t SPI 的时钟极性，取值参考 hal_spi_cfg_clk_cpol_t
clk_phase uint32_t SPI 的时钟相位，取值参考 hal_spi_cfg_clk_cpha_t
frame_format uint32_t 串行传输协议，取值参考 hal_spi_cfg_frame_format_t
spi_frame_format uint32_t SPI 帧格式，取值参考 hal_spi_frame_format_t
frame_size uint32_t SPI 帧长度，取值参考 hal_spi_frame_size_t
tmod uint32_t SPI 传输模式，取值参考 hal_spi_trans_mode_t
ndf uint32_t SPI 的数据帧数
sste uint32_t SPI 从机选择切换使能配置，取值参考 hal_spi_cfg_sste_t

hal_spi_extra_attr_t 

typedef struct hal_spi_extra_attr {
    bool tx_use_dma;
    bool rx_use_dma;
    hal_spi_xfer_qspi_param_t qspi_param;
    hal_spi_xfer_sspi_param_t sspi_param;
} hal_spi_extra_attr_t;

成员说明

成员名称 数据类型 描述
tx_use_dma bool SPI 发送数据是否使用 DMA
rx_use_dma bool SPI 接收数据是否使用 DMA
qspi_param hal_spi_xfer_qspi_param_t QSPI 参数
sspi_param hal_spi_xfer_sspi_param_t Single SPI 参数

hal_spi_xfer_data_t 

typedef struct hal_spi_xfer_data {
    uint8_t *tx_buff;
    uint32_t tx_bytes;
    uint8_t *rx_buff;
    uint32_t rx_bytes;
    uint8_t cmd;
    uint8_t reserved[3];
    uint32_t addr;
} hal_spi_xfer_data_t;

成员说明

成员名称 数据类型 描述
tx_buff uint8_t * 通过 TX FIFO 发送数据的缓冲区
tx_bytes uint32_t 需要发送的数据字节数，取值需与 hal_spi_attr_t 的 frame_size 配置匹配
rx_buff uint8_t * 通过 RX FIFO 接收数据的缓冲区
rx_bytes uint32_t 需要接收的数据字节数，取值需与 hal_spi_attr_t 的 frame_size 配置匹配
cmd uint8_t QSPI 模式下的命令
reserved uint8_t[3] 保留字段
addr uint32_t QSPI 模式下的地址

Macros

SPI_BUS_MAX_NUM 

#define SPI_BUS_MAX_NUM SPI_BUS_MAX_NUMBER

ERRCODE_SUCC 

#define ERRCODE_SUCC                                        0UL

ERRCODE_INVALID_PARAM 

#define ERRCODE_INVALID_PARAM                               0x80000001

ERRCODE_FAIL 

#define ERRCODE_FAIL                                        0xFFFFFFFF

ERRCODE_SPI_CONFIG_FAIL 

#define ERRCODE_SPI_CONFIG_FAIL                             0x80001330

ERRCODE_SPI_MODE_MISMATCH 

#define ERRCODE_SPI_MODE_MISMATCH                           0x80001332

ERRCODE_SPI_TIMEOUT 

#define ERRCODE_SPI_TIMEOUT                                 0x80001333

ERRCODE_SPI_DMA_CONFIG_ERROR 

#define ERRCODE_SPI_DMA_CONFIG_ERROR                        0x80001336

ERRCODE_SPI_DMA_TRANSFER_ERROR 

#define ERRCODE_SPI_DMA_TRANSFER_ERROR                      0x80001337

ERRCODE_SPI_ADD_QUEUE_FAIL 

#define ERRCODE_SPI_ADD_QUEUE_FAIL                          0x8000133B

ERRCODE_SPI_DMA_IRQ_MODE_MUTEX 

#define ERRCODE_SPI_DMA_IRQ_MODE_MUTEX                      0x8000133C

ERRCODE_SPI_INVALID_TMODE 

#define ERRCODE_SPI_INVALID_TMODE                           0x8000133E