matlabcp - (For ModelSim) Associate MATLAB component function with instantiated HDL design

Syntax

matlabcp <instance>
[<time-specs>]
[-socket <tcp-spec>]
[-rising <port>[,<port>...]]
[-falling <port> [,<port>,...]] 
[-sensitivity <port>[,<port>,...]]
[-mfunc <name>]
[-use_instance_obj]
[-argument]

Description

The matlabcp command has the following characteristics:

Starts the HDL simulator client component of the EDA Simulator Link software.
Associates a specified instance of an HDL design created in the HDL simulator with a MATLAB function.
Creates a process that schedules invocations of the specified MATLAB function.
Cancels any pending events scheduled by a previous matlabcp command that specified the same instance. For example, if you issue the command matlabcp for instance foo, all previously scheduled events initiated by matlabcp on foo are canceled.

This command is issued in the HDL simulator.

MATLAB component functions simulate the behavior of modules in the HDL model. A stub module (providing port definitions only) in the HDL model passes its input signals to the MATLAB component function. The MATLAB component processes this data and returns the results to the outputs of the stub module. A MATLAB component typically provides some functionality (such as a filter) that is not yet implemented in the HDL code. See Replacing an HDL Component with a MATLAB Component Function.

Notes The communication mode that you specify for matlabcp must match the communication mode you specified for hdldaemon when you established the server connection.

For socket communications, specify the port number you selected for hdldaemon when you issue a link request with the matlabcp command in the HDL simulator.

Arguments

<instance>

Specifies an instance of an HDL design that is associated with a MATLAB function. By default, matlabcp associates the instance to a MATLAB function that has the same name as the instance. For example, if the instance is myfirfilter, matlabcp associates the instance with the MATLAB function myfirfilter (note that hierarchy names are ignored; for example, if your instance name is top.myfirfilter, matlabcp would associate only myfirfilter with the MATLAB function). Alternatively, you can specify a different MATLAB function with -mfunc.

Note Do not specify an instance of an HDL module that has already been associated with a MATLAB M-function (via matlabcp or matlabtb). If you do, the new association overwrites the existing one.

<time-specs>

Specifies a combination of time specifications consisting of any or all of the following:

<timen>,...

Specifies one or more discrete time values at which the HDL simulator calls the specified MATLAB function. Each time value is relative to the current simulation time. Even if you do not specify a time, the HDL simulator calls the MATLAB function once at the start of the simulation. Separate multiple time values by a space.

For example:

matlabtb vlogtestbench_top 10 ns, 10 ms, 10 sec

The MATLAB function executes when time equals 0 and then 10 nanoseconds, 10 milliseconds, and 10 seconds from time zero.

Note For time-based parameters, you can specify any standard time units (ns, us, and so on). If you do not specify units, the command treats the time value as a value of HDL simulation ticks.

-repeat <time> Specifies that the HDL simulator calls the MATLAB function repeatedly based on the specified <timen>,... pattern. The time values are relative to the value of tnow at the time the HDL simulator first calls the MATLAB function.

-cancel <time>

Specifies a time at which the specified MATLAB function stops executing. The time value is relative to the value of tnow at the time the HDL simulator first calls the MATLAB function. If you do not specify a cancel time, the application calls the MATLAB function until you finish the simulation, quit the session, or issue a nomatlabtb call.

Note The -cancel option works only with the <time-specs> arguments. It does not affect any of the other scheduling arguments for matlabcp.

Note Place time specifications after the matlabcp instance and before any additional command arguments; otherwise the time specifications are ignored.

All time specifications for the matlabcp functions appear as a number and, optionally, a time unit:

fs (femtoseconds)
ps (picoseconds)
ns (nanoseconds)
us (microseconds)
ms (milliseconds)
sec (seconds)
no units (tick)

-socket <tcp_spec>

Specifies TCP/IP socket communication for the link between the HDL simulator and MATLAB. When you provide TCP/IP information for matlabcp, you can choose a TCP/IP port number or TCP/IP port alias or service name for the <tcp_spec> parameter. If you are setting up communication between computers, you must also specify the name or Internet address of the remote host that is running the MATLAB server (hdldaemon). See Specifying TCP/IP Values for some valid tcp_spec examples.

For more information on choosing TCP/IP socket ports, see Choosing TCP/IP Socket Ports.

