 |
RTEMS 6.1-rc1
|
|
RTEMS 6.1-rc1
|
FMAC HAL module driver. This file provides firmware functions to manage the following functionalities of the FMAC peripheral: More...
#include "stm32h7xx_hal.h"FMAC HAL module driver. This file provides firmware functions to manage the following functionalities of the FMAC peripheral:
Copyright (c) 2017 STMicroelectronics. All rights reserved.
This software is licensed under terms that can be found in the LICENSE file in the root directory of this software component. If no LICENSE file comes with this software, it is provided AS-IS.
================================================================================
##### How to use this driver #####
================================================================================
[..]
The FMAC HAL driver can be used as follows:
(#) Initialize the FMAC low level resources by implementing the HAL_FMAC_MspInit():
(++) Enable the FMAC interface clock using __HAL_RCC_FMAC_CLK_ENABLE().
(++) In case of using interrupts (e.g. access configured as FMAC_BUFFER_ACCESS_IT):
(+++) Configure the FMAC interrupt priority using HAL_NVIC_SetPriority().
(+++) Enable the FMAC IRQ handler using HAL_NVIC_EnableIRQ().
(+++) In FMAC IRQ handler, call HAL_FMAC_IRQHandler().
(++) In case of using DMA to control data transfer (e.g. access configured
as FMAC_BUFFER_ACCESS_DMA):
(+++) Enable the DMA interface clock using __HAL_RCC_DMA1_CLK_ENABLE()
or __HAL_RCC_DMA2_CLK_ENABLE() depending on the used DMA instance.
(+++) Enable the DMAMUX1 interface clock using __HAL_RCC_DMAMUX1_CLK_ENABLE().
(+++) If the initialization of the internal buffers (coefficients, input,
output) is done via DMA, configure and enable one DMA channel for
managing data transfer from memory to memory (preload channel).
(+++) If the input buffer is accessed via DMA, configure and enable one
DMA channel for managing data transfer from memory to peripheral
(input channel).
(+++) If the output buffer is accessed via DMA, configure and enable
one DMA channel for managing data transfer from peripheral to
memory (output channel).
(+++) Associate the initialized DMA handle(s) to the FMAC DMA handle(s)
using __HAL_LINKDMA().
(+++) Configure the priority and enable the NVIC for the transfer complete
interrupt on the enabled DMA channel(s) using HAL_NVIC_SetPriority()
and HAL_NVIC_EnableIRQ().
(#) Initialize the FMAC HAL using HAL_FMAC_Init(). This function
resorts to HAL_FMAC_MspInit() for low-level initialization.
(#) Configure the FMAC processing (filter) using HAL_FMAC_FilterConfig()
or HAL_FMAC_FilterConfig_DMA().
This function:
(++) Defines the memory area within the FMAC internal memory
(input, coefficients, output) and the associated threshold (input, output).
(++) Configures the filter and its parameters:
(+++) Finite Impulse Response (FIR) filter (also known as convolution).
(+++) Infinite Impulse Response (IIR) filter (direct form 1).
(++) Choose the way to access to the input and output buffers: none, polling,
DMA, IT. "none" means the input and/or output data will be handled by
another IP (ADC, DAC, etc.).
(++) Enable the error interruptions in the input access and/or the output
access is done through IT/DMA. If an error occurs, the interruption
will be triggered in loop. In order to recover, the user will have
to reset the IP with the sequence HAL_FMAC_DeInit / HAL_FMAC_Init.
Optionally, he can also disable the interrupt using __HAL_FMAC_DISABLE_IT;
the error status will be kept, but no more interrupt will be triggered.
(++) Write the provided coefficients into the internal memory using polling
mode ( HAL_FMAC_FilterConfig() ) or DMA ( HAL_FMAC_FilterConfig_DMA() ).
In the DMA case, HAL_FMAC_FilterConfigCallback() is called when
the handling is over.
(#) Optionally, the user can enable the error interruption related to
saturation by calling __HAL_FMAC_ENABLE_IT. This helps in debugging the
filter. If a saturation occurs, the interruption will be triggered in loop.
In order to recover, the user will have to:
(++) Disable the interruption by calling __HAL_FMAC_DISABLE_IT if
the user wishes to continue all the same.
(++) Reset the IP with the sequence HAL_FMAC_DeInit / HAL_FMAC_Init.
(#) Optionally, preload input (FIR, IIR) and output (IIR) data using
HAL_FMAC_FilterPreload() or HAL_FMAC_FilterPreload_DMA().
In the DMA case, HAL_FMAC_FilterPreloadCallback() is called when
the handling is over.
This step is optional as the filter can be started without preloaded
data.
(#) Start the FMAC processing (filter) using HAL_FMAC_FilterStart().
This function also configures the output buffer that will be filled from
the circular internal output buffer. The function returns immediately
without updating the provided buffer. The IP processing will be active until
HAL_FMAC_FilterStop() is called.
(#) If the input internal buffer is accessed via DMA, HAL_FMAC_HalfGetDataCallback()
will be called to indicate that half of the input buffer has been handled.
(#) If the input internal buffer is accessed via DMA or interrupt, HAL_FMAC_GetDataCallback()
will be called to require new input data. It will be provided through
HAL_FMAC_AppendFilterData() if the DMA isn't in circular mode.
(#) If the output internal buffer is accessed via DMA, HAL_FMAC_HalfOutputDataReadyCallback()
will be called to indicate that half of the output buffer has been handled.
(#) If the output internal buffer is accessed via DMA or interrupt,
HAL_FMAC_OutputDataReadyCallback() will be called to require a new output
buffer. It will be provided through HAL_FMAC_ConfigFilterOutputBuffer()
if the DMA isn't in circular mode.
(#) In all modes except none, provide new input data to be processed via HAL_FMAC_AppendFilterData().
This function should only be called once the previous input data has been handled
(the preloaded input data isn't concerned).
(#) In all modes except none, provide a new output buffer to be filled via
HAL_FMAC_ConfigFilterOutputBuffer(). This function should only be called once the previous
user's output buffer has been filled.
(#) In polling mode, handle the input and output data using HAL_FMAC_PollFilterData().
This function:
(++) Write the user's input data (provided via HAL_FMAC_AppendFilterData())
into the FMAC input memory area.
(++) Read the FMAC output memory area and write it into the user's output buffer.
It will return either when:
(++) the user's output buffer is filled.
(++) the user's input buffer has been handled.
The unused data (unread input data or free output data) will not be saved.
The user will have to use the updated input and output sizes to keep track
of them.
(#) Stop the FMAC processing (filter) using HAL_FMAC_FilterStop().
(#) Call HAL_FMAC_DeInit() to de-initialize the FMAC peripheral. This function
resorts to HAL_FMAC_MspDeInit() for low-level de-initialization.
##### Callback registration #####
==================================
[..]
The compilation define USE_HAL_FMAC_REGISTER_CALLBACKS when set to 1
allows the user to configure dynamically the driver callbacks.
[..]
Use Function HAL_FMAC_RegisterCallback() to register a user callback.
Function HAL_FMAC_RegisterCallback() allows to register following callbacks:
(+) ErrorCallback : Error Callback.
(+) HalfGetDataCallback : Get Half Data Callback.
(+) GetDataCallback : Get Data Callback.
(+) HalfOutputDataReadyCallback : Half Output Data Ready Callback.
(+) OutputDataReadyCallback : Output Data Ready Callback.
(+) FilterConfigCallback : Filter Configuration Callback.
(+) FilterPreloadCallback : Filter Preload Callback.
(+) MspInitCallback : FMAC MspInit.
(+) MspDeInitCallback : FMAC MspDeInit.
This function takes as parameters the HAL peripheral handle, the Callback ID
and a pointer to the user callback function.
[..]
Use function HAL_FMAC_UnRegisterCallback() to reset a callback to the default
weak (surcharged) function.
HAL_FMAC_UnRegisterCallback() takes as parameters the HAL peripheral handle
and the Callback ID.
This function allows to reset following callbacks:
(+) ErrorCallback : Error Callback.
(+) HalfGetDataCallback : Get Half Data Callback.
(+) GetDataCallback : Get Data Callback.
(+) HalfOutputDataReadyCallback : Half Output Data Ready Callback.
(+) OutputDataReadyCallback : Output Data Ready Callback.
(+) FilterConfigCallback : Filter Configuration Callback.
(+) FilterPreloadCallback : Filter Preload Callback.
(+) MspInitCallback : FMAC MspInit.
(+) MspDeInitCallback : FMAC MspDeInit.
[..]
By default, after the HAL_FMAC_Init() and when the state is HAL_FMAC_STATE_RESET
all callbacks are set to the corresponding weak (surcharged) functions:
examples GetDataCallback(), OutputDataReadyCallback().
Exception done for MspInit and MspDeInit functions that are respectively
reset to the legacy weak (surcharged) functions in the HAL_FMAC_Init()
and HAL_FMAC_DeInit() only when these callbacks are null (not registered beforehand).
If not, MspInit or MspDeInit are not null, the HAL_FMAC_Init() and HAL_FMAC_DeInit()
keep and use the user MspInit/MspDeInit callbacks (registered beforehand).
[..]
Callbacks can be registered/unregistered in HAL_FMAC_STATE_READY state only.
Exception done MspInit/MspDeInit that can be registered/unregistered
in HAL_FMAC_STATE_READY or HAL_FMAC_STATE_RESET state, thus registered (user)
MspInit/DeInit callbacks can be used during the Init/DeInit.
In that case first register the MspInit/MspDeInit user callbacks
using HAL_FMAC_RegisterCallback() before calling HAL_FMAC_DeInit()
or HAL_FMAC_Init() function.
[..]
When the compilation define USE_HAL_FMAC_REGISTER_CALLBACKS is set to 0 or
not defined, the callback registration feature is not available
and weak (surcharged) callbacks are used. 
1.9.4