cosimulationConfiguration

Configure HDL cosimulation workflow

Since R2022b

Description

The cosimulationConfiguration object controls the creation of an HDL Cosimulation block or System object™ for a specified HDL module.

Creation

Syntax

cosimObj = cosimulationConfiguration(HDLSimulator,SubWorkflow,HDLTopLevelName)

cosimObj = cosimulationConfiguration(MATfile)

Description

cosimObj = cosimulationConfiguration(HDLSimulator,SubWorkflow,HDLTopLevelName) creates a cosimulationConfiguration object with the specified HDLSimulator, SubWorkflow, and HDLTopLevelName values.

This workflow is a command-line alternative to using the Cosimulation Wizard for creating an HDL Cosimulation block or an hdlverifier.HDLCosimulation System object.

cosimObj = cosimulationConfiguration(MATfile) creates a cosimulationConfiguration object based on the results of a previous run of the Cosimulation Wizard or command-line workflows.

Properties

Workflow

HDLSimulator — HDL simulator to use

'ModelSim' | 'Xcelium' | 'Vivado Simulator'

HDL simulator to use for cosimulation, specified as 'ModelSim', 'Xcelium', or 'Vivado Simulator'.

SubWorkflow — Cosimulation kind

'Simulink' | 'MATLAB System Object'

Kind of cosimulation to perform:

• 'Simulink' — Configures the workflow to create an HDL Cosimulation block for a Simulink^® cosimulation.

• 'MATLAB System Object' — Configures the workflow to create an hdlverifier.HDLCosimulation System object for a MATLAB^® cosimulation.

HDLTopLevelName — Name of top level HDL module or entity

string

Name of the top level HDL module or entity, specified as a string or character vector.

Data Types: char | string

HDL Compilation

HDLFiles — HDL files for cosimulation

string | character vector | cell array

HDL directory, file, or files required for cosimulation, specified as a string or cell array. If one of the files does not have a known HDL file extension, the tool ignores it.

Example: './hdlsrc' includes all files from the hdlsrc directory

Example: {'./hdlsrc','myModule.v'} includes all files from the hdlsrc directory and a local file named myModule.v.

Another option, is to specify a list where each file is followed by a file type. Available file types depend on the simulator:

• ModelSim™: Verilog (*.v, *.sv), VHDL (*.vhd), ModelSim macro file (*.do)

• Xcelium™: Verilog (*.v, *.sv), VHDL (*.vhd), Shell script (*.sh)

• Vivado^®: Verilog (*.v, *.sv), VHDL (*.vhd), Vivado XCI file (*.xci)

Example: {'mytop.v','Verilog','submod.v','Verilog'}

Data Types: char | string | cell array

HDLSimulatorPath — HDL simulator location

string | character vector

Location of the HDL simulator, specified as a string or character vector. Use this option when you want to use a simulator in a different location than the one specified on the system PATH. When empty, the system path is used.

Data Types: char | string

HDLCompilationCommand — Compilation commands to use

string | character vector

Compilation commands to use, specified as a string or character vector. The compilation commands are automatically generated based on the selected simulator and design file list. You can supply different compilation commands if required, for example when you have to compile into a specific library.

Tip

It is useful to run the workflow once to generate a cosimWizard_<TOP>.mat file. Then you can modify the compilation commands and set this property.

Data Types: char | string

HDLParameterFile — Set values for HDL parameters or generics

'' (default) | 'GENERATE_AND_EDIT' | filename

Include a parameter file to specify nondefault values for HDL parameters or generics. Edit the file to override values from their defaults and execute the runWorkflow function for the parameter values to be in effect. You can enter one of these options:

• '' — Generates a default parameter file named parameter_HDLTopLevelName.cfg, where HDLTopLevelName is the name of the top-level HDL module or entity. The file includes a line for each HDL parameter and all the lines are commented. When executing the runWorkflow function, the function generates the default file and continues running through the whole workflow.

• GENERATE_AND_EDIT — Generates a new parameter file with the default filename parameter_HDLTopLevelName.cfg. When executing the runWorkflow function, the execution stops after generating the parameter configuration file. Edit the file to uncomment the lines with relevant parameters and change their value to override the default value. Then, restart the workflow by executing runworkflow(c) in the command line.

• filename — Uses the specified parameter file when you execute the workflow.

