From b544d8c335f2932b34f9e9206bb627650b76b208 Mon Sep 17 00:00:00 2001 From: Nick Gasson Date: Sat, 2 Nov 2013 20:05:12 +0000 Subject: [PATCH] Start adding a man page --- Makefile.am | 4 +- nvc.1 | 173 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 nvc.1 diff --git a/Makefile.am b/Makefile.am index ef1df60fa..08e41dc95 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,11 +1,13 @@ SUBDIRS = lxt fst src lib test -EXTRA_DIST = autogen.sh +EXTRA_DIST = autogen.sh data/coverage.css nvc.1 ACLOCAL_AMFLAGS = -I m4 pkgdata_DATA = data/coverage.css +man_MANS = nvc.1 + bootstrap: all @cd lib && $(MAKE) $(AM_MAKEFLAGS) clean bootstrap diff --git a/nvc.1 b/nvc.1 new file mode 100644 index 000000000..452a303b2 --- /dev/null +++ b/nvc.1 @@ -0,0 +1,173 @@ +.\" -*- mode: nroff -*- +.TH "nvc" 1 "November 2013" +.\" -------------------------------------------------------------------------------- +.SH NAME +nvc \- VHDL Compiler and Simulator +.\" -------------------------------------------------------------------------------- +.SH SYNOPSIS +.B nvc -a +.RI [ options] +.I files +... +.br +.B nvc -e +.RI [ options ] +.I unit +.br +.B nvc -r +.RI [ options ] +.I unit +.\" -------------------------------------------------------------------------------- +.SH DESCRIPTION +NVC is an implementation of the VHDL language as defined by IEEE +standard 1076-1993 and later revisions. Simulating a design typically involes +three steps: +.I analysing +one more more source files into the work library; +.I elaborating +a top-level design unit; and +.I running +the elaborated design. +.\" -------------------------------------------------------------------------------- +.SH OPTIONS +NVC accepts three kinds of options: global options; a single command +option; 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 +.TP +.BI "-a " files +Analyse +.I files +into the work library. +.TP +.BI "-e " unit +Elaborate a previously analysed top level design unit. +.TP +.BI "-r " unit +Execute a previously elaborated top level design unit. +.TP +.BI "--codegen " unit +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 +.BI "--dump " unit +Print out a pseudo-VHDL representation of an analysed unit. This is +usually only useful for debugging the compiler. + +.SS Global options +.TP +.B "-h, --help" +Display usage summary. +.TP +.BI "-L " path +Add +.I path +to the list of directories to search for libraries (see +.B LIBRARIES +section below). +.TP +.B "-v, --version" +Display version and copyright information. +.TP +.BI "--work=" name +Use +.I name +as the work library (see +.B LIBRARIES +section below). +.SS Analysis options +.TP +.BI "--bootstrap" +Allow compilation of the STANDARD package. Not intended for end users. +.SS Elaboration options +.TP +.B "--cover" +Enable code coverage reporting (see +.B COVERAGE +section below). +.TP +.B "--disable-opt" +Disable LLVM optimisations. Not generally useful unless debugging the +generated LLVM IR. +.TP +.B "--dump-llvm" +Print generated LLVM IR prior to optimisation. +.TP +.B "--native" +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. +.SS Runtime options +.TP +.B "-b, --batch" +Run in batch mode. This is the default. +.TP +.B "-c, --command" +Run in interactive TCL command line mode. See +.B TCL SHELL +section below. +.TP +.BI "--format=" fmt +Generate waveform data in format +.IR fmt . +Currently supported formats are: +.BR fst ", " lxt ", and " vcd . +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. +.TP +.BI "--stats" +Print time and memory statistics at the end of the run. +.TP +.BI "--stop-delta=" N +Stop after +.I 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. +.TP +.BI "--stop-time=" T +Stop the simulation after the given time has elapsed. Format of +.I T +is an integer followed by a time unit in lower case. For example +.B 5ns +or +.BR 20ms . +.TP +.BI "--trace" +Trace simulation events. This is usually only useful for debugging the +simulator. +.TP +.BI "-w, --wave=" FILE +Write waveform data to +.IR 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 +.B --format +option. + +.\" -------------------------------------------------------------------------------- +.SH LIBRARIES +Description of library search path, contents, etc. +.\" -------------------------------------------------------------------------------- +.SH CODE COVERAGE +Description of coverage generation +.\" -------------------------------------------------------------------------------- +.SH TCL SHELL +Describe interactive TCL shell +.\" -------------------------------------------------------------------------------- +.SH AUTHOR +Written by Nick Gasson +.\" -------------------------------------------------------------------------------- +.SH "REPORTING BUGS" +Report bugs using the GitHub issue tracker at +.br +