This shows you the differences between two versions of the page.
Both sides previous revision Previous revision | Last revision Both sides next revision | ||
geda:icarus_readme [2014/04/14 08:58] rlutz Update README to latest version (20130827 snapshot) |
geda:icarus_readme [2014/04/14 09:39] rlutz Use wiki syntax (part 1) |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | [[:|gEDA]] >> [[Documentation]] >> [[icarus|Icarus Verilog]] >> [[|The Icarus Verilog Compilation System]] | ||
+ | |||
====== The Icarus Verilog Compilation System ====== | ====== The Icarus Verilog Compilation System ====== | ||
- | <code> THE ICARUS VERILOG COMPILATION SYSTEM | + | Copyright 2000-2004 Stephen Williams |
- | Copyright 2000-2004 Stephen Williams | + | |
- | + | ===== What is ICARUS Verilog? ===== | |
- | 1.0 What is ICARUS Verilog? | + | |
Icarus Verilog is intended to compile ALL of the Verilog HDL as | Icarus Verilog is intended to compile ALL of the Verilog HDL as | ||
Line 16: | Line 16: | ||
tools. | tools. | ||
- | For instructions on how to run Icarus Verilog, | + | For instructions on how to run Icarus Verilog, see the ''iverilog'' [[icarus_mp|man page]]. |
- | see the ``iverilog'' man page. | + | |
- | 2.0 Building/Installing Icarus Verilog From Source | + | ===== Building/Installing Icarus Verilog From Source ===== |
If you are starting from source, the build process is designed to be | If you are starting from source, the build process is designed to be | ||
Line 30: | Line 29: | ||
If you are building for Windows, see the mingw.txt file. | If you are building for Windows, see the mingw.txt file. | ||
- | 2.1 Compile Time Prerequisites | + | ==== Compile Time Prerequisites ==== |
You need the following software to compile Icarus Verilog from source | You need the following software to compile Icarus Verilog from source | ||
on a UNIX-like system: | on a UNIX-like system: | ||
- | - GNU Make | + | * **GNU Make**\\ 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. |
- | 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. | + | |
- | + | ||
- | - ISO C++ Compiler | + | |
- | The ivl and ivlpp 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. | + | |
- | - bison and flex | + | * **ISO C++ Compiler**\\ The ivl and ivlpp 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. |
- | - gperf 2.7 | + | * **bison and flex** |
- | 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. | + | |
- | A version problem with this program is the most common cause | + | * **gperf 2.7**\\ 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.\\ A version problem with this program is the most common cause of difficulty. See the Icarus Verilog FAQ. |
- | of difficulty. See the Icarus Verilog FAQ. | + | |
- | - readline 4.2 | + | * **readline 4.2**\\ On Linux systems, this usually means the readline-devel rpm. In any case, it is the development headers of readline that are needed. |
- | On Linux systems, this usually means the readline-devel | + | |
- | rpm. In any case, it is the development headers of readline | + | |
- | that are needed. | + | |
- | - termcap | + | * **termcap**\\ The readline library in turn uses termcap. |
- | The readline library in turn uses termcap. | + | |
If you are building from git, you will also need software to generate | If you are building from git, you will also need software to generate | ||
the configure scripts. | the configure scripts. | ||
- | - autoconf 2.53 | + | * **autoconf 2.53**\\ This generates configure scripts from configure.in. The 2.53 or later versions are known to work, autoconf 2.13 is reported to *not* work. |
- | This generates configure scripts from configure.in. The 2.53 | + | |
- | or later versions are known to work, autoconf 2.13 is | + | |
- | reported to *not* work. | + | |
- | 2.2 Compilation | + | ==== Compilation ==== |
Unpack the tar-ball and cd into the verilog-######### directory | Unpack the tar-ball and cd into the verilog-######### directory | ||
Line 87: | Line 64: | ||
configure script that modify its behavior: | configure script that modify its behavior: | ||
+ | <code> | ||
--prefix=<root> | --prefix=<root> | ||
The default is /usr/local, which causes the tool suite to | The default is /usr/local, which causes the tool suite to | ||
Line 107: | Line 85: | ||
with the same prefix but different suffix are guaranteed | with the same prefix but different suffix are guaranteed | ||
to not interfere with each other. | to not interfere with each other. | ||
+ | </code> | ||
- | 2.3 (Optional) Testing | + | ==== (Optional) Testing ==== |
To run a simple test before installation, execute | To run a simple test before installation, execute | ||
Line 118: | Line 97: | ||
by root. | by root. | ||
- | 2.4 Installation | + | ==== Installation ==== |
Now install the files in an appropriate place. (The makefiles by | Now install the files in an appropriate place. (The makefiles by | ||
- | default install in /usr/local unless you specify a different prefix | + | default install in ''/usr/local'' unless you specify a different prefix |
- | with the --prefix=<path> flag to the configure command.) You may need | + | with the ''--prefix=<path>'' flag to the configure command.) You may need |
to do this as root to gain access to installation directories. | to do this as root to gain access to installation directories. | ||
make install | make install | ||
- | 2.5 Uninstallation | + | ==== Uninstallation ==== |
- | The generated Makefiles also include the uninstall target. This should | + | The generated Makefiles also include the ''uninstall'' target. This should |
- | remove all the files that ``make install'' creates. | + | remove all the files that ''make install'' creates. |
- | 3.0 How Icarus Verilog Works | + | ===== How Icarus Verilog Works ===== |
This tool includes a parser which reads in Verilog (plus extensions) | This tool includes a parser which reads in Verilog (plus extensions) | ||
Line 141: | Line 120: | ||
switches. | switches. | ||
- | 3.1 Preprocessing | + | ==== Preprocessing ==== |
There is a separate program, ivlpp, that does the preprocessing. This | There is a separate program, ivlpp, that does the preprocessing. This | ||
Line 147: | Line 126: | ||
output that is equivalent but without the directives. The output is a | output that is equivalent but without the directives. The output is a | ||
single file with line number directives, so that the actual compiler | single file with line number directives, so that the actual compiler | ||
- | only sees a single input file. See ivlpp/ivlpp.txt for details. | + | only sees a single input file. See ''ivlpp/ivlpp.txt'' for details. |
- | 3.2 Parse | + | ==== Parse ==== |
The Verilog compiler starts by parsing the Verilog source file. The | The Verilog compiler starts by parsing the Verilog source file. The | ||
output of the parse is a list of Module objects in "pform". The pform | output of the parse is a list of Module objects in "pform". The pform | ||
- | (see pform.h) is mostly a direct reflection of the compilation | + | (see ''pform.h'') is mostly a direct reflection of the compilation |
step. There may be dangling references, and it is not yet clear which | step. There may be dangling references, and it is not yet clear which | ||
module is the root. | module is the root. | ||
One can see a human readable version of the final pform by using the | One can see a human readable version of the final pform by using the | ||
- | ``-P <path>'' flag to the ``ivl'' subcommand. This will cause ivl | + | ''-P <path>'' flag to the ''ivl'' subcommand. This will cause ivl |
- | to dump the pform into the file named <path>. (Note that this is not | + | to dump the pform into the file named ''<path>''. (Note that this is not |
- | normally done, unless debugging the ``ivl'' subcommand.) | + | normally done, unless debugging the ''ivl'' subcommand.) |
- | 3.3 Elaboration | + | ==== Elaboration ==== |
This phase takes the pform and generates a netlist. The driver selects | This phase takes the pform and generates a netlist. The driver selects | ||
(by user request or lucky guess) the root module to elaborate, | (by user request or lucky guess) the root module to elaborate, | ||
resolves references and expands the instantiations to form the design | resolves references and expands the instantiations to form the design | ||
- | netlist. (See netlist.txt.) Final semantic checks are performed during | + | netlist. (See ''netlist.txt''.) Final semantic checks are performed during |
elaboration, and some simple optimizations are performed. The netlist | elaboration, and some simple optimizations are performed. The netlist | ||
includes all the behavioral descriptions, as well as gates and wires. | includes all the behavioral descriptions, as well as gates and wires. | ||
Line 174: | Line 153: | ||
One can see a human readable version of the final, elaborated and | One can see a human readable version of the final, elaborated and | ||
- | optimized netlist by using the ``-N <path>'' flag to the compiler. If | + | optimized netlist by using the ''-N <path>'' flag to the compiler. If |
elaboration succeeds, the final netlist (i.e., after optimizations but | elaboration succeeds, the final netlist (i.e., after optimizations but | ||
- | before code generation) will be dumped into the file named <path>. | + | before code generation) will be dumped into the file named ''<path>''. |
Elaboration is actually performed in two steps: scopes and parameters | Elaboration is actually performed in two steps: scopes and parameters | ||
first, followed by the structural and behavioral elaboration. | first, followed by the structural and behavioral elaboration. | ||
- | 3.3.1 Scope Elaboration | + | === Scope Elaboration === |
This pass scans through the pform looking for scopes and parameters. A | This pass scans through the pform looking for scopes and parameters. A | ||
tree of NetScope objects is built up and placed in the Design object, | tree of NetScope objects is built up and placed in the Design object, | ||
with the root module represented by the root NetScope object. The | with the root module represented by the root NetScope object. The | ||
- | elab_scope.cc file contains most of the code for handling this phase. | + | ''elab_scope.cc'' file contains most of the code for handling this phase. |
The tail of the elaborate_scope behavior (after the pform is | The tail of the elaborate_scope behavior (after the pform is | ||
Line 193: | Line 172: | ||
the defparam overrides are applied to the parameters. | the defparam overrides are applied to the parameters. | ||
- | 3.3.2 Netlist Elaboration | + | === Netlist Elaboration === |
After the scopes and parameters are generated and the NetScope tree | After the scopes and parameters are generated and the NetScope tree | ||
Line 202: | Line 181: | ||
simply passing through the pform. | simply passing through the pform. | ||
- | 3.4 Optimization | + | ==== Optimization ==== |
This is actually a collection of processing steps that perform | This is actually a collection of processing steps that perform | ||
Line 208: | Line 187: | ||
some useful transformations are | some useful transformations are | ||
- | - eliminate null effect circuitry | + | * eliminate null effect circuitry |
- | - combinational reduction | + | * combinational reduction |
- | - constant propagation | + | * constant propagation |
The actual functions performed are specified on the ivl command line by | The actual functions performed are specified on the ivl command line by | ||
- | the -F flags (see below). | + | the ''-F'' flags (see below). |
- | 3.5 Code Generation | + | ==== Code Generation ==== |
This step takes the design netlist and uses it to drive the code | This step takes the design netlist and uses it to drive the code | ||
- | generator (see target.h). This may require transforming the | + | generator (see ''target.h''). This may require transforming the |
design to suit the technology. | design to suit the technology. | ||
- | The emit() method of the Design class performs this step. It runs | + | The ''emit()'' method of the ''Design'' class performs this step. It runs |
through the design elements, calling target functions as need arises | through the design elements, calling target functions as need arises | ||
to generate actual output. | to generate actual output. | ||
- | The user selects the target code generator with the -t flag on the | + | The user selects the target code generator with the ''-t'' flag on the |
command line. | command line. | ||
- | 3.6 ATTRIBUTES | + | ==== Attributes ==== |
- | NOTE: The $attribute syntax will soon be deprecated in favor of the | + | <note tip> |
- | Verilog-2001 attribute syntax, which is cleaner and standardized. | + | The ''$attribute'' syntax will soon be deprecated in favor of the |
+ | Verilog-2001 attribute syntax, which is cleaner and standardized. | ||
+ | </note> | ||
The parser accepts, as an extension to Verilog, the $attribute module | The parser accepts, as an extension to Verilog, the $attribute module | ||
Line 266: | Line 247: | ||
name. Also, the key is a Verilog identifier instead of a string. | name. Also, the key is a Verilog identifier instead of a string. | ||
- | 4.0 Running iverilog | + | ===== Running iverilog ===== |
The preferred way to invoke the compiler is with the iverilog(1) | The preferred way to invoke the compiler is with the iverilog(1) | ||
Line 274: | Line 255: | ||
- | 4.1 EXAMPLES | + | ==== Examples ==== |
Example: Compiling "hello.vl" | Example: Compiling "hello.vl" | ||
Line 308: | Line 289: | ||
by the compiler. See the iverilog(1) man page. | by the compiler. See the iverilog(1) man page. | ||
- | 5.0 Unsupported Constructs | + | ===== Unsupported Constructs ===== |
Icarus Verilog is in development - as such it still only supports a | Icarus Verilog is in development - as such it still only supports a | ||
Line 338: | Line 319: | ||
but they cannot take arguments. | but they cannot take arguments. | ||
- | 5.1 Nonstandard Constructs or Behaviors | + | ==== Nonstandard Constructs or Behaviors ==== |
Icarus Verilog includes some features that are not part of the | Icarus Verilog includes some features that are not part of the | ||
Line 469: | Line 450: | ||
flag to iverilog. | flag to iverilog. | ||
- | 6.0 CREDITS | + | ===== Credits ===== |
Except where otherwise noted, Icarus Verilog, ivl and ivlpp are | Except where otherwise noted, Icarus Verilog, ivl and ivlpp are | ||
Line 476: | Line 457: | ||
Verilog guidance, and especially testing from many people. Testers in | Verilog guidance, and especially testing from many people. Testers in | ||
particular include a larger community of people interested in a GPL | particular include a larger community of people interested in a GPL | ||
- | Verilog for Linux.</code> | + | Verilog for Linux. |