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 standard input
if file is
‘
-
’. -e
unit- Elaborate a previously analysed top level design unit.
-r
unit- Execute a previously elaborated top level design unit.
--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.
--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.
--make
unit ...- Generate a makefile for already analysed units.
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 parameter takes an optional k, m, or g suffix to indicate kilobytes, megabytes, and gigabytes respectively. The default size is 16 megabytes. --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.
-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 kilobytes, megabytes, and gigabytes respectively. For example
-M64m
for 64 megabytes. --map
=name:path- Specify exactly the location of the logical library name. Libraries mapped in this way will not use the normal search path.
--messages
=[full
|compact
]- Select the format used for printing error and informational messages. The default full message format is designed for readability whereas the compact messages can be easily parsed by tools.
--std
=rev- Select the VHDL standard revision to use. VHDL standard revisions are commonly referred to by the year they were published. For example 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 accepted revisions are 1993, 2000, 2002, 2008, 2019. Note there is very limited supported VHDL-2019 at present and VHDL-87 is not supported. The default standard revision is VHDL-2008.
--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 arenote
,warning
,error
, andfailure
. -v
,--version
- Display version and copyright information.
--vhpi-debug
- Report any VHPI errors as diagnostic messages on the console. Normally
these are only returned through the
vhpi_check_error
() function. --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 specifies the location of the library. See the LIBRARIES section below 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 preprocessor macro (Verilog). This option can be used multiple times to define 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. Alternatively this argument may be passed as @list for compatibility with other tools. --no-save
- Do not save analysed design units to the working library. This can be used to quickly check for syntax and type errors.
--psl
- Enable parsing of PSL directives in comments.
--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 single compilation unit. This means macros declared in one file are visible in all subsequent files.
Elaboration options
--cover
- Enable code coverage reporting (see the CODE COVERAGE section below).
--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 coverage 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"
. -j
,--jit
- Normally
nvc
compiles all code ahead-of-time during elaboration. The--jit
option defers native code generation until run-time where each function will be compiled separately on a background thread once it has been has been executed often enough in the interpreter to be deemed worthwhile. This dramatically reduces elaboration time at the cost of increased memory and CPU usage while the simulation is executing. This option is beneficial for short-running simulations where the performance gain from ahead-of-time compilation is not so significant. --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 signal 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 performance. --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
, andfailure
. The default isfailure
.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
andvcd
. 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 represent 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. --ieee-warnings=
[on
|off
]- Enable or disable warning messages from the standard IEEE packages. The default is warnings enabled.
--include=
glob,--exclude=
glob- Signals that match glob are included in or excluded from the waveform 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 exhibit 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. Setting 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
or20ms
. --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:
-o
,--output=
file- Write output to file. If this option is not specified the standard output stream is used.
--relative
[=path]- Strip path or the current working directory from the front of any absolute path names in the output.
Coverage merge options
-o
,--output=
file- File name of output coverage database.
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:
--item-limit=
limit- NVC displays maximum limit items of single type (covered, uncovered, 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 coverage report.
Make options
--deps-only
- Generate rules that only contain dependencies without actions. These can be useful for inclusion in a hand written makefile.
--posix
- The generated makefile will work with any POSIX compliant make. Otherwise the output may use extensions specific to GNU make.
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 explicitly 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.
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. Coverage bins saturate at 2147483647. The
following coverage kinds are supported:
statement
- For each statement, NVC creates coverage bin. When a statement
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 transitions). When a signal toggles, coverage bin is incremented.expression
- NVC creates multiple coverage bins for combinations of input 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 corresponding 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 considers 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)
- PSL ‘
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 creates union of all coverage bins from all input coverage databases in the merged code coverage database. This allows merging code coverage from different designs (e.g. where part of the hierarchy is formed by "if-generate" statement).
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 summary 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 coverage 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 collection:
count-from-undefined
- When set, NVC also counts toggles fromU
/X
to1
as0
to1
and toggles fromU
/X
to0
as1
/0
during toggle coverage collection.count-from-to-z
- When set, NVC also counts toggles from/toZ
to either of0/1
as valid0
->1
or1
->0
transitions.include-mems
- When set, NVC collects toggle coverage on multidimensional arrays or nested arrays (array of array), disabled by default.ignore-arrays-from-<size>
- When set, NVC does not collect toggle coverage 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
expression 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 signals 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 coverage bin to be reported as
covered. Default is 1.
All additional coverage options are passed comma separated to
--cover
elaboration 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 coverage 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
’, disabled 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 elaborated 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>
<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 regular 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 hierarchical 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 compiled 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
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 static.
- 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 operator regardless of the region in which it is declared. This is required 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 numeric 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 refer 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 exclusion 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 exported 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 follows.
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. Additionally foreign
subprograms must not retain any pointers passed as arguments 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 executing simulations. This
allows
nvc
to scale its worker thread count to avoid overloading the system. This is set automatically by frameworks such as VUnit. SeeNVC_MAX_THREADS
. NVC_COLORS
- Controls whether
nvc
uses ANSI colour escape sequences to print diagnostic messages. The possible values arenever
,always
, andauto
which enables colour if stdout is connected to a terminal. The default isauto
. 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.
SEE ALSO
AUTHORS
Written by Nick Gasson ⟨nick@nickg.me.uk⟩
BUGS
Report bugs to nick@nickg.me.uk or using the GitHub issue tracker at https://github.com/nickg/nvc/issues. Please include enough information to reproduce the problem, ideally with a small VHDL test case.
February 9, 2025 | Debian |