This property is valid only for cosimulation with Xcelium or ModelSim.

Tip

To set HDL parameters when using Vivado simulator, use the HDLCompilationCommand property. For more information see Set HDL Parameters for Vivado Simulation.

Data Types: char | string

HDLElaborationOptions — Options for the HDL elaboration tool

string | character vector

Options for the HDL elaboration tool, specified as a string or character vector.

This property is valid for cosimulation with Xcelium.

Data Types: char | string

HDLSimulationOptions — Options for the HDL simulation tool

string | character vector

Options for the HDL simulation tool, specified as a string or character vector.

The default value for Xcelium forces use of the 64-bit app.

The default value for ModelSim includes the necessary flags to define the HDL time precision and to give read/write access of the port for cosimulation.

This property is only valid for cosimulation with Xcelium or ModelSim.

Data Types: char | string

HDL Timing

HDLTimeUnit — Time unit for HDL simulation

fs | ps | ns | us | ms | s

Time unit for HDL simulation. This unit affects the following configurations:

• PreCosimulationRunTime property

• SampleTime property (MATLAB System object sub-workflow)

• Period attribute of clock ports

• Duration attribute of reset ports

The default unit is determined dynamically by a query of the time precision to the HDL simulator during compilation (ModelSim, Xcelium) or by the HDLTimePrecision property (Vivado).

Note

The SampleTime attribute of output ports is in seconds because it specifies a Simulink time.

PreCosimulationRunTime — Time to run HDL simulator before cosimulation starts

integer

The amount of time to run the HDL simulator before beginning simulation in Simulink or MATLAB, in HDLTimeUnit units. This time allows getting through any necessary resets and asserting clock enables.

A visual timing diagram of clocks, resets, and the cosimulation start time is created in file hdlverifier_rstclk_waveform.jpg after you run the workflow.

AutoTimeScale — Automatically determine timescale

true (default) | false

Automatically determine the ratio between Simulink time to HDL time at the first cosimulation.

The Simulink sample times are related to the HDL simulation time using a timing scale. Often the best choice is for the fundamental Simulink sample time to equal the fastest clock period in the HDL. Because all of the input sample times are not known at the time that this workflow executes, you can choose to have the timescale determined automatically on the first simulation when all of the sample times are known.

To enable this property, set Subworkflow to Simulink.

TimeScale — Explicitly set timescale

{1, 's'} (default) | scale factor and time unit

Manually set the timescale, specified as a scale factor and a time unit: {factor, unit}.

The scale is relative to 1 second in Simulink: 1 second in Simulink is equal to {factor, unit} in HDL. The factor is a double and the unit is one of 'fs','ps','ns','us','ms', or 's'. The default value is {1, 's'}, which means that Simulink times are equivalent to HDL

times.

Example: With a Simulink sample time of 1 second and an HDL clock of 100 MHz, create a timescale where 1 second in Simulink is equal to 10 ns in HDL: c.AutoTimeScale = false; c.TimeScale = {10, 'ns'};

Dependencies

To enable this property, set Subworkflow to Simulink.

SampleTime — HDL time for each System object evaluation

nonnegative numeric

Set the MATLAB sample time for the generated System object in HDLTimeUnit units. All inputs and outputs share the same sample time in MATLAB and each call to the step method elapses this amount of time.

The default value is determined by the specified clock periods and output sample times.

Dependencies

To enable this property, set Subworkflow to MATLAB System Object.

HDL Simulator Connection

Connection — Type of connectivity to the HDL simulator

Socket (default) | Shared Memory

Channel type for connecting to MATLAB or Simulink to the HDL simulator, specified as Socket or Shared Memory.

• Socket: MATLAB or Simulink and the HDL simulator communicate through a designated TCP/IP socket. You can use it for single-system and network configurations. This option offers the greatest scalability. For more information about TCP/IP socket communication, see TCP/IP Socket Ports.

• Shared memory: MATLAB or Simulink and the HDL simulator communicate through shared memory. Shared memory communication provides optimal performance.

Port Interface Properties

ClockPortRegularExpression — Expression for auto-assigning ports to clocks

'clk$|clock$' (default) | regular expression

Expression for auto-assigning ports to clocks, specified as a regular expression. For more information about regular expressions in MATLAB, see Regular Expressions.

