Main Content

dsphdl.Upsampler

Upsample by adding zeros between input samples

Since R2022b

expand all in page

Description

The dsphdl.Upsampler System object™ upsamples an input signal by adding L–1 zeros between input samples, where L is the upsampling factor. The System object supports these combinations of input and output data.

  • Scalar input and scalar output

  • Scalar input and vector output

  • Vector input and vector output

The System object provides an architecture suitable for HDL code generation and hardware deployment.

To upsample input data with an upsampler, follow these steps:

  1. Create the dsphdl.Upsampler object and set its properties.

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

To learn more about how System objects work, see What Are System Objects?

Note

You can also generate HDL code for this hardware-optimized algorithm, without creating a MATLAB® script, by using the DSP HDL IP Designer app. The app provides the same interface and configuration options as the System object.

Creation

Syntax

upsample = dsphdl.Upsampler
upsample = dsphdl.Upsampler(Name=Value)

Description

upsample = dsphdl.Upsampler creates an HDL-optimized upsampler System object with default property values.

upsample = dsphdl.Upsampler(Name=Value) sets property values using one or more name-value arguments.

example

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.

Upsampling factor specified as an integer in the range [1, 2.^16]. This value gives the rate by which the System object increases the input sampling rate.

Sample offset, specified as an integer in the range [0, UpsampleFactor – 1].

Specify the minimum number of cycles between the valid input samples as a factor or multiple of UpsampleFactor, or an integer in the range [1, Inf] based on the type of input and output data.

Input DataOutput DataMinimum Number of Cycles Between Valid Input Samples
ScalarScalarGreater than or equal to UpsampleFactor
ScalarVectorFactor of UpsampleFactor
VectorVectorInteger in the range [1, Inf]

Option to enable the reset input argument, specified as a numeric or logical 1 (true) or 0 (false)

Option to enable the ready output argument, specified as a numeric or logical 1 (true) or 0 (false)

Usage

Syntax

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

Description

[dataOut,validOut] = upsampler(dataIn,validIn) upsamples the input dataIn using an upsampling factor only when validIn is true.

[dataOut,validOut] = upsampler(dataIn,validIn,reset) upsamples the input data when reset is false and clears the filter internal states when reset is true. To enable the reset argument, set the ResetInputPort property to true.

example

Input Arguments

expand all

Input data, specified as a scalar or a column vector with a length up to 64. The input data must be an integer or a fixed-point value with a word length less than or equal to 128.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | fi

Valid input data indicator, specified as a numeric or logical 1 (true) or 0 (false). When validIn is 1 (true), the object captures the values from the dataIn argument. When validIn is 0 (false), the object ignores the values from the dataIn argument.

Data Types: logical

Option to clear the internal states, specified as a numeric or logical 1 (true) or 0 (false). When reset is 1 (true), the object stops the current calculation and clears the internal states. When reset is 0 (false) and valid is 1 (true), the object captures data for processing.

For more reset considerations, see the Reset Signal section on the Hardware Control Signals page.

Dependencies

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

Data Types: logical

Output Arguments

expand all

Upsampled data, returned as a scalar or a column vector with a length up to 128.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | fi

Valid output data indicator, returned as a logical 0 or 1. A value of 1 indicates that the object returns valid data in the dataOut argument. A value of 0 indicates that values in the dataOut 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

getLatencyLatency of upsampler
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

This example uses:

Open Script

This example shows how to use a dsphdl.Upsampler System object to upsample data. You can generate HDL code for this object.

Generate Frames of Random Input Samples

Set up workspace variables for the object to use. The object supports scalar and vector inputs. For vector inputs, the input data must be a column vector of size 1 to 64.

clear variables % Clear workspace
clear HDLUpsample
clear HDLUpsample_Vec

L = 8;                % Upsample factor
O = 2;                % Sample offset

scalar = true;
if scalar
    vecSize = 1;
    value = 1;
else
    vecSize = 2; %#ok % multiple or factor of L
    value = vecSize*L;
end

numFrames = 1;
dataSamples = cell(1,numFrames);
framesize = zeros(1,numFrames);
refOutput = [];
WL = 0;               % word length
FL = 0;               % fraction length

Generate Reference Output from Function

Generate frames of random input samples and apply the upsample function. You can use the output that this function generates as a reference against which to compare the output of the System object.

