Main Content

matlabtb

Schedule MATLAB test bench session for instantiated HDL module

    Description

    example

    Note

    Enter this command in the HDL simulator, not in MATLAB®.

    matlabtb instance performs the following actions:

    • Starts the HDL simulator client component of the HDL Verifier™ 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 matlabtb command that specified the same instance. For example, if you issue the command matlabtb for instance foo, matlabtb cancels all previously scheduled events initiated by matlabtb on foo.

      This command is issued in the HDL simulator.

      MATLAB test bench functions mimic stimuli passed to entities in the HDL model. Force stimulus from MATLAB or HDL scheduled with matlabtb.

      Note

      The communication mode that you specify for matlabtb 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 matlabtb command in the HDL simulator.

    example

    matlabtb instance time-specs adds time specifications for scheduling the specified MATLAB function.

    example

    matlabtb instance ___ pair1 ... pairN specifies one or more additional specifications as pairs consisting of a valid specification name and its value. For example, -mfunc vlogmatlabc specifies for the MATLAB function vlogmatlabc to be associated with the specified HDL module. You can specify these pairs with or without time-specs.

    Examples

    collapse all

    Start the HDL simulator client component of HDL Verifier, associate an instance of the entity myfirfilter with the MATLAB function myfirfilter, and begin a local TCP/IP socket-based test bench session using TCP/IP port 4449. Based on the specified test bench stimuli, myfirfilter.m executes 5 nanoseconds from the current time and then executes repeatedly every 10 nanoseconds.

    hdlsim> matlabtb myfirfilter 5 ns -repeat 10 ns -socket 4449
    

    Start the HDL simulator client component of HDL Verifier. Begin a remote TCP/IP socket-based session using the remote MATLAB host computer named computer123 and TCP/IP port 4449. Based on the specified test bench stimuli, myfirfilter.m executes 10 nanoseconds from the current time, each time the signal /top/fclk experiences a rising edge, and each time the signal /top/din changes state.

    hdlsim> matlabtb /top/myfirfilter 10 ns -rising /top/fclk -sensitivity /top/din 
          -socket 4449@computer123

    Start the HDL simulator client component of the HDL Verifier software. The -mfunc option specifies the MATLAB function to connect to and the -socket pair specifies the port number for socket connection mode. The -sensitivity pair indicates that the test bench session is sensitized to the signal sine_out.

    hdlsim> matlabtb osc_top -sensitivity /osc_top/sine_out
          -socket 4448 -mfunc hosctb

    Input Arguments

    collapse all

    Instance of an HDL module that is associated with a MATLAB function, specified as a character vector or string scalar that indicates an HDL module instance. By default, the matlabtb command associates the instance to a MATLAB function that has the same name as the instance. For example, if the instance is myfirfilter, matlabtb associates the instance with the MATLAB function myfirfilter The command ignores hierarchy names. For example, if the instance is top.myfirfilter, the matlabtb command associates only myfirfilter with the MATLAB function. To associate the specified instance with a MATLAB function that differs from the instance name, use the -mfunc specification as in the pair1 ... pairN argument.

    Note

    If you specify an instance of an HDL module that is already associated with a MATLAB function (via matlabcp or matlabtb) the new association overwrites the existing one.

    Data Types: char | string

    Space-separated list of one or more time specifications, specified as a space-separated list of one or more time specifications listed in this table.

    Time SpecificationDescription
    time_1 time_2 ... time_n

    Specify one or more discrete times at which the HDL simulator calls the specified MATLAB function. The specified times are relative to the current simulation time. If you do not specify a time, the HDL simulator calls the MATLAB function once at the start of the simulation. Each time_i consists of a number indicating the time value and an optional time unit of:

    • fs (femtoseconds)

    • ps (picoseconds)

    • ns (nanoseconds)

    • us (microseconds)

    • ms (milliseconds)

    • sec (seconds)

    If you do not specify a time unit, the command treats the time value as a value of HDL simulation ticks. Separate each time_i by a space.

    For example, this code specifies for the MATLAB function vlogmodel_top to execute at time 0 (initial execution) and then at 10 nanoseconds, 10 milliseconds, and 10 seconds.

    matlabtb vlogmodel_top 10 ns, 10 ms, 10 sec
    
    -repeat <time>Specify that the HDL simulator calls the MATLAB function repeatedly based on the specified times. The time values are relative to the value of tnow at the time the HDL simulator first calls the MATLAB function.
    -cancel <time>

    Specify a single 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 matlabtb.

    Note

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

    Additional specifications, specified as a space-separated list of one or more specification pairs. A specification pair consists of a name and value. This table shows valid options for these pairs.

    Specification Pairs

    NameValueDescription
    -socketCommunication mode that matches the communication mode issued with the hdldaemon command

    Specify for HDL Verifier to use TCP/IP sockets to communicate between the HDL simulator and MATLAB. Shared memory is the default mode of communication and takes effect if you do not specify -socket <tcp_spec>. The communication mode that you specify with the matlabtb command must match the communication mode that you specified with the hdldaemon command.

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

    Note

    The communication mode that you specify with the matlabtb 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 Communications for HDL Cosimulation. For more information on establishing the MATLAB end of the communication link, see Start the HDL Simulator from MATLAB.

    -risingComma-separated list of one or more signal names

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

    • In VHDL®, a transition from 0 or L to 1 or H determines a rising edge.

    • In Verilog®, a transition from 0 to x, z, or 1, or from x or z to 1 determines a rising edge.

    Note

    When specifying signals with the -rising pair, specify the signals 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.

    -fallingComma-separated list of one or more signal names

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

    For determining signal transition in:

    • In VHDL, a transition from 1 or H to 0 or L determines a falling edge.

    • In Verilog, a transition from 1 to x, z, or 0, or from x or z to 0 determines a falling edge.

    Note

    When specifying signals with the -falling pair, specify the signals 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.

    -sensitivityComma-separated list of one or more signal names

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

    Note

    When specifying signals with the -sensitivity pair, specify the signals 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.

    -mfuncMATLAB function name

    Specify the name of the MATLAB function that is associated with the HDL module instance you specify for instance. By default, the HDL Verifier software calls a MATLAB function that has the same name as the specified HDL instance. If the names are the same, you can omit the -mfunc pair. If the names are not the same, use this argument when you call matlabtb. If you omit this argument and matlabtb does not find a MATLAB function with the same name, the command generates an error message.

    -use_instance_objStructure with fields as described in the table in -use_instance_obj Fields

    This pair Instructs the function specified with the argument -mfunc to use an HDL instance object passed by HDL Verifier to the function. This value has the fields shown in the applicable table. See Writing Functions Using the HDL Instance Object for examples.

    -argumentHDL instance argument

    Pass user-defined arguments from the matlabtb command on the HDL side to the MATLAB function callbacks. This pair is supported with -use_instance_obj only. For more details, see the field in the table -use_instance_obj Fields.

    -use_instance_obj Fields

    FieldRead or Write AccessDescription
    tnextWrite-only

    Schedule a callback during the set time. This field is equivalent to old tnext. For example, this code schedules a callback 5 nanoseconds from tnow.

    hdl_instance_obj.tnext = hdl_instance_obj.tnow + 5e-9
    userdataRead or WriteStore state variables of the current matlabtb instance. You can retrieve the variables the next time the callback of this instance is scheduled.
    simstatusRead-only

    Store the status of the HDL simulator. The HDL Verifier software sets this field to Init during the first callback for this particular instance and to Running thereafter. simstatus is a read-only field.

    >> hdl_instance_obj.simstatus
    
    ans=
          Init
    instanceRead-only

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

    In the HDL simulator:

    hdlsim> matlabtb osc_top -mfunc oscfilter use_instance_obj
    

    In MATLAB:

    >> hdl_instance_obj.instance
    
    ans=
    		osc_top
    argumentRead-only

    Store the argument that is set by the -argument pair. 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 the -use_instance_objpair. Otherwise, the command ignores the argument. argument is a read-only property.

    >> hdl_instance_obj.argument
    
    ans= 
        	foo
    
    portinfoRead-only

    Store information about the VHDL and Verilog ports that are 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 type, direction, and size of the port. 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.

    tscaleRead-only

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

    tnowRead-only

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

    hdl_instance_obj.tnext = hld_instance_obj.tnow + fastestrate;
    
    portvaluesRead or Write

    Store the current values of and set new values for the output and input ports for a matlabtb instance. For example:

    >> hdl_instance_obj.portvalues
    
    ans =
    Read Only Input ports:
    	clk_enable: []
    	clk: []
    	reset: []
    Read/Write Output ports:
    	sine_out: [22x1 char]
    linkmodeRead-only

    Store the status of the callback. HDL Verifier sets this field to 'testbench' if the callback is associated with the matlabtb command and 'component' if the callback is associated with the matlabcp command. linkmode is a read-only property.

    >> hdl_instance_obj.linkmode
    
    ans=
    	component
    Introduced in R2008a