Example: 'clk_in$' assigns all the ports that end with "clk_in" as clock ports.

ResetPortRegularExpression — Expression for auto-assigning ports to resets

'rst$|reset$|rst_n$|reset_n$|reset_x$' (default) | regular expression

Expression for auto-assigning ports to resets, specified as a regular expression. For more information about regular expressions in MATLAB, see Regular Expressions.

Example: c.ResetPortRegularExpression = [c.ResetPortRegularExpress 'rst[0-9]$'] assigns all the ports that end with "rst" and a numerical value as reset ports, in addition to the default expression for reset ports.

UnusedPortRegularExpression — Expression for auto-assigning ports as unused

'' (default) | regular expression

Expression for labelling ports as unused, specified as a regular expression. Ports assigned as unused are not part of the cosimulation. Unused ports do not show up in the cosimulation interface and are not driven or sampled.

To clear the specifications, provide an empty argument after the signal names.

For more information about regular expressions in MATLAB, see Regular Expressions.

Example: 'clk_out$' indicates that any ports that end with "clk_out" are unused.

InputDataPorts — Display input ports

table

This property is read-only.

Input ports, displayed as a table. See the full table contents by calling the portInterface object function.

The default is an empty table and the workflow determines input data ports. Inputs that do not match the clock, reset, and unused regular expressions are considered input data ports.

You can explicitly assign input ports by using the specifyInput object function.

OutputDataPorts — Display output ports

table

This property is read-only.

Output ports, displayed as a table. Each row in the table contains the following information per output:

• Name of output port

• SampleTime

• DataType

• Signed

• FractionLength

In addition to the DUT outputs, the table includes a row named default_output_definition, which contains the default values assigned for the outputs.

You can change the default output values or manually assign output ports by using the specifyOutput object function.

See the full table contents by calling the portInterface object function.

ClockPorts — Display clock ports

table

This property is read-only.

Clock ports, displayed as a table. Each row in the table contains the following information per clock:

• Name of clock port

• Edge

• Period

In addition to the DUT clocks, the table includes an extra row named default_clock_definition for the default clock definitions.

You can change the default clock values or manually assign clocks by using the specifyClock object function.

See the full table contents by calling the portInterface object function.

ResetPorts — Display reset ports

table

This property is read-only.

Reset ports, displayed as a table. Each row in the table contains the following information per reset:

• Name — Name of reset port

• InitialValue — Initial value of the reset

• Duration — Duration of the reset signal

In addition to the DUT resets, the table includes an extra row named default_reset_definition for the default reset definitions.

You can change the default reset values or manually assign resets by using the specifyReset object function.

See the full table contents by calling the portInterface object function.

UnusedPorts — Display unused ports

table

This property is read-only.

Unused ports, displayed as a table. See the full table contents by calling the portInterface object function.

The default is an empty table and the workflow determines the unused ports. Ports that match the unused regular expression are considered unused.

You can explicitly label ports as unused by using the specifyUnused object function.

Object Functions

portInterface	Display port specifications
runWorkflow	Execute cosimulation workflow and generate required artifacts
specifyClock	Assign clock ports to cosimulation block or System object
specifyInput	Assign HDL input ports to cosimulation block or System object
specifyOutput	Assign HDL output ports to cosimulation block or System object
specifyReset	Assign reset ports to cosimulation block or System object
specifyUnused	Label HDL ports as unused ports

Examples

Command-Line Workflow for Verifying Raised Cosine Filter in Simulink

This example shows how to cosimulate a raised cosine filter in Simulink® using the command-line interface. It follows the same workflow to generate cosimulation artifacts as in Get Started with Simulink HDL Cosimulation, but it uses the command line instead of the Cosimulation Wizard.

Configure Cosimulation Workflow

Create a cosimulation configuration object.

c =  cosimulationConfiguration('ModelSim','Simulink','rcosflt_rtl');

Set up the HDL file.

c.HDLFiles = {'./rcosflt_rtl.v','Verilog'};

Set the filter_out port as an output with a signed fixed-point data-type, and set the fraction length to 29.

specifyOutput(c,'filter_out',Datatype='Fixedpoint',Signed=true,FractionLength=29)

Set the clock to a period of 20 ns, and set the reset duration to 15 ns.

specifyClock(c,'clk',Period=20)
specifyReset(c,'reset',Duration=15)

