Set Up Cosimulation Testbench

This article explains how to set up a MATLAB^® testbench to cosimulate an HDL module represented as a MATLAB function. This workflow is not supported for the Vivado^® simulator.

Place Testbench on MATLAB Search Path

Use MATLAB which Function to Find Testbench

The MATLAB function that you are associating with an HDL component must be on the MATLAB search path or reside in the current working folder (see the MATLAB cd function). To verify whether the function is accessible, use the MATLAB which function. The following call to which checks whether the function MyVhdlFunction is on the MATLAB search path, for example:

which MyVhdlFunction
/work/xcelium/MySym/MyVhdlFunction.m

If the specified function is on the search path, which displays the complete path to the function. If the function is not on the search path, which informs you that the file was not found.

Add Testbench Function to MATLAB Search Path

To add a MATLAB function to the MATLAB search path:

On the Home tab, in the Environment section, click Set Path.
Use the addpath function.
For temporary access, change the MATLAB working folder to a desired location with the cd command.

Bind Testbench Function Calls With `matlabtb`

Invoke MATLAB Testbench Command `matlabtb`

You invoke matlabtb by issuing the command in the HDL simulator. See the Examples section of the matlabtb reference page for several examples of invoking matlabtb.

Be sure to follow the path specifications for MATLAB testbench sessions when invoking matlabtb, as explained in Specify HDL Signal/Port and Module Paths for MATLAB Testbench Cosimulation.

For instructions in issuing the matlabtb command, see Run MATLAB-HDL Cosimulation.

Specify HDL Signal/Port and Module Paths for MATLAB Testbench Cosimulation

HDL Verifier™ software has specific requirements for specifying HDL design hierarchy, the syntax of which is described in the following sections: one for Verilog^® at the top level, and one for VHDL^® at the top level. Do not use a file name hierarchy in place of the design hierarchy name.

The rules stated in this section apply to signal/port and module path specifications for MATLAB cosimulation sessions. Other specifications may work but the HDL Verifier software does not officially recognize nor support them.

In the following example:

matlabtb u_osc_filter -mfunc oscfilter

u_osc_filter is the top-level component. If you specify a subcomponent, you must follow valid module path specifications for MATLAB cosimulation sessions.

Path Specifications for MATLAB Link Sessions with Verilog Top Level

The path specification must start with a top-level module name.
The path specification can include "." or "/" path delimiters, but it cannot include mixed delimiters.
The leaf module or signal must match the HDL language of the top-level module.

The following examples show valid signal and module path specifications:

top.port_or_sig
/top/sub/port_or_sig
top
top/sub
top.sub1.sub2

The following examples show invalid signal and module path specifications:

top.sub/port_or_sig
Why this specification is invalid: You cannot use mixed delimiters.
:sub:port_or_sig
:
:sub
Why this specification is invalid: When you use VHDL-specific delimiters you limit the interoperability with paths when moving between HDL simulators and between VHDL and Verilog.

Path Specifications for MATLAB Link Sessions with VHDL Top Level

The path specification can include the top-level module name, but you do not have to include it.
The path specification can include "." or "/" path delimiters, but it cannot include mixed delimiters.
The leaf module or signal must match the HDL language of the top-level module.

Examples for ModelSim and Xcelium Users

Bind HDL Module Component to MATLAB Testbench Function

By default, the HDL Verifier software assumes that the name for a MATLAB function matches the name of the HDL module that the function verifies. When you create a testbench or component function that has a different name than the design under test, you must associate the design with the MATLAB function using the -mfunc argument to matlabtb. This argument associates the HDL module instance to a MATLAB function that has a different name from the HDL instance.

For more information on the -mfunc argument and for a full list of matlabtb parameters, see the matlabtb function reference.

For details on MATLAB function naming guidelines, see "MATLAB Programming Tips" on files and file names in the MATLAB documentation.

Example of Binding Testbench and Component Function Calls. In this first example, you form an association between the inverter_vl component and the MATLAB testbench function inverter_tb by invoking the function matlabtb with the -mfunc argument when you set up the simulation.

matlabtb inverter_vl -mfunc inverter_tb

