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)