1iverilog(1) Version 11.0 (stable) iverilog(1)
2
6 iverilog - Icarus Verilog compiler
7
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
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
26 iverilog accepts the following options:
27 -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 -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 -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 -Dmacro=defn
47 Defines macro macro as defn.
48 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -Mpath This is equivalent to -Mall=path. Preserved for backwards com‐
188 patibility.
189 -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 -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 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 -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 -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 -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 -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 -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 -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 -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 -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 -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 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 -V Print the version of the compiler, and exit.
280 -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 -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 -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
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 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
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 null The null target causes no code to be generated. It is useful
317 for checking the syntax of the Verilog source.
318 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 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 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
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 all This enables the anachronisms, implicit, macro-replacement,
349 portbind, select-range, timescale, and sensitivity-entire-array
350 warning categories.
351 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 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 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 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 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 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 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 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 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 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
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 VPI modules may also be supplied using the -L and -m options.
433
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 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 vpiSysFuncReal
449 The function returns a real/realtime value.
450 vpiSysFuncInt
453 The function returns an integer.
454 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 vpiSysFuncString
462 The function returns a string. This is an Icarus-specific ex‐
463 tension, not available in the VPI standard.
464
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 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 -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 -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 Variables in the file are substituted.
492 -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 Variables in the libdir are substituted.
500 +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 Variables in the includedir are substituted.
510 +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 +libdir+dir
520 This is another way to specify library directories. See the -y
521 flag.
522 +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 +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 +parameter+NAME=value
538 The +parameter+ token is the same as the -P option on the com‐
539 mand line.
540 +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 +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 +tolower-filename
557 This is similar to the +toupper-filename hack described above.
558 +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 +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
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 Variable values come from the operating system environment, and not
582 from preprocessor defines elsewhere in the file or the command line.
583
586 The following macros are predefined by the compiler:
587 __ICARUS__ = 1
589 This is always defined when compiling with Icarus Verilog.
590 __VAMS_ENABLE__ = 1
593 This is defined if Verilog-AMS is enabled.
594
597 iverilog also accepts some environment variables that control its be‐
598 havior. These can be used to make semi-permanent changes.
599 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 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
615 These examples assume that you have a Verilog source file called
616 hello.v in the current directory
617 To compile hello.v to an executable file called a.out:
619 iverilog hello.v
621 To compile hello.v to an executable file called hello:
623 iverilog -o hello hello.v
625 To compile and run explicitly using the vvp runtime:
627 iverilog -ohello.vvp -tvvp hello.v
629
632 Steve Williams (steve@icarus.com)
633
636 vvp(1), <http://iverilog.icarus.com/>
637 Tips on using, debugging, and developing the compiler can be found at
639 <http://iverilog.wikia.com/>
640
643 Copyright © 2002-2020 Stephen Williams
644 This document can be freely redistributed according to the terms of the
646 GNU General Public License version 2.0
647 Aug 10th, 2020 iverilog(1)