DSP Filter Functions Help


Table of Contents

 

1    Fractional Filter Operations. 3

2    FIR and IIR Filter Implementations. 3

3    Single Sample Filtering. 4

4    User Considerations. 4

5    Functions. 4

5.1         FIRStruct 4

5.2         FIR. 6

5.3         FIRDecimate. 7

5.4         FIRDelayInit 8

5.5         FIRInterpolate. 8

5.6         FIRInterpDelayInit 10

5.7         FIRLattice. 10

5.8         FIRLMS. 11

5.9         FIRLMSNorm.. 13

5.10       FIRStructInit 14

5.11       IIRCanonic. 15

5.12       IIRCanonicInit 17

5.13       IIRLattice. 17

5.14       IIRLatticeInit 19

5.15       IIRTransposed. 20

5.16       IIRTransposedInit 21

5.17       OCTAVE model for analysis of IIRLattice filter 22

 


1          Fractional Filter Operations

 

Filtering the data sequence represented by fractional vector x[n] (0 £ n < N) is equivalent to solving the difference equation:

 

 

for every nth sample, which results into the filtered data sequence y[n]. In this sense, the fractional filter is characterized by the fractional vectors a[p] (0 £ p < P) and b[m] (0 £ m < M), referred to as the set of filter coefficients, which are designed to induce some pre-specified changes in the signal represented by the input data sequence.

 

When filtering it is important to know and manage the past history of the input and output data sequences (x[n], -M + 1 £ n < 0, and y[n], -P + 1 £ n < 0), which represent the initial conditions of the filtering operation. Also, when repeatedly applying the filter to contiguous sections of the input data sequence it is necessary to remember the final state of the last filtering operation (x[n], N – M + 1 £ n < N – 1, and y[n], N – P + 1 £ n < N – 1). This final state is then taken into consideration for the calculations of the next filtering stage. Accounting for the past history and current state is required in order to perform a correct filtering operation.

 

The management of the past history and current state of a filtering operation is commonly implemented via additional sequences (also fractional vectors), referred to as the filter delay line. Prior to applying the filter operation, the delay describes the past history of the filter. After performing the filtering operation, the delay contains a set of the most recently filtered data samples, and of the most recent output samples.

Note: To ensure correct operation of a particular filter implementation, it is advisable to initialize the delay values to zero by calling the corresponding initialization function.

 

In the filter implementations provided with the DSP Library the input data sequence is referred to as the sequence of source samples, while the resulting filtered sequence is called the destination samples. The filter coefficients (a,b) and delay are usually thought of as making up a filter structure. In all filter implementations, the input and output data samples may be allocated in default RAM memory space (X-Data or Y-Data). Filter coefficients may reside either in X-Data memory or program memory, and filter delay values must be accessed only from Y-Data.

 

2          FIR and IIR Filter Implementations

 

The properties of a filter depend on the value distribution of its coefficients. In particular, two types of filters are of special interest: Finite Impulse Response (FIR) filters, for which a[m] = 0 when 1 £ m < M, and Infinite Impulse Response (IIR) filters, those such that a[0] ¹ 0, and a[m] ¹ 0 for some m in {1, ..., M}. Other classifications within the FIR and IIR filter families account for the effects that the operation induces on input data sequences.

 

Furthermore, even though filtering consists on solving the difference equation stated above, several implementations are available which are more efficient than direct computation of the difference equation. Also, some other implementations are designed to execute the filtering operation under the constraints imposed by fractional arithmetic.

 

All these considerations lead to a proliferation of filtering operations, of which a subset is provided by the DSP Library.

 

3          Single Sample Filtering

 

The filtering functions provided in the DSP Library are designed for block processing. Each filter function accepts an argument named numSamps which indicates the number of words of input data (block size) to operate on. If single sample filtering is desired, you may set numSamps to 1. This will have the effect of filtering one input sample, and the function will compute a single output sample from the filter.

 

4          User Considerations

 

All the fractional filtering operations in this library rely on the values of either input parameters or data structure elements to specify the number of samples to process, and the sizes of the coefficients and delay vectors. Based on these values the following assumptions are made:

 

  1. The sum of sizes of all the vectors (sample sequences) involved in a particular operation falls within the range of available data memory for the target device.
  2. The destination vector must be large enough to accept the results of an operation.
  3. No boundary checking is performed by these functions. Out of range sizes (including zero length vectors) as well as nonconforming use of source vectors and coefficient sets may produce unexpected results.
  4. It is recommended that the STATUS Register (SR) is examined after completion of each function call. In particular, users can inspect the SA, SB and SAB flags after the function returns to determine if saturation occurred.
  5. Operations which return a destination vector can be nested, so that for instance if:
    a = Op1 (b, c), with b = Op2 (d), and c = Op3 (e, f), then
    a = Op1 (Op2 (d), Op3 (e, f))

 

