Filter 3p3z

General Description

Overview

This block implements a 3-pole 3-zero (3p3z) digital filter, commonly used as a compensator in power converter control loops. The 3p3z structure provides three poles and three zeros, enabling flexible shaping of the loop transfer function to achieve desired stability margins and transient response characteristics.

The block supports two filter architectures:

• Direct Form 1 (DF1): Used by the DF1-Q23 software variant and the hardware-accelerated (HW) variant. DF1 maintains separate delay lines for the input ( \(x\)) and output ( \(y\)) histories, and includes the full fixed-point signal processing chain (input gain, coefficient scaling, output gain, output offset, and output limiting) to match the HWFILTER3P3Z peripheral on PSoC Control MCUs.
• Direct Form 2 (DF2): Used by the DF2-F32 software variant. DF2 uses a single shared delay line, reducing memory usage. This variant operates in single-precision floating-point arithmetic, simplifying coefficient design and adding support for back-calculation anti-windup on the output limiter.

The general 3p3z transfer function implemented by all variants is:

\( H(z) = \frac{cx_0 + cx_1 z^{-1} + cx_2 z^{-2} + cx_3 z^{-3}} {1 - cy_1 z^{-1} - cy_2 z^{-2} - cy_3 z^{-3}} \)

The Direct Form 1 and the hardware-accelerated variants share the same top-level API (Filter3p3zReset, Filter3p3zInit, * Filter3p3z), allowing seamless switching between software and hardware implementations without application code changes. The Direct Form 2 variant deviates from this API for the data types (single-precision floating-point).

Configurable features

The filter provides the following configurable features. Note that the available parameters depend on the selected variant.

Parameter	Name	DF1-Q23 / HW	DF2-F32	Description
Filter input	dIn0/dIn1	Q0.15	float32	The input of the filter is the difference of \(dIn0-dIn1\).
Filter output	dOut	Q0.23	float32	The output of the filter, returned by reference.
Filter coefficients	cx/cy	Q0.23	float32	Arrays \([cx_0, cx_1, cx_2, cx_3]\) and \([cy_1, cy_2, cy_3]\).
Input gain	gIn	Yes (0..3)	N/A	Left shift by 0..3 applied to the input difference. DF1-Q23 and HW variants only.
Coefficient scaling	scaleCx/scaleCy	Yes (0..7)	N/A	Left shift by 0..7 applied to accumulated cx/cy branches. DF1-Q23 and HW variants only.
Output gain	gOut	Yes (0..7)	N/A	Right shift by 0..7 applied to the filter output. DF1-Q23 and HW variants only.
Output offset	dOutOffset	Yes (Q0.23)	N/A	Constant value added to the output after gain. DF1-Q23 and HW variants only.
Output limiter	limMin/limMax	Yes (Q0.23)	Yes (float32, as min/max)	Output clamping limits.
Anti-windup	anti-windup_gain	N/A	Yes (float32)	Back-calculation anti-windup gain applied to the DF2 delay element when output is clamped. DF2-F32 variant only.

Using the API

The application must allocate the context structure (filter_3p3z_context_t) in a memory section of choice. It must set the values of the configuration sub-structure (filter_3p3z_context_t::config). The static sub-structure (filter_3p3z_context_t::vars) contains the static memory the block needs to operate. It must not be initialized by the application. The application has to call the block reset function (Filter3p3zReset) to clear the static sub-structure and the block init function (Filter3p3zInit) to initialize the internal configuration.

Variants and configuration options

This section describes the available variants and configuration options. The Direct Form 1 and the hardware-accelerated variants share the same API so that changing the block interface does not require further changes to the application code when switching between the variants. The Direct Form 2 variant deviates from this API for the data types (single-precision floating-point).

