Tutorial - Running a Sample ModelSim and MATLAB Test Bench Session :: Simulating an HDL Component in a MATLAB Test Bench Environment (EDA Simulator Link™)

Learn more about EDA Link Simulator

Tutorial – Running a Sample ModelSim and MATLAB Test Bench Session

On this page…
Tutorial Overview Setting Up Tutorial Files Starting the MATLAB Server Setting Up the ModelSim Simulator Developing the VHDL Code Compiling the VHDL File Loading the Simulation Developing the MATLAB Function Running the Simulation Shutting Down the Simulation

On this page…

Tutorial Overview

Setting Up Tutorial Files

Starting the MATLAB Server

Setting Up the ModelSim Simulator

Developing the VHDL Code

Compiling the VHDL File

Loading the Simulation

Developing the MATLAB Function

Running the Simulation

Shutting Down the Simulation

Tutorial Overview

This chapter guides you through the basic steps for setting up an EDA Simulator Link application that uses MATLAB to verify a simple HDL design. In this tutorial, you develop, simulate, and verify a model of a pseudorandom number generator based on the Fibonacci sequence. The model is coded in VHDL.

Note This tutorial requires MATLAB, the ModelSim HDL simulator, and the EDA Simulator Link software.

Setting Up Tutorial Files

To ensure that others can access copies of the tutorial files, set up a folder for your own tutorial work:

Create a folder outside the scope of your MATLAB installation folder into which you can copy the tutorial files. The folder must be writable. This tutorial assumes that you create a folder named MyPlayArea.

Copy the following files to the folder you just created:

matlabroot\toolbox\edalink\extensions\modelsim\modelsimdemos\modsimrand_plot.m
matlabroot\toolbox\edalink\extensions\modelsim\modelsimdemos\VHDL\modsimrand\
		modsimrand.vhd

Starting the MATLAB Server

This section describes starting MATLAB, setting up the current folder for completing the tutorial, starting the product's MATLAB server component, and checking for client connections, using the server's TCP/IP socket mode. These instructions assume you are familiar with the MATLAB user interface.

Perform the following steps:

Start MATLAB.
Set your MATLAB current folder to the folder you created in Setting Up Tutorial Files.
Check whether the MATLAB server is running. To do so, call the function hdldaemon with the 'status' option in the MATLAB Command Window as shown here:
```
hdldaemon('status')
```
If the server is not running, the function displays
```
HDLDaemon is NOT running
```
If the server is running in TCP/IP socket mode, the message reads
```
HDLDaemon socket server is running on Port portnum with 0 connections
```
If the server is running in shared memory mode, the message reads
```
HDLDaemon shared memory server is running with 0 connections
```
If the server is not currently running, skip to step 5. If the server is currently running, shut down the server by typing
```
hdldaemon('kill')
```
The following message appears, confirming that the server was shut down.
```
HDLDaemon server was shut down
```
The next step is to start the server in TCP/IP socket mode. To do so, call hdldaemon with the property name/property value pair 'socket' 0. The value 0 specifies that the operating system assign the server a TCP/IP socket port that is available on your system. For example
```
hdldaemon('socket', 0)
```
The server informs you that it has started by displaying the following message. The portnum will be specific to your system:
```
HDLDaemon socket server is running on Port portnum with 0 connections
```
Other options that you can specify in the hdldaemon function call include the following:
- Shared memory communication instead of TCP/IP socket communication
- Whether time will be returned as scaled or a 64-bit integer
For details on how to specify the various options, see the description of hdldaemon.

Setting Up the ModelSim Simulator

This section describes the basic procedure for starting the ModelSim software and setting up a ModelSim design library. These instructions assume you are familiar with the ModelSim user interface.

Perform the following steps:

Start ModelSim from the MATLAB environment by calling the function vsim in the MATLAB Command Window.
```
vsim
```
This function launches and configures ModelSim for use with the EDA Simulator Link software. The first folder of ModelSim matches your MATLAB current folder.
Verify the current ModelSim folder. You can verify that the current ModelSim folder matches the MATLAB current folder by entering the ls command in the ModelSim command window.

