iverilog/Documentation/usage/command_line_flags.rst

iverilog Command Line Flags
===========================

The iverilog command is the compiler/driver that takes the Verilog input and
generates the output format, whether the simulation file or synthesis
results. This information is at least summarized in the iverilog man page
distributed in typical installations, but here we try to include more detail.

General
-------

These flags affect the general behavior of the compiler.

* -c <cmdfile>
  
  This flag selects the command file to use. The command file is an
  alternative to writing a long command line with a lot of file names and
  compiler flags. See the Command File Format page for more information.

* -d <flag>
  
  Enable compiler debug output. These are aids for debugging Icarus Verilog,
  and this flag is not commonly used.
  The flag is one of these debug classes:
  
  * scope
  * eval_tree
  * elaborate
  * synth2

* -g <generation flag>
  the generation is the compiler language, and specifies the language and
  extensions to use during the compile. The language level can be selected
  by a major level selector, and by controlling various features. Various
  "-g" flags can be compined. For example, to get Verilog 2001 without
  specify supoprt, use "-g2001 -gno-specify".

  The supported flags are:

  * 1995
    
    This flag enables the IEEE1364-1995 standard.

  * 2001
    
    This flag enables the IEEE1364-2001 standard.

  * 2001-noconfig
    
    This flag enables the IEEE1364-2001 standard with config file support
    disabled. This eliminates the config file keywords from the language and
    so helps some programs written to older 2001 support compile.

  * 2005
    This flag enables the IEEE1364-2005 standard. This is default enabled
    after v0.9.

  * 2009
    This flag enables the IEEE1800-2009 standard, which includes
    SystemVerilog. The SystemVerilog support is not present in v0.9 and
    earlier. It is new to git master as of November 2009. Actual SystemVerilog
    support is ongoing.

  * 2012
    
    This flag enables the IEEE1800-2012 standard, which includes
    SystemVerilog.

  * verilog-ams
    
    This flag enables Verilog-AMS features that are supported by Icarus
    Verilog. (This is new as of 5 May 2008.)

  * assertions/supported-assertions/no-assertions
    
    Enable or disable SystemVerilog assertions. When enabled, assertion
    statements are elaborated. When disabled, assertion statements are parsed
    but ignored. The supported-assertions option only enables assertions that
    are currently supported by the compiler.

  * specify/no-specify

    Enable or disable support for specify block timing controls. When
    disabled, specify blocks are parsed but ignored. When enabled, specify
    blocks cause timing path and timing checks to be active.

  * std-include/no-std-include

    Enable or disable the search of a standard installation include directory
    after all other explicit include directories. This standard include
    directory is a convenient place to install standard header files that a
    Verilog program may include.

  * relative-include/no-relative-include

    Enable or disable adding the local files directory to the beginning of the
    include file search path. This allows files to be included relative to the
    current file.

  * xtypes/no-xtypes

    Enable or disable support for extended types. Enabling types allows for
    new types and type syntax that are Icarus Verilog extensions.

  * io-range-error/no-io-range-error

    When enabled the range for a port and any associated net declaration must
    match exactly. When disabled a scalar port is allowed to have a net
    declaration with a range (obsolete usage). A warning message will be
    printed for this combination. All other permutations are still considered
    an error.

  * strict-ca-eval/no-strict-ca-eval

    The standard requires that if any input to a continuous assignment
    expression changes value, the entire expression is re-evaluated. By
    default, parts of the expression that do not depend on the changed input
    value(s) are not re-evaluated. If an expression contains a call to a
    function that doesn't depend solely on its input values or that has side
    effects, the resulting behavior will differ from that required by the
    standard. Enabling strict-ca-eval will force standard compliant behavior
    (with some loss in performance).

  * strict-expr-width/no-strict-expr-width

    Enable or disable strict compliance with the standard rules for
    determining expression bit lengths. When disabled, the RHS of a parameter
    assignment is evaluated as a lossless expression, as is any expression
    containing an unsized constant number, and unsized constant numbers are
    not truncated to integer width.

  * shared-loop-index/no-shared-loop-index

    Enable or disable the exclusion of for-loop control variables from
    implicit event_expression lists. When enabled, if a for-loop control
    variable (loop index) is only used inside the for-loop statement, the
    compiler will not include it in an implicit event_expression list it
    calculates for that statement or any enclosing statement. This allows the
    same control variable to be used in multiple processes without risk of
    entering an infinite loop caused by each process triggering all other
    processes that use the same variable. For strict compliance with the
    standards, this behaviour should be disabled.

* -i

  Ignore missing modules. Normally it is an error if a module instantiation
  refers to an undefined module. This option causes the compiler to skip over
  that instantiation. It will also stop the compiler returning an error if
  there are no top level modules. This allows the compiler to be used to check
  incomplete designs for errors.

  NOTE: The "-i" flag was added in v11.0.

* -L <path>

  Add the specified 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 the
  paths will be searched in order.

  NOTE: The "-L" flag was added in v11.0.

* -l <path>

  Add the specified file to the list of source files to be compiled, but mark
  it as a library file. All modules contained within that file will be treated
  as library modules, and only elaborated if they are instantiated by other
  modules in the design.

  NOTE: The "-l" flag is new as of 2 October 2016. It will become available in
  releases and snapshots made after that date.

* -M<mode>=<path>

  Write into the file specified by path a list of files that contribute to the
  compilation of the design.

  If _mode_ is *all* or *prefix*, this includes files that are included by
  include directives and files that are automatically loaded by library
  support as well as the files explicitly specified by the user.

  If _mode_ is *include*, only files that are included by include directives
  are listed.

  If _mode_ is *module*, only files that are specified by the user or that are
  automatically loaded by library support are listed. The output is one file
  name per line, with no leading or trailing space.

  If _mode_ is *prefix*, files that are included by include directives are
  prefixed by "I " and other files are prefixed by "M ".

* -m<module>

  Add this module to the list of VPI modules to be loaded by the
  simulation. Many modules can be specified, and all will be loaded, in the
  order specified. The system module is implicit and always included (and
  loaded last).

  If the specified name includes at least one directory character, it is
  assumed to be prefixed by the path to the module, otherwise the module is
  searched for in the paths specified by preceding -L options, and if not
  found there, in the iverilog base directory.

  NOTE: The "-m" flag was added in v11.0.

* -o <path>

  Specify the output file. The <path> is the name of the file to hold the
  output. The default is "a.out".

* -S

  Activate synthesis. This flag tells the compiler to do what synthesis it can
  do before calling the code generator. This flag is rarely used explicitly,
  and certain code generators will implicitly enable this flag.

* -u

  Treat each source file as a separate compilation unit (as defined in
  SystemVerilog). If compiling for an IEEE1364 generation, this will just
  reset all compiler directives (including macro definitions) before each new
  file is processed.

  NOTE: The "-u" flag was added in v11.0.

* -v

  Be verbose. Print copyright information, progress messages, and some timing
  information about various compilation phases.

  (New in snapshots after 2014-12-16) If the selected target is vvp, the -v
  switch is appended to the shebang line in the compiler output file, so
  directly executing the compiler output file will turn on verbose messages in
  vvp. This extra verbosity can be avoided by using the vvp command to
  indirectly execute the compiler output file.

* -V

  Print the version information. This skips all compilation. Just print the
  version information, including version details for the various components of
  the compiler.

* -R

  Print the runtime paths of the compiler. This can be useful to find, e.g.,
  the include path of vpi_user.h.

* -W<warning class>

  Enable/disable warnings. All the warning types (other then "all") can be
  prefixed with no- to disable that warning.

  * all

    This enables almost all of the available warnings. More specifically, it
    enables these warnings::

      -Wanachronisms
      -Wimplicit
      -Wimplicit-dimensions
      -Wmacro-replacement
      -Wportbind
      -Wselect-range
      -Wtimescale
      -Wsensitivity-entire-array

  * anachronisms

    This enables warnings for use of features that have been deprecated or
    removed in the selected generation of the Verilog language.

  * implicit

    This enables warnings for creation of implicit declarations. For example,
    if a scalar wire X is used but not declared in the Verilog source, this
    will print a warning at its first use.

  * implicit-dimensions
    
    This enables warnings for the case where a port declaration or a var/net
    declaration for the same name is missing dimensions. Normally, Verilog
    allows you to do this (the undecorated declaration gets its dimensions
    form the decorated declaration) but this is no longer common, and some
    other tools (notable Xilix synthesizers) do not handle this correctly.

    This flag is supported in release 10.1 or master branch snapshots after
    2016-02-06.

  * macro-redefinition
    
    This enables warnings when a macro is redefined, even if the macro text
    remains the same.

    NOTE: The "macro-redefinition" flag was added in v11.0.

  * macro-replacement
    
    This enables warnings when a macro is redefined and the macro text
    changes. Use no-macro-redefinition to disable this,

    NOTE: The "macro-replacement" flag was added in v11.0.

  * portbind
    
    This enables warnings for ports of module instantiations that are not
    connected properly, but probably should be. Dangling input ports, for
    example, will generate a warning.

  * select-range
    
    This enables warnings for constant out-of-bound selects. This includes
    partial or fully out-of-bound select as well as a select containing a 'bx
    or 'bz in the index.

  * timescale
    
    This enables warnings for inconsistent use of the timescale directive. It
    detects if some modules have no timescale, or if modules inherit timescale
    from another file. Both probably mean that timescales are inconsistent,
    and simulation timing can be confusing and dependent on compilation order.

  * infloop
    
    This enables warnings for always statements that may have runtime infinite
    loops (i.e. has paths with zero or no delay). This class of warnings is
    not included in -Wall and hence does not have a no- variant. A fatal error
    message will always be printed when the compiler can determine that there
    will definitely be an infinite loop (all paths have no or zero delay).

    When you suspect an always statement is producing a runtine infinite loop,
    use this flag to find the always statements that need to have their logic
    verified. it is expected that many of the warnings will be false
    positives, since the code treats the value of all variables and signals as
    indeterninite.

  * sensitivity-entire-vector

    This enables warnings for when a part select with an "always @*" statement
    results in the entire vector being added to the implicit sensitivity
    list. Although this behavior is prescribed by the IEEE standard, it is not
    what might be expected and can have performance implications if the vector
    is large.

  * sensitivity-entire-array

    This enables warnings for when a word select with an "always @*" statement
    results in the entire array being added to the implicit sensitivity
    list. Although this behavior is prescribed by the IEEE standard, it is not
    what might be expected and can have performance implications if the array
    is large.

  * floating-nets
    
    This enables warnings for nets that are present but have no drivers.

    This flag was added in version 11.0 or later (and is in the master branch
    as of 2015-10-01).

* -y<libdir>

  Append the directory to the library module search path. When the compiler
  finds an undefined module, it looks in these directories for files with the
  right name.

* -Y<suf>

  Appends suf to the list of file extensions that are used to resolve an
  undefined module to a file name. Should be specified before any -y flag. For
  example, this command::

    % iverilog -Y .sv -y sources src.v

  will try to resolve any undefined module m by looking into the directory
  sources and checking if there exist files named m.v or m.sv.


Preprocessor Flags
------------------

These flags control the behavior of the preprocessor. They are similar to
flags for the typical "C" compiler, so C programmers will find them familiar.

* -E

  This flag is special in that it tells the compiler to only run the
  preprocessor. This is useful for example as a way to resolve preprocessing
  for other tools. For example, this command::

    % iverilog -E -ofoo.v -DKEY=10 src1.v src2.v
    
  runs the preprocessor on the source files src1.v and src2.v and produces the
  single output file foo.v that has all the preprocessing (including header
  includes and ifdefs) processed.

* -D<macro>

  Assign a value to the macro name. The format of this flag is one of::

    -Dkey=value
    -Dkey

  The key is defined to have the given value. If no value is given, then it is
  assumed to be "1". The above examples are the same as these defines in
  Verilog source::

    `define key value
    `define key

* -I<path>

  Append directory <path> to list of directories searched for Verilog include
  files. The -I switch may be used many times to specify several directories
  to search, the directories are searched in the order they appear on the
  command line.

Elaboration Flags
-----------------

These are flags that pass information to the elaboration steps.

* -P<symbol>=<value>
  
  Define a parameter using the defparam behavior to override a parameter
  values. This can only be used for parameters of root module instances.

* -s <topmodule>

  Specify the top level module to elaborate. Icarus Verilog will by default
  choose modules that are not instantiated in any other modules, but sometimes
  that is not sufficient, or instantiates too many modules. If the user
  specifies one or more root modules with "-s" flags, then they will be used
  as root modules instead.

* -Tmin, -Ttyp, -Tmax

  Select the timings to use. The Verilog language allows many timings to be
  specified as three numbers, min:typical:max, but for simulation you need to
  choose which set to use. The "-Tmin" flag tells the compiler to at
  elaboration time choose "min" times. The default is "-Ttyp".

Target Flags
------------