跳至主要內容

Spi模块用户手册

大约 12 分钟约 3666 字2025/12/26

Spi模块用户手册

目录

1. 简介

本SPI驱动模块提供了对 SPI (Serial Peripheral Interface) 的抽象接口，旨在实现主从模式下的高速全双工同步通信。

主要功能包括：

  • 初始化与反初始化: 通过 HLI_Spi_Init、HLI_Spi_InitModule 和 HLI_Spi_DeInit 对一个或多个SPI模块进行配置和资源释放。
  • 主模式通信:
    • 同步收发: 提供 HLI_Spi_Exchange8Bit、HLI_Spi_Exchange16Bit 和 HLI_Spi_Exchange32Bit 函数，以阻塞方式进行8/16/32位数据的全双工交换。
    • 异步收发: 提供 HLI_Spi_AsyncExchange8Bit、HLI_Spi_AsyncExchange16Bit 和 HLI_Spi_AsyncExchange32Bit 函数，以非阻塞方式启动数据交换，支持DMA和中断。
  • 从模式通信:
    • 响应配置: 提供 HLI_Spi_Config8BitSlave、HLI_Spi_Config16BitSlave 和 HLI_Spi_Config32BitSlave 函数，用于配置从机即将发送的数据和接收缓冲区。
  • DMA支持: 可配置SPI使用DMA通道进行高效的数据传输。
  • FIFO支持: 支持发送和接收FIFO功能，可提高数据吞吐量。（部分型号支持）

1.1 支持的设备

当前软件适用于以下芯片:

  • KF32A158xxxSF

1.2 名词及缩写

缩写解释
SPI串行外设接口(SPI)
DMA直接存储器访问模块
ISR中断服务例程

2. 文件结构

文件名称描述
kf32axxx_hli_spi.c此文件包含Spi驱动程序的通用功能
kf32axxx_hli_spi.h此头文件输出Spi驱动程序的宏、类型定义和函数原型
__irq_dma.c此文件包含SPI模块对应的DMA中断服务函数
__irq_spi.c此文件包含SPI模块对应的SPI中断服务函数
kf32axxx_hli_spi_Lcfg.c此文件包含Spi初始化配置信息
kf32axxx_hli_spi_Lcfg.h此文件包含Spi声明初始化配置信息
kf32axxx_hli_spi_cfg.h此文件包含Spi模块、通道定义

3. 数据结构

3.1 数据类型

3.1.1 宏定义

无。

3.1.2 枚举

  1. SPI模块编号 (HLI_Spi_ModuleType)

    枚举值解释
    HLI_SPI_MODULE_0SPI0模块
    HLI_SPI_MODULE_1SPI1模块
    HLI_SPI_MODULE_2SPI2模块

  2. SPI模式类型 (HLI_Spi_ModeType)

    枚举值解释
    HLI_SPI_MASTER_CLKDIV2主模式2分频
    HLI_SPI_MASTER_CLKDIV4主模式4分频
    HLI_SPI_MASTER_CLKDIV16主模式16分频
    HLI_SPI_MASTER_CLKDIV64主模式64分频
    HLI_SPI_SLAVE从模式

  3. 字节序 (HLI_Spi_EndianType)

    枚举值解释
    HLI_SPI_LSB小端模式
    HLI_SPI_MSB大端模式

  4. 时钟极性 (HLI_Spi_ClkModeType)

    枚举值解释
    HLI_SPI_CPOL_0_CPHA_1CPOL=0 CPHA=1
    HLI_SPI_CPOL_1_CPHA_1CPOL=1 CPHA=1
    HLI_SPI_CPOL_0_CPHA_0CPOL=0 CPHA=0
    HLI_SPI_CPOL_1_CPHA_0CPOL=1 CPHA=0

  5. 片选引脚 (HLI_Spi_CsPinsType)

    枚举值解释
    HLI_SPI_CS_PIN_SS0SS0为片选引脚
    HLI_SPI_CS_PIN_SS1SS1为片选引脚
    HLI_SPI_CS_PIN_SS2SS2为片选引脚
    HLI_SPI_CS_PIN_SS3SS3为片选引脚

    注

    主机推荐使用软件片选。

  6. DMA传输通道开关 (HLI_Spi_DmaModeType)

    枚举值解释
    HLI_SPI_DMA_ENABLE开启DMA传输通道
    HLI_SPI_DMA_DISABLE关闭DMA传输通道

  7. DMA通道 (HLI_Spi_DmaSourceType)

    枚举值解释
    HLI_SPI_DMA0_CHANNEL_1DMA0通道1
    HLI_SPI_DMA0_CHANNEL_2DMA0通道2
    ......
    HLI_SPI_DMA1_CHANNEL_7DMA1通道7

  8. FIFO模式 (HLI_Spi_FifoModeType)

    枚举值解释
    HLI_SPI_FIFO_ENABLE开启FIFO模式
    HLI_SPI_FIFO_DISABLE关闭FIFO模式

  9. SPI返回值 (HLI_Spi_StatusType)

    枚举值解释
    HLI_SPI_TRANSMISSION_COMPLETE传输完成
    HLI_SPI_TRANSMISSION_TIMEOUT传输超时
    HLI_SPI_RX_BUFFER_OVERFLOW接收buffer溢出
    HLI_SPI_TX_BUFFER_OVERFLOW发送buffer溢出
    HLI_SPI_SLAVE_TX_UNDERFLOW从机模式发送buffer下溢

