dpigen

Generate SystemVerilog DPI component from MATLAB function

collapse all in page

Syntax

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

Description

example

dpigen fcn -args args generates a SystemVerilog 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 -args args -testbench tb_name -options options files -c -launchreport -PortsDataType 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 test bench for the SystemVerilog DPI component. The MATLAB test bench must be on the MATLAB path or in the current folder.

  • -options 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.

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 Test Bench to Linux.

Examples

collapse all

Generate a DPI component and test bench for the function fun.m and its associated test bench, 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 Mentor Graphics QuestaSim/Modelsim run_tb_mq.do
### Generating test bench simulation script for Cadence Incisive run_tb_incisive.sh
### 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 test bench for the function fun.m and its associated test bench, fun_tb.m. To prevent the dipgen 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 Mentor Graphics ModelSim/QuestaSim run_tb_mq.do
### Generating test bench simulation script for Cadence Incisive run_tb_incisive.sh
### 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

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.

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 test bench used to generate test bench for generated DPI component, specified as a character vector or string scalar. The dpigen function uses this test bench to generate a SystemVerilog test bench along with data files and execution scripts. The MATLAB test bench must be on the MATLAB path or in the current folder.

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.

-config config

Specify a custom configuration object using coder.config('dll'). The DPI component must be a shared library.

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

Not all the options in the 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.

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

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.

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

See Also

| (MATLAB Coder)

Topics

Introduced in R2014b

HDL Verifier Documentation

Support