dsp.HDLCICDecimation

Decimate signal using cascaded integrator-comb filter — optimized for HDL code generation

Description

The dsp.HDLCICDecimation System object™ decimates an input signal by using a cascaded integrator-comb (CIC) decimation filter. CIC filters are a class of linear phase FIR filters consisting of a comb part and an integrator part. The CIC decimation filter structure consists of N sections of cascaded integrators, a rate change factor of R, and then N sections of cascaded comb filters. For more information about CIC decimation filters, see Algorithms.

The System object supports both fixed and variable decimation rates. It provides an architecture suitable for HDL code generation and hardware deployment.

The System object supports real and complex fixed-point inputs.

To filter input data with an HDL-optimized CIC decimation filter:

Create the dsp.HDLCICDecimation object and set its properties.
Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects? (MATLAB).

Creation

Syntax

cicDecFilt = dsp.HDLCICDecimation

cicDecFilt = dsp.HDLCICDecimation(Name,Value)

Description

cicDecFilt = dsp.HDLCICDecimation creates an HDL-optimized CIC decimation filter System object, cicDecFilt, with default properties.

example

cicDecFilt = dsp.HDLCICDecimation(Name,Value) creates the filter with properties set using one or more name-value pairs. Enclose each property name in single quotes.

Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects (MATLAB).

`VariableDownsample` — Variable decimation rate
`(0)` `false` (default) | `(1)` `true`

Set this property to true (1) to operate the System object with a variable decimation rate specified by the decimFactor input argument. Set this property to false (0) to operate the object with a fixed decimation rate, specified by the DecimationFactor property.

`DecimationFactor` — Decimation factor
`2` (default) | integer from 2 to 2048

Specify the decimation factor as an integer from 2 to 2048. This value represents the rate with which you want to decimate the input.

When you set the VariableDownsample property to true, set this property to the maximum-expected decimation rate.

`DifferentialDelay` — Differential delay
`1` (default) | `2`

Specify the differential delay of the comb part of the filter as either 1 or 2 cycles.

`NumSections` — Number of integrator or comb sections
`2` (default) | integer from 1 to 6

Specify the number of sections in either the integrator or the comb part of the filter as an integer from 1 to 6.

`OutputDataType` — Data type of output
`'Full precision'` (default) | `'Same word length as input'` | `'Minimum section word lengths'`

Choose the data type of the filtered output data.

'Full precision' — The output data type has a word length equal to the input word length plus gain bits.
'Same word length as input' — The output data type has a word length equal to the input word length.
'Minimum section word lengths' — The output data type uses the word length you specify in the OutputWordLength property. When you choose this option, the System object applies a pruning algorithm internally. For more information about pruning, see Output Data Type. This option is not supported when VariableDownsample is true.

`OutputWordLength` — Word length of output
`16` (default) | integer from 2 to 104

Word length of the output, specified as an integer from 2 to 104.

Note

When this value is less than 7 the output data values might overflow.

Dependencies

To enable this property, set the OutputDataType property to 'Minimum section word lengths'.

`GainCorrection` — Compensate output gain
`false` (default) | `true`

Set this property to true to compensate for the output gain of the filter.

Depending on the type of decimation you specify and the value of this property, the latency of the object changes.

For fixed decimation (VariableDownsample is false):

With gain correction off, the latency of the object is 3 + N clock cycles.
With gain correction on, the latency of the object is 3 + N + 9 clock cycles.

For variable decimation (VariableDownsample is true):

With gain correction off, the latency of the object is 4 + N clock cycles.
With gain correction on, the latency of the object is 4 + N + 9 clock cycles.

`ResetIn` — Enable reset argument
`false` (default) | `true`

When you set this property to true, the System object expects a reset input argument.

Usage

Syntax

[dataOut,validOut] = cicDecFilt(dataIn,validIn)

[dataOut,validOut] = cicDecFilt(dataIn,validIn,decimFactor)

[dataOut,validOut] = cicDecFilt(dataIn,validIn,reset)

[dataOut,validOut] = cicDecFilt(dataIn,validIn,decimFactor,reset)

Description