The command should list the files modsimrand.vhd, modsimrand_plot.m, and transcript.
Create a design library to hold your demo compilation results. To create the library and required _info file, enter the vlib and vmap commands as follows:
```
ModelSim> vlib work

ModelSim> vmap work work
```

Developing the VHDL Code

After setting up a design library, typically you would use the ModelSim Editor to create and modify your HDL code. For this tutorial, open and examine the existing file modsimrand.vhd. This section highlights areas of code in modsimrand.vhd that are of interest for a ModelSim and MATLAB test bench:

Open modsimrand.vhd in the edit window with the edit command, as follows:
```
ModelSim> edit modsimrand.vhd
```
ModelSim opens its edit window and displays the VHDL code for modsimrand.vhd.
Search for ENTITY modsimrand. This line defines the VHDL entity modsimrand:
```
ENTITY modsimrand IS
PORT (
  clk     : IN std_logic ;
  clk_en  : IN std_logic ;
  reset   : IN std_logic ;
  dout    : OUT std_logic_vector (31 DOWNTO 0);
END modsimrand;
```
This entity will be verified in the MATLAB environment. Note the following:
- By default, the MATLAB server assumes that the name of the MATLAB function that verifies the entity in the MATLAB environment is the same as the entity name. You have the option of naming the MATLAB function explicitly. However, if you do not specify a name, the server expects the function name to match the entity name. In this example, the MATLAB function name is modsimrand_plot and does not match.
- The entity must be defined with a PORT clause that includes at least one port definition. Each port definition must specify a port mode (IN, OUT, or INOUT) and a VHDL data type that is supported by the EDA Simulator Link software. For a list of the supported types, see Code HDL Modules for Verification Using MATLAB .
  The entity modsimrand in this example is defined with three input ports clk, clk_en, and reset of type STD_LOGIC and output port dout of type STD_LOGIC_VECTOR. The output port passes simulation output data out to the MATLAB function for verification. The optional input ports receive clock and reset signals from the function. Alternatively, the input ports can receive signals from ModelSim force commands.
  For more information on coding port entities for use with MATLAB, see Code HDL Modules for Verification Using MATLAB .
Browse through the rest of modsimrand.vhd. The remaining code defines a behavioral architecture for modsimrand that writes a randomly generated Fibonacci sequence to an output register when the clock experiences a rising edge.
Close the ModelSim edit window.

Compiling the VHDL File

After you create or edit your VHDL source files, compile them. As part of this tutorial, compile modsimrand.vhd. One way of compiling the file is to click the file name in the project workspace and select Compile > Compile All. Another alternative is to specify modsimrand.vhd with the vcom command, as follows:

ModelSim> vcom modsimrand.vhd

If the compilation succeeds, informational messages appear in the command window and the compiler populates the work library with the compilation results.

Loading the Simulation

After you successfully compile the VHDL source file, you are ready to load the model for simulation. This section explains how to load an instance of entity modsimrand for simulation:

Load the instance of modsimrand for verification. To load the instance, specify the vsimmatlab command as follows:
```
ModelSim> vsimmatlab modsimrand
```
The vsimmatlab command starts the ModelSim simulator, vsim, specifically for use with MATLAB. You can specify vsimmatlab with any combination of valid ModelSim vsim command parameters and options.
ModelSim displays a series of messages in the command window as it loads the entity's packages and architecture.

Initialize the simulator for verifying modsimrand with MATLAB. You initialize ModelSim by using the matlabtb or matlabtbeval ModelSim command. These commands define the communication link and a callback to a MATLAB function that executes in MATLAB on behalf of ModelSim. In addition, the matlabtb commands can specify parameters that control when the MATLAB function executes.

For this tutorial, enter the following matlabtb command:

VSIM n> matlabtb modsimrand -mfunc modsimrand_plot 
-rising /modsimrand/clk -socket portnum

Remember that the port number or service name that you specify with -socket must match the port value returned by or specified with the call to hdldaemon that started the MATLAB server.

Arguments in the command line specify the following conditions:

