Valid Configurations for HDL Cosimulation with MATLAB

An HDL simulator session connected to a MATLAB function through a single instance of the MATLAB server.
An HDL simulator session connected to multiple MATLAB functions through a single instance of the MATLAB server.
An HDL simulator session connected to a MATLAB function through multiple instances of the MATLAB server. Each instance runs within the scope of a unique MATLAB session). This configuration is not supported by the Cosimulation Wizard.
Multiple HDL simulator sessions, each connected to a MATLAB function through multiple instances of the MATLAB server. Each instance runs within the scope of a unique MATLAB session.
An hdlcosim System object™ in a MATLAB session connected to a single HDL simulator session. Note This configuration is supported for Vivado cosimulation.
Multiple hdlcosim system objects in a MATLAB session connected to the same HDL simulator session. This configuration is not supported by the Cosimulation Wizard. You can combine multiple HDL modules into a higher level module to include them in a single HDL Cosimulation System object.
Multiple hdlcosim System objects in a MATLAB session connected to different HDL simulator sessions. hdlcosim System objects in a MATLAB session can connect to the same or different HDL simulator sessions. Each hdlcosim System object can communicate with only one HDL simulator.

Valid Configurations for Cosimulation with Simulink

An HDL Cosimulation block in a Simulink model connected to a single HDL simulator session. Note This configuration is supported for Vivado cosimulation.
Multiple HDL Cosimulation blocks in a Simulink model connected to the same HDL simulator session. This configuration is not supported by the Cosimulation Wizard. You can combine multiple HDL modules into a higher level module to include them in a single HDL Cosimulation block.
Multiple HDL Cosimulation blocks in a Simulink model connected to different HDL simulator sessions. HDL Cosimulation blocks in a Simulink model can connect to the same or different HDL simulator sessions. Each HDL Cosimulation block can communicate with only one HDL simulator.

Set up for Cosimulation with Vivado

When using the Vivado simulator you must first use the Cosimulation Wizard or HDL Workflow Advisor to create an HDL Cosimulation block or an hdlverifier.VivadoHDLCosimulation System object.

Use the Cosimulation Wizard to generate cosimulation artifacts when you already have an HDL DUT. Use the HDL Workflow Advisor to generate an HDL DUT (requires HDL Coder™), in addition to cosimulation artifacts.

For Vivado setup on Windows, you must set the following variables. If you are using the Cosimulation Wizard, it ensures you set these variables correctly:

For Vivado setup on Linux, you must set these variables before starting MATLAB:

To set $LD_LIBRARY_PATH on Linux, perform the following in a csh shell prompt:

csh> setenv LD_LIBRARY_PATH /tools/Vivado/2020.2-mw-0/Lin/Vivado/2020.2/lib/lnx64.o:$LD_LIBRARY_PATH
csh> matlab

For other shell types, enter the following:

sh> export LD_LIBRARY_PATH=/tools/Vivado/2020.2-mw-0/Lin/Vivado/2020.2/lib/lnx64.o:$LD_LIBRARY_PATH
sh> matlab

Alternatively, create a /etc/ld.so.conf.d/xilvivado.conf file and then invoke it using ldconfig (requires root privileges). File contents:

# to automatically find Xilinx Vivado libraries from MATLAB applications such as HDL Cosimulation using HDL Verifier.
# (despite the name, this is a folder that holds linux *libraries*)
# reload updates to this file via: sudo ldconfig
/tools/Vivado/2020.2-mw-0/Lin/Vivado/2020.2/lib/lnx64.o

Then invoke it by executing:

sh> sudo ldconfig

Start the HDL Simulator from MATLAB

Each supported HDL simulator has a unique command that opens it from MATLAB.

In either function, you can specify the HDL Verifier library, the design to load, the type of communication connection information and other required parameters as name-value pair arguments. No special setup is required. See Cosimulation Libraries.

This function starts and configures the HDL simulator for use with the HDL Verifier™ software. By default, the function starts the first version of the simulator executable that it finds on the system path, as defined by the path variable. This function uses a temporary file that is overwritten each time the HDL simulator starts.

You can customize the startup file and communication mode to be used between MATLAB or Simulink and the HDL simulator by specifying name-value pairs when you call the function. For property details, see nclaunch or vsim.

To start a different version of the simulator executable than the first one found on the system path, use the setenv and getenv MATLAB functions to set and get the environment of any subshells spawned by UNIX(), DOS(), or system().

If you specify a communication mode when you call one of the functions that open the HDL simulator, the specified mode applies to all HDL simulator sessions connected to either MATLAB or Simulink.