5          Functions

 

In what follows, the individual functions implementing filtering operations are described. For further discussions on digital filters, please consult Alan Oppenheim and Ronald Schafer’s “Discrete-Time Signal Processing”, Prentice Hall, 1989. For implementation details of Least Mean Square FIR filters, please refer to T. Hsia’s “Convergence Analysis of LMS and NLMS Adaptive Algorithms”, Proc. ICASSP, pp. 667-670, 1983, as well as Sangil Park and Garth Hillman’s “On Acoustic-Echo Cancellation Implementation with Multiple Cascadable Adaptive FIR Filter Chips”, Proc. ICASSP, 1989.

 

5.1         FIRStruct

 

Structure:

FIRStruct describes the filter structure for any of the FIR filters.

Include:

dsp.h

Declaration:

typedef struct {

  int numCoeffs;

  fractional* coeffsBase;

  fractional* coeffsEnd;

  int coeffsPage;

  fractional* delayBase;

  fractional* delayEnd;

  fractional* delay;

} FIRStruct;

Parameters:

numCoeffs      number of coefficients in filter (also M)

coeffsBase    base address for filter coefficients (also h)

coeffsEnd      end address for filter coefficients

coeffsPage    coefficients buffer page number

delayBase      base address for delay buffer

delayEnd        end address for delay buffer

delay  current value of delay pointer (also d)

Remarks:

Number of coefficients in filter is M.

Coefficients, h[m], defined in 0 £ m < M, either within X-Data or program memory.

Delay buffer d[m], defined in 0 £ m < M, only in Y-Data.

If coefficients are stored in X-Data space, coeffsBase points to the actual address where coefficients are allocated. If coefficients are stored in program memory, coeffsBase is the offset from the program page boundary containing the coefficients to the address in the page where coefficients are allocated. This latter value can be calculated using the inline assembly operator psvoffset().

coeffsEnd is the address in X-Data space (or offset if in program memory) of the last byte of the filter coefficients buffer.

If coefficients are stored in X-Data space, coeffsPage must be set to 0xFF00 (defined value COEFFS_IN_DATA). If coefficients are stored in program memory, it is the program page number containing the coefficients. This latter value can be calculated using the inline assembly operator psvpage().

delayBase points to the actual address where the delay buffer is allocated.

delayEnd is the address of the last byte of the filter delay buffer.

When the coefficients and delay buffers are implemented as circular increasing modulo buffers, both coeffsBase and delayBase must be aligned to a ‘zero’ power of two address (coeffsEnd and delayEnd are odd addresses). Whether these buffers are implemented as circular increasing modulo buffers or not is indicated in the remarks section of each FIR filter function description.

When the coefficients and delay buffers are not implemented as circular (increasing) modulo buffers, coeffsBase and delayBase do not need to be aligned to a ‘zero’ power of two address, and the values of coeffsEnd and delayEnd are ignored within the particular FIR Filter function implementation.

5.2         FIR

 

Description:

FIR applies an FIR filter to the sequence of source samples, places the results in the sequence of destination samples, and updates the delay values.

Include:

dsp.h

Prototype:

extern fractional* FIR (

   int numSamps,

   fractional* dstSamps,

   fractional* srcSamps,

   FIRStruct* filter

);

Arguments:

numSamps        number of input samples to filter (also N)

dstSamps        pointer to destination samples (also y)

srcSamps        pointer to source samples (also x)

filter            pointer to FIRStruct filter structure

Return Value:

Pointer to base address of destination samples.

Remarks:

Number of coefficients in filter is M.

Coefficients, h[m], defined in 0 £ m < M, implemented as a circular increasing modulo buffer.

Delay, d[m], defined in 0 £ m < M, implemented as a circular increasing modulo buffer.

Source samples, x[n], defined in 0 £ n < N.

Destination samples, y[n], defined in 0 £ n < N.

(See also FIRStruct, FIRStructInit and FIRDelayInit.)

Source File:

fir.s

Function Profile:

System resources usage:

W0..W6            used, not restored

W8, W10          saved, used, restored

ACCA   used, not restored

CORCON          saved, used, restored

MODCON          saved, used, restored

XMODSTRT       saved, used, restored

XMODEND        saved, used, restored

YMODSTRT      saved, used, restored