totalsamples = 0;
for i = 1:numFrames
    framesize(i) = randi([5 200],1,1);
    dataSamples{i} = fi(randn(vecSize,framesize(i)),1,16,8);
    ref_upsample= upsample((dataSamples{i}(:)),L,O);
    refOutput = [refOutput,ref_upsample]; %#ok
end

Run Function Containing System Object

This example uses the HDLUpsample function for a scalar input and HDLUpsample_Vec function for a vector input. Set the properties of the System object in these functions to match the input data properties.

function [dataOut,validOut] = HDLUpsample(dataIn,ValidIn)
persistent hdlUSObj
if isempty(hdlUSObj)
    hdlUSObj = dsphdl.Upsampler(UpsampleFactor=8, ...
        SampleOffset=2, ...
        NumCycles=8);
end
[dataOut,validOut] = hdlUSObj(dataIn,ValidIn);
end

% Copyright 2022-2023 The MathWorks, Inc.


function [dataOut,validOut] = HDLUpsample_Vec(dataIn,ValidIn)
persistent hdlUSObj
if isempty(hdlUSObj)
    hdlUSObj = dsphdl.Upsampler(UpsampleFactor=8, ...
        SampleOffset=2, ...
        NumCycles=1);
end
[dataOut,validOut] = hdlUSObj(dataIn,ValidIn);
end

% Copyright 2022-2023 The MathWorks, Inc.

Insert the required number of idle cycles after each frame using the latency variable to avoid invalid output data.

latency = 3;
dataOut = zeros(value,totalsamples+numFrames*latency);
validOut = zeros(1,totalsamples+numFrames*latency);
idx=0;
for ij = 1:numFrames
    dataIn = zeros(vecSize,size(dataSamples{ij},2)*L);
    validIn = upsample(true(1,length(dataSamples{ij})),L);
    dataIn(:,validIn) = dataSamples{ij};
    if scalar
        for ii = 1:length(validIn)
            idx = idx+1;
            [dataOut(:,idx),validOut(idx)] = HDLUpsample( ...
                fi(dataIn(:,ii),1,16,8), ...
                validIn(ii));
        end
        for ii = 1:latency
            idx = idx+1;
            [dataOut(:,idx),validOut(idx)] = HDLUpsample( ...
                fi(zeros(vecSize,1),1,16,8), ...
                false);
        end
    else
        for ii = 1:length(validIn) %#ok
            idx = idx+1;
            [dataOut(:,idx),validOut(idx)] = HDLUpsample_Vec( ...
                fi(dataIn(:,ii),1,16,8), ...
                validIn(ii));
        end
        for ii = 1:latency
            idx = idx+1;
            [dataOut(:,idx),validOut(idx)] = HDLUpsample_Vec( ...
                fi(zeros(vecSize,1),1,16,8), ...
                false);
        end
    end
end

Compare Function Output with Reference Output

Compare the output of the HDL function with the output of the upsample function.

HDLOutput = dataOut(:,validOut==1);
HDLOutput = HDLOutput(:);

fprintf('\n Upsampler:\n');
difference = (abs(HDLOutput-refOutput(1:length(HDLOutput)))>0);
fprintf(['\nTotal number of samples differed between Behavioral ' ...
    'and HDL simulation: %d \n'],sum(difference));

 Upsampler:

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

The latency of the dsphdl.Upsampler System object™ varies according to the upsample factor and the input vector size. Use the getLatency function to find the latency of an upsampler 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 dsphdl.Upsampler System object and get the latency. The default System object has an upsampling factor of 3 and a sample offset set of 0.

upsampler = dsphdl.Upsampler
upsampler = 
  dsphdl.Upsampler with properties:

    UpsampleFactor: 3
      SampleOffset: 0
         NumCycles: 1

  Use get to show all properties


V = 1;
Ydefault = getLatency(upsampler,V)
Ydefault = 
3

Modify the object and check the resulting change in latency.

upsampler.UpsampleFactor = 8;
Y1 = getLatency(upsampler)
Y1 = 
2

Change the vector input size to 2. Check the resulting change in latency.

V = 2;
upsampler.UpsampleFactor = 10;
LVec = getLatency(upsampler,V)
LVec = 
2

Algorithms

expand all

Extended Capabilities

Version History

Introduced in R2022b

See Also

Blocks

Objects