Verify HDL Module with MATLAB Testbench

Open Live Script

This tutorial guides you through the basic steps to set up an HDL Verifier™ 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®.

This tutorial uses QuestaSim® to create and run a testbench and therefore requires QuestaSim to be on the system path. For other supported tools and requirements see Cosimulation Requirements.

Start the MATLAB Server

This section describes how to start the MATLAB server component and check for client connections using shared memory or TCP/IP socket mode. These instructions assume you are familiar with the MATLAB user interface.

1. Start MATLAB.

2. Verify that the MATLAB server is running by calling hdldaemon('status') in the MATLAB Command Window.

If the server is not running, the message reads: 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.

3. Shut down the server by typing hdldaemon('kill'). You will see the message HDLDaemon server was shutdown, which confirms that the server is shut down.

4. Start the server in TCP/IP socket mode by calling hdldaemon('socket', 0). The value 0 in the property name/property value pair ('socket' 0) specifies that the operating system assigns the server a TCP/IP socket port that is available on your system.

5. The server informs you that it has started by displaying the message:

HDLDaemon socket server is running on Port portnum with 0 connections.

Make note of the portnum. You need it when you issue the matlabtb command in Load Simulation. Note that the portnum will be specific to your system.

You may also specify the MATLAB server to use shared memory communication instead of TCP/IP socket communication. For this tutorial we use socket communication. For details on how to specify the various options, see hdldaemon.

Start QuestaSim Simulator and Set Up for Cosimulation

This section describes the basic procedure to start the QuestaSim software and set up a QuestaSim design library. These instructions assume you are familiar with the QuestaSim user interface.

1. To start QuestaSim, enter vsim in the MATLAB Command Window. This function launches and configures QuestaSim for use with the HDL Verifier software. The first folder of QuestaSim should match your MATLAB current folder.

2. Verify the current QuestaSim folder. You can verify that the current QuestaSim folder matches the MATLAB current folder by entering the ls command in the QuestaSim Command Window.

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

If it does not, change your QuestaSim folder to the current MATLAB folder. You can find the current MATLAB folder by looking in the Current Folder Browser or by viewing the Current Folder navigation bar. In QuestaSim, you can change the working folder by issuing the command: cd directory

Where directory is the folder you want to work from. Or you may change directory by selecting File > Change Directory...

3. Create a design library to hold your compilation results. To create the library and the required _info file, enter the vlib command:

QuestaSim> vlib work

Note: You must use the QuestaSim File menu or the vlib command to create the library folder so that the required _info file is created. Do not create the library with operating system commands.

Develop VHDL Code

After setting up a design library, you need to use the QuestaSim Editor to create and modify your VHDL code. For this tutorial, you do not need to create the VHDL code yourself. Instead, open and examine the existing file modsimrand.vhd. This section highlights areas of code in modsimrand.vhd that are of interest for a QuestaSim and MATLAB testbench.

If you choose not to examine the VHDL code at this time, skip to Compile VHDL Code.

You can open modsimrand.vhd in the edit window with the edit command:

QuestaSim> edit modsimrand.vhd

QuestaSim opens its edit window and displays the VHDL code of modsimrand.vhd.

While you are viewing the file:

1. The line ENTITY modsimrand contains the definition for 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 is the entity that will be verified in the MATLAB environment. Note that:

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 can name 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 name.
You must define the entity 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 HDL Verifier software. The entity modsimrand in this example is defined with three input ports clk, clk_en, and reset of type STD_LOGIC and an output port dout of type STD_LOGIC_VECTOR. The output port passes simulation output data 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 QuestaSim force commands. For more information on coding port entities for use with MATLAB, see Coding HDL Modules for Verification with MATLAB.

2. The remaining code for modsimrand.vhd defines a behavioral architecture for modsimrand that writes a randomly generated Fibonacci sequence to an output register when the clock experiences a rising edge.

When you finish examining the file, close the QuestaSim edit window.

Compile VHDL Code

After you create or edit your VHDL source files, you need to compile them. In this tutorial, you need to compile modsimrand.vhd. You can compile the file is by clicking the file name in the project workspace and select Compile > Compile All. An alternative is to specify modsimrand.vhd with the vcom command:

QuestaSim> vcom modsimrand.vhd

If the compilation succeeds, messages appear in the Command Window and the compiler populates the work library with the compilation results.

Develop MATLAB Function

The HDL Verifier software verifies HDL hardware in MATLAB using MATLAB testbench functions. You need to create or edit the MATLAB testbench function that meets the HDL Verifier requirements. For this tutorial, you do not need to develop the MATLAB testbench function yourself. Instead, open and examine the existing file modsimrand_plot.m.

If you choose not to examine the MATLAB function at this time, skip to Load Simulation.

Note: modsimrand_plot.m is a lower-level component of the MATLAB Random Number Generator example. 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.

