FreeBSD Manual Pages

home | help

NVC(1) General Commands Manual NVC(1)

NAME
nvc -- VHDL Compiler and Simulator

SYNOPSIS
nvc -a file ...
nvc -e unit
nvc -r unit

DESCRIPTION
nvc is an implementation of the VHDL language as defined by IEEE standard
1076-1993 and later revisions.

Simulating a design typically involves three steps: analysing one or more
source files into the work library; elaborating a top-level design unit;
and finally running the elaborated design.

nvc accepts three kinds of options: global options; commands; and options
specific to the command. Global options must be placed before the command
and specific options must be placed after the command.

Commands
-a file ...
Analyse one or more files into the work library. Reads from stan-
dard input if file is `-'.

-e unit
Elaborate a previously analysed top level design unit.

-r [unit]
Execute a previously elaborated top level design unit.

-i [unit]
Start an interactive TCL shell, optionally with unit loaded.

--cover-export file ...
Export collected coverage information from the internal database
format to an external format such as Cobertura XML.

--cover-merge file ...
Merge multiple coverage databases into a single database.

--cover-report file ...
Generate an HTML report from a coverage database.

--do [unit] script
Evaluate a batch TCL script, optionally with unit loaded.

--init Initialise the working library directory. This is not normally
necessary as the library will be automatically created when using
other commands such as -a.

--install package
Execute scripts to compile common verification frameworks and FPGA
vendor libraries.

--list Print all analysed and elaborated units in the work library.

--print-deps unit ...
Print dependencies of unit in Makefile format.

Commands can be chained together arbitrarily and the top-level unit name
need only be specified once. For example to analyse a file `source.vhd'
and then elaborate and run a top-level entity `tb':

$ nvc -a source.vhd -e tb -r

Note how the unit argument for the -r command is taken from the earlier -e
command.

Global options
-h, --help
Display usage summary.

-H size
Set the maximum size in bytes of the simulation heap. This area of
memory is used for temporary allocations during process execution
and dynamic allocations by the VHDL `new' operator. The size para-
meter takes an optional k, m, or g suffix to indicate kilobytes,
megabytes, and gigabytes respectively. The default size is 16
megabytes.

--ieee-warnings=[on|off|off-at-0]
Enable or disable warning messages from the standard IEEE packages.
The off-at-0 option disables warnings in the first time step only.
The default is warnings enabled.

--ignore-time
Do not check the timestamps of source files when the corresponding
design unit is loaded from a library.

--load=plugin
Loads a VHPI plugin from the shared library plugin. See section
"VHPI" for details on the VHPI implementation. If plugin is not a
valid path the directories listed in NVC_PLUGIN_PATH will be
searched for a shared library with plugin as the basename.

-L path
Add path to the list of directories to search for libraries. See
the "LIBRARIES" section below for details.

-M size
Set the maximum amount of memory in bytes used for the internal
representations of design units. The default is 16 megabytes but
this may be insufficient when elaborating a large design. The size
parameter takes an optional k, m, or g suffix to indicate kilo-
bytes, megabytes, and gigabytes respectively. For example -M 64m
for 64 megabytes.

--map=name:path
Specify exactly the location of the logical library name. Li-
braries mapped in this way will not use the normal search path.

--messages=[full|compact]
Select the format used for printing error and informational mes-
sages. The default full message format is designed for readability
whereas the compact messages can be easily parsed by tools.

--seed=N
Seed for random number generation. Affects the `get_random' func-
tion in the `nvc.random' package, the --shuffle option, and PSL
union expressions.

--std=rev
Select the VHDL standard revision to use. VHDL standard revisions
are commonly referred to by the year they were published. For ex-
ample IEEE 1076-1993 is known as VHDL-93. Specify either the full
year such as 1993 or just the last two digits such as 93. The ac-
cepted revisions are 1993, 2000, 2002, 2008, and 2019. The default
standard revision is VHDL-2008. VHDL-1987 is not supported.

