svdpiConfiguration

R2026b

Configure workflows for UVM and SystemVerilog component generation from MATLAB

Since R2023a

Description

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

The svdpiConfiguration object controls the creation of a universal verification methodology (UVM) component or a SystemVerilog DPI component from a MATLAB^® function.

Creation

Syntax

svdpiObj = svdpiConfiguration()

svdpiObj = svdpiConfiguration(ComponentKind)

svdpiObj = svdpiConfiguration(___,Name=Value)

Description

svdpiObj = svdpiConfiguration() creates an svdpiConfiguration object for a sequential module.

svdpiObj = svdpiConfiguration(ComponentKind) creates an svdpiConfiguration object for a SystemVerilog module or a UVM component specified by ComponentKind.

svdpiObj = svdpiConfiguration(___,Name=Value) creates an svdpiConfiguration object with additional options specified by one or more name-value pair arguments.

Properties

Code Generation

CoderConfiguration — A coder.config object

configuration object

Specify a custom configuration object using coder.config('dll'). The configuration object build type must be set as dynamic library. See coder.config (MATLAB Coder).

Tip

If you have a license for Embedded Coder^®, the coder.config object uses it by default. If you do not want to use Embedded Coder, you must provide an svdpiConfiguration object and specify ecoder=false to the CoderConfiguration property. For example:

cgcfg = coder.config('dll', ecoder=false) 
svcfg = svdpiConfiguration
svcfg.CoderConfiguration = cgcfg;
dpigen fun -args sample -testbench fun_tb -config svcfg

PreserveStructures — Preserve structures

0 (default) | 1

Choose how the SystemVerilog ports are generated when your MATLAB function includes a port that is a composite data type, such as struct or complex.

• 1 — Retain structures by defining new SystemVerilog types.

• 0 — Flatten composite data types to its individual members in SystemVerilog.

Data Types: logical

ScalarizePorts — Flatten vectors and matrices

0 (default) | 1

Choose how the SystemVerilog ports are generated when your MATLAB function includes a port that is a vector or matrix data type.

• 1 — Each element in the array or matrix creates a scalar port in the generated SystemVerilog code.

• 0 — The generated SystemVerilog ports preserve the array or matrix as defined in MATLAB.

Data Types: logical

MATLABFunctionName — Name of MATLAB function

character vector | string

Name of MATLAB function to generate the DPI component from, specified as a character vector or string.

This is an optional property. If you use the uvmfTestBenchConfiguration object, then this is the only way in which you can specify the MATLAB function name associated with this object.

Example: "funcName"

Data Types: char | string

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
variable size numeric vectors	open array
variable size character vector	string

Dependencies

To enable this property, set the ComponentKind property to 'uvmf-predictor', 'uvmf-sequence', or 'uvmf-custom'.

InputArgs — 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. InputArgs is a cell array specifying the type of each function argument. Elements are converted to types using coder.typeof.

This property has the same functionality as the codegen (MATLAB Coder) function argument args.

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

Dependencies

To enable this property, set the ComponentKind property to 'uvmf-predictor', 'uvmf-sequence', or 'uvmf-custom'.

Component Information

ComponentKind — Kind of SystemVerilog or UVM component to generate

'sequential-module' (default) | 'sequential-module-varsize' | 'combinational-module' | 'uvm-predictor' | 'uvm-sequence' | 'uvm-scoreboard' | 'custom' | 'uvmf-sequence' | 'uvmf-predictor' | 'uvmf-custom'

Select a built-in template for SystemVerilog DPI or UVM component generation, specified as 'template-name'. For a customized template, specify 'custom'.

You can override values of built-in template variables through this configuration object. A common use of overrides is to ensure compatibility of the generated code with any existing testbench or component library by avoiding type-name conflicts.

Common overrides for all templates include:

• ComponentTypeName, TestBenchTypeName — override the default values by setting the ComponentTypeName and TestBenchTypeName properties in the svdpiConfiguration object.

• ComponentPackageTypeName — override the default value by setting the TemplateDictionary property in the svdpiConfiguration object.

Optional template-specific overrides:

• UVM sequence:

  • SequenceTransTypeName, SequencerTypeName, SequenceCount, SequenceFlushCount, ConfigObjTypeName — override the default values by setting the TemplateDictionary property in the svdpiConfiguration object.

• UVM predictor:

  • InputTransTypeName, OutputTransTypeName, ConfigObjTypeName — override the default values by setting the TemplateDictionary property in the svdpiConfiguration object.

• UVM scoreboard:

  • InputTransTypeName, OutputTransTypeName, ConfigObjTypeName — override the default values by setting the TemplateDictionary property in the svdpiConfiguration object.

• PREDICTOR_INPUTS, MONITOR_INPUTS, CONFIG_OBJECT_INPUTS — map HDL ports to groups by using the addPortGroup object function with the svdpiConfiguration object.

For more information about the template engine, see SystemVerilog and UVM Templates.

ComponentTypeName — Type name for the main module or component

MATLAB function name (default) | string | character vector

Component type name, specified as a string or character vector. The dpigen function uses this argument to name the generated component and the SystemVerilog package files. If you do not specify a component type name, the component type name is the MATLAB function name.

TestBenchTypeName — Type name for the testbench component

