Verilator Control Files¶

In addition to the command line, warnings and other features for the verilator command may be controlled with Verilator Control Files, not to be confused with IEEE Configurations blocks (config…endconfig). Typically named with the .vlt extension, what makes it a Verilator Control File is the `verilator_config directive. These files, when named .vlt, are read before source code files; if this behavior is undesired, name the control file with a .v or other suffix.

An example:

`verilator_config
lint_off -rule WIDTH
lint_off -rule CASEX  -file "silly_vendor_code.v"

This disables WIDTH warnings globally, and CASEX for a specific file.

Verilator control files are fed through the normal Verilog preprocessor prior to parsing, so “`ifdef”, “`define”, and comments may be used as if the control file was standard Verilog code.

Note that file or line-specific control only applies to files read after the control file. It is therefore recommended to pass the control file to Verilator as the first file.

The grammar of control commands is as follows:

`verilator_config¶: Take the remaining text and treat it as Verilator Control File commands. See Verilator Control Files.

clock_enable -module "<modulename>" -var "<signame>"¶

Deprecated and has no effect (ignored).

In versions before 5.000:

Indicates that the signal is used to gate a clock, and the user takes responsibility for ensuring there are no races related to it.

Same as /*verilator clock_enable*/ metacomment.

clocker -module "<modulename>" [-function "<funcname>"] -var "<signame>"¶

clocker -module "<modulename>" [-task "<taskname>"] -var "<signame>"¶

no_clocker -module "<modulename>" [-function "<funcname>"] -var "<signame>"¶

no_clocker -module "<modulename>" [-task "<taskname>"] -var "<signame>"¶

Deprecated and has no effect (ignored).

In versions before 5.042:

Indicates whether the signal is used as clock or not. Verilator uses this information to mark the signal and any derived signals as clocker. See --clk.

Same as /*verilator clocker*/ metacomment.

coverage_block_off -file "<filename>" -line <lineno>¶

coverage_block_off -module "<modulename>" -block "<blockname>"¶

Specifies the entire begin/end block should be ignored for coverage analysis purposes. It can either be specified as a named block or as a filename and line number.

Same as /*verilator coverage_block_off*/ metacomment.

coverage_off [-file "<filename>" [-lines <line> [ - <line> ]]]¶

coverage_on [-file "<filename>" [-lines <line> [ - <line> ]]]¶: Enable/disable coverage for the specified filename (or wildcard with ‘*’ or ‘?’, or all files if omitted) and range of line numbers (or all lines if omitted). Often used to ignore an entire module for coverage analysis purposes.

forceable -module "<modulename>" -var "<signame>"¶

Generate public <signame>__VforceEn and <signame>__VforceVal signals that can force/release a signal from C++ code. The force control signals are created as public_flat signals.

Same as /*verilator forceable*/ metacomment.

full_case -file "<filename>" -lines <lineno>¶: Same as //synthesis full_case. When these synthesis directives are discovered, Verilator will either formally prove the directive to be true, or, failing that, will insert the appropriate code to detect failing cases at simulation runtime and print an “Assertion failed” error message.

hier_block -module "<modulename>"¶: Specifies that the module is an unit of hierarchical Verilation. Note that the setting is ignored unless the --hierarchical option is specified. See Hierarchical Verilation.

hier_params -module "<modulename>"¶: Specifies that the module contains parameters a --hierarchical block. This option is used internally to specify parameters for deparametrized hier block instances. This option should not be used directly. See Hierarchical Verilation.

hier_workers -hier-dpi "<function_name>" -workers <worker_count>¶: Specifies how many threads need to be used for scheduling hierarchical DPI tasks. This data is inserted internally during --hierarchical, based on value specified in hier_workers -module. This option should not be used directly. See Hierarchical Verilation.

hier_workers -module "<module_name>" -workers <worker_count>¶: Specifies how many threads need to be used for scheduling given module with /*verilator hier_block*/ metacomment. This number needs to be smaller than --threads to fit in a thread schedule. See Hierarchical Verilation.

inline -module "<modulename>"¶: Specifies the module may be inlined into any modules that use this module. Same as /*verilator inline_module*/ metacomment.

no_inline -module "<modulename>"¶: Specifies the module should not be inlined into any modules that use this module. Same as /*verilator no_inline_module*/ metacomment.

no_inline [-module "<modulename>"] -function "<funcname>"¶

no_inline [-module "<modulename>"] -task "<taskname>"¶

Specify the function or task should not be inlined into where it is used. This may reduce the size of the final executable when a task is used a very large number of times. For this flag to work, the task and tasks below it must be pure; they cannot reference any variables outside the task itself.

Same as /*verilator no_inline_task*/ metacomment.

isolate_assignments -module "<modulename>" -function "<fname>"¶

isolate_assignments -module "<modulename>" [-function "<funcname>"] -var "<signame>"¶

isolate_assignments -module "<modulename>" [-task "<taskname>"] -var "<signame>"¶: Used to indicate that the assignments to this signal in any blocks should be isolated into new blocks. Same as /*verilator isolate_assignments*/ metacomment.

lint_off [-rule <message>] [-file "<filename>" [-lines <line> [ - <line>]]]¶

lint_off [-rule <message>] [-file "<filename>"] [-contents "<wildcard>"] [-match "<wildcard>"]¶

lint_on [-rule <message>] [-file "<filename>" [-lines <line> [ - <line>]]]¶

Enable/disables the specified lint warning, in the specified filename (or wildcard with ‘*’ or ‘?’, or all files if omitted) and range of line numbers (or all lines if omitted).

If the -rule is omitted, all lint warnings (see list in -Wno-lint) are enabled/disabled.

If -contents is provided, the input files must contain the given wildcard (with ‘*’ or ‘?’), and are waived in case they match, provided the -rule, -file, and -contents also match. The wildcard should be designed to match a single line; it is unspecified if the wildcard is allowed to match across multiple lines. The input contents does not include --std standard files, nor control files (with verilator_config). Typical use for this is to match a version number present in the Verilog sources, so that the waiver will only apply to that version of the sources.

If -match is provided, the linter warnings are matched against the given wildcard (with ‘*’ or ‘?’), and are waived in case they match, provided the -rule, -file, and -contents also match. The wildcard is compared across the entire multi-line message; see --waiver-multiline.

When there are overlapping conflicting lint_on/lint_off directives, they are resolved in the following priority order:

All lint_on/lint_off without a -file, or with a -file "\*", are processed in order of parsing.
All lint_on/lint_off with -file "non-\*" are processed in order of parsing.
All lint_off with --match in order of parsing.

If a warning is disabled with lint_off, it will not be printed, even if the source contains a lint_on metacomment. The control file directives and metacomments are interpreted separately and do not interact. A warning is emitted only if not disabled either in a control file or via metacomments.

Before version 4.026, -rule was named -msg, and -msg remained a deprecated alias until Version 5.000.

parallel_case -file "<filename>" -lines <lineno>¶: Same as //synthesis parallel_case. When these synthesis directives are discovered, Verilator will either formally prove the directive to be true, or, failing that, will insert the appropriate code to detect failing cases at simulation runtime and print an “Assertion failed” error message.

profile_data -hier-dpi "<function_name>" -cost <cost_value>¶: Internal profiling data inserted during --hierarchical; specifies execution cost of a hierarchical DPI wrappers for modules with /*verilator hier_block*/ metacomment. See Hierarchical Verilation.

profile_data -mtask "<mtask_hash>" -cost <cost_value>¶: Feeds profile-guided optimization data into the Verilator algorithms in order to improve model runtime performance. This option is not expected to be used by users directly. See Thread Profile-Guided Optimization.

public [-module "<modulename>"] [-task/-function "<taskname>"] [-var "<signame>"]¶

public_flat [-module "<modulename>"] [-task/-function "<taskname>"] [(-param | -port | -var) "<signame>"]¶

public_flat_rd [-module "<modulename>"] [-task/-function "<taskname>"] [(-param | -port | -var) "<signame>"]¶

public_flat_rw [-module "<modulename>"] [-task/-function "<taskname>"] [(-param | -port | -var) "<signame>"] ["@(edge)"]¶

Sets the specified signal to be public. Same as /*verilator public*/ or /*verilator public_flat*/, etc., metacomments. See also VPI Example.

Using -port only selects matching ports, -param matches parameters and localparams, and -var matches any signal (including ports, parameters, and regular variables or nets). In all three, the following <signame> can contain * and ? wildcard characters that match any substring or any single character respectively.

sc_biguint -module "<modulename>" -var "<signame>"¶: Sets the input/output signal to be of sc_biguint<{width}> type. This metacomment works for signals of any width. Same as /*verilator sc_biguint*/ metacomment.

sc_bv -module "<modulename>" -var "<signame>"¶: Sets the port to be of sc_bv<{width}> type, instead of bool, uint32_t, or uint64_t. Same as /*verilator sc_bv*/ metacomment.

sformat [-module "<modulename>"] [-function "<funcname>"] -var "<signame>"¶

sformat [-module "<modulename>"] [-task "<taskname>"] -var "<signame>"¶

Must be applied to the final argument of type input string of a function or task to indicate that the function or task should pass all remaining arguments through $sformatf. This allows the creation of DPI functions with $display-like behavior. See the test_regress/t/t_dpi_display.v file for an example.

Same as /*verilator sformat*/ metacomment.

split_var [-module "<modulename>"] [-function "<funcname>"] -var "<varname>"¶

split_var [-module "<modulename>"] [-task "<taskname>"] -var "<varname>"¶

Break the variable into multiple pieces typically to resolve UNOPTFLAT performance issues. Typically the variables to attach this to are recommended by Verilator itself; see UNOPTFLAT.

Same as /*verilator split_var*/ metacomment.

timing_off [-file "<filename>" [-lines <line> [ - <line>]]]¶

timing_on [-file "<filename>" [-lines <line> [ - <line>]]]¶

Enables/disables timing constructs for the specified file and lines. When disabled, all timing control constructs in the specified source code locations are ignored the same way as with the --no-timing, and code:fork/join* blocks are converted into begin/end blocks.

Similar to /*verilator timing_on*/, /*verilator timing_off*/ meta-comments, but interpreted independently. If either a control file, or meta-comments disable timing constructs, they will be disabled.

tracing_off [-file "<filename>" [-lines <line> [ - <line> ]]]¶

tracing_on [-file "<filename>" [-lines <line> [ - <line> ]]]¶

tracing_off [-scope "<scopename>" [-levels <levels> ]]¶

tracing_on [-scope "<scopename>" [-levels <levels> ]]¶

Enable/disable waveform tracing for all future signals declared in all files.

With -file, enable/disable waveform tracing in the specified filename (or wildcard with ‘*’ or ‘?’), and -line range of line numbers (or all lines if omitted).

For tracing_off with -file, instances below any module in the files/ranges specified will also not be traced. To overcome this feature, use tracing_on on the upper module declaration and on any cells, or use the -scope flavor of the command.

With -scope enable/disable waveform tracing for the specified scope (or wildcard with ‘*’ or ‘?’), and optional --levels number of levels below. These controls only operate after other file/line/module-based controls have indicated the signal should be traced. Matching is performed on the shortest prefix first, such that tracing_on -scope "a.b" tracing_off -scope "a" will turn it on for “a.b” and off for everything else “a.*”.

With -levels (used with -scope), the number of levels below that scope which the rule is to match, where 0 means all levels below, 1 the exact level as the provided scope, and 2 means an additional level of children below the provided scope, etc.

verilator_lib -module "<modulename>"¶: Internal use only. Marks the specified module as being a stub for a library created by --lib-create (including when created with --hierarchical). Required for special internal processing.