ch32v00x_spi.h

描述

#

该文件包含 CH32V00x 系列微控制器 SPI 外设固件库的所有函数原型、常量定义、枚举类型和结构体定义。SPI（串行外设接口）是一种高速、全双工、同步的通信协议，广泛用于连接微控制器与传感器、存储器、显示器等外设。本库支持主从模式切换、CRC 校验、DMA 传输、软件 NSS 管理、单双线模式等高级功能，特别针对 CH32V00x 系列的硬件特性进行了优化。注意：在从模式下发送数据时，必须将 SPI_CPOL 设置为高电平（SPI_CPOL_High），这是由芯片内部时序逻辑决定的硬性要求。

常量

#

SPI_data_direction

#

指定 SPI 数据传输方向，支持全双工、单向接收、单向发送和半双工模式。
在半双工模式下，通过 SPI_BiDirectionalLineConfig() 动态切换收发方向，适用于节省引脚资源的场景。

以上所有值都强制转换为 uint16_t

SPI_mode

#

配置 SPI 工作模式为主机或从机。
主模式下由 SPI 控制时钟（SCK），从模式下时钟由外部主机提供。从模式下若需主动发送数据，必须确保 SPI_CPOL=1 以匹配主机时钟极性。

以上所有值都强制转换为 uint16_t

SPI_data_size

#

设置每次传输的数据帧大小。
CH32V00x 的 SPI 支持 8 位和 16 位两种帧格式，16 位模式下可一次传输两个字节，提高吞吐率，但需确保外设兼容。

以上所有值都强制转换为 uint16_t

SPI_Clock_Polarity

#

设置 SPI 时钟的稳态电平（CPOL）。
CPOL=0 表示空闲时钟为低电平，CPOL=1 表示空闲时钟为高电平。在从模式下发送数据时，必须与主机的 CPOL 一致，否则通信失败。

以上所有值都强制转换为 uint16_t

SPI_Clock_Phase

#

设置时钟相位（CPHA），决定数据采样发生在时钟的第几个边沿。
CPHA=0：第一个时钟边沿采样；CPHA=1：第二个时钟边沿采样。必须与主机配置一致。

以上所有值都强制转换为 uint16_t

SPI_Slave_Select_management

#

配置 NSS（从机选择）信号的管理方式。
硬件管理由芯片自动控制 NSS 引脚，软件管理通过 SPI_NSSInternalSoftwareConfig() 手动控制 SSI 位，适用于多从机或无物理 NSS 引脚的场景。

以上所有值都强制转换为 uint16_t

SPI_BaudRate_Prescaler

#

设置 SPI 时钟分频系数，决定 SCK 频率。
SCK = PCLK / (prescaler)，主模式下有效。从模式下时钟由主机决定，此参数仅影响发送速率。

以上所有值都强制转换为 uint16_t

SPI_MSB_LSB transmission

#

设置数据传输的起始位顺序。
注意：SPI_FirstBit_LSB 在从模式下不被支持，仅在主模式下可用。

以上所有值都强制转换为 uint16_t

SPI_I2S_DMA_transfer_requests

#

配置 SPI 的 DMA 请求使能，用于高速数据传输。
DMA 可在后台自动完成数据收发，避免 CPU 轮询，提高系统效率。

以上所有值都强制转换为 uint16_t

SPI_NSS_internal_software_management

#

软件控制 NSS 信号的内部状态（SSI 位）。
仅在 SPI_NSS_Soft 模式下有效，用于模拟从机选择信号。

以上所有值都强制转换为 uint16_t

SPI_CRC_Transmit_Receive

#

指定读取 CRC 寄存器的类型（发送或接收）。
用于调试或校验 CRC 值，配合 SPI_GetCRC() 使用。

以上所有值都强制转换为 uint8_t

SPI_direction_transmit_receive

#

用于 SPI_BiDirectionalLineConfig() 的方向控制掩码，与 SPI_Direction_Tx/Rx 一致。
在半双工模式下，通过此常量切换数据线方向，实现单线双向通信。

以上所有值都强制转换为 uint16_t

SPI_I2S_interrupts_definition

#

SPI/I2S 中断标志位定义，用于 SPI_I2S_ITConfig() 和 SPI_I2S_GetITStatus()。

以上所有值都强制转换为 uint8_t

SPI_I2S_flags_definition

#

SPI/I2S 状态标志位定义，用于 SPI_I2S_GetFlagStatus()。

以上所有值都强制转换为 uint16_t

枚举

#

无

结构体

#

SPI_InitTypeDef

#

SPI 初始化结构体，用于配置 SPI 外设的所有工作参数。
该结构体在 SPI_Init() 中被读取并写入 SPI 控制寄存器，SPI_StructInit() 会将其所有成员初始化为默认值。

函数

#

SPI_I2S_DeInit

#

void SPI_I2S_DeInit(SPI_TypeDef *SPIx)
将指定的 SPI 外设寄存器恢复为复位默认值。通过复位 APB2 总线上的 SPI 时钟实现，确保寄存器状态完全清除。

参数：

返回值：
无

SPI_Init

#

void SPI_Init(SPI_TypeDef *SPIx, SPI_InitTypeDef *SPI_InitStruct)
根据传入的初始化结构体配置 SPI 外设。该函数会将结构体中的所有参数写入 SPI 控制寄存器（CTLR1 和 CRCR），并自动启用 SPI。

参数：

返回值：
无

注意：在从模式下发送数据时，必须确保 SPI_CPOL=1，否则通信将失败。

