RA Flexible Software Package Documentation  Release v5.2.0

 
IIR Filter Accelerator (r_iirfa)

Functions

fsp_err_t R_IIRFA_Open (iir_ctrl_t *const p_api_ctrl, iir_cfg_t const *const p_cfg)
 
fsp_err_t R_IIRFA_Filter (iir_ctrl_t *const p_api_ctrl, float const *p_data_in, float *p_data_out, uint16_t const num_samples)
 
fsp_err_t R_IIRFA_Configure (iir_ctrl_t *const p_api_ctrl, iir_filter_cfg_t const *const p_filter_cfg)
 
fsp_err_t R_IIRFA_StatusGet (iir_ctrl_t *const p_api_ctrl, iir_status_t *const p_status)
 
fsp_err_t R_IIRFA_Close (iir_ctrl_t *const p_api_ctrl)
 
__STATIC_INLINE float R_IIRFA_SingleFilter (iir_ctrl_t *const p_api_ctrl, float data_in)
 

Detailed Description

Driver for the IIRFA peripheral on RA MCUs. This module implements the IIR Interface.

Overview

The IIR Filter Accelerator (IIRFA) provides hardware acceleration for calculation of single-precision floating point direct form 2 biquad IIR filters. Up to 32 biquad stages can be configured at a time.

Features

The IIRFA module supports the following features:

Configuration

Build Time Configurations for r_iirfa

The following build time configurations are defined in fsp_cfg/r_iirfa_cfg.h:

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) If selected code for parameter checking is included in the build.
Polling Mode
  • Enabled
  • Disabled
Enabled When enabled the IIRFA driver will poll for completion before reading the output register. This prevents IIRFA operations from delaying global interrupt processing at the cost of slower filter performance.
Software Loop Unroll DepthRefer to the RA Configuration tool for available options.1 Sample Select the number of samples to process for every loop. This setting generally only affects filters that use 1 biquad stage.
ECC Support
  • Disabled
  • Enabled
  • Enabled (no writeback)
Enabled Select whether to detect ECC errors. When set to 'Enabled (no writeback)' 1-bit ECC errors will not be corrected.
Rounding Mode
  • Nearest
  • Toward zero
Nearest Select how to round calculation results.

Configurations for DSP > IIR Filter Accelerator (r_iirfa)

This module can be added to the Stacks tab via New Stack > DSP > IIR Filter Accelerator (r_iirfa). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_iirfa0 Module name.
ChannelValue must be an integer between 0 and 150 Select the IIRFA channel.

Clock Configuration

The clock source for the IIRFA peripheral is ICLK.

Pin Configuration

IIRFA does not have any pin connections.

Filter Configuration

Before using IIRFA to filter data the coefficients and state variables must be initialized. See the Filter Configuration example for how to initialize an iir_filter_cfg_t struct to pass to R_IIRFA_Configure.

Note
There are 32 total biquad stages in the peripheral shared across all channels. Channels may not select the same stages, so it is important to choose iir_filter_cfg_t::stage_base and iir_filter_cfg_t::stage_num carefully to ensure no overlap.

Usage Notes

Maximizing Performance

The optimum configuration for IIRFA is dependent on the application. It is recommended to consider the following in regards to your project to determine what settings may be ideal.

Regardless of configuration, each filter stage takes 2 ICLK cycles to process per sample and an additional 5 cycles to write state values back to registers. This means single-sample operations only take 2 cycles per stage while multi-sample operations take 7. Additional overhead cycles are required to load and store each sample. The following suggestions may improve performance:

Polling Mode

By default, the driver will poll a status flag for completion after writing input data to IIRFA. Disabling polling significantly improves performance when using a low number of stages, but may cause higher global interrupt latency during processing.

Note
If only one stage is used it is recommended to disable polling as IIRFA will typically execute faster than code resulting in no wait cycles. If polling must be used with a one stage filter, please note that in some situations the Arm CMSIS DSP Library functions arm_biquad_cascade_df2T_init_f32 and arm_biquad_cascade_df2T_f32 may provide better performance. It up to the user to evaluate performance within their own project.

Warning
When polling is disabled, filter operation works by writing a value to IIRCHnINP then immediately reading IIRCHnOUT. While this maximizes performance, the core will wait for output data to become available before continuing execution. While execution waits for IIRCHnOUT no interrupts will be processed by the core. The maximum wait time for a 32-stage filter may be up to approximately 64 ICLK cycles for single sample processing or 224 ICLK cycles for multi-sample processing (decreasing linearly with the number of stages used).

Single Sample Processing

In applications such as motor control where each sample needs immediate processing, the inline function R_IIRFA_SingleFilter is provided. This function has no parameter checking, takes one sample, and returns a filtered sample. Polling is supported by this function (if configured).

ECC Errors

If configured, R_IIRFA_Filter will return an error if a 1- or 2-bit ECC error has occurred.

1-bit errors are automatically corrected unless writeback is disabled. 2-bit errors cannot be automatically corrected. Reset the coefficient and filter data by calling R_IIRFA_Configure if a non-correctable ECC error is reported.

Limitations

Examples

Filter Configuration

Below is an example of how to initialize a filter configuration to pass to R_IIRFA_Configure.

