nvc.1

.Dd $Mdocdate$
.Dt NVC 1
.Os
.Sh NAME
.Nm nvc
.Nd VHDL Compiler and Simulator
.\" ------------------------------------------------------------
.\" Synopsis
.\" ------------------------------------------------------------
.Sh SYNOPSIS
.Nm
.Fl a Ar
.Nm
.Fl e
.Fa unit
.Nm
.Fl r
.Fa unit
.\" ------------------------------------------------------------
.\" Description
.\" ------------------------------------------------------------
.Sh DESCRIPTION
.Nm
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 more more source files into the work library;
elaborating a top-level design unit; and running the elaborated design.
.Pp
.Nm
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.
.\"
.Ss Commands
.Bl -tag -width Ds
.\"
.It Fl a Ar
Analyse one or more files into the work library.
.\"
.It Fl e Ar unit
Elaborate a previously analysed top level design unit.
.\"
.It Fl r Ar unit
Execute a previously elaborated top level design unit.
.\"
.It Fl -dump Ar unit
Print out a pseudo-VHDL representation of an analysed unit.  This is
usually only useful for debugging the compiler.
.\"
.It Fl -list
Print all analysed and elaborated units in the work library.
.\"
.It Fl -make Ar unit ...
Generate a makefile for already analysed units.
.\"
.It Fl -syntax Ar
Check input files for syntax errors only.
.El
.\"
.Pp
Commands can be chained together.  For example to analyse a file
.Ar foo.vhd
and then elaborate and run a top-level entity
.Ar bar :
.Pp
.Dl $ nvc -a foo.vhd -e bar -r
.Pp
Note that the
.Ar unit
argument for the
.Fl r
run command is taken from the earlier
.Fl e
elaborate command.
.\" ------------------------------------------------------------
.\" Global options
.\" ------------------------------------------------------------
.Ss Global options
.Bl -tag -width Ds
.It Fl -force-init
Initialise a library work directory even if it already exists and is
non-empty.
.\"
.It Fl h , -help
Display usage summary.
.\"
.It Fl -ignore-time
Do not check the timestamps of source files when the corresponding
design unit is loaded from a library.
.\"
.It Fl L Ar path
Add
.Ar path
to the list of directories to search for libraries.  See the
.Xs LIBRARIES
section below for details.
.\"
.It Fl -map Ns = Ns Ar name Ns : Ns Ar path
Specify exactly the location of the logical library
.Ar name .
Libraries mapped in this way will not use the normal search path.
.\"
.It Fl -messages Ns = Ns Ar style
Select either the
.Ar full
or
.Ar compact
message format.  The default full message format is designed for
readability whereas the compact messages can be easily parsed by tools.
.\"
.It Fl -std Ns = Ns Ar 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, and 2008.  Note there is very limited supported for
any features beyond those in VHDL-2002.  VHDL-87 is not supported.
.\"
.It Fl v , -version
Display version and copyright information.
.\"
.It Fl -work Ns = Ns Ar name , Fl -work Ns = Ns Ar name Ns : Ns Ar path
Use
.Ar name
as the work library.  The second variant explicitly specifies the
location of the library.  See the
.\"
.Sx LIBRARIES
section below for details.
.El
.\" ------------------------------------------------------------
.\" Analysis options
.\" ------------------------------------------------------------
.Ss Analysis options
.Bl -tag -width Ds
.It Fl -bootstrap
Allow compilation of the
.Ql STANDARD
package.  Not useful in any other circumstances.
.\"
.It Fl -error-limit Ns = Ns Ar num
Stop after reporting
.Ar num
errors.  The default is 20.  Zero allows unlimited errors.
.\"
.It Fl -relax Ns = Ns Ar rules
Disable certain pedantic rule checks specified in the comma-separated
list
.Ar rules .
See the
.Sx RELAXING RULES
section below for the full list.
.El
.\" ------------------------------------------------------------
.\" Elaboration options
.\" ------------------------------------------------------------
.Ss Elaboration options
.Bl -tag -width Ds
.It Fl -cover
Enable code coverage reporting (see the
.Sx CODE COVERAGE
section below).
.\"
.It Fl -dump-llvm
Print generated LLVM IR prior to optimisation.
.\"
.It Fl -dump-vcode
Print generated intermediate code.  This is only useful for debugging
the compiler.
.\"
.It Fl g Ar name Ns = Ns Ar value
Override top-level generic
.Ar name
with
.Ar value .
Integers, enumeration literals, and string literals are supported.  For
example
.Fl gI=5 ,
.Fl gINIT='1' ,
and
.Fl gSTR="hello" .
.\"
.It Fl O0 , Fl 01 , Fl 02 , Fl O3
Set LLVM optimisation level.  Default is
.Fl O2 .
.\"
.It Fl V , Fl -verbose
Prints resource usage information after each elaboration step.
.El
.\" ------------------------------------------------------------
.\" Runtime options
.\" ------------------------------------------------------------
.Ss Runtime options
.Bl -tag -width Ds
.It Fl -exit-severity Ns = Ns Ar level
Terminate the simulation after an assertion failures of severity greater
than or equal to
.Ar level .
Valid levels are
.Cm note ,
.Cm warning ,
.Cm error ,
and
.Cm failure .
The default is
.Cm error .
.\"
.It Fl -format= Ns Ar fmt
Generate waveform data in format
.Ar fmt .
Currently supported formats are:
.Cm fst
and
.Cm vcd .
The FST format is native to
.Xr 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.
.\"
.It Fl -include= Ns Ar glob , Fl -exclude= Ns Ar glob
Signals that match
.Ar glob
are included in or excluded from the waveform dump.  See section
.Sx SELECTING SIGNALS
for details on how to select particular signals.  These options can be
given multiple times.
.\"
.It Fl -load= Ns Ar plugin
Loads a VHPI plugin from the shared library
.Ar plugin .
See section
.Sx VHPI
for details on the VHPI implementation.
.\"
.It Fl -profile
Collect profiling data and print this at the end of the run.  Note this
will slow down the simulation slightly.
.\"
.It Fl -stats
Print time and memory statistics at the end of the run.
.\"
.It Fl -stop-delta Ns = Ns Ar N
Stop after
.Ar N
delta cycles.  This can be used to detect zero-time loops in your model.
The default is 1000 if not specified.  Setting this to zero disables the
delta cycle limit.
.\"
.It Fl -stop-time Ns = Ns Ar T
Stop the simulation after the given time has elapsed.  Format of
.Ar T
is an integer followed by a time unit in lower case.  For example
.Cm 5ns
or
.Cm 20ms .
.\"
.It Fl -trace
Trace simulation events.  This is usually only useful for debugging the
simulator.
.\"
.It Fl -vhpi-trace
Trace VHPI calls and events.  This can be useful for debugging VHPI
plugins.
.\"
.It Fl w , Fl -wave Ns = Ns Ar file
Write waveform data to
.Ar 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
.Fl -format
option.  By default all signals in the design will be dumped: see the
.Sx SELECTING SIGNALS
section below for how to control this.
.El
.\" ------------------------------------------------------------
.\" Make options
.\" ------------------------------------------------------------
.Ss Make options
.Bl -tag -width Ds
.It Fl -deps-only
Generate rules that only contain dependencies without actions.  These
can be useful for inclusion in a hand written makefile.
.\"
.It Fl -posix
The generated makefile will work with any POSIX compliant make.
Otherwise the output may use extensions specific to GNU make.
.El
.\" ------------------------------------------------------------
.\" Relaxing rules
.\" ------------------------------------------------------------
.Sh RELAXING RULES
The following can be specified as a comma-separated list to the
.Fl -relax
option to disable certain semantic rule checks.
.Bl -tag -width "universal bound"
.\"
.It Cm prefer-explict
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
.Sy std_logic_arith
package.
.\"
.It Cm locally-static
References to generics and array slices are allowed in locally static
expressions using the VHDL-2008 rules.
.\"
.It Cm universal-bound
Prior to VHDL-2000 when range bounds have universal integer type the
expressions must be either numeric literals or attributes.  This option
allows ranges such as
.Ql -1 to 1
in VHDL-1993 which otherwise must be written
.Ql integer'(-1) to 1 .
.\"
.It Cm pure-files
Pure functions are allowed to declare file objects.
.\"
.It Cm impure
Pure functions may call impure functions.
.El
.\" ------------------------------------------------------------
.\" Selecting signals
.\" ------------------------------------------------------------
.Sh SELECTING SIGNALS
Every signal object in an elaborated design has a unique hierarchical
path name.  In VHDL this can be accessed using the
.Ql PATH_NAME
attribute.
.Pp
A signal can be referred to using its full path name, for example
.Ql :top:sub:x ,
and
.Ql :top:other:x
are two different signals named
.Ql x
in the design.  The character
.Ql \&:
is a hierarchy separator.  The special character
.Ql *
is a wildcard that matches zero or more characters and may be used refer
to a group of signals.  For example
.Ql :top:*:x ,
.Ql *:x ,
and
.Ql :top:sub:* ,
all select both of the previous signals.
.\"
.Ss 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
.Fl -include
and
.Fl -exclude
arguments.  For example
.Fl -exclude= Ns Qq Ar :top:sub:*
will exclude all matching signals from the waveform dump.  Multiple
inclusion and exclusion patterns can be provided.
.Pp
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
.Ql top
then inclusion patterns should be placed in a file called
.Pa top.include
and exclusion patterns in a file called
.Pa top.exclude .
These files should be in the working directory where the
.Ql nvc -r
command is executed.  The format is one glob per line, with comments
preceded by a
.Ql #
character.
.Pp
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
.\" ------------------------------------------------------------
.Sh VHPI
.Nm
supports a subset of VHPI allowing access to signal values and
events at runtime.  The standard VHPI header file
.In 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:
.Bd -literal -offset indent
$ cc -shared -fPIC my_plugin.c -o my_plugin.so
$ nvc -r --load my_plugin.so my_tb
.Ed
.Pp
The plugin should define a global
.Va vhpi_startup_routines
which is a NULL-terminated list of functions to call when the plugin is
loaded:
.Bd -literal -offset indent
void (*vhpi_startup_routines[])() = {
   startup_1,
   startup_2,
   NULL
};
.Ed
.Sh ENVIRONMENT
.Bl -tag -width "NVC_COLORS"
.It Ev NVC_COLORS
Controls whether
.Nm
uses ANSI colour escape sequences to print diagnostic messages.  The
possible values are
.Cm never ,
.Cm always ,
and
.Cm auto
which enables colour if stdout is connected to a terminal.
The default is
.Cm auto .
.El
.\" .Sh FILES
.\" .Sh EXIT STATUS
.\" For sections 1, 6, and 8 only.
.\" .Sh EXAMPLES
.Sh SEE ALSO
.Xr gtkwave 1 ,
.Xr ghdl 1
.\" .Sh STANDARDS
.\" .Sh HISTORY
.Sh AUTHORS
Written by
.An Nick Gasson Aq nick@nickg.me.uk
.\" .Sh CAVEATS
.Sh BUGS
Report bugs to
.Mt nick@nickg.me.uk
or using the GitHub issue tracker at
.Lk https://github.com/nickg/nvc/issues .
Please include enough information to reproduce the problem, ideally with
a small VHDL test case.