For more information on how HDL Verifier links the HDL simulator with MATLAB, see Linking with MATLAB and the HDL Simulator.

For a full cosimulation example that demonstrates starting the HDL simulator from MATLAB, see Verify HDL Module with MATLAB Testbench.

Start Cadence Xcelium from MATLAB.  To start the Cadence Xcelium simulator from MATLAB, at the MATLAB command prompt, enter:

nclaunch('PropertyName', 'PropertyValue', ...)

This example changes the folder location to VHDLproj and then opens Xcelium. Because the command line omits the 'hdlsimdir' and 'startupfile' properties, nclaunch creates a temporary file. The 'tclstart' property specifies Tcl commands that load and initialize the HDL simulator for testbench instance modsimrand.

cd VHDLproj
nclaunch('tclstart',...
 'hdlsimmatlab modsimrand; matlabtb modsimrand 10 ns -socket 4449')

This example changes the folder location to VHDLproj and then opens Xcelium. Because the function call omits the 'hdlsimdir' and 'startupfile' properties, nclaunch creates a temporary file. The 'tclstart' property specifies a Tcl command that loads the VHDL^® entity parse in library work for cosimulation between nclaunch and Simulink. The 'socketsimulink' property specifies TCP/IP socket communication on the same computer, using port 4449.

cd VHDLproj
nclaunch('tclstart', 'hdlsimulink work.parse', 'socketsimulink', '4449')

Start Siemens ModelSim from MATLAB.  To start the Siemens ModelSim HDL simulator from MATLAB, at the MATLAB command prompt, enter:

vsim('PropertyName','PropertyValue', ...)

This example changes the folder location to VHDLproj and then opens ModelSim. Because the vsim call omits the 'vsimdir' and 'startupfile' properties, the function creates a temporary DO file. The 'tclstart' property specifies Tcl commands that load and initialize the HDL simulator for testbench instance modsimrand.

cd VHDLproj
vsim('tclstart','vsimmatlab modsimrand; matlabtb modsimrand 10 ns -socket 4449')

This example changes the folder location to VHDLproj and then opens ModelSim. Because the vsim call omits the 'vsimdir' and 'startupfile' properties, vsim creates a temporary DO file. The 'tclstart' property specifies a Tcl command that loads the VHDL entity parse in library work for cosimulation between vsim and Simulink. The 'socketsimulink' property specifies TCP/IP socket communication on the same computer, using socket port 4449.

cd VHDLproj
vsim('tclstart','vsimulink work.parse','socketsimulink','4449')

This example includes Tcl commands that run HDL compilation and simulation when the ModelSim software starts up.

vsim('tclstart',{'vlib work','vlog +acc clocked_inverter.v hdl_top.v','vsim +acc hdl_top'});

This example loads the hdl_top module for Simulink cosimulation. The vsimulink command also specifies socket number 5678 for communication with HDL Cosimulation blocks in Simulink models, and specifies an HDL time precision of 10 ps. Specifying the socket this way is equivalent to using the socketsimulink property of the vsim function.

vsim('tclstart', …
             {'vlib work', 'vlog -voptargs=+acc clocked_inverter.v hdl_top.v', …
              'vsimulink hdl_top -socket 5678 -t 10ps'});

Start the HDL Simulator from a Shell

When you start the HDL simulator from a shell, you must first create a Tcl setup file for the HDL simulator. The setup file includes the location of the specified cosimulation libraries for MATLAB and Simulink. You can then include this file when you start your HDL simulator.

For more information on cosimulation libraries, see Cosimulation Libraries.

After you have created your Tcl setup file, you can edit it to add compilation and execution commands.

Start Cadence Xcelium from a Shell.  Generate a setup file by using the nclaunch function at the MATLAB prompt.

nclaunch('starthdlsim','no','startupfile','cosim_procdefs.tcl','tclstart',{''})

This creates a Tcl setup file named cosim_procdefs.tcl, which contains definitions for functions that enable cosimulation with MATLAB or Simulink.

Now, load this generated setup file when you start Xcelium. In a shell prompt, enter the following.

xmsim design_name -64bit -input setupfile

Where design_name is the name of your top level design and setupfile is the name of the Tcl setup file (cosim_procdefs.tcl in this example, or compile_and_launch.tcl by default). For an example that uses a Tcl setup file, see Cosimulation for Testing Filter Component Using MATLAB Testbench.

Once the simulator is launched, use the hdlsimmatlab function to load the HDL module, and the matlabtb or matlabcp function to connect to a MATLAB function. For example, to compile and launch Xcelium enter the following commands in a shell (assuming the Tcl script is named cosim_procdefs.tcl).

