stm32g4xx_hal_fmac.c

跳转到此文件的文档。

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

      (#) 通过实现 HAL_FMAC_MspInit() 初始化 FMAC 底层资源：
          (++) 使用 __HAL_RCC_FMAC_CLK_ENABLE() 使能 FMAC 接口时钟。
          (++) 如果使用中断（例如，访问配置为 FMAC_BUFFER_ACCESS_IT）：
               (+++) 使用 HAL_NVIC_SetPriority() 配置 FMAC 中断优先级。
               (+++) 使用 HAL_NVIC_EnableIRQ() 使能 FMAC IRQ 处理程序。
               (+++) 在 FMAC IRQ 处理程序中，调用 HAL_FMAC_IRQHandler()。
          (++) 如果使用 DMA 控制数据传输（例如，访问配置为
               FMAC_BUFFER_ACCESS_DMA）：
               (+++) 使用 __HAL_RCC_DMA1_CLK_ENABLE() 或
                     __HAL_RCC_DMA2_CLK_ENABLE()（取决于使用的 DMA 实例）使能 DMA 接口时钟。
               (+++) 使用 __HAL_RCC_DMAMUX1_CLK_ENABLE() 使能 DMAMUX1 接口时钟。
               (+++) 如果内部缓冲区（系数、输入、输出）的初始化通过 DMA 完成，
                     则配置并使能一个 DMA 通道用于管理从内存到内存的数据传输（预加载通道）。
               (+++) 如果输入缓冲区通过 DMA 访问，则配置并使能一个
                     DMA 通道用于管理从内存到外设的数据传输（输入通道）。
               (+++) 如果输出缓冲区通过 DMA 访问，则配置并使能一个
                     DMA 通道用于管理从外设到内存的数据传输（输出通道）。
               (+++) 使用 __HAL_LINKDMA() 将初始化的 DMA 句柄关联到 FMAC DMA 句柄。
               (+++) 使用 HAL_NVIC_SetPriority() 和 HAL_NVIC_EnableIRQ() 配置优先级并使能
                     已使能 DMA 通道上的传输完成中断的 NVIC。

      (#) 使用 HAL_FMAC_Init() 初始化 FMAC HAL。此函数
          调用 HAL_FMAC_MspInit() 进行底层初始化。

      (#) 使用 HAL_FMAC_FilterConfig() 或 HAL_FMAC_FilterConfig_DMA()
          配置 FMAC 处理（滤波器）。
          此函数：
          (++) 定义 FMAC 内部内存中的内存区域
               （输入、系数、输出）以及关联的阈值（输入、输出）。
          (++) 配置滤波器及其参数：
               (+++) 有限脉冲响应（FIR）滤波器（也称为卷积）。
               (+++) 无限脉冲响应（IIR）滤波器（直接形式 1）。
          (++) 选择访问输入和输出缓冲区的方式：无、轮询、
               DMA、IT。"无"表示输入和/或输出数据将由
               另一个 IP（ADC、DAC 等）处理。
          (++) 如果输入访问和/或输出访问通过 IT/DMA 进行，
               则使能错误中断。如果发生错误，中断
               将在循环中触发。为了恢复，用户必须
               使用序列 HAL_FMAC_DeInit / HAL_FMAC_Init 重置 IP。
               或者，他也可以使用 __HAL_FMAC_DISABLE_IT 禁用中断；
               错误状态将被保留，但不会再触发中断。
          (++) 使用轮询模式（HAL_FMAC_FilterConfig()）或 DMA（HAL_FMAC_FilterConfig_DMA()）
               将提供的系数写入内部内存。
               在 DMA 情况下，当处理完成时调用 HAL_FMAC_FilterConfigCallback()。

       (#) 或者，用户可以通过调用 __HAL_FMAC_ENABLE_IT 使能与
           饱和相关的错误中断。这有助于调试滤波器。如果发生饱和，
           中断将在循环中触发。为了恢复，用户必须：
           (++) 如果用户希望继续，请调用 __HAL_FMAC_DISABLE_IT 禁用中断。
           (++) 使用序列 HAL_FMAC_DeInit / HAL_FMAC_Init 重置 IP。

       (#) 或者，使用 HAL_FMAC_FilterPreload() 或 HAL_FMAC_FilterPreload_DMA()
           预加载输入（FIR、IIR）和输出（IIR）数据。
           在 DMA 情况下，当处理完成时调用 HAL_FMAC_FilterPreloadCallback()。
           此步骤是可选的，因为滤波器可以在没有预加载数据的情况下启动。

       (#) 使用 HAL_FMAC_FilterStart() 启动 FMAC 处理（滤波器）。
           此函数还配置输出缓冲区，该缓冲区将从循环内部输出缓冲区填充。
           该函数立即返回，不会更新提供的缓冲区。IP 处理将保持活动状态，直到
           调用 HAL_FMAC_FilterStop()。

       (#) 如果输入内部缓冲区通过 DMA 访问，HAL_FMAC_HalfGetDataCallback()
           将被调用以指示输入缓冲区的一半已被处理。

       (#) 如果输入内部缓冲区通过 DMA 或中断访问，HAL_FMAC_GetDataCallback()
           将被调用以请求新的输入数据。如果 DMA 不在循环模式下，
           将通过 HAL_FMAC_AppendFilterData() 提供。

       (#) 如果输出内部缓冲区通过 DMA 访问，HAL_FMAC_HalfOutputDataReadyCallback()
           将被调用以指示输出缓冲区的一半已被处理。

       (#) 如果输出内部缓冲区通过 DMA 或中断访问，
           HAL_FMAC_OutputDataReadyCallback() 将被调用以请求新的输出
           缓冲区。如果 DMA 不在循环模式下，
           将通过 HAL_FMAC_ConfigFilterOutputBuffer() 提供。

       (#) 在除"无"以外的所有模式下，通过 HAL_FMAC_AppendFilterData() 提供要处理的新输入数据。
           此函数应仅在先前的输入数据已被处理后调用
           （预加载的输入数据不受影响）。

       (#) 在除"无"以外的所有模式下，通过
           HAL_FMAC_ConfigFilterOutputBuffer() 提供要填充的新输出缓冲区。此函数应仅在先前
           用户的输出缓冲区已被填充后调用。

       (#) 在轮询模式下，使用 HAL_FMAC_PollFilterData() 处理输入和输出数据。
           此函数：
           (++) 将用户的输入数据（通过 HAL_FMAC_AppendFilterData() 提供）
                写入 FMAC 输入内存区域。
           (++) 读取 FMAC 输出内存区域并将其写入用户的输出缓冲区。
           它将在以下情况下返回：
           (++) 用户的输出缓冲区已填满。
           (++) 用户的输入缓冲区已被处理。
           未使用的数据（未读取的输入数据或空闲输出数据）将不会被保存。
           用户必须使用更新后的输入和输出大小来跟踪它们。

       (#) 使用 HAL_FMAC_FilterStop() 停止 FMAC 处理（滤波器）。

       (#) 调用 HAL_FMAC_DeInit() 反初始化 FMAC 外设。此函数
           调用 HAL_FMAC_MspDeInit() 进行底层反初始化。

  ##### 回调注册 #####
  ==================================

    [..]
      编译定义 USE_HAL_FMAC_REGISTER_CALLBACKS 设置为 1 时
      允许用户动态配置驱动程序回调。

    [..]
      使用函数 HAL_FMAC_RegisterCallback() 注册用户回调。
      函数 HAL_FMAC_RegisterCallback() 允许注册以下回调：
      (+) ErrorCallback               : 错误回调。
      (+) HalfGetDataCallback         : 获取一半数据回调。
      (+) GetDataCallback             : 获取数据回调。
      (+) HalfOutputDataReadyCallback : 一半输出数据就绪回调。
      (+) OutputDataReadyCallback     : 输出数据就绪回调。
      (+) FilterConfigCallback        : 滤波器配置回调。
      (+) FilterPreloadCallback       : 滤波器预加载回调。
      (+) MspInitCallback             : FMAC MspInit。
      (+) MspDeInitCallback           : FMAC MspDeInit。
      此函数接受 HAL 外设句柄、回调 ID
      和指向用户回调函数的指针作为参数。

    [..]
      使用函数 HAL_FMAC_UnRegisterCallback() 将回调重置为默认
      弱函数。
      HAL_FMAC_UnRegisterCallback() 接受 HAL 外设句柄
      和回调 ID 作为参数。
      此函数允许重置以下回调：
      (+) ErrorCallback               : 错误回调。
      (+) HalfGetDataCallback         : 获取一半数据回调。
      (+) GetDataCallback             : 获取数据回调。
      (+) HalfOutputDataReadyCallback : 一半输出数据就绪回调。
      (+) OutputDataReadyCallback     : 输出数据就绪回调。
      (+) FilterConfigCallback        : 滤波器配置回调。
      (+) FilterPreloadCallback       : 滤波器预加载回调。
      (+) MspInitCallback             : FMAC MspInit。
      (+) MspDeInitCallback           : FMAC MspDeInit。

    [..]
      默认情况下，在 HAL_FMAC_Init() 之后，当状态为 HAL_FMAC_STATE_RESET
      时，所有回调都设置为相应的弱函数：
      例如 GetDataCallback()、OutputDataReadyCallback()。
      MspInit 和 MspDeInit 函数例外，它们分别
      仅在 HAL_FMAC_Init()
      和 HAL_FMAC_DeInit() 中当这些回调为 null（未预先注册）时重置为传统弱函数。
      如果不是，MspInit 或 MspDeInit 不为 null，HAL_FMAC_Init() 和 HAL_FMAC_DeInit()
      将保留并使用用户 MspInit/MspDeInit 回调（预先注册）。

    [..]
      回调只能在 HAL_FMAC_STATE_READY 状态下注册/注销。
      MspInit/MspDeInit 例外，可以在
      HAL_FMAC_STATE_READY 或 HAL_FMAC_STATE_RESET 状态下注册/注销，因此注册的（用户）
      MspInit/DeInit 回调可在 Init/DeInit 期间使用。
      在这种情况下，请先使用 HAL_FMAC_RegisterCallback() 注册 MspInit/MspDeInit 用户回调
      然后再调用 HAL_FMAC_DeInit