--stderr=level
Print error messages with the given severity or higher to `stderr'
instead of `stdout'. The default is to print all messages to
`stderr'. Valid levels are note, warning, error, failure, and
none.

-v, --version
Display version and copyright information.

--vhpi-debug
Report any VHPI errors as diagnostic messages on the console. Nor-
mally these are only returned through the vhpi_check_error() func-
tion.

--vhpi-trace
Trace VHPI calls and events. This can be useful for debugging VHPI
plugins.

--work=name, --work=name:path
Use name as the work library. The second variant explicitly speci-
fies the location of the library. See the "LIBRARIES" section be-
low for details.

Analysis options
--check-synthesis
Issue warnings for common coding mistakes that may cause problems
during synthesis such as missing signals from process sensitivity
lists.

-D name[=value], --define=name[=value]
Define a conditional analysis identifier (VHDL-2019) or preproces-
sor macro (Verilog). This option can be used multiple times to de-
fine multiple identifiers or macros. When value is ommited, the
macro value is the empty string ("").

--error-limit=num
Stop after reporting num errors. The default is 20. Zero allows
unlimited errors.

-f list, --files=list
Read the list of source files to analyse from list which is a text
file containing one file name per line. If list is `-' then reads
from the standard input instead. Comments starting with `#' are
ignored. References to environment variables such as `$FOO' are
automatically expanded. This argument may also be passed as @list
for compatibility with other tools.

-I dir Add dir to the list of directories searched when processing the
Verilog ``include' directive.

--keywords=version
Use the set of keywords from the given Verilog or System Verilog
standard version. The set of allowed versions is the same as those
accepted by the ``begin_keywords' directive. For example
`1364-2001' or `1800-2017'. In the absence of this option or a
``begin_keywords' directive, the default is `1364-2001' for files
with a `.v' extension, and `1800-2023' for files with a `.sv' ex-
tension.

--no-save
Do not save analysed design units to the working library. This can
be used to quickly check for syntax and type errors.

--preserve-case
Retain the original spelling of VHDL identifiers instead of con-
verting to a canonical upper-case form. This is an experimental
option and may lead to incorrect behaviour.

--psl Enable parsing of PSL directives in comments.

--relative=dir
By default nvc saves the literal file path given to the -a command
in the binary representation of the design unit in the working li-
brary. This can be undesirable when distributing libraries in bi-
nary form since the same file analysed from two different paths
will produce different outputs. The --relative flag forces all
paths to be stored relative to dir. For example the following
stores `foo/bar.vhd' instead of `../prefix/foo/bar.vhd' in the bi-
nary representation:

nvc -a --relative=../prefix ../prefix/foo/bar.vhd

--relaxed
Disable certain pedantic LRM conformance checks or rules that were
relaxed by later standards. See the "RELAXED RULES" section below
for details.

--single-unit
Treat all Verilog source files given on the command line as a sin-
gle compilation unit. This means macros declared in one file are
visible in all subsequent files.

-Werror
Treat all analysis warnings as errors.

Elaboration options
--cover
Enable code coverage reporting (see the "CODE COVERAGE" section be-
low).

