Main Content

Template Engine Language Syntax

Template files are SystemVerilog code parameterized to generate different kinds of SystemVerilog DPI components and UVM artifacts. Templates use template directives and template variables to generate components for specific variable values. You can assign variable values from the svdpiConfiguration object properties, local template dictionaries, and design-specific information.

For applications that cannot use built-in template files, you can create a configuration with the ComponentKind property set to custom and write custom template files.

Note

This feature requires the ASIC Testbench for HDL Verifier add-on.

Template Anatomy

A template first defines template-specific variables in a local dictionary. It may also include template variables that defined in other files such as the SystemVerilogTemplateLibrary.svt. For example:

%<BEGIN_LOCAL_DICTIONARY>
ComponentPackageTypeName=%<ComponentTypeName>_pkg
InputTransTypeName=my_input_trans
OutputTransTypeName=my_output_trans
%<END_LOCAL_DICTIONARY>
%<INCLUDE SystemVerilogTemplateLibrary.svt>

After defining or including the required template variables, the template specifies the contents of the SystemVerilog artifacts that it generates between BEGIN_FILE and END_FILE directives. The content is composed of SystemVerilog code and template variables defined in the local dictionary or included in the file. At run time, the template engine assigns your values to these template variables and replaces them with SystemVerilog text. For example, the top part of the combinational module template has this structure:

%<BEGIN_FILE %<ComponentTypeName>.sv>
// -------------------------------------------
// File:    %<ComponentTypeName>.sv
%<SVTLCommonHeader>    // this can be a common company header
`timescale 1ns/1ns     // SV timescale directive
import %<ComponentPackageTypeName>::*; // Importing component SV package

module %<ComponentTypeName> (          // Module interface declaration 
  %<BEGIN_FOREACH_PORT_CHOP ALL_INS_AND_OUTS>
    %<PORT_DECL> 
  %<END_FOREACH_PORT_CHOP>
);

.
.
.
endmodule

%<END_FILE>

When the ComponentTypeName is sineWaveGen the engine generates the output into a file named sineWaveGen.sv as indicated by the BEGIN_FILE and BEGIN_FILE directives.

For an example, see Generate SystemVerilog DPI Component from MATLAB Function.

// -------------------------------------------
// File:    sineWaveGen.sv

// -------------------------------------------
// Created: 03-Jan-2023 19:04:05
// Tools  : Generated by MATLAB 9.14 and HDL Verifier 7.1

// -------------------------------------------

`timescale 1ns/1ns
import sineWaveGen_pkg::*;

module sineWaveGen (
  input real amp  ,
  input real freq  ,
  output real y [0:99]
);
.
.
.
endmodule

Template Directives

Template directives provide instructions for the template engine to generate files, iterate on port groups, define and use variables, and emit SystemVerilog code.

Template FeatureTemplate DirectiveOperation

Template comment

%</*  
…  
*/> 

The template engine ignores text within these comment markers when processing a template.

Mark start and end of a resulting output file

%<BEGIN_FILE filename>  
… 
%<END_FILE>  

HDL Verifier™ writes the processed content between these directives into filename. filename itself can use a template variable, for example:

%<ComponentTypeName>.sv

Include template
%<INCLUDE filename>  

Include another template file in a parent template file.

This directive inlines the contents of filename in the template file. filename itself can use a template variable.

Local template variables
%<BEGIN_LOCAL_DICTIONARY>  
…  
%<END_LOCAL_DICTIONARY>   

Define template variables local to this template file.

Specify dictionary entries in the form variable=value. Template code can utilize the variable using a %<Var> token. Specify multi-line variable definitions between the %<BEGIN_VARIABLE_DEFINITION> and %<END_VARIABLE_DEFINITION>directives.

You can override variable values by setting the TemplateDictionary property of the svdpiConfiguration object. Variable lookups have a hierarchy. See the %<VAR_NAME> directive for more information.

Template variable definition
%<BEGIN_VARIABLE_DEFINITION>  
…  
%<END_VARIABLE_DEFINITION> 

Define multi-line template variables inside a dictionary.

Define a template variable across any number of lines. The contents are not variable expanded but rather placed as-is into the template when referenced.

Iterate over a port group to emit code
%<BEGIN_FOREACH_PORT PortGroup> 
… 
%<END_FOREACH_PORT>

Expand template code between these directives for each port in PortGroup. These port groups are built-in:

  • ALL_PORTS, ALL_INPUTS, ALL_OUTPUTS, ALL_SEQ_CONTROL, ALL_INS_AND_OUTS

  • ALL_FIELD_MACRO_INPUTS, ALL_FIELD_MACRO_OUTPUTS

  • ALL_VARSIZE_OUTPUTS, ALL_NONVARSIZE_OUTPUTS

You can define custom groups by setting the PortGroups property of the svdpiConfiguration object. On each iteration, HDL Verifier creates a local, port-specific dictionary.

Iterate over a port group to emit code
%<BEGIN_FOREACH_PORT_CHOP PortGroup> 
… 
%<END_FOREACH_PORT_CHOP>

