| blob | 5b33825b84d4a20a85ef9571b7192436c896d0cf |
5 <head>
12 <link rel="search" type="application/opensearchdescription+xml" href="http://geda.seul.org/wiki/lib/exe/opensearch.php" title="geda Wiki" />
14 <link rel="contents" href="http://geda.seul.org/wiki/geda:icarus_readme?do=index" title="Index" />
15 <link rel="alternate" type="application/rss+xml" title="Recent Changes" href="http://geda.seul.org/wiki/feed.php" />
16 <link rel="alternate" type="application/rss+xml" title="Current Namespace" href="http://geda.seul.org/wiki/feed.php?mode=list&ns=geda" />
17 <link rel="alternate" type="text/html" title="Plain HTML" href="http://geda.seul.org/wiki/_export/xhtml/geda:icarus_readme" />
18 <link rel="alternate" type="text/plain" title="Wiki Markup" href="http://geda.seul.org/wiki/_export/raw/geda:icarus_readme" />
22 </head>
23 <body>
28 <h1><a name="the_icarus_verilog_compilation_system" id="the_icarus_verilog_compilation_system">The Icarus Verilog Compilation System</a></h1>
34 1.0 What is ICARUS Verilog?
36 Icarus Verilog is intended to compile ALL of the Verilog HDL as
38 yet. It does currently handle a mix of structural and behavioral
39 constructs. For a view of the current state of Icarus Verilog, see its
42 Icarus Verilog is not aimed at being a simulator in the traditional
43 sense, but a compiler that generates code employed by back-end
44 tools. These back-end tools currently include a simulator engine
45 called VVP, an XNF (Xilinx Netlist Format) generator and an EDIF FPGA
46 netlist generator. In the future, backends are expected for EDIF/LPM,
47 structural Verilog, VHDL, etc.
49 For instructions on how to run Icarus Verilog,
50 see the ``iverilog'' man page.
53 2.0 Building/Installing Icarus Verilog From Source
55 If you are starting from source, the build process is designed to be
56 as simple as practical. Someone basically familiar with the target
57 system and C/C++ compilation should be able to build the source
58 distribution with little effort. Some actual programming skills are
59 not required, but helpful in case of problems.
61 If you are building for Windows, see the mingw.txt file.
63 2.1 Compile Time Prerequisites
65 You need the following software to compile Icarus Verilog from source
66 on a UNIX-like system:
68 - GNU Make
69 The Makefiles use some GNU extensions, so a basic POSIX
70 make will not work. Linux systems typically come with a
71 satisfactory make. BSD based systems (i.e., NetBSD, FreeBSD)
72 typically have GNU make as the gmake program.
74 - ISO C++ Compiler
75 The ivl and ivlpp programs are written in C++ and make use
76 of templates and some of the standard C++ library. egcs and
77 recent gcc compilers with the associated libstdc++ are known
80 - bison and flex
82 - gperf 2.7
83 The lexical analyzer doesn't recognize keywords directly,
84 but instead matches symbols and looks them up in a hash
85 table in order to get the proper lexical code. The gperf
86 program generates the lookup table.
88 A version problem with this program is the most common cause
89 of difficulty. See the Icarus Verilog FAQ.
91 - readline 4.2
92 On Linux systems, this usually means the readline-devel
93 rpm. In any case, it is the development headers of readline
94 that are needed.
96 - termcap
97 The readline library in turn uses termcap.
99 If you are building from CVS, you will also need software to generate
100 the configure scripts.
102 - autoconf 2.53
103 This generates configure scripts from configure.in. The 2.53
104 or later versions are known to work, autoconf 2.13 is
105 reported to *not* work.
107 2.2 Compilation
109 Unpack the tar-ball and cd into the verilog-######### directory
110 (presumably that is how you got to this README) and compile the source
111 with the commands:
113 ./configure
114 make
116 Normally, this command automatically figures out everything it needs
117 to know. It generally works pretty well. There are a few flags to the
118 configure script that modify its behavior:
120 --without-ipal
121 This turns off support for Icarus PAL, whether ipal
122 libraries are installed or not.
125 The default is /usr/local, which causes the tool suite to
126 be compiled for install in /usr/local/bin,
127 /usr/local/share/ivl, etc.
129 I recommend that if you are configuring for precompiled
130 binaries, use --prefix=/usr. On Solaris systems, it is
131 common to use --prefix=/opt. You can configure for a non-root
132 install with --prefix=$HOME.
134 --enable-vvp32 (experimental)
135 If compiling on AMD64 systems, this enables the
136 compilation of 32bit compatible vvp (vvp32) and the vpi
137 modules that match.
139 2.2.1 Special AMD64 Instructions
141 (The Icarus Verilog RPM for x86_64 is build using these instructions.)
143 If you are building for Linux/AMD64 (a.k.a x86_64) then to get the
144 most out of your install, first make sure you have both 64bit and
145 32bit development libraries installed. Then configure with this
146 somewhat more complicated command:
150 This reflects the convention on AMD64 systems that 64bit libraries go
152 compatibility files. A 32bit version of vvp (vvp32) will be created,
153 as well as 32bit versions of the development libraries and bundled VPI
154 libraries.
156 2.3 (Optional) Testing
158 To run a simple test before installation, execute
160 make check
162 The commands printed by this run might help you in running Icarus
163 Verilog on your own Verilog sources before the package is installed
164 by root.
166 2.4 Installation
168 Now install the files in an appropriate place. (The makefiles by
169 default install in /usr/local unless you specify a different prefix
171 to do this as root to gain access to installation directories.
173 make install
175 2.5 Uninstallation
177 The generated Makefiles also include the uninstall target. This should
178 remove all the files that ``make install'' creates.
180 3.0 How Icarus Verilog Works
182 This tool includes a parser which reads in Verilog (plus extensions)
183 and generates an internal netlist. The netlist is passed to various
184 processing steps that transform the design to more optimal/practical
185 forms, then is passed to a code generator for final output. The
186 processing steps and the code generator are selected by command line
187 switches.
189 3.1 Preprocessing
191 There is a separate program, ivlpp, that does the preprocessing. This
192 program implements the `include and `define directives producing
193 output that is equivalent but without the directives. The output is a
194 single file with line number directives, so that the actual compiler
195 only sees a single input file. See ivlpp/ivlpp.txt for details.
197 3.2 Parse
199 The Verilog compiler starts by parsing the Verilog source file. The
201 (see pform.h) is mostly a direct reflection of the compilation
202 step. There may be dangling references, and it is not yet clear which
203 module is the root.
205 One can see a human readable version of the final pform by using the
209 3.3 Elaboration
211 This phase takes the pform and generates a netlist. The driver selects
212 (by user request or lucky guess) the root module to elaborate,
213 resolves references and expands the instantiations to form the design
214 netlist. (See netlist.txt.) Final semantic checks are performed during
215 elaboration, and some simple optimizations are performed. The netlist
216 includes all the behavioral descriptions, as well as gates and wires.
218 The elaborate() function performs the elaboration.
220 One can see a human readable version of the final, elaborated and
222 elaboration succeeds, the final netlist (i.e., after optimizations but
225 Elaboration is actually performed in two steps: scopes and parameters
226 first, followed by the structural and behavioral elaboration.
228 3.3.1 Scope Elaboration
230 This pass scans through the pform looking for scopes and parameters. A
231 tree of NetScope objects is built up and placed in the Design object,
232 with the root module represented by the root NetScope object. The
233 elab_scope.cc and elab_pexpr.cc files contain most of the code for
234 handling this phase.
236 The tail of the elaborate_scope behavior (after the pform is
237 traversed) includes a scan of the NetScope tree to locate defparam
238 assignments that were collected during scope elaboration. This is when
239 the defparam overrides are applied to the parameters.
241 3.3.2 Netlist Elaboration
243 After the scopes and parameters are generated and the NetScope tree
244 fully formed, the elaboration runs through the pform again, this time
245 generating the structural and behavioral netlist. Parameters are
246 elaborated and evaluated by now so all the constants of code
247 generation are now known locally, so the netlist can be generated by
248 simply passing through the pform.
250 3.4 Optimization
252 This is actually a collection of processing steps that perform
253 optimizations that do not depend on the target technology. Examples of
254 some useful transformations are
256 - eliminate null effect circuitry
257 - combinational reduction
258 - constant propagation
260 The actual functions performed are specified on the ivl command line by
261 the -F flags (see below).
263 3.5 Code Generation
265 This step takes the design netlist and uses it to drive the code
266 generator (see target.h). This may require transforming the
267 design to suit the technology.
269 The emit() method of the Design class performs this step. It runs
270 through the design elements, calling target functions as need arises
271 to generate actual output.
273 The user selects the target code generator with the -t flag on the
274 command line.
276 3.6 ATTRIBUTES
278 NOTE: The $attribute syntax will soon be deprecated in favor of the
279 Verilog-2001 attribute syntax, which is cleaner and standardized.
281 The parser accepts, as an extension to Verilog, the $attribute module
282 item. The syntax of the $attribute item is:
286 The $attribute keyword looks like a system task invocation. The
287 difference here is that the parameters are more restricted then those
290 expressions, that give the key and the value of the attribute to be
291 attached to the identified object.
294 the various processing steps. See the documentation for the processing
295 step for a list of the pertinent attributes.
297 Attributes can also be applied to gate types. When this is done, the
298 attribute is given to every instantiation of the primitive. The syntax
300 names a primitive earlier in the compilation unit and the statement is
301 placed in global scope, instead of within a module. The semicolon is
302 not part of a type attribute.
304 Note that attributes are also occasionally used for communication
305 between processing steps. Processing steps that are aware of others
306 may place attributes on netlist objects to communicate information to
307 later steps.
309 Icarus Verilog also accepts the Verilog 2001 syntax for
310 attributes. They have the same general meaning as with the $attribute
311 syntax, but they are attached to objects by position instead of by
312 name. Also, the key is a Verilog identifier instead of a string.
314 4.0 Running iverilog
316 The preferred way to invoke the compiler is with the iverilog(1)
317 command. This program invokes the preprocessor (ivlpp) and the
318 compiler (ivl) with the proper command line options to get the job
319 done in a friendly way. See the iverilog(1) man page for usage details.
322 4.1 EXAMPLES
326 ------------------------ hello.vl ----------------------------
327 module main();
329 initial
330 begin
332 $finish ;
333 end
335 endmodule
337 --------------------------------------------------------------
340 is available.
342 To compile the program:
344 iverilog hello.vl
346 (The above presumes that /usr/local/include and /usr/local/lib are
347 part of the compiler search path, which is usually the case for gcc.)
349 To run the program:
351 ./a.out
354 by the compiler. See the iverilog(1) man page.
356 5.0 Unsupported Constructs
358 Icarus Verilog is in development - as such it still only supports a
359 (growing) subset of Verilog. Below is a description of some of the
360 currently unsupported Verilog features. This list is not exhaustive,
361 and does not account for errors in the compiler. See the Icarus
362 Verilog web page for the current state of support for Verilog, and in
363 particular, browse the bug report database for reported unsupported
364 constructs.
366 - System functions are supported, but the return value is a little
367 tricky. See SYSTEM FUNCTION TABLE FILES in the iverilog man page.
369 - Specify blocks are parsed but ignored in general.
371 - trireg is not supported. tri0 and tri1 are supported.
373 - tran primitives, i.e. tran, tranif1, tranif0, rtran, rtranif1
374 and rtranif0 are not supported.
377 every other context do work properly, including the V2001 form
380 - Event controls inside non-blocking assignments are not supported.
381 i.e.: a <= @(posedge clk) b;
383 - Macro arguments are not supported. `define macros are supported,
384 but they cannot take arguments.
386 5.1 Nonstandard Constructs or Behaviors
388 Icarus Verilog includes some features that are not part of the
389 IEEE1364 standard, but have well defined meaning, and also sometimes
390 gives nonstandard (but extended) meanings to some features of the
392 more details.
395 This system function returns 1 if the expression contained is
396 signed, or 0 otherwise. This is mostly of use for compiler
397 regression tests.
401 The $bits system function returns the size in bits of the
402 expression that is its argument. The result of this
403 function is undefined if the argument doesn't have a
404 self-determined size.
406 The $sizeof function is deprecated in favor of $bits, which is
407 the same thing, but included in the SystemVerilog definition.
409 $simtime
410 The $simtime system function returns as a 64bit value the
411 simulation time, unscaled by the time units of local
412 scope. This is different from the $time and $stime functions
413 which return the scaled times. This function is added for
414 regression testing of the compiler and run time, but can be
415 used by applications who really want the simulation time.
417 Note that the simulation time can be confusing if there are
418 lots of different `timescales within a design. It is not in
419 general possible to predict what the simulation precision will
420 turn out to be.
422 $mti_random()
423 $mti_dist_uniform
424 These functions are similar to the IEEE1364 standard $random
425 functions, but they use the Mersenne Twister (MT19937)
426 algorithm. This is considered an excellent random number
427 generator, but does not generate the same sequence as the
428 standardized $random.
430 Builtin system functions
432 Certain of the system functions have well defined meanings, so
433 can theoretically be evaluated at compile time, instead of
434 using runtime VPI code. Doing so means that VPI cannot
435 override the definitions of functions handled in this
436 manner. On the other hand, this makes them synthesizable, and
437 also allows for more aggressive constant propagation. The
438 functions handled in this manner are:
440 $bits
441 $signed
442 $sizeof
443 $unsigned
445 Implementations of these system functions in VPI modules will
446 be ignored.
448 Preprocessing Library Modules
450 Icarus Verilog does preprocess modules that are loaded from
451 libraries via the -y mechanism. However, the only macros
452 defined during compilation of that file are those that it
453 defines itself (or includes) or that are defined on the
454 command line or command file.
456 Specifically, macros defined in the non-library source files
457 are not remembered when the library module is loaded. This is
458 intentional. If it were otherwise, then compilation results
459 might vary depending on the order that libraries are loaded,
460 and that is too unpredictable.
462 It is said that some commercial compilers do allow macro
463 definitions to span library modules. That's just plain weird.
465 Width in %t Time Formats
467 Standard Verilog does not allow width fields in the %t formats
468 of display strings. For example, this is illegal:
472 Standard Verilog instead relies on the $timeformat to
473 completely specify the format.
475 Icarus Verilog allows the programmer to specify the field
477 does in standard Verilog. However, if the programmer chooses
479 Icarus Verilog will override the $timeformat minimum width and
480 use the explicit minimum width.
482 vpiScope iterator on vpiScope objects.
484 In the VPI, the normal way to iterate over vpiScope objects
485 contained within a vpiScope object, is the vpiInternalScope
486 iterator. Icarus Verilog adds support for the vpiScope
487 iterator of a vpiScope object, that iterates over *everything*
488 the is contained in the current scope. This is useful in cases
489 where one wants to iterate over all the objects in a scope
490 without iterating over all the contained types explicitly.
492 time 0 race resolution.
494 Combinational logic is routinely modeled using always
495 blocks. However, this can lead to race conditions if the
496 inputs to the combinational block are initialized in initial
497 statements. Icarus Verilog slightly modifies time 0 scheduling
498 by arranging for always statements with ANYEDGE sensitivity
499 lists to be scheduled before any other threads. This causes
500 combinational always blocks to be triggered when the values in
501 the sensitivity list are initialized by initial threads.
503 Nets with Types
505 Icarus Verilog support an extension syntax that allows nets
506 and regs to be explicitly typed. The currently supported types
508 are new keywords. Typical syntax is:
510 wire real foo = 1.0;
511 reg logic bar, bat;
513 ... and so forth. The syntax can be turned off by using the
514 -g2 flag to iverilog, and turned on explicitly with the -g2x
515 flag to iverilog.
517 6.0 CREDITS
519 Except where otherwise noted, Icarus Verilog, ivl and ivlpp are
520 Copyright Stephen Williams. The proper notices are in the head of each
521 file. However, I have early on received aid in the form of fixes,
522 Verilog guidance, and especially testing from many people. Testers in
523 particular include a larger community of people interested in a GPL
524 Verilog for Linux.</pre>
526 </div>
527 </div>
528 </body>
529 </html>