dpigen

Generate UVM or SystemVerilog DPI component from MATLAB function

collapse all in page

Syntax

dpigen fcn -args args
dpigen fcn -config config -args args
dpigen fcn -args args -testbench tb_name options files -c -launchreport -PortsDataType type -ComponentTemplateType template_type

Description

Add-On Required: This feature requires the ASIC Testbench for HDL Verifier add-on.

dpigen fcn -args args generates a DPI component shared library from MATLAB® function fcn and all the functions that fcn calls.

  • .dll for shared libraries on Microsoft® Windows® systems

  • .so for shared libraries on Linux® systems

The dpigen function also generates a SystemVerilog package file, which contains the function declarations.

The argument -args args specifies the type of inputs the generated code can accept. The generated DPI component is specialized to the class and size of the inputs. Using this information, dpigen generates a DPI component that emulates the behavior of the MATLAB function.

fcn and —args args are required input arguments. The MATLAB function must be on the MATLAB path or in the current folder.

example

dpigen fcn -config config -args args generates a SystemVerilog or a UVM component based on the template and settings specified in an svdpiConfiguration object. For more information about SystemVerilog and UVM templates, see SystemVerilog and UVM Templates.

example

dpigen fcn -args args -testbench tb_name options files -c -launchreport -PortsDataType type -ComponentTemplateType template_type generates a SystemVerilog DPI component shared library according to the options specified. You can specify zero or more optional arguments, in any order.

  • -testbench tb_name also generates a testbench for the SystemVerilog DPI component. The MATLAB testbench must be on the MATLAB path or in the current folder.

  • options specifies additional options for the compiler and code generation.

  • files specifies custom files to include in the generated code.

  • -c generates C code only.

  • -launchreport generates and opens a code generation report.

  • -PortsDataType specifies the SystemVerilog data type to use for ports.

  • -ComponentTemplateType specifies whether the design is sequential or combinational.

When generating a DPI component, it creates a shared library specific to that host platform. For example, if you use 64-bit MATLAB on Windows, you get a 64-bit DLL, which can be used only with a 64-bit HDL simulator in Windows. For porting the generated component from Windows to Linux, see Port Generated Component and Testbench to Linux.

example

Examples

collapse all

Generate a DPI component and testbench for the function fun.m and its associated testbench, fun_tb.m. The dpigen function compiles the component automatically using the default compiler. The -args option specifies that the first input type is a double and the second input type is an int8.

dpigen -testbench fun_tb.m -I E:\HDLTools\ModelSim\10.2c-mw-0\questa_sim\include fun.m 
      -args {double(0),int8(0)}
### Generating DPI-C Wrapper fun_dpi.c
### Generating DPI-C Wrapper header file fun_dpi.h
### Generating SystemVerilog module package fun_dpi_pkg.sv
### Generating SystemVerilog module fun_dpi.sv
### Generating makefiles for: fun_dpi
### Compiling the DPI Component
### Generating SystemVerilog test bench fun_tb.sv
### Generating test bench simulation script for Siemens Questa/ModelSim run_tb_mq.do
### Generating test bench simulation script for Cadence Xcelium run_tb_xcelium.sh
### Generating test bench simulation script for Synopsys VCS run_tb_vcs.sh
### Generating test bench simulation script for Vivado Simulator run_tb_vivado.bat

Generate a DPI component and a testbench for the function fun.m and its associated testbench, fun_tb.m. To prevent the dpigen function from compiling the library, include the -c option. Send the source code output to 'MyDPIProject'.

dpigen -c -d MyDPIProject -testbench fun_tb.m fun.m -args {double(0),int8(0)}
### Generating DPI-C Wrapper fun_dpi.c
### Generating DPI-C Wrapper header file fun_dpi.h
### Generating SystemVerilog module package fun_dpi_pkg.sv
### Generating SystemVerilog module fun_dpi.sv
### Generating makefiles for: fun_dpi
### Generating SystemVerilog test bench fun_tb.sv
### Generating test bench simulation script for Siemens Questa/ModelSim run_tb_mq.do
### Generating test bench simulation script for Cadence Xcelium run_tb_xcelium.sh
### Generating test bench simulation script for Synopsys VCS run_tb_vcs.sh
### Generating test bench simulation script for Vivado Simulator run_tb_vivado.bat
Open Live Script

This example shows how to generate a SystemVerilog DPI (SVDPI) component from the sineWaveGen function by using the default template in HDL Verifier™.

Use Default Template to Create SVDPI Module

Create a configuration object with the default template, and use it with the dpigen function. Note the generated SystemVerilog files:

  • sineWaveGen.sv

  • sineWaveGen_pkg.sv

c=svdpiConfiguration();
dpigen -config c -args {0,0} sineWaveGen
### Generating DPI-C Wrapper sineWaveGen_dpi.c
### Generating DPI-C Wrapper header file sineWaveGen_dpi.h
### Generating file sineWaveGen_pkg.sv
### Generating file sineWaveGen.sv
### Generating makefiles for: sineWaveGen_dpi
Code generation successful.

Rename the generated module to myDut. Note the generated SystemVerilog files:

  • myDut.sv

  • myDut_pkg.sv

c.ComponentTypeName = 'myDut';
dpigen -config c -args {0,0} sineWaveGen
### Generating DPI-C Wrapper sineWaveGen_dpi.c
### Generating DPI-C Wrapper header file sineWaveGen_dpi.h
### Generating file myDut_pkg.sv
### Generating file myDut.sv
### Generating makefiles for: sineWaveGen_dpi
Code generation successful.

Use Template to Create UVM Predictor

Create a configuration object with the UVM predictor template, and use it with the dpigen function. Note the generated SystemVerilog files:

  • predictor_input_trans.sv

  • predictor_output_trans.sv

  • sinWave_predictor_pkg.sv

  • sinWave_predictor.sv

c = svdpiConfiguration('uvm-predictor');
c.ComponentTypeName = 'sinWave_predictor';
dpigen sineWaveGen -config c -args {0,0}
### Generating DPI-C Wrapper sineWaveGen_dpi.c
### Generating DPI-C Wrapper header file sineWaveGen_dpi.h
### Generating file sinWave_predictor_pkg.sv
### Generating file sineWaveGen_predictor_input_trans.sv
### Generating file sineWaveGen_predictor_output_trans.sv
### Generating file sineWaveGen_predictor_cfgobj.sv
### Generating file sinWave_predictor.sv
### Generating makefiles for: sineWaveGen_dpi
Code generation successful.

Override Template Variable Values

Now, change the generated SystemVerilog transaction names.

  • Override the default predictor_input_trans and rename it sineWaveTrans.

  • Override the default predictor_output_trans and rename it sineWaveOut.

To assign new values to the InputTransTypeName and OutputTransTypeName variables in the template dictionary, set the TemplateDictionary property.

c.TemplateDictionary = {
    'InputTransTypeName','sineWaveTrans',
    'OutputTransTypeName','sineWaveOut'
};
dpigen sineWaveGen -config c -args {0,0}
### Generating DPI-C Wrapper sineWaveGen_dpi.c
### Generating DPI-C Wrapper header file sineWaveGen_dpi.h
### Generating file sinWave_predictor_pkg.sv
### Generating file sineWaveTrans.sv
### Generating file sineWaveOut.sv
### Generating file sineWaveGen_predictor_cfgobj.sv
### Generating file sinWave_predictor.sv
### Generating makefiles for: sineWaveGen_dpi
Code generation successful.

Input Arguments

collapse all

Name of MATLAB function to generate the DPI component from, specified as a character vector or string scalar. The MATLAB function must be on the MATLAB path or in the current folder.

Specify custom configuration parameters using an svdpiConfiguration object. The object includes custom C-code generation parameters using a coder.config('dll') object and specification of the kind of SystemVerilog component to generate, such as sequential-module, uvm-predictor, uvm-sequence, or custom.

To avoid using conflicting options, do not combine a configuration object with command-line options. Usually the config object offers more options than the command-line flags.

Note

The option to specify a coder.config object will be deprecated in a future release. Transition to using an svdpiConfiguration object.

Not all the options in the coder.config object are compatible with the DPI feature. If you try to use an incompatible option, an error message informs you of which options are not compatible.

Data type and size of MATLAB function inputs, specified as a cell array. Specify the input types that the generated DPI component accepts. args is a cell array specifying the type of each function argument. Elements are converted to types using coder.typeof. This argument is required.

This argument has the same functionality as the codegen (MATLAB Coder) function argument args. args applies only to the function, fcn.

Example: -args {double(0),int8(0)}

MATLAB testbench used to generate testbench for generated DPI component, specified as a character vector or string scalar. The dpigen function uses this testbench to generate a SystemVerilog testbench along with data files and execution scripts. The MATLAB testbench must be on the MATLAB path or in the current folder.

The -testbench argument requires a Fixed-Point Designer™ license.

Example: -testbench My_Test_bench.m

Compiler and codegen options, specified as a character vector or string scalar. These options are a subset of the options for codegen (MATLAB Coder). The dpigen function gives precedence to individual command-line options over options specified using a configuration object. If command-line options conflict, the right-most option prevails.

You can specify zero or more optional arguments, in any order. For example:

dpigen -c -d MyDPIProject -testbench fun_tb.m fun.m -args {double(0),int8(0)} -launchreport

Option flagOption value
-I include_path

Specifies the path to folders containing headers and library files needed for codegen, specified as a character vector or string scalar. Add include_path to the beginning of the code generation path.

For example:

-I E:\HDLTools\ModelSim\10.2c-mw-0\questa_sim\include

include_path must not contain spaces, which can lead to code generation failures in certain operating system configurations. If the path contains non 7-bit ASCII characters, such as Japanese characters, dpigen might not find files on this path.

When converting MATLAB code to C/C++ code, dpigen searches the code generation path first.

Alternatively, you can specify the include path with the files input argument.

-o output

Specify the name of the generated component as a character vector or string scalar. The dpigen function adds a platform-specific extension to this name for the shared library:

  • .dll for C/C++ dynamic libraries on Microsoft Windows systems

  • .so for C/C++ dynamic libraries on Linux systems

-d dir

Specify the output folder. All generated files are placed in dir. By default, files are placed in ./codegen/dll/<function>.

For example, when dpigen compiles the function fun.m, the generated code is placed in ./codegen/dll/fun.

-globals globals

Specify initial values for global variables in MATLAB files. The global variables in your function are initialized to the values in the cell array GLOBALS. The cell array provides the name and initial value of each global variable.

If you do not provide initial values for global variables using the -globals option, dpigen checks for the variables in the MATLAB global workspace. If you do not supply an initial value, dpigen generates an error.

MATLAB Coder™ and MATLAB each have their own copies of global data. For consistency, synchronize their global data whenever the two products interact. If you do not synchronize the data, their global variables might differ.

-rowmajorSpecify this option to generate code that uses row-major array layout in all functions. If this option is not specified, the generated code uses column-major array layout. To override the used array layout for a specific function and the functions it calls, specify coder.rowMajor or coder.columnMajor in the body of the function.

Custom files to include in the generated code, each file specified as a character vector or string scalar. The files build along with the MATLAB function specified by fcn. List each file separately, separated by a space. The following extensions are supported.

File TypeDescription
.cCustom C file
.cppCustom C++ file
.hCustom header file (included by all generated files)
.oObject file
.objObject file
.aLibrary file
.soLibrary file
.libLibrary file

In Windows, if your MATLAB function contains matrix or vector output or input arguments, use the files option to specify the library (.lib) that contains the ModelSim™ DPI definitions. Otherwise, you must manually modify the generated Makefile (*.mk) and then compile the library separately.

Option to generate C code without compiling the DPI component, specified as the character vector -c. If you do not use the -c option, dpigen tries to compile the DPI component using the default compiler. To select a different compiler, use the -config option and refer to the codegen (MATLAB Coder) documentation for instructions on specifying the different options.

Option to generate and open a code generation report, specified as the character vector -launchreport.

Note

The -PortsDataType argument will be removed in a future release. To specify the ports data type, create an svdpiConfiguration object, and set the PortsDataType property to the required value.

Select the SystemVerilog data type that will be used for ports. Choose from three possible values:

  • CompatibleCType – Generate a compatible C type interface for the port.

  • BitVector – Generate a bit vector type interface for the port.

  • LogicVector – Generate a logic vector type interface for the port.

This table shows the MATLAB data-type in the left column, and the generated SystemVerilog type for each value of PortsDataType.

Generated SystemVerilog Types

MATLABSystemVerilog
Compatible C TypeLogic VectorBit Vector
uint8byte unsignedlogic [7:0] bit [7:0]
uint16shortint unsignedlogic [15:0] bit [15:0]
uint32int unsignedlogic [31:0]bit [31:0]
uint64longint unsignedlogic [63:0]bit [63:0]
int8bytelogic signed [7:0]bit signed [7:0]
int16shortintlogic signed [15:0]bit signed [15:0]
int32intlogic signed [31:0]bit signed [31:0]
int64longintlogic signed [63:0]bit signed [63:0]
logicalbyte unsignedlogic [0:0]bit [0:0]
fi (fixed-point data type)

Depends on the fixed-point word length. If the fixed-point word length is greater than the host word size (for example, 64-bit vs. 32-bit), then this data type cannot be converted to a SystemVerilog data type by MATLAB Coder and you will get an error. If the fixed-point word length is less than or equal to the host word size, MATLAB Coder converts the fixed-point data type to a built-in C type.

logic [n-1:0]

logic signed [n-1:0]

The logic vector length (n) is equal to the wordlength. The sign is inherited from the fixed point type.

bit [n-1:0]

bit signed [n-1:0]

The bit vector length (n) is equal to the wordlength. The sign is inherited from the fixed point type.

singleshortreal
doublereal
complex

The coder flattens complex signals into real and imaginary parts in the SystemVerilog component.

vectors, matrices

arrays

For example, a 4-by-2 matrix in MATLAB is converted into a one-dimensional array of eight elements in SystemVerilog. By default, the coder flattens matrices in column-major order. To change to row-major order, use the -rowmajor option with the dpigen function. For additional information, see Generate Code That Uses Row-Major Array Layout (MATLAB Coder).

structure

The coder flattens structure elements into separate ports in the SystemVerilog component.

enumerated data typesenum

Select the DPI component template for the SystemVerilog wrapper.

  • Sequential – to specify a sequential design, with registers.

  • Combinational – to specify a combinational design, with no registers.

Note

The -ComponentTemplateType argument will be removed in a future release. To specify the component template type, create an svdpiConfiguration object, and set the ComponentKind property to the required template.

Dependencies

When the config argument is set to a svdpiConfiguration object, this argument is ignored.

If your function contains persistent variable it is considered a sequential design.

Version History

Introduced in R2014b

expand all

See Also

| (MATLAB Coder) |

Topics