Display the port table. It reflects the settings just made for output, clock, and reset attributes. The other design ports will take on default attributes.

portInterface(c);

----- Input Data Ports -----
  0×1 empty table

    Name
    ____



----- Output Data Ports -----
  2×5 table

                Name                 SampleTime       DataType       Signed    FractionLength
    _____________________________    __________    ______________    ______    ______________

    {'default_output_definition'}        1         {'Inherit'   }    true             0      
    {'filter_out'               }        1         {'Fixedpoint'}    true            29      


----- Clock Ports -----
  2×3 table

                Name                   Edge       Period
    ____________________________    __________    ______

    {'default_clock_definition'}    {'Rising'}      10  
    {'clk'                     }    {'Rising'}      20  


----- Reset Ports -----
  2×3 table

                Name                InitialValue    Duration
    ____________________________    ____________    ________

    {'default_reset_definition'}         1              8   
    {'reset'                   }         1             15   


----- Unused Ports -----
  0×1 empty table

    Name
    ____

Generate HDL Cosimulation Block

Run the workflow to generate an HDL Cosimulation block and the accompanying files.

runWorkflow(c);

-------------------- Step 1------------------
Select the type of cosimulation you want to do. If the HDL simulator executable you want to use is not on the system path in your environment, you must specify its location.
-------------------- Step 2------------------
Add all VHDL, Verilog, and/or script files to be used in cosimulation to the following table. If the file type cannot be automatically detected or the detection result is incorrect, specify the correct file type in the table. If possible, we will determine the compilation order automatically using HDL simulator provided functionality. Then the HDL files can be added in any order.
-------------------- Step 3------------------
HDL Verifier has automatically generated the following HDL compilation commands. You can customize these commands with optional parameters as specified in the HDL simulator documentation but they are sufficient as shown to compile your HDL code for cosimulation. The HDL files will be compiled when you click Next.
Compiling HDL files. Please wait ...
### Compiling HDL design
Reading pref.tcl 
 
# 2023.2 
 
# Create design library 
vlib work 
# Create and open project 
project new . compile_project 
# Loading project compile_project 
project open compile_project 
# Add source files to project 
set SRC1 "." 
# . 
project addfile "$SRC1/rcosflt_rtl.v" 
# Calculate compilation order 
project calculateorder 
# QuestaSim-64 vlog 2023.2 Compiler 2023.04 Apr 11 2023 
# Start time: 14:10:53 on Mar 18,2024 
# vlog -work work -vopt C:/Users/user/OneDrive - MathWorks/Documents/MATLAB/ExampleManager/user.Bdoc.j2534643/hdlverifier-ex80882452/rcosflt_rtl.v  
# -- Compiling module rcosflt_rtl 
#  
# Top level modules: 
# 	rcosflt_rtl 
# End time: 14:10:54 on Mar 18,2024, Elapsed time: 0:00:01 
# Errors: 0, Warnings: 0 
# Compile of rcosflt_rtl.v was successful. 
# All compile dependencies have been resolved. 
set compcmd [project compileall -n] 
# vlog -work work -vopt -stats=none {C:/Users/user/OneDrive - MathWorks/Documents/MATLAB/ExampleManager/user.Bdoc.j2534643/hdlverifier-ex80882452/rcosflt_rtl.v} 
# Close project 
project close 
# reading E:/share/apps/HDLTools/ModelSim/questasim-2023.2/Windows/win64/../modelsim.ini 
# Compile all files and report error 
if [catch {eval $compcmd}] { 
    exit -code 1 
} 
# QuestaSim-64 vlog 2023.2 Compiler 2023.04 Apr 11 2023 
# -- Compiling module rcosflt_rtl 
#  
# Top level modules: 
# 	rcosflt_rtl 
#  
# <EOF> 
...done
-------------------- Step 4------------------
Specify the name of the HDL module for cosimulation. The Cosimulation Wizard will launch the HDL simulator, load the specified module, and populate the port list of that HDL module before the next step. Use "Shared Memory" communication method if your firewall policy does not allow  TCP/IP socket communication.
Elaborating and Loading HDL simulation image. Please wait ...
Waiting for HDL Simulator to startup ...
120 seconds to time-out ...
To stop this process, press Ctrl+C in MATLAB console.
Waiting for HDL Simulator to startup ...
119 seconds to time-out ...
To stop this process, press Ctrl+C in MATLAB console.
Waiting for HDL Simulator to startup ...
118 seconds to time-out ...
To stop this process, press Ctrl+C in MATLAB console.
Waiting for HDL Simulator to startup ...
117 seconds to time-out ...
To stop this process, press Ctrl+C in MATLAB console.
Waiting for HDL Simulator to startup ...
116 seconds to time-out ...
To stop this process, press Ctrl+C in MATLAB console.
Waiting for HDL Simulator to startup ...
115 seconds to time-out ...
To stop this process, press Ctrl+C in MATLAB console.
Waiting for HDL Simulator to startup ...
114 seconds to time-out ...
To stop this process, press Ctrl+C in MATLAB console.
Generated a new parameter file named 'parameter_rcosflt_rtl.cfg'. Edit the file to reflect your desired parameter settings.
...done
-------------------- Step 5------------------
Specify all input and output port types. Input signals that are identified as 'Clock' and 'Reset' signals will be forced in the HDL simulator through Tcl commands. You can specify the timing parameters for forced 'Clock' and 'Reset' signals in the next step. If you want to drive your HDL clock and reset signals with Simulink signals, mark them as 'Input'.
-------------------- Step 6------------------
Set the sample time and data type for each output port. You can specify the sample time as -1, which means that it will be inherited via back propagation in the Simulink model. Back propagation may fail in certain circumstances; click Help for details.
-------------------- Step 7------------------
Set clock and reset parameters here. The time in these tables refers to time in the HDL simulator.
Please wait while generating waveforms.
...done
-------------------- Step 8------------------
The diagram below shows the current settings for forced 'Clock' and 'Reset' signals. The red line represents the time in the HDL simulation at which MATLAB/Simulink will start (i.e. cosimulation will start).

To change the MATLAB/Simulink start time relative to the HDL simulation time, enter the new start time below. To avoid a race condition, make sure the start time does not coincide with the active edge of any clock signal. You can do so by moving the start time or by changing the clock active edge in the previous step (click Back).
-------------------- Step 9------------------
When you click Finish, the Cosimulation Wizard performs the following actions:
 - Creates and opens a new Simulink model containing an HDL Cosimulation block configured to your specifications.
 - Generates the scripts to compile your HDL code and launch the HDL simulator according to the choices you made with this assistant.
 - (If you check the box below) Configures the HDL Cosimulation block to assist you in setting the simulation timescale when you cosimulate with the generated block for the first time. If you do not check the box below, the timescale is set to the default of 1 Simulink second = 1 second in the HDL simulator, or you may change it below.
Generating blocks ... Please wait.
...done

The workflow executes the steps and generates a Simulink model named hdlverifier_wizard_rcosflt_rtl.slx, which includes an HDL Cosimulation block and two additional blocks for compilation and communication with the HDL simulator.

Open the provided testbench model.

open_system('rcosflt_tb.slx')

Drag the generated HDL Cosimulation block to the canvas, and connect its inputs and outputs to the testbench. Your model now looks similar to the following figure.

Run Cosimulation and Verify HDL Design

1. Start the HDL simulator by double-clicking the block labeled Launch HDL Simulator.

2. When the HDL simulator is ready, return to Simulink and start the simulation.

3. Determine timescale. Since the AutoTimeScale property is set to automatically determine the timescale at start of simulation, HDL Verifier launches the Timescale Details graphical interface instead of starting the simulation. Both the HDL simulator and Simulink sample the filter_in and filter_out ports at 1 second. However, their sample time in the HDL simulator should be the same as the clock period (20 ns). Change the Simulink sample time of /rcosflt_rtl/clk to 1 (seconds), and press Enter. The wizard then updates the table. The following figure shows the new timescale: 1 second in Simulink corresponds to 2e-008 s in the HDL simulator.

4. Click OK to close the Timescale Details dialog box. Restart the Simulink simulation and verify the results from the scope in the testbench model.

The scope displays both the delayed version of input to the raised cosine filter and that filter's output. If you sample the output of this filter directly, no inter-symbol-interference occurs.

Version History

Introduced in R2022b

R2024a: New HDLParameterFile property

Import a parameterized HDL design. Specify or edit a parameter file to set values for HDL parameters.