PSVPAG          saved, used, restored (only if coefficients in P memory)

 

DO and REPEAT instruction usage:

1 level DO instructions

1 level REPEAT instructions

 

Program words (24-bit instructions):

55

 

Cycles (including C-function call and return overheads):

53 + N(4+M), or

56 + N(8+M) if coefficients in P memory.

Example:

Please refer to the MPLAB C30 installation folder for a sample project demonstrating the use of this function.

5.3         FIRDecimate

 

Description:

FIRDecimate decimates the sequence of source samples at a rate of R to 1; or equivalently, it downsamples the signal by a factor of R. Effectively,

y[n] = x[Rn].

To diminish the effect of aliasing, the source samples are first filtered and then downsampled. The decimated results are stored in the sequence of destination samples, and the delay values updated.

Include:

dsp.h

Prototype:

extern fractional* FIRDecimate (

   int numSamps,

   fractional* dstSamps,

   fractional* srcSamps,

   FIRStruct* filter,

   int rate

);

Arguments:

numSamps        number of output samples (also N, N = Rp, p integer)

dstSamp          pointer to destination samples (also y)

srcSamps        pointer to source samples (also x)

filter            pointer to FIRStruct filter structure

rate    rate of decimation (downsampling factor, also R)

Return Value:

Pointer to base address of destination samples.

Remarks:

Number of coefficients in filter is M, with M an integer multiple of R.

Coefficients, h[m], defined in 0 £ m < M, not implemented as a circular modulo buffer.

Delay, d[m], defined in 0 £ m < M, not implemented as a circular modulo buffer.

Source samples, x[n], defined in 0 £ n < NR.

Destination samples, y[n], defined in 0 £ n < N.

(See also FIRStruct, FIRStructInit, and FIRDelayInit.)

Source File:

firdecim.s

Function Profile:

System resources usage:

W0..W7            used, not restored

W8..W12          saved, used, restored

ACCA   used, not restored

CORCON          saved, used, restored

PSVPAG          saved, used, restored (only if

            coefficients in P memory)

 

DO and REPEAT instruction usage:

1 level DO instructions

1 level REPEAT instructions

 

Program words (24-bit instructions):

48

 

Cycles (including C-function call and return overheads):

45 + N(10 + 2M), or

48 + N(13 + 2M) if coefficients in P memory.

5.4         FIRDelayInit

 

Description:

FIRDelayInit initializes to zero the delay values in an FIRStruct filter structure.

Include:

dsp.h

Prototype:

extern void FIRDelayInit (

   FIRStruct* filter

);

Arguments:

filter            pointer to FIRStruct filter structure.

Return Value:

None.

Remarks:

See description of FIRStruct structure above.

Note: FIR interpolator's delay is initialized by function FIRInterpDelayInit.

Source File:

firdelay.s

Function Profile:

System resources usage:

W0..W2            used, not restored

 

DO and REPEAT instruction usage:

no DO instructions

1 level REPEAT instructions

 

Program words (24-bit instructions):

7

 

Cycles (including C-function call and return overheads):

11 + M

5.5         FIRInterpolate

 

Description:

FIRInterpolate interpolates the sequence of source samples at a rate of 1 to R; or equivalently, it upsamples the signal by a factor of R. Effectively, y[n] = x[n/R].

To diminish the effect of aliasing, the source samples are first upsampled and then filtered. The interpolated results are stored in the sequence of destination samples, and the delay values updated.

Include:

dsp.h

Prototype:

extern fractional* FIRInterpolate (

   int numSamps,

   fractional* dstSamps,

   fractional* srcSamps,

   FIRStruct* filter,

   int rate

);

Arguments:

numSamps        number of input samples (also N, N = Rp, p integer)

dstSamps        pointer to destination samples (also y)

srcSamps        pointer to source samples (also x)

filter            pointer to FIRStruct filter structure

rate    rate of interpolation (upsampling factor, also R)

Return Value:

Pointer to base address of destination samples.

Remarks:

Number of coefficients in filter is M, with M an integer multiple of R.

Coefficients, h[m], defined in 0 £ m < M, not implemented as a circular modulo buffer.

Delay, d[m], defined in 0 £ m < M/R, not implemented as a circular modulo buffer.

Source samples, x[n], defined in 0 £ n < N.

Destination samples, y[n], defined in 0 £ n < NR.

(See also FIRStruct, FIRStructInit, and FIRInterpDelayInit.)

Source File:

firinter.s

Function Profile:

System resources usage:

W0..W7            used, not restored

W8..W13          saved, used, restored