--cover-file=file
Specify the file name of the output coverage database. Defaults to
the name of the top-level unit with a `.ncdb' extension.

--cover-spec=sfile
Specify design part where code coverage is collected by sfile cov-
erage specification file (see the "CODE COVERAGE" section below).

-g name=value
Override generic name with value. Integers, enumeration literals,
and string literals are supported. Generics in internal instances
can be overridden by giving the full dotted path to the generic.
For example -g I=5, -g INIT='1', and -g UUT.STR="hello".

--no-collapse
Do not collapse ports into a single signal. Normally if a signal
at one level in the hierarchy is directly connected to another sig-
nal in a lower level via a port map, the signals are "collapsed"
and only the signal in the upper level is preserved. The
--no-collapse option disables this optimisation and preserves both
signals. This improves debuggability at the cost of some perfor-
mance.

--no-save
Do not save the elaborated design and other generated files to the
working library. This is only really useful in combination with
the -r option. For example:

$ nvc -e --no-save tb -r

-O0, -01, -02, -O3
Set LLVM optimisation level. Default is -O2.

-V, --verbose
Prints resource usage information after each elaboration step.

Runtime options
--dump-arrays[=N]
Include memories and nested arrays in the waveform data. This is
disabled by default as it can have significant performance, memory,
and disk space overhead. With optional argument N only arrays with
up to this many elements will be dumped.

--exit-severity=level
Terminate the simulation after an assertion failures of severity
greater than or equal to level. Valid levels are note, warning,
error, and failure. The default is failure.

This option also overrides the minimum severity level which causes
the program to return a non-zero status code. The default is error
which allows assertion violations to be detected easily.

--format=fmt
Generate waveform data in format fmt. Currently supported formats
are: fst and vcd. The FST format is native to gtkwave(1). FST is
preferred over VCD due its smaller size and better performance.
VCD is a very widely used format but has limited ability to repre-
sent VHDL types and the performance is poor: select this only if
you must use the output with a tool that does not support FST. The
default format is FST if this option is not provided. Note that
GtkWave 3.3.79 or later is required to view the FST output.

-g, --gtkw[=file]
Write a gtkwave(1) save file containing every signal in the design
hierarchy in declaration order with separators for each scope.
This only makes sense in combination with the --wave option.

--include=glob, --exclude=glob
Signals that match glob are included in or excluded from the wave-
form dump. See section "SELECTING SIGNALS" for details on how to
select particular signals. These options can be given multiple
times.

--shuffle
Run processes in random order. The VHDL standard does not specify
the execution order of processes and different simulators may ex-
hibit subtly different orderings. The --shuffle option can help to
find and debug code that inadvertently depends on a particular
process execution order. This option should only be used during
debug as it incurs a significant performance overhead as well as
introducing potentially non-deterministic behaviour.

--stats
Print a summary of the time taken and memory used at the end of the
run.

--stop-delta=N
Stop after N delta cycles. This can be used to detect zero-time
loops in your model. The default is 10000 if not specified. Set-
ting this to zero disables the delta cycle limit.

--stop-time=T
Stop the simulation after the given time has elapsed. Format of T
is an integer followed by a time unit in lower case. For example
5ns or 20ms.

--trace
Trace simulation events. This is usually only useful for debugging
the simulator.

-w, --wave[=file]
Write waveform data to file. The file name is optional and if not
specified will default to the name of the top-level unit with the
appropriate extension for the waveform format. The waveform format
can be specified with the --format option. By default all signals
in the design will be dumped: see the "SELECTING SIGNALS" section
below for how to control this.

Coverage export options
--format=format
Selects one of the following output file formats:

cobertura Cobertura XML format widely supported by CI systems.

xml Simple XML dump of the coverage database contents. The
schema is liable to change between releases.

-o, --output=file
Write output to file. If this option is not specified the standard
output stream is used.

--relative[=path]
Report file names relative to path or the current working direc-
tory.

Coverage merge options
-o, --output=file
File name of output coverage database.

-m, --merge-mode=mode
Where mode can be one of: union, intersect

Coverage report options
-o, --output=dir
Name of output directory where HTML files will be generated.

--exclude-file=efile
Apply commands in efile exclude file when generating code coverage
report.

--dont-print=options
When set, NVC does not include code coverage details specified by
options in the code coverage report. options is comma separated
list of the following values:

covered Does not include covered items.

uncovered Does not include uncovered items.

excluded Does not include excluded items.

--item-limit=limit
NVC displays maximum limit items of single type (covered, uncov-
ered, excluded) in a single hierarchy in the code coverage report.
Each Bin is counted as one item. The default value of limit is
5000.

--per-file
Create source file code coverage report instead of hierarchy cover-
age report.

Install options
--dest=dir
Compile libraries into directory dir instead of the default
$HOME/.nvc/lib.

LIBRARIES
A library is a directory containing analysed design units and other files
generated by nvc. The default library is called "work" and is placed in a
directory also called work. Note that VHDL also has a concept of the "work
library" where the current library can be referred to by the alias work.
This confusing behaviour is an unfortunate hangover from the proprietary
tools the author used prior to writing nvc.

The name and physical location of the work library is controlled by the
--work global option. In the simple case of --work=name the library name
is `name' and the physical location is a directory name relative to the
current working directory. The physical location can be specified explic-
itly using --work=name:path where path is the directory name. On Windows
the ; character can be used instead of : as a separator.

The following examples should make this behaviour clear:

$ nvc --work=mylib ...

The work library is named `mylib' and is mapped to a directory with the
same name in the current working directory.

$ nvc --work=mylib:somedir ...

The work library is named `mylib' and is mapped to a directory somedir in
the current working directory.