Argument	Specifies
`modsimrand`	The instance of the VHDL entity that is to be associated with a MATLAB function.
`-mfunc modsimrand_plot`	The MATLAB function to be called on behalf of HDL instance `modsimrand`.
`-rising /modsimrand/clk`	That the function `modsimrand_plot.m` be called when the signal `/modsimrand/clk` changes from '`0'` to `'1'`. The signal specification uses a full path name format. If you do not specify a full path name, the command applies ModelSim rules to resolve signal specifications.
`-socket``portnum`	The TCP/IP socket port `portnum` to be used to establish a communication link with MATLAB.

This command links an instance of the entity modsimrand to the function modsimrand_plot.m, which executes within the context of MATLAB based on specified timing parameters. In this case, the MATLAB function is called when the signal /modsimrand/clk experiences a rising edge.

Initialize clock and reset input signals. You can drive simulation input signals using several mechanisms, including ModelSim force commands and an iport parameter (see Syntax of a Test Bench Function). For now, enter the following force commands:
```
VSIM n> force /modsimrand/clk 0 0 ns, 1 5 ns -repeat 10 ns
VSIM n> force /modsimrand/clk_en 1
VSIM n> force /modsimrand/reset 1 0, 0 50 ns
```
The first command forces the clk signal to value 0 at 0 nanoseconds and to 1 at 5 nanoseconds. After 10 nanoseconds, the cycle starts to repeat every 10 nanoseconds. The second and third force commands set clk_en to 1 and reset to 1 at 0 nanoseconds and to 0 at 50 nanoseconds.

The ModelSim environment is ready to run a simulation. Now, you need to set up the MATLAB function.

Developing the MATLAB Function

The EDA Simulator Link software verifies HDL hardware in MATLAB as a function. Typically, at this point you would create or edit a MATLAB function that meets EDA Simulator Link requirements. For this tutorial, open and examine the existing file modsimrand_plot.m.

modsimrand_plot.m is a lower-level component of the MATLAB Random Number Generator Demo. Plotting code within modsimrand_plot.m is not discussed in the next section. This tutorial focuses only on those parts of modsimrand_plot.m that are required for MATLAB to verify a VHDL model.

Perform the following steps:

Open modsimrand_plot.m in the MATLAB Edit/Debug window. For example:
```
edit modsimrand_plot.m
```
Look at line 1. On this line, you specify the MATLAB function name and required parameters:
```
function [iport,tnext] = modsimrand_plot(oport,tnow,portinfo)
```
This function definition is significant because it represents the communication channel between MATLAB and ModelSim. When coding the function definition, consider the following:
- By default, the EDA Simulator Link software assumes the function name is the same as the name of the VHDL entity that it services. However, you can name the function differently, as in this case. The name of the VHDL entity is modsimrand, and the name of the function is modsimrand_plot. Because the names differ, you must explicitly specify the function name when you request service from ModelSim.
- You must define the function with two output parameters, iport and tnext, and three input parameters, oport, tnow, and portinfo.
  For more information on the required MATLAB function parameters, see Process for Coding MATLAB EDA Simulator Link Functions.
- You can use the iport parameter to drive input signals instead of, or in addition to, using other signal sources, such as ModelSim force commands. Depending on your application, you might use any combination of input sources. However, if multiple sources drive signals to a single iport, you will need a resolution function to handle signal contention.
Initialize the function outputs iport and tnext to empty values, as in the following code excerpt:
```
tnext = [];
iport = struct();
```
Make note of the data types of ports defined for the entity under simulation. The EDA Simulator Link software converts VHDL data types to comparable MATLAB data types and vice versa. As you develop your MATLAB function, you must know the types of the data that it receives from and needs to return to ModelSim. This tutorial includes the following port data type definitions and conversions:
- The entity defined for this tutorial consists of three input ports of type STD_LOGIC and an output port of type STD_LOGIC_VECTOR.
- Data of type STD_LOGIC_VECTOR consists of a column vector of characters with one bit per character.
- The interface converts scalar data of type STD_LOGIC to a character that matches the character literal for the corresponding enumerated type.
For more information on interface data type conversions, see Performing Data Type Conversions.
Search for oport.dout. This line of code shows how the data that a MATLAB function receives from ModelSim might need to be converted for use in the MATLAB environment:
```
ud.buffer(cyc) = mvl2dec(oport.dout)
```
In this case, the function receives STD_LOGIC_VECTOR data on oport. The function mvl2dec converts the bit vector to a decimal value that can be used in arithmetic computations. Performing Data Type Conversions provides a summary of the types of data conversions to consider when coding your own MATLAB functions.
Browse through the rest of modsimrand_plot.m.

Running the Simulation

This section explains how to start and monitor this simulation, and rerun it, if necessary. When you have completed as many simulation runs as desired, shut down the simulation as described in the next section.

Running the Simulation for the First Time

Before running the simulation for the first time, you must verify the client connection. You may also want to set breakpoints for debugging.

Perform the following steps:

Open ModelSim and MATLAB windows.

In MATLAB, verify the client connection by calling hdldaemon with the 'status' option:

hdldaemon('status')

This function returns a message indicating a connection exists:

HDLDaemon socket server is running on port 4795 with 1 connection

Note If you attempt to run the simulation before starting the hdldaemon in MATLAB, you will receive the following warning:

#ML Warn - MATLAB server not available (yet),
  The entity 'modsimrand' will not be active

Open modsimrand_plot.m in the MATLAB Edit/Debug window.
Search for oport.dout and set a breakpoint at that line by clicking next to the line number. A red breakpoint marker will appear.
Return to ModelSim and enter the following command in the command window:
```
 Vsim n> run 80000