SPI_StructInit

#

void SPI_StructInit(SPI_InitTypeDef *SPI_InitStruct)
将 SPI_InitTypeDef 结构体的所有成员初始化为默认值，便于用户按需修改。

参数：

返回值：
无

默认配置：全双工、从模式、8位数据、CPOL=0、CPHA=0、分频=2、MSB 优先、CRC 多项式=7。

SPI_Cmd

#

void SPI_Cmd(SPI_TypeDef *SPIx, FunctionalState NewState)
启用或禁用 SPI 外设。通过设置或清除 CTLR1 寄存器中的 SPE 位实现。

参数：

返回值：
无

SPI_I2S_ITConfig

#

void SPI_I2S_ITConfig(SPI_TypeDef *SPIx, uint8_t SPI_I2S_IT, FunctionalState NewState)
启用或禁用指定的 SPI 中断源。通过设置或清除 CTLR2 寄存器中的对应中断使能位实现。

参数：

返回值：
无

SPI_I2S_DMACmd

#

void SPI_I2S_DMACmd(SPI_TypeDef *SPIx, uint16_t SPI_I2S_DMAReq, FunctionalState NewState)
启用或禁用 SPI 的 DMA 传输请求。DMA 可在后台自动收发数据，减轻 CPU 负担。

参数：

返回值：
无

SPI_I2S_SendData

#

void SPI_I2S_SendData(SPI_TypeDef *SPIx, uint16_t Data)
向 SPI 数据寄存器写入待发送数据，触发一次传输。

参数：

返回值：
无

SPI_I2S_ReceiveData

#

uint16_t SPI_I2S_ReceiveData(SPI_TypeDef *SPIx)
读取 SPI 数据寄存器中的最近接收数据。

参数：

返回值：
uint16_t：接收到的数据值（8位或16位，取决于配置）

SPI_NSSInternalSoftwareConfig

#

void SPI_NSSInternalSoftwareConfig(SPI_TypeDef *SPIx, uint16_t SPI_NSSInternalSoft)
在软件管理 NSS 模式下，通过 SSI 位手动控制从机选择信号。

参数：

返回值：
无

SPI_SSOutputCmd

#

void SPI_SSOutputCmd(SPI_TypeDef *SPIx, FunctionalState NewState)
启用或禁用 SPI 主模式下的 SS（从机选择）输出引脚。仅在主模式下有效。

参数：

返回值：
无

SPI_DataSizeConfig

#

void SPI_DataSizeConfig(SPI_TypeDef *SPIx, uint16_t SPI_DataSize)
动态修改 SPI 数据帧大小（8位或16位），无需重新初始化整个外设。

参数：

返回值：
无

SPI_TransmitCRC

#

void SPI_TransmitCRC(SPI_TypeDef *SPIx)
在下一次传输中自动发送 CRC 校验值。需先启用 CRC 计算（SPI_CalculateCRC()）。

参数：

返回值：
无

SPI_CalculateCRC

#

void SPI_CalculateCRC(SPI_TypeDef *SPIx, FunctionalState NewState)
启用或禁用 SPI 在传输过程中自动计算 CRC 校验值。

参数：

返回值：
无

SPI_GetCRC

#

uint16_t SPI_GetCRC(SPI_TypeDef *SPIx, uint8_t SPI_CRC)
读取 SPI 的发送或接收 CRC 寄存器值，用于校验或调试。

参数：

返回值：
uint16_t：CRC 寄存器的当前值

SPI_GetCRCPolynomial

#

uint16_t SPI_GetCRCPolynomial(SPI_TypeDef *SPIx)
读取 SPI 的 CRC 多项式寄存器值，用于验证配置是否正确。

参数：

返回值：
uint16_t：CRC 多项式值（默认为 7）

SPI_BiDirectionalLineConfig

#

void SPI_BiDirectionalLineConfig(SPI_TypeDef *SPIx, uint16_t SPI_Direction)
在单线半双工模式下切换数据线方向（发送或接收）。

参数：

返回值：
无

注意：仅在 SPI_Direction_1Line_Rx 或 SPI_Direction_1Line_Tx 模式下有效。

SPI_I2S_GetFlagStatus

#

FlagStatus SPI_I2S_GetFlagStatus(SPI_TypeDef *SPIx, uint16_t SPI_I2S_FLAG)
检查指定的 SPI 状态标志是否被置位。

参数：

返回值：
FlagStatus：SET（标志置位）或 RESET（标志未置位）

SPI_I2S_ClearFlag

#

void SPI_I2S_ClearFlag(SPI_TypeDef *SPIx, uint16_t SPI_I2S_FLAG)
清除指定的 SPI 状态标志。

注意：OVR 和 MODF 标志需特殊清除序列，详见函数注释。

参数：

返回值：
无

SPI_I2S_GetITStatus

#

ITStatus SPI_I2S_GetITStatus(SPI_TypeDef *SPIx, uint8_t SPI_I2S_IT)
检查指定的 SPI 中断是否发生（中断标志 + 中断使能位）。

参数：

返回值：
ITStatus：SET（中断发生）或 RESET（未发生）

SPI_I2S_ClearITPendingBit

#

void SPI_I2S_ClearITPendingBit(SPI_TypeDef *SPIx, uint8_t SPI_I2S_IT)
清除指定的 SPI 中断挂起位。

注意：OVR、MODF、UDR 等中断需配合读取寄存器才能清除，详见注释。

参数：

返回值：
无