If you run the HDL simulator and MATLAB on the same computer, you have the option of using shared memory for communication. Shared memory is the default mode of communication and takes effect if you do not specify -socket <tcp_spec> on the command line.

Note The communication mode that you specify with the matlabcp command must match what you specify for the communication mode when you issue the hdldaemon command in MATLAB.

For more information on modes of communication, see Communicating with MATLAB or Simulink and the HDL Simulator. For more information on establishing the MATLAB end of the communication link, see Start hdldaemon to Provide Connection to HDL Simulator.

-rising <signal>[, <signal>...]

Indicates that the application calls the specified MATLAB function on the rising edge (transition from '0' to '1') of any of the specified signals. Specify -rising with the path names of one or more signals defined as a logic type (STD_LOGIC, BIT, X01, and so on).

For determining signal transition in:

Verilog: Rising edge is the transition from 0, x, or z to 1.
VHDL: Rising edge is '0'->'1'. Z and X will not create a rate transition.

Specify -rising with the path names of one or more signals defined as a logic type.

Note When specifying signals with the -rising, -falling, and -sensitivity options, specify them in full path name format. If you do not specify a full path name, the command applies the HDL simulator rules to resolve signal specifications.

-falling <signal>[, <signal>...]

Indicates that the application calls the specified MATLAB function whenever any of the specified signals experiences a falling edge—changes from '1' to '0'. Specify -falling with the path names of one or more signals defined as a logic type (STD_LOGIC, BIT, X01, and so on).

For determining signal transition in:

Verilog: Falling edge is the transition from 1 to x, z or 0.
VHDL: Falling edge is '1'->'0'. Values 'X', 'Z', 'H', and 'L' will be ignored.

-sensitivity <signal>[, <signal>...]

Indicates that the application calls the specified MATLAB function whenever any of the specified signals changes state. Specify -sensitivity with the path names of one or more signals. Signals of any type can appear in the sensitivity list and can be positioned at any level in the HDL model hierarchy.

-mfunc <name>

The name of the MATLAB function that is associated with the HDL module instance you specify for instance. By default, the EDA Simulator Link 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. If the names are not the same, use this argument when you call matlabcp. If you omit this argument and matlabcp does not find a MATLAB function with the same name, the command generates an error message.

-use_instance_obj (Beta Feature)

Instructs the function specified with the argument -mfunc to use an HDL instance object passed by EDA Simulator Link to the M-function. You include the -use_instance_obj argument with matlabcp in the following format:

matlabcp modelname -mfunc funcname -use_instance_obj

When you call matlabcp with the use_instance_obj argument, the M-function has the following signature:

function MyFunctionName(hdl_instance_obj)

The HDL instance object (hdl_instance_obj) has the fields shown in the following table.

Field Read/Write Access Description

tnext

Write only

Used to schedule a callback during the set time value. This field is equivalent to old tnext. For example:

hdl_instance_obj.tnext = hdl_instance_obj.tnow + 5e-9

will schedule a callback at time equals 5 nanoseconds from tnow.

userdata Read/Write Stores state variables of the current matlabcp instance. You can retrieve the variables the next time the callback of this instance is scheduled.

simstatus

Read only

Stores the status of the HDL simulator. The EDA Simulator Link software sets this field to 'Init' during the first callback for this particular instance and to 'Running' thereafter. simstatus is a read-only property.

>> hdl_instance_obj.simstatus

ans=
      Init

instance

Read only

Stores the full path of the Verilog/VHDL instance associated with the callback. instance is a read-only property. The value of this field equals that of the module instance specified with the function call. For example:

In the HDL simulator:

hdlsim> matlabcp osc_top -mfunc oscfilter use_instance_obj

In MATLAB:

>> hdl_instance_obj.instance

ans=
		osc_top

argument

Read only

Stores the argument set by the -argument option of matlabcp. For example:

matlabtb osc_top -mfunc oscfilter -use_instance_obj -argument foo

The link software supports the -argument option only when it is used with -use_instance_obj, otherwise the argument is ignored. argument is a read-only property.

>> hdl_instance_obj.argument

ans= 
    	foo

portinfo

Read only

Stores information about the VHDL and Verilog ports associated with this instance. portinfo is a read-only property, which has a field structure that describes the ports defined for the associated HDL module. For each port, the portinfo structure passes information such as the port's type, direction, and size. For more information on port data, see Gaining Access to and Applying Port Information.

