# 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 fixed and variable decimation rates for scalar inputs and only fixed decimation for vector inputs. For both types of inputs, the System object provides a scalar output. The System object 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?

## Creation

### Description

creates an
HDL-optimized CIC decimation filter System object, `cicDecFilt`

= dsp.HDLCICDecimation`cicDecFilt`

, with default properties.

creates the filter with properties set using one or more name-value pairs. Enclose each
property name in single quotes.`cicDecFilt`

= dsp.HDLCICDecimation(`Name,Value`

)

## Properties

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.

`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.

For vector inputs, the object does not support variable decimation rate.

`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`

, this property sets the upper bound of the range of valid
values for the `decimFactor`

argument.

`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. Here, *N* means the number of sections
and *vecLen* means the length of the vector.

For a scalar input with 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 a scalar input with 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.

For a vector input with fixed decimation (`VariableDownsample`

is
`false`

):

With gain correction off, the latency of the object is

`floor`

((*vecLen*– 1) * (*N*/*vecLen*)) + 1 +*N*+ (2 + (*vecLen*+ 1) **N*clock cycles.With gain correction on, the latency of the object is

`floor`

((*vecLen*– 1) * (*N*/*vecLen*)) + 1 +*N*+ (2 + (*vecLen*+ 1) **N*) + 9 clock cycles.

**Note**

For vector inputs, the object does not support variable decimation.

`ResetIn`

— Enable reset argument

`false`

(default) | `true`

When you set this property to `true`

, the System object expects a `reset`

input
argument.

## Usage

### Syntax

### Description

`[`

filters the input data using the specified variable decimation factor,
`dataOut`

,`validOut`

] = cicDecFilt(`dataIn`

,`validIn`

,`decimFactor`

)`decimFactor`

. The `VariableDownsample`

property
must be set to `true`

.

`[`

filters the input data when `dataOut`

,`validOut`

] = cicDecFilt(`dataIn`

,`validIn`

,`decimFactor`

,`reset`

)`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`

. The `VariableDownsample`

property is set to
`true`

.

### Input Arguments

`dataIn`

— Input data

scalar | column vector

Specify input data as a scalar or a column vector of length 1 to 64. The input
data must be a signed integer or signed fixed point with a word length less than or
equal to 32. `DecimationFactor`

property must be an integer
multiple of the input frame size.

**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

scalar

Specifies the decimation rate.

The `decimFactor`

value must be of data type
`ufix12`

data type and an integer 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

