stm32g4xx_hal_sai.c

转到此文件的文档。

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

  [..]
    SAI HAL 驱动程序可按如下方式使用：

    (#) 声明一个 SAI_HandleTypeDef 句柄结构体（例如 SAI_HandleTypeDef hsai）。
    (#) 通过实现 HAL_SAI_MspInit() API 来初始化 SAI 底层资源：
        (##) 使能 SAI 接口时钟。
        (##) SAI 引脚配置：
            (+++) 使能 SAI GPIO 的时钟。
            (+++) 将这些 SAI 引脚配置为复用功能上拉。
        (##) 如果需要使用中断处理（HAL_SAI_Transmit_IT()
             和 HAL_SAI_Receive_IT() API），则进行 NVIC 配置：
            (+++) 配置 SAI 中断优先级。
            (+++) 使能 NVIC SAI IRQ 句柄。

        (##) 如果需要使用 DMA 处理（HAL_SAI_Transmit_DMA()
             和 HAL_SAI_Receive_DMA() API），则进行 DMA 配置：
            (+++) 为 Tx/Rx 流声明一个 DMA 句柄结构体。
            (+++) 使能 DMAx 接口时钟。
            (+++) 使用所需的 Tx/Rx 参数配置已声明的 DMA 句柄结构体。
            (+++) 配置 DMA Tx/Rx 流。
            (+++) 将初始化的 DMA 句柄关联到 SAI DMA Tx/Rx 句柄。
            (+++) 配置优先级并使能 DMA Tx/Rx 流传输完成中断的 NVIC。

    (#) 初始化可以通过两种方式完成
        (##) 专家模式：初始化结构体 Init、FrameInit 和 SlotInit，然后调用 HAL_SAI_Init()。
        (##) 简化模式：初始化 Init 结构体的高位部分，然后调用 HAL_SAI_InitProtocol()。

  [..]
    (@) 特定的 SAI 中断（FIFO 请求和上溢/下溢中断）
        将在发送和接收过程中使用宏 __HAL_SAI_ENABLE_IT() 和 __HAL_SAI_DISABLE_IT() 进行管理。
  [..]
    (@) 确保已配置 SAI 时钟源：
        (+@) SYSCLK 或
        (+@) PLLQ 输出 或
        (+@) HSI 或
        (+@) 在 stm32g4xx_hal_conf.h 文件中正确设置常量 EXTERNAL_CLOCK_VALUE 后配置的外部时钟源。

  [..]
    (@) 在主机发送模式下：使能音频块会立即为外部从机生成位时钟，
        即使 FIFO 中没有数据，但是 FS 信号的生成取决于 FIFO 中是否存在数据。

  [..]
    (@) 在主机接收模式下：使能音频块会立即为外部从机生成位时钟和 FS 信号。

  [..]
    (@) 为避免 SAI 行为异常，必须遵守以下条件：
        (+@) 首位偏移 <= (时隙大小 - 数据大小)
        (+@) 数据大小 <= 时隙大小
        (+@) 时隙数 x 时隙大小 = 帧长度
        (+@) 当选择 SAI_FS_CHANNEL_IDENTIFICATION 时，时隙数应为偶数。

  [..]
    (@) PDM 接口可通过 HAL_SAI_Init 函数激活。
        请注意，PDM 接口仅适用于 SAI1 子块 A。
        PDM 麦克风延迟可通过 HAL_SAIEx_ConfigPdmMicDelay 函数进行调整。

  [..]
    此驱动程序中提供三种操作模式：

    *** 轮询模式 IO 操作 ***
    =================================
    [..]
      (+) 使用 HAL_SAI_Transmit() 在阻塞模式下发送一定量的数据
      (+) 使用 HAL_SAI_Receive() 在阻塞模式下接收一定量的数据

    *** 中断模式 IO 操作 ***
    ===================================
    [..]
      (+) 使用 HAL_SAI_Transmit_IT() 在非阻塞模式下发送一定量的数据
      (+) 传输结束时执行 HAL_SAI_TxCpltCallback()，用户可以通过
          自定义函数指针 HAL_SAI_TxCpltCallback() 添加自己的代码
      (+) 使用 HAL_SAI_Receive_IT() 在非阻塞模式下接收一定量的数据
      (+) 接收结束时执行 HAL_SAI_RxCpltCallback()，用户可以通过
          自定义函数指针 HAL_SAI_RxCpltCallback() 添加自己的代码
      (+) 如果发生标志错误，将执行 HAL_SAI_ErrorCallback() 函数，用户可以通过
          自定义函数指针 HAL_SAI_ErrorCallback() 添加自己的代码

    *** DMA 模式 IO 操作 ***
    =============================
    [..]
      (+) 使用 HAL_SAI_Transmit_DMA() 在非阻塞模式 (DMA) 下发送一定量的数据
      (+) 传输结束时执行 HAL_SAI_TxCpltCallback()，用户可以通过
          自定义函数指针 HAL_SAI_TxCpltCallback() 添加自己的代码
      (+) 使用 HAL_SAI_Receive_DMA() 在非阻塞模式 (DMA) 下接收一定量的数据
      (+) 接收结束时执行 HAL_SAI_RxCpltCallback()，用户可以通过
          自定义函数指针 HAL_SAI_RxCpltCallback() 添加自己的代码
      (+) 如果发生标志错误，将执行 HAL_SAI_ErrorCallback() 函数，用户可以通过
          自定义函数指针 HAL_SAI_ErrorCallback() 添加自己的代码
      (+) 使用 HAL_SAI_DMAPause() 暂停 DMA 传输
      (+) 使用 HAL_SAI_DMAResume() 恢复 DMA 传输
      (+) 使用 HAL_SAI_DMAStop() 停止 DMA 传输

    *** SAI HAL 驱动程序附加函数列表 ***
    ===============================================
    [..]
      以下是 SAI HAL 驱动程序可用的其他 API：

      (+) HAL_SAI_EnableTxMuteMode(): 在发送模式下使能静音
      (+) HAL_SAI_DisableTxMuteMode(): 在发送模式下禁用静音
      (+) HAL_SAI_EnableRxMuteMode(): 在接收模式下使能静音
      (+) HAL_SAI_DisableRxMuteMode(): 在接收模式下禁用静音
      (+) HAL_SAI_FlushRxFifo(): 刷新接收 FIFO。
      (+) HAL_SAI_Abort(): 中止当前传输

    *** SAI HAL 驱动程序宏列表 ***
    ==================================
    [..]
      以下是 SAI HAL 驱动程序中最常用的宏：

      (+) __HAL_SAI_ENABLE(): 使能 SAI 外设
      (+) __HAL_SAI_DISABLE(): 禁用 SAI 外设
      (+) __HAL_SAI_ENABLE_IT(): 使能指定的 SAI 中断
      (+) __HAL_SAI_DISABLE_IT(): 禁用指定的 SAI 中断
      (+) __HAL_SAI_GET_IT_SOURCE(): 检查指定的 SAI 中断源是否
          已使能或已禁用
      (+) __HAL_SAI_GET_FLAG(): 检查指定的 SAI 标志是否已设置

    *** 回调注册 ***
    =============================
    [..]
    编译定义 USE_HAL_SAI_REGISTER_CALLBACKS 设置为 1 时，
    允许用户动态配置驱动程序回调。
    使用函数 HAL_SAI_RegisterCallback() 注册用户回调。

    [..]
    函数 HAL_SAI_RegisterCallback() 允许注册以下回调：
      (+) RxCpltCallback     : SAI 接收完成。
      (+) RxHalfCpltCallback : SAI 接收半完成。
      (+) TxCpltCallback     : SAI 发送完成。
      (+) TxHalfCpltCallback : SAI 发送半完成。
      (+) ErrorCallback      : SAI 错误。
      (+) MspInitCallback    : SAI MspInit。
      (+) MspDeInitCallback  : SAI MspDeInit。
    [..]
    此函数接受 HAL 外设句柄、回调 ID
    和指向用户回调函数的指针作为参数。

    [..]
    使用函数 HAL_SAI_UnRegisterCallback() 将回调重置为默认
    弱函数。
    HAL_SAI_UnRegisterCallback() 接受 HAL 外设句柄
    和回调 ID 作为参数。
    [..]
    此函数允许重置以下回调：
      (+) RxCpltCallback     : SAI 接收完成。
      (+) RxHalfCpltCallback : SAI 接收半完成。
      (+) TxCpltCallback     : SAI 发送完成。
      (+) TxHalfCpltCallback : SAI 发送半完成。
      (+) ErrorCallback      : SAI 错误。
      (+) MspInitCallback    : SAI MspInit。
      (+) MspDeInitCallback  : SAI MspDeInit。

    [..]
    默认情况下，在 HAL_SAI_Init 之后，如果状态为 HAL_SAI_STATE_RESET，
    所有回调都将重置为相应的传统弱函数：
    例如 HAL_SAI_RxCpltCallback()、HAL_SAI_ErrorCallback()。
    MspInit 和 MspDeInit 回调是例外，它们分别在 HAL_SAI_Init