hdl_instance_obj.portinfo.field1.field2.field3

Note When you use use_instance_obj, you access tscale through the HDL instance object. If you do not use use_instance_obj, you can still access tscale through portinfo.

tscale

Read only

Stores the resolution limit (tick) in seconds of the HDL simulator. tscale is a read-only property.

>> hdl_instance_obj.tscale

ans=
	1.0000e-009

Note When you use use_instance_obj, you access tscale through the HDL instance object. If you do not use use_instance_obj, you can still access tscale through portinfo.

tnow

Read only

Stores the current time. tnow is a read-only property.

hdl_instance_obj.tnext = hld_instance_obj.tnow + fastestrate;

portvalues

Read/Write

Stores the current values of and sets new values for the output and input ports for a matlabcp instance. For example:

>> hdl_instance_obj.portvalues

ans =
Read Only Input ports:
	clk_enable: []
	clk: []
	reset: []
Read/Write Output ports:
	sine_out: [22x1 char]

linkmode

Read only

Stores the status of the callback. The EDA Simulator Link software sets this field to 'testbench' if the callback is associated with matlabtb and 'component' if the callback is associated with matlabcp. linkmode is a read-only property.

>> hdl_instance_obj.linkmode

ans=
	component

-argument (Beta Feature)

Used to pass user-defined arguments from the matlabcp invocation on the HDL side to the M-function callbacks. Supported with -use_instance_obj only. See the field listing under the -use_instance_obj property.

Examples

The following examples demonstrate some ways you might use the matlabcp function.

Using matlabcp with the -mfunc option to Associate an HDL Component with a MATLAB M-Function of a Different Name

This example explicitly associates the Verilog module vlogtestbench_top.u_matlab_component with the MATLAB function vlogmatlabc using the -mfunc option. The '-socket' option specifies using socket communication on port 4449.

matlabcp vlogtestbench_top.u_matlab_component -mfunc vlogmatlabc -socket 4449

Using matlabcp with Explicit Times and the -cancel Option

This example implicitly associates the Verilog module, vtestbench_top, with the MATLAB function vlogtestbench_top, and includes explicit times with the -cancel option.

matlabcp vlogtestbench_top 1e6 fs  3 2e3 ps -repeat 3 ns -cancel 7ns

Using matlabcp with Rising and Falling Edges

This example implicitly associates the Verilog module, vlogtestbench_top, with the MATLAB function vlogtestbench_top, and also uses rising and falling edges.

hldsim> matlabcp vlogtestbench_top  1 2 3 4 5 6 7 -rising outclk3 
          -falling u_matlab_component/inoutclk

Using matlabcp and the HDL Instance Object (Beta Feature)

In this example, the HDL simulator makes repeated calls to matlabcp to bind multiple HDL instances to the same M-function. Each call contains -argument as a constructor parameter to differentiate behavior.

> matlabcp u1_filter1x -mfunc osc_filter -use_instance_obj -argument "oversample=1"
> matlabcp u1_filter8x -mfunc osc_filter -use_instance_obj -argument "oversample=8"
> matlabcp u2_filter8x -mfunc osc_filter -use_instance_obj -argument "oversample=8"

The M-function callback, osc_filter.m, sets up user instance-based state using obj.userdata, queries port and simulation context using other obj fields, and uses the passed in obj.argument to differentiate behavior.

function osc_filter(obj)
  if (strcmp(obj.simstatus,'Init'))
    ud = struct('Nbits', 22, 'Norder', 31, 'clockperiod', 80e-9, 'phase', 1));
    eval(obj.argument);
    if (~exist('oversample','var'))
        error('HdlLinkDemo:UseInstanceObj:BadCtorArg', ...
        'Bad constructor arg to osc_filter callback. Expecting 
					''oversample=value''.');
    end
    ud.oversample        = oversample;
    ud.oversampleperiod  = ud.clockperiod/ud.oversample;
    ud.InDelayLine       = zeros(1,ud.Norder+1);

    centerfreq = 70/256;
    passband   = [centerfreq-0.01, centerfreq+0.01];
    b          = fir1((ud.Norder+1)*ud.oversample-1, passband./ud.oversample);
    ud.Hresp             = ud.oversample .* b;

    obj.userdata = ud;
  end

...

hdldaemon

matlabtb

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