tb_function (default) | string | character vector

Testbench type name, specified as a string or character vector. The dpigen function uses this argument to name the generated SystemVerilog testbench and its associated files. If you do not specify a component type name, the testbench type name is uses the name of the MATLAB testbench function.

In the code below, the dpigen function generates a predictor component, and creates a testbench module for it using the provided testbench function name (my_tb).

c = svdpiConfiguration('uvm-predictor');
dpigen fooBar -testbench my_tb -config c;

To override that testbench name, specify the desired SystemVerilog name. In this example it is specified as pulse_framed_tb.

c = svdpiConfiguration('uvm-predictor');
c.TestBenchTypeName = 'pulse_framed_tb';
dpigen fooBar -testbench my_tb -config c;

Template

TemplateDictionary — List of name and value pairs defined in the template file

cell array of name-value pairs

Each template defines a template dictionary, which declares template-specific variables. Assign values to these variables as a cell array of variable names followed by values.

The template files expand tokens of the form %<gtd.Name> with Value. GTD stands for global template dictionary, and it holds predefined built-in values in addition to the variables you define in the configuration object. Names and values must be character arrays.

Override default template values here such as transaction type names for UVM components or sequence counts for a UVM sequence component. To see an example, go to Override Template Variable Values.

Example:

c = svdpiConfiguration('uvm-sequence');
c.TemplateDictionary = {
     'SequenceCount',      '15',
     'SequenceFlushCount', '2',
   };

In the template file, the line:

repeat (%<gtd.SequenceCount>)

will be replaced with:

repeat (15)

PortGroups — Display custom lists of port names used by template files

Read-only: string | character vector

This property is read-only.

A port group represents a section of the generated interface that logically belongs together. For example:

• All inputs to a module belong to the ALL_INPUTS port group in the built-in templates.

• All inputs to a UVM scoreboard module that originate in the monitor belong to the MONITOR_INPUTS port group in the UVM scoreboard template.

• Configuration inputs to a scoreboard, sequence, or predictor belong to the CONFIG_OBJECT_INPUTS interface.

Several built-in groups exist such as ALL_INPUTS and ALL_OUTPUTS. Templates utilize port groups to generate wrapper code specific to that group.

You can modify a port group by using the addPortGroup or removePortGroup functions respectively.

For example, add port groups to a scoreboard:

c = svdpiConfiguration('uvm-scoreboard');
     addPortGroup(c, 'PREDICTOR_INPUTS', {'PeakSq','Location','FilterOut_re','FilterOut_im'});
     addPortGroup(c, 'MONITOR_INPUTS', {'PeakSqImplIn','LocationImplIn',...
                     'FilterOutImpl_re','FilterOutImpl_im'}); 
     addPortGroup(c, 'CONFIG_OBJECT_INPUTS', 'pErrorPercentThreshold'); 

In the template file, the configuration object definition can include the following code to allow randomization of variables:

%foreach io = ptd.CONFIG_OBJECT_INPUTS_size
    %<ptd.CONFIG_OBJECT_INPUTS[io].PORT_RAND_VAR_DECL>
%endforeach

Note that in ptd.CONFIG_OBJECT_INPUTS_size the ptd stands for port template dictionary.

ComponentTemplateFiles — Template files to use when generating module or component

cell array

The path to the template files to use when processing a module or component, specified as a cell array of one or more templates.

A template file can generate several files per component. Template file location and name can use an absolute path or relative path. Relative paths are converted to absolute paths.

Dependencies

To write this property, set the ComponentKind property to 'custom'. Otherwise, this property is read-only.

TestBenchTemplateFiles — Template files to use when generating testbench

cell array

The path to the template files to use when processing a testbench for a component, specified as a string or as a cell array for multiple templates.

A template file can generate several files per component. Filenames can use an absolute path or relative path. Relative paths are converted to absolute paths.

Dependencies

To write this property, set the ComponentKind property to 'custom'. Otherwise, this property is read-only.

Object Functions

addPortGroup	Add port group mapping to svdpiConfiguration or DPICustomTemplateConfiguration object
removePortGroup	Remove port group mapping from svdpiConfiguration or DPICustomTemplateConfiguration object

Examples

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

Version History

Introduced in R2023a

R2023b: Sequence and Predictor templates support configuration ports

Add configuration ports to your UVM sequence or predictor by adding a CONFIG_OBJECT_INPUTS port group. Use the addPortGroup function to map configuration inputs to the UVM component.

The predictor template has two new port groups: PREDICTOR_INPUTS and CONFIG_OBJECT_INPUTS. By default, ALL_INPUTS = PREDICTOR_INPUTS. You can define CONFIG_OBJECT_INPUTS or PREDICTOR_INPUTS, and then ALL_INPUTS = PREDICTOR_INPUTS + CONFIG_OBJECT_INPUTS.

Similarly, the sequence template has two new port groups: SEQUENCE_INPUTS and CONFIG_OBJECT_INPUTS. By default, ALL_INPUTS = SEQUENCE_INPUTS. You can define CONFIG_OBJECT_INPUTS or SEQUENCE_INPUTS, and then ALL_INPUTS = SEQUENCE_INPUTS + CONFIG_OBJECT_INPUTS.