You can open modsimrand_plot.m in the MATLAB Editor by typing edit modsimrand_plot.m in the MATLAB Command Window.

While you are viewing the file:

1. On line 1, you will find the MATLAB function name specified along with its required parameters: function [iport,tnext] = modsimrand_plot(oport,tnow,portinfo)

This function definition is important because it represents the communication channel between MATLAB and QuestaSim. When you code the function:

You must define the function with two output parameters, iport and tnext, and three input parameters, oport, tnow, and portinfo. See MATLAB Function Syntax and Function Argument Definitions.
You can use the iport parameter to drive input signals instead of, or in addition to, using other signal sources, such as QuestaSim 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.

2. On lines 21 and 22, you will find some parameter initialization:

tnext = [];

iport = struct();

In this case, function outputs iport and tnext are initialized to empty values.

3. You need to know the types of the data that the MATLAB testbench function receives from and returns to QuestaSim and how HDL Verifier handles this data; see Supported Data Types. This function 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.

On line 61, the line of code containing oport.dout shows how the data that a MATLAB function receives from QuestaSim is 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. Supported Data Types provides a summary of the types of data conversions to consider when coding your own MATLAB functions.

4. Browse through the rest of modsimrand_plot.m. When you are finished, go to Load Simulation.

Load Simulation

After you 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:

QuestaSim> vsimmatlab modsimrand

The vsimmatlab command starts the QuestaSim simulator, vsim, specifically for use with MATLAB. QuestaSim displays a series of messages in the Command Window as it loads the entity's packages and architecture.

2. Initialize the simulator to verify modsimrand with MATLAB. You initialize QuestaSim by using the matlabtb command. This command defines the communication link and a callback to a MATLAB function that executes in MATLAB on behalf of QuestaSim. In addition, the matlabtb command can specify parameters that control when the MATLAB function executes.

For this tutorial, enter the following matlabtb command in QuestaSim:

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

Arguments in the command line specify the following conditions:

modsimrand — Specifies the VHDL module to cosimulate.
-mfunc modsimrand_plot — Links an instance of the entity modsimrand to the MATLAB function modsimrand_plot.m. The argument is required because the entity name is not the same as the testbench function name.
-rising /modsimrand/clk — Specifies that the testbench function be called whenever signal /modsimrand/clk experiences a rising edge.
-socket portnum — Specifies the port number portnum returned by the call to hdldaemon in Start the MATLAB Server.

3. Initialize clock and reset input signals. You can drive simulation input signals using several mechanisms, such as the QuestaSim force commands and an iport parameter (see Syntax of a Testbench Function). For now, enter the following force commands:

> force /modsimrand/clk 0 0 ns, 1 5 ns -repeat 10 ns

> force /modsimrand/clk_en 1

> 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 QuestaSim environment is ready to run a simulation. Now, you need to set up the MATLAB function.

Run Simulation

This section explains how to start, monitor, and rerun the simulation.

Run 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 QuestaSim 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

HDLDaemon shared memory server is running 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 Editor.

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 QuestaSim and enter the following command:

> run 80000

This command instructs QuestaSim 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, the simulation runs in MATLAB until it reaches the breakpoint.

QuestaSim is now blocked and remains blocked until you explicitly unblock it. While the simulation is blocked, note that MATLAB displays the data that QuestaSim passed to the MATLAB function in the Workspace window.

In MATLAB, an empty figure window opens. You can use this window to plot data generated by the simulation.

6. Examine oport, portinfo, and tnow by hovering over these arguments inside the MATLAB Workspace window. Observe that tnow, the current simulation time, is set to 0. Also notice that you can see the portinfo argument in the MATLAB workspace because the simulation has reached a breakpoint during the first call to modsimrand_plot.

7. Click Continue in the MATLAB Editor. 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 call. Also note that the value of tnow advances from 0 to 5e-09.

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

9. Unblock QuestaSim and continue the simulation by clicking Continue in the MATLAB Editor. The simulation runs to completion. As the simulation progresses, it plots generated data in the figure window. When the simulation completes, the figure window appears as shown below.

Rerun the Simulation

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

1. Close the figure window.

2. Restart the simulation in QuestaSim with the following command:

> 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 matlabtb command. Therefore after restarting QuestaSim, you must reissue the previous command or issue a new command.

3. Reissue the matlabtb command in QuestaSim:

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

4. Open modsimrand_plot.m in the MATLAB Editor.

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

6. Return to QuestaSim and re-enter the following commands to reinitialize clock and input signals:

> force /modsimrand/clk 0 0,1 5 ns -repeat 10 ns

> force /modsimrand/clk_en 1

> force /modsimrand/reset 1 0, 0 50 ns

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

> run 80000

Shut Down Simulation

To shut down a simulation in an orderly way:

In QuestaSim:

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

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

To shut down the server without closing MATLAB, you can call hdldaemon with the 'kill' option:

hdldaemon('kill')

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

HDLDaemon server was shutdown