FIRUser

Overview

FIR filter which works together with the StateAllocator and CoeffAllocator modules

Discussion

This module implements a multi-channel FIR filter. It allows a different set of coefficients per channel, and is also useful in MIMO adaptive filtering applications. The module is a "user" type and works in conjuction with other "user" and "allocator" modules.

FIRUser has two operating modes: FIR mode and Group mode. FIR mode is a regular FIR operation where there is one channel of coefficients per each channel of state. Logically, the number of output channels is the same as in the coefficients and state. Group mode is useful in MIMO adaptive filtering scenarios. In this mode, there can be fewer state channels than coeff channels. The number of coeff channels must be a multiple of the number of state channels. Filtering is then done in groups: all state channels are filtered one-to-one against the first corresponding number of coeff channels. This would be the first group. All channel-group outputs are then summed (i.e. if blocksize is 1, only one scalar is obtained per group). Next, all state channels are filtered against the next group of coeff channels (non-overlapping) and summed. This is done until all coeff channels have been used. Since there is only one result per group, the number of output channels in this mode is equal to NUMCHANCOEFFS/NUMCHANSTATE.

S is the state input. It connects to a StateAllocator module. StateAllocator modules host (allocate) state data and provide a reference to its internal buffer through an "S" frame. StateAllocator must be configured to hold at least numTaps-1 delay samples. It must also be set to "deinterleave" mode and input is expected to be real numbers only.

C is the coefficients input. It connects to a CoeffAllocator module. CoeffAllocator modules host (allocate) coefficient data and provide a reference to its internal buffer through a "C" frame. The output (C) forwards the "C" frame which it receives on the input (as long as no errors are found). This can be useful for setting up sequential operations. The CoeffAllocator module must be configured to have numChanCoeffs channels and numTaps samples per channel. Coefficients must be stored in reverse order and only real number are expected. CoeffAllocators store the channels in non-interleaved format.

The first output of the module (not labeled) is the filter output.

The module will report an error in the errorCode variable (shown in inspector) if input frame values do not match expected ones. The reported error is the first one encountered, so there may be more. A list of possible errors is detailed further down. Filtering does not start until all inputs are deemed correct. To reduce error-checking overhead, the module will go into locked state and will only run full checking again if heap numbers or offsets change. When an error is found, the filter output is muted and the "C" frame offset value is set to 0 (output wire may contain other undefined values).

The argument NUMTAPS specifies the filter length. CoeffAllocator samples-per-channel must be set to this same value. Set this number to be a multiple of the internal memory alignment for a better chance at optimal performance.

The argument NUMCHANCOEFFS specifies the number of coefficient channels. CoeffAllocator numChannels must be set to this value.

The argument NUMCHANSTATE specifies the number of state channels. This must match the number of channels connected to the StateAllocator.

The argument BLOCKSIZE specifies the output blocksize. This must match the input blocksize of the StateAllocator.

The argument SAMPLERATE specifies the filter output sample rate (output C inherits sampe rate from input C).

The argument MEMHEAP specifies the heap to use for internal arrays. This includes a helper state array.

The argument FILTERMODE specifies the mode of operation.

In FIR_MODE, NUMCHANCOEFFS must equal NUMCHANSTATE. The number of output channels is set to match these values. In GROUP_MODE, NUMCHANCOEFFS must be a multiple of NUMCHANSTATE. The number of output channels is set to NUMCHANCOEFFS/NUMCHANSTATE.

Error list:
0: No error
-1: heap number out of range on input 1 (state)
-2: heap number out of range on input 2 (coeffs)
-11: heap does not exist on target, offset is zero or reported size too large for heap on input 1 (state)
-12: heap does not exist on target, offset is zero or reported size too large for heap on input 2 (coeffs)
-21: incorrect format on input 1 (state) - deinterleaving, complexity, number of channels or channel length
-22: incorrect format on input 2 (coeffs) - complexity, number of channels or channel length
Note: errors are checked and reported at run-time

See usage examples in the AllocatorUser_*.awd layouts found in the audioweaver/Examples/Module_Usage folder

Module Pack

Advanced

ClassID

classID = 1460

Type Definition

