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:

• Up to 16 different concurrent configurations/channels
• 32 biquad filter stages (shared between all channels)
• Runtime filter configuration
• ECC error detection for coefficient and delay data
  • 1-bit error correction, 2-bit error detection

Configuration

Build Time Configurations for r_iirfa

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

Configuration	Options	Default	Description
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 Depth	Refer 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.

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_iirfa0	Module name.
Channel	Value must be an integer between 0 and 15	0	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:

• Either process more data at a time with R_IIRFA_Filter or only one sample at a time using R_IIRFA_SingleFilter
• Use the unrolled software loop option
  • Provide data in a multiple of the unroll depth
• Disable polling (see warning)

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

• A total of 32 stages may be configured at any one time across all channels.
• When polling is disabled core execution is halted while waiting for data to become available. (See warning)

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. */
    if (FSP_ERR_INVALID_RESULT == err)
    {
        /* 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_SUCCESS	The channel was successfully opened.
FSP_ERR_ASSERTION	One or both of the parameters was NULL.
FSP_ERR_IP_CHANNEL_NOT_PRESENT	An invalid channel was selected.
FSP_ERR_ALREADY_OPEN	The 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_SUCCESS	Data has been successfully filtered.
FSP_ERR_ASSERTION	One of the provided pointers is NULL.
FSP_ERR_NOT_OPEN	Instance is not open.
FSP_ERR_INVALID_ARGUMENT	num_samples is zero.
FSP_ERR_INVALID_RESULT	The result of one or more calculations was +/- infinity.
FSP_ERR_NOT_INITIALIZED	The filter is not configured.
FSP_ERR_IIRFA_ECC_1BIT	A 1-bit ECC error was detected.
FSP_ERR_IIRFA_ECC_2BIT	A 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_SUCCESS	Configuration successful.
FSP_ERR_ASSERTION	p_api_ctrl is NULL.
FSP_ERR_NOT_OPEN	Instance is not open.
FSP_ERR_INVALID_ARGUMENT	Invalid filter stage selection.
FSP_ERR_IN_USE	One 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_SUCCESS	Information read successfully.
FSP_ERR_ASSERTION	p_api_ctrl is NULL.
FSP_ERR_NOT_OPEN	Instance 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_SUCCESS	The channel is successfully closed.
FSP_ERR_ASSERTION	p_api_ctrl is NULL.
FSP_ERR_NOT_OPEN	Instance 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.