The matlabtb command instructs the HDL simulator to call back the inverter_tb function when inverter_vl executes in the simulation.

In this second example, you bind the model osc_top.u_osc_filter to the component function oscfilter:

matlabcp osc_top.u_osc_filter -mfunc oscfilter

When the HDL simulator calls the oscfilter callback, the function knows to operate on the model osc_top.u_osc_filter.

Schedule Options for a Testbench Session

About Scheduling Options for Testbench Sessions

There are two ways to schedule the invocation of a MATLAB function:

Using the arguments to the HDL Verifier function matlabtb or matlabcp
Inside the MATLAB function using the tnext parameter

The two types of scheduling are not mutually exclusive. You can combine the matlabtb or matlabcp timing arguments and the tnext parameter of a MATLAB function to schedule testbench or component session callbacks.

Schedule Testbench Session Using `matlabtb` Arguments

By default, the HDL Verifier software invokes a MATLAB testbench or component function once (at the time that you make the call to matlabtb or matlabcp). If you want to apply more control, and execute the MATLAB function more than once, use the command scheduling options. With these options, you can specify when and how often the HDL Verifier software invokes the relevant MATLAB function. If applicable, modify the function or specify timing arguments when you begin a MATLAB testbench or component function session with the matlabtb or matlabcp function.

You can schedule a MATLAB testbench or component function to execute using the command arguments under any of the following conditions:

Discrete time values—Based on time specifications that can also include repeat intervals and a stop time
Rising edge—When a specified signal experiences a rising edge
- VHDL: Rising edge is {0 or L} to {1 or H}.
- Verilog: Rising edge is the transition from 0 to x, z, or 1, and from x or z to 1.
Falling edge—When a specified signal experiences a falling edge
- VHDL: Falling edge is {1 or H} to {0 or L}.
- Verilog: Falling edge is the transition from 1 to x, z, or 0, and from x or z to 0.
Signal state change—When a specified signal changes state, based on a list using the -sensitivity argument to matlabtb.

Schedule Testbench Functions With the `tnext` Parameter

You can control the callback timing of a MATLAB function by using that function's tnext parameter. This parameter passes a time value to the HDL simulator, and the value gets added to the simulation schedule for that function. If the function returns a null value ([]) , the software does not add any new entries to the schedule.

You can set the value of tnext to a value of type double or int64. Specify double to express the callback time in seconds. For example, to schedule a callback in 1 ns, specify:

 tnext = 1e-9

Specify int64 to convert to an integer multiple of the current HDL simulator time resolution limit. For example: if the HDL simulator time precision is 1 ns, to schedule a callback at 100 ns, specify:

tnext=int64(100)

Note

The tnext parameter represents time from the start of the simulation. Therefore, tnext must always be greater than tnow. If it is less, the software does not schedule a callback.

For more information on tnext and the function prototype, see MATLAB Function Syntax and Function Argument Definitions.

Examples. In this first example, each time the HDL simulator calls the testbench function (via HDL Verifier), tnext schedules the next callback to the MATLAB function for 1 ns later, relative to the current simulation time:

tnext = [];
.
.
.
tnext = tnow+1e-9;

Using tnext you can dynamically decide the callback scheduling based on criteria specific to the operation of the testbench. For example, you can decide to stop scheduling callbacks when a data signal has a certain value:

    if qsum == 17,
        qsum = 0;
        disp('done');
        tnext = [];  % suspend callbacks
        testisdone = 1;
        return;
    end

This next example demonstrates scheduling a component session using tnext. In the Oscillator example, the oscfilter function calculates a time interval at which the HDL simulator calls the callbacks. The component function calculates this interval on the first call to oscfilter and stores the result in the variable fastestrate. The variable fastestrate represents the sample period of the fastest oversampling rate supported by the filter. The function derives this rate from a base sampling period of 80 ns.

The following assignment statement sets the timing parameter tnext. This parameter schedules the next callback to the MATLAB component function, relative to the current simulation time (tnow).

tnext = tnow + fastestrate;

The function returns a new value for tnext each time the HDL simulator calls the function.