[dataOut,validOut] = cicDecFilt(dataIn,validIn) filters and decimates the input data using a fixed decimation factor only when validIn is true.

[dataOut,validOut] = cicDecFilt(dataIn,validIn,decimFactor) filters the input data using the specified variable decimation factor, decimFactor. The VariableDownsample property must be set to true.

[dataOut,validOut] = cicDecFilt(dataIn,validIn,reset) filters the input data when reset is false and clears filter internal states when reset is true. The System object expects the reset argument only when you set the ResetIn property to true.

[dataOut,validOut] = cicDecFilt(dataIn,validIn,decimFactor,reset) filters the input data when reset is false and clears filter internal states when reset is true. The VariableDownsample property is set to true. The System object expects the reset argument only when you set the ResetIn property to true.

Input Arguments

expand all

`dataIn` — Input data
scalar

Input data, specified as a signed integer or signed fixed-point value with a word length less than or equal to 32.

Data Types: int8 | int16 | int32 | fi
Complex Number Support: Yes

`validIn` — Indication of valid input data
logical scalar

Control signal that indicates if the input data is valid.

When validIn is 1 (true), the System object captures the value from the dataIn input argument. When validIn is 0 (false), the System object ignores the dataIn input value.

Data Types: logical

`decimFactor` — Variable decimation rate
`2` (default) | scalar from 2 to 2048

Specifies the decimation rate.

The decimFactor value must be of ufix12 data type and in the range from 2 to the DecimationFactor property value.

Dependencies

To enable this argument, set the VariableDownsample property to true.

Data Types: fi(0,12,0)

`reset` — Clear internal states
logical scalar

Clear internal states, specified as a logical scalar.

When this value is 1 (true), the System object stops the current calculation and clears all internal states. When this value is 0 (false) and validIn is 1 (true), the System object starts a new filtering operation.

Dependencies

To enable this argument, set the ResetIn property to true.

Data Types: logical

Output Arguments

expand all

`dataOut` — CIC decimated output data
scalar

CIC decimated output data, returned as a scalar.

The OutputDataType property sets the output data type of this argument. See OutputDataType.

Data Types: int8 | int16 | int32 | fi
Complex Number Support: Yes

`validOut` — Indication of valid output data
logical scalar

Control signal that indicates if the data from the dataOut output argument is valid. When this value is 1 (true), the System object returns valid data from the dataOut output argument. When this value is 0 (false), the values of the dataOut output argument are not valid.

Data Types: logical

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

expand all

Specific to dsp.HDLCICDecimation

getLatency Latency of CIC decimation filter

Common to All System Objects

`step`	Run System object algorithm
`release`	Release resources and allow changes to System object property values and input characteristics
`reset`	Reset internal states of System object

Examples

collapse all

Create CIC Decimation Filter for HDL Code Generation

Open Script

This example shows how to use the dsp.HDLCICDecimation System object™ to filter and downsample data. The example performs these steps:

Generate frames of random input samples.
Generate reference output data from the dsp.CICDecimation System object™.
Run a function that contains the dsp.HDLCICDecimation System object™. This function operates on a stream of data samples rather than a frame.
Compare the output of the function with the reference data.

You can generate HDL code from the function.

Set up input data parameters. The object supports variable decimation factor specified as an argument. Choose a range for the input decimation factor.

M = 1; % Differential delay
N = 3; % Number of sections
R = 8; % Decimation factor

varRValue = [4,5,6,7,8];

numFrames = length(varRValue);
dataSamples = cell(1,numFrames);
varRtemp = cell(1,numFrames);
refOutput = [];
WL = 0; FL = 0;

Generate frames of random input samples, with the decimation factor changing every frame. To generate reference output data for comparison, apply the samples to the dsp.CICDecimation System object. This object does not support variable decimation rate, so you must create and release the object for each change in decimation factor.

