stm32g4xx_hal_spi.c

转到此文件的文档。

/**
  ******************************************************************************
  * @file    stm32g4xx_hal_spi.c
  * @author  MCD Application Team
  * @brief   SPI HAL模块驱动程序。
  *          此文件提供固件函数，用于管理串行外设接口 (SPI) 外设的以下功能：
  *           + 初始化和反初始化函数
  *           + IO操作函数
  *           + 外设控制函数
  *           + 外设状态函数
  ******************************************************************************
  * @attention
  *
  * 版权所有 (c) 2019 STMicroelectronics。
  * 保留所有权利。
  *
  * 本软件受可在本软件组件根目录下的 LICENSE 文件中找到的条款约束。
  * 如果本软件未附带 LICENSE 文件，则按原样提供。
  *
  ******************************************************************************
  @verbatim
  ==============================================================================
                        ##### 如何使用此驱动程序 #####
  ==============================================================================
    [..]
      SPI HAL驱动程序可按如下方式使用：

      (#) 声明一个 SPI_HandleTypeDef 句柄结构体，例如：
          SPI_HandleTypeDef  hspi;

      (#) 通过实现 HAL_SPI_MspInit() API 来初始化 SPI 底层资源：
          (##) 使能 SPIx 接口时钟
          (##) SPI 引脚配置
              (+++) 使能 SPI GPIO 的时钟
              (+++) 将这些 SPI 引脚配置为复用功能推挽输出
          (##) 如果需要使用中断处理，则进行 NVIC 配置
              (+++) 配置 SPIx 中断优先级
              (+++) 使能 NVIC SPI IRQ 处理
          (##) 如果需要使用 DMA 处理，则进行 DMA 配置
              (+++) 为发送或接收流/通道声明一个 DMA_HandleTypeDef 句柄结构体
              (+++) 使能 DMAx 时钟
              (+++) 配置 DMA 句柄参数
              (+++) 配置 DMA Tx 或 Rx 流/通道
              (+++) 将初始化好的 hdma_tx（或 _rx）句柄关联到 hspi DMA Tx 或 Rx 句柄
              (+++) 配置 DMA Tx 或 Rx 流/通道的传输完成中断的优先级并使能 NVIC

      (#) 在 hspi Init 结构体中编程模式、双向模式、数据大小、波特率预分频器、NSS
          管理、时钟极性和相位、FirstBit 和 CRC 配置。

      (#) 通过调用 HAL_SPI_Init() API 来初始化 SPI 寄存器：
          (++) 此 API 还通过调用定制的 HAL_SPI_MspInit() API 来配置底层硬件 GPIO、CLOCK、CORTEX...等。
     [..]
       循环模式限制：
      (#) 当 SPI 配置为以下模式时，不能使用 DMA 循环模式：
          (##) 主机 2线 仅接收
          (##) 主机 1线 接收
      (#) 当使能 DMA 循环模式时，不管理 CRC 功能
      (#) 当使用 SPI DMA 暂停/停止功能时，必须仅在 SPI 回调函数中使用以下 API
          HAL_SPI_DMAPause()/ HAL_SPI_DMAStop()
     [..]
       主机接收模式限制：
      (#) 在主机单向仅接收模式 (MSTR =1, BIDIMODE=0, RXONLY=1) 或
          双向接收模式 (MSTR=1, BIDIMODE=1, BIDIOE=0) 下，为确保 SPI
          不启动新的传输，必须遵守以下步骤：
          (##) HAL_SPI_DeInit()
          (##) HAL_SPI_Init()
     [..]
       回调注册：

      (#) 编译标志 USE_HAL_SPI_REGISTER_CALLBACKS 设置为 1U 时，
          允许用户动态配置驱动程序回调。
          使用函数 HAL_SPI_RegisterCallback() 来注册中断回调。

          函数 HAL_SPI_RegisterCallback() 允许注册以下回调：
            (++) TxCpltCallback        : SPI 发送完成回调
            (++) RxCpltCallback        : SPI 接收完成回调
            (++) TxRxCpltCallback      : SPI 发送接收完成回调
            (++) TxHalfCpltCallback    : SPI 发送半完成回调
            (++) RxHalfCpltCallback    : SPI 接收半完成回调
            (++) TxRxHalfCpltCallback  : SPI 发送接收半完成回调
            (++) ErrorCallback         : SPI 错误回调
            (++) AbortCpltCallback     : SPI 中止完成回调
            (++) MspInitCallback       : SPI Msp 初始化回调
            (++) MspDeInitCallback     : SPI Msp 反初始化回调
          此函数接受 HAL 外设句柄、回调 ID
          和指向用户回调函数的指针作为参数。


      (#) 使用函数 HAL_SPI_UnRegisterCallback 将回调重置为默认的
          弱函数。
          HAL_SPI_UnRegisterCallback 接受 HAL 外设句柄、
          和回调 ID 作为参数。
          此函数允许重置以下回调：
            (++) TxCpltCallback        : SPI 发送完成回调
            (++) RxCpltCallback        : SPI 接收完成回调
            (++) TxRxCpltCallback      : SPI 发送接收完成回调
            (++) TxHalfCpltCallback    : SPI 发送半完成回调
            (++) RxHalfCpltCallback    : SPI 接收半完成回调
            (++) TxRxHalfCpltCallback  : SPI 发送接收半完成回调
            (++) ErrorCallback         : SPI 错误回调
            (++) AbortCpltCallback     : SPI 中止完成回调
            (++) MspInitCallback       : SPI Msp 初始化回调
            (++) MspDeInitCallback     : SPI Msp 反初始化回调

       [..]
       默认情况下，在 HAL_SPI_Init() 之后且状态为 HAL_SPI_STATE_RESET 时，
       所有回调都设置为相应的弱函数：
       例如 HAL_SPI_MasterTxCpltCallback()、HAL_SPI_MasterRxCpltCallback()。
       MspInit 和 MspDeInit 函数的例外情况是，仅在这些回调为 null（未预先注册）时，
       才在 HAL_SPI_Init()/ HAL_SPI_DeInit() 中重置为传统的弱函数。
       如果 MspInit 或 MspDeInit 不为 null，则无论状态如何，
       HAL_SPI_Init()/ HAL_SPI_DeInit() 都会保留并使用用户 MspInit/MspDeInit 回调（预先注册）。

       [..]
       回调只能在 HAL_SPI_STATE_READY 状态下注册/注销。
       MspInit/MspDeInit 函数的例外情况是，可以在 HAL_SPI_STATE_READY 或 HAL_SPI_STATE_RESET 状态下注册/注销，
       因此注册的（用户）MspInit/DeInit 回调可以在初始化/反初始化期间使用。
       然后，用户首先使用 HAL_SPI_RegisterCallback() 注册 MspInit/MspDeInit 用户回调，
       然后再调用 HAL_SPI_DeInit() 或 HAL_SPI_Init() 函数。

       [..]
       当编译定义 USE_HAL_PPP_REGISTER_CALLBACKS 设置为 0 或
       未定义时，回调注册功能不可用，
       并使用弱（重载）回调。

     [..]
       使用 HAL 无法在不同 SPI 模式下达到所有支持的 SPI 频率，
       下表总结了在数据大小为 8 位/16 位时达到的最大 SPI 频率，
         取决于 SPI 实例使用的 APBx 外设时钟频率 (fPCLK)。

  @endverbatim

  附加表格：

       DataSize = SPI_DATASIZE_8BIT:
       +----------------------------------------------------------------------------------------------+
       |         |                | 2线全双工          |     2线仅接收       |         1线        |
       | 过程    | 传输模式       |---------------------|----------------------|----------------------|
       |         |                |  主机   |  从机   |  主机    |  从机   |  主机    |  从机   |
       |==============================================================================================|
       |    T    |     轮询       | Fpclk/4  | Fpclk/8  |    NA     |    NA    |    NA     |   NA     |
       |    X    |----------------|----------|----------|-----------|----------|-----------|----------|
       |    /    |     中断       | Fpclk/4  | Fpclk/16 |    NA     |    NA    |    NA     |   NA     |
       |    R    |----------------|----------|----------|-----------|----------|-----------|----------|
       |    X    |       DMA      | Fpclk/2  | Fpclk/2  |    NA     |    NA    |    NA     |   NA     |
       |=========|================|==========|==========|===========|==========|===========|==========|
       |         |     轮询       | Fpclk/4  | Fpclk/8  | Fpclk/16  | Fpclk/8  | Fpclk/8   | Fpclk/8  |
       |         |----------------|----------|----------|-----------|----------|-----------|----------|
       |    R    |     中断       | Fpclk/8  | Fpclk/16 | Fpclk/8   | Fpclk/8  | Fpclk/8   | Fpclk/4  |
       |    X    |----------------|----------|----------|-----------|----------|-----------|----------|
       |         |       DMA      | Fpclk/4  | Fpclk/2  | Fpclk/2   | Fpclk/16 | Fpclk/2   | Fpclk/16 |
       |=========|================|==========|==========|===========|==========|===========|==========|
       |         |     轮询       | Fpclk/8  | Fpclk/2  |     NA    |    NA    | Fpclk/8   | Fpclk/8  |
       |         |----------------|----------|----------|-----------|----------|-----------|----------|
       |    T    |     中断       | Fpclk/2  | Fpclk/4  |     NA    |    NA    | Fpclk/16  | Fpclk/8  |
       |    X    |----------------|----------|----------|-----------|----------|-----------|----------|
       |         |       DMA      | Fpclk/2  | Fpclk/2  |     NA    |    NA    | Fpclk/8   | Fpclk/16 |
       +----------------------------------------------------------------------------------------------+

       DataSize = SPI_DATASIZE_16BIT:
       +----------------------------------------------------------------------------------------------+
       |         |                | 2线全双工          |     2线仅接收       |         1线        |
       | 过程    | 传输模式       |---------------------|----------------------|----------------------|
       |         |                |  主机   |  从机   |  主机    |  从机   |  主机    |  从机   |
       |==============================================================================================|
       |    T    |     轮询       | Fpclk/4  | Fpclk/8  |    NA     |    NA    |    NA     |   NA     |
       |    X    |----------------|----------|----------|-----------|----------|-----------|----------|
       |    /    |     中断       | Fpclk/4  | Fpclk/16 |    NA     |    NA    |    NA     |   NA     |
       |    R    |----------------|----------|----------|-----------|----------|-----------|----------|
       |    X    |       DMA      | Fpclk/2  | Fpclk/2  |    NA     |    NA    |    NA     |   NA     |