#define FILTER_STAGE_NUM (2)
/* Biquad coefficients (4th order Butterworth 200Hz lowpass on 44.1KHz input) */
iir_filter_coeffs_t gp_iirfa0_filter_coeffs[FILTER_STAGE_NUM] =
{
{
.b0 = 1.000000000F,
.b1 = 2.000000000F,
.b2 = 1.000000000F,
.a1 = -1.947914029F,
.a2 = 0.948705125F,
},
{
.b0 = 1.000000000F,
.b1 = 2.000000000F,
.b2 = 1.000000000F,
.a1 = -1.977625722F,
.a2 = 0.978428884F,
},
};
/* Biquad state data (clear to start) */
iir_filter_state_t gp_iirfa0_filter_state[FILTER_STAGE_NUM] = {0};
/* Filter configuration */
iir_filter_cfg_t g_iirfa0_filter_cfg =
{
.p_filter_coeffs = gp_iirfa0_filter_coeffs, // Pointer to filter coefficient array
.p_filter_state = gp_iirfa0_filter_state, // Pointer to filter state data array
.stage_base = 0, // Which hardware biquad stage to start allocation from (0-31)
.stage_num = 2, // Number of stages to allocate
};

Software Example

The following is a basic example of configuring and using a filter with IIRFA.

#define NUM_SAMPLES (128)
#define TWO_PI (2.0F * (float) M_PI)
float gp_data_in[NUM_SAMPLES];
float gp_data_out[NUM_SAMPLES];
void iirfa_filter_example (void)
{
fsp_err_t err;
/* Initialize the IIRFA module */
err = R_IIRFA_Open(&g_iirfa0_ctrl, &g_iirfa0_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Initialize filter coefficients and state variables */
err = R_IIRFA_Configure(&g_iirfa0_ctrl, &g_iirfa0_filter_cfg);
assert(FSP_SUCCESS == err);
/* Get input data to be filtered */
get_input_data(gp_data_in);
/* Filter data */
err = R_IIRFA_Filter(&g_iirfa0_ctrl, gp_data_in, gp_data_out, NUM_SAMPLES);
/* R_IIRFA_Filter will return FSP_ERR_INVALID_RESULT when one or more calculations results in infinity. */
{
/* Handle error */
}
else
{
assert(FSP_SUCCESS == err);
}
}

Data Structures

struct  iirfa_instance_ctrl_t
 

Data Structure Documentation

◆ iirfa_instance_ctrl_t

struct iirfa_instance_ctrl_t

IIRFA instance control block.

Function Documentation

◆ R_IIRFA_Open()

fsp_err_t R_IIRFA_Open ( iir_ctrl_t *const  p_api_ctrl,
iir_cfg_t const *const  p_cfg 
)

Prepare an IIR channel for filtering.

Return values
FSP_SUCCESSThe channel was successfully opened.
FSP_ERR_ASSERTIONOne or both of the parameters was NULL.
FSP_ERR_IP_CHANNEL_NOT_PRESENTAn invalid channel was selected.
FSP_ERR_ALREADY_OPENThe instance is already opened.

◆ R_IIRFA_Filter()

fsp_err_t R_IIRFA_Filter ( iir_ctrl_t *const  p_api_ctrl,
float const *  p_data_in,
float *  p_data_out,
uint16_t const  num_samples 
)

Start a filter operation on the specified data.

Return values
FSP_SUCCESSData has been successfully filtered.
FSP_ERR_ASSERTIONOne of the provided pointers is NULL.
FSP_ERR_NOT_OPENInstance is not open.
FSP_ERR_INVALID_ARGUMENTnum_samples is zero.
FSP_ERR_INVALID_RESULTThe result of one or more calculations was +/- infinity.
FSP_ERR_NOT_INITIALIZEDThe filter is not configured.
FSP_ERR_IIRFA_ECC_1BITA 1-bit ECC error was detected.
FSP_ERR_IIRFA_ECC_2BITA 2-bit ECC error was detected.

◆ R_IIRFA_Configure()

fsp_err_t R_IIRFA_Configure ( iir_ctrl_t *const  p_api_ctrl,
iir_filter_cfg_t const *const  p_filter_cfg 
)

Configure filter coefficients and state values.

Return values
FSP_SUCCESSConfiguration successful.
FSP_ERR_ASSERTIONp_api_ctrl is NULL.
FSP_ERR_NOT_OPENInstance is not open.
FSP_ERR_INVALID_ARGUMENTInvalid filter stage selection.
FSP_ERR_IN_USEOne or more requested filter stages are currently in use.

◆ R_IIRFA_StatusGet()

fsp_err_t R_IIRFA_StatusGet ( iir_ctrl_t *const  p_api_ctrl,
iir_status_t *const  p_status 
)

Read the current filter state variables.

Return values
FSP_SUCCESSInformation read successfully.
FSP_ERR_ASSERTIONp_api_ctrl is NULL.
FSP_ERR_NOT_OPENInstance is not open.

◆ R_IIRFA_Close()

fsp_err_t R_IIRFA_Close ( iir_ctrl_t *const  p_api_ctrl)

Stop filter operations and close the channel instance.

Return values
FSP_SUCCESSThe channel is successfully closed.
FSP_ERR_ASSERTIONp_api_ctrl is NULL.
FSP_ERR_NOT_OPENInstance is not open.

◆ R_IIRFA_SingleFilter()

__STATIC_INLINE float R_IIRFA_SingleFilter ( iir_ctrl_t *const  p_api_ctrl,
float  data_in 
)

Perform a single inline filter operation.

Note
This function is intended to be used in performance-critical applications. As such, no parameter checking or error validation is provided.