ACCA   used, not restored

CORCON          saved, used, restored

PSVPAG          saved, used, restored (only if coefficients in P memory)

 

DO and REPEAT instruction usage:

2 level DO instructions

1 level REPEAT instructions

 

Program words (24-bit instructions):

63

 

Cycles (including C-function call and return overheads):

45 + 6(M / R) + N(14 + M / R + 3M + 5R), or

48 + 6(M / R) + N(14 + M / R + 4M + 5R) if coefficients in P memory.

5.6         FIRInterpDelayInit

 

Description:

FIRInterpDelayInit initializes to zero the delay values in an FIRStruct filter structure, optimized for use with an FIR interpolating filter.

Include:

dsp.h

Prototype:

extern void FIRDelayInit (

   FIRStruct* filter,

   int rate

);

Arguments:

filter            pointer to FIRStruct filter structure

rate    rate of interpolation (upsampling factor, also R)

Return Value:

None.

Remarks:

Delay, d[m], defined in 0 £ m < M/R, with M the number of filter coefficients in the interpolator. See description of FIRStruct structure above.

Source File:

firintdl.s

Function Profile:

System resources usage:

W0..W4            used, not restored

 

DO and REPEAT instruction usage:

no DO instructions

1 level REPEAT instructions

 

Program words (24-bit instructions):

13

 

Cycles (including C-function call and return overheads):

10 + 7M/R

5.7         FIRLattice

 

Description:

FIRLattice uses a lattice structure implementation to apply an FIR filter to the sequence of source samples. It then places the results in the sequence of destination samples, and updates the delay values.

Include:

dsp.h

Prototype:

extern fractional* FIRLattice (

   int numSamps,

   fractional* dstSamps,

   fractional* srcSamps,

   FIRStruct* filter

);

Arguments:

numSamps        number of input samples to filter (also N)

dstSamps        pointer to destination samples (also y)

srcSamps        pointer to source samples (also x)

filter            pointer to FIRStruct filter structure

Return Value:

Pointer to base address of destination samples.

Remarks:

Number of coefficients in filter is M.

Lattice coefficients, k[m], defined in 0 £ m < M, not implemented as a circular modulo buffer.

Delay, d[m], defined in 0 £ m < M, not implemented as a circular modulo buffer.

Source samples, x[n], defined in 0 £ n < N.

Destination samples, y[n], defined in 0 £ n < N.

(See also FIRStruct, FIRStructInit and FIRDelayInit.)

Source File:

firlatt.s

Function Profile:

System resources usage:

W0..W7            used, not restored

W8..W12          saved, used, restored

ACCA   used, not restored

ACCB   used, not restored

CORCON          saved, used, restored

PSVPAG          saved, used, restored (only if coefficients in P memory)

 

DO and REPEAT instruction usage:

2 level DO instructions

no REPEAT instructions

 

Program words (24-bit instructions):

50

 

Cycles (including C-function call and return overheads):

41 + N(4 + 7M)

44 + N(4 + 8M) if coefficients in P memory

5.8         FIRLMS

 

Description:

FIRLMS applies an adaptive FIR filter to the sequence of source samples, stores the results in the sequence of destination samples, and updates the delay values.

The filter coefficients are also updated, at a sample-per-sample basis, using a Least Mean Square algorithm applied according to the values of the reference samples.

Include:

dsp.h

Prototype:

extern fractional* FIRLMS (

   int numSamps,

   fractional* dstSamps,

   fractional* srcSamps,

   FIRStruct* filter,

   fractional* refSamps,

   fractional muVal

);

Arguments:

numSamps        number of input samples (also N)

dstSamps        pointer to destination samples (also y)

srcSamps        pointer to source samples (also x)

filter            pointer to FIRStruct filter structure

refSamps        pointer to reference samples (also r)

muVal  adapting factor (also mu)

Return Value:

Pointer to base address of destination samples.

Remarks:

Number of coefficients in filter is M.

Coefficients, h[m], defined in 0 £ m < M, implemented as a circular increasing modulo buffer.

delay, d[m], defined in 0 £ m < M-1, implemented as a circular increasing modulo buffer.

Source samples, x[n], defined in 0 £ n < N.

Reference samples, r[n], defined in 0 £ n < N.

Destination samples, y[n], defined in 0 £ n < N.

Adaptation:

   h_m[n] = h_m[n – 1] + mu * (r[n] – y[n]) * x[n – m],

   for 0 £ n < N, 0 £ m < M.

The operation could result in saturation if the absolute value of (r[n] - y[n]) is greater than or equal to one.

