vvp/vvp.man

   1 .TH vvp 1 "$Date: 2005/01/29 06:28:19 $" Version "$Date: 2005/01/29 06:28:19 $"
   2 .SH NAME
   3 vvp - Icarus Verilog vvp runtime engine
   4
   5 .SH SYNOPSIS
   6 .B vvp
   7 [-sv] [-Mpath] [-mmodule] [-llogfile] inputfile [extended-args...]
   8
   9 .SH DESCRIPTION
  10 .PP
  11 \fIvvp\fP is the run time engine that executes the default compiled
  12 form generated by Icarus Verilog. The output from the \fIiverilog\fP
  13 command is not by itself executable on any platform. Instead, the
  14 \fIvvp\fP program is invoked to execute the generated output file.
  15
  16 .SH OPTIONS
  17 .l
  18 \fIvvp\fP accepts the following options:
  19 .TP 8
  20 .B -l\fIlogfile\fP
  21 This flag specifies a logfile where all MCI <stdlog> output goes.
  22 Specify logfile as '-' to send log output to <stderr>.  $display and
  23 friends send their output both to <stdout> and <stdlog>.
  24 .TP 8
  25 .B -M\fIpath\fP
  26 This flag adds a directory to the path list used to locate VPI
  27 modules. The default path includes only the install directory for the
  28 system.vpi module, but this flag can add other directories. Multiple
  29 paths are allowed, and modules will be searched in order.
  30 .TP 8
  31 .B -m\fImodule\fP
  32 Tell the vvp run time to load the named module before executing the
  33 simulation. The \fBsystem.vpi\fP module is loaded by default, but
  34 additional modules, including modules that you compiled locally, can
  35 be specified with this flag. Any number of modules can be loaded, and
  36 they will be linked in the order they are listed on the command line.
  37
  38 Normally, you only need to specify the name of the module, without any
  39 directory path or .vpi suffix and the search path is scanned to find
  40 the module. However, if the name includes at least one directory
  41 character, then the search path is not scanned and the name is assumed
  42 to be a complete file name.
  43 .TP 8
  44 .B -s
  45 Stop. This will cause the simulation to stop in the beginning, before
  46 any events are scheduled. This allows the interactive user to get
  47 hold of the simulation just before it starts.
  48 .TP 8
  49 .B -v
  50 Turn on verbose messages. This will cause information about run time
  51 progress to be printed to standard out.
  52
  53 .SH EXTENDED ARGUMENTS
  54 .PP
  55 The vvp options described above must come before the design file name.
  56 After the design file name, however, there may be any number of
  57 unspecified arguments. These arguments are not interpreted by vvp but
  58 are instead passed on to the executed design, and are available via
  59 the \fI$test$plusargs\fP and \fI$value$plusargs\fP system functions.
  60 .PP
  61 Arguments that do not start with the plus(+) character are not
  62 available to the \fI$plusargs\fP system tasks, but can still be
  63 accessed via PLI code via the \fIvpi_get_vlog_info\fP function. This
  64 means that vpi modules may use arguments that do not start with + and
  65 be assured that they do not interfere with user defined plus-args.
  66 .PP
  67 There are a few extended arguments that are interpreted by the
  68 standard system.vpi module, which implements the standard system tasks
  69 and so is always included. These arguments are described here.
  70 .TP 8
  71 .B -vcd\fR|\fP-vcd-none
  72 This extended argument sets the wave dump format to VCD. This is the
  73 default in the absence of any \fBIVERILOG_DUMPER\fP environment
  74 variable. The VCD dump files are large and ponderous, but are also
  75 maximally compatible with third party tools that read waveform dumps.
  76 .PP
  77 The \fB-vcd-none\fP variant actually suppresses all waveform
  78 output. This can make long simulations run faster.
  79
  80 .TP 8
  81 .B -lxt\fR|\fP-lxt-speed\fR|\fP-lxt-space\fR|\fP-lxt-none
  82 These extended arguments set the wave dump format to lxt, possibly with
  83 format optimizations. The \fB-lxt-space\fP flag sets the output
  84 format to lxt with full compression enabled. The resulting files are
  85 quite small. The \fB-lxt-speed\fP chooses the lxt compression mode
  86 that leads to the best execution time and the fastest read time, at
  87 the expense of some file size.
  88 .PP
  89 The \fB-lxt-none\fP variant actually suppresses all waveform
  90 output. This can make long simulations run faster.
  91
  92 .TP 8
  93 .B -lxt2\fR|\fP-lx2
  94 The LXT2 format is slower then LXT (faster then VCD) but takes less
  95 space, and is written out incrementally. Thus, you can view lxt2 files
  96 while a simulation is still running (or paused) or if your simulation
  97 crashes or is killed, you still have a useful dump.
  98
  99 .SH ENVIRONMENT
 100 .PP
 101 The vvp command also accepts some environment variables that control
 102 its behavior. These can be used to make semi-permanent changes.
 103
 104 .TP 8
 105 .B IVERILOG_DUMPER=\fIlxt|lxt2|lx2|vcd|none\fP
 106 This selects the output format for the waveform output. Normally,
 107 waveforms are dumped in vcd format, but this variable can be used to
 108 select lxt format, which is far more compact, though limited to
 109 gtkwave or compatible viewers. It can also be used to suppress VCD
 110 output, a time-saver for regression tests.
 111
 112 .SH INTERACTIVE MODE
 113 .PP
 114 The simulation engine supports an interactive mode. The user may
 115 interrupt the simulation (typically by typing Ctrl-C) to get to the
 116 interactive prompt. From that prompt, the \fIhelp\fP command prints a
 117 brief summary of the available commands.
 118 .PP
 119 The interactive mode may also be entered by a call to the \fI$stop\fP
 120 system task from within the simulation, or by a call to the
 121 \fIvpi_control\fP VPI function with the \fIvpiStop\fP control
 122 argument. These means of entering interactive mode are equivalent.
 123
 124 .SH "AUTHOR"
 125 .nf
 126 Steve Williams (steve@icarus.com)
 127
 128 .SH SEE ALSO
 129 iverilog(1),
 130 iverilog-vpi(1),
 131 .BR "<http://www.icarus.com/eda/verilog/>"
 132
 133 .SH COPYRIGHT
 134 .nf
 135 Copyright \(co  2001-2003 Stephen Williams
 136
 137 This document can be freely redistributed according to the terms of the
 138 GNU General Public License version 2.0