`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)

### Specific to dsp.HDLCICDecimation

`getLatency` | Latency of CIC decimation filter |

## Examples

### Create CIC Decimation Filter for HDL Code Generation

This example shows how to use a `dsp.HDLCICDecimation`

System object™ to filter and downsample the data. This object supports scalar and vector inputs. In this example, two functions are provided to work with scalar and vector input data separately. You can generate the HDL code from these functions.

**Generate Frames of Random Input Samples**

Set up these workspace variables for the object to use. The object supports fixed and variable decimation rates for scalar inputs and only a fixed decimation rate for vector inputs. The example runs the `HDLCIC_maxR8`

function when you set the scalar variable to `true`

and runs the `HDLCIC_vec`

function when you set the scalar variable to `false`

. For scalar inputs, choose a range of the input varRValue values and set the decimation factor value, R, to the maximum expected decimation factor. For vector inputs, the input data must be a column vector of size 1 to 64 and R must be an integer multiple of the input frame size.

R = 8; % decimation factor M = 1; % differential delay N = 3; % number of sections scalar = false; % true for scalar; false for vector if scalar varRValue = [2, 4, 5, 6, 7, 8]; vecSize = 1; else varRValue = R; fac = (factor(R)); vecSize = fac(randi(length(fac),1,1)); end numFrames = length(varRValue); dataSamples = cell(1,numFrames); varRtemp = cell(1,numFrames); framesize = zeros(1,numFrames); refOutput = []; WL = 0; % Word length FL = 0; % Fraction length

**Generate Reference Output from dsp.CICDecimation System Object™**

Generate frames of random input samples and apply the samples to the `dsp.CICDecimation`

System object. The output generated from this System object is used as a reference data for comparison. The System object does not support a variable decimation rate, so you must create and release the object for each change in decimation factor value.

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

**Run a Function that contains dsp.HDLCICDecimation System Object**

Set the properties of the System object to match the input data parameters and run the respective function based on the input type. These functions operate on a stream of data samples rather than a frame. You can generate HDL code from these functions.

The example uses the `HDLCIC_maxR8`

function for a scalar input.

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

The example uses the `HDLCIC_vec`

function for a vector input.

function [dataOut,validOut] = HDLCIC_vec(dataIn,validIn) %HDLCIC_vec % Performs CIC decimation with an input vector. % sampleIn is a fixed-point vector. % validIn is a logical scalar value. % You can generate HDL code from this function. persistent cicVec; if isempty(cicVec) cicVec = dsp.HDLCICDecimation('DecimationFactor',8,... 'VariableDownsample',false,... 'DifferentialDelay',1,... 'NumSections',3); end [dataOut,validOut] = cicVec(dataIn,validIn); end

To flush remaining data, run the object by inserting the required number of idle cycles after each frame through `latency`

variable. For more information, see GainCorrection property.

Initialize the output to a size large enough to accommodate the output data. The final size is expected to be smaller than `totalsamples`

due to decimation.

latency = floor((vecSize - 1)*(N/vecSize))+ 1+ N +(2+(vecSize + 1)*N)+ 9; dataOut = zeros(1,totalsamples+numFrames*latency); validOut = zeros(1,totalsamples+numFrames*latency); idx=0; for ij = 1:numFrames if scalar % scalar input with variable decimation 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 else % vector input with fixed decimation for ii = 1:size(dataSamples{ij},2) idx = idx+1; [dataOut(idx),validOut(idx)] = HDLCIC_vec(... dataSamples{ij}(:,ii),... true); end for ii = 1:latency idx = idx+1; [dataOut(idx),validOut(idx)] = HDLCIC_vec(... fi(zeros(vecSize,1),1,16,8),... false); end end end

**Compare the Function Output with the Reference Data**

Compare the function 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

The latency of the `dsp.HDLCICDecimation`

System object™ varies depending on how many integrator and comb sections your filter has, input vector size, 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 with vector input size 2. Check the resulting change in latency.

hdlcic.GainCorrection = true; vecSize = 2; L_wgain = getLatency(hdlcic,vecSize)

L_wgain = 25

## Algorithms

### CIC Decimation Filter

The transfer function of a CIC decimation filter is

$$H(z)={\left[{\displaystyle \sum _{k=0}^{RM-1}{z}^{-k}}\right]}^{N}=\frac{{\left(1-{z}^{-RM}\right)}^{N}}{{\left(1-{z}^{-1}\right)}^{N}}=\frac{1}{{\left(1-{z}^{-1}\right)}^{N}}\xb7\frac{{\left(1-{z}^{-RM}\right)}^{N}}{1}={H}_{\text{I}}{}^{N}(z)\xb7{H}_{\text{c}}{}^{N}(z),$$

where

*H*_{I}is the transfer function of the integrator part of the CIC filter.*H*_{C}is the transfer function of the comb part of the CIC 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 $$Gain={(R\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{x}\text{\hspace{0.17em}}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 $$Gain={2}^{cGain}\text{\hspace{0.17em}}\text{x}\text{\hspace{0.17em}}\text{\hspace{0.17em}}fGain$$, where *cGain* means coarse gain and
*fGain* means fine gain.

$$cGain=floor({\mathrm{log}}_{2}Gain)$$

$$fGain=Gain/{2}^{cGain}=Gain\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{x}\text{\hspace{0.17em}}\text{\hspace{0.17em}}{2}^{-cGain}{}^{}$$

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 $${\text{Maximumgain-log}}_{\text{2}}\text{(currentgain)}$$.

### 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}_{\text{OUT}}=\text{\hspace{0.17em}}\text{\hspace{0.17em}}{B}_{\text{IN}}+\text{\hspace{0.17em}}\text{\hspace{0.17em}}[{\mathrm{log}}_{2}(Gain)]$$,

where:

$$Gain={(R\text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{x}\text{\hspace{0.17em}}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 Hogenauer algorithm provides the number of LSBs to discard at each stage. This
algorithm minimizes the loss of information in the output data [1].

### Latency

This section shows the latencies of the System object for a scalar input when the System object is operated with fixed and variable decimation rates and for a vector input when the System object is operated with a fixed decimation rate.

**Scalar Input**

This figure shows the output of the System object for the default configuration, that is, with a fixed decimation rate and
`DecimationFactor`

, `DifferentialDelay`

, and
`NumSections`

values of 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 with a fixed decimation rate, `DecimationFactor`

,
`DifferentialDelay`

, and `NumSections`

values of
8, 1, and 3, respectively and `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 and is 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*.