Filter coefficients must not be allocated in program memory, because in that case their values could not be adapted. If filter coefficients are detected as allocated in program memory the function returns NULL.

(See also FIRStruct, FIRStructInit and FIRDelayInit.)

Source File:

firlms.s

Function Profile:

System resources usage:

W0..W7            used, not restored

W8..W12          saved, used, restored

ACCA   used, not restored

ACCB   used, not restored

CORCON          saved, used, restored

MODCON          saved, used, restored

XMODSTRT       saved, used, restored

XMODEND        saved, used, restored

YMODSTRT      saved, used, restored

 

DO and REPEAT instruction usage:

2 level DO instructions

1 level REPEAT instructions

 

Program words (24-bit instructions):

76

 

Cycles (including C-function call and return overheads):

61 + N(13 + 5M)

5.9         FIRLMSNorm

 

Description:

FIRLMSNorm applies an adaptive FIR filter to the sequence of source samples, stores the results in the sequence of destination samples, and updates the delay values.

The filter coefficients are also updated, at a sample-per-sample basis, using a Normalized Least Mean Square algorithm applied according to the values of the reference samples.

Include:

dsp.h

Prototype:

extern fractional* FIRLMSNorm (

   int numSamps,

   fractional* dstSamps,

   fractional* srcSamps,

   FIRStruct* filter,

   fractional* refSamps,

   fractional muVal,

   fractional* energyEstimate

);

Arguments:

numSamps        number of input samples (also N)

dstSamps        pointer to destination samples (also y)

srcSamps        pointer to source samples (also x)

filter            pointer to FIRStruct filter structure

refSamps        pointer to reference samples (also r)

muVal  adapting factor (also mu)

energyEstimate        estimated energy value for the last M input signal samples, with M the number of filter coefficients

Return Value:

Pointer to base address of destination samples.

Remarks:

Number of coefficients in filter is M.

Coefficients, h[m], defined in 0 £ m < M, implemented as a circular increasing modulo buffer.

delay, d[m], defined in 0 £ m < M, implemented as a circular increasing modulo buffer.

Source samples, x[n], defined in 0 £ n < N.

Reference samples, r[n], defined in 0 £ n < N.

Destination samples, y[n], defined in 0 £ n < N.

Adaptation:

   h_m[n] = h_m[n – 1] + nu[n] * (r[n] – y[n]) * x[n – m],

   for 0 £ n < N, 0 £ m < M,

   where nu[n] =  mu / (mu + E[n])

   with E[n]=E[n – 1] + (x[n])2 – (x[n – M + 1])2 an estimate of

   input signal energy.

On start up, energyEstimate should be initialized to the value of E[-1] (zero the first time the filter is invoked). Upon return, energyEstimate is updated to the value E[N – 1] (which may be used as the start up value for a subsequent function call if filtering an extension of the input signal).

The operation could result in saturation if the absolute value of (r[n] – y[n]) is greater than or equal to one.

Note: Another expression for the energy estimate is:

