1iverilog(1) Version 12.0 (stable) iverilog(1)
2
6 iverilog - Icarus Verilog compiler
7
10 iverilog [-EiRSuVv] [-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. This warning is included in the anachronisms
130 category.
131 -gstrict-ca-eval|-gno-strict-ca-eval
133 The standard requires that if any input to a continuous assign‐
134 ment expression changes value, the entire expression is re-
135 evaluated. By default, parts of the expression that do not de‐
136 pend on the changed input value(s) are not re-evaluated. If an
137 expression contains a call to a function that doesn't depend
138 solely on its input values or that has side effects, the re‐
139 sulting behavior will differ from that required by the stan‐
140 dard. Using -gstrict-ca-eval will force standard compliant be‐
141 havior (with some loss in performance).
142 -gstrict-expr-width|-gno-strict-expr-width
144 Enable or disable (default) strict compliance with the standard
145 rules for determining expression bit lengths. When disabled,
146 the RHS of a parameter assignment is evaluated as a lossless
147 expression, as is any expression containing an unsized constant
148 number, and unsized constant numbers are not truncated to inte‐
149 ger width.
150 -gshared-loop-index|-gno-shared-loop-index
152 Enable (default) or disable the exclusion of for-loop control
153 variables from implicit event_expression lists. When enabled,
154 if a for-loop control variable (loop index) is only used inside
155 the for-loop statement, the compiler will not include it in an
156 implicit event_expression list it calculates for that statement
157 or any enclosing statement. This allows the same control vari‐
158 able to be used in multiple processes without risk of entering
159 an infinite loop caused by each process triggering all other
160 processes that use the same varaible. For strict compliance
161 with the standards, this behaviour should be disabled.
162 -Iincludedir
164 Append directory includedir to list of directories searched for
165 Verilog include files. The -I switch may be used many times to
166 specify several directories to search, the directories are
167 searched in the order they appear on the command line.
168 -i Ignore missing modules. Normally it is an error if a module in‐
170 stantiation refers to an undefined module. This option causes
171 the compiler to skip over that instantiation. It will also stop
172 the compiler returning an error if there are no top level mod‐
173 ules. This allows the compiler to be used to check incomplete
174 designs for errors.
175 -Lpath This flag adds a directory to the path list used to locate VPI
177 modules. The default path includes only the install directory
178 for the system.vpi module, but this flag can add other directo‐
179 ries. Multiple paths are allowed, and the paths will be
180 searched in order.
181 -lfile Add the specified file to the list of source files to be com‐
183 piled, but mark it as a library file. All modules contained
184 within that file will be treated as library modules, and only
185 elaborated if they are instantiated by other modules in the de‐
186 sign.
187 -Mpath This is equivalent to -Mall=path. Preserved for backwards com‐
189 patibility.
190 -Mmode=path
192 Write into the file specified by path a list of files that con‐
193 tribute to the compilation of the design. If mode is all or
194 prefix, this includes files that are included by include direc‐
195 tives and files that are automatically loaded by library sup‐
196 port as well as the files explicitly specified by the user. If
197 mode is include, only files that are included by include direc‐
198 tives are listed. If mode is module, only files that are speci‐
199 fied by the user or that are automatically loaded by library
200 support are listed. The output is one file name per line, with
201 no leading or trailing space. If mode is prefix, files that are
202 included by include directives are prefixed by "I " and other
203 files are prefixed by "M ".
204 -mmodule
206 Add this module to the list of VPI modules to be loaded by the
207 simulation. Many modules can be specified, and all will be
208 loaded, in the order specified. The system module is implicit
209 and always included (and loaded last).
210 If the specified name includes at least one directory charac‐
212 ter, it is assumed to be prefixed by the path to the module,
213 otherwise the module is searched for in the paths specified by
214 preceding -L options, and if not found there, in the iverilog
215 base directory.
216 -Npath This is used for debugging the compiler proper. Dump the final
218 netlist form of the design to the specified file. It otherwise
219 does not affect operation of the compiler. The dump happens af‐
220 ter the design is elaborated and optimized.
221 -o filename
223 Place output in the file filename. If no output file name is
224 specified, iverilog uses the default name a.out.
225 -pflag=value
227 Assign a value to a target specific flag. The -p switch may be
228 used as often as necessary to specify all the desired flags.
229 The flags that are used depend on the target that is selected,
230 and are described in target specific documentation. Flags that
231 are not used are ignored.
232 -S Synthesize. Normally, if the target can accept behavioral de‐
234 scriptions the compiler will leave processes in behavioral
235 form. The -S switch causes the compiler to perform synthesis
236 even if it is not necessary for the target. If the target type
237 is a netlist format, the -S switch is unnecessary and has no
238 effect.
239 -s topmodule
241 Specify the top level module to elaborate. Icarus Verilog will
242 by default choose modules that are not instantiated in any
243 other modules, but sometimes that is not sufficient, or instan‐
244 tiates too many modules. If the user specifies one or more root
245 modules with -s flags, then they will be used as root modules
246 instead.
247 -Tmin|typ|max
249 Use this switch to select min, typ or max times from
250 min:typ:max expressions. Normally, the compiler will simply use
251 the typ value from these expressions (printing a warning for
252 the first ten it finds) but this switch will tell the compiler
253 explicitly which value to use. This will suppress the warning
254 that the compiler is making a choice.
255 -ttarget
257 Use this switch to specify the target output format. See the
258 TARGETS section below for a list of valid output formats.
259 -u Treat each source file as a separate compilation unit (as de‐
261 fined in SystemVerilog). If compiling for an IEEE1364 genera‐
262 tion, this will just reset all compiler directives (including
263 macro definitions) before each new file is processed.
264 -v Turn on verbose messages. This will print the command lines
266 that are executed to perform the actual compilation, along with
267 version information from the various components, as well as the
268 version of the product as a whole. You will notice that the
269 command lines include a reference to a key temporary file that
270 passes information to the compiler proper. To keep that file
271 from being deleted at the end of the process, provide a file
272 name of your own in the environment variable IVERILOG_ICONFIG.
273 If the selected target is vvp, the -v switch is appended to the
275 shebang line in the compiler output file, so directly executing
276 the compiler output file will turn on verbose messages in vvp.
277 This extra verbosity can be avoided by using the vvp command to
278 indirectly execute the compiler output file.
279 -V Print the version of the compiler, and exit.
281 -R Print the runtime paths of the compiler, and exit.
283 -Wclass Turn on different classes of warnings. See the WARNING TYPES
285 section below for descriptions of the different warning groups.
286 If multiple -W switches are used, the warning set is the union
287 of all the requested classes.
288 -ylibdir
290 Append the directory to the library module search path. When
291 the compiler finds an undefined module, it looks in these di‐
292 rectories for files with the right name.
293 -Ysuffix
295 Add suffix to the list of accepted file name suffixes used when
296 searching a library for cells. The list defaults to the single
297 entry .v.
298
301 The Icarus Verilog compiler supports module libraries as directories
302 that contain Verilog source files. During elaboration, the compiler
303 notices the instantiation of undefined module types. If the user speci‐
304 fies library search directories, the compiler will search the directory
305 for files with the name of the missing module type. If it finds such a
306 file, it loads it as a Verilog source file, then tries again to elabo‐
307 rate the module.
308 Library module files should contain only a single module, but this is
310 not a requirement. Library modules may reference other modules in the
311 library or in the main design.
312
315 The Icarus Verilog compiler supports a variety of targets, for differ‐
316 ent purposes, and the -t switch is used to select the desired target.
317 null The null target causes no code to be generated. It is useful
320 for checking the syntax of the Verilog source.
321 vvp This is the default. The vvp target generates code for the vvp
323 runtime. The output is a complete program that simulates the
324 design but must be run by the vvp command. The -pfileline=1 op‐
325 tion can be used to add procedural statement debugging opcodes
326 to the generated code. These opcodes are also used to generate
327 file and line information for procedural warning/error mes‐
328 sages. To enable the debug command tracing us the trace command
329 (trace on) from the vvp interactive prompt.
330 fpga This is a synthesis target that supports a variety of fpga de‐
332 vices, mostly by EDIF format output. The Icarus Verilog fpga
333 code generator can generate complete designs or EDIF macros
334 that can in turn be imported into larger designs by other
335 tools. The fpga target implies the synthesis -S flag.
336 vhdl This target produces a VHDL translation of the Verilog netlist.
338 The output is a single file containing VHDL entities corre‐
339 sponding to the modules in the Verilog source code. Note that
340 only a subset of the Verilog language is supported. See the
341 wiki for more information.
342
345 These are the types of warnings that can be selected by the -W switch.
346 All the warning types (other than all) can also be prefixed with no- to
347 turn off that warning. This is most useful after a -Wall argument to
348 suppress isolated warning types.
349 all This enables the anachronisms, implicit, macro-replacement,
352 portbind, select-range, timescale, and sensitivity-entire-array
353 warning categories.
354 anachronisms
357 This enables warnings for use of features that have been depre‐
358 cated or removed in the selected generation of the Verilog lan‐
359 guage.
360 implicit
363 This enables warnings for creation of implicit declarations.
364 For example, if a scalar wire X is used but not declared in the
365 Verilog source, this will print a warning at its first use.
366 macro-redefinition | macro-replacement
369 This enables preprocessor warnings when a macro is being rede‐
370 fined. The first variant prints a warning any time a macro is
371 redefined. The second variant only prints a warning if the
372 macro text changes. Use no-macro-redefinition to turn off all
373 warnings of this type.
374 portbind
377 This enables warnings for ports of module instantiations that
378 are not connected but probably should be. Dangling input ports,
379 for example, will generate a warning.
380 select-range
383 This enables warnings for constant out of bound selects. This
384 includes partial or fully out of bound selects as well as a se‐
385 lect containing a 'bx or 'bz in the index.
386 timescale
389 This enables warnings for inconsistent use of the timescale di‐
390 rective. It detects if some modules have no timescale, or if
391 modules inherit timescale from another file. Both probably mean
392 that timescales are inconsistent, and simulation timing can be
393 confusing and dependent on compilation order.
394 infloop This enables warnings for always statements that may have run‐
397 time infinite loops (has paths with no or zero delay). This
398 class of warnings is not included in -Wall and hence does not
399 have a no- variant. A fatal error message will always be
400 printed when the compiler can determine that there will defi‐
401 nitely be an infinite loop (all paths have no or zero delay).
402 When you suspect an always statement is producing a runtime in‐
404 finite loop use this flag to find the always statements that
405 need to have their logic verified. It is expected that many of
406 the warnings will be false positives, since the code treats the
407 value of all variables and signals as indeterminate.
408 sensitivity-entire-vector
411 This enables warnings for when a part select within an "always
412 @*" statement results in the entire vector being added to the
413 implicit sensitivity list. Although this behaviour is pre‐
414 scribed by the IEEE standard, it is not what might be expected
415 and can have performance implications if the vector is large.
416 sensitivity-entire-array
419 This enables warnings for when a word select within an "always
420 @*" statement results in the entire array being added to the
421 implicit sensitivity list. Although this behaviour is pre‐
422 scribed by the IEEE standard, it is not what might be expected
423 and can have performance implications if the array is large.
424
427 If the source file name has a .vpi or .vpl suffix, then it is taken to
428 be a VPI module. VPI modules supplied by the user are scanned to deter‐
429 mine the return types of any system functions they provide. This is
430 necessary because the compiler needs this information to elaborate ex‐
431 pressions that contain these system functions. The module path/name is
432 passed on to the target to allow the VPI module to be automatically
433 loaded at the start of simulation.
434 VPI modules may also be supplied using the -L and -m options.
436
439 If the source file name has a .sft suffix, then it is taken to be a
440 system function table file. A system function table file is the old
441 method used to describe to the compiler the return types for system
442 functions. Users are encouraged to switch to the new method of simply
443 supplying the VPI module.
444 The format of the table is ASCII, one function per line. Empty lines
446 are ignored, and lines that start with the '#' character are comment
447 lines. Each non-comment line starts with the function name, then the
448 vpi type (i.e. vpiSysFuncReal). The following types are supported:
449 vpiSysFuncReal
452 The function returns a real/realtime value.
453 vpiSysFuncInt
456 The function returns an integer.
457 vpiSysFuncSized <wid> <signed|unsigned>
460 The function returns a vector with the given width, and is
461 signed or unsigned according to the flag.
462 vpiSysFuncString
465 The function returns a string. This is an Icarus-specific ex‐
466 tension, not available in the VPI standard.
467
470 The command file allows the user to place source file names and certain
471 command line switches into a text file instead of on a long command
472 line. Command files can include C or C++ style comments, as well as #
473 comments, if the # starts the line.
474 file name
477 A simple file name or file path is taken to be the name of a
478 Verilog source file. The path starts with the first non-white-
479 space character. Variables are substituted in file names.
480 -c cmdfile -f cmdfile
483 A -c or -f token prefixes a command file, exactly like it does
484 on the command line. The cmdfile may be on the same line or the
485 next non-comment line.
486 -l file -v file
489 A -l token prefixes a library file in the command file, exactly
490 like it does on the command line. The parameter to the -l flag
491 may be on the same line or the next non-comment line. -v is an
492 alias for -l, provided for compatibility with other simulators.
493 Variables in the file are substituted.
495 -y libdir
498 A -y token prefixes a library directory in the command file,
499 exactly like it does on the command line. The parameter to the
500 -y flag may be on the same line or the next non-comment line.
501 Variables in the libdir are substituted.
503 +incdir+includedir
506 The +incdir+ token in command files gives directories to search
507 for include files in much the same way that -I flags work on
508 the command line. The difference is that multiple +includedir
509 directories are valid parameters to a single +incdir+ token,
510 although you may also have multiple +incdir+ lines.
511 Variables in the includedir are substituted.
513 +libext+ext
516 The +libext token in command files lists file extensions to try
517 when looking for a library file. This is useful in conjunction
518 with -y flags to list suffixes to try in each directory before
519 moving on to the next library directory.
520 +libdir+dir
523 This is another way to specify library directories. See the -y
524 flag.
525 +libdir-nocase+dir
528 This is like the +libdir statement, but file names inside the
529 directories declared here are case insensitive. The missing
530 module name in a lookup need not match the file name case, as
531 long as the letters are correct. For example, "foo" matches
532 "Foo.v" but not "bar.v".
533 +define+NAME=value
536 The +define+ token is the same as the -D option on the command
537 line. The value part of the token is optional.
538 +parameter+NAME=value
541 The +parameter+ token is the same as the -P option on the com‐
542 mand line.
543 +timescale+value
546 The +timescale+ token is used to set the default timescale for
547 the simulation. This is the time units and precision before any
548 `timescale directive or after a `resetall directive. The de‐
549 fault is 1s/1s.
550 +toupper-filename
553 This token causes file names after this in the command file to
554 be translated to uppercase. This helps with situations where a
555 directory has passed through a DOS machine, and in the process
556 the file names become munged.
557 +tolower-filename
560 This is similar to the +toupper-filename hack described above.
561 +integer-width+value
564 This allows the programmer to select the width for integer
565 variables in the Verilog source. The default is 32, the value
566 can be any desired integer value.
567 +width-cap+value
570 This allows the programmer to select the width cap for unsized
571 expressions. If the calculated width for an unsized expression
572 exceeds this value, the compiler will issue a warning and limit
573 the expression width to this value.
574
577 In certain cases, iverilog supports variables in command files. These
578 are strings of the form "$(varname)" or "${varname}", where varname is
579 the name of the environment variable to read. The entire string is re‐
580 placed with the contents of that variable. Variables are only substi‐
581 tuted in contexts that explicitly support them, including file and di‐
582 rectory strings.
583 Variable values come from the operating system environment, and not
585 from preprocessor defines elsewhere in the file or the command line.
586
589 The following macros are predefined by the compiler:
590 __ICARUS__ = 1
592 This is always defined when compiling with Icarus Verilog.
593 __ICARUS_SYNTH__ = 1
596 This is defined when synthesis is enabled.
597 __VAMS_ENABLE__ = 1
600 This is defined when Verilog-AMS is enabled.
601
604 iverilog also accepts some environment variables that control its be‐
605 havior. These can be used to make semi-permanent changes.
606 IVERILOG_ICONFIG=file-name
609 This sets the name used for the temporary file that passes pa‐
610 rameters to the compiler proper, and prevents that file being
611 deleted after the compiler has exited.
612 IVERILOG_VPI_MODULE_PATH=/some/path:/some/other/path
615 This adds additional components to the VPI module search path.
616 Paths specified in this way are searched after paths specified
617 with -L, but before the default search path. Multiple paths can
618 be separated with colons (semicolons if using Windows).
619
622 These examples assume that you have a Verilog source file called
623 hello.v in the current directory
624 To compile hello.v to an executable file called a.out:
626 iverilog hello.v
628 To compile hello.v to an executable file called hello:
630 iverilog -o hello hello.v
632 To compile and run explicitly using the vvp runtime:
634 iverilog -ohello.vvp -tvvp hello.v
636
639 Steve Williams (steve@icarus.com)
640
643 vvp(1), <http://iverilog.icarus.com/>
644 Tips on using, debugging, and developing the compiler can be found at
646 <http://iverilog.wikia.com/>
647
650 Copyright © 2002-2021 Stephen Williams
651 This document can be freely redistributed according to the terms of the
653 GNU General Public License version 2.0
654 Jan 14th, 2021 iverilog(1)