luke
/
iverilog
mirror of https://github.com/steveicarus/iverilog.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Convert README.txt to Markdown

This commit is contained in:
Nish Tahir 2022-09-13 20:08:16 -04:00
parent f881baeef1
commit 76047fd83a
No known key found for this signature in database
1 changed files with 115 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
README.txt → README.md
View File

@ -1,24 +1,24 @@
THE ICARUS VERILOG COMPILATION SYSTEM # The ICARUS Verilog Compilation System
Copyright 2000-2019 Stephen Williams Copyright 2000-2019 Stephen Williams
1.0 What is ICARUS Verilog? ## 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
described in the IEEE-1364 standard. Of course, it's not quite there described in the IEEE-1364 standard. Of course, it's not quite there
yet. It does currently handle a mix of structural and behavioural yet. It does currently handle a mix of structural and behavioural
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://iverilog.icarus.com/>. home page at http://iverilog.icarus.com/.
Icarus Verilog is not aimed at being a simulator in the traditional Icarus Verilog is not aimed at being a simulator in the traditional
sense, but a compiler that generates code employed by back-end sense, but a compiler that generates code employed by back-end
tools. tools.
For instructions on how to run Icarus Verilog, > For instructions on how to run Icarus Verilog, see the `iverilog` 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 the source, the build process is designed to be If you are starting from the source, the build process is designed to be
as simple as practical. Someone basically familiar with the target as simple as practical. Someone basically familiar with the target
@ -26,9 +26,9 @@ system and C/C++ compilation should be able to build the source
distribution with little effort. Some actual programming skills are distribution with little effort. Some actual programming skills are
not required, but helpful in case of problems. not required, but helpful in case of problems.
If you are building on Windows, see the mingw.txt file. > If you are building on 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:
@ -68,7 +68,7 @@ on a UNIX-like system:
- 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 or later - autoconf 2.53 or later
@ -76,25 +76,30 @@ the configure scripts.
or later versions are known to work, autoconf 2.13 is or later versions are known to work, autoconf 2.13 is
reported to *not* work. 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
(presumably, that is how you got to this README) and compile the source (presumably, that is how you got to this README) and compile the source
with the commands: with the commands:
```
./configure ./configure
make make
```
If you are building from git, you have to run the command below before If you are building from git, you have to run the command below before
compiling the source. This will generate the "configure" file, which is compiling the source. This will generate the "configure" file, which is
automatically done when building from tarball. automatically done when building from tarball.
```
sh autoconf.sh sh autoconf.sh
```
Normally, this command automatically figures out everything it needs Normally, this command automatically figures out everything it needs
to know. It generally works pretty well. There are a few flags to the to know. It generally works pretty well. There are a few flags to the
configure script that modify its behaviour: configure script that modify its behaviour:
```
--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
be compiled for install in /usr/local/bin, be compiled for install in /usr/local/bin,
@ -121,32 +126,37 @@ configure script that modify its behaviour:
x64_64-w64-mingw32 for building 64-bit Windows executables x64_64-w64-mingw32 for building 64-bit Windows executables
i686-w64-mingw32 for building 32-bit Windows executables i686-w64-mingw32 for building 32-bit Windows executables
Both options require installing the required mingw-w64 packages. Both options require installing the required mingw-w64 packages.
```
2.3 (Optional) Testing ### (Optional) Testing
To run a simple test before installation, execute To run a simple test before installation, execute
```
make check make check
```
The commands printed by this run might help you in running Icarus The commands printed by this run might help you in running Icarus
Verilog on your own Verilog sources before the package is installed Verilog on your own Verilog sources before the package is installed
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)
and generates an internal netlist. The netlist is passed to various and generates an internal netlist. The netlist is passed to various
@ -155,28 +165,28 @@ forms, then is passed to a code generator for final output. The
processing steps and the code generator are selected by command line processing steps and the code generator are selected by command line
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,
@ -185,29 +195,29 @@ 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 behavioural descriptions, as well as gates and wires. includes all the behavioural 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 performed in two steps: scopes and parameters Elaboration is performed in two steps: scopes and parameters
first, followed by the structural and behavioural elaboration. first, followed by the structural and behavioural 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 behaviour (after the pform is The tail of the elaborate_scope behaviour (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
@ -216,7 +226,7 @@ elaborated and evaluated by now so all the constants of code
generation are now known locally, so the netlist can be generated by generation are now known locally, so the netlist can be generated by
simply passing through the pform. simply passing through the pform.
3.4 Optimization ### Optimization
This is a collection of processing steps that perform This is a collection of processing steps that perform
optimizations that do not depend on the target technology. Examples of optimizations that do not depend on the target technology. Examples of
@ -226,46 +236,47 @@ some useful transformations are
- 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 the need arises through the design elements, calling target functions as the 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 favour of the > NOTE: The $attribute syntax will soon be deprecated in favour of the Verilog-2001 attribute syntax, which is cleaner and standardized.
Verilog-2001 attribute syntax, which is cleaner and standardized.
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.
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 the global scope, instead of within a module. The semicolon is placed in the global scope, instead of within a module. The semicolon is
not part of a type attribute. not part of a type attribute.
@ -280,18 +291,19 @@ 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 `iverilog`(1) man page for usage details.
4.1 EXAMPLES ## EXAMPLES
Example: Compiling "hello.vl" Example: Compiling `"hello.vl"`
```
------------------------ hello.vl ---------------------------- ------------------------ hello.vl ----------------------------
module main(); module main();
@ -304,25 +316,27 @@ initial
endmodule endmodule
-------------------------------------------------------------- --------------------------------------------------------------
```
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.
To compile the program: To compile the program:
```
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.)
To run the program: To run the program:
```
./a.out ./a.out
```
You can use the `-o` switch to name the output command to be generated
by the compiler. See the `iverilog`(1) man page.
You can use the "-o" switch to name the output command to be generated ## Unsupported Constructs
by the compiler. See the iverilog(1) man page.
5.0 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
@ -337,22 +351,22 @@ constructs.
- 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 every other context do work properly, including the V2001 form
"wire #5 foo = bar;" `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
@ -483,7 +497,7 @@ more details.
-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.
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