xmvlog -64bit cosim_lowpass_filter.v
xmelab -64bit -access +wc cosim_lowpass_filter
xmsim cosim_lowpass_filter -64bit -input cosim_procdefs.tcl

Then in Xcelium enter:

matlabtb cosim_lowpass_filter 10ns -repeat 10ns -mfunc cosim_lowpass_filtertb
force cosim_lowpass_filter.clk_enable 1 -after 0ns
force cosim_lowpass_filter.reset 1 -after 0ns 0 -after 22ns
force cosim_lowpass_filter.clk 1 -after 0ns 0 -after 5ns -repeat 10ns
deposit cosim_lowpass_filter.filter_in 0
run 10000ns

Start Siemens ModelSim from a Shell.  Generate a setup file by using the vsim function at the MATLAB prompt.

vsim('startms','no','startupfile','cosim_procdefs.tcl')

This creates a Tcl setup file named cosim_procdefs.tcl, which contains definitions for functions that enable cosimulation with MATLAB or Simulink.

Now, use this generated configuration file when you Start the HDL Simulator from a Shell.

Now, load this generated setup file when you start ModelSim. In a shell prompt, enter the following.

vsim design_name -do setupfile

setupfile is the name of the Tcl setup file (cosim_procdefs.tcl in this example, or compile_and_launch.tcl by default). When you include the design_name argument, the vsim call also starts the simulation.

The configuration file defines the -foreign option to vsim. This option loads the HDL Verifier shared library and specifies its entry point. You can also specify any other existing configuration files you are using.

If you do not use the generated config file, you can load the client shared library and specify its entry point by executing vsim with a command like this:

vsim design_name -foreign matlabclient /path/library

where path is the path to the HDL Verifier cosimulation library. See Cosimulation Libraries to find the applicable library name for your machine. For an example that uses a Tcl configuration file, see Cosimulation for Testing Filter Component Using MATLAB Testbench.

Once the simulator is launched, use the vsimmatlab function to load the HDL module, and the matlabtb or matlabcp function to connect to a MATLAB function. For example, to compile and launch ModelSim enter the following commands in a shell (assuming the Tcl script is named cosim_procdefs.tcl):

vlib work
vlog cosim_lowpass_filter.v
vsim -c -do cosim_procdefs.tcl

vsimmatlab work.cosim_lowpass_filter
matlabtb cosim_lowpass_filter 10ns -repeat 10ns -mfunc cosim_lowpass_filtertb.m
force clk_enable 1 0
force reset 1 0, 0 25
force clk 1 0, 0 5 -repeat 10
run 10000ns

Library Naming Format

The HDL Verifier cosimulation libraries use the following naming format:

edalink/extensions/{version}/{arch}/lib{version_short_name}{client_server_tag}_{compiler_tag).{libext}
 

For more on MATLAB build compilers, see MATLAB Build Compilers.

Default Libraries

The HDL Verifier scripts support the use of libraries compiled with versions of GCC supplied by the HDL tool vendors. The table lists the libraries shipped with HDL Verifier for each supported HDL simulator.

The default library is tmwgcc or tmwvs versions. Specify an alternative with the libfile argument to vsim or nclaunch.

Alternative HDL Simulator Libraries

You can use a different HDL-side library by specifying the libfile name-value pair when you call the nclaunch or vsim function. Choose the version of the library that matches the compiler and system libraries you are using for any other C/C++ libraries linked into the HDL simulator. Depending on the version of your HDL simulator, you might need to explicitly set additional paths in the LD_LIBRARY_PATH environment variable.

For example, to use a nondefault library:

Specify Alternate Library Using nclaunch.  This example shows library settings for an HDL simulation that links in a custom C++ application, compiled with gcc44. Therefore, the simulator must use the cosimulation libraries compiled with gcc44, instead of using the default library. Both MATLAB and Xcelium are running on the same 64-bit Linux machine.

Modify the PATH variable so that the nclaunch function finds the desired version of the HDL simulator. Then, specify the library name with the libfile name-value pair. At the MATLAB command prompt, type:

currPath = getenv('PATH');
setenv('PATH',['/tools/IUS-1110/bin:' currPath]);
nclaunch('tclstart',{'exec xmvhdl -64bit inverter.vhd', ...
                     'exec xmelab -64bit -access +rwc inverter', ...
                     'hdlsimulink -gui inverter' }, ...
                     'libfile','liblfihdls_gcc48');

Verify the library resolution using ldd from within the xmsim console.

exec ldd /path/to/matlab/toolbox/edalink/extensions/incisive/linux64/liblfihdls_gcc48.so
        linux-vdso.so.1 =>  (0x00007fff2ffff000)
        libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007f98361a0000)
        libstdc++.so.6 => /usr/lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007f9835e99000)
        libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007f9835c16000)
        libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007f9835a00000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f9835676000)
        /lib64/ld-linux-x86-64.so.2 (0x00007f983661c000)

Specify Alternate Library for Xcelium Using System Shell.  This example shows how to start Xcelium with an explicit option to specify the cosimulation library. You can start Xcelium from a system shell on the same machine as MATLAB, on a different machine, or on a machine with a different operating system.

This example code runs on a 64-bit Linux version of Xcelium. It does not matter what machine MATLAB is running on. Instead of using the default library in the Xcelium distribution, this example uses the library compiled with GCC 4.4.

Modify the PATH variable to point to the desired version of the HDL simulator. Although xmsim finds any GCC libraries in the installation, this example changes the LD_LIBRARY_PATH to show how to use a custom installation of GCC. In a csh-compatible system shell, enter:

setenv PATH /tools/ius/lnx/tools/bin/64bit:${PATH}
setenv LD_LIBRARY_PATH /tools/ius/lnx/tools/systemc/gcc/4.4-x86_64/install/lib64:${LD_LIBRARY_PATH}
xmvhdl -64bit inverter.vhd
xmelab -64bit -access +rwc inverter
xmsim -tcl -loadvpi /tools/matlab/toolbox/edalink/extensions/incisive/linux64/liblfihdlc_gcc48:matlabclient inverter.vhd

You can check the library resolution using ldd, as in the previous example.

Specify Alternate Library Using vsim.  This example shows library settings for an HDL simulation that uses some SystemC applications, compiled with gcc450. You can download this version of GCC with its associated system libraries from Siemens. Therefore, the simulator must use the cosimulation libraries compiled with gcc450, instead of using the default library. Both MATLAB and ModelSim are running on the same 64-bit Linux machine.

Modify the PATH variable so that the vsim function finds the desired version of the HDL simulator. Modify theLD_LIBRARY_PATH because the HDL simulator does not add the path to the system libraries. Then, specify the library name with the libfile name-value pair. At the MATLAB command prompt, type:

currPath = getenv('PATH');
currLdPath = getenv('LD_LIBRARY_PATH');
setenv('PATH',['/tools/modelsim-10.1c/bin:' currPath]);
setenv('LD_LIBRARY_PATH',['/tools/modelsim-10.1c/gcc-4.5.0-linux/lib:' currLdPath]);
vsim('tclstart',{'vlib work','vcom inverter.vhd','vsimulink inverter'}, ...
       'libfile','liblfmhdls_gcc450');

Verify the library resolution using ldd from within the vsim GUI.

exec ldd /path/to/matlab/toolbox/edalink/extensions/modelsim/linux64/liblfmhdls_gcc450.so 
        linux-vdso.so.1 =>  (0x00007fff06652000)
        libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007f505083d000)
        libstdc++.so.6 => /usr/lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007f5050536000)
        libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007f50502b3000)
        libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007f505009d000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f504fd13000)
        /lib64/ld-linux-x86-64.so.2 (0x00007f5050cb8000)

Specify Alternate ModelSim Library Using System Shell.  This example shows how to start ModelSim with an explicit option to specify the cosimulation library. You can start ModelSim from a system shell on the same machine as MATLAB, on a different machine, or on a machine with a different operating system.

This example code runs on a 64-bit Linux version of ModelSim. It does not matter what machine MATLAB is running on. Instead of using the default library in the ModelSim distribution, this example uses the library compiled with GCC 4.5.0. You can download this version of GCC with its associated system libraries from Siemens.

Modify the PATH variable to point to the desired version of the HDL simulator. Modify theLD_LIBRARY_PATH because the HDL simulator does not add the path to the system libraries, unless you saved the GCC at the root of the ModelSim installation. In a csh-compatible system shell, enter:

setenv PATH /tools/questasim/bin:${PATH}
setenv LD_LIBRARY_PATH /tools/mtigcc/gcc-4.5.0-linux_x86_64/lib64:${LD_LIBRARY_PATH}
setenv MTI_VCO_MODE 64
vlib work
vcom +acc+inverter inverter.vhd
vsim +acc+inverter -foreign \
     "matlabclient /tools/matlab/toolbox/edalink/extensions/modelsim/linux64/liblfmhdlc_gcc450.so" \
      work.inverter

You can check the library resolution using ldd, as in the previous example.