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 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
   4  lang="en" dir="ltr">
   5 <head>
   6   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   7   <title>geda:icarus_readme</title>
   8 <meta name="generator" content="DokuWiki Release rc2007-05-24" />
   9 <meta name="robots" content="noindex,nofollow" />
  10 <meta name="date" content="2007-05-24T22:27:27-0400" />
  11 <meta name="keywords" content="geda,icarus_readme" />
  12 <link rel="search" type="application/opensearchdescription+xml" href="http://geda.seul.org/wiki/lib/exe/opensearch.php" title="geda Wiki" />
  13 <link rel="start" href="http://geda.seul.org/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" />
  19 <link rel="stylesheet" media="all" type="text/css" href="lib/exe/css" />
  20 <link rel="stylesheet" media="screen" type="text/css" href="lib/exe/001css" />
  21 <link rel="stylesheet" media="print" type="text/css" href="lib/exe/002css" />
  22 </head>
  23 <body>
  24 <div class="dokuwiki export">
  25
  26
  27
  28 <h1><a name="the_icarus_verilog_compilation_system" id="the_icarus_verilog_compilation_system">The Icarus Verilog Compilation System</a></h1>
  29 <div class="level1">
  30 <pre class="code">              THE ICARUS VERILOG COMPILATION SYSTEM
  31                 Copyright 2000-2004 Stephen Williams
  32
  33
  34 1.0 What is ICARUS Verilog?
  35
  36 Icarus Verilog is intended to compile ALL of the Verilog HDL as
  37 described in the IEEE-1364 standard. Of course, it&#039;s not quite there
  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
  40 home page at &lt;http://www.icarus.com/eda/verilog&gt;.
  41
  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.
  48
  49     For instructions on how to run Icarus Verilog,
  50     see the ``iverilog&#039;&#039; man page.
  51
  52
  53 2.0 Building/Installing Icarus Verilog From Source
  54
  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.
  60
  61 If you are building for Windows, see the mingw.txt file.
  62
  63 2.1 Compile Time Prerequisites
  64
  65 You need the following software to compile Icarus Verilog from source
  66 on a UNIX-like system:
  67
  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.
  73
  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
  78           to work. MSVC++ 5 and 6 are known to definitely *not* work.
  79
  80         - bison and flex
  81
  82         - gperf 2.7
  83           The lexical analyzer doesn&#039;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.
  87
  88           A version problem with this program is the most common cause
  89           of difficulty. See the Icarus Verilog FAQ.
  90
  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.
  95
  96         - termcap
  97           The readline library in turn uses termcap.
  98
  99 If you are building from CVS, you will also need software to generate
 100 the configure scripts.
 101
 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.
 106
 107 2.2 Compilation
 108
 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:
 112
 113   ./configure
 114   make
 115
 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:
 119
 120         --without-ipal
 121             This turns off support for Icarus PAL, whether ipal
 122             libraries are installed or not.
 123
 124         --prefix=&lt;root&gt;
 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.
 128
 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.
 133
 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.
 138
 139 2.2.1 Special AMD64 Instructions
 140
 141 (The Icarus Verilog RPM for x86_64 is build using these instructions.)
 142
 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:
 147
 148   ./configure libdir64=&#039;$(prefix)/lib64&#039; vpidir1=vpi64 vpidir2=. --enable-vvp32
 149
 150 This reflects the convention on AMD64 systems that 64bit libraries go
 151 into lib64 directories. The &quot;--enable-vvp32&quot; also turns on 32bit
 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.
 155
 156 2.3 (Optional) Testing
 157
 158 To run a simple test before installation, execute
 159
 160   make check
 161
 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.
 165
 166 2.4 Installation
 167
 168 Now install the files in an appropriate place. (The makefiles by
 169 default install in /usr/local unless you specify a different prefix
 170 with the --prefix=&lt;path&gt; flag to the configure command.) You may need
 171 to do this as root to gain access to installation directories.
 172
 173   make install
 174
 175 2.5 Uninstallation
 176
 177 The generated Makefiles also include the uninstall target. This should
 178 remove all the files that ``make install&#039;&#039; creates.
 179
 180 3.0 How Icarus Verilog Works
 181
 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.
 188
 189 3.1 Preprocessing
 190
 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.
 196
 197 3.2 Parse
 198
 199 The Verilog compiler starts by parsing the Verilog source file. The
 200 output of the parse is a list of Module objects in &quot;pform&quot;. The pform
 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.
 204
 205 One can see a human readable version of the final pform by using the
 206 ``-P &lt;path&gt;&#039;&#039; flag to the compiler. This will cause iverilog to dump
 207 the pform into the file named &lt;path&gt;.
 208
 209 3.3 Elaboration
 210
 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.
 217
 218 The elaborate() function performs the elaboration.
 219
 220 One can see a human readable version of the final, elaborated and
 221 optimized netlist by using the ``-N &lt;path&gt;&#039;&#039; flag to the compiler. If
 222 elaboration succeeds, the final netlist (i.e., after optimizations but
 223 before code generation) will be dumped into the file named &lt;path&gt;.
 224
 225 Elaboration is actually performed in two steps: scopes and parameters
 226 first, followed by the structural and behavioral elaboration.
 227
 228 3.3.1 Scope Elaboration
 229
 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.
 235
 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.
 240
 241 3.3.2 Netlist Elaboration
 242
 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.
 249
 250 3.4 Optimization
 251
 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
 255
 256         - eliminate null effect circuitry
 257         - combinational reduction
 258         - constant propagation
 259
 260 The actual functions performed are specified on the ivl command line by
 261 the -F flags (see below).
 262
 263 3.5 Code Generation
 264
 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.
 268
 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.
 272
 273 The user selects the target code generator with the -t flag on the
 274 command line.
 275
 276 3.6 ATTRIBUTES
 277
 278     NOTE: The $attribute syntax will soon be deprecated in favor of the
 279     Verilog-2001 attribute syntax, which is cleaner and standardized.
 280
 281 The parser accepts, as an extension to Verilog, the $attribute module
 282 item. The syntax of the $attribute item is:
 283
 284         $attribute (&lt;identifier&gt;, &lt;key&gt;, &lt;value&gt;);
 285
 286 The $attribute keyword looks like a system task invocation. The
 287 difference here is that the parameters are more restricted then those
 288 of a system task. The &lt;identifier&gt; must be an identifier. This will be
 289 the item to get an attribute. The &lt;key&gt; and &lt;value&gt; are strings, not
 290 expressions, that give the key and the value of the attribute to be
 291 attached to the identified object.
 292
 293 Attributes are [&lt;key&gt; &lt;value&gt;] pairs and are used to communicate with
 294 the various processing steps. See the documentation for the processing
 295 step for a list of the pertinent attributes.
 296
 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
 299 for the attribute statement is the same, except that the &lt;identifier&gt;
 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.
 303
 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.
 308
 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.
 313
 314 4.0 Running iverilog
 315
 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.
 320
 321
 322 4.1 EXAMPLES
 323
 324 Example: Compiling &quot;hello.vl&quot;
 325
 326 ------------------------ hello.vl ----------------------------
 327 module main();
 328
 329 initial
 330   begin
 331     $display(&quot;Hi there&quot;);
 332     $finish ;
 333   end
 334
 335 endmodule
 336
 337 --------------------------------------------------------------
 338
 339 Ensure that &quot;iverilog&quot; is on your search path, and the vpi library
 340 is available.
 341
 342 To compile the program:
 343
 344   iverilog hello.vl
 345
 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.)
 348
 349 To run the program:
 350
 351   ./a.out
 352
 353 You can use the &quot;-o&quot; switch to name the output command to be generated
 354 by the compiler. See the iverilog(1) man page.
 355
 356 5.0 Unsupported Constructs
 357
 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.
 365
 366   - System functions are supported, but the return value is a little
 367     tricky. See SYSTEM FUNCTION TABLE FILES in the iverilog man page.
 368
 369   - Specify blocks are parsed but ignored in general.
 370
 371   - trireg is not supported. tri0 and tri1 are supported.
 372
 373   - tran primitives, i.e. tran, tranif1, tranif0, rtran, rtranif1
 374     and rtranif0 are not supported.
 375
 376   - Net delays, of the form &quot;wire #N foo;&quot; do not work. Delays in
 377     every other context do work properly, including the V2001 form
 378     &quot;wire #5 foo = bar;&quot;
 379
 380   - Event controls inside non-blocking assignments are not supported.
 381     i.e.: a &lt;= @(posedge clk) b;
 382
 383   - Macro arguments are not supported. `define macros are supported,
 384     but they cannot take arguments.
 385
 386 5.1 Nonstandard Constructs or Behaviors
 387
 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
 391 language that are defined. See the &quot;extensions.txt&quot; documentation for
 392 more details.
 393
 394     $is_signed(&lt;expr&gt;)
 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.
 398
 399     $sizeof(&lt;expr&gt;)
 400     $bits(&lt;expr&gt;)
 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&#039;t have a
 404         self-determined size.
 405
 406         The $sizeof function is deprecated in favor of $bits, which is
 407         the same thing, but included in the SystemVerilog definition.
 408
 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.
 416
 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.
 421
 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.
 429
 430     Builtin system functions
 431
 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:
 439
 440                 $bits
 441                 $signed
 442                 $sizeof
 443                 $unsigned
 444
 445         Implementations of these system functions in VPI modules will
 446         be ignored.
 447
 448     Preprocessing Library Modules
 449
 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.
 455
 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.
 461
 462         It is said that some commercial compilers do allow macro
 463         definitions to span library modules. That&#039;s just plain weird.
 464
 465     Width in %t Time Formats
 466
 467         Standard Verilog does not allow width fields in the %t formats
 468         of display strings. For example, this is illegal:
 469
 470                 $display(&quot;Time is %0t&quot;, %time);
 471
 472         Standard Verilog instead relies on the $timeformat to
 473         completely specify the format.
 474
 475         Icarus Verilog allows the programmer to specify the field
 476         width. The &quot;%t&quot; format in Icarus Verilog works exactly as it
 477         does in standard Verilog. However, if the programmer chooses
 478         to specify a minimum width (i.e., &quot;%5t&quot;), then for that display
 479         Icarus Verilog will override the $timeformat minimum width and
 480         use the explicit minimum width.
 481
 482     vpiScope iterator on vpiScope objects.
 483
 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.
 491
 492     time 0 race resolution.
 493
 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.
 502
 503     Nets with Types
 504
 505         Icarus Verilog support an extension syntax that allows nets
 506         and regs to be explicitly typed. The currently supported types
 507         are logic, bool and real. This implies that &quot;logic&quot; and &quot;bool&quot;
 508         are new keywords. Typical syntax is:
 509
 510         wire real foo = 1.0;
 511         reg logic bar, bat;
 512
 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.
 516
 517 6.0 CREDITS
 518
 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>
 525
 526 </div>
 527 </div>
 528 </body>
 529 </html>