3.1.3 类型定义

无。

3.2 配置项说明

  1. 静态配置

    静态配置在 kf32axxx_hli_spi_cfg.h 文件中通过宏定义完成。

    成员解释取值范围
    SPI_FEATURE_FIFO_ENABLE是否使能SPI的FIFO特性。true/false

    注

    仅部分型号支持，请参考用户手册。

  2. SPI模块消息配置结构体 (HLI_Spi_MessageType)

    成员解释取值范围
    ModeSPI工作模式。可选范围参考 HLI_Spi_ModeType。
    DataEndian数据字节序。可选范围参考 HLI_Spi_EndianType。
    ClkMode时钟极性和相位。可选范围参考 HLI_Spi_ClkModeType。
    CsPin片选引脚 (主模式通常使用GPIO软件控制，从模式需配置)。可选范围参考 HLI_Spi_CsPinsType。
    Prescaler波特率预分频值。Baud Rate = SysClk / (CLKDIV *2* (Prescaler + 1))。uint16_t 类型。
    RxDmaSwitch接收DMA使能开关。可选范围参考 HLI_Spi_DmaModeType。
    TxDmaSwitch发送DMA使能开关。可选范围参考 HLI_Spi_DmaModeType。
    RxDmaSource接收DMA通道源。可选范围参考 HLI_Spi_DmaSourceType。
    TxDmaSource发送DMA通道源。可选范围参考 HLI_Spi_DmaSourceType。
    DataTransferCompletionCallback异步数据传输完成回调函数。HLI_Spi_DataTransferCompletionFcnType 类型的函数指针。
    DataTransferErrorCallback异步数据传输错误回调函数。HLI_Spi_DataTransferErrorFcnType 类型的函数指针。
    TxFifoEnabled发送FIFO使能开关。可选范围参考 HLI_Spi_FifoModeType。
    RxFifoEnabled接收FIFO使能开关。可选范围参考 HLI_Spi_FifoModeType。
    TxFifoLowThreshold发送FIFO低阈值。0-4
    RxFifoHighThreshold接收FIFO高阈值。0-4

    注

    FIFO相关配置项，仅在 SPI_FEATURE_FIFO_ENABLE 使能时有效。

  3. SPI单元配置结构体 (HLI_Spi_NumConfigType)

    成员解释取值范围
    SpiIndexSPI模块索引编号。可选范围参考 HLI_Spi_ModuleType。
    MessageSPI模块具体配置。HLI_Spi_MessageType 类型结构体。

  4. SPI顶层配置结构体 (HLI_Spi_ConfigType)

    成员解释取值范围
    SpiNum配置的SPI模块数量。1 ~ HLI_SPI_MODULE_MAX
    NumConfigPtr指向SPI模块配置数组的指针。指向 HLI_Spi_NumConfigType 指针数组的指针数组。

4. 驱动函数

4.1 函数接口

4.1.1 HLI_Spi_Init

NameDescription
函数名称HLI_Spi_Init
语法void HLI_Spi_Init(const HLI_Spi_ConfigType *SpiConfigPtr)
同步/异步同步
重入性不可重入
形参(输入)SpiConfigPtr: 指向SPI多模块配置结构体的指针。
返回值无
描述根据配置项内容初始化一个或多个SPI模块及其对应的DMA通道。
注意事项SPI模块可分多次进行初始化。

4.1.2 HLI_Spi_InitModule

NameDescription
函数名称HLI_Spi_InitModule
语法void HLI_Spi_InitModule(HLI_Spi_ModuleType SpiIndex, const HLI_Spi_MessageType *SpiConfigPtr)
同步/异步同步
重入性SPI模块不同时可重入
形参(输入)SpiIndex: SPI模块索引编号。
形参(输入)SpiConfigPtr: 指向SPI模块具体配置结构体的指针。
返回值无
描述初始化单个SPI模块。
注意事项无

4.1.3 HLI_Spi_DeInit

NameDescription
函数名称HLI_Spi_DeInit
语法void HLI_Spi_DeInit(HLI_Spi_ModuleType SpiIndex)
同步/异步同步
重入性可重入
形参(输入)SpiIndex: SPI模块索引编号。
返回值无
描述反初始化指定的SPI模块。
注意事项无