```
This command instructs ModelSim to advance the simulation 80,000 time steps (80,000 nanoseconds using the default time step period). Because you previously set a breakpoint in modsimrand_plot.m, however, the simulation runs in MATLAB until it reaches the breakpoint.
ModelSim is now blocked and remains blocked until you explicitly unblock it. While the simulation is blocked, note that MATLAB displays the data that ModelSim passed to the MATLAB function in the Workspace window.

An empty ModelSim figure window opens. You can use this window to plot data generated by the simulation.
Examine oport, portinfo, and tnow. Observe that tnow, the current simulation time, is set to 0. Also notice that, because the simulation has reached a breakpoint during the first call to modsimrand_plot, the portinfo is visible in the MATLAB workspace.
Click Debug > Continue in the MATLAB Edit/Debug window. The next time the breakpoint is reached, notice that portinfo no longer appears in the MATLAB workspace. The portinfo function does not show because it is passed in only on the first function invocation. Also note that the value of tnow advances from 0 to 5e-009.
Clear the breakpoint by clicking the red breakpoint marker.
Unblock ModelSim and continue the simulation by clicking Debug > Continue in the MATLAB Edit/Debug window.
The simulation runs to completion. As the simulation progresses, it plots generated data in a figure window. When the simulation completes, the figure window appears as shown here.

The simulation runs in MATLAB until it reaches the breakpoint that you just set. Continue the simulation/debugging session as desired.

Rerunning the Simulation

If you want to run the simulation again, you must restart the simulation in ModelSim, reinitialize the clock, and reset input signals. To do so:

Close the figure window.
Restart the simulation with the following command:
```
VSIM n> restart
```
The Restart dialog box appears. Leave all the options enabled, and click Restart.

Reissue the matlabtb command.

VSIM n> matlabtb modsimrand -mfunc modsimrand_plot 
-rising /modsimrand/clk -socket portnum

Open modsimrand_plot.m in the MATLAB Edit/Debug window.
Set a breakpoint at the same line as in the previous run.

Return to ModelSim and re-enter the following commands to reinitialize clock and input signals:

Vsim n> force /modsimrand/clk 0 0,1 5 ns -repeat 10 ns
Vsim n> force /modsimrand/clk_en 1
Vsim n> force /modsimrand/reset 1 0, 0 50 ns

Enter a command to start the simulation, for example:
```
Vsim n> run 80000
```

Shutting Down the Simulation

This section explains how to shut down a simulation in an orderly way.

In ModelSim, perform the following steps:

Stop the simulation on the client side by selecting Simulate > End Simulation or entering the quit command.
Quit ModelSim.

In MATLAB, you can just quit the application, which will shut down the simulation and also close MATLAB.

To shut down the server without closing MATLAB, you have the option of calling hdldaemon with the 'kill' option:

hdldaemon('kill')

The following message appears, confirming that the server was shut down:

HDLDaemon server was shut down

Stop Test Bench Simulation

Replacing an HDL Component with a MATLAB Component Function

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit