dpigen

Generate UVM or SystemVerilog DPI component from MATLAB function

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

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

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.

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.

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.

Examples

Generate DPI Component and Testbench

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 DPI Component and Testbench Without Compiling

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

Generate SystemVerilog DPI Component from MATLAB Function

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 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 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 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 makefiles for: sineWaveGen_dpi
Code generation successful.

Input Arguments

fcn — Name of MATLAB function

character vector | string scalar

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.

-config — SystemVerilog DPI configuration

svdpiConfiguration object | coder.config object

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.

-args args — Data type and size of MATLAB function inputs

cell array

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)}

-testbench tb_name — MATLAB testbench used to generate testbench for generated DPI component

character vector | string scalar

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

options — Compiler and code generation options

character vector | string scalar

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 flag	Option 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.
-rowmajor	Specify 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.

files — Custom files to include in the generated code

character vector | string scalar

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 Type	Description
.c	Custom C file
.cpp	Custom C++ file
.h	Custom header file (included by all generated files)
.o	Object file
.obj	Object file
.a	Library file
.so	Library file
.lib	Library 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.

-c — Option to generate C code only

character vector | string scalar

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.

-launchreport — Option to generate and open a code generation report

character vector | string scalar

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

-PortsDataType — generated SystemVerilog data type for ports

Compatible C Type | Bit Vector | Logic Vector

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

MATLAB	SystemVerilog
	Compatible C Type	Logic Vector	Bit Vector
uint8	byte unsigned	logic [7:0]	bit [7:0]
uint16	shortint unsigned	logic [15:0]	bit [15:0]
uint32	int unsigned	logic [31:0]	bit [31:0]
uint64	longint unsigned	logic [63:0]	bit [63:0]
int8	byte	logic signed [7:0]	bit signed [7:0]
int16	shortint	logic signed [15:0]	bit signed [15:0]
int32	int	logic signed [31:0]	bit signed [31:0]
int64	longint	logic signed [63:0]	bit signed [63:0]
logical	byte unsigned	logic [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.
single	shortreal
double	real
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 types	enum

-ComponentTemplateType — Option to generate combinational SystemVerilog DPI component

Sequential (default) | Combinational

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.

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

R2023a: Support for svdpiConfiguration object

Generate a UVM component or a SystemVerilog DPI component from a MATLAB function. Use the new svdpiConfiguration object to specify the kind of component and a template to use for code generation. Select a built-in template for common component kinds, or create your own custom template.

R2023a: Not recommended

Using the config argument with a coder.config object is not recommended. Use the new svdpiConfiguration object instead. This object adds support for using the SystemVerilog and UVM Templates, and it allows generation of UVM components from a MATLAB function in addition to SystemVerilog DPI components.

R2022a: Support for combinational designs

Generate a DPI component for a combinational MATLAB function so that outputs immediately reflect changes in the inputs.

Use the dpigen function with the new -ComponentTemplateType argument set to Combinational.

dpigen myCombFunction -args {0,0} -ComponentTemplateType Combinational

R2020b: Function input renamed

The FixedpointDataType name-value pair argument has been renamed PortsDataType.

R2018a: Support for row-major arrays

You can now generate DPI-C code in a row major array. To specify this layout, at the MATLAB command prompt, enter:

 dpigen -rowmajor

Alternatively, insert coder.rowMajor in a function body.