totalsamples = 0;
for i = 1:numFrames
    framesize(i) = varRValue(i)*randi([5 20],1,1);
    dataSamples{i} = fi(randn(framesize(i),1),1,16,8);
    ref_cic = dsp.CICDecimator('DifferentialDelay',M,...
                                'NumSections',N,...
                                'DecimationFactor',varRValue(i));
    refOutput = [refOutput,ref_cic(dataSamples{i}).'];
    release(ref_cic);
end

Write a function that creates and calls the dsp.HDLCICDecimation System object™. You can generate HDL from this function. Set the properties of the object to match the input data parameters. Set the decimationFactor property of the object to the maximum input decimation factor.

function [dataOut,validOut] = HDLCIC_maxR8(dataIn,validIn,R)
%HDLCIC_maxR8
% Performs CIC decimation with an input decimation factor up to 8. 
% sampleIn is a scalar fixed-point value.
% validIn is a logical scalar value.
% You can generate HDL code from this function.

  persistent cic8;
  if isempty(cic8)
    cic8 = dsp.HDLCICDecimation('DecimationFactor',8,...
                                'VariableDownsample',true,...
                                'DifferentialDelay',1,...
                                'NumSections',3);
  end    
  [dataOut,validOut] = cic8(dataIn,validIn,R);
end

Call the function for each input sample, passing the corresponding valid signal and the decimation rate. The input decimation rate must be an unsigned 12-bit fixed-point value. The object has a latency of 2+N cycles. To flush remaining data before changing the decimation rate, call the object with invalid input arguments for 2+N cycles after each frame.

Initialize the output vectors to a size large enough to accommodate the output data. The final size will be smaller than totalsamples due to decimation.

latency = 2+N;
dataOut = zeros(1,totalsamples+numFrames*latency);
validOut = zeros(1,totalsamples+numFrames*latency);
idx=0;
for ij = 1:numFrames
    for ii = 1:length(dataSamples{ij})
        idx = idx+1;
        [dataOut(idx),validOut(idx)] = HDLCIC_maxR8(...
            dataSamples{ij}(ii),...
            true,...
            fi(varRValue(ij),0,12,0));
    end
    for ii = 1:latency
        idx = idx+1;
        [dataOut(idx),validOut(idx)] = HDLCIC_maxR8(...
            fi(0,1,16,8),...
            false,...
            fi(varRValue(ij),0,12,0));
    end
end

Compare the results against the output from the dsp.CICDecimation object.

cicOutput = dataOut(validOut==1);

fprintf('\nHDL CIC Decimation\n');
difference = (abs(cicOutput-refOutput(1:length(cicOutput)))>0);
fprintf('\nTotal number of samples differed between Behavioral and HDL simulation: %d \n',sum(difference));

HDL CIC Decimation

Total number of samples differed between Behavioral and HDL simulation: 0

Explore Latency of HDL CIC Decimation Object

Open Live Script

The latency of the dsp.HDLCICDecimation System object™ varies depending on how many integrator and comb sections your filter has, and whether you enable gain correction. Use the getLatency function to find the latency of a particular filter configuration. The latency is the number of cycles between the first valid input and the first valid output, assuming the input is continuously valid.

Create a dsp.HDLCICDecimation System object™ and request the latency. The default filter has two sections, and gain correction is disabled.

hdlcic = dsp.HDLCICDecimation

hdlcic = 
  dsp.HDLCICDecimation with properties:

    VariableDownsample: false
      DecimationFactor: 2
     DifferentialDelay: 1
           NumSections: 2
        OutputDataType: 'Full precision'
        GainCorrection: false
               ResetIn: false

L_def = getLatency(hdlcic)

L_def = 5

Modify the filter object to have three integrator and comb sections. Check the resulting change in latency.

hdlcic.NumSections = 3;
L_3sec = getLatency(hdlcic)

L_3sec = 6

Enable the gain correction on the filter object. Check the resulting change in latency.

hdlcic.GainCorrection = true;
L_wgain = getLatency(hdlcic)

L_wgain = 15

Algorithms

expand all

CIC Decimation Filter

The transfer function of a CIC decimation filter is

$H (z) = {[\sum_{k = 0}^{R M - 1} z^{- k}]}^{N} = \frac{{(1 - z^{- R M})}^{N}}{{(1 - z^{- 1})}^{N}} = \frac{1}{{(1 - z^{- 1})}^{N}} \cdot \frac{{(1 - z^{- R M})}^{N}}{1} = H_{I}^{N} (z) \cdot H_{c}^{N} (z),$

where

H_I is the transfer function of the integrator part of the filter.
H_C is the transfer function of the comb part of the filter.
N is the number of sections. The number of sections in a CIC filter is defined as the number of sections in either the comb part or the integrator part of the filter. This value does not represent the total number of sections throughout the entire filter.
R is the decimation factor.
M is the differential delay.

CIC Filter Structure

The dsp.HDLCICDecimation System object has the CIC filter structure shown in this figure. The structure consists of N sections of cascaded integrators, a rate change factor of R, and N sections of cascaded comb filters [1].

Designs can put the unit delay in the integrator part of the CIC filter in either the feed-forward or feedback path. These two configurations yield an identical filter frequency response. However, the numerical outputs from these two configurations are different due to the latency of the paths. This System object puts the unit delay in the feed-forward path of the integrator.

Fixed and Variable Decimation

The System object downsamples the integrator stage output using R, either the fixed decimation rate provided using the DecimationFactor property or the variable decimation rate provided using the decimFactor input argument. At the downsampler stage, the System object uses a counter to count the valid input samples, which depend on the decimation rate. Whenever the decimation rate changes, the object resets and starts a new calculation from the next sample. This mechanism prevents the System object from accumulating invalid values. Then, the System object provides the decimated output to the comb part.

Gain Correction

The gain of the System object is given by $G a i n = {(R x M)}^{N}$ .

where:

R is the DecimationFactor property value.
M is the DifferentialDelay property value.
N is the NumSections property value.

The System object implements gain correction in two parts: coarse gain and fine gain. In coarse gain correction, the System object calculates the shift value, adds the shift value to the fractional bits to create a numeric type, and then performs bit-shift left. In fine gain correction, the System object divides the remaining gain with the coarse gain if the gain is not a power of 2 and then multiplies the coarse gain corrected value with the inverse value of fine gain. All possible shift and fine gain values are precalculated initially and stored in an array before the System object starts processing.

You can modify this equation as $G a i n = 2^{c G a i n} x f G a i n$ , where cGain means coarse gain and fGain means fine gain.

$c G a i n = f l o o r (\log_{2} G a i n)$
$f G a i n = G a i n / 2^{c G a i n} = G a i n x 2^{- c G a i n}^{}$

To perform GainCorrection when the VariableDownsample property is enabled, the System object sets the output data type configured with the maximum decimation rate and bit-shifts left for all the values under the maximum decimation rate. The bit-shift value is equal to ${Maximum gain - log}_{2} (current gain)$ .

Output Data Type

This section explains how the System object determines the output data type. For example, consider a filter with DecimationFactor, DifferentialDelay, and NumSections values 8, 1, and 3, respectively, with an input width of 16 bits.

The output word length is calculated as: $B_{OUT} = B_{IN} + [\log_{2} (G a i n)]$ ,

where:

$G a i n = {(R x M)}^{N}$
B_IN is the input word length.
B_OUT is the output word length.

When you set the OutputDataType property to 'Full precision', the System object returns data with a word length of 25 bits, by adding nine gain bits to the input word length.

When you set the OutputDataType property to 'Same word length as input', the object outputs data with a word length of 16, which is the same length as the input word length. The internal integrator and comb stages use the full-precision data type with 25 bits.

When you set the OutputDataType property to 'Minimum section word lengths' and the OutputWordLength property to 16, the System object returns data with a word length of 16 bits. In this case, the object changes the bit width at each stage, based on the pruning algorithm.

If the OutputWordLength property value is less than the number of bits requested at the output, the least significant bits (LSBs) at the earlier stages are pruned. The number of LSBs to discard at each stage is provided in the Hogenauer algorithm. This algorithm minimizes the loss of information in the output data [1].

Latency

This section shows the latencies of the System object when operated with fixed and variable decimation rates.

This figure shows the output of the System object for the default configuration, that is, fixed decimation rate with DecimationFactor, DifferentialDelay, and NumSections values 2, 1, and 2, respectively. The System object returns valid output data at every second cycle based on the fixed DecimationFactor value of 2. The latency of the System object is 5 clock cycles, calculated as 3 + N.

This figure shows the output of the System object for fixed decimation with DecimationFactor, DifferentialDelay, and NumSections values 8, 1, and 3, respectively and with GainCorrection set to true. The System object returns valid output data at every eighth cycle based on the fixed DecimationFactor value of 8. The latency of the object is 15 clock cycles, calculated as 3 + N + 9.

This figure shows the output of the System object for variable decimFactor values 2, 4, and 8 along with M and N values 1 and 3. The GainCorrection property is set to false. The System object returns valid output data at the second, fourth, and eighth cycles corresponding to the decimFactor values 2, 4, and 8, respectively. The System object accepts decimFactor argument value changes only when input validIn is 1 (true). The latency of the System object is 7 clock cycles, calculated as 4 + N.

Performance

The performance of the synthesized HDL code varies with your target and synthesis options. This table shows the resource and performance data synthesis results of the filter with fixed and variable decimation rates when DecimationFactor, DifferentialDelay, and NumSections values are 2, 1, and 2, respectively. The generated HDL is targeted to Xilinx^® Zynq^® ZC706 FPGA.

Decimation Type	Slice LUTs	Slice Registers	Maximum Frequency in MHz
Fixed rate	101	166	711.74
Variable rate	206	186	441.70

The resources and frequencies vary based on the values of R, M, and N and other property values.

References

[1] Hogenauer, E. “An Economical Class of Digital Filters for Decimation and Interpolation.” IEEE Transactions on Acoustics, Speech and Signal Processing vol. 29, no. 2, Apr. 1981, pp. 155–162.

Documentation

dsp.HDLCICDecimation

Description

Creation

Syntax

Description

Properties

VariableDownsample — Variable decimation rate (0) false (default) | (1) true

DecimationFactor — Decimation factor 2 (default) | integer from 2 to 2048

DifferentialDelay — Differential delay 1 (default) | 2

NumSections — Number of integrator or comb sections 2 (default) | integer from 1 to 6

OutputDataType — Data type of output 'Full precision' (default) | 'Same word length as input' | 'Minimum section word lengths'

OutputWordLength — Word length of output 16 (default) | integer from 2 to 104

Note

Dependencies

GainCorrection — Compensate output gain false (default) | true

ResetIn — Enable reset argument false (default) | true

Usage

Syntax

Description

Input Arguments

dataIn — Input data scalar

validIn — Indication of valid input data logical scalar

decimFactor — Variable decimation rate 2 (default) | scalar from 2 to 2048

Dependencies

reset — Clear internal states logical scalar

Dependencies

Output Arguments

dataOut — CIC decimated output data scalar

validOut — Indication of valid output data logical scalar

Object Functions

Specific to dsp.HDLCICDecimation

Common to All System Objects

Examples

Create CIC Decimation Filter for HDL Code Generation

Explore Latency of HDL CIC Decimation Object

Algorithms

CIC Decimation Filter

CIC Filter Structure

Fixed and Variable Decimation

Gain Correction

Output Data Type

Latency

Performance

References

See Also

Objects

Blocks

Introduced in R2019b

DSP System Toolbox Documentation

Support

`VariableDownsample` — Variable decimation rate
`(0)` `false` (default) | `(1)` `true`

`DecimationFactor` — Decimation factor
`2` (default) | integer from 2 to 2048

`DifferentialDelay` — Differential delay
`1` (default) | `2`

`NumSections` — Number of integrator or comb sections
`2` (default) | integer from 1 to 6

`OutputDataType` — Data type of output
`'Full precision'` (default) | `'Same word length as input'` | `'Minimum section word lengths'`

`OutputWordLength` — Word length of output
`16` (default) | integer from 2 to 104

`GainCorrection` — Compensate output gain
`false` (default) | `true`

`ResetIn` — Enable reset argument
`false` (default) | `true`

`dataIn` — Input data
scalar

`validIn` — Indication of valid input data
logical scalar

`decimFactor` — Variable decimation rate
`2` (default) | scalar from 2 to 2048

`reset` — Clear internal states
logical scalar

`dataOut` — CIC decimated output data
scalar

`validOut` — Indication of valid output data
logical scalar