**Vector Input**

The latency of the System object for a vector input is calculated using this formula:
`floor`

((*vecLen* – 1) *
(*N*/*vecLen*)) + 1 + *N* + 9 *
`GainCorrection`

+ (2 + (*vecLen* + 1) *
*N*), where *vecLen* is the length of the vector and
*N* is the number of sections.

This figure shows the output of the System object for a two-element column vector input with default configuration, that is,
with a fixed decimation rate and `DecimationFactor`

,
`DifferentialDelay`

, and `NumSections`

values of
2, 1, and 2, respectively. The latency of the block is 12 clock cycles.

This figure shows the output of the System object for an eight-element column vector input with a fixed decimation rate and
*R*, *M*, and *N* values of 8, 1, and
3, respectively and `GainCorrection`

set to `true`

.
The latency of the block is 44 clock cycles.

### 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 block
for a scalar input with fixed and variable decimation rates and for a two-element column
vector input with fixed decimation rate `DecimationFactor`

,
`DifferentialDelay`

, and `NumSections`

values are 2,
1, and 2, respectively. The generated HDL is targeted to the Xilinx^{®}
Zynq^{®}-7000 ZC706 evaluation board.

Input Data | Decimation Type | Slice LUTs | Slice Registers | Maximum Frequency in MHz |
---|---|---|---|---|

Scalar | Fixed rate | 101 | 166 | 711.74 |

Variable rate | 206 | 186 | 441.70 | |

Vector | Fixed rate | 218 | 627 | 624.61 |

The resources and frequencies vary based on the type of input data and
*R*, *M*, and *N* values and other
selected property values. Using a vector input can increase the throughput, however this
option also increases the number of hardware resources that the System object uses.

## References

[1] Hogenauer, E. *“An
Economical Class of Digital Filters for Decimation and Interpolation.”*
*IEEE Transactions on Acoustics, Speech, and Signal
Processing* 29, no. 2 (April 1981): 155–62.
https://doi.org/10.1109/TASSP.1981.1163535.

## Extended Capabilities

### C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

This System object supports C/C++ code generation for accelerating MATLAB^{®} simulations, and for DPI component generation.

### HDL Code Generation

Generate Verilog and VHDL code for FPGA and ASIC designs using HDL Coder™.

`double`

and `single`

data
types are supported for simulation, but not for HDL code generation.

To generate HDL code from predefined System objects, see HDL Code Generation from Viterbi Decoder System Object (HDL Coder).

## See Also

### Objects

`dsp.CICDecimator`

|`dsp.CICInterpolator`

|`dsp.CICCompensationDecimator`

|`dsp.CICCompensationInterpolator`

### Blocks

**Introduced in R2019b**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)