Macro name	Macro purpose
FILTER_3P3Z_USE_VARIANT_DF1_Q23	Use the DF1-Q23 software variant of the filter_3p3z (default)
FILTER_3P3Z_USE_VARIANT_DF2_F32	Use the DF2-F32 software variant of the filter_3p3z
FILTER_3P3Z_USE_VARIANT_HW	Use the hardware-accelerated variant of the filter_3p3z (using HWFILTER peripheral from HW_PPCA)
FILTER_3P3Z_USE_VARIANT_DF1_Q23_HW_PPCA_BEHAVIOR	Emulate bit-true HW filter of HW_PPCA
FILTER_3P3Z_USE_INLINE	Use function inlining for the filter_3p3z

Software variants

The library provides two software variants that implement the 3p3z filter without hardware acceleration, suitable for simulation, portability, or when hardware resources are unavailable.

DF1-Q23 variant: This variant implements the 3p3z filter in Direct Form 1 using fixed-point Q23 arithmetic. The filter equation is

\(dOut[n] = \Big(cx_3 * x[n-3] + cx_2 * x[n-2] + cx_1 * x[n-1] + cx_0 * x[n]\Big) + \Big(cy_3 * y[n-3] + cy_2 * y[n-2] + cy_1 * y[n-1]\Big)\)

The filter works in the normalized range of +-1. The filter architecture is shown in the block diagram below:

It mimics the implementation of the PPCA HW 3P3Z FILTER IP block, retaining the same configuration parameters and data types. This enables three use cases:

• Switch the application to a target without HWFILTER
• Switch to a software implementation if the HW resource is used up
• Use the software variant for system simulation

Because this variant mirrors the hardware filter, it includes the full hardware signal processing chain: input gain (gIn), coefficient scaling (scaleCx/scaleCy), rounding and saturation, output gain (gOut), output offset (dOutOffset), and output limiting (limMin/limMax). These stages are specific to the fixed-point arithmetic used by the HWFILTER peripheral and are not applicable to the DF2-F32 variant. Anti-windup is not supported by this variant.

The DF1-Q23 software variant is selected by defining FILTER_3P3Z_USE_VARIANT_DF1_Q23 in the user config file. This is the default variant. Anti-windup feature is not supported by this variant.

DF2-F32 variant: This variant implements the 3p3z filter in Direct Form 2 using single-precision floating-point arithmetic. It is a simplified variant compared to DF1-Q23, as floating-point arithmetic eliminates the need for the fixed-point scaling stages (input gain, coefficient scaling, output gain, output offset) that are required by the DF1-Q23 and HW variants.

The DF2-F32 variant uses only the filter coefficients (cx, cy), output clamping limits (min, max), and an anti-windup gain. The anti-windup uses back-calculation: when the output is clamped, the excess is fed back into the DF2 delay element, scaled by the antiwindup_gain parameter, to prevent integrator windup.

This variant is suitable for microcontrollers with floating-point units when hardware acceleration is not available. It provides easier coefficient calculation since the coefficients are specified directly as float32 values without the need for fixed-point quantization.

The DF2-F32 software variant is selected by defining FILTER_3P3Z_USE_VARIANT_DF2_F32 in the user config file.

Performance optimization: To allow for an optimization of the execution time, the API functions can be inlined by defining FILTER_3P3Z_USE_INLINE in the user config file. The default is no function inlining.

The functional behavior of the DF1 Q23 variant is bit-accurate compared to the 3p3z hardware filter of PPCA HW FILTER as long as the internal data of the filter remains within the bit width of the hardware implementation. In case of an overflow, the hardware filter would show a change of the sign bit while the software variant would eventually be able to represent the number correctly because of its int32 operations. Additional masking of internal data would fully match the hardware behavior but is not used because it would affect the execution time. Optionally, full bit-accuracy can be enabled (e.g., for simulation purposes) by defining FILTER_3P3Z_USE_VARIANT_DF1_Q23_HW_PPCA_BEHAVIOR in the user config file.

Code snippet for using the filter_3p3z software variant
The user config file should contain the

