| blob | eaf80455056e422814b781b30d25ea52cae2ee43 |
3 <html>
4 <head>
10 </head>
11 <body>
13 <p>
14 <a href="start.html" class="wikilink1" title="start.html">gEDA</a> » <a href="geda-documentation.html" class="wikilink1" title="geda-documentation.html">Documentation</a> » <a href="geda-icarus.html" class="wikilink1" title="geda-icarus.html">Icarus Verilog</a> » <a href="geda-icarus_readme.txt.html" class="wikilink2" title="geda-icarus_readme.txt.html">The Icarus Verilog Compilation System</a>
15 </p>
17 <h1 class="sectionedit1" id="the_icarus_verilog_compilation_system">The Icarus Verilog Compilation System</h1>
20 <p>
22 </p>
24 </div>
25 <!-- EDIT1 SECTION "The Icarus Verilog Compilation System" [109-198] -->
29 <p>
30 Icarus Verilog is intended to compile ALL of the Verilog HDL as
32 yet. It does currently handle a mix of structural and behavioral
33 constructs. For a view of the current state of Icarus Verilog, see its
34 home page at <a href="http://www.icarus.com/eda/verilog" class="urlextern" title="http://www.icarus.com/eda/verilog" rel="nofollow">http://www.icarus.com/eda/verilog</a>.
35 </p>
37 <p>
38 Icarus Verilog is not aimed at being a simulator in the traditional
39 sense, but a compiler that generates code employed by back-end
40 tools.
41 </p>
43 <p>
44 For instructions on how to run Icarus Verilog, see the <code><a href="geda-icarus_mp.html" class="wikilink1" title="geda-icarus_mp.html">iverilog(1)</a></code> man page.
45 </p>
47 </div>
48 <!-- EDIT2 SECTION "What is ICARUS Verilog?" [199-789] -->
49 <h2 class="sectionedit3" id="building_installing_icarus_verilog_from_source">Building/Installing Icarus Verilog From Source</h2>
52 <p>
53 If you are starting from source, the build process is designed to be
54 as simple as practical. Someone basically familiar with the target
55 system and C/C++ compilation should be able to build the source
56 distribution with little effort. Some actual programming skills are
57 not required, but helpful in case of problems.
58 </p>
60 <p>
61 If you are building for Windows, see the mingw.txt file.
62 </p>
64 </div>
65 <!-- EDIT3 SECTION "Building/Installing Icarus Verilog From Source" [790-1223] -->
69 <p>
70 You need the following software to compile Icarus Verilog from source
71 on a UNIX-like system:
72 </p>
73 <ul>
75 The Makefiles use some GNU extensions, so a basic POSIX make will not work. Linux systems typically come with a satisfactory make. BSD based systems (i.e., NetBSD, FreeBSD) typically have GNU make as the gmake program.</div>
76 </li>
77 </ul>
78 <ul>
80 The <code>ivl</code> and <code>ivlpp</code> programs are written in C++ and make use of templates and some of the standard C++ library. egcs and recent gcc compilers with the associated libstdc++ are known to work. MSVC++ 5 and 6 are known to definitely *not* work.</div>
81 </li>
82 </ul>
83 <ul>
85 </li>
86 </ul>
87 <ul>
89 The lexical analyzer doesn't recognize keywords directly, but instead matches symbols and looks them up in a hash table in order to get the proper lexical code. The gperf program generates the lookup table.<br/>
90 A version problem with this program is the most common cause of difficulty. See the Icarus Verilog <abbr title="Frequently Asked Questions">FAQ</abbr>.</div>
91 </li>
92 </ul>
93 <ul>
95 On Linux systems, this usually means the <code>readline-devel</code> rpm. In any case, it is the development headers of readline that are needed.</div>
96 </li>
97 </ul>
98 <ul>
100 The readline library in turn uses termcap.</div>
101 </li>
102 </ul>
104 <p>
105 If you are building from git, you will also need software to generate
106 the configure scripts.
107 </p>
108 <ul>
110 This generates configure scripts from <code>configure.in</code>. The 2.53 or later versions are known to work, autoconf 2.13 is reported to *not* work.</div>
111 </li>
112 </ul>
114 </div>
115 <!-- EDIT4 SECTION "Compile Time Prerequisites" [1224-2706] -->
119 <p>
120 Unpack the tar-ball and cd into the <code>verilog-#########</code> directory and compile the source
121 with the commands:
122 </p>
124 make</pre>
126 <p>
127 Normally, this command automatically figures out everything it needs
128 to know. It generally works pretty well. There are a few flags to the
129 configure script that modify its behavior:
130 </p>
132 The default is /usr/local, which causes the tool suite to
133 be compiled for install in /usr/local/bin,
134 /usr/local/share/ivl, etc.
136 I recommend that if you are configuring for precompiled
137 binaries, use --prefix=/usr. On Solaris systems, it is
138 common to use --prefix=/opt. You can configure for a non-root
139 install with --prefix=$HOME.
141 --enable-suffix
143 --disable-suffix
144 Enable/disable changing the names of install files to use
145 a suffix string so that this version or install can co-
146 exist with other versions. This renames the installed
147 commands (iverilog, iverilog-vpi, vvp) and the installed
148 library files and include directory so that installations
149 with the same prefix but different suffix are guaranteed
150 to not interfere with each other.</pre>
152 </div>
153 <!-- EDIT5 SECTION "Compilation" [2707-3922] -->
157 <p>
158 To run a simple test before installation, execute
159 </p>
162 <p>
163 The commands printed by this run might help you in running Icarus
164 Verilog on your own Verilog sources before the package is installed
165 by root.
166 </p>
168 </div>
169 <!-- EDIT6 SECTION "(Optional) Testing" [3923-4161] -->
173 <p>
174 Now install the files in an appropriate place. (The makefiles by
177 to do this as root to gain access to installation directories.
178 </p>
181 </div>
182 <!-- EDIT7 SECTION "Installation" [4162-4476] -->
186 <p>
189 </p>
191 </div>
192 <!-- EDIT8 SECTION "Uninstallation" [4477-4630] -->
196 <p>
197 This tool includes a parser which reads in Verilog (plus extensions)
198 and generates an internal netlist. The netlist is passed to various
199 processing steps that transform the design to more optimal/practical
200 forms, then is passed to a code generator for final output. The
201 processing steps and the code generator are selected by command line
202 switches.
203 </p>
205 </div>
206 <!-- EDIT9 SECTION "How Icarus Verilog Works" [4631-5018] -->
210 <p>
213 output that is equivalent but without the directives. The output is a
214 single file with line number directives, so that the actual compiler
216 </p>
218 </div>
219 <!-- EDIT10 SECTION "Preprocessing" [5019-5398] -->
223 <p>
224 The Verilog compiler starts by parsing the Verilog source file. The
225 output of the parse is a list of Module objects in “pform”. The pform
227 step. There may be dangling references, and it is not yet clear which
228 module is the root.
229 </p>
231 <p>
232 One can see a human readable version of the final pform by using the
233 <code>-P <path></code> flag to the <code>ivl</code> subcommand. This will cause <code>ivl</code>
236 </p>
238 </div>
239 <!-- EDIT11 SECTION "Parse" [5399-5981] -->
243 <p>
244 This phase takes the pform and generates a netlist. The driver selects
245 (by user request or lucky guess) the root module to elaborate,
246 resolves references and expands the instantiations to form the design
248 elaboration, and some simple optimizations are performed. The netlist
249 includes all the behavioral descriptions, as well as gates and wires.
250 </p>
252 <p>
254 </p>
256 <p>
257 One can see a human readable version of the final, elaborated and
259 elaboration succeeds, the final netlist (i.e., after optimizations but
261 </p>
263 <p>
264 Elaboration is actually performed in two steps: scopes and parameters
265 first, followed by the structural and behavioral elaboration.
266 </p>
268 </div>
273 <p>
274 This pass scans through the pform looking for scopes and parameters. A
278 </p>
280 <p>
283 assignments that were collected during scope elaboration. This is when
284 the defparam overrides are applied to the parameters.
285 </p>
287 </div>
292 <p>
294 fully formed, the elaboration runs through the pform again, this time
295 generating the structural and behavioral netlist. Parameters are
296 elaborated and evaluated by now so all the constants of code
297 generation are now known locally, so the netlist can be generated by
298 simply passing through the pform.
299 </p>
301 </div>
302 <!-- EDIT12 SECTION "Elaboration" [5982-7876] -->
306 <p>
307 This is actually a collection of processing steps that perform
308 optimizations that do not depend on the target technology. Examples of
309 some useful transformations are
310 </p>
311 <ul>
313 </li>
315 </li>
317 </li>
318 </ul>
320 <p>
323 </p>
325 </div>
326 <!-- EDIT13 SECTION "Optimization" [7877-8261] -->
330 <p>
331 This step takes the design netlist and uses it to drive the code
333 design to suit the technology.
334 </p>
336 <p>
338 through the design elements, calling target functions as need arises
339 to generate actual output.
340 </p>
342 <p>
344 command line.
345 </p>
347 </div>
348 <!-- EDIT14 SECTION "Code Generation" [8262-8706] -->
352 Verilog-2001 attribute syntax, which is cleaner and standardized.
354 </div>
355 <p>
358 </p>
361 <p>
363 difference here is that the parameters are more restricted than those
365 the item to get an attribute. The <code><key></code> and <code><value></code> are strings, not
366 expressions, that give the key and the value of the attribute to be
367 attached to the identified object.
368 </p>
370 <p>
372 the various processing steps. See the documentation for the processing
373 step for a list of the pertinent attributes.
374 </p>
376 <p>
377 Attributes can also be applied to gate types. When this is done, the
378 attribute is given to every instantiation of the primitive. The syntax
380 names a primitive earlier in the compilation unit and the statement is
381 placed in global scope, instead of within a module. The semicolon is
382 not part of a type attribute.
383 </p>
385 <p>
386 Note that attributes are also occasionally used for communication
387 between processing steps. Processing steps that are aware of others
388 may place attributes on netlist objects to communicate information to
389 later steps.
390 </p>
392 <p>
393 Icarus Verilog also accepts the Verilog 2001 syntax for
395 syntax, but they are attached to objects by position instead of by
396 name. Also, the key is a Verilog identifier instead of a string.
397 </p>
399 </div>
400 <!-- EDIT15 SECTION "Attributes" [8707-10499] -->
404 <p>
408 done in a friendly way. See the <code><a href="geda-icarus_mp.html" class="wikilink1" title="geda-icarus_mp.html">iverilog(1)</a></code> man page for usage details.
409 </p>
411 </div>
412 <!-- EDIT16 SECTION "Running iverilog" [10500-10828] -->
416 <p>
418 </p>
420 <dt><a href="/./_export/code/:geda:icarus_readme.txt?codeblock=1" title="Download Snippet" class="mediafile mf_vl_">"hello.vl"</a></dt>
421 <dd><pre class="code verilog"><span class="kw1">module</span> main<span class="br0">(</span><span class="br0">)</span><span class="sy0">;</span>
422
425 <span class="kw2">$display</span><span class="br0">(</span><span class="st0">"Hi there"</span><span class="br0">)</span><span class="sy0">;</span>
428
430 </dd></dl>
432 <p>
434 is available.
435 </p>
437 <p>
438 To compile the program:
439 </p>
442 <p>
444 part of the compiler search path, which is usually the case for gcc.)
445 </p>
447 <p>
448 To run the program:
449 </p>
452 <p>
454 by the compiler. See the <code><a href="geda-icarus_mp.html" class="wikilink1" title="geda-icarus_mp.html">iverilog(1)</a></code> man page.
455 </p>
457 </div>
458 <!-- EDIT17 SECTION "Examples" [10829-11456] -->
462 <p>
463 Icarus Verilog is in development—as such it still only supports a
464 (growing) subset of Verilog. Below is a description of some of the
465 currently unsupported Verilog features. This list is not exhaustive,
466 and does not account for errors in the compiler. See the Icarus
467 Verilog web page for the current state of support for Verilog, and in
468 particular, browse the bug report database for reported unsupported
469 constructs.
470 </p>
471 <ul>
472 <li class="level1"><div class="li"> System functions are supported, but the return value is a little tricky. See SYSTEM FUNCTION TABLE FILES in the <a href="geda-icarus_mp.html" class="wikilink1" title="geda-icarus_mp.html">iverilog man page</a>.</div>
473 </li>
474 </ul>
475 <ul>
477 </li>
478 </ul>
479 <ul>
480 <li class="level1"><div class="li"> <code>trireg</code> is not supported. <code>tri0</code> and <code>tri1</code> are supported.</div>
481 </li>
482 </ul>
483 <ul>
484 <li class="level1"><div class="li"> tran primitives, i.e. <code>tran</code>, <code>tranif1</code>, <code>tranif0</code>, <code>rtran</code>, <code>rtranif1</code> and <code>rtranif0</code> are not supported.</div>
485 </li>
486 </ul>
487 <ul>
488 <li class="level1"><div class="li"> Net delays, of the form <code>wire #N foo;</code> do not work. Delays in every other context do work properly, including the V2001 form <code>wire #5 foo = bar;</code></div>
489 </li>
490 </ul>
491 <ul>
492 <li class="level1"><div class="li"> Event controls inside non-blocking assignments are not supported. i.e.: <code>a ⇐ @(posedge clk) b;</code></div>
493 </li>
494 </ul>
495 <ul>
496 <li class="level1"><div class="li"> Macro arguments are not supported. <code>`define</code> macros are supported, but they cannot take arguments.</div>
497 </li>
498 </ul>
500 </div>
501 <!-- EDIT18 SECTION "Unsupported Constructs" [11457-12676] -->
502 <h3 class="sectionedit19" id="nonstandard_constructs_or_behaviors">Nonstandard Constructs or Behaviors</h3>
505 <p>
506 Icarus Verilog includes some features that are not part of the
507 IEEE1364 standard, but have well defined meaning, and also sometimes
508 gives nonstandard (but extended) meanings to some features of the
510 more details.
511 </p>
513 This system function returns 1 if the expression contained is
514 signed, or 0 otherwise. This is mostly of use for compiler
515 regression tests.
519 The $bits system function returns the size in bits of the
520 expression that is its argument. The result of this
521 function is undefined if the argument doesn't have a
522 self-determined size.
524 The $sizeof function is deprecated in favor of $bits, which is
525 the same thing, but included in the SystemVerilog definition.
527 $simtime
528 The $simtime system function returns as a 64bit value the
529 simulation time, unscaled by the time units of local
530 scope. This is different from the $time and $stime functions
531 which return the scaled times. This function is added for
532 regression testing of the compiler and run time, but can be
533 used by applications who really want the simulation time.
535 Note that the simulation time can be confusing if there are
536 lots of different `timescales within a design. It is not in
537 general possible to predict what the simulation precision will
538 turn out to be.
540 $mti_random()
541 $mti_dist_uniform
542 These functions are similar to the IEEE1364 standard $random
543 functions, but they use the Mersenne Twister (MT19937)
544 algorithm. This is considered an excellent random number
545 generator, but does not generate the same sequence as the
546 standardized $random.
548 Builtin system functions
550 Certain of the system functions have well defined meanings, so
551 can theoretically be evaluated at compile time, instead of
552 using runtime VPI code. Doing so means that VPI cannot
553 override the definitions of functions handled in this
554 manner. On the other hand, this makes them synthesizable, and
555 also allows for more aggressive constant propagation. The
556 functions handled in this manner are:
558 $bits
559 $signed
560 $sizeof
561 $unsigned
563 Implementations of these system functions in VPI modules will
564 be ignored.
566 Preprocessing Library Modules
568 Icarus Verilog does preprocess modules that are loaded from
569 libraries via the -y mechanism. However, the only macros
570 defined during compilation of that file are those that it
571 defines itself (or includes) or that are defined on the
572 command line or command file.
574 Specifically, macros defined in the non-library source files
575 are not remembered when the library module is loaded. This is
576 intentional. If it were otherwise, then compilation results
577 might vary depending on the order that libraries are loaded,
578 and that is too unpredictable.
580 It is said that some commercial compilers do allow macro
581 definitions to span library modules. That's just plain weird.
583 Width in %t Time Formats
585 Standard Verilog does not allow width fields in the %t formats
586 of display strings. For example, this is illegal:
590 Standard Verilog instead relies on the $timeformat to
591 completely specify the format.
593 Icarus Verilog allows the programmer to specify the field
595 does in standard Verilog. However, if the programmer chooses
597 Icarus Verilog will override the $timeformat minimum width and
598 use the explicit minimum width.
600 vpiScope iterator on vpiScope objects.
602 In the VPI, the normal way to iterate over vpiScope objects
603 contained within a vpiScope object, is the vpiInternalScope
604 iterator. Icarus Verilog adds support for the vpiScope
605 iterator of a vpiScope object, that iterates over *everything*
606 the is contained in the current scope. This is useful in cases
607 where one wants to iterate over all the objects in a scope
608 without iterating over all the contained types explicitly.
610 time 0 race resolution.
612 Combinational logic is routinely modeled using always
613 blocks. However, this can lead to race conditions if the
614 inputs to the combinational block are initialized in initial
615 statements. Icarus Verilog slightly modifies time 0 scheduling
616 by arranging for always statements with ANYEDGE sensitivity
617 lists to be scheduled before any other threads. This causes
618 combinational always blocks to be triggered when the values in
619 the sensitivity list are initialized by initial threads.
621 Nets with Types
623 Icarus Verilog support an extension syntax that allows nets
624 and regs to be explicitly typed. The currently supported types
626 are new keywords. Typical syntax is:
628 wire real foo = 1.0;
629 reg logic bar, bat;
631 ... and so forth. The syntax can be turned off by using the
632 -g2 flag to iverilog, and turned on explicitly with the -g2x
633 flag to iverilog.</pre>
635 </div>
636 <!-- EDIT19 SECTION "Nonstandard Constructs or Behaviors" [12677-17701] -->
640 <p>
642 Copyright Stephen Williams. The proper notices are in the head of each
643 file. However, I have early on received aid in the form of fixes,
644 Verilog guidance, and especially testing from many people. Testers in
645 particular include a larger community of people interested in a <abbr title="GNU General Public License">GPL</abbr>
646 Verilog for Linux.
647 </p>
649 </div>
651 </html>