4.1.4 HLI_Spi_Exchange8Bit

NameDescription
函数名称HLI_Spi_Exchange8Bit
语法HLI_Spi_StatusType HLI_Spi_Exchange8Bit(HLI_Spi_ModuleType SpiIndex, const uint8_t *TxData, const uint8_t *RxData, uint16_t DataLength, uint32_t TimeOut)
同步/异步同步
重入性SPI模块不同时可重入
形参(输入)SpiIndex: SPI模块索引编号。
形参(输入)TxData: 发送数据缓冲区指针。
形参(输出)RxData: 接收数据缓冲区指针。
形参(输入)DataLength: 数据长度 (单位: 字节)。
形参(输入)TimeOut: 超时时间。指一次传输的总时长非单帧传输时间。
返回值HLI_SPI_TRANSMISSION_COMPLETE: 传输完成。
HLI_SPI_TRANSMISSION_TIMEOUT: 传输超时。
描述同步收发8bit数据。
注意事项发送、接收数据数组长度需要>=DataLength。允许TxData或RxData为空指针以实现单向传输。

4.1.5 HLI_Spi_Exchange16Bit

NameDescription
函数名称HLI_Spi_Exchange16Bit
语法HLI_Spi_StatusType HLI_Spi_Exchange16Bit(HLI_Spi_ModuleType SpiIndex, const uint16_t *TxData, const uint16_t *RxData, uint16_t DataLength, uint32_t TimeOut)
同步/异步同步
重入性SPI模块不同时可重入
形参(输入)SpiIndex: SPI模块索引编号。
形参(输入)TxData: 发送数据缓冲区指针。
形参(输出)RxData: 接收数据缓冲区指针。
形参(输入)DataLength: 数据长度 (单位: 半字/2字节)。
形参(输入)TimeOut: 超时时间。指一次传输的总时长非单帧传输时间。
返回值HLI_SPI_TRANSMISSION_COMPLETE: 传输完成。
HLI_SPI_TRANSMISSION_TIMEOUT: 传输超时。
描述同步收发16bit数据。
注意事项发送、接收数据数组长度需要>=DataLength。允许TxData或RxData为空指针以实现单向传输。

4.1.6 HLI_Spi_Exchange32Bit

NameDescription
函数名称HLI_Spi_Exchange32Bit
语法HLI_Spi_StatusType HLI_Spi_Exchange32Bit(HLI_Spi_ModuleType SpiIndex, const uint32_t *TxData, const uint32_t *RxData, uint16_t DataLength, uint32_t TimeOut)
同步/异步同步
重入性SPI模块不同时可重入
形参(输入)SpiIndex: SPI模块索引编号。
形参(输入)TxData: 发送数据缓冲区指针。
形参(输出)RxData: 接收数据缓冲区指针。
形参(输入)DataLength: 数据长度 (单位: 字/4字节)。
形参(输入)TimeOut: 超时时间。指一次传输的总时长非单帧传输时间。
返回值HLI_SPI_TRANSMISSION_COMPLETE: 传输完成。
HLI_SPI_TRANSMISSION_TIMEOUT: 传输超时。
描述同步收发32bit数据。
注意事项发送、接收数据数组长度需要>=DataLength。允许TxData或RxData为空指针以实现单向传输。

4.1.7 HLI_Spi_AsyncExchange8Bit

NameDescription
函数名称HLI_Spi_AsyncExchange8Bit
语法void HLI_Spi_AsyncExchange8Bit(HLI_Spi_ModuleType SpiIndex, const uint8_t *TxData, const uint8_t *RxData, uint16_t DataLength)
同步/异步异步
重入性SPI模块不同时可重入
形参(输入)SpiIndex: SPI模块索引编号。
形参(输入)TxData: 发送数据缓冲区指针。
形参(输出)RxData: 接收数据缓冲区指针。
形参(输入)DataLength: 数据长度 (单位: 字节)。
返回值无
描述启动主机8bit异步收发数据。
注意事项传输完成后会调用初始化时注册的回调函数。

4.1.8 HLI_Spi_AsyncExchange16Bit

NameDescription
函数名称HLI_Spi_AsyncExchange16Bit
语法void HLI_Spi_AsyncExchange16Bit(HLI_Spi_ModuleType SpiIndex, const uint16_t *TxData, const uint16_t *RxData, uint16_t DataLength)
同步/异步异步
重入性SPI模块不同时可重入
形参(输入)SpiIndex: SPI模块索引编号。
形参(输入)TxData: 发送数据缓冲区指针。
形参(输出)RxData: 接收数据缓冲区指针。
形参(输入)DataLength: 数据长度 (单位: 半字)。
返回值无
描述启动主机16bit异步收发数据。
注意事项传输完成后会调用初始化时注册的回调函数。

