This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
geda:icarus_readme [2014/04/14 08:58] rlutz Update README to latest version (20130827 snapshot) |
geda:icarus_readme [2014/04/14 09:57] (current) rlutz Use wiki syntax (part 2) |
||
---|---|---|---|
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 10: | Line 10: | ||
yet. It does currently handle a mix of structural and behavioral | yet. It does currently handle a mix of structural and behavioral | ||
constructs. For a view of the current state of Icarus Verilog, see its | constructs. For a view of the current state of Icarus Verilog, see its | ||
- | home page at <http://www.icarus.com/eda/verilog>. | + | home page at http://www.icarus.com/eda/verilog. |
Icarus Verilog is not aimed at being a simulator in the traditional | Icarus Verilog is not aimed at being a simulator in the traditional | ||
Line 16: | Line 16: | ||
tools. | tools. | ||
- | For instructions on how to run Icarus Verilog, | + | For instructions on how to run Icarus Verilog, see the ''[[icarus_mp|iverilog(1)]]'' 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 and compile the source |
- | (presumably that is how you got to this README) and compile the source | + | |
with the commands: | with the commands: | ||
Line 87: | Line 63: | ||
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 84: | ||
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 96: | ||
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 119: | ||
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 |
- | program implements the `include and `define directives producing | + | program implements the ''`include'' and ''`define'' directives producing |
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. | ||
- | The elaborate() function performs the elaboration. | + | The ''elaborate()'' function performs the elaboration. |
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 |
- | traversed) includes a scan of the NetScope tree to locate defparam | + | traversed) includes a scan of the ''NetScope'' tree to locate defparam |
assignments that were collected during scope elaboration. This is when | assignments that were collected during scope elaboration. This is when | ||
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 |
fully formed, the elaboration runs through the pform again, this time | fully formed, the elaboration runs through the pform again, this time | ||
generating the structural and behavioral netlist. Parameters are | generating the structural and behavioral netlist. Parameters are | ||
Line 202: | Line 180: | ||
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 186: | ||
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 |
- | item. The syntax of the $attribute item is: | + | item. The syntax of the ''$attribute'' item is: |
$attribute (<identifier>, <key>, <value>); | $attribute (<identifier>, <key>, <value>); | ||
- | The $attribute keyword looks like a system task invocation. The | + | The ''$attribute'' keyword looks like a system task invocation. The |
difference here is that the parameters are more restricted than those | difference here is that the parameters are more restricted than those | ||
- | of a system task. The <identifier> must be an identifier. This will be | + | of a system task. The ''<identifier>'' must be an identifier. This will be |
- | the item to get an attribute. The <key> and <value> are strings, not | + | the item to get an attribute. The ''<key>'' and ''<value>'' are strings, not |
expressions, that give the key and the value of the attribute to be | expressions, that give the key and the value of the attribute to be | ||
attached to the identified object. | attached to the identified object. | ||
- | Attributes are [<key> <value>] pairs and are used to communicate with | + | Attributes are ''[<key> <value>]'' pairs and are used to communicate with |
the various processing steps. See the documentation for the processing | the various processing steps. See the documentation for the processing | ||
step for a list of the pertinent attributes. | step for a list of the pertinent attributes. | ||
Line 251: | Line 231: | ||
Attributes can also be applied to gate types. When this is done, the | Attributes can also be applied to gate types. When this is done, the | ||
attribute is given to every instantiation of the primitive. The syntax | attribute is given to every instantiation of the primitive. The syntax | ||
- | for the attribute statement is the same, except that the <identifier> | + | for the attribute statement is the same, except that the ''<identifier>'' |
names a primitive earlier in the compilation unit and the statement is | names a primitive earlier in the compilation unit and the statement is | ||
placed in global scope, instead of within a module. The semicolon is | placed in global scope, instead of within a module. The semicolon is | ||
Line 262: | Line 242: | ||
Icarus Verilog also accepts the Verilog 2001 syntax for | Icarus Verilog also accepts the Verilog 2001 syntax for | ||
- | attributes. They have the same general meaning as with the $attribute | + | attributes. They have the same general meaning as with the ''$attribute'' |
syntax, but they are attached to objects by position instead of by | syntax, but they are attached to objects by position instead of by | ||
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)'' |
- | command. This program invokes the preprocessor (ivlpp) and the | + | command. This program invokes the preprocessor (''ivlpp'') and the |
- | compiler (ivl) with the proper command line options to get the job | + | compiler (''ivl'') with the proper command line options to get the job |
- | done in a friendly way. See the iverilog(1) man page for usage details. | + | done in a friendly way. See the ''[[icarus_mp|iverilog(1)]]'' man page for usage details. |
- | 4.1 EXAMPLES | + | ==== Examples ==== |
- | Example: Compiling "hello.vl" | + | Example: Compiling ''hello.vl'' |
- | ------------------------ hello.vl ---------------------------- | + | <code verilog "hello.vl"> |
module main(); | module main(); | ||
Line 288: | Line 268: | ||
endmodule | endmodule | ||
+ | </code> | ||
- | -------------------------------------------------------------- | + | Ensure that ''iverilog'' is on your search path, and the ''vpi'' library |
- | + | ||
- | Ensure that "iverilog" is on your search path, and the vpi library | + | |
is available. | is available. | ||
Line 298: | Line 277: | ||
iverilog hello.vl | iverilog hello.vl | ||
- | (The above presumes that /usr/local/include and /usr/local/lib are | + | (The above presumes that ''/usr/local/include'' and ''/usr/local/lib'' are |
part of the compiler search path, which is usually the case for gcc.) | part of the compiler search path, which is usually the case for gcc.) | ||
Line 305: | Line 284: | ||
./a.out | ./a.out | ||
- | You can use the "-o" switch to name the output command to be generated | + | You can use the ''-o'' switch to name the output command to be generated |
- | by the compiler. See the iverilog(1) man page. | + | by the compiler. See the ''[[icarus_mp|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 |
(growing) subset of Verilog. Below is a description of some of the | (growing) subset of Verilog. Below is a description of some of the | ||
currently unsupported Verilog features. This list is not exhaustive, | currently unsupported Verilog features. This list is not exhaustive, | ||
Line 318: | Line 297: | ||
constructs. | constructs. | ||
- | - System functions are supported, but the return value is a little | + | * System functions are supported, but the return value is a little tricky. See SYSTEM FUNCTION TABLE FILES in the [[icarus_mp|iverilog man page]]. |
- | tricky. See SYSTEM FUNCTION TABLE FILES in the iverilog man page. | + | |
- | - Specify blocks are parsed but ignored in general. | + | * Specify blocks are parsed but ignored in general. |
- | - trireg is not supported. tri0 and tri1 are supported. | + | * ''trireg'' is not supported. ''tri0'' and ''tri1'' are supported. |
- | - tran primitives, i.e. tran, tranif1, tranif0, rtran, rtranif1 | + | * tran primitives, i.e. ''tran'', ''tranif1'', ''tranif0'', ''rtran'', ''rtranif1'' and ''rtranif0'' are not supported. |
- | and rtranif0 are not supported. | + | |
- | - Net delays, of the form "wire #N foo;" do not work. Delays in | + | * Net delays, of the form ''wire #N foo;'' do not work. Delays in every other context do work properly, including the V2001 form ''wire #5 foo = bar;'' |
- | every other context do work properly, including the V2001 form | + | |
- | "wire #5 foo = bar;" | + | |
- | - Event controls inside non-blocking assignments are not supported. | + | * Event controls inside non-blocking assignments are not supported. i.e.: ''a <= @(posedge clk) b;'' |
- | i.e.: a <= @(posedge clk) b; | + | |
- | - Macro arguments are not supported. `define macros are supported, | + | * Macro arguments are not supported. ''`define'' macros are supported, 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 | ||
IEEE1364 standard, but have well defined meaning, and also sometimes | IEEE1364 standard, but have well defined meaning, and also sometimes | ||
gives nonstandard (but extended) meanings to some features of the | gives nonstandard (but extended) meanings to some features of the | ||
- | language that are defined. See the "extensions.txt" documentation for | + | language that are defined. See the ''extensions.txt'' documentation for |
more details. | more details. | ||
+ | <code> | ||
$is_signed(<expr>) | $is_signed(<expr>) | ||
This system function returns 1 if the expression contained is | This system function returns 1 if the expression contained is | ||
Line 468: | Line 442: | ||
-g2 flag to iverilog, and turned on explicitly with the -g2x | -g2 flag to iverilog, and turned on explicitly with the -g2x | ||
flag to iverilog. | flag to iverilog. | ||
+ | </code> | ||
- | 6.0 CREDITS | + | ===== Credits ===== |
- | Except where otherwise noted, Icarus Verilog, ivl and ivlpp are | + | Except where otherwise noted, Icarus Verilog, ''ivl'' and ''ivlpp'' are |
Copyright Stephen Williams. The proper notices are in the head of each | Copyright Stephen Williams. The proper notices are in the head of each | ||
file. However, I have early on received aid in the form of fixes, | file. However, I have early on received aid in the form of fixes, | ||
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. |