xenial (1) iverilog.1.gz

Provided by: iverilog_0.9.7-1_amd64 bug

NAME

       iverilog - Icarus Verilog compiler

SYNOPSIS

       iverilog    [-ESVv]    [-Bpath]    [-ccmdfile|-fcmdfile]    [-Dmacro[=defn]]    [-pflag=value]   [-dname]
       [-g1995|-g2001|-g2005|-g<feature>]  [-Iincludedir]  [-mmodule]   [-Mfile]   [-Nfile]   [-ooutputfilename]
       [-stopmodule] [-ttype] [-Tmin/typ/max] [-Wclass] [-ypath] 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 specifies 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.

       -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
               Select  the  Verilog  language  generation  to  support  in  the  compiler.  This selects between
               IEEE1364-1995, IEEE1364-2001, or IEEE1364-2005. Normally, Icarus Verilog defaults to  the  latest
               known  generation  of  the  language.  This flag is most useful to restrict the language to a set
               supported by tools of specific generations, for compatibility with other tools.

       -gverilog-ams|-gno-verilog-ams
               Enable  or  disable  (default)  support  for  Verilog-AMS.   Very  little  Verilog-AMS   specific
               functionality is currently supported.

       -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.

       -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).

       -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.

       -Mpath  Write into the file specified by path a list of files that contribute to the compilation  of  the
               design.  This  includes  files  that  are  included  by  include  directives  and  files that are
               automatically loaded by library support. The output is one file name per line, with no leading or
               trailing space.

       -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.  If a System Function Table file (<module>.sft) exists for the module it will be
               loaded automatically.

       -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.

       -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.

       -V      Print the version 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, they 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.

       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  implicit,  portbind,  select-range,  timescale,  and sensitivity-entire-array
               warning categories.

       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.

       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.

SYSTEM FUNCTION TABLE FILES

       If the source file name as a .sft suffix, then it is taken to be a system function table file.  A  System
       function  table  file  is used to describe to the compiler the return types for system functions. This is
       necessary because the compiler needs this information to elaborate expressions that contain these  system
       functions, but cannot run the sizetf functions since it has no run-time.

       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.

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.

       -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 fives 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.

       +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.

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.

       __VAMS_ENABLE__ = 1
               This is defined if Verilog-AMS is enabled.

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://www.icarus.com/eda/verilog/>

       Tips on using, debugging, and developing the compiler can be found at <http://iverilog.wikia.com/>

       Copyright ©  2002-2010 Stephen Williams

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

                                               January 22nd, 2010                                    iverilog(1)