1iverilog(1) Version 10.3 (stable) iverilog(1)
2
6 iverilog - Icarus Verilog compiler
7
10 iverilog [-ESVv] [-Bpath] [-ccmdfile|-fcmdfile] [-Dmacro[=defn]] [-Ppa‐
11 rameter=value] [-pflag=value] [-dname] [-g1995|-g2001|-g2005|-g2005-sv
12 |-g2009|-g2012|-g<feature>] [-Iincludedir] [-mmodule] [-M[mode=]file]
13 [-Nfile] [-ooutputfilename] [-stopmodule] [-ttype] [-Tmin/typ/max]
14 [-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
51 allows the user to override at compile time (defparam) a param‐
52 eter 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
64 example, to preprocess Verilog source for use by other compil‐
65 ers.
66 -g1995|-g2001|-g2001-noconfig|-g2005|-g2005-sv|-g2009|-g2012
68 Select the Verilog language generation to support in the com‐
69 piler. This selects between IEEE1364-1995, IEEE1364-2001,
70 IEEE1364-2005, IEEE1800-2005, IEEE1800-2009, or IEEE1800-2012.
71 Icarus Verilog currently defaults to the IEEE1364-2005 genera‐
72 tion of the language. This flag is used to restrict the lan‐
73 guage to a set of keywords/features, this allows simulation of
74 older Verilog code that may use newer keywords and for compati‐
75 bility with other tools. Much of the IEEE1800 generations func‐
76 tionality is not currently supported. The IEEE1800 generations
77 do parse all the keywords, so they can be used to verify that
78 IEEE1364 compliant Verilog code does not use any of the new
79 IEEE1800 keywords.
80 -gverilog-ams|-gno-verilog-ams
82 Enable or disable (default) support for Verilog-AMS. Very lit‐
83 tle Verilog-AMS specific functionality is currently supported.
84 -gspecify|-gno-specify
86 Enable or disable (default) specify block support. When
87 enabled, specify block code is elaborated. When disabled, spec‐
88 ify blocks are parsed but ignored. Specify blocks are commonly
89 not needed for RTL simulation, and in fact can hurt performance
90 of the simulation. However, disabling specify blocks reduces
91 accuracy of full-timing simulations.
92 -gstd-include|-gno-std-include
94 Enable (default) or disable the search of a standard installa‐
95 tion include directory after all other explicit include direc‐
96 tories. This standard include directory is a convenient place
97 to install standard header files that a Verilog program may
98 include.
99 -grelative-include|-gno-relative-include
101 Enable or disable (default) adding the local files directory to
102 the beginning of the include file search path. This allows
103 files to be included relative to the current file not the more
104 common files are only found in the working directory or in the
105 specified include file search path.
106 -gxtypes|-gno-xtypes
108 Enable (default) or disable support for extended types.
109 Enabling extended types allows for new types that are supported
110 by Icarus Verilog as extensions beyond the baseline Verilog. It
111 may be necessary to disable extended types if compiling code
112 that clashes with the few new keywords used to implement the
113 type system.
114 -gio-range-error|-gno-io-range-error
116 The standards requires that a vectored port have matching
117 ranges for its port declaration as well as any net/register
118 declaration. It was common practice in the past to only specify
119 the range for the net/register declaration and some tools still
120 allow this. By default any mismatch is reported as a error.
121 Using -gno-io-range-error will produce a warning instead of a
122 fatal error for the case of a vectored net/register and a
123 scalar port declaration.
124 -gstrict-ca-eval|-gno-strict-ca-eval
126 The standard requires that if any input to a continuous assign‐
127 ment expression changes value, the entire expression is re-
128 evaluated. By default, parts of the expression that do not
129 depend on the changed input value(s) are not re-evaluated. If
130 an expression contains a call to a function that doesn't depend
131 solely on its input values or that has side effects, the
132 resulting behavior will differ from that required by the stan‐
133 dard. Using -gstrict-ca-eval will force standard compliant
134 behavior (with some loss in performance).
135 -gstrict-expr-width|-gno-strict-expr-width
137 Enable or disable (default) strict compliance with the standard
138 rules for determining expression bit lengths. When disabled,
139 the RHS of a parameter assignment is evaluated as a lossless
140 expression, as is any expression containing an unsized constant
141 number, and unsized constant numbers are not truncated to inte‐
142 ger width.
143 -gshared-loop-index|-gno-shared-loop-index
145 Enable or disable (default) the exclusion of for-loop control
146 variables from implicit event_expression lists. When enabled,
147 if a for-loop control variable (loop index) is only used inside
148 the for-loop statement, the compiler will not include it in an
149 implicit event_expression list it calculates for that statement
150 or any enclosing statement. This allows the same control vari‐
151 able to be used in multiple processes without risk of entering
152 an infinite loop caused by each process triggering all other
153 processes that use the same varaible. For strict compliance
154 with the standards, this behaviour should be disabled.
155 -Iincludedir
157 Append directory includedir to list of directories searched for
158 Verilog include files. The -I switch may be used many times to
159 specify several directories to search, the directories are
160 searched in the order they appear on the command line.
161 -lfile Add the specified file to the list of source files to be com‐
163 piled, but mark it as a library file. All modules contained
164 within that file will be treated as library modules, and only
165 elaborated if they are instantiated by other modules in the
166 design.
167 -Mpath This is equivalent to -Mall=path. Preserved for backwards com‐
169 patibility.
170 -Mmode=path
172 Write into the file specified by path a list of files that con‐
173 tribute to the compilation of the design. If mode is all or
174 prefix, this includes files that are included by include direc‐
175 tives and files that are automatically loaded by library sup‐
176 port as well as the files explicitly specified by the user. If
177 mode is include, only files that are included by include direc‐
178 tives are listed. If mode is module, only files that are speci‐
179 fied by the user or that are automatically loaded by library
180 support are listed. The output is one file name per line, with
181 no leading or trailing space. If mode is prefix, files that are
182 included by include directives are prefixed by "I " and other
183 files are prefixed by "M ".
184 -mmodule
186 Add this module to the list of VPI modules to be loaded by the
187 simulation. Many modules can be specified, and all will be
188 loaded, in the order specified. The system module is implicit
189 and always included. If a System Function Table file (<mod‐
190 ule>.sft) exists for the module it will be loaded automati‐
191 cally.
192 -Npath This is used for debugging the compiler proper. Dump the final
194 netlist form of the design to the specified file. It otherwise
195 does not affect operation of the compiler. The dump happens
196 after the design is elaborated and optimized.
197 -o filename
199 Place output in the file filename. If no output file name is
200 specified, iverilog uses the default name a.out.
201 -pflag=value
203 Assign a value to a target specific flag. The -p switch may be
204 used as often as necessary to specify all the desired flags.
205 The flags that are used depend on the target that is selected,
206 and are described in target specific documentation. Flags that
207 are not used are ignored.
208 -S Synthesize. Normally, if the target can accept behavioral
210 descriptions the compiler will leave processes in behavioral
211 form. The -S switch causes the compiler to perform synthesis
212 even if it is not necessary for the target. If the target type
213 is a netlist format, the -S switch is unnecessary and has no
214 effect.
215 -s topmodule
217 Specify the top level module to elaborate. Icarus Verilog will
218 by default choose modules that are not instantiated in any
219 other modules, but sometimes that is not sufficient, or instan‐
220 tiates too many modules. If the user specifies one or more root
221 modules with -s flags, then they will be used as root modules
222 instead.
223 -Tmin|typ|max
225 Use this switch to select min, typ or max times from
226 min:typ:max expressions. Normally, the compiler will simply use
227 the typ value from these expressions (printing a warning for
228 the first ten it finds) but this switch will tell the compiler
229 explicitly which value to use. This will suppress the warning
230 that the compiler is making a choice.
231 -ttarget
233 Use this switch to specify the target output format. See the
234 TARGETS section below for a list of valid output formats.
235 -v Turn on verbose messages. This will print the command lines
237 that are executed to perform the actual compilation, along with
238 version information from the various components, as well as the
239 version of the product as a whole. You will notice that the
240 command lines include a reference to a key temporary file that
241 passes information to the compiler proper. To keep that file
242 from being deleted at the end of the process, provide a file
243 name of your own in the environment variable IVERILOG_ICONFIG.
244 If the selected target is vvp, the -v switch is appended to the
246 shebang line in the compiler output file, so directly executing
247 the compiler output file will turn on verbose messages in vvp.
248 This extra verbosity can be avoided by using the vvp command to
249 indirectly execute the compiler output file.
250 -V Print the version of the compiler, and exit.
252 -Wclass Turn on different classes of warnings. See the WARNING TYPES
254 section below for descriptions of the different warning groups.
255 If multiple -W switches are used, the warning set is the union
256 of all the requested classes.
257 -ylibdir
259 Append the directory to the library module search path. When
260 the compiler finds an undefined module, it looks in these
261 directories for files with the right name.
262 -Ysuffix
264 Add suffix to the list of accepted file name suffixes used when
265 searching a library for cells. The list defaults to the single
266 entry .v.
267
270 The Icarus Verilog compiler supports module libraries as directories
271 that contain Verilog source files. During elaboration, the compiler
272 notices the instantiation of undefined module types. If the user speci‐
273 fies library search directories, the compiler will search the directory
274 for files with the name of the missing module type. If it finds such a
275 file, it loads it as a Verilog source file, then tries again to elabo‐
276 rate the module.
277 Library module files should contain only a single module, but this is
279 not a requirement. Library modules may reference other modules in the
280 library or in the main design.
281
284 The Icarus Verilog compiler supports a variety of targets, for differ‐
285 ent purposes, and the -t switch is used to select the desired target.
286 null The null target causes no code to be generated. It is useful
289 for checking the syntax of the Verilog source.
290 vvp This is the default. The vvp target generates code for the vvp
292 runtime. The output is a complete program that simulates the
293 design but must be run by the vvp command. The -pfileline=1
294 option can be used to add procedural statement debugging
295 opcodes to the generated code.
296 fpga This is a synthesis target that supports a variety of fpga
298 devices, mostly by EDIF format output. The Icarus Verilog fpga
299 code generator can generate complete designs or EDIF macros
300 that can in turn be imported into larger designs by other
301 tools. The fpga target implies the synthesis -S flag.
302 vhdl This target produces a VHDL translation of the Verilog netlist.
304 The output is a single file containing VHDL entities corre‐
305 sponding to the modules in the Verilog source code. Note that
306 only a subset of the Verilog language is supported. See the
307 wiki for more information.
308
311 These are the types of warnings that can be selected by the -W switch.
312 All the warning types (other than all) can also be prefixed with no- to
313 turn off that warning. This is most useful after a -Wall argument to
314 suppress isolated warning types.
315 all This enables the anachronisms, implicit, portbind,
318 select-range, timescale, and sensitivity-entire-array warning
319 categories.
320 anachronisms
323 This enables warnings for use of features that have been depre‐
324 cated or removed in the selected generation of the Verilog lan‐
325 guage.
326 implicit
329 This enables warnings for creation of implicit declarations.
330 For example, if a scalar wire X is used but not declared in the
331 Verilog source, this will print a warning at its first use.
332 portbind
335 This enables warnings for ports of module instantiations that
336 are not connected but probably should be. Dangling input ports,
337 for example, will generate a warning.
338 select-range
341 This enables warnings for constant out of bound selects. This
342 includes partial or fully out of bound selects as well as a
343 select containing a 'bx or 'bz in the index.
344 timescale
347 This enables warnings for inconsistent use of the timescale
348 directive. It detects if some modules have no timescale, or if
349 modules inherit timescale from another file. Both probably mean
350 that timescales are inconsistent, and simulation timing can be
351 confusing and dependent on compilation order.
352 infloop This enables warnings for always statements that may have run‐
355 time infinite loops (has paths with no or zero delay). This
356 class of warnings is not included in -Wall and hence does not
357 have a no- variant. A fatal error message will always be
358 printed when the compiler can determine that there will defi‐
359 nitely be an infinite loop (all paths have no or zero delay).
360 When you suspect an always statement is producing a runtime
362 infinite loop use this flag to find the always statements that
363 need to have their logic verified. It is expected that many of
364 the warnings will be false positives, since the code treats the
365 value of all variables and signals as indeterminate.
366 sensitivity-entire-vector
369 This enables warnings for when a part select within an "always
370 @*" statement results in the entire vector being added to the
371 implicit sensitivity list. Although this behaviour is pre‐
372 scribed by the IEEE standard, it is not what might be expected
373 and can have performance implications if the vector is large.
374 sensitivity-entire-array
377 This enables warnings for when a word select within an "always
378 @*" statement results in the entire array being added to the
379 implicit sensitivity list. Although this behaviour is pre‐
380 scribed by the IEEE standard, it is not what might be expected
381 and can have performance implications if the array is large.
382
385 If the source file name as a .sft suffix, then it is taken to be a sys‐
386 tem function table file. A System function table file is used to
387 describe to the compiler the return types for system functions. This is
388 necessary because the compiler needs this information to elaborate
389 expressions that contain these system functions, but cannot run the
390 sizetf functions since it has no run-time.
391 The format of the table is ASCII, one function per line. Empty lines
393 are ignored, and lines that start with the '#' character are comment
394 lines. Each non-comment line starts with the function name, then the
395 vpi type (i.e. vpiSysFuncReal). The following types are supported:
396 vpiSysFuncReal
399 The function returns a real/realtime value.
400 vpiSysFuncInt
403 The function returns an integer.
404 vpiSysFuncSized <wid> <signed|unsigned>
407 The function returns a vector with the given width, and is
408 signed or unsigned according to the flag.
409
412 The command file allows the user to place source file names and certain
413 command line switches into a text file instead of on a long command
414 line. Command files can include C or C++ style comments, as well as #
415 comments, if the # starts the line.
416 file name
419 A simple file name or file path is taken to be the name of a
420 Verilog source file. The path starts with the first non-white-
421 space character. Variables are substituted in file names.
422 -c cmdfile -f cmdfile
425 A -c or -f token prefixes a command file, exactly like it does
426 on the command line. The cmdfile may be on the same line or the
427 next non-comment line.
428 -l file -v file
431 A -l token prefixes a library file in the command file, exactly
432 like it does on the command line. The parameter to the -l flag
433 may be on the same line or the next non-comment line. -v is an
434 alias for -l, provided for compatibility with other simulators.
435 Variables in the file are substituted.
437 -y libdir
440 A -y token prefixes a library directory in the command file,
441 exactly like it does on the command line. The parameter to the
442 -y flag may be on the same line or the next non-comment line.
443 Variables in the libdir are substituted.
445 +incdir+includedir
448 The +incdir+ token in command files gives directories to search
449 for include files in much the same way that -I flags work on
450 the command line. The difference is that multiple +includedir
451 directories are valid parameters to a single +incdir+ token,
452 although you may also have multiple +incdir+ lines.
453 Variables in the includedir are substituted.
455 +libext+ext
458 The +libext token in command files fives file extensions to try
459 when looking for a library file. This is useful in conjunction
460 with -y flags to list suffixes to try in each directory before
461 moving on to the next library directory.
462 +libdir+dir
465 This is another way to specify library directories. See the -y
466 flag.
467 +libdir-nocase+dir
470 This is like the +libdir statement, but file names inside the
471 directories declared here are case insensitive. The missing
472 module name in a lookup need not match the file name case, as
473 long as the letters are correct. For example, "foo" matches
474 "Foo.v" but not "bar.v".
475 +define+NAME=value
478 The +define+ token is the same as the -D option on the command
479 line. The value part of the token is optional.
480 +parameter+NAME=value
483 The +parameter+ token is the same as the -P option on the com‐
484 mand line.
485 +timescale+value
488 The +timescale+ token is used to set the default timescale for
489 the simulation. This is the time units and precision before any
490 `timescale directive or after a `resetall directive. The
491 default is 1s/1s.
492 +toupper-filename
495 This token causes file names after this in the command file to
496 be translated to uppercase. This helps with situations where a
497 directory has passed through a DOS machine, and in the process
498 the file names become munged.
499 +tolower-filename
502 This is similar to the +toupper-filename hack described above.
503 +integer-width+value
506 This allows the programmer to select the width for integer
507 variables in the Verilog source. The default is 32, the value
508 can be any desired integer value.
509 +width-cap+value
512 This allows the programmer to select the width cap for unsized
513 expressions. If the calculated width for an unsized expression
514 exceeds this value, the compiler will issue a warning and limit
515 the expression width to this value.
516
519 In certain cases, iverilog supports variables in command files. These
520 are strings of the form "$(varname)" or "${varname}", where varname is
521 the name of the environment variable to read. The entire string is
522 replaced with the contents of that variable. Variables are only substi‐
523 tuted in contexts that explicitly support them, including file and
524 directory strings.
525 Variable values come from the operating system environment, and not
527 from preprocessor defines elsewhere in the file or the command line.
528
531 The following macros are predefined by the compiler:
532 __ICARUS__ = 1
534 This is always defined when compiling with Icarus Verilog.
535 __VAMS_ENABLE__ = 1
538 This is defined if Verilog-AMS is enabled.
539
542 These examples assume that you have a Verilog source file called
543 hello.v in the current directory
544 To compile hello.v to an executable file called a.out:
546 iverilog hello.v
548 To compile hello.v to an executable file called hello:
550 iverilog -o hello hello.v
552 To compile and run explicitly using the vvp runtime:
554 iverilog -ohello.vvp -tvvp hello.v
556
559 Steve Williams (steve@icarus.com)
560
563 vvp(1), <http://iverilog.icarus.com/>
564 Tips on using, debugging, and developing the compiler can be found at
566 <http://iverilog.wikia.com/>
567
570 Copyright © 2002-2016 Stephen Williams
571 This document can be freely redistributed according to the terms of the
573 GNU General Public License version 2.0
574 Oct 2nd, 2016 iverilog(1)