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