Preprocessed Files Support

This application note describes how to use DVT IDE with Verilog or SystemVerilog source files which contain preprocessing code written in a different language (either general-purpose like perl, jinja2, python, ruby, php or even proprietary).

Typically, in such a flow, the source files get preprocessed and pure SystemVerilog code is generated. Subsequently, all tools in the toolchain (compiler/simulator/linter/…) actually use the generated files.

Note

For simplicity, from here on, files containing preprocessing code are referred to as (p) files while generated files are referred to as (g) files.

DVT IDE also compiles the pure SystemVerilog (g) files, however editing and navigation is done in the (p) files.

Although DVT is agnostic of the preprocessing language, you need to provide it the mapping of (p) to (g) files. The available mapping mechanisms are described in detail below.

In the pure Verilog/SystemVerilog code sections of (p) files, all of the advanced DVT navigation and editing features are available (errors reported as you type, auto-complete, quick fix proposals etc.).

The preprocessing code sections of (p) files are marked with a distinct background color. Compilation problems detected in the corresponding section of the (g) file are back-annotated.

Inside (g) files, code generated from a preprocessing code section is marked with a colored background.

To avoid manually editing (g) files by mistake, they are by default treated as read-only.

Navigation between (p) and (g) files

The code which gets generated from a particular preprocessing section is shown in the Inspect View. Similarly, you can see the preprocessed code which generates a particular code section. Click on the filename link to navigate to the associated code section.

You can also navigate from anywhere inside the (p) file to the corresponding code section of the (g) file and vice versa: Right Click in the editor -> Show -> PVerilog Preprocessed/Generated File.

Integration of the preprocessing tool

You can define a Run Configurations to invoke the preprocessing tool.

You can instruct DVT to run this configuration every time you save the preprocessing file. Use this directive in the build configuration file:

+dvt_pverilog_run_on_save+run_preprocess
+dvt_pverilog_run_on_save+"run configuration name"

Note

that you need to enclose the run configuration name in quotes if it contains whitespace characters.

The run configuration script or command can use the following environment variables:

$DVT_PVERILOG_G_FILE path to the generated (g) file $DVT_PVERILOG_P_FILE path to the preprocessing (p) file

Tip

For convenience you can also use Custom Shortcut and Button for a Run Configuration to quickly apply preprocessing.

Preferences

Go to Window > Preferences then DVT > SystemVerilog > Editor.

To configure background highlighting, adjust the PVlog Preprocessing code and PVlog Generated code preferences in the Code highlighting color group.

You can also configure the Treat PVerilog generated files as read-only preference in the Editing group.

Mapping preprocessing (p) to generated (g) files

You must specify how (p) files are mapped to (g) files using one of the following directives in the build configuration file:

• Direct mapping

  +dvt_pverilog_map+<(p) file path>=<(g) file path>

For example:

+dvt_pverilog_map+$SOURCE/file.svp=$GENERATED/file.sv

You may specify this directive multiple times for several file pairs.

• Map by extension

  +dvt_pverilog_ext_map+<(p) files extension>=<(g) files extension>

For example:

+dvt_pverilog_ext_map+.svp=.sv

A (p) file is mapped to a (g) file if they have the same basename, mapped extensions, and if the (p) file resides in any of the Scan locations for (p) files. If multiple such files exist, there is no guarantee on the chosen pair.

You may specify this directive multiple times for different extension pairs.

• Map by pattern tag

  +dvt_pverilog_pattern_tag_map+<(p) pattern1>=<(g) pattern2>

For example:

+dvt_pverilog_pattern_tag_map+<tag>.svp=<tag>_suffix.sv

A (p) file is mapped to a (g) file if their names match the specified patterns and if the (p) file resides in any of the Scan locations for (p) files. A pattern is defined by an alternation of constant fragments and tags.

You may specify this directive multiple times for different pattern pairs.

• Map by path prefix

  +dvt_pverilog_path_map+<path prefix of (p) files>=<path prefix of (g) files>

For example:

+dvt_pverilog_path_map+${PREPROCESS_SOURCE}=${PREPROCESS_TARGET}

A (p) file is mapped to a (g) file if they have the same subpath relative to the (p) path prefix respectively to the (g) path prefix.

You may specify this directive multiple times for different path prefix pairs.

• Map by comment

  +dvt_pverilog_comment_map+”<pattern>”

For example:

+dvt_pverilog_comment_map+"Source file: (?<PFILE>\S+)"

You must specify a regular expression pattern containing a named capturing group called PFILE.

The mapping is inferred from the (g) file, assuming it contains a comment pointing to the corresponding (p) source file.

Scan locations for (p) files

By default, in order to find the suitable (p) files for +dvt_pverilog_ext_map and +dvt_pverilog_pattern_tag_map, all source files located inside the project are scanned, recursively.

You can specify multiple scan locations using +dvt_pverilog_scan_location_add+<path>, for example when sources reside in multiple independent locations:

# Specify scan roots in addition to the project location
+dvt_pverilog_scan_location_add+/additional/scan/location1
+dvt_pverilog_scan_location_add+/additional/scan/location2

The project location is by default a scan location. To override this behavior, specify the +dvt_pverilog_scan_location_clear directive first:

# Don't scan the default project location, only the specified scan roots
+dvt_pverilog_scan_location_clear
+dvt_pverilog_scan_location_add+/scan/location1
+dvt_pverilog_scan_location_add+/scan/location2

Note

By default, DVT compiles the (p) files. You can use the +dvt_pverilog_mode+<mode> directive to specify which files should be compiled. For example, to compile the generated files, use +dvt_pverilog_mode+generated.

Using the PVerilog editor (Deprecated)

This functionality is deprecated. To work with preprocessed files using the PVerilog editor, add the following directive in the build configuration file:

+dvt_pverilog_compile_preproc+false

Whenever you open a (p) or (g) file (from any view, or by jumping into it with a hyperlink) it gets opened using the PVerilog editor.

It’s a multi-page editor which provides a convenient way to work with preprocessed/generated code. It has 3 tabs:

• 16. • Shows the preprocessing file with syntax highlighting.

Hyperlinks navigation options are available (Open Declaration, Show Usages, etc).

DVT detects the element under cursor by advanced analysis of the diff between the (p) and the (g) files, however in certain situations (for example in case of massive diffs) several hyperlink candidates might be available.

To see the full list, click on Show more….

From the pop-up dialog, choose the hyperlink navigation option and the element for which it should be applied.

• 7. • Shows the generated code in a regular SystemVerilog editor. All of the advanced navigation and editing features of DVT are available (hyperlinks, autocomplete, errors as you type etc). Whenever you edit this file, a visual indicator reminds you that the file is generated.

• Compare - A compare viewer of the (p) and (g) files. It is editable and allows you to move pieces of code between the two files. The (p) and (g) editors are synchronously scrolled.

A possible usage flow is to edit/debug code in the (g) tab of the PVerilog editor, and thus benefit from all the advanced DVT functionality. When done, quickly bring (p) and (g) files into sync using the compare viewer’s “Copy from …” buttons.