NAME

       vvp - Icarus Verilog vvp runtime engine

SYNOPSIS

       vvp [-inNsvV] [-Mpath] [-mmodule] [-llogfile] inputfile [extended-args...]

DESCRIPTION

       vvp  is  the  run  time  engine  that executes the default compiled form generated by Icarus Verilog. The
       output from the iverilog command is not by itself executable on any platform. Instead, the vvp program is
       invoked to execute the generated output file.

OPTIONS

       vvp accepts the following options:

       -i      This flag causes all output to <stdout> to be unbuffered.

       -llogfile
               This flag specifies a logfile where all MCI <stdlog> output goes.  Specify logfile as '-' to send
               log output to <stderr>.  $display and friends send their output both to <stdout> and <stdlog>.

       -Mpath  This flag adds a directory to the path list used to locate VPI modules. The default path includes
               only the install directory for the system.vpi module, but this flag can  add  other  directories.
               Multiple paths are allowed, and modules will be searched in order.

       -mmodule
               Tell  the  vvp  run time to load the named module before executing the simulation. The system.vpi
               module is loaded by default, but additional modules, including modules that you compiled locally,
               can be specified with this flag. Any number of modules can be loaded, and they will be linked  in
               the order they are listed on the command line.

               Normally,  you  only  need  to specify the name of the module, without any directory path or .vpi
               suffix and the search path is scanned to find the module. However, if the name includes at  least
               one  directory  character,  then  the  search path is not scanned and the name is assumed to be a
               complete file name.

       -n      This flag makes $stop or a <Control-C> a synonym for $finish.  It can be used to give the program
               a more meaningful interface when running in a non-interactive environment.

       -N      This flag does the same thing as -n, but results in an exit code of 1 if  the  stimulation  calls
               $stop.  It can be used to indicate a simulation failure when running a testbench.

       -s      Stop.  This  will cause the simulation to stop in the beginning, before any events are scheduled.
               This allows the interactive user to get hold of the simulation just before it starts.

       -v      Turn on verbose messages. This will cause information about run time progress to  be  printed  to
               standard out.

       -V      Print the version of the runtime, and exit.

EXTENDED ARGUMENTS

       The  vvp  options  described  above  must  come before the design file name.  After the design file name,
       however, there may be any number of unspecified arguments. These arguments are not interpreted by vvp but
       are  instead  passed  on  to  the  executed  design,  and  are  available  via  the  $test$plusargs   and
       $value$plusargs system functions.

       Arguments  that  do not start with the plus(+) character are not available to the $plusargs system tasks,
       but can still be accessed via PLI code via the vpi_get_vlog_info function. This means  that  vpi  modules
       may  use  arguments  that do not start with + and be assured that they do not interfere with user defined
       plus-args.

       There are a few extended arguments  that  are  interpreted  by  the  standard  system.vpi  module,  which
       implements the standard system tasks and are always included. These arguments are described here.

       -vcd    This  extended  argument  sets the wave dump format to VCD. This is the default in the absence of
               any IVERILOG_DUMPER environment variable. The VCD dump files are large  and  ponderous,  but  are
               also maximally compatible with third party tools that read waveform dumps.

       -lxt|-lxt-speed|-lxt-space
               These extended arguments set the wave dump format to lxt, possibly with format optimizations. The
               -lxt-space  flag sets the output format to lxt with full compression enabled. The resulting files
               are quite small. The -lxt-speed chooses the lxt compression mode that leads to the best execution
               time and the fastest read time, at the expense of some file size.

       -lxt2|-lxt2-speed|-lxt2-space
       -lx2|-lx2-speed|-lx2-space
               The LXT2  format  is  slower  than  LXT  but  usually  takes  less  space,  and  is  written  out
               incrementally.  Thus,  you can view lxt2 files while a simulation is still running (or paused) or
               if your simulation crashes or is killed, you  still  have  a  useful  dump.  The  -lxt2-speed  or
               -lx2-speed  arguments  are  the  same  as  -lxt2 or -lx2. The -lxt2-space or -lx2-space arguments
               enable better compression and turn off incremental writing.

       -fst|-fst-speed|-fst-space
       -fst-space-speed|-fst-speed-space
               This is a modern dumping format that is both faster and  more  compact  than  the  other  dumping
               formats.  It  supports incremental dumping just like -lxt2. The -fst-speed argument uses a faster
               compression methods that creates a  noticeably  larger  output  file.   The  -fst-space  argument
               performs  a  repack  of  the  file  on  close  to  produce  the  smallest possible dump file. The
               -fst-space-speed or -fst-speed-space arguments use the faster compression method and  repack  the
               file on close.

       -none   This   flag   can   be   used   by   itself   or  appended  to  the  end  of  the  above  dumpers
               (vcd/lxt/lxt2/lx2/fst) to suppress all waveform  output.  This  can  make  long  simulations  run
               faster.

       -sdf-warn
               When  loading  an  SDF  annotation  file,  this option causes the annotator to print warnings for
               questionable but non-fatal issues.

       -sdf-info
               When loading an SDF annotation file, this option causes the annotator to print information  about
               the annotation.

       -sdf-verbose
               This is shorthand for -sdf-info -sdf-warn.

       -compatible
               This extended argument enables improved compatibility with other simulators. At present this only
               affects the display format for real numbers when no format string is supplied.

ENVIRONMENT

       The  vvp  command also accepts some environment variables that control its behavior. These can be used to
       make semi-permanent changes.

       IVERILOG_DUMPER=fst|lxt|lxt2|lx2|vcd|none
               This selects the output format for the waveform output. Normally, waveforms  are  dumped  in  vcd
               format,  but  this  variable  can be used to select lxt format, which is far more compact, though
               limited to GTKWave or compatible viewers. It can also be used to suppress  VCD  output,  a  time-
               saver for regression tests.

       IVERILOG_VPI_MODULE_PATH=/some/path:/some/other/path
               This  adds  additional  components to the VPI module search path. Paths specified in this way are
               searched after paths specified with -M, but before the default search path. Multiple paths can be
               separated with colons (semicolons if using Windows).

INTERACTIVE MODE

       The simulation engine supports an interactive mode. The user may interrupt the simulation  (typically  by
       typing  <Control-C>)  to get to the interactive prompt. From that prompt, the help command prints a brief
       summary of the available commands.

       The interactive mode may also be entered by a call to the $stop system task from within  the  simulation,
       or  by  a call to the vpi_control VPI function with the vpiStop control argument. These means of entering
       interactive mode are equivalent.

AUTHOR

       Steve Williams (steve@icarus.com)

SEE ALSO

       iverilog(1), iverilog-vpi(1), <http://iverilog.icarus.com/>

COPYRIGHT

       Copyright ©  2001-2022 Stephen Williams

       This document can be freely redistributed according to the terms of the
       GNU General Public License version 2.0

                                                March 25th, 2022                                          vvp(1)