$ nvc --work=mylib:/foo/bar ...

The work library is named `mylib' and is mapped to the absolute path
/foo/bar.

Concurrent access to a single library by multiple processes is completely
safe and protected by a lock in the filesystem using flock(2) that allows
multiple concurrent readers but only a single writer.

TCL SCRIPTING
nvc supports both interactive and batch scripting using TCL. This must be
enabled at compile time using `--enable-tcl'. The TCL environment supports
standard TCL commands, the `tcllib' extension library, and a number of NVC-
specific commands. Use the help command in the interactive environment
(-i) to list these.

CODE COVERAGE
nvc can collect code coverage data while the simulation is executing. NVC
counts coverage in so called coverage bins. Each coverage bin counts from
0, and increments each time coverage kind specific criteria are met. Cover-
age bins saturate at 2147483647. The following coverage kinds are sup-
ported:

* statement - For each statement, NVC creates coverage bin. When a state-
ment
is executed, coverage bin is incremented.

* branch - For each point where code diverges (if/else, case, when/else,
with/select statements), NVC creates coverage bin. If branch can be
evaluated to both true and false, NVC creates two coverage bins for
such branch (one for each of true/false). When a branch is evaluated,
its coverage bin is incremented.

* toggle - Each signal of type derived from `std_logic' (including nested
arrays) creates two coverage bins (to track 0 -> 1 and 1 -> 0 transi-
tions). When a signal toggles, coverage bin is incremented.

* expression - NVC creates multiple coverage bins for combinations of in-
put operands of the following logical operators: `and', `nand', `or',
`nor', `xor', `xnor', such that propagation of operand values causes
the expression result to change its value. Further, NVC creates two
coverage bins for evaluating expression result to `True' and `False'
for the following operators: `=', `/=', `>', `<', `<=', `>=', `not'.
NVC collects expression coverage also on overloaded logic operators
from `ieee.std_logic_1164' library. It tracks combinations of input
values to logic operators for `std_logic' operand type. NVC does not
collect expression coverage for VHDL 2008 overloaded operands for
`std_logic_vector' type. When expression evaluates, coverage bin corre-
sponding to combination of expression operands, or expression result is
incremented.

* fsm-state - NVC tracks if states of Finite State Machines (FSMs) are
visited. NVC creates a coverage bin for each state of an FSM. NVC con-
siders internal signals of all user-defined enum types as FSMs. NVC
does not consider port signals or variables as an FSM. When a signal
recognized as FSM changes its value, coverage bin for new state value
is incremented.

* functional - NVC creates a coverage bin for each:

* PSL `cover' directive. When a PSL sequence in the cover directive
completes, coverage bin is incremented.

* Functional coverage bin from third party libraries (e.g. OSVVM)

Collection of each coverage kind can be enabled separately at elaboration
time:

$ nvc -e --cover=statement,branch,toggle,expression <top>

If no coverage type is specified as an argument of --cover, all coverage
types are collected. After the simulation has finished the coverage data
is written to a coverage database file. By default this is the name of the
top-level unit with an `.ncdb' extension in the current working directory,
but can be changed with the --cover-file elaboration option.

Code coverage merging
To merge code coverage data from multiple simulations run:

$ nvc --cover-merge -o merged.ncdb first.ncdb second.ncdb third.ncdb ...

During code coverage merging, NVC sums together coverage bins with equal
hierarchical paths in the elaborated design.

NVC supports different modes of merging. The merge mode controls what NVC
does if a coverage database that is being merged (new) contains a coverage
item that is not present in the coverage database being merged into (old).
The merge mode can be selected by a --merge-mode=mode option where mode can
be one of:

* union - The item is added to the merged (old) database. This is the de-
fault mode.

* intersect - The item is dropped from the merged (old) database.

Generating code coverage report
To generate code coverage report in HTML format, run:

$ nvc --cover-report -o report_dir merged.ncdb

The command above will generate a code coverage report in the report_dir
directory. Code coverage report shows whether a coverage bin is covered or
uncovered. A bin is covered when its counter is equal to, or higher than
threshold given by --threshold-<value> option of --cover elabortion switch.
NVC supports two kinds of code coverage reports:

