Provided by: iverilog_12.0-2build2_amd64 
NAME
iverilog - Icarus Verilog compiler
SYNOPSIS
iverilog [-EiRSuVv] [-Bpath] [-ccmdfile|-fcmdfile] [-Dmacro[=defn]] [-Pparameter=value]
[-pflag=value] [-dname] [-g1995|-g2001|-g2005|-g2005-sv|-g2009|-g2012|-g<feature>]
[-Iincludedir] [-Lmoduledir] [-mmodule] [-M[mode=]file] [-Nfile] [-ooutputfilename]
[-stopmodule] [-ttype] [-Tmin/typ/max] [-Wclass] [-ypath] [-lfile] sourcefile
DESCRIPTION
iverilog is a compiler that translates Verilog source code into executable programs for
simulation, or other netlist formats for further processing. The currently supported
targets are vvp for simulation, and fpga for synthesis. Other target types are added as
code generators are implemented.
OPTIONS
iverilog accepts the following options:
-Bbase The iverilog program uses external programs and configuration files to preprocess
and compile the Verilog source. Normally, the path used to locate these tools is
built into the iverilog program. However, the -B switch allows the user to select
a different set of programs. The path given is used to locate ivlpp, ivl, code
generators and the VPI modules.
-cfile -ffile
These flags specify an input file that contains a list of Verilog source files.
This is similar to the command file of other Verilog simulators, in that it is a
file that contains the file names instead of taking them on the command line. See
Command Files below.
-Dmacro Defines macro macro with the string `1' as its definition. This form is normally
only used to trigger ifdef conditionals in the Verilog source.
-Dmacro=defn
Defines macro macro as defn.
-Pparameter=value
Override (i.e. defparam) a parameter in a root module. This allows the user to
override at compile time (defparam) a parameter in a root module instance. For
example, -Pmain.foo=2 overrides the parameter foo in the root instance main with
the value 2.
-dname Activate a class of compiler debugging messages. The -d switch may be used as
often as necessary to activate all the desired messages. Supported names are
scopes, eval_tree, elaborate, and synth2; any other names are ignored.
-E Preprocess the Verilog source, but do not compile it. The output file is the
Verilog input, but with file inclusions and macro references expanded and removed.
This is useful, for example, to preprocess Verilog source for use by other
compilers.
-g1995|-g2001|-g2001-noconfig|-g2005|-g2005-sv|-g2009|-g2012
Select the Verilog language generation to support in the compiler. This selects
between IEEE1364-1995, IEEE1364-2001, IEEE1364-2005, IEEE1800-2005, IEEE1800-2009,
or IEEE1800-2012. Icarus Verilog currently defaults to the IEEE1364-2005
generation of the language. This flag is used to restrict the language to a set of
keywords/features, this allows simulation of older Verilog code that may use newer
keywords and for compatibility with other tools. Much of the IEEE1800 generations
functionality is not currently supported. The IEEE1800 generations do parse all
the keywords, so they can be used to verify that IEEE1364 compliant Verilog code
does not use any of the new IEEE1800 keywords.
-gverilog-ams|-gno-verilog-ams
Enable or disable (default) support for Verilog-AMS. Very little Verilog-AMS
specific functionality is currently supported.
-gassertions|-gsupported-assertions|-gno-assertions
Enable (default) or disable SystemVerilog assertions. When enabled, assertion
statements are elaborated. When disabled, assertion statements are parsed but
ignored. The -gsupported-assertions option only enables assertions that are
currently supported by the compiler.
-gspecify|-gno-specify
Enable or disable (default) specify block support. When enabled, specify block
code is elaborated. When disabled, specify blocks are parsed but ignored. Specify
blocks are commonly not needed for RTL simulation, and in fact can hurt
performance of the simulation. However, disabling specify blocks reduces accuracy
of full-timing simulations.
-gstd-include|-gno-std-include
Enable (default) 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.
-grelative-include|-gno-relative-include
Enable or disable (default) 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 not the more common files are only found in the working directory or
in the specified include file search path.
-gxtypes|-gno-xtypes
Enable (default) or disable support for extended types. Enabling extended types
allows for new types that are supported by Icarus Verilog as extensions beyond the
baseline Verilog. It may be necessary to disable extended types if compiling code
that clashes with the few new keywords used to implement the type system.
-gio-range-error|-gno-io-range-error
The standards requires that a vectored port have matching ranges for its port
declaration as well as any net/register declaration. It was common practice in the
past to only specify the range for the net/register declaration and some tools
still allow this. By default any mismatch is reported as a error. Using
-gno-io-range-error will produce a warning instead of a fatal error for the case
of a vectored net/register and a scalar port declaration. This warning is included
in the anachronisms category.
-gstrict-ca-eval|-gno-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. Using -gstrict-ca-eval will force standard
compliant behavior (with some loss in performance).
-gstrict-expr-width|-gno-strict-expr-width
Enable or disable (default) 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.
-gshared-loop-index|-gno-shared-loop-index
Enable (default) 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.
-Iincludedir
Append directory includedir 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.
-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.
-Lpath 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 the paths
will be searched in order.
-lfile 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.
-Mpath This is equivalent to -Mall=path. Preserved for backwards compatibility.
-Mmode=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 ".
-mmodule
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.
-Npath This is used for debugging the compiler proper. Dump the final netlist form of the
design to the specified file. It otherwise does not affect operation of the
compiler. The dump happens after the design is elaborated and optimized.
-o filename
Place output in the file filename. If no output file name is specified, iverilog
uses the default name a.out.
-pflag=value
Assign a value to a target specific flag. The -p switch may be used as often as
necessary to specify all the desired flags. The flags that are used depend on the
target that is selected, and are described in target specific documentation. Flags
that are not used are ignored.
-S Synthesize. Normally, if the target can accept behavioral descriptions the
compiler will leave processes in behavioral form. The -S switch causes the
compiler to perform synthesis even if it is not necessary for the target. If the
target type is a netlist format, the -S switch is unnecessary and has no effect.
-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|typ|max
Use this switch to select min, typ or max times from min:typ:max expressions.
Normally, the compiler will simply use the typ value from these expressions
(printing a warning for the first ten it finds) but this switch will tell the
compiler explicitly which value to use. This will suppress the warning that the
compiler is making a choice.
-ttarget
Use this switch to specify the target output format. See the TARGETS section below
for a list of valid output formats.
-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.
-v Turn on verbose messages. This will print the command lines that are executed to
perform the actual compilation, along with version information from the various
components, as well as the version of the product as a whole. You will notice
that the command lines include a reference to a key temporary file that passes
information to the compiler proper. To keep that file from being deleted at the
end of the process, provide a file name of your own in the environment variable
IVERILOG_ICONFIG.
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 of the compiler, and exit.
-R Print the runtime paths of the compiler, and exit.
-Wclass Turn on different classes of warnings. See the WARNING TYPES section below for
descriptions of the different warning groups. If multiple -W switches are used,
the warning set is the union of all the requested classes.
-ylibdir
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.
-Ysuffix
Add suffix to the list of accepted file name suffixes used when searching a
library for cells. The list defaults to the single entry .v.
MODULE LIBRARIES
The Icarus Verilog compiler supports module libraries as directories that contain Verilog
source files. During elaboration, the compiler notices the instantiation of undefined
module types. If the user specifies library search directories, the compiler will search
the directory for files with the name of the missing module type. If it finds such a file,
it loads it as a Verilog source file, then tries again to elaborate the module.
Library module files should contain only a single module, but this is not a requirement.
Library modules may reference other modules in the library or in the main design.
TARGETS
The Icarus Verilog compiler supports a variety of targets, for different purposes, and the
-t switch is used to select the desired target.
null The null target causes no code to be generated. It is useful for checking the
syntax of the Verilog source.
vvp This is the default. The vvp target generates code for the vvp runtime. The output
is a complete program that simulates the design but must be run by the vvp
command. The -pfileline=1 option can be used to add procedural statement debugging
opcodes to the generated code. These opcodes are also used to generate file and
line information for procedural warning/error messages. To enable the debug
command tracing us the trace command (trace on) from the vvp interactive prompt.
fpga This is a synthesis target that supports a variety of fpga devices, mostly by EDIF
format output. The Icarus Verilog fpga code generator can generate complete
designs or EDIF macros that can in turn be imported into larger designs by other
tools. The fpga target implies the synthesis -S flag.
vhdl This target produces a VHDL translation of the Verilog netlist. The output is a
single file containing VHDL entities corresponding to the modules in the Verilog
source code. Note that only a subset of the Verilog language is supported. See
the wiki for more information.
WARNING TYPES
These are the types of warnings that can be selected by the -W switch. All the warning
types (other than all) can also be prefixed with no- to turn off that warning. This is
most useful after a -Wall argument to suppress isolated warning types.
all This enables the anachronisms, implicit, macro-replacement, portbind,
select-range, timescale, and sensitivity-entire-array warning categories.
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.
macro-redefinition | macro-replacement
This enables preprocessor warnings when a macro is being redefined. The first
variant prints a warning any time a macro is redefined. The second variant only
prints a warning if the macro text changes. Use no-macro-redefinition to turn off
all warnings of this type.
portbind
This enables warnings for ports of module instantiations that are not connected
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 selects 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
(has paths with no or zero 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 runtime 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 indeterminate.
sensitivity-entire-vector
This enables warnings for when a part select within an "always @*" statement
results in the entire vector being added to the implicit sensitivity list.
Although this behaviour 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 within an "always @*" statement
results in the entire array being added to the implicit sensitivity list. Although
this behaviour is prescribed by the IEEE standard, it is not what might be
expected and can have performance implications if the array is large.
VPI MODULES
If the source file name has a .vpi or .vpl suffix, then it is taken to be a VPI module.
VPI modules supplied by the user are scanned to determine the return types of any system
functions they provide. This is necessary because the compiler needs this information to
elaborate expressions that contain these system functions. The module path/name is passed
on to the target to allow the VPI module to be automatically loaded at the start of
simulation.
VPI modules may also be supplied using the -L and -m options.
SYSTEM FUNCTION TABLE FILES [deprecated]
If the source file name has a .sft suffix, then it is taken to be a system function table
file. A system function table file is the old method used to describe to the compiler the
return types for system functions. Users are encouraged to switch to the new method of
simply supplying the VPI module.
The format of the table is ASCII, one function per line. Empty lines are ignored, and
lines that start with the '#' character are comment lines. Each non-comment line starts
with the function name, then the vpi type (i.e. vpiSysFuncReal). The following types are
supported:
vpiSysFuncReal
The function returns a real/realtime value.
vpiSysFuncInt
The function returns an integer.
vpiSysFuncSized <wid> <signed|unsigned>
The function returns a vector with the given width, and is signed or unsigned
according to the flag.
vpiSysFuncString
The function returns a string. This is an Icarus-specific extension, not available
in the VPI standard.
COMMAND FILES
The command file allows the user to place source file names and certain command line
switches into a text file instead of on a long command line. Command files can include C
or C++ style comments, as well as # comments, if the # starts the line.
file name
A simple file name or file path is taken to be the name of a Verilog source file.
The path starts with the first non-white-space character. Variables are
substituted in file names.
-c cmdfile -f cmdfile
A -c or -f token prefixes a command file, exactly like it does on the command
line. The cmdfile may be on the same line or the next non-comment line.
-l file -v file
A -l token prefixes a library file in the command file, exactly like it does on
the command line. The parameter to the -l flag may be on the same line or the next
non-comment line. -v is an alias for -l, provided for compatibility with other
simulators.
Variables in the file are substituted.
-y libdir
A -y token prefixes a library directory in the command file, exactly like it does
on the command line. The parameter to the -y flag may be on the same line or the
next non-comment line.
Variables in the libdir are substituted.
+incdir+includedir
The +incdir+ token in command files gives directories to search for include files
in much the same way that -I flags work on the command line. The difference is
that multiple +includedir directories are valid parameters to a single +incdir+
token, although you may also have multiple +incdir+ lines.
Variables in the includedir are substituted.
+libext+ext
The +libext token in command files lists file extensions to try when looking for a
library file. This is useful in conjunction with -y flags to list suffixes to try
in each directory before moving on to the next library directory.
+libdir+dir
This is another way to specify library directories. See the -y flag.
+libdir-nocase+dir
This is like the +libdir statement, but file names inside the directories declared
here are case insensitive. The missing module name in a lookup need not match the
file name case, as long as the letters are correct. For example, "foo" matches
"Foo.v" but not "bar.v".
+define+NAME=value
The +define+ token is the same as the -D option on the command line. The value
part of the token is optional.
+parameter+NAME=value
The +parameter+ token is the same as the -P option on the command line.
+timescale+value
The +timescale+ token is used to set the default timescale for the simulation.
This is the time units and precision before any `timescale directive or after a
`resetall directive. The default is 1s/1s.
+toupper-filename
This token causes file names after this in the command file to be translated to
uppercase. This helps with situations where a directory has passed through a DOS
machine, and in the process the file names become munged.
+tolower-filename
This is similar to the +toupper-filename hack described above.
+integer-width+value
This allows the programmer to select the width for integer variables in the
Verilog source. The default is 32, the value can be any desired integer value.
+width-cap+value
This allows the programmer to select the width cap for unsized expressions. If
the calculated width for an unsized expression exceeds this value, the compiler
will issue a warning and limit the expression width to this value.
VARIABLES IN COMMAND FILES
In certain cases, iverilog supports variables in command files. These are strings of the
form "$(varname)" or "${varname}", where varname is the name of the environment variable
to read. The entire string is replaced with the contents of that variable. Variables are
only substituted in contexts that explicitly support them, including file and directory
strings.
Variable values come from the operating system environment, and not from preprocessor
defines elsewhere in the file or the command line.
PREDEFINED MACROS
The following macros are predefined by the compiler:
__ICARUS__ = 1
This is always defined when compiling with Icarus Verilog.
__ICARUS_SYNTH__ = 1
This is defined when synthesis is enabled.
__VAMS_ENABLE__ = 1
This is defined when Verilog-AMS is enabled.
ENVIRONMENT
iverilog also accepts some environment variables that control its behavior. These can be
used to make semi-permanent changes.
IVERILOG_ICONFIG=file-name
This sets the name used for the temporary file that passes parameters to the
compiler proper, and prevents that file being deleted after the compiler has
exited.
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 -L, but before the default search
path. Multiple paths can be separated with colons (semicolons if using Windows).
EXAMPLES
These examples assume that you have a Verilog source file called hello.v in the current
directory
To compile hello.v to an executable file called a.out:
iverilog hello.v
To compile hello.v to an executable file called hello:
iverilog -o hello hello.v
To compile and run explicitly using the vvp runtime:
iverilog -ohello.vvp -tvvp hello.v
AUTHOR
Steve Williams (steve@icarus.com)
SEE ALSO
vvp(1), <http://iverilog.icarus.com/>
Tips on using, debugging, and developing the compiler can be found at
<http://iverilog.wikia.com/>
COPYRIGHT
Copyright © 2002-2021 Stephen Williams
This document can be freely redistributed according to the terms of the
GNU General Public License version 2.0
Jan 14th, 2021 iverilog(1)