docs/wiki/geda-icarus_readme.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   6   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   7   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   8
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10 </head>
  11 <body>
  12
  13 <p>
  14 <a href="start.html" class="wikilink1" title="start.html">gEDA</a> &gt;&gt; <a href="geda-documentation.html" class="wikilink1" title="geda-documentation.html">Documentation</a> &gt;&gt; <a href="geda-icarus.html" class="wikilink1" title="geda-icarus.html">Icarus Verilog</a> &gt;&gt; <a href="geda-icarus_readme.txt.html" class="wikilink2" title="geda-icarus_readme.txt.html">The Icarus Verilog Compilation System</a>
  15 </p>
  16
  17 <h1 id="theicarusverilogcompilationsystem">The Icarus Verilog Compilation System</h1>
  18 <div class="level1">
  19
  20 <p>
  21 Copyright 2000-2004 Stephen Williams
  22 </p>
  23
  24 </div>
  25
  26 <h2 id="whatisicarusverilog">What is ICARUS Verilog?</h2>
  27 <div class="level2">
  28
  29 <p>
  30 Icarus Verilog is intended to compile ALL of the Verilog HDL as
  31 described in the IEEE-1364 standard. Of course, it&#039;s not quite there
  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 http:<em>www.icarus.com/eda/verilog.
  35
  36 Icarus Verilog is not aimed at being a simulator in the traditional
  37 sense, but a compiler that generates code employed by back-end
  38 tools.
  39
  40 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.
  41
  42
  43 ===== Building/Installing Icarus Verilog From Source =====
  44
  45 If you are starting from source, the build process is designed to be
  46 as simple as practical. Someone basically familiar with the target
  47 system and C/C++ compilation should be able to build the source
  48 distribution with little effort. Some actual programming skills are
  49 not required, but helpful in case of problems.
  50
  51 If you are building for Windows, see the mingw.txt file.
  52
  53 ==== Compile Time Prerequisites ====
  54
  55 You need the following software to compile Icarus Verilog from source
  56 on a UNIX-like system:
  57
  58         * <strong>GNU Make</strong><br/>
  59 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.
  60
  61         * <strong>ISO C++ Compiler</strong><br/>
  62 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.
  63
  64         * <strong>bison and flex</strong>
  65
  66         * <strong>gperf 2.7</strong><br/>
  67 The lexical analyzer doesn&#039;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/>
  68 A version problem with this program is the most common cause of difficulty. See the Icarus Verilog FAQ.
  69
  70         * <strong>readline 4.2</strong><br/>
  71 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.
  72
  73         * <strong>termcap</strong><br/>
  74 The readline library in turn uses termcap.
  75
  76 If you are building from git, you will also need software to generate
  77 the configure scripts.
  78
  79         * <strong>autoconf 2.53</strong><br/>
  80 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.
  81
  82 ==== Compilation ====
  83
  84 Unpack the tar-ball and cd into the <code>verilog-#########</code> directory and compile the source
  85 with the commands:
  86
  87   ./configure
  88   make
  89
  90 Normally, this command automatically figures out everything it needs
  91 to know. It generally works pretty well. There are a few flags to the
  92 configure script that modify its behavior:
  93
  94 &lt;code&gt;
  95         --prefix=&lt;root&gt;
  96             The default is /usr/local, which causes the tool suite to
  97             be compiled for install in /usr/local/bin,
  98             /usr/local/share/ivl, etc.
  99
 100             I recommend that if you are configuring for precompiled
 101             binaries, use --prefix=/usr.  On Solaris systems, it is
 102             common to use --prefix=/opt.  You can configure for a non-root
 103             install with --prefix=$HOME.
 104
 105         --enable-suffix
 106         --enable-suffix=&lt;your-suffix&gt;
 107         --disable-suffix
 108             Enable/disable changing the names of install files to use
 109             a suffix string so that this version or install can co-
 110             exist with other versions. This renames the installed
 111             commands (iverilog, iverilog-vpi, vvp) and the installed
 112             library files and include directory so that installations
 113             with the same prefix but different suffix are guaranteed
 114             to not interfere with each other.
 115 &lt;/code&gt;
 116
 117 ==== (Optional) Testing ====
 118
 119 To run a simple test before installation, execute
 120
 121   make check
 122
 123 The commands printed by this run might help you in running Icarus
 124 Verilog on your own Verilog sources before the package is installed
 125 by root.
 126
 127 ==== Installation ====
 128
 129 Now install the files in an appropriate place. (The makefiles by
 130 default install in <code>/usr/local</code> unless you specify a different prefix
 131 with the <code>--prefix=&lt;path&gt;</code> flag to the configure command.) You may need
 132 to do this as root to gain access to installation directories.
 133
 134   make install
 135
 136 ==== Uninstallation ====
 137
 138 The generated Makefiles also include the <code>uninstall</code> target. This should
 139 remove all the files that <code>make install</code> creates.
 140
 141 ===== How Icarus Verilog Works =====
 142
 143 This tool includes a parser which reads in Verilog (plus extensions)
 144 and generates an internal netlist. The netlist is passed to various
 145 processing steps that transform the design to more optimal/practical
 146 forms, then is passed to a code generator for final output. The
 147 processing steps and the code generator are selected by command line
 148 switches.
 149
 150 ==== Preprocessing ====
 151
 152 There is a separate program, <code>ivlpp</code>, that does the preprocessing. This
 153 program implements the <code>`include</code> and <code>`define</code> directives producing
 154 output that is equivalent but without the directives. The output is a
 155 single file with line number directives, so that the actual compiler
 156 only sees a single input file. See <code>ivlpp/ivlpp.txt</code> for details.
 157
 158 ==== Parse ====
 159
 160 The Verilog compiler starts by parsing the Verilog source file. The
 161 output of the parse is a list of Module objects in &quot;pform&quot;. The pform
 162 (see <code>pform.h</code>) is mostly a direct reflection of the compilation
 163 step. There may be dangling references, and it is not yet clear which
 164 module is the root.
 165
 166 One can see a human readable version of the final pform by using the
 167 <code>-P &lt;path&gt;</code> flag to the <code>ivl</code> subcommand. This will cause <code>ivl</code>
 168 to dump the pform into the file named <code>&lt;path&gt;</code>. (Note that this is not
 169 normally done, unless debugging the <code>ivl</code> subcommand.)
 170
 171 ==== Elaboration ====
 172
 173 This phase takes the pform and generates a netlist. The driver selects
 174 (by user request or lucky guess) the root module to elaborate,
 175 resolves references and expands the instantiations to form the design
 176 netlist. (See <code>netlist.txt</code>.) Final semantic checks are performed during
 177 elaboration, and some simple optimizations are performed. The netlist
 178 includes all the behavioral descriptions, as well as gates and wires.
 179
 180 The <code>elaborate()</code> function performs the elaboration.
 181
 182 One can see a human readable version of the final, elaborated and
 183 optimized netlist by using the <code>-N &lt;path&gt;</code> flag to the compiler. If
 184 elaboration succeeds, the final netlist (i.e., after optimizations but
 185 before code generation) will be dumped into the file named <code>&lt;path&gt;</code>.
 186
 187 Elaboration is actually performed in two steps: scopes and parameters
 188 first, followed by the structural and behavioral elaboration.
 189
 190 === Scope Elaboration ===
 191
 192 This pass scans through the pform looking for scopes and parameters. A
 193 tree of <code>NetScope</code> objects is built up and placed in the <code>Design</code> object,
 194 with the root module represented by the root <code>NetScope</code> object. The
 195 <code>elab_scope.cc</code> file contains most of the code for handling this phase.
 196
 197 The tail of the <code>elaborate_scope</code> behavior (after the pform is
 198 traversed) includes a scan of the <code>NetScope</code> tree to locate defparam
 199 assignments that were collected during scope elaboration. This is when
 200 the defparam overrides are applied to the parameters.
 201
 202 === Netlist Elaboration ===
 203
 204 After the scopes and parameters are generated and the <code>NetScope</code> tree
 205 fully formed, the elaboration runs through the pform again, this time
 206 generating the structural and behavioral netlist. Parameters are
 207 elaborated and evaluated by now so all the constants of code
 208 generation are now known locally, so the netlist can be generated by
 209 simply passing through the pform.
 210
 211 ==== Optimization ====
 212
 213 This is actually a collection of processing steps that perform
 214 optimizations that do not depend on the target technology. Examples of
 215 some useful transformations are
 216
 217         * eliminate null effect circuitry
 218         * combinational reduction
 219         * constant propagation
 220
 221 The actual functions performed are specified on the <code>ivl</code> command line by
 222 the <code>-F</code> flags (see below).
 223
 224 ==== Code Generation ====
 225
 226 This step takes the design netlist and uses it to drive the code
 227 generator (see <code>target.h</code>). This may require transforming the
 228 design to suit the technology.
 229
 230 The <code>emit()</code> method of the <code>Design</code> class performs this step. It runs
 231 through the design elements, calling target functions as need arises
 232 to generate actual output.
 233
 234 The user selects the target code generator with the <code>-t</code> flag on the
 235 command line.
 236
 237 ==== Attributes ====
 238
 239 &lt;note tip&gt;
 240 The <code>$attribute</code> syntax will soon be deprecated in favor of the
 241 Verilog-2001 attribute syntax, which is cleaner and standardized.
 242 &lt;/note&gt;
 243
 244 The parser accepts, as an extension to Verilog, the <code>$attribute</code> module
 245 item. The syntax of the <code>$attribute</code> item is:
 246
 247         $attribute (&lt;identifier&gt;, &lt;key&gt;, &lt;value&gt;);
 248
 249 The <code>$attribute</code> keyword looks like a system task invocation. The
 250 difference here is that the parameters are more restricted than those
 251 of a system task. The <code>&lt;identifier&gt;</code> must be an identifier. This will be
 252 the item to get an attribute. The <code>&lt;key&gt;</code> and <code>&lt;value&gt;</code> are strings, not
 253 expressions, that give the key and the value of the attribute to be
 254 attached to the identified object.
 255
 256 Attributes are <code>[&lt;key&gt; &lt;value&gt;]</code> pairs and are used to communicate with
 257 the various processing steps. See the documentation for the processing
 258 step for a list of the pertinent attributes.
 259
 260 Attributes can also be applied to gate types. When this is done, the
 261 attribute is given to every instantiation of the primitive. The syntax
 262 for the attribute statement is the same, except that the <code>&lt;identifier&gt;</code>
 263 names a primitive earlier in the compilation unit and the statement is
 264 placed in global scope, instead of within a module. The semicolon is
 265 not part of a type attribute.
 266
 267 Note that attributes are also occasionally used for communication
 268 between processing steps. Processing steps that are aware of others
 269 may place attributes on netlist objects to communicate information to
 270 later steps.
 271
 272 Icarus Verilog also accepts the Verilog 2001 syntax for
 273 attributes. They have the same general meaning as with the <code>$attribute</code>
 274 syntax, but they are attached to objects by position instead of by
 275 name. Also, the key is a Verilog identifier instead of a string.
 276
 277 ===== Running iverilog =====
 278
 279 The preferred way to invoke the compiler is with the <code>iverilog(1)</code>
 280 command. This program invokes the preprocessor (<code>ivlpp</code>) and the
 281 compiler (<code>ivl</code>) with the proper command line options to get the job
 282 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.
 283
 284
 285 ==== Examples ====
 286
 287 Example: Compiling <code>hello.vl</code>
 288
 289 &lt;code verilog &quot;hello.vl&quot;&gt;
 290 module main();
 291
 292 initial
 293   begin
 294     $display(&quot;Hi there&quot;);
 295     $finish ;
 296   end
 297
 298 endmodule
 299 &lt;/code&gt;
 300
 301 Ensure that <code>iverilog</code> is on your search path, and the <code>vpi</code> library
 302 is available.
 303
 304 To compile the program:
 305
 306   iverilog hello.vl
 307
 308 (The above presumes that <code>/usr/local/include</code> and <code>/usr/local/lib</code> are
 309 part of the compiler search path, which is usually the case for gcc.)
 310
 311 To run the program:
 312
 313   ./a.out
 314
 315 You can use the <code>-o</code> switch to name the output command to be generated
 316 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.
 317
 318 ===== Unsupported Constructs =====
 319
 320 Icarus Verilog is in development---as such it still only supports a
 321 (growing) subset of Verilog.  Below is a description of some of the
 322 currently unsupported Verilog features. This list is not exhaustive,
 323 and does not account for errors in the compiler. See the Icarus
 324 Verilog web page for the current state of support for Verilog, and in
 325 particular, browse the bug report database for reported unsupported
 326 constructs.
 327
 328   * 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>.
 329
 330   * Specify blocks are parsed but ignored in general.
 331
 332   * <code>trireg</code> is not supported. <code>tri0</code> and <code>tri1</code> are supported.
 333
 334   * 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.
 335
 336   * 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>
 337
 338   * Event controls inside non-blocking assignments are not supported. i.e.: <code>a &lt;= @(posedge clk) b;</code>
 339
 340   * Macro arguments are not supported. <code>`define</code> macros are supported, but they cannot take arguments.
 341
 342 ==== Nonstandard Constructs or Behaviors ====
 343
 344 Icarus Verilog includes some features that are not part of the
 345 IEEE1364 standard, but have well defined meaning, and also sometimes
 346 gives nonstandard (but extended) meanings to some features of the
 347 language that are defined. See the <code>extensions.txt</code> documentation for
 348 more details.
 349
 350 &lt;code&gt;
 351     $is_signed(&lt;expr&gt;)
 352         This system function returns 1 if the expression contained is
 353         signed, or 0 otherwise. This is mostly of use for compiler
 354         regression tests.
 355
 356     $sizeof(&lt;expr&gt;)
 357     $bits(&lt;expr&gt;)
 358         The $bits system function returns the size in bits of the
 359         expression that is its argument. The result of this
 360         function is undefined if the argument doesn&#039;t have a
 361         self-determined size.
 362
 363         The $sizeof function is deprecated in favor of $bits, which is
 364         the same thing, but included in the SystemVerilog definition.
 365
 366     $simtime
 367         The $simtime system function returns as a 64bit value the
 368         simulation time, unscaled by the time units of local
 369         scope. This is different from the $time and $stime functions
 370         which return the scaled times. This function is added for
 371         regression testing of the compiler and run time, but can be
 372         used by applications who really want the simulation time.
 373
 374         Note that the simulation time can be confusing if there are
 375         lots of different `timescales within a design. It is not in
 376         general possible to predict what the simulation precision will
 377         turn out to be.
 378
 379     $mti_random()
 380     $mti_dist_uniform
 381         These functions are similar to the IEEE1364 standard $random
 382         functions, but they use the Mersenne Twister (MT19937)
 383         algorithm. This is considered an excellent random number
 384         generator, but does not generate the same sequence as the
 385         standardized $random.
 386
 387     Builtin system functions
 388
 389         Certain of the system functions have well defined meanings, so
 390         can theoretically be evaluated at compile time, instead of
 391         using runtime VPI code. Doing so means that VPI cannot
 392         override the definitions of functions handled in this
 393         manner. On the other hand, this makes them synthesizable, and
 394         also allows for more aggressive constant propagation. The
 395         functions handled in this manner are:
 396
 397                 $bits
 398                 $signed
 399                 $sizeof
 400                 $unsigned
 401
 402         Implementations of these system functions in VPI modules will
 403         be ignored.
 404
 405     Preprocessing Library Modules
 406
 407         Icarus Verilog does preprocess modules that are loaded from
 408         libraries via the -y mechanism. However, the only macros
 409         defined during compilation of that file are those that it
 410         defines itself (or includes) or that are defined on the
 411         command line or command file.
 412
 413         Specifically, macros defined in the non-library source files
 414         are not remembered when the library module is loaded. This is
 415         intentional. If it were otherwise, then compilation results
 416         might vary depending on the order that libraries are loaded,
 417         and that is too unpredictable.
 418
 419         It is said that some commercial compilers do allow macro
 420         definitions to span library modules. That&#039;s just plain weird.
 421
 422     Width in %t Time Formats
 423
 424         Standard Verilog does not allow width fields in the %t formats
 425         of display strings. For example, this is illegal:
 426
 427                 $display(&quot;Time is %0t&quot;, %time);
 428
 429         Standard Verilog instead relies on the $timeformat to
 430         completely specify the format.
 431
 432         Icarus Verilog allows the programmer to specify the field
 433         width. The &quot;%t&quot; format in Icarus Verilog works exactly as it
 434         does in standard Verilog. However, if the programmer chooses
 435         to specify a minimum width (i.e., &quot;%5t&quot;), then for that display
 436         Icarus Verilog will override the $timeformat minimum width and
 437         use the explicit minimum width.
 438
 439     vpiScope iterator on vpiScope objects.
 440
 441         In the VPI, the normal way to iterate over vpiScope objects
 442         contained within a vpiScope object, is the vpiInternalScope
 443         iterator. Icarus Verilog adds support for the vpiScope
 444         iterator of a vpiScope object, that iterates over *everything*
 445         the is contained in the current scope. This is useful in cases
 446         where one wants to iterate over all the objects in a scope
 447         without iterating over all the contained types explicitly.
 448
 449     time 0 race resolution.
 450
 451         Combinational logic is routinely modeled using always
 452         blocks. However, this can lead to race conditions if the
 453         inputs to the combinational block are initialized in initial
 454         statements. Icarus Verilog slightly modifies time 0 scheduling
 455         by arranging for always statements with ANYEDGE sensitivity
 456         lists to be scheduled before any other threads. This causes
 457         combinational always blocks to be triggered when the values in
 458         the sensitivity list are initialized by initial threads.
 459
 460     Nets with Types
 461
 462         Icarus Verilog support an extension syntax that allows nets
 463         and regs to be explicitly typed. The currently supported types
 464         are logic, bool and real. This implies that &quot;logic&quot; and &quot;bool&quot;
 465         are new keywords. Typical syntax is:
 466
 467         wire real foo = 1.0;
 468         reg logic bar, bat;
 469
 470         ... and so forth. The syntax can be turned off by using the
 471         -g2 flag to iverilog, and turned on explicitly with the -g2x
 472         flag to iverilog.
 473 &lt;/code&gt;
 474
 475 ===== Credits =====
 476
 477 Except where otherwise noted, Icarus Verilog, <code>ivl</code> and <code>ivlpp</code> are
 478 Copyright Stephen Williams. The proper notices are in the head of each
 479 file. However, I have early on received aid in the form of fixes,
 480 Verilog guidance, and especially testing from many people. Testers in
 481 particular include a larger community of people interested in a GPL
 482 Verilog for Linux.
 483 </p>
 484
 485 </div>
 486 </body>
 487 </html>