typedef struct _ModuleFIRUser
{
ModuleInstanceDescriptor instance;            // Common Audio Weaver module instance structure
INT32 numTaps;                                // Length of the filter.
INT32 blockSize;                              // Blocksize
INT32 numChanCoeffs;                          // Number of coeff channels
INT32 numChanState;                           // Number of state channels
INT32 numChanRatio;                           // Ratio of coeff channels to state channels.
INT32 errorCode;                              // Captures errors that could arise at run-time and is shown on the inspector
UINT32 pastOffsetCoeffs;                      // Keeps past received coeffs offset
UINT32 pastOffsetState;                       // Keeps past received state offset
UINT32 pastHeapCoeffs;                        // Keeps past received coeffs heap
UINT32 pastHeapState;                         // Keeps past received state heap
INT32 locked;                                 // Locks pointers and sizes safety checks.
INT32 invalidateCoeffs;                       // Flag to invalidate cache for coeffs.
INT32 invalidateState;                        // Flag to invalidate cache for state.
INT32 filterMode;                             // Sets mode of operation. See documentation for options.
INT32 chanLenLin;                             // Length of state per channel for internal linear buff.
INT32 arrayHeap;                              // Heap in which to allocate internal state.
FLOAT32* aLinState;                           // Linear state buffer
float * state;                                // Keeps past calculated pointer
float * coeffs;                               // Keeps past calculated pointer
} ModuleFIRUserClass;

Variables

Properties

Name	Type	Usage	isHidden	Default Value	Range
numTaps	int	const	0	20	Unrestricted
blockSize	int	const	0	8	Unrestricted
numChanCoeffs	int	const	0	1	Unrestricted
numChanState	int	const	0	1	Unrestricted
numChanRatio	int	derived	0	1	Unrestricted
errorCode	int	state	0	0	Unrestricted
pastOffsetCoeffs	uint	state	0	0	Unrestricted
pastOffsetState	uint	state	0	0	Unrestricted
pastHeapCoeffs	uint	state	0	0	Unrestricted
pastHeapState	uint	state	0	0	Unrestricted
locked	int	state	0	0	Unrestricted
invalidateCoeffs	int	state	0	0	Unrestricted
invalidateState	int	state	0	0	Unrestricted
filterMode	int	const	0	0	Unrestricted
chanLenLin	int	const	1	27	Unrestricted
arrayHeap	int	const	1	1	Unrestricted
aLinState	float*	state	0	[27 x 1]	Unrestricted
state	float *	state	1		Unrestricted
coeffs	float *	state	1		Unrestricted

Pins

Input Pins


Name	S
Description	StateAllocator frame input
Data type	int
Channel range	7
Block size range	1
Sample rate range	Unrestricted
Complex support	Real


Name	C
Description	CoeffAllocator frame input
Data type	int
Channel range	5
Block size range	1
Sample rate range	Unrestricted
Complex support	Real

Output Pins


Name	out
Description	audio output
Data Type	float


Name	C
Description	CoeffAllocator frame output
Data Type	int

Matlab Usage

File Name: fir_user_module.m 
 M = fir_user_module(NAME, NUMTAPS, NUMCHANCOEFFS, NUMCHANSTATE, BLOCKSIZE, SAMPLERATE, MEMHEAP, FILTERMODE) 
 Creates a multichannel FIR filter which can have a different set of 
 coefficients per channel. This "user" module works with  
 other "user" and "allocator" modules. 
 Arguments: 
    NAME - name of the module. 
    NUMTAPS - length of the filter (number of taps) 
              By default, NUMTAPS = 20. 
    NUMCHANCOEFFS - number of channels in coefficients buffer.   
              By default, NUMCHANCOEFFS = 1. 
    NUMCHANSTATE - number of channels in state buffer.   
              By default, NUMCHANSTATE = 1. 
    BLOCKSIZE - output block size (number of samples to generate). 
        If this is empty then we use the blockSize from the system 
        input.  By default, BLOCKSIZE = []. 
    SAMPLERATE - sample rate of the output data.  If this is empty 
        then we use the sample rate of the first input pin of the 
        containing system.  By default, SAMPLERATE = []. 
    MEMHEAP - heap which hosts internal arrays. This is a string and  
         follows the memory allocation enumeration in Framework.h.  
         Allowable values are: 
            'AWE_HEAP_FAST' - always use internal DM memory (default). 
            'AWE_HEAP_FASTB' - always use internal PM memory. 
            'AWE_HEAP_SLOW' - always use external memory. 
            'AWE_HEAP_FAST2SLOW' - try DM, PM or external in that order 
            'AWE_HEAP_FASTB2SLOW' - try PM or external in that order 
            'AWE_HEAP_SHARED' - always use shared memory. 
    FILTERMODE - working mode, possible values are: 
             0 - regular FIR mode, one state channel per coeff 
               channel (default). 
             1 - Group mode, can have fewer state channels than coeff 
               channels (num coeff channels must be exact multiple). 
               All state channels are filtered one-to-one against the 
               first corresponding coeff channels and all results are 
               summed, forming one output channel. State is then filtered 
               against the next coeff channel group and summed, forming 
               another output channel (and so on).