nvc.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "NVC" "1" "July 2017" "" "NVC Manual"
.
.SH "NAME"
\fBnvc\fR \- VHDL Compiler and Simulator
.
.SH "SYNOPSIS"
\fBnvc\fR \-a [\fIoptions\fR] \fIfiles\fR\.\.\.
.
.br
\fBnvc\fR \-e [\fIoptions\fR] \fIunit\fR
.
.br
\fBnvc\fR \-r [\fIoptions\fR] \fIunit\fR
.
.br
.
.SH "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 more more source files into the work library; elaborating a top\-level design unit; and running the elaborated design\.
.
.SH "OPTIONS"
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\.
.
.P
Commands can be chained together\. For example to analyse a file \fBfoo\.vhd\fR and then elaborate and run a top\-level entity \fBbar\fR:
.
.IP "" 4
.
.nf

nvc \-a foo\.vhd \-e bar \-r
.
.fi
.
.IP "" 0
.
.P
Note that the \fIunit\fR argument for the \fB\-r\fR run command is taken from the earlier \fB\-e\fR elaborate command\.
.
.SS "Commands"
.
.TP
\fB\-a\fR \fIfiles\fR
Analyse \fIfiles\fR into the work library\.
.
.TP
\fB\-e\fR \fIunit\fR
Elaborate a previously analysed top level design unit\.
.
.TP
\fB\-r\fR \fIunit\fR
Execute a previously elaborated top level design unit\.
.
.TP
\fB\-\-codegen\fR \fIunit\fR
Generate a native shared library for a previously analysed package\. This can improve runtime performance if the package contains a large number of frequently used subprograms\.
.
.TP
\fB\-\-dump\fR \fIunit\fR
Print out a pseudo\-VHDL representation of an analysed unit\. This is usually only useful for debugging the compiler\.
.
.TP
\fB\-\-list\fR
Print all analysed and elaborated units in the library\.
.
.TP
\fB\-\-make\fR \fIunits\fR
Generate a makefile for already analysed units\.
.
.TP
\fB\-\-syntax\fR \fIfiles\fR
Check input files for syntax errors only\.
.
.SS "Global options"
.
.TP
\fB\-\-force\-init\fR
Initialise a library work directory even if it already exists and is non\-empty\.
.
.TP
\fB\-h\fR, \fB\-\-help\fR
Display usage summary\.
.
.TP
\fB\-\-ignore\-time\fR
Do not check the timestamps of source files when the corresponding design unit is loaded from a library\.
.
.TP
\fB\-L\fR \fIpath\fR
Add \fIpath\fR to the list of directories to search for libraries\. See the \fILIBRARIES\fR section below for details\.
.
.TP
\fB\-\-map=\fR\fIname\fR\fB:\fR\fIpath\fR
Specify exactly the location of logical library \fIname\fR\. Libraries mapped in this way will not used the normal search path\.
.
.TP
\fB\-\-messages=\fR\fIstyle\fR
Select either the \fIfull\fR or \fIcompact\fR message format\. The default full message format is designed for readability whereas the compact messages can be easily parsed by tools\.
.
.TP
\fB\-\-std=\fR\fIrev\fR
Select the VHDL standard revision to use\. Specify either the full year such as \fI1993\fR or the decade such as \fI93\fR\. The allowed revisions are 1993, 2000, 2002, and 2008\. Note there is very limited supported for any features beyond those in VHDL\-93\. VHDL\-87 is not supported\.
.
.TP
\fB\-v\fR, \fB\-\-version\fR
Display version and copyright information\.
.
.TP
\fB\-\-work=\fR\fIname\fR, \fB\-\-work=\fR\fIname\fR\fB:\fR\fIpath\fR
Use \fIname\fR as the work library\. The second variant explicitly specifies the location of the library\. See the \fILIBRARIES\fR section below for details\.
.
.SS "Analysis options"
.
.TP
\fB\-\-bootstrap\fR
Allow compilation of the STANDARD package\. Not intended for end users\.
.
.TP
\fB\-\-relax=\fR\fIrules\fR
Disable certain pedantic rule checks specified in the comma\-separate list \fIrules\fR\. See \fIRELAXING RULES\fR section below for full list\.
.
.SS "Elaboration options"
.
.TP
\fB\-\-cover\fR
Enable code coverage reporting (see the \fICODE COVERAGE\fR section below)\.
.
.TP
\fB\-\-dump\-llvm\fR
Print generated LLVM IR prior to optimisation\.
.
.TP
\fB\-\-dump\-vcode\fR
Print generated intermediate code\.
.
.TP
\fB\-g\fR \fIname\fR\fB=\fR\fIvalue\fR
Override top\-level generic \fIname\fR name with \fIvalue\fR\. Integers, enumeration literals, and string literals are supported\. For example \fB\-gI=5\fR, \fB\-gINIT=\'1\'\fR, and \fB\-gSTR=hello\fR\.
.
.TP
\fB\-\-native\fR
Generate native code shared library\. By default NVC will use LLVM JIT compilation to generate machine code at runtime\. For large designs compiling to native code at elaboration time may improve performance\.
.
.TP
\fB\-O0\fR, \fB\-01\fR, \fB\-02\fR, \fB\-03\fR
Set LLVM optimisation level\. Default is \fB\-O2\fR\.
.
.TP
\fB\-V\fR, \fB\-\-verbose\fR
Prints resource usage information after each elaboration step\.
.
.SS "Runtime options"
.
.TP
\fB\-\-exit\-severity=\fR\fIlevel\fR
Terminate the simulation after an assertion failures of severity greater than or equal to \fIlevel\fR\. Valid levels are \fBnote\fR, \fBwarning\fR, \fBerror\fR, and \fBfailure\fR\. The default is \fBerror\fR\.
.
.TP
\fB\-\-format=\fR\fIfmt\fR
Generate waveform data in format \fIfmt\fR\. Currently supported formats are: \fBfst\fR, \fBlxt\fR, and \fBvcd\fR\. The FST and LXT formats are native to GtkWave\. The FST format is preferred over LXT due its smaller size and better performance; however VHDL support in FST requires a recent version of GtkWave so LXT is provided for compatibility\. 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 or LXT\. The default format is FST if this option is not provided\. Note that GtkWave 3\.3\.53 or later is required to view the FST output\.
.
.TP
\fB\-\-include=\fR\fIglob\fR, \fB\-\-exclude=\fR\fIglob\fR
Signals that match \fIglob\fR are included in or excluded from the waveform dump\. See section \fISELECTING SIGNALS\fR for details on how to select particular signals\. These options can be given multiple times\.
.
.TP
\fB\-\-load=\fR\fIplugin\fR
Loads a VHPI plugin from the shared library \fIplugin\fR\. See section \fIVHPI\fR for details on the VHPI implementation\.
.
.TP
\fB\-\-stats\fR
Print time and memory statistics at the end of the run\.
.
.TP
\fB\-\-stop\-delta=\fR\fIN\fR
Stop after \fIN\fR 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\.
.
.TP
\fB\-\-stop\-time=\fR\fIT\fR
Stop the simulation after the given time has elapsed\. Format of \fIT\fR is an integer followed by a time unit in lower case\. For example \fB5ns\fR or \fB20ms\fR\.
.
.TP
\fB\-\-trace\fR
Trace simulation events\. This is usually only useful for debugging the simulator\.
.
.TP
\fB\-\-vhpi\-trace\fR
Trace VHPI calls and events\. This can be useful for debugging VHPI plugins\.
.
.TP
\fB\-w, \-\-wave=\fR\fIfile\fR
Write waveform data to \fIfile\fR\. 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 \fB\-\-format\fR option\. By default all signals in the design will be dumped: see the \fISELECTING SIGNALS\fR section below for how to control this\.
.
.SS "Make options"
.
.TP
\fB\-\-deps\-only\fR
Generate rules that only contain dependencies without actions\. These can be useful for inclusion in a hand written makefile\.
.
.TP
\fB\-\-native\fR
Output actions to generate native code\.
.
.TP
\fB\-\-posix\fR
The generated makefile will work with any POSIX compliant make\. Otherwise the output may use extensions specific to GNU make\.
.
.SH "RELAXING RULES"
The following can be specified as a comma\-separated list to the \fB\-\-relax\fR option to disable certain semantic rule checks\.
.
.TP
\fBprefer\-explict\fR
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 Synopsys \fBstd_logic_arith\fR package\.
.
.TP
\fBlocally\-static\fR
References to generics and array slices are allowed in locally static expressions using the VHDL\-2008 rules\.
.
.TP
\fBuniversal\-bound\fR
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 \fB\-1 to 1\fR in VHDL\-1993 which otherwise must be written \fBinteger\'(\-1) to 1\fR\.
.
.TP
\fBpure\-files\fR
Pure functions are allowed to declare file objects\.
.
.SH "SELECTING SIGNALS"
Every signal object in the design has a unique hierarchical path name\. This is identical to the value of the \fBPATH_NAME\fR attribute\.
.
.P
A signal can be referred to using its full path name, for example \fB:top:sub:x\fR, and \fB:top:other:x\fR are two different signals\. The character \fB:\fR is a hierarchy separator\. A \fIglob\fR may be used refer to a group of signals\. For example \fB:top:*:x\fR, \fB*:x\fR, and \fB:top:sub:*\fR, all select both of the previous signals\. The special character \fB*\fR is a wildcard that matches zero or more characters\.
.
.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 \fB\-\-include\fR and \fB\-\-exclude\fR arguments\. For example \fB\-\-exclude=":top:sub:*"\fR will exclude all matching signals from the waveform dump\. Multiple inclusion and exclusion patterns can be provided\.
.
.P
When the number of patterns becomes large, specifying them on the command line is cumbersome\. Instead a text file can be used to provide inclusion and exclusion patterns\. If the top\-level unit name is \fBtop\fR then inclusion patterns should be placed in a file called \fBtop\.include\fR and exclusion patterns in a file called \fBtop\.exclude\fR\. These files should be in the working directory where the \fBnvc \-r\fR command is executed\. The format is one glob per line, with comments preceded by a \fB#\fR character\.
.
.P
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\.
.
.SH "VHPI"
NVC supports a subset of VHPI allowing access to signal values and events at runtime\. The standard VHPI header file \fBvhpi_user\.h\fR will be placed in the system include directory as part of the installation process\. VHPI plugins should be compiled as shared libraries; for example:
.
.IP "" 4
.
.nf

$ cc \-shared \-fPIC my_plugin\.c \-o my_plugin\.so
$ nvc \-r \-\-load my_plugin\.so my_tb
.
.fi
.
.IP "" 0
.
.P
The plugin should define a global \fBvhpi_startup_routines\fR which is a NULL\-terminated list of functions to call when the plugin is loaded:
.
.IP "" 4
.
.nf

void (*vhpi_startup_routines[])() = {
   startup_1,
   startup_2,
   NULL
};
.
.fi
.
.IP "" 0
.
.P
TODO: describe VHPI functions implemented
.
.SH "LIBRARIES"
Description of library search path, contents, etc\.
.
.SH "CODE COVERAGE"
Description of coverage generation
.
.SH "AUTHOR"
Written by Nick Gasson
.
.SH "REPORTING BUGS"
Report bugs using the GitHub issue tracker at
.
.br
\fIhttps://github\.com/nickg/nvc/issues\fR