#define FILTER_3P3Z_USE_VARIANT_DF1_Q23
#define FILTER_3P3Z_USE_INLINE

The filter configuration and execution is done by

// instantiate an instance of the filter context
filter_3p3z_context_t filter3p3z_context;
 
{
    // instantiate an instance of the filter context
    filter_3p3z_context_t filter3p3z_context =
    {
        // init the filter_3p3z context
        .config.cx_q23 = { 5563703, -5472912, -5563408, 5473207 },
        .config.cy_q23 = { 695249, 5929426, 1763933 },
        .config.dOutOffset_q23 = 838861,
        .config.limMax_q23 = 7130317,
        .config.limMin_q23 = 838861,
        .config.scaleCx = 7,
        .config.scaleCy = 0,
        .config.gIn = 0,
        .config.gOut = 0
    };
    // init and reset the filter context instance
    Filter3p3zInit(&filter3p3z_context);
    Filter3p3zReset(&filter3p3z_context);
 
    // get some input values
    int16_t din0 = 25600;
    int16_t din1 = 1082;
    int32_t dout;
 
    // execute filter function
    Filter3p3z(&filter3p3z_context, din0, din1, &dout);
}    

Hardware variant

If the compile target is PPCA HW, the 3p3z hardware filter can be used.

The hardware variant is selected by defining FILTER_3P3Z_USE_VARIANT_HW in the user config file. This variant also does not support the anti-windup feature. To allow for an optimization of the execution time, the API functions can be inlined by defining FILTER_3P3Z_USE_INLINE in the user config file. The default is no function inlining.

Code snippet for using the filter_3p3z hardware variant
The user config file should contain the

#define FILTER_3P3Z_USE_VARIANT_HW

Open the MTB Device Configurator and assign a HWFILT3P3Z block to the correct PPCA CPU in the PPCA configuration block (CNFG). Initialize the CNFG block before using the hardware filter:

// configure CNFG
Cy_PPCA_CNFG_Init(ppca_0_ppca_cnfg_0_HW, &ppca_0_ppca_cnfg_0_config);

Enable the hardware filter instance

// enable filter block
Cy_PPCA_HWFILT3P3Z_SS_PeripheralEnable((PPCA_HWFILT3P3Z_SS_Type*)PPCA_HWFILT3P3Z_SS_1);

The filter configuration and execution is done by

// instantiate an instance of the filter context
filter_3p3z_context_t filter3p3z_context;
 
{
    // instantiate an instance of the filter context
    filter_3p3z_context_t filter3p3z_context =
    {
        // init the filter_3p3z context
        .config.cx_q23 = { 5563703, -5472912, -5563408, 5473207 },
        .config.cy_q23 = { 695249, 5929426, 1763933 },
        .config.dOutOffset_q23 = 838861,
        .config.limMax_q23 = 7130317,
        .config.limMin_q23 = 838861,
        .config.scaleCx = 7,
        .config.scaleCy = 0,
        .config.gIn = 0,
        .config.gOut = 0,
        // provide the base address of the hardware filter instance in the configuration structure
        .vars.variant.base = (PPCA_HWFILT3P3Z_SS_HWFILT3P3Z_Type *)PPCA_HWFILT3P3Z_SS_0_HWFILT3P3Z0
    };
 
    // init and reset the filter context instance
    Filter3p3zInit(&filter3p3z_context);
    Filter3p3zReset(&filter3p3z_context);
 
    // get some input values
    int16_t din0 = 25600;
    int16_t din1 = 1082;
    int32_t dout;
 
    // execute filter function
    Filter3p3z(&filter3p3z_context, din0, din1, &dout);
}    

API Reference
	Macros and enumerated types
	Configuration macros for Filter 3p3z block.
	Typedefs and structures
	Context structure and sub-structures for the 3p3z filter block.
	Functions
	API functions for Filter 3p3z block.