EDA Simulator Link™ MQ

MATLAB and ModelSim Tutorial

Tutorial Overview

This chapter guides you through the basic steps for setting up an EDA Simulator Link MQ 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 MQ software.

Back to Top

Setting Up Tutorial Files

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

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

2. Copy the following files to the directory you just created:

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

Back to Top

Starting the MATLAB Server

This section describes starting MATLAB, setting up the current directory 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:

1. Start MATLAB.

2. Set your MATLAB current directory to the directory you created in Setting Up Tutorial Files.

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

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

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

   Note   The hdldaemon function can handle multiple connections that are initiated by multiple commands from a single ModelSim session or multiple sessions.

Back to Top

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:

1. 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 MQ software. The first directory of ModelSim matches your MATLAB current directory.

2. Verify the current ModelSim directory. You can verify that the current ModelSim directory matches the MATLAB current directory by entering the ls command in the ModelSim command window.

   

   The command should list the files modsimrand.vhd, modsimrand_plot.m, and transcript.

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

   

   Note   You must use the ModelSim File menu or vlib command to create the library directory to ensure that the required _info file is created. Do not create the library with operating system commands.

Back to Top

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:

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

   

2. 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 MQ software. For a list of the supported types, see Coding HDL Modules for MATLAB Verification.

     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 Coding HDL Modules for MATLAB Verification.

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

4. Close the ModelSim edit window.

Back to Top

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.

Back to Top

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:

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

   

2. 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.
   -socketportnum	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.

   Note   By default, the EDA Simulator Link MQ software invokes a MATLAB function that has the same name as the specified HDL instance. Thus, if the names are the same, you can omit the -mfunc option.

3. Initialize clock and reset input signals. You can drive simulation input signals using several mechanisms, including ModelSim force commands and an iport parameter (see Coding MATLAB Link Functions). 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.

Back to Top

Developing the MATLAB Function

The EDA Simulator Link MQ 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 MQ 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:

1. Open modsimrand_plot.m in the MATLAB Edit/Debug window. For example:

   edit modsimrand_plot.m
   

2. 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 MQ 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 Coding MATLAB 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.

3. Initialize the function outputs iport and tnext to empty values, as in the following code excerpt:

   tnext = [];
   iport = struct();
   

4. Make note of the data types of ports defined for the entity under simulation. The EDA Simulator Link MQ 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.

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

6. Browse through the rest of modsimrand_plot.m.

Back to Top

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:

1. Open ModelSim and MATLAB windows.

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

3. Open modsimrand_plot.m in the MATLAB Edit/Debug window.

4. Search for oport.dout and set a breakpoint at that line by clicking next to the line number. A red breakpoint marker will appear.

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

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

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

8. Clear the breakpoint by clicking the red breakpoint marker.

9. 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:

1. Close the figure window.

2. Restart the simulation with the following command:

   VSIM n> restart
   

   The Restart dialog box appears. Leave all the options enabled, and click Restart.

   Note   The Restart button clears the simulation context established by a matlabcp or matlabtb command. Thus, after restarting ModelSim, you must reissue the previous command or issue a new command.

3. Reissue the matlabtb command.

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

4. Open modsimrand_plot.m in the MATLAB Edit/Debug window.

5. Set a breakpoint at the same line as in the previous run.

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

7. Enter a command to start the simulation, for example:

   Vsim n> run 80000
   

Back to Top

Shutting Down the Simulation

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

In ModelSim, perform the following steps:

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

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

Back to Top

Running MATLAB Link Sessions

Linking Simulink Software to ModelSim Simulators