hdlverifier.HDLCosimulation

Create a System object for HDL cosimulation with MATLAB

Description

The hdlverifier.HDLCosimulation System object™ cosimulates MATLAB® and a hardware component. The System object writes input signals to and reads output signals from an HDL model under simulation in the HDL simulator. You can use this System object to model a source or sink device by configuring the System object with only output or input ports, respectively.

To create a System object for HDL cosimulation with MATLAB:

  1. Customize the hdlverifier.HDLCosimulation object using Cosimulation Wizard.

  2. Create the object in your design and set its properties.

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

To create an hdlverifier.HDLCosimulation System object, use the Cosimulation Wizard to customize the HDLCosimulation System object. The output of the Cosim Wizard is a file called hdlcosim_toplevel.m, where toplevel is the name of the top level HDL module. You can then create the System object by assigning it to a local variable.

Syntax

hdlc = hdlverifier.HDLCosimulation
hdlc = hdlverifier.HDLCosimulation(Name,Value)
hdlc = hdlcosim
hdlc = hdlcosim(Name,Value)

Description

hdlc = hdlverifier.HDLCosimulation creates an hdlverifier.HDLCosimulation System object with default property values. This System object provides an interface to your HDL simulation in your MATLAB workspace.

hdlc = hdlverifier.HDLCosimulation(Name,Value) specifies properties by one or more Name,Value pairs. Enclose each property name in single quotes. For example,

hdlc = hdlverifier.HDLCosimulation('InputSignals','/top/in1', ... , 'OutputFractionLangths',10);

hdlc = hdlcosim creates an hdlverifier.HDLCosimulation System object with default property values. This syntax is equivalent to the hdlverifier.HDLCosimulation syntax.

hdlc = hdlcosim(Name,Value) is equivalent to the hdlverifier.HDLCosimulation(Name,Value) syntax.

The Cosimulation Wizard creates an hdlverifier.HDLCosimulation System object using existing HDL code, and an HDL launch script. Use the Cosimulation Wizard for easier startup.

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

Input paths in the HDL code, specified as a character vector or cell array of character vectors. The paths are specified relative to the top level of the HDL hierarchy.

Example: 'data_in'

Example: {'/top/in1','/top/in2'}

Data Types: char | cell

Output paths in the HDL code, specified as a character vector or cell array of character vectors. The paths are specified relative to the top level of the HDL hierarchy.

Example: 'out1'

Example: {'out1','out2'}

Data Types: char | cell

Data types of the output signals, specified as a cell array of character vectors. Valid data types are 'fixedpoint','double', or 'single'.

If you specify only one data type, each output has that same data type. To assign different data types to each output, specify a cell array of the same size as the number of outputs. Each element in the OutputDataTypes cell array specifies the data type of the corresponding element in the System object output (hdloutputs).

Example: {'fixedpoint'} – All output data types are fixedpoint.

Example: {'double','single'} – The data type of the first output is double and the second is single.

Note

When OutputDataTypes is {'fixedpoint'}, the bit-width matches the size of a built-in data type (8,16,32, or 64), and OutputFractionLengths is set to 0, the data type of the output signal is returned as that built-in data type.

Data Types: cell

Sign of the outputs, specified as false (unsigned), true (signed), or a logical vector.

If you provide only true or false, each output has that corresponding sign. To apply different signs to each output, specify a logical vector of the same size as the number of outputs. Each element in the OutputSigned vector specifies the sign of the corresponding element in the System object output (hdloutputs).

Example: true – All outputs have a signed value.

Example: [true,true,false] — The first output is a signed value, the second output is a signed value, and the third (and final) output is an unsigned value.

Output fraction lengths, in bits, specified as an integer or vector of integers.

If you specify only a scalar, each output has that same fraction length. To apply different fraction lengths to each output, specify a vector of the same size as the number of outputs. Each element in the OutputFractionLengths vector specifies the fraction length of the corresponding element in the System object output (hdloutputs).

Example: 10 — All outputs have a fraction length of 10 bits.

Example: [16,8] — The first output has a fraction length of 16 bits, and the second (and final) output has a fraction length of 8 bits.

Tcl pre simulation command executed by the HDL simulator during the first call to the System object, specified as a character vector. This Tcl presimulation command is also executed during the first call to the System object after it is released.

Example: 'force /top/rst 1 0, 0 2 ns; force /top/clk 0 0, 1 1 ns -repeat 2 ns'

Data Types: char

Tcl post simulation command executed by the HDL simulator during a call to release the System object, specified as a character vector.

Example: 'echo "done"'

Data Types: char

Delay in HDL simulator before the cosimulation starts, specified as a cell array with two elements.

  • The first element is the HDL presimulation delay, specified as a nonnegative integer.

  • The second element is the time unit, specified as one of these character vectors: 'fs','ps','ns','us','ms', or 's'.

Example: {10,'fs'}

Data Types: cell

Parameters for the connection to the HDL simulator, specified as a cell array with one, two, or three elements.

  • The first element is the connection type, specified as 'SharedMemory' or 'Socket'. If specifying shared memory, then the port number and host name (the second and third elements in this cell array) are not applicable.

  • The second element is the port number, which must be a positive integer. This value is set to 4449 if not specified.

  • The third element is the host name of the HDL session. This value is set to localhost if not specified.

Example: {'SharedMemory'}

Example: {'Socket',1234}

Example: {'Socket',1234,'hostname'}

Data Types: cell

Note

The FrameBasedProcessing property will be removed in a future release.

Sample mode or frame mode is automatically detected based on the size of the inputs during the System object execution.

Elapsed time in the HDL simulator between each call to the System object, specified as a cell array with two elements.

  • The first element is the time between two calls to the System object, specified as a positive integer.

  • The second element is the time unit, specified as a character vector: 'fs','ps','ns','us','ms','s'.

Example: {10,'ns'}

Data Types: cell

Usage

For versions earlier than R2016b, use the step function to run the System object algorithm. The arguments to step are the object you created, followed by the arguments shown in this section.

For example, y = step(obj,x) and y = obj(x) perform equivalent operations.

Syntax

hdloutputs = hdlc(hdlinputs)

Description

example

hdloutputs = hdlc(hdlinputs) connects to the HDL simulator, writes hdlinputs to the HDL simulator, and reads hdloutputs from the HDL simulator. The elapsed simulation time between each call to the System object is defined by the SampleTime property.

Input Arguments

expand all

Inputs to the HDL simulator, specified as a comma-separated list of values that are driven to your HDL input ports. The HDL input ports are set by the InputSignals property. The number of elements in this comma-separated pair must equal the number of HDL input ports. Each input argument value is driven to its corresponding HDL input port.

For example, if InputSignals is set as {'in1','in2'}, specify out = hdlc(input1,input2) to drive the value input1 to in1 and input2 to in2.

Example: [RealFft, ImagFft] = hdlc(3,12); the values 3 and 12 are driven as inputs to the HDL simulator, which has two input ports.

Output Arguments

expand all

Outputs from the HDL simulator, returned as a scalar or vector. Each returned element is the output from its corresponding HDL output port. The HDL output ports are specified in the OutputSignals property. The number of elements returned is the same as the number of HDL output ports specified. For example, if OutputSignals is set as {'out1','out2'}, specify [o1, o2] = hdlc(i1,i2) to assign the value from out1 to o1 and out2 to o2.

Example: out1 = hdlc(3,12); assigns the output value from an HDL simulator with one output port.

Example: [RealFft, ImagFft] = hdlc(3,12); assigns output values from an HDL simulator with two output ports. In this example, RealFft is the output from the first port and ImagFft is the output from the second port.

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

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

Examples

expand all

This example shows you how to use MATLAB® System objects and Mentor Graphics® ModelSim®/QuestaSim® or Cadence® Incisive®/Xcelium® to cosimulate a Viterbi decoder implemented in VHDL.

Set Simulation Parameters and Instantiate Communication System Objects

If you are using Incisive/Xcelium, set simulator variable to 'Incisive'

Simulator = 'Incisive';

% or if you are using ModelSim/QuestaSim, set simulator variable to
% 'ModelSim'
Simulator = 'ModelSim';

% The following code sets up the simulation parameters and instantiates the
% system objects that represent the channel encoder, BPSK modulator, AWGN
% channel, BPSK demodulator, and error rate calculator. Those objects
% comprise the system around the Viterbi decoder and can be thought of as
% the test bed for the Viterbi HDL implementation.

EsNo = 0;	% Energy per symbol to noise power spectrum density ratio in dB
FrameSize = 1024;  % Number of bits in each frame

% Convolution Encoder
hConEnc = comm.ConvolutionalEncoder;
% BPSK Modulator
hMod    = comm.BPSKModulator;
% AWGN channel
hChan   = comm.AWGNChannel('NoiseMethod', ...
                           'Signal to noise ratio (Es/No)',...
                           'SamplesPerSymbol',1,...
                           'EsNo',EsNo);
% BPSK demodulator
hDemod  = comm.BPSKDemodulator('DecisionMethod','Log-likelihood ratio',...
                               'Variance',0.5*10^(-EsNo/10));
% Error Rate Calculator
hError  = comm.ErrorRate('ComputationDelay',100,'ReceiveDelay', 58);

Instantiate the Cosimulation System Object

The hdlcosim function returns an HDL cosimulation System object, which represents the HDL implementation of the Viterbi decoder in this simulation system.

switch Simulator
    case 'ModelSim'
        hDec    = hdlcosim('InputSignals', {'/viterbi_block/In1','/viterbi_block/In2'}, ...
                           'OutputSignals', {'/viterbi_block/Out1'}, ...
                           'OutputSigned', false, ...
                           'OutputFractionLengths', 0, ...
                           'TCLPreSimulationCommand', 'force /viterbi_block/clk_enable 1 0; force /viterbi_block/clk 0 0 ns, 1 5 ns -repeat 10 ns; force /viterbi_block/reset 1 0 ns, 0 8 ns; ', ...
                           'TCLPostSimulationCommand', 'echo "done";', ...
                           'PreRunTime', {10,'ns'}, ...
                           'Connection', {'Shared'}, ...
                           'SampleTime', {10,'ns'});
    case 'Incisive'
        hDec    = hdlcosim('InputSignals', {'/viterbi_block/In1','/viterbi_block/In2'}, ...
                           'OutputSignals', {'/viterbi_block/Out1'}, ...
                           'OutputSigned', false, ...
                           'OutputFractionLengths', 0, ...
                           'TCLPreSimulationCommand', 'force :clk B"0" -after 0ns B"1" -after 5ns -repeat 10ns; force reset B"1" -after 0ns B"0" -after 8ns; force :clk_enable B"1" -after 0ns', ...
                           'TCLPostSimulationCommand', 'echo "done";', ...
                           'PreRunTime', {10,'ns'}, ...
                           'Connection', {'Shared'}, ...
                           'SampleTime', {10,'ns'});
end

Launch HDL Simulator

The vsim and nclaunch command launches HDL simulator. The launched HDL simulator session compiles the HDL design and loads the HDL simulation. You are ready to perform cosimulation when the HDL simulation is fully loaded in simulator.

disp('Waiting for HDL simulator to launch ...');
switch Simulator
    case 'ModelSim'
        vsim('tclstart',viterbi_tclcmds_modelsim('vsimmatlabsysobj'));
    case 'Incisive'
        nclaunch('tclstart',viterbi_tclcmds_incisive('hdlsimmatlabsysobj'));
end
Timeout=450;
processid = pingHdlSim(Timeout);
% Check if HDL simulator is ready for Cosimulation.
assert(ischar(processid),['Timeout: HDL simulator took more than ', num2str(Timeout),' seconds to setup,please increase the timeout in ''pingHdlSim''']);
disp('Ready for cosimulation ...');

Run Cosimulation

This example simulates the BPSK communication system in MATLAB incorporating the Viterbi decoder HDL implementation via the cosimulation System object. This section of the code calls the processing loop to process the data frame-by-frame with 1024 bits in each data frame.

for counter = 1:20480/FrameSize
    data            = randi([0 1],FrameSize,1);
    encodedData     = step(hConEnc, data);
    modSignal       = step(hMod, encodedData);
    receivedSignal  = step(hChan, modSignal);
    demodSignalSD   = step(hDemod, receivedSignal);
    quantizedValue  = fi(4-demodSignalSD,0,3,0);
    input1          = quantizedValue(1:2:2*FrameSize);
    input2          = quantizedValue(2:2:2*FrameSize);
    receivedBits    = step(hDec,input1, input2);
    errors          = step(hError, data, double(receivedBits));
end

Display the Bit-Error Rate

The Bit-Error Rate is displayed for the Viterbi decoder.

sprintf('Bit Error Rate is %d\n',errors(1))

Destroy Cosimulation System Object to Release HDL Simulator

The HDL simulator is unblocked when the HDL cosimulation system object is destroyed in MATLAB. Close the HDL simulator session manually.

clear hDec;

% This concludes the "Verify Viterbi Decoder Using MATLAB System Object and
% HDL Simulator".

Introduced in R2012b