4.1.9 HLI_Spi_AsyncExchange32Bit

NameDescription
函数名称HLI_Spi_AsyncExchange32Bit
语法void HLI_Spi_AsyncExchange32Bit(HLI_Spi_ModuleType SpiIndex, const uint32_t *TxData, const uint32_t *RxData, uint16_t DataLength)
同步/异步异步
重入性SPI模块不同时可重入
形参(输入)SpiIndex: SPI模块索引编号。
形参(输入)TxData: 发送数据缓冲区指针。
形参(输出)RxData: 接收数据缓冲区指针。
形参(输入)DataLength: 数据长度 (单位: 字)。
返回值无
描述启动主机32bit异步收发数据。
注意事项传输完成后会调用初始化时注册的回调函数。

4.1.10 HLI_Spi_Config8BitSlave

NameDescription
函数名称HLI_Spi_Config8BitSlave
语法void HLI_Spi_Config8BitSlave(HLI_Spi_ModuleType SpiIndex, const uint8_t *TxData, const uint8_t *RxData, uint16_t DataLength)
同步/异步异步
重入性SPI模块不同时可重入
形参(输入)SpiIndex: SPI模块索引编号。
形参(输入)TxData: 发送数据缓冲区指针。
形参(输出)RxData: 接收数据缓冲区指针。
形参(输入)DataLength: 数据长度 (单位: 字节)。
返回值无
描述配置从机8bit异步响应数据。
注意事项从机准备好发送数据和接收缓冲区，等待主机时钟信号。

4.1.11 HLI_Spi_Config16BitSlave

NameDescription
函数名称HLI_Spi_Config16BitSlave
语法void HLI_Spi_Config16BitSlave(HLI_Spi_ModuleType SpiIndex, const uint16_t *TxData, const uint16_t *RxData, uint16_t DataLength)
同步/异步异步
重入性SPI模块不同时可重入
形参(输入)SpiIndex: SPI模块索引编号。
形参(输入)TxData: 发送数据缓冲区指针。
形参(输出)RxData: 接收数据缓冲区指针。
形参(输入)DataLength: 数据长度 (单位: 半字)。
返回值无
描述配置从机16bit异步响应数据。
注意事项从机准备好发送数据和接收缓冲区，等待主机时钟信号。

4.1.12 HLI_Spi_Config32BitSlave

NameDescription
函数名称HLI_Spi_Config32BitSlave
语法void HLI_Spi_Config32BitSlave(HLI_Spi_ModuleType SpiIndex, const uint32_t *TxData, const uint32_t *RxData, uint16_t DataLength)
同步/异步异步
重入性SPI模块不同时可重入
形参(输入)SpiIndex: SPI模块索引编号。
形参(输入)TxData: 发送数据缓冲区指针。
形参(输出)RxData: 接收数据缓冲区指针。
形参(输入)DataLength: 数据长度 (单位: 字)。
返回值无
描述配置从机32bit异步响应数据。
注意事项从机准备好发送数据和接收缓冲区，等待主机时钟信号。

4.2 中断回调

4.2.1 HLI_Spi_DataTransferCompletionFcnType

NameDescription
函数名称HLI_Spi_DataTransferCompletionFcnType
语法typedef void (*HLI_Spi_DataTransferCompletionFcnType)(void);
形参(输入)无
返回值无
描述异步数据传输完成时的回调函数。
注意事项用户需实现此函数并在初始化时注册。

4.2.2 HLI_Spi_DataTransferErrorFcnType

NameDescription
函数名称HLI_Spi_DataTransferErrorFcnType
语法typedef void (*HLI_Spi_DataTransferErrorFcnType)(HLI_Spi_StatusType ErrorType);
形参(输入)ErrorType: 错误类型。
返回值无
描述异步数据传输发生错误时的回调函数。
注意事项用户需实现此函数并在初始化时注册。

5. 使用示例

注

示例中使用的参数仅用作示例演示，应用时以实际为准。

5.1 主机异步收发与从机响应

此示例展示了SPI2作为主机，SPI1作为从机，两者通过异步方式进行数据交换的流程。

6. 限制与假设

  1. 时钟源: 默认使用系统时钟 (通常为120MHz)。
  2. DMA/FIFO一致性: 无论主机或从机模式，推荐收发数据同时使用DMA或同时不使用DMA；同时使用FIFO或同时不使用FIFO。
  3. 片选信号: 主机模式下，驱动只负责产生时钟和数据，片选信号（SS）推荐用户通过GPIO（DIO模块）手动控制。从机模式下，需要配置硬件片选引脚。
  4. 连续传输: 推荐对同一SPI模块在数据传输完成后再进行第二次数据传输，否则可能会打断、覆盖上一轮数据传输设置。

7. 变更记录

版本时间变更记录
v1.02025-11-24新增初版文档
最近更新
贡献者: 翟宇