* hierarchy report - Code coverage report contains code coverage summary
for each design hierarchy in simulated design. Code coverage data of a
nested hierarchy are added to data of hierarchy that instantiate the
nested hierarchy.

* source file report - Code coverage report contains code coverage sum-
mary for each source file used in simulated design. If a single entity
or module was instantiated multiple times, code coverage data from all
such instantiations are merged and reported under one source file. If a
source file was compiled, but none of its entities, modules or packages
were used in the simulated design, such file is not shown in code cov-
erage report.

By default NVC generates hierarchy code coverage report. To generate
source file code coverage report, add --per-file switch to --cover-report
command.

Code coverage merging and generating code coverage report can also be done
in a single command:

$ nvc --cover-report -o html first.ncdb second.ncdb third.ncdb ...

Additional code coverage options
NVC supports the following additional options to control coverage collec-
tion:

* count-from-undefined - When set, NVC also counts toggles from U / X to
1 as 0 to 1 and toggles from U / X to 0 as 1 / 0 during toggle coverage
collection.

* count-from-to-z - When set, NVC also counts toggles from/to Z to either
of 0/1 as valid 0 -> 1 or 1 -> 0 transitions.

* include-mems - When set, NVC collects toggle coverage on multidimen-
sional arrays or nested arrays (array of array), disabled by default.

* ignore-arrays-from-<size> - When set, NVC does not collect toggle cov-
erage on arrays whose size is equal to or larger than <size>

* exclude-unreachable - When set, NVC detects unreachable coverage bins
and automatically excludes them during code coverage report generation.
NVC detects following unreachable coverage items:

* Toggle coverage on instance ports driven by constant value.

* Expression coverage bins where right side of the expression is not
evaluated due to left side value being sufficient to determine ex-
pression result. This applies to following cases:

* `or' expression bin with LHS=True, RHS=False

* `and' expression bin with LHS=False, RHS=True.

