1iverilog(1) Version 0.9.4 iverilog(1)
2
6 iverilog - Icarus Verilog compiler
7
10 iverilog [-ESVv] [-Bpath] [-ccmdfile|-fcmdfile] [-Dmacro[=defn]]
11 [-pflag=value] [-dname] [-g1995|-g2001|-g2005|-g<feature>] [-Iin‐
12 cludedir] [-mmodule] [-Mfile] [-Nfile] [-ooutputfilename] [-stopmodule]
13 [-ttype] [-Tmin/typ/max] [-Wclass] [-ypath] sourcefile
14
17 iverilog is a compiler that translates Verilog source code into exe‐
18 cutable programs for simulation, or other netlist formats for further
19 processing. The currently supported targets are vvp for simulation, and
20 fpga for synthesis. Other target types are added as code generators are
21 implemented.
22
25 iverilog accepts the following options:
26 -Bbase The iverilog program uses external programs and configuration
28 files to preprocess and compile the Verilog source. Normally,
29 the path used to locate these tools is built into the iverilog
30 program. However, the -B switch allows the user to select a
31 different set of programs. The path given is used to locate
32 ivlpp, ivl, code generators and the VPI modules.
33 -cfile -ffile
35 These flags specifies an input file that contains a list of
36 Verilog source files. This is similar to the command file of
37 other Verilog simulators, in that it is a file that contains
38 the file names instead of taking them on the command line. See
39 Command Files below.
40 -Dmacro Defines macro macro with the string `1' as its definition. This
42 form is normally only used to trigger ifdef conditionals in the
43 Verilog source.
44 -Dmacro=defn
46 Defines macro macro as defn.
47 -dname Activate a class of compiler debugging messages. The -d switch
49 may be used as often as necessary to activate all the desired
50 messages. Supported names are scopes, eval_tree, elaborate,
51 and synth2; any other names are ignored.
52 -E Preprocess the Verilog source, but do not compile it. The out‐
54 put file is the Verilog input, but with file inclusions and
55 macro references expanded and removed. This is useful, for
56 example, to preprocess Verilog source for use by other compil‐
57 ers.
58 -g1995|-g2001|-g2001-noconfig|-g2005
60 Select the Verilog language generation to support in the com‐
61 piler. This selects between IEEE1364-1995, IEEE1364-2001, or
62 IEEE1364-2005. Normally, Icarus Verilog defaults to the latest
63 known generation of the language. This flag is most useful to
64 restrict the language to a set supported by tools of specific
65 generations, for compatibility with other tools.
66 -gverilog-ams|-gno-verilog-ams
68 Enable or disable (default) support for Verilog-AMS. Very lit‐
69 tle Verilog-AMS specific functionality is currently supported.
70 -gspecify|-gno-specify
72 Enable or disable (default) specify block support. When
73 enabled, specify block code is elaborated. When disabled, spec‐
74 ify blocks are parsed but ignored. Specify blocks are commonly
75 not needed for RTL simulation, and in fact can hurt performance
76 of the simulation. However, disabling specify blocks reduces
77 accuracy of full-timing simulations.
78 -gstd-include|-gno-std-include
80 Enable (default) or disable the search of a standard installa‐
81 tion include directory after all other explicit include direc‐
82 tories. This standard include directory is a convenient place
83 to install standard header files that a Verilog program may
84 include.
85 -grelative-include|-gno-relative-include
87 Enable or disable (default) adding the local files directory to
88 the beginning of the include file search path. This allows
89 files to be included relative to the current file not the more
90 common files are only found in the working directory or in the
91 specified include file search path.
92 -gxtypes|-gno-xtypes
94 Enable (default) or disable support for extended types.
95 Enabling extended types allows for new types that are supported
96 by Icarus Verilog as extensions beyond the baseline Verilog. It
97 may be necessary to disable extended types if compiling code
98 that clashes with the few new keywords used to implement the
99 type system.
100 -gio-range-error|-gno-io-range-error
102 The standards requires that a vectored port have matching
103 ranges for its port declaration as well as any net/register
104 declaration. It was common practice in the past to only specify
105 the range for the net/register declaration and some tools still
106 allow this. By default any mismatch is reported as a error.
107 Using -gno-io-range-error will produce a warning instead of a
108 fatal error for the case of a vectored net/register and a
109 scalar port declaration.
110 -gstrict-ca-eval|-gno-strict-ca-eval
112 The standard requires that if any input to a continuous assign‐
113 ment expression changes value, the entire expression is re-
114 evaluated. By default, parts of the expression that do not
115 depend on the changed input value(s) are not re-evaluated. If
116 an expression contains a call to a function that doesn't depend
117 solely on its input values or that has side effects, the
118 resulting behavior will differ from that required by the stan‐
119 dard. Using -gstrict-ca-eval will force standard compliant
120 behavior (with some loss in performance).
121 -Iincludedir
123 Append directory includedir to list of directories searched for
124 Verilog include files. The -I switch may be used many times to
125 specify several directories to search, the directories are
126 searched in the order they appear on the command line.
127 -Mpath Write into the file specified by path a list of files that con‐
129 tribute to the compilation of the design. This includes files
130 that are included by include directives and files that are
131 automatically loaded by library support. The output is one file
132 name per line, with no leading or trailing space.
133 -mmodule
135 Add this module to the list of VPI modules to be loaded by the
136 simulation. Many modules can be specified, and all will be
137 loaded, in the order specified. The system module is implicit
138 and always included. If a System Function Table file (<mod‐
139 ule>.sft) exists for the module it will be loaded automati‐
140 cally.
141 -Npath This is used for debugging the compiler proper. Dump the final
143 netlist form of the design to the specified file. It otherwise
144 does not affect operation of the compiler. The dump happens
145 after the design is elaborated and optimized.
146 -o filename
148 Place output in the file filename. If no output file name is
149 specified, iverilog uses the default name a.out.
150 -pflag=value
152 Assign a value to a target specific flag. The -p switch may be
153 used as often as necessary to specify all the desired flags.
154 The flags that are used depend on the target that is selected,
155 and are described in target specific documentation. Flags that
156 are not used are ignored.
157 -S Synthesize. Normally, if the target can accept behavioral
159 descriptions the compiler will leave processes in behavioral
160 form. The -S switch causes the compiler to perform synthesis
161 even if it is not necessary for the target. If the target type
162 is a netlist format, the -S switch is unnecessary and has no
163 effect.
164 -s topmodule
166 Specify the top level module to elaborate. Icarus Verilog will
167 by default choose modules that are not instantiated in any
168 other modules, but sometimes that is not sufficient, or instan‐
169 tiates too many modules. If the user specifies one or more root
170 modules with -s flags, then they will be used as root modules
171 instead.
172 -Tmin|typ|max
174 Use this switch to select min, typ or max times from
175 min:typ:max expressions. Normally, the compiler will simply use
176 the typ value from these expressions (printing a warning for
177 the first ten it finds) but this switch will tell the compiler
178 explicitly which value to use. This will suppress the warning
179 that the compiler is making a choice.
180 -ttarget
182 Use this switch to specify the target output format. See the
183 TARGETS section below for a list of valid output formats.
184 -v Turn on verbose messages. This will print the command lines
186 that are executed to perform the actual compilation, along with
187 version information from the various components, as well as the
188 version of the product as a whole. You will notice that the
189 command lines include a reference to a key temporary file that
190 passes information to the compiler proper. To keep that file
191 from being deleted at the end of the process, provide a file
192 name of your own in the environment variable IVERILOG_ICONFIG.
193 -V Print the version of the compiler, and exit.
195 -Wclass Turn on different classes of warnings. See the WARNING TYPES
197 section below for descriptions of the different warning groups.
198 If multiple -W switches are used, the warning set is the union
199 of all the requested classes.
200 -ylibdir
202 Append the directory to the library module search path. When
203 the compiler finds an undefined module, it looks in these
204 directories for files with the right name.
205 -Ysuffix
207 Add suffix to the list of accepted file name suffixes used when
208 searching a library for cells. The list defaults to the single
209 entry .v.
210
213 The Icarus Verilog compiler supports module libraries as directories
214 that contain Verilog source files. During elaboration, the compiler
215 notices the instantiation of undefined module types. If the user speci‐
216 fies library search directories, the compiler will search the directory
217 for files with the name of the missing module type. If it finds such a
218 file, it loads it as a Verilog source file, they tries again to elabo‐
219 rate the module.
220 Library module files should contain only a single module, but this is
222 not a requirement. Library modules may reference other modules in the
223 library or in the main design.
224
227 The Icarus Verilog compiler supports a variety of targets, for differ‐
228 ent purposes, and the -t switch is used to select the desired target.
229 null The null target causes no code to be generated. It is useful
232 for checking the syntax of the Verilog source.
233 vvp This is the default. The vvp target generates code for the vvp
235 runtime. The output is a complete program that simulates the
236 design but must be run by the vvp command.
237 fpga This is a synthesis target that supports a variety of fpga
239 devices, mostly by EDIF format output. The Icarus Verilog fpga
240 code generator can generate complete designs or EDIF macros
241 that can in turn be imported into larger designs by other
242 tools. The fpga target implies the synthesis -S flag.
243 vhdl This target produces a VHDL translation of the Verilog netlist.
245 The output is a single file containing VHDL entities corre‐
246 sponding to the modules in the Verilog source code. Note that
247 only a subset of the Verilog language is supported. See the
248 wiki for more information.
249
252 These are the types of warnings that can be selected by the -W switch.
253 All the warning types (other than all) can also be prefixed with no- to
254 turn off that warning. This is most useful after a -Wall argument to
255 suppress isolated warning types.
256 all This enables the implicit, portbind, select-range, timescale,
259 and sensitivity-entire-array warning categories.
260 implicit
263 This enables warnings for creation of implicit declarations.
264 For example, if a scalar wire X is used but not declared in the
265 Verilog source, this will print a warning at its first use.
266 portbind
269 This enables warnings for ports of module instantiations that
270 are not connected but probably should be. Dangling input ports,
271 for example, will generate a warning.
272 select-range
275 This enables warnings for constant out of bound selects. This
276 includes partial or fully out of bound selects as well as a
277 select containing a 'bx or 'bz in the index.
278 timescale
281 This enables warnings for inconsistent use of the timescale
282 directive. It detects if some modules have no timescale, or if
283 modules inherit timescale from another file. Both probably mean
284 that timescales are inconsistent, and simulation timing can be
285 confusing and dependent on compilation order.
286 infloop This enables warnings for always statements that may have run‐
289 time infinite loops (has paths with no or zero delay). This
290 class of warnings is not included in -Wall and hence does not
291 have a no- variant. A fatal error message will always be
292 printed when the compiler can determine that there will defi‐
293 nitely be an infinite loop (all paths have no or zero delay).
294 When you suspect an always statement is producing a runtime
296 infinite loop use this flag to find the always statements that
297 need to have their logic verified. It is expected that many of
298 the warnings will be false positives, since the code treats the
299 value of all variables and signals as indeterminate.
300 sensitivity-entire-vector
303 This enables warnings for when a part select within an "always
304 @*" statement results in the entire vector being added to the
305 implicit sensitivity list. Although this behaviour is pre‐
306 scribed by the IEEE standard, it is not what might be expected
307 and can have performance implications if the vector is large.
308 sensitivity-entire-array
311 This enables warnings for when a word select within an "always
312 @*" statement results in the entire array being added to the
313 implicit sensitivity list. Although this behaviour is pre‐
314 scribed by the IEEE standard, it is not what might be expected
315 and can have performance implications if the array is large.
316
319 If the source file name as a .sft suffix, then it is taken to be a sys‐
320 tem function table file. A System function table file is used to
321 describe to the compiler the return types for system functions. This is
322 necessary because the compiler needs this information to elaborate
323 expressions that contain these system functions, but cannot run the
324 sizetf functions since it has no run-time.
325 The format of the table is ASCII, one function per line. Empty lines
327 are ignored, and lines that start with the '#' character are comment
328 lines. Each non-comment line starts with the function name, then the
329 vpi type (i.e. vpiSysFuncReal). The following types are supported:
330 vpiSysFuncReal
333 The function returns a real/realtime value.
334 vpiSysFuncInt
337 The function returns an integer.
338 vpiSysFuncSized <wid> <signed|unsigned>
341 The function returns a vector with the given width, and is
342 signed or unsigned according to the flag.
343
346 The command file allows the user to place source file names and certain
347 command line switches into a text file instead of on a long command
348 line. Command files can include C or C++ style comments, as well as #
349 comments, if the # starts the line.
350 file name
353 A simple file name or file path is taken to be the name of a
354 Verilog source file. The path starts with the first non-white-
355 space character. Variables are substituted in file names.
356 -c cmdfile -f cmdfile
359 A -c or -f token prefixes a command file, exactly like it does
360 on the command line. The cmdfile may be on the same line or the
361 next non-comment line.
362 -y libdir
365 A -y token prefixes a library directory in the command file,
366 exactly like it does on the command line. The parameter to the
367 -y flag may be on the same line or the next non-comment line.
368 Variables in the libdir are substituted.
370 +incdir+includedir
373 The +incdir+ token in command files gives directories to search
374 for include files in much the same way that -I flags work on
375 the command line. The difference is that multiple +includedir
376 directories are valid parameters to a single +incdir+ token,
377 although you may also have multiple +incdir+ lines.
378 Variables in the includedir are substituted.
380 +libext+ext
383 The +libext token in command files fives file extensions to try
384 when looking for a library file. This is useful in conjunction
385 with -y flags to list suffixes to try in each directory before
386 moving on to the next library directory.
387 +libdir+dir
390 This is another way to specify library directories. See the -y
391 flag.
392 +libdir-nocase+dir
395 This is like the +libdir statement, but file names inside the
396 directories declared here are case insensitive. The missing
397 module name in a lookup need not match the file name case, as
398 long as the letters are correct. For example, "foo" matches
399 "Foo.v" but not "bar.v".
400 +define+NAME=value
403 The +define+ token is the same as the -D option on the command
404 line. The value part of the token is optional.
405 +timescale+value
408 The +timescale+ token is used to set the default timescale for
409 the simulation. This is the time units and precision before any
410 `timescale directive or after a `resetall directive. The
411 default is 1s/1s.
412 +toupper-filename
415 This token causes file names after this in the command file to
416 be translated to uppercase. This helps with situations where a
417 directory has passed through a DOS machine, and in the process
418 the file names become munged.
419 +tolower-filename
422 This is similar to the +toupper-filename hack described above.
423 +integer-width+value
426 This allows the programmer to select the width for integer
427 variables in the Verilog source. The default is 32, the value
428 can be any desired integer value.
429
432 In certain cases, iverilog supports variables in command files. These
433 are strings of the form "$(varname)" or "${varname}", where varname is
434 the name of the environment variable to read. The entire string is
435 replaced with the contents of that variable. Variables are only substi‐
436 tuted in contexts that explicitly support them, including file and
437 directory strings.
438 Variable values come from the operating system environment, and not
440 from preprocessor defines elsewhere in the file or the command line.
441
444 The following macros are predefined by the compiler:
445 __ICARUS__ = 1
447 This is always defined when compiling with Icarus Verilog.
448 __VAMS_ENABLE__ = 1
451 This is defined if Verilog-AMS is enabled.
452
455 These examples assume that you have a Verilog source file called
456 hello.v in the current directory
457 To compile hello.v to an executable file called a.out:
459 iverilog hello.v
461 To compile hello.v to an executable file called hello:
463 iverilog -o hello hello.v
465 To compile and run explicitly using the vvp runtime:
467 iverilog -ohello.vvp -tvvp hello.v
469
472 Steve Williams (steve@icarus.com)
473
476 vvp(1), <http://www.icarus.com/eda/verilog/>
477 Tips on using, debugging, and developing the compiler can be found at
479 <http://iverilog.wikia.com/>
480
483 Copyright © 2002-2010 Stephen Williams
484 This document can be freely redistributed according to the terms of the
486 GNU General Public License version 2.0
487 January 22nd, 2010 iverilog(1)