Documentation

dpigen

Generate SystemVerilog DPI component from MATLAB function

Syntax

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

Description

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

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 -args args -testbench tb_name -options options files -c -launchreport 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.

You cannot generate a DPI component for use on a different platform than the MATLAB host. For instance 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.

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 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 ModelSim/QuestaSim run_tb_mq.do
### Generating test bench simulation script for Cadence Incisive run_tb_ncsim.sh
### Generating test bench simulation script for Synopsys VCS run_tb_vcs.sh

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 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_ncsim.sh
### Generating test bench simulation script for Synopsys VCS run_tb_vcs.sh

Input Arguments

collapse all

Name of MATLAB function to generate the DPI component from, specified as a character vector. 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 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. 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 character vectors. These options are a subset of the options for codegen. 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. 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. The dpigen function adds a platform-specific extension to this name for the shared library.

-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. 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 documentation for instructions on specifying the different options.

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

See Also

Introduced in R2014b

Was this topic helpful?