1iverilog(1)                  Version 11.0 (stable)                 iverilog(1)
2
3
4

NAME

6       iverilog - Icarus Verilog compiler
7
8

SYNOPSIS

10       iverilog   [-EiSuVv]  [-Bpath]  [-ccmdfile|-fcmdfile]  [-Dmacro[=defn]]
11       [-Pparameter=value]   [-pflag=value]   [-dname]   [-g1995|-g2001|-g2005
12       |-g2005-sv|-g2009|-g2012|-g<feature>]    [-Iincludedir]   [-Lmoduledir]
13       [-mmodule] [-M[mode=]file]  [-Nfile]  [-ooutputfilename]  [-stopmodule]
14       [-ttype] [-Tmin/typ/max] [-Wclass] [-ypath] [-lfile] sourcefile
15
16

DESCRIPTION

18       iverilog  is  a  compiler that translates Verilog source code into exe‐
19       cutable programs for simulation, or other netlist formats  for  further
20       processing. The currently supported targets are vvp for simulation, and
21       fpga for synthesis. Other target types are added as code generators are
22       implemented.
23
24

OPTIONS

26       iverilog accepts the following options:
27
28       -Bbase  The  iverilog  program uses external programs and configuration
29               files to preprocess and compile the Verilog  source.  Normally,
30               the  path used to locate these tools is built into the iverilog
31               program. However, the -B switch allows the  user  to  select  a
32               different  set  of  programs.  The path given is used to locate
33               ivlpp, ivl, code generators and the VPI modules.
34
35       -cfile -ffile
36               These flags specify an input file that contains a list of  Ver‐
37               ilog source files. This is similar to the command file of other
38               Verilog simulators, in that it is a file that contains the file
39               names  instead  of taking them on the command line. See Command
40               Files below.
41
42       -Dmacro Defines macro macro with the string `1' as its definition. This
43               form is normally only used to trigger ifdef conditionals in the
44               Verilog source.
45
46       -Dmacro=defn
47               Defines macro macro as defn.
48
49       -Pparameter=value
50               Override (i.e. defparam) a parameter in a root module. This al‐
51               lows  the user to override at compile time (defparam) a parame‐
52               ter in a root module instance. For example, -Pmain.foo=2  over‐
53               rides  the  parameter  foo  in  the root instance main with the
54               value 2.
55
56       -dname  Activate a class of compiler debugging messages. The -d  switch
57               may  be  used as often as necessary to activate all the desired
58               messages.  Supported names are  scopes,  eval_tree,  elaborate,
59               and synth2; any other names are ignored.
60
61       -E      Preprocess  the Verilog source, but do not compile it. The out‐
62               put file is the Verilog input, but  with  file  inclusions  and
63               macro  references expanded and removed. This is useful, for ex‐
64               ample, to preprocess Verilog source for use by other compilers.
65
66       -g1995|-g2001|-g2001-noconfig|-g2005|-g2005-sv|-g2009|-g2012
67               Select the Verilog language generation to support in  the  com‐
68               piler.   This  selects  between  IEEE1364-1995,  IEEE1364-2001,
69               IEEE1364-2005, IEEE1800-2005, IEEE1800-2009, or  IEEE1800-2012.
70               Icarus  Verilog currently defaults to the IEEE1364-2005 genera‐
71               tion of the language. This flag is used to  restrict  the  lan‐
72               guage  to a set of keywords/features, this allows simulation of
73               older Verilog code that may use newer keywords and for compati‐
74               bility with other tools. Much of the IEEE1800 generations func‐
75               tionality is not currently supported.  The IEEE1800 generations
76               do  parse  all the keywords, so they can be used to verify that
77               IEEE1364 compliant Verilog code does not use  any  of  the  new
78               IEEE1800 keywords.
79
80       -gverilog-ams|-gno-verilog-ams
81               Enable or disable (default) support for Verilog-AMS.  Very lit‐
82               tle Verilog-AMS specific functionality is currently supported.
83
84       -gassertions|-gsupported-assertions|-gno-assertions
85               Enable (default) or disable SystemVerilog assertions. When  en‐
86               abled,  assertion statements are elaborated. When disabled, as‐
87               sertion statements are parsed but ignored. The  -gsupported-as‐
88               sertions option only enables assertions that are currently sup‐
89               ported by the compiler.
90
91       -gspecify|-gno-specify
92               Enable or disable (default) specify  block  support.  When  en‐
93               abled, specify block code is elaborated. When disabled, specify
94               blocks are parsed but ignored. Specify blocks are commonly  not
95               needed  for RTL simulation, and in fact can hurt performance of
96               the simulation. However, disabling specify blocks reduces accu‐
97               racy of full-timing simulations.
98
99       -gstd-include|-gno-std-include
100               Enable  (default) or disable the search of a standard installa‐
101               tion include directory after all other explicit include  direc‐
102               tories.  This  standard include directory is a convenient place
103               to install standard header files that a Verilog program may in‐
104               clude.
105
106       -grelative-include|-gno-relative-include
107               Enable or disable (default) adding the local files directory to
108               the beginning of the include  file  search  path.  This  allows
109               files  to be included relative to the current file not the more
110               common files are only found in the working directory or in  the
111               specified include file search path.
112
113       -gxtypes|-gno-xtypes
114               Enable  (default)  or  disable  support for extended types. En‐
115               abling extended types allows for new types that  are  supported
116               by Icarus Verilog as extensions beyond the baseline Verilog. It
117               may be necessary to disable extended types  if  compiling  code
118               that  clashes  with  the few new keywords used to implement the
119               type system.
120
121       -gio-range-error|-gno-io-range-error
122               The standards requires  that  a  vectored  port  have  matching
123               ranges  for  its  port  declaration as well as any net/register
124               declaration. It was common practice in the past to only specify
125               the range for the net/register declaration and some tools still
126               allow this. By default any mismatch is reported as a error. Us‐
127               ing -gno-io-range-error will produce a warning instead of a fa‐
128               tal error for the case of a vectored net/register and a  scalar
129               port declaration.
130
131       -gstrict-ca-eval|-gno-strict-ca-eval
132               The standard requires that if any input to a continuous assign‐
133               ment expression changes value, the  entire  expression  is  re-
134               evaluated.  By default, parts of the expression that do not de‐
135               pend on the changed input value(s) are not re-evaluated. If  an
136               expression  contains  a  call to a function that doesn't depend
137               solely on its input values or that has side  effects,  the  re‐
138               sulting  behavior  will  differ from that required by the stan‐
139               dard. Using -gstrict-ca-eval will force standard compliant  be‐
140               havior (with some loss in performance).
141
142       -gstrict-expr-width|-gno-strict-expr-width
143               Enable or disable (default) strict compliance with the standard
144               rules for determining expression bit  lengths.  When  disabled,
145               the  RHS  of  a parameter assignment is evaluated as a lossless
146               expression, as is any expression containing an unsized constant
147               number, and unsized constant numbers are not truncated to inte‐
148               ger width.
149
150       -gshared-loop-index|-gno-shared-loop-index
151               Enable (default) or disable the exclusion of  for-loop  control
152               variables  from  implicit event_expression lists. When enabled,
153               if a for-loop control variable (loop index) is only used inside
154               the  for-loop statement, the compiler will not include it in an
155               implicit event_expression list it calculates for that statement
156               or  any enclosing statement. This allows the same control vari‐
157               able to be used in multiple processes without risk of  entering
158               an  infinite  loop  caused by each process triggering all other
159               processes that use the same  varaible.  For  strict  compliance
160               with the standards, this behaviour should be disabled.
161
162       -Iincludedir
163               Append directory includedir to list of directories searched for
164               Verilog include files. The -I switch may be used many times  to
165               specify  several  directories  to  search,  the directories are
166               searched in the order they appear on the command line.
167
168       -i      Ignore missing modules. Normally it is an error if a module in‐
169               stantiation  refers  to an undefined module. This option causes
170               the compiler to skip over that instantiation. It will also stop
171               the  compiler returning an error if there are no top level mod‐
172               ules. This allows the compiler to be used to  check  incomplete
173               designs for errors.
174
175       -Lpath  This  flag adds a directory to the path list used to locate VPI
176               modules. The default path includes only the  install  directory
177               for the system.vpi module, but this flag can add other directo‐
178               ries. Multiple  paths  are  allowed,  and  the  paths  will  be
179               searched in order.
180
181       -lfile  Add  the  specified file to the list of source files to be com‐
182               piled, but mark it as a library  file.  All  modules  contained
183               within  that  file will be treated as library modules, and only
184               elaborated if they are instantiated by other modules in the de‐
185               sign.
186
187       -Mpath  This  is equivalent to -Mall=path. Preserved for backwards com‐
188               patibility.
189
190       -Mmode=path
191               Write into the file specified by path a list of files that con‐
192               tribute  to  the  compilation  of the design. If mode is all or
193               prefix, this includes files that are included by include direc‐
194               tives  and  files that are automatically loaded by library sup‐
195               port as well as the files explicitly specified by the user.  If
196               mode is include, only files that are included by include direc‐
197               tives are listed. If mode is module, only files that are speci‐
198               fied  by  the  user or that are automatically loaded by library
199               support are listed. The output is one file name per line,  with
200               no leading or trailing space. If mode is prefix, files that are
201               included by include directives are prefixed by "I "  and  other
202               files are prefixed by "M ".
203
204       -mmodule
205               Add  this module to the list of VPI modules to be loaded by the
206               simulation. Many modules can be  specified,  and  all  will  be
207               loaded,  in  the order specified. The system module is implicit
208               and always included (and loaded last).
209
210               If the specified name includes at least one  directory  charac‐
211               ter,  it  is  assumed to be prefixed by the path to the module,
212               otherwise the module is searched for in the paths specified  by
213               preceding  -L  options, and if not found there, in the iverilog
214               base directory.
215
216       -Npath  This is used for debugging the compiler proper. Dump the  final
217               netlist  form of the design to the specified file. It otherwise
218               does not affect operation of the compiler. The dump happens af‐
219               ter the design is elaborated and optimized.
220
221       -o filename
222               Place  output  in  the file filename. If no output file name is
223               specified, iverilog uses the default name a.out.
224
225       -pflag=value
226               Assign a value to a target specific flag. The -p switch may  be
227               used  as  often  as necessary to specify all the desired flags.
228               The flags that are used depend on the target that is  selected,
229               and  are described in target specific documentation. Flags that
230               are not used are ignored.
231
232       -S      Synthesize. Normally, if the target can accept  behavioral  de‐
233               scriptions  the  compiler  will  leave  processes in behavioral
234               form. The -S switch causes the compiler  to  perform  synthesis
235               even  if it is not necessary for the target. If the target type
236               is a netlist format, the -S switch is unnecessary  and  has  no
237               effect.
238
239       -s topmodule
240               Specify  the top level module to elaborate. Icarus Verilog will
241               by default choose modules that  are  not  instantiated  in  any
242               other modules, but sometimes that is not sufficient, or instan‐
243               tiates too many modules. If the user specifies one or more root
244               modules  with  -s flags, then they will be used as root modules
245               instead.
246
247       -Tmin|typ|max
248               Use  this  switch  to  select  min,  typ  or  max  times   from
249               min:typ:max expressions. Normally, the compiler will simply use
250               the typ value from these expressions (printing  a  warning  for
251               the  first ten it finds) but this switch will tell the compiler
252               explicitly which value to use. This will suppress  the  warning
253               that the compiler is making a choice.
254
255       -ttarget
256               Use  this  switch  to specify the target output format. See the
257               TARGETS section below for a list of valid output formats.
258
259       -u      Treat each source file as a separate compilation unit  (as  de‐
260               fined  in  SystemVerilog). If compiling for an IEEE1364 genera‐
261               tion, this will just reset all compiler  directives  (including
262               macro definitions) before each new file is processed.
263
264       -v      Turn  on  verbose  messages.  This will print the command lines
265               that are executed to perform the actual compilation, along with
266               version information from the various components, as well as the
267               version of the product as a whole.  You will  notice  that  the
268               command  lines include a reference to a key temporary file that
269               passes information to the compiler proper.  To keep  that  file
270               from  being  deleted  at the end of the process, provide a file
271               name of your own in the environment variable IVERILOG_ICONFIG.
272
273               If the selected target is vvp, the -v switch is appended to the
274               shebang line in the compiler output file, so directly executing
275               the compiler output file will turn on verbose messages in  vvp.
276               This extra verbosity can be avoided by using the vvp command to
277               indirectly execute the compiler output file.
278
279       -V      Print the version of the compiler, and exit.
280
281       -Wclass Turn on different classes of warnings. See  the  WARNING  TYPES
282               section below for descriptions of the different warning groups.
283               If multiple -W switches are used, the warning set is the  union
284               of all the requested classes.
285
286       -ylibdir
287               Append  the  directory  to the library module search path. When
288               the compiler finds an undefined module, it looks in  these  di‐
289               rectories for files with the right name.
290
291       -Ysuffix
292               Add suffix to the list of accepted file name suffixes used when
293               searching a library for cells. The list defaults to the  single
294               entry .v.
295
296

MODULE LIBRARIES

298       The  Icarus  Verilog  compiler supports module libraries as directories
299       that contain Verilog source files.  During  elaboration,  the  compiler
300       notices the instantiation of undefined module types. If the user speci‐
301       fies library search directories, the compiler will search the directory
302       for  files with the name of the missing module type. If it finds such a
303       file, it loads it as a Verilog source file, then tries again to  elabo‐
304       rate the module.
305
306       Library  module  files should contain only a single module, but this is
307       not a requirement. Library modules may reference other modules  in  the
308       library or in the main design.
309
310

TARGETS

312       The  Icarus Verilog compiler supports a variety of targets, for differ‐
313       ent purposes, and the -t switch is used to select the desired target.
314
315
316       null    The null target causes no code to be generated.  It  is  useful
317               for checking the syntax of the Verilog source.
318
319       vvp     This  is the default. The vvp target generates code for the vvp
320               runtime. The output is a complete program  that  simulates  the
321               design but must be run by the vvp command. The -pfileline=1 op‐
322               tion can be used to add procedural statement debugging  opcodes
323               to  the generated code. These opcodes are also used to generate
324               file and line information  for  procedural  warning/error  mes‐
325               sages. To enable the debug command tracing us the trace command
326               (trace on) from the vvp interactive prompt.
327
328       fpga    This is a synthesis target that supports a variety of fpga  de‐
329               vices,  mostly  by  EDIF format output. The Icarus Verilog fpga
330               code generator can generate complete  designs  or  EDIF  macros
331               that  can  in  turn  be  imported  into larger designs by other
332               tools. The fpga target implies the synthesis -S flag.
333
334       vhdl    This target produces a VHDL translation of the Verilog netlist.
335               The  output  is  a  single file containing VHDL entities corre‐
336               sponding to the modules in the Verilog source code.  Note  that
337               only  a  subset  of the Verilog language is supported.  See the
338               wiki for more information.
339
340

WARNING TYPES

342       These are the types of warnings that can be selected by the -W  switch.
343       All the warning types (other than all) can also be prefixed with no- to
344       turn off that warning. This is most useful after a  -Wall  argument  to
345       suppress isolated warning types.
346
347
348       all     This  enables  the  anachronisms,  implicit, macro-replacement,
349               portbind, select-range, timescale, and sensitivity-entire-array
350               warning categories.
351
352
353       anachronisms
354               This enables warnings for use of features that have been depre‐
355               cated or removed in the selected generation of the Verilog lan‐
356               guage.
357
358
359       implicit
360               This  enables  warnings  for creation of implicit declarations.
361               For example, if a scalar wire X is used but not declared in the
362               Verilog source, this will print a warning at its first use.
363
364
365       macro-redefinition | macro-replacement
366               This  enables preprocessor warnings when a macro is being rede‐
367               fined.  The first variant prints a warning any time a macro  is
368               redefined.   The  second  variant  only prints a warning if the
369               macro text changes.  Use no-macro-redefinition to turn off  all
370               warnings of this type.
371
372
373       portbind
374               This  enables  warnings for ports of module instantiations that
375               are not connected but probably should be. Dangling input ports,
376               for example, will generate a warning.
377
378
379       select-range
380               This  enables  warnings for constant out of bound selects. This
381               includes partial or fully out of bound selects as well as a se‐
382               lect containing a 'bx or 'bz in the index.
383
384
385       timescale
386               This enables warnings for inconsistent use of the timescale di‐
387               rective. It detects if some modules have no  timescale,  or  if
388               modules inherit timescale from another file. Both probably mean
389               that timescales are inconsistent, and simulation timing can  be
390               confusing and dependent on compilation order.
391
392
393       infloop This  enables warnings for always statements that may have run‐
394               time infinite loops (has paths with no  or  zero  delay).  This
395               class  of  warnings is not included in -Wall and hence does not
396               have a no- variant.  A  fatal  error  message  will  always  be
397               printed  when  the compiler can determine that there will defi‐
398               nitely be an infinite loop (all paths have no or zero delay).
399
400               When you suspect an always statement is producing a runtime in‐
401               finite  loop  use  this flag to find the always statements that
402               need to have their logic verified. It is expected that many  of
403               the warnings will be false positives, since the code treats the
404               value of all variables and signals as indeterminate.
405
406
407       sensitivity-entire-vector
408               This enables warnings for when a part select within an  "always
409               @*"  statement  results in the entire vector being added to the
410               implicit sensitivity list.  Although  this  behaviour  is  pre‐
411               scribed  by the IEEE standard, it is not what might be expected
412               and can have performance implications if the vector is large.
413
414
415       sensitivity-entire-array
416               This enables warnings for when a word select within an  "always
417               @*"  statement  results  in the entire array being added to the
418               implicit sensitivity list.  Although  this  behaviour  is  pre‐
419               scribed  by the IEEE standard, it is not what might be expected
420               and can have performance implications if the array is large.
421
422

VPI MODULES

424       If the source file name has a .vpi or .vpl suffix, then it is taken  to
425       be a VPI module. VPI modules supplied by the user are scanned to deter‐
426       mine the return types of any system functions  they  provide.  This  is
427       necessary  because the compiler needs this information to elaborate ex‐
428       pressions that contain these system functions. The module path/name  is
429       passed  on  to  the  target to allow the VPI module to be automatically
430       loaded at the start of simulation.
431
432       VPI modules may also be supplied using the -L and -m options.
433
434

SYSTEM FUNCTION TABLE FILES [deprecated]

436       If the source file name has a .sft suffix, then it is  taken  to  be  a
437       system  function  table  file.  A system function table file is the old
438       method used to describe to the compiler the  return  types  for  system
439       functions.   Users are encouraged to switch to the new method of simply
440       supplying the VPI module.
441
442       The format of the table is ASCII, one function per  line.  Empty  lines
443       are  ignored,  and  lines that start with the '#' character are comment
444       lines. Each non-comment line starts with the function  name,  then  the
445       vpi type (i.e. vpiSysFuncReal). The following types are supported:
446
447
448       vpiSysFuncReal
449               The function returns a real/realtime value.
450
451
452       vpiSysFuncInt
453               The function returns an integer.
454
455
456       vpiSysFuncSized <wid> <signed|unsigned>
457               The  function  returns  a  vector  with the given width, and is
458               signed or unsigned according to the flag.
459
460
461       vpiSysFuncString
462               The function returns a string. This is an  Icarus-specific  ex‐
463               tension, not available in the VPI standard.
464
465

COMMAND FILES

467       The command file allows the user to place source file names and certain
468       command line switches into a text file instead of  on  a  long  command
469       line.  Command  files can include C or C++ style comments, as well as #
470       comments, if the # starts the line.
471
472
473       file name
474               A simple file name or file path is taken to be the  name  of  a
475               Verilog  source file. The path starts with the first non-white-
476               space character. Variables are substituted in file names.
477
478
479       -c cmdfile -f cmdfile
480               A -c or -f token prefixes a command file, exactly like it  does
481               on the command line. The cmdfile may be on the same line or the
482               next non-comment line.
483
484
485       -l file -v file
486               A -l token prefixes a library file in the command file, exactly
487               like  it does on the command line. The parameter to the -l flag
488               may be on the same line or the next non-comment line. -v is  an
489               alias for -l, provided for compatibility with other simulators.
490
491               Variables in the file are substituted.
492
493
494       -y libdir
495               A  -y  token  prefixes a library directory in the command file,
496               exactly like it does on the command line. The parameter to  the
497               -y flag may be on the same line or the next non-comment line.
498
499               Variables in the libdir are substituted.
500
501
502       +incdir+includedir
503               The +incdir+ token in command files gives directories to search
504               for include files in much the same way that -I  flags  work  on
505               the  command  line. The difference is that multiple +includedir
506               directories are valid parameters to a  single  +incdir+  token,
507               although you may also have multiple +incdir+ lines.
508
509               Variables in the includedir are substituted.
510
511
512       +libext+ext
513               The +libext token in command files lists file extensions to try
514               when looking for a library file. This is useful in  conjunction
515               with  -y flags to list suffixes to try in each directory before
516               moving on to the next library directory.
517
518
519       +libdir+dir
520               This is another way to specify library directories. See the  -y
521               flag.
522
523
524       +libdir-nocase+dir
525               This  is  like the +libdir statement, but file names inside the
526               directories declared here are  case  insensitive.  The  missing
527               module  name  in a lookup need not match the file name case, as
528               long as the letters are correct.  For  example,  "foo"  matches
529               "Foo.v" but not "bar.v".
530
531
532       +define+NAME=value
533               The  +define+ token is the same as the -D option on the command
534               line. The value part of the token is optional.
535
536
537       +parameter+NAME=value
538               The +parameter+ token is the same as the -P option on the  com‐
539               mand line.
540
541
542       +timescale+value
543               The  +timescale+ token is used to set the default timescale for
544               the simulation. This is the time units and precision before any
545               `timescale  directive  or  after a `resetall directive. The de‐
546               fault is 1s/1s.
547
548
549       +toupper-filename
550               This token causes file names after this in the command file  to
551               be  translated to uppercase. This helps with situations where a
552               directory has passed through a DOS machine, and in the  process
553               the file names become munged.
554
555
556       +tolower-filename
557               This is similar to the +toupper-filename hack described above.
558
559
560       +integer-width+value
561               This  allows  the  programmer  to  select the width for integer
562               variables in the Verilog source. The default is 32,  the  value
563               can be any desired integer value.
564
565
566       +width-cap+value
567               This  allows the programmer to select the width cap for unsized
568               expressions.  If the calculated width for an unsized expression
569               exceeds this value, the compiler will issue a warning and limit
570               the expression width to this value.
571
572

VARIABLES IN COMMAND FILES

574       In certain cases, iverilog supports variables in command  files.  These
575       are  strings of the form "$(varname)" or "${varname}", where varname is
576       the name of the environment variable to read. The entire string is  re‐
577       placed  with  the contents of that variable. Variables are only substi‐
578       tuted in contexts that explicitly support them, including file and  di‐
579       rectory strings.
580
581       Variable  values  come  from  the operating system environment, and not
582       from preprocessor defines elsewhere in the file or the command line.
583
584

PREDEFINED MACROS

586       The following macros are predefined by the compiler:
587
588       __ICARUS__ = 1
589               This is always defined when compiling with Icarus Verilog.
590
591
592       __VAMS_ENABLE__ = 1
593               This is defined if Verilog-AMS is enabled.
594
595

ENVIRONMENT

597       iverilog also accepts some environment variables that control  its  be‐
598       havior. These can be used to make semi-permanent changes.
599
600
601       IVERILOG_ICONFIG=file-name
602               This  sets the name used for the temporary file that passes pa‐
603               rameters to the compiler proper, and prevents that  file  being
604               deleted after the compiler has exited.
605
606
607       IVERILOG_VPI_MODULE_PATH=/some/path:/some/other/path
608               This  adds additional components to the VPI module search path.
609               Paths specified in this way are searched after paths  specified
610               with -L, but before the default search path. Multiple paths can
611               be separated with colons (semicolons if using Windows).
612
613

EXAMPLES

615       These examples assume that  you  have  a  Verilog  source  file  called
616       hello.v in the current directory
617
618       To compile hello.v to an executable file called a.out:
619
620            iverilog hello.v
621
622       To compile hello.v to an executable file called hello:
623
624            iverilog -o hello hello.v
625
626       To compile and run explicitly using the vvp runtime:
627
628            iverilog -ohello.vvp -tvvp hello.v
629
630

AUTHOR

632       Steve Williams (steve@icarus.com)
633
634

SEE ALSO

636       vvp(1), <http://iverilog.icarus.com/>
637
638       Tips  on  using, debugging, and developing the compiler can be found at
639       <http://iverilog.wikia.com/>
640
641
643       Copyright ©  2002-2020 Stephen Williams
644
645       This document can be freely redistributed according to the terms of the
646       GNU General Public License version 2.0
647
648
649
650                                Aug 10th, 2020                     iverilog(1)
Impressum