Iterate over PortGroup to emit code, removing the final character at the end of the expansion.

Operates the same as %<BEGIN/END_FOREACH_PORT> but also removes the last character. Use this directive to accommodate constructs such as function argument lists that require a comma (‘,’) between arguments but no comma after the last one.

Variable name
%<VAR_NAME>

Expand the template variable.

When generating code, HDL Verifier replaces %<VAR_NAME> with its assigned value. It searches for template variable values in the following order. Once HDL Verifier finds a value, the search stops.

  1. Dictionary from svdpiConfiguration object

  2. Local port dictionary of the current PortGroup port

  3. A dictionary from an INCLUDE directive, for example, the SystemVerilogTemplateLibrary

  4. A dictionary local to this template file

  5. A built-in variable

Template Variables

When processing a template, HDL Verifier replaces template variables with values. Most variable values are the result of entries in a global and local dictionary. This table describes the predefined variables in the system in their lookup order. You can build your own library of variable definitions with custom dictionaries.

Variable Source Variables

Global dictionary

This dictionary is defined in the svdpiConfiguration object. It reflects the property values that you set in addition to the dictionary defined by the TemplateDictionary property. The global dictionary also includes the port lists defined in the PortGroups property.

  • ComponentKind

  • ComponentTypeName

  • TestBenchTypeName

  • ComponentTemplateFiles

  • TestBenchTemplateFiles

  • MATLABTestBenchFunctionName

  • MATLABFunctionName

  • DLLOutputName

  • TemplateDictionary contents

  • PortGroupName1

  • PortGroupName2

Port dictionary

There are several built-in port groups and you can define your own groups using the PortGroups property of the svdpiConfiguration object.

In a %<BEGIN/END_FOREACH_PORT> template block, you can define several template variables specific to the port in each iteration.

  • PORT_NAME

  • PORT_DIRECTION

  • PORT_DATATYPE

  • PORT_DIMENSIONS

  • PORT_RAND_QUALIFIER

  • PORT_FIELD_MACRO_TYPE

Convenience variables for declarations:

  • PORT_DECL

  • PORT_VAR_DECL

  • PORT_RAND_VAR_DECL

  • PORT_FIELD_MACRO_DECL

Local dictionaries

A template file can define a dictionary using the %<BEGIN_LOCAL_DICTIONARY>. If more than one dictionary is present, either directly or through an INCLUDE, then the local dictionary is the concatenation of all of them. If a variable is specified more than once in different dictionaries, the definition supersedes all prior definitions.

HDL Verifier provides a special dictionary, SystemVerilogTemplateLibrary, which you can include in a template using:

%<INCLUDE SystemVerilogTemplateLibrary.svt>

  • Any variable defined by the template file

From the SystemVerilogTemplateLibrary:

General Variables:

  • SVTLCommonHeader

  • SVTLDPIPackageDefinition

  • SVTLAllModuleScripts

  • SVTLAllUVMScripts

Variables specific to Questa® simulator:

  • SVTLQuestaDoFileStart

  • SVTLQuestaDoFileWaves

  • SVTLQuestaModuleDoFile

  • SVTLQuestaModuleToolchainDoFile

  • SVTLQuestaUVMDoFile

  • SVTLQuestaUVMToolchainDoFile

Variables specific to Xcelium™ simulator:

  • SVTLXceliumScriptFileStart

  • SVTLXceliumModuleScript

  • SVTLXceliumModuleToolchainScript

  • SVTLXceliumUVMScript

  • SVTLXceliumUVMToolchainScript

Variables specific to VCS® simulator:

  • SVTLVCSScriptFileStart

  • SVTLVCSModuleScript

  • SVTLVCSModuleToolchainScript

  • SVTLVCSUVMScript

  • SVTLVCSUVMToolchainScript

Variables specific to Vivado® simulator:

  • SVTLVivadoScriptFileStart

  • SVTLVivadoModuleScript

  • SVTLVivadoModuleToolchainScript

  • SVTLVivadoUVMScript

  • SVTLVivadoUVMToolchainScript

  • SVTLVivadoScriptFileStartWin

  • SVTLVivadoModuleScriptWin

  • SVTLVivadoModuleToolchainScriptWin

  • SVTLVivadoUVMScriptWin

  • SVTLVivadoUVMToolchainScriptWin

Built-in variables

These variables are built-in.

  • HasVarSizeInputs

  • HasVarSizeOutputs

  • TimeStamp

  • ToolVersions

  • IsUsingHDLToolchain

  • IsCrossPlatformWorkflow

  • IsQuestaSimToolchain

  • IsXceliumToolchain

  • IsVCSToolchain

  • IsVivadoToolchain

  • DPIObjectHandleDecl

  • ResetFcnCallStart

  • OutputFcnCallStart

  • CalcAndSizesFcnCallStart

  • VarSizeOutputFcnCallStart

  • TestBenchVectorGetAndCheck

See Also

|

Related Topics