* fsm-no-default-enums - When set, NVC by default does not consider sig-
nals of usr-define enum types as FSMs. With this option, NVC can be
forced to recognize FSMs only via `fsm-type' directive in coverage
specification file.

* threshold-<value> - A minimal value of coverage bin counter for cover-
age bin to be reported as
covered. Default is 1.

All additional coverage options are passed comma separated to --cover elab-
oration option, e.g.:

$ nvc -e --cover=all,include-mems,count-from-undefined <top>

Coverage collection on parts of the code can be ignored via a comment
pragma, for example:

case (sel) is
when "00" => ...
when "01" => ...
when "10" => ...
when "11" => ...
-- coverage off
when others => report "ERROR" severity failure;
-- coverage on
end case;

In the example above, statement coverage for the `report' statement and
branch coverage for `others' choice will not be collected.

Toggle coverage collection on specific signals can be also disabled:

-- coverage off
signal cnt : std_logic_vector(3 downto 0);
-- coverage on

Coverage specification file
NVC can collect code coverage only on part of the simulated design. When
coverage specification file is passed during elaboration time, NVC collects
code coverage only as specified in this file. If the file is ommited, NVC
collects code coverage on whole design. The format of commands in the cov-
erage specification file is as follows:

(+|-)block <ENTITY_NAME>
(+|-)hierarchy <HIERARCHY>
(+|-)fsm-type <TYPE>

An example of coverage specification file is following:

# Placing '#' is treated as comment till end of line

# Example how to enable collecting code coverage on a hierarchy:
+hierarchy WORK.TOP.DUT_INST*

# Example how to disable collecting code coverage on a hierarchy:
-hierarchy WORK.TOP.DUT_INST.THIRD_PARTY_SUB_BLOCK_INST*

# Example how to enable collecting code coverage on entity or block:
+block async_fifo

# Example how to disable collecting code coverage on entity or block:
-block clock_gate_model

# Example how to force all signals of enum types named 'T_FSM_STATE'
# to be recognized as FSM
+fsm_type T_FSM_STATE

# Example how to force all signals of enum types with name matching
# 'T_*_FSM' pattern to be recognized as FSM
+fsm_type T_*_FSM

# Example how to force all signals of enum type named 'T_TRANSFER_TYPE'
# not to be recognized as an FSM
-fsm-type T_TRANSFER_TYPE

In coverage specification file `block' has priority over `hierarchy', dis-
abled hierarchy / block ( `-' ) has priority over enabled hierarchy / block
( `+' ).

Exclude file
NVC can exclude any coverage bins when generating code coverage report.
When a coverage bin is excluded, it is counted as "Covered" in the coverage
summary and displayed in a dedicated group in the code coverage report.
Format of commands in exclude file is following:

exclude <HIERARCHY(.BIN)>

Where `<HIERARCHY>' is hierarchical path of the coverage bin in the elabo-
rated design, and `BIN' is one of following bins:

* BIN_TRUE - Excludes "Evaluated to: True" bin. Applicable to if/else
branch, when/else branch or expression.

* BIN_FALSE - Excludes "Evaluated to: False" bin. Applicable to if/else
branch, when/else branch or expression.

* BIN_CHOICE - Excludes "Choice of:" bin. Applicable to case/with branch
choices.

* BIN_X_Y - Excludes bins for combination of input operands (LHS, RHS) of
an expression. Applicable to an expression for which combinations of
input operand values is tracked. `X', `Y' shall be 0 or 1. Excludes
bin where LHS = `X' and RHS = `Y', see an example exclude file below.

* BIN_0_TO_1 - Excludes "Toggle from 0 to 1" bin. Applicable to signal /
port toggle coverage.

* BIN_1_TO_0 - Excludes "Toggle from 1 to 0" bin. Applicable to signal /
port toggle coverage.

* BIN_STATE.<ENUM_VALUE> - Excludes `ENUM_VALUE' FSM state.

An example of exclude file:

# Placing '#' is treated as comment till end of line

# Example how to exclude statement
# For statements BIN shall be ommited
exclude WORK.TOP._P1._S0._S3

# Example how to exclude all coverage items which match wildcard:
exclude WORK.TOP.SUB_BLOCK_INST.*

# Example how to exclude 4 coverage bins for combinations of input
# operands value (LHS, RHS) of an expression:
exclude WORK.TOP.XOR_GATE._S0._E0.BIN_0_0
exclude WORK.TOP.XOR_GATE._S0._E0.BIN_0_1
exclude WORK.TOP.XOR_GATE._S0._E0.BIN_1_0
exclude WORK.TOP.XOR_GATE._S0._E0.BIN_1_1

# Example which excludes the same items as previous example,
# but excludes all bins by a single command:
exclude WORK.TOP.XOR_GATE._S0._E0.*

# Example how to exclude branch 'Evaluated to: False' bin:
exclude WORK.TOP._P0._S0._B0.BIN_FALSE

# Example how to exclude toggle bin 'Toggle from 0 to 1' on
# a signal, and all toggle bins on a port of sub-instance:
exclude WORK.TOP.SIGNAL_NAME.BIN_0_TO_1
exclude WORK.TOP.SUB_BLOCK_INST.PORT_NAME.*

# Example how to exclude FSM state "ST_ERROR" where "ST_ERROR"
# is one of the enum values used to code the FSM.
exclude WORK.TOP.CONTROLLER.CURR_STATE.BIN_STATE.ST_ERROR

Coverage folding
NVC supports merging code coverage of single entity / module instantiated
on multiple places in hierarchy. Such type of coverage merging is called
coverage folding. Coverage folding is useful when simulating a complex DUT.
If a sub-block of a DUT has a logic that is hard to cover in DUT top level
test-bench, then creating a unit test for such sub-block is easy way to
achieve full sub-block coverage. The sub-block has different hierarchy when
simulated in DUT top level test-bench and in the unit test. In DUT top
level test-bench, the sub-block is instantiated under the DUT. In the unit-
test, sub-block is instantiated directly. To merge coverage data from two
such instantiations, you can utilize coverage folding.

Coverage folding is specified by `fold' command placed in Exclude file. The
syntax of `fold' command is following:

fold <DESTINATION_INSTANCE_HIERARCHY> <SOURCE_INSTANCE_HIERARCHY>
where `<DESTINATION_INSTANCE_HIERARCHY>' is the destination hierarchy where
the coverage data will be merged and `<SOURCE_INSTANCE_HIERARCHY>' is the
source hierarchy from which the coverage data will be merged.

When folding coverage, NVC merges coverage items similarly as during regu-
lar merging (based on hierarchical path). However, in case of folding, NVC
strips `<DESTINATION_INSTANCE_HIERARCHY>' from the path of the destination
coverage item, and strips `<SOURCE_INSTANCE_HIERARCHY>' from the source
item. Thus NVC folds coverage items based on matching suffix of their hier-
archical path.

An example of how folding can be specified is following. Assume there is
an entity `INSTR_CACHE' instantiated as:

* `I_INSTR_CACHE' instance in a testbench `TB_TOP'

* `DUT' instance in a unit test `CACHE_UNIT_TEST'

`TB_TOP' testbench is compiled into `TB_TOP_LIB' library. Unit test is com-
piled into `UNIT_TEST_LIB' library. The following command folds coverage
items of `INSTR_CACHE' from `CACHE_UNIT_TEST' to `TB_TOP' :

fold TB_TOP_LIB.TB_TOP.DUT.I_CPU_DATAPATH.I_INSTR_CACHE UNIT_TEST_LIB.CACHE_UNIT_TEST.DUT

Code coverage limitations
When part of the design hierarchy is formed by an if-generate-else or case-
generate statement, the hierarchical path of implicit block statements for
each of the if-else branches or case choices is identical unless the user
provides an alternative label for each branch or choice. For example:

my_gen : case (op_kind) generate
when op_add => x <= a + b;
when op_sub => x <= a - b;
end generate my_gen;

Both assignment statements have a hierarchical path that ends with
`.MY_GEN._P0._SO' and will not be considered distinct when merging. To
avoid this give each case branch a unique label:

my_gen : case (op_kind) generate
when branch1: op_add => x <= a + b;
when branch2: op_sub => x <= a - b;
end generate my_gen;

Additional Information
In coverage specification file and Exclude file `<ENTITY_NAME>'
`<HIERARCHY>' and `<TYPE>' are case-insensitive. You can get examples of
exclude commands from generated Code coverage report by clicking on a "Get
Exclude Command" button.

RELAXED RULES
The --relaxed analysis flag enables "relaxed rules" mode which downgrades
the following errors to warnings:

* Impure function called from pure function.

* File object declared in pure function.

* Default expression in object interface declaration is not globally sta-
tic.

* Shared variable is not of protected type in VHDL-2000 or later.

Additionally the following languages features from VHDL-2008 and later are
enabled in earlier standards:

* Any visible explicitly declared operator always hides an implicit oper-
ator regardless of the region in which it is declared. This is re-
quired to analyse code that uses the non-standard Synopsys
std_logic_arith package.

* References to generics and array slices are allowed in locally static
expressions using the VHDL-2008 rules.

* Range bounds with `universal_integer' type are not required to be nu-
meric literals or attributes. This option allows ranges such as `-1 to
1' in VHDL-1993 which otherwise must be written `integer'(-1) to 1'.

SELECTING SIGNALS
Every signal object in an elaborated design has a unique hierarchical path
name. In VHDL this can be accessed using the `PATH_NAME' attribute.

A signal can be referred to using its full path name, for example
`:top:sub:x', and `:top:other:x' are two different signals named `x' in the
design. The character `:' is a hierarchy separator. The special character
`*' is a wildcard that matches zero or more characters and may be used re-
fer to a group of signals. For example `:top:*:x', `*:x', and
`:top:sub:*', all select both of the previous signals.

Restricting waveform dumps
Path names and globs can be used to exclude or explicitly include signals
in a waveform dump. For simple cases this can be done using the --include
and --exclude arguments. For example --exclude=":top:sub:*" will exclude
all matching signals from the waveform dump. Multiple inclusion and exclu-
sion patterns can be provided.

Specifying large numbers of patterns on the command line quickly becomes
cumbersome. Instead inclusion and exclusion patterns can be read from a
text file. If the top-level unit name is `top' then inclusion patterns
should be placed in a file called top.include and exclusion patterns in a
file called top.exclude. These files should be in the working directory
where the `nvc -r' command is executed. The format is one glob per line,
with comments preceded by a `#' character.

When both inclusion and exclusion patterns are present, exclusions have
precedence over inclusions. If no inclusion patterns are present then all
signals are implicitly included.

VHPI
nvc supports a subset of VHPI allowing access to signal values and events
at runtime. The standard VHPI header file <vhpi_user.h> will be placed in
the system include directory as part of the installation process. VHPI
plugins should be compiled as shared libraries; for example:

$ cc -shared -fPIC my_plugin.c -o my_plugin.so
$ nvc -r --load my_plugin.so my_tb

The plugin should define a global vhpi_startup_routines which is a NULL-
terminated list of functions to call when the plugin is loaded:

void (*vhpi_startup_routines[])() = {
startup_1,
startup_2,
NULL
};

Functions defined in VHPI plugin libraries may be called from VHDL using
either the standard VHPI protocol or a simplified protocol similar to
ghdl(1)

To use the standard VHPI protocol the VHDL function should be declared with
the `FOREIGN' attribute giving the "object library name" and "model name"
of the foreign function. For example:

function my_func (x : integer;
y : bit_vector;
z : std_logic) return integer is
begin
report "should not reach here" severity failure;
end function;

attribute foreign of my_func : function is "VHPI my_lib my_func";

The VHPI plugin should then call vhpi_register_foreignf() to register the
foreign subprogram.

static void my_func_cb(const vhpiCbDataT *cb_data_p) { ... }

vhpiForeignDataT my_func_data = {
.kind = vhpiFuncF,
.libraryName = "my_lib",
.modelName = "my_func",
.execf = my_func_cb,
};
vhpi_register_foreignf(&my_func_data);

To use the simplified protocol the VHDL the `FOREIGN' attribute should be
specified with the keyword `VHPIDIRECT' and name of the function symbol ex-
ported from the plugin. For example:

attribute foreign of my_func : function is "VHPIDIRECT my_func";

Where `my_func' is a global function defined in the plugin library as fol-
lows.

int32_t my_func(int32_t x, const uint8_t *y, int64_t y_len, uint8_t z);

Foreign procedures may be defined similarly:

function my_proc (x : out integer; y : out bit_vector; z : std_logic);
attribute foreign of my_proc : function is "VHPIDIRECT my_proc";

void my_proc(int32_t *x, uint8_t *y, int64_t y_len, uint8_t z);

Note that scalar `out' parameters are passed by pointer.

There is a simple mapping between VHDL and C types.

Integers The smallest C integer type that holds the full range
of the VHDL type.

Reals C double regardless of the range of the VHDL type.

Enumerated types The smallest unsigned integer type that holds the
full range of the VHDL type.

Constrained arrays Pointer to the element type.

Unconstrained arrays Pointer to the element type followed by one int64_t
length argument for each dimension. Note that the
bounds and direction are not available and must be
passed explicitly as separate arguments if required.

Records Not yet supported.

Here are several examples for common types:

VHDL type C type
INTEGER int32_t
INTEGER range 1 to 5 int8_t
REAL double
BOOLEAN uint8_t
BIT_VECTOR(1 to 3) uint8_t *
STD_LOGIC uint8_t
STD_LOGIC_VECTOR uint8_t *, int64_t

Foreign functions must not modify arrays passed as `in' arguments. Addi-
tionally foreign subprograms must not retain any pointers passed as argu-
ments after the subprogram returns. Violating these rules will result in
unpredictable and hard to debug behaviour.

ENVIRONMENT
NVC_CONCURRENT_JOBS Provides a hint for the number of concurrently execut-
ing simulations. This allows nvc to scale its worker
thread count to avoid overloading the system. This is
set automatically by frameworks such as VUnit. See
NVC_MAX_THREADS.

NVC_COLORS Controls whether nvc uses ANSI colour escape sequences
to print diagnostic messages. The possible values are
never, always, and auto which enables colour if stdout
is connected to a terminal. The default is auto.

NVC_MAX_THREADS Limit the number of worker threads nvc can create.
The default is either eight or the number of available
CPUs, whichever is smaller.

NVC_PLUGIN_PATH List of directories to search for PLI plugins. Sepa-
rated by `'; on Windows and `': on all other plat-
forms. This list is only searched when the argument
to --load is not a valid path and does not contain a
directory separator.

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages