Main Content

Set Up for HDL Cosimulation

To cosimulate your HDL code with a MATLAB® or Simulink® design, you must first:

  • Decide how to connect your HDL simulator with MATLAB or Simulink. You may have one or multiple HDL modules in a cosimulation setup. The modules are represented by matlabcp and matlabtb functions or hdlcosimulation system objects for MATLAB, or by HDL Cosimulation blocks for Simulink. See Cosimulation Configurations.

  • Start the HDL simulator from MATLAB, or from a shell. You must use a shell for a cross-network simulation, such as if the HDL simulator runs on a different machine from your MATLAB host. Starting the simulator from MATLAB allows you to specify the library by name rather than exact path. See HDL Simulator Startup.

  • If you require a non-default library or customized library location, specify the library when you start the HDL simulator. If you start the HDL simulator from MATLAB, use the name of the library. If you start the HDL simulator from a shell, use the library path. See Cosimulation Libraries.

  • Optionally, use the configuration and diagnostic script to configure your library location and test the TCP/IP connection. This script is supported only for Linux® machines. For Windows® machines, you can create a configuration file. See HDL Simulator Startup.

Cosimulation Configurations

There are several ways to connect your HDL simulator to a design in MATLAB or Simulink. You can run your HDL simulator on the same or different host machine as MATLAB. Each HDL simulator can connect to one or more functions in MATLAB, or one or more HDL Cosimulation blocks in a Simulink model. In a network configuration, to identify your application servers, use an Internet address and a TCP/IP socket port.

Note

  • Vivado® cosimulation is supported via one HDL Cosimulation block in Simulink or one VivadoHDLCosimulation system object in MATLAB connected to the HDL simulator.

  • An instance of MATLAB can run only one instance of the MATLAB server (hdldaemon) at a time.

  • Each HDL simulator must communicate with a unique instance of the MATLAB server.

  • Shared memory communication is an option for configurations that require only one communication link on a single computing system.

  • TCP/IP socket communication is required for configurations that use multiple communication links on one or more computing systems. Unique TCP/IP socket ports distinguish the communication links.

Valid Configurations for HDL Cosimulation with MATLAB

An HDL simulator session connected to a MATLAB function through a single instance of the MATLAB server. One hdlcosim function in a MATLAB session, connected to one HDL session.
An HDL simulator session connected to multiple MATLAB functions through a single instance of the MATLAB server. Multiple hdlcosim functions in one MATLAB session, connected to one HDL session.
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 hdlcosim functions, each one in a MATLAB session, all connected to one HDL session.
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. Multiple hdlcosim functions, each one in a MATLAB session, and each MATLAB session is connected to an HDL session.

An hdlcosim System object™ in a MATLAB session connected to a single HDL simulator session.

Note

This configuration is supported for Vivado cosimulation.

hdlcosim System object in a MATLAB session, connected to an HDL Simulator session.

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 one HDL simulation session.

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.

Multiple hdlcosim System objects in a MATLAB session, connected to multiple HDL simulation sessions.

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.

HDL Simulator Startup

You can start the HDL simulator from MATLAB, or from a shell. You must use a shell for a cross-network simulation, such as if the HDL simulator runs on a different machine from your MATLAB host. Starting the simulator from MATLAB allows you to specify the library by name rather than exact path.

Vivado users are not required to start the HDL simulator separately from MATLAB or Simulink, since Vivado cosimulation is executed as one process with a shared DLL.

Set up for Cosimulation with Vivado

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

For Vivado setup on Windows, you must set the following variables. The Cosimulation Wizard ensures you set these variables correctly:

  1. %PATH% must point to Vivado executables (such as vivado, xelab, xvlog, and xvhdl).

  2. %PATH% must point to Vivado libraries (%XILINX_VIVADO%\lib\win64.o).

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

  1. $PATH must point to Vivado executables (the Cosimulation Wizard ensures that you set it properly).

  2. $LD_LIBRARY_PATH must point to Vivado libraries ($XILINX_VIVADO/lib/lnx64.o). This must be done 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.

Note

If you use the Cosimulation Wizard, you do not need to start the HDL simulator separately.

HDL SimulatorCommand to Open the SimulatorExample

Cadence® Xcelium™

nclaunchStart Cadence Xcelium from MATLAB
Mentor Graphics® ModelSim® vsimStart Mentor Graphics ModelSim 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 Test Bench.

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 test bench 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 Mentor Graphics ModelSim from MATLAB.  To start the Mentor Graphics 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 test bench 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 Test Bench.

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 Mentor Graphics 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 Test Bench.

Note

You can also call this command from inside the HDL simulator.

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
Then in ModelSim enter:
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

Cosimulation Libraries

It is recommended to use the same compiler for all libraries linked into the same executable. HDL Verifier versions of the library for the compilers that the HDL simulators support. Using the same libraries helps the cosimulation software stay compatible with other C++ libraries that you might link into the HDL simulator, including SystemC libraries.

If any of these conditions apply, choose the version of the HDL Verifier library that matches the compiler used for that code:

  • You link other third-party applications into your HDL simulator.

  • You compile and link SystemC code as part of your design or test bench.

  • You link custom C/C++ applications into your HDL simulator.

If you do not link any other code into your HDL simulator, you can use any version of the supplied libraries. The function for opening the HDL simulator (nclaunch or vsim) chooses a default version of this library.

For examples on specifying HDL Verifier libraries when cosimulating across a network, see Cross-Network Cosimulation.

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}
 
ArgumentXcelium ValuesModelSim Values
versionincisivemodelsim
archlinux64linux64, windows32, or windows64
version_short_name lfihdllfmhdl
client_server_tagMATLAB: c
Simulink: s
MATLAB: c
Simulink: s
compiler_taggcc41, gcc44, gcc48

Linux: gcc433, gcc450, gcc474
Windows 32: gcc421vc12
Windows 64: gcc450vc12, tmwvs

Note

gcc450vc12 or gcc421vc12 requires Visual Studio® 2013 redistribute, available from Microsoft®.

libextsodll or so

Not all combinations are supported. See Default Libraries for valid combinations.

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

Default Libraries

HDL Verifier scripts fully support the use of default libraries. The table lists the libraries shipped with HDL Verifier for each supported HDL simulator. The default libraries for each platform are in bold text.

Cadence Xcelium Libraries

PlatformMATLAB LibrarySimulink Library
Linux 64

liblfihdlc_gcc41.so
liblfihdlc_gcc44.so
liblfihdlc_gcc48.so

liblfihdls_gcc41.so
liblfihdls_gcc44.so
liblfihdls_gcc48.so

Mentor Graphics ModelSim Libraries

PlatformMATLAB LibrarySimulink Library
Linux 64

liblfmhdlc_gcc433.so
liblfmhdlc_gcc474.so
liblfmhdls_gcc450.so

liblfmhdls_gcc433.so
liblfmhdls_gcc474.so
liblfmhdls_gcc450.so

Windows 32

liblfmhdlc_gcc421vc12.dll

liblfmhdls_gcc421vc12.dll

Windows 64liblfmhdlc_tmwvs.dll
liblfmhdlc_gcc450vc12.dll
liblfmhdls_tmwvs.dll
liblfmhdls_gcc450vc12.dll

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:

  1. Copy the system libraries from the MATLAB installation to the machine with the HDL simulator. The system libraries are installed in matlabroot/sys/os.

  2. Modify the LD_LIBRARY_PATH environment variable to add the path to the copied system libraries.

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_gcc44');

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

exec ldd /path/to/matlab/toolbox/edalink/extensions/incisive/linux64/liblfihdls_gcc44.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_gcc44: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 Mentor Graphics. 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 Mentor Graphics.

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.

See Also

Functions

Blocks

Related Topics