E[n] = (x[n])2 + (x[n – 1)2 + ... + (x[n – M + 2])2.

Thus, to avoid saturation while computing the estimate, the input sample values should be bound so that

, for 0 £ n < N.

Filter coefficients must not be allocated in program memory, because in that case their values could not be adapted. If filter coefficients are detected as allocated in program memory the function returns NULL.

(See also FIRStruct, FIRStructInit and FIRDelayInit.)

Source File:

firlmsn.s

Function Profile:

System resources usage:

W0..W7            used, not restored

W8..W13          saved, used, restored

ACCA   used, not restored

ACCB   used, not restored

CORCON          saved, used, restored

MODCON          saved, used, restored

XMODSTRT       saved, used, restored

XMODEND        saved, used, restored

YMODSTRT      saved, used, restored

 

DO and REPEAT instruction usage:

2 level DO instructions

1 level REPEAT instructions

 

Program words (24-bit instructions):

91

 

Cycles (including C-function call and return overheads):

66 + N(49 + 5M)

5.10     FIRStructInit

 

Description:

FIRStructInit initializes the values of the parameters in an FIRStruct FIR Filter structure.

Include:

dsp.h

Prototype:

extern void FIRStructInit (

  FIRStruct* filter,

  int numCoeffs,

  fractional* coeffsBase,

  int coeffsPage,

  fractional* delayBase

);

Arguments:

filter            pointer to FIRStruct filter structure

numCoeffs      number of coefficients in filter (also M)

coeffsBase    base address for filter coefficients (also h)

coeffsPage    coefficient buffer page number

delayBase      base address for delay buffer

Return Value:

None.

Remarks:

See description of FIRStruct structure above.

Upon completion, FIRStructInit initializes the coeffsEnd and delayEnd pointers accordingly. Also, delay is set equal to delayBase.

Source File:

firinit.s

Function Profile:

System resources usage:

W0..W5            used, not restored

 

DO and REPEAT instruction usage:

no DO instructions

no REPEAT instructions

 

Program words (24-bit instructions):

10

 

Cycles (including C-function call and return overheads):

19

5.11     IIRCanonic

 

Description:

IIRCanonic applies an IIR filter, using a cascade of canonic (direct form II) biquadratic sections, to the sequence of source samples. It places the results in the sequence of destination samples, and updates the delay values.

Include:

dsp.h

Prototype:

typedef struct {

  int numSectionsLess1;

  fractional* coeffsBase;

  int coeffsPage;

  fractional* delayBase;

  int initialGain;

  int finalShift;

} IIRCanonicStruct;

 

extern fractional* IIRCanonic (

   int numSamps,

   fractional* dstSamps,

   fractional* srcSamps,

   IIRCanonicStruct* filter

);

Arguments:

Filter structure:

numSectionsLess1    1 less than number of cascaded second order (biquadratic) sections (also S-1)

coeffsBase    pointer to filter coefficients (also {a, b}), either within X-Data or program memory

coeffsPage    coefficients buffer page number, or 0xFF00 (defined value COEFFS_IN_DATA) if coefficients in data space

delayBase      pointer to filter delay (also d), only in Y-Data

initialGain  initial gain value

finalShift    output scaling (shift left)

 

Filter Description:

numSamps        number of input samples to filter (also N)

dstSamps        pointer to destination samples (also y)

srcSamps        pointer to source samples (also x)

filter            pointer to IIRCanonicStruct filter structure

Return Value:

Pointer to base address of destination samples.

Remarks:

There are 5 coefficients per second order (biquadratic) sections arranged in the ordered set {a2[s], a1[s], b2[s], b1[s], b0[s]}, 0 £ s < S. Coefficient values should be generated with dsPICFD filter design package from Momentum Data Systems, Inc., or similar tool.

The delay is made up of two words of filter state per section {d1[s], d2[s]}, 0 £ s < S.

Source samples, x[n], defined in 0 £ n < N.

Destination samples, y[n], defined in 0 £ n < N.

Initial gain value is applied to each input sample prior to entering the filter structure.

The output scale is applied as a shift to the output of the filter structure prior to storing the result in the output sequence. It is used to restore the filter gain to 0 dB. Shift count may be zero; if not zero, it represents the number of bits to shift: negative indicates shift left, positive is shift right.

Source File:

iircan.s

Function Profile:

System resources usage:

W0..W7            used, not restored

W8..W11          saved, used, restored

ACCA   used, not restored

CORCON          saved, used, restored

PSVPAG          saved, used, restored

 

DO and REPEAT instruction usage:

2 level DO instructions

1 level REPEAT instructions

 

Program words (24-bit instructions):

42

 

Cycles (including C-function call and return overheads):

36 + N(8 + 7S), or

39 + N(9 + 12S) if coefficients in program memory.

5.12     IIRCanonicInit

 

Description:

IIRCanonicInit initializes to zero the delay values in an IIRCanonicStruct filter structure.

Include:

dsp.h

Prototype:

extern void IIRCanonicInit (

   IIRCanonicStruct* filter

);

Arguments:

Filter structure:

(See description of IIRCanonic function).

 

Initialization Description:

filter            pointer to IIRCanonicStruct filter structure

Return Value:

None.

Remarks:

Two words of filter state per second order section {d1[s], d2[s]},

0 £ s < S.

Source File:

iircan.s

Function Profile:

System resources usage:

W0, W1            used, not restored

 

DO and REPEAT instruction usage:

1 level DO instructions

no REPEAT instructions

 

Program words (24-bit instructions):

7

 

Cycles (including C-function call and return overheads):

10 + S2.

5.13     IIRLattice

 

Description:

IIRLattice uses a lattice structure implementation to apply an IIR filter to the sequence of source samples. It then places the results in the sequence of destination samples, and updates the delay values.

Include:

dsp.h

Prototype:

typedef struct {

  int order;

  fractional* kappaVals;

  fractional* gammaVals;

  int coeffsPage;

  fractional* delay;

} IIRLatticeStruct;

 

extern fractional* IIRLattice (

   int numSamps,

   fractional* dstSamps,

   fractional* srcSamps,

   IIRLatticeStruct* filter

);

Arguments:

Filter structure:

order  filter order (also M, M £ N; see FIRLattice for N)

kappaVals      base address for lattice coefficients (also k), either in X-Data or program memory

gammaVals      base address for ladder coefficients (also g), either in X-Data or program memory. If NULL, the function will implement an all-pole filter.

coeffsPage    coefficients buffer page number, or 0xFF00 (defined value COEFFS_IN_DATA) if coefficients in data space

delay  base address for delay (also d), only in Y-Data

 

Filter Description:

numSamps        number of input samples to filter (also N, N ³ M; see IIRLatticeStruct for M)

dstSamps        pointer to destination samples (also y)

srcSamps        pointer to source samples (also x)

filter            pointer to IIRLatticeStruct filter structure

Return Value:

Pointer to base address of destination samples.

Remarks:

Lattice coefficients, k[m], defined in 0 £ m £ M.

Ladder coefficients, g[m], defined in 0 £ m £ M (unless if implementing an all-pole filter).

Delay, d[m], defined in 0 £ m £ M.

Source samples, x[n], defined in 0 £ n < N.

Destination samples, y[n], defined in 0 £ n < N.

Note: The fractional implementation provided with this library is prone to saturation. Design and test the filter “off-line” using a floating-point implementation such as the OCTAVE model at the end of this section.

Then, the intermediate forward and backward values should be monitored during the floating-point execution in search for levels outside the [-1, 1) range. If any one of the intermediate values spans outside of that range, the maximum absolute value should be used to scale the input signal prior to applying the fractional filter in real-time; i.e., multiply the signal by the inverse of that maximum. This scaling should prevent the fractional implementation from saturating.

Source File:

iirlatt.s

Function Profile:

System resources usage:

W0..W7            used, not restored

W8..W13          saved, used, restored

ACCA   used, not restored

ACCB   used, not restored

CORCON          saved, used, restored

 

DO and REPEAT instruction usage:

2 level DO instructions

no REPEAT instructions

 

Program words (24-bit instructions):

76

 

Cycles (including C-function call and return overheads):

46 + N(16 + 7M), or

49 + N(20 + 8M) if coefficients in program memory.

 

If implementing an all-pole filter:

46 + N(16 + 6M), or

49 + N(16 + 7M) if coefficients in program memory

5.14     IIRLatticeInit

 

Description:

IIRLatticeInit initializes to zero the delay values in an IIRLatticeStruct filter structure.

Include:

dsp.h

Prototype:

extern void IIRLatticeInit (

   IIRLatticeStruct* filter

);

Arguments:

Filter structure:

(See description of IIRLattice function).

 

Initialization Description:

filter            pointer to IIRLatticeStruct filter structure.

Return Value:

None.

Remarks:

None.

Source File:

iirlattd.s

Function Profile:

System resources usage:

W0..W2            used, not restored

 

DO and REPEAT instruction usage:

no DO instructions

1 level REPEAT instructions

 

Program words (24-bit instructions):

6

 

Cycles (including C-function call and return overheads):

10 + M

5.15     IIRTransposed

 

Description:

IIRTransposed applies an IIR filter, using a cascade of transposed (direct form II) biquadratic sections, to the sequence of source samples. It places the results in the sequence of destination samples, and updates the delay values.

Include:

dsp.h

Prototype:

typedef struct {

  int numSectionsLess1;

  fractional* coeffsBase;

  int coeffsPage;

  fractional* delayBase1;

  fractional* delayBase2;

  int finalShift;

} IIRTransposedStruct;

 

extern fractional* IIRTransposed (

   int numSamps,

   fractional* dstSamps,

   fractional* srcSamps,

   IIRTransposedStruct* filter

);

Arguments:

Filter structure:

numSectionsLess1    1 less than number of cascaded second order (biquadratic) sections (also S-1)

coeffsBase    pointer to filter coefficients (also {a, b}), either in X-Data or program memory

coeffsPage    coefficient buffer page number, or 0xFF00 (defined value COEFFS_IN_DATA) if coefficients in data space

delayBase1    pointer to filter state 1, with one word of delay per second order section (also d1), only in Y-Data

delayBase2    pointer to filter state 2, with one word of delay per second order section (also d2), only in Y-Data

finalShift    output scaling (shift left)

 

Filter Description:

numSamps        number of input samples to filter (also N)

dstSamps        pointer to destination samples (also y)

srcSamps        pointer to source samples (also x)

filter            pointer to IIRTransposedStruct filter structure

Return Value:

Pointer to base address of destination samples.

Remarks:

There are 5 coefficients per second order (biquadratic) section arranged in the ordered set {b0[s], b1[s], a1[s], b2[s],a2[s]}, 0 £ s < S. Coefficient values should be generated with dsPICFD filter design package from Momentum Data Systems, Inc., or similar tool.

The delay is made up of two independent buffers, each buffer containing one word of filter state per section {d2[s], d1[s]}, 0 £ s < S.

Source samples, x[n], defined in 0 £ n < N.

Destination samples, y[n], defined in 0 £ n < N.

The output scale is applied as a shift to the output of the filter structure prior to storing the result in the output sequence. It is used to restore the filter gain to 0 dB. Shift count may be zero; if not zero, it represents the number of bits to shift: negative indicates shift left, positive is shift right.

Source File:

iirtrans.s

Function Profile:

System resources usage:

W0..W7            used, not restored

W8..W11          saved, used, restored

ACCA   used, not restored

ACCB   used, not restored

CORCON          saved, used, restored

PSVPAG          saved, used, restored

 

DO and REPEAT instruction usage:

2 level DO instructions

1 level REPEAT instructions

 

Program words (24-bit instructions):

48

 

Cycles (including C-function call and return overheads):

35 + N(11 + 11S), or

38 + N(9 + 17S) if coefficients in P memory.

S is number of second order sections.

Example:

Please refer to the MPLAB C30 installation folder for a sample project demonstrating the use of this function.

5.16     IIRTransposedInit

 

Description:

IIRTransposedInit initializes to zero the delay values in an

IIRTransposedStruct filter structure.

Include:

dsp.h

Prototype:

extern void IIRTransposedInit (

   IIRTransposedStruct* filter

);

Arguments:

Filter structure:

(See description of IIRTransposed function).

 

Initialization Description:

filter            pointer to IIRTransposedStruct filter structure.

Return Value:

None.

Remarks:

The delay is made up of two independent buffers, each buffer containing one word of filter state per section {d2[s], d1[s]}, 0 £ s < S.

Source File:

iirtrans.s

Function Profile:

System resources usage:

W0..W2            used, not restored

 

DO and REPEAT instruction usage:

1 level DO instructions

no REPEAT instructions

 

Program words (24-bit instructions):

8

 

Cycles (including C-function call and return overheads):

11 + 2S,

S is number of second order sections.

Example:

Please refer to the MPLAB C30 installation folder for a sample project demonstrating the use of this function.

5.17     OCTAVE model for analysis of IIRLattice filter

 

The following OCTAVE model may be used to examine the performance of an IIR Lattice Filter prior to using the fractional implementation provided by the function IIRLattice.

 

IIRLattice OCTAVE model

 

function [out, del, forward, backward] = iirlatt (in, kappas, gammas, delay)

## FUNCTION.-

## IIRLATT: IIR Fileter Lattice implementation.

##

##       [out, del, forward, backward] = iirlatt (in, kappas, gammas, delay)

##

##       forward: records intermediate forward values.

##       backward: records intermediate backward values.

 

#..............................................................................

 

## Get implicit parameters.

numSamps = length(in); numKapps = length(kappas);

if (gammas != 0)

   numGamms = length(gammas);

else

   numGamms = 0;

endif

numDels = length(delay); filtOrder = numDels-1;

 

## Error check.

if (numGamms != 0)

   if (numGamms != numKapps)

      fprintf ("ERROR! %d should be equal to %d.\n", numGamms, numKapps);

      return;

   endif

endif

if (numDels != numKapps)

   fprintf ("ERROR! %d should equal to %d.\n", numDels, numKapps);

   return;

endif

 

## Initialize.

M = filtOrder; out = zeros(numSamps,1); del = delay;

forward = zeros(numSamps*M,1); backward = forward; i = 0;

 

## Filter samples.

for n = 1:numSamps

   ## Get new sample.

   current = in(n);

 

   ## Lattice structure.

   for m = 1:M

      after     = current  - kappas(M+1-m) * del(m+1);

      del(m)    = del(m+1) + kappas(M+1-m) * after;

      i = i+1;

      forward(i) = current;

      backward(i) = after;

      current   = after;

   end

   del(M+1) = after;

 

   ## Ladder structure (computes output).

   if (gammas == 0)

      out(n) = del(M+1);

   else

      for m = 1:M+1

         out(n) = out(n) + gammas(M+2-m)*del(m);

      endfor

   endif

endfor

 

## Return.

return;

 

#..............................................................................

 

endfunction