# 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:

1. Create the `dsp.HDLCICDecimation` object and set its properties.

2. Call the object with arguments, as if it were a function.

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

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.

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.

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

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

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

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

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.

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

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

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`

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

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

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

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

 `getLatency` Latency of CIC decimation filter
 `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

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

1. Generate frames of random input samples.

2. Generate reference output data from the `dsp.CICDecimation` System object™.

3. Run a function that contains the `dsp.HDLCICDecimation` System object™. This function operates on a stream of data samples rather than a frame.

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

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

expand all

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

Watch now