diff --git a/README.txt b/README.md similarity index 75% rename from README.txt rename to README.md index d04dab88c..53a6dc842 100644 --- a/README.txt +++ b/README.md @@ -1,24 +1,24 @@ - THE ICARUS VERILOG COMPILATION SYSTEM - Copyright 2000-2019 Stephen Williams +# The ICARUS Verilog Compilation System + +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 described in the IEEE-1364 standard. Of course, it's not quite there yet. It does currently handle a mix of structural and behavioural constructs. For a view of the current state of Icarus Verilog, see its -home page at . +home page at http://iverilog.icarus.com/. Icarus Verilog is not aimed at being a simulator in the traditional sense, but a compiler that generates code employed by back-end tools. - For instructions on how to run Icarus Verilog, - see the ``iverilog'' man page. +> For instructions on how to run Icarus Verilog, 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 as simple as practical. Someone basically familiar with the target @@ -26,75 +26,80 @@ system and C/C++ compilation should be able to build the source distribution with little effort. Some actual programming skills are 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 on a UNIX-like system: - - 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. +- 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. - - 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. +- 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 - OSX note: bison 2.3 shipped with MacOS including Catalina generates - broken code, but bison 3+ works. We recommend using the Fink - project version of bison and flex (finkproject.org), brew version - works fine either. +- bison and flex + OSX note: bison 2.3 shipped with MacOS including Catalina generates + broken code, but bison 3+ works. We recommend using the Fink + project version of bison and flex (finkproject.org), brew version + works fine either. - - gperf 3.0 or later - 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. +- gperf 3.0 or later + 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. + A version problem with this program is the most common cause + of difficulty. See the Icarus Verilog FAQ. - - readline 4.2 or later - On Linux systems, this usually means the readline-devel - rpm. In any case, it is the development headers of readline - that are needed. +- readline 4.2 or later + On Linux systems, this usually means the readline-devel + rpm. In any case, it is the development headers of readline + that are needed. - - termcap - The readline library, in turn, uses termcap. +- termcap + The readline library, in turn, uses termcap. -If you are building from git, you will also need software to generate -the configure scripts. + > If you are building from git, you will also need software to generate + the configure scripts. - - autoconf 2.53 or later - This generates configure scripts from configure.ac. The 2.53 - or later versions are known to work, autoconf 2.13 is - reported to *not* work. +- autoconf 2.53 or later + This generates configure scripts from configure.ac. 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 (presumably, that is how you got to this README) and compile the source with the commands: +``` ./configure make +``` 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 automatically done when building from tarball. +``` sh autoconf.sh +``` Normally, this command automatically figures out everything it needs to know. It generally works pretty well. There are a few flags to the configure script that modify its behaviour: +``` --prefix= The default is /usr/local, which causes the tool suite to 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 i686-w64-mingw32 for building 32-bit Windows executables Both options require installing the required mingw-w64 packages. +``` -2.3 (Optional) Testing +### (Optional) Testing To run a simple test before installation, execute +``` make check +``` The commands printed by this run might help you in running Icarus Verilog on your own Verilog sources before the package is installed by root. -2.4 Installation +### Installation Now install the files in an appropriate place. (The makefiles by default install in /usr/local unless you specify a different prefix -with the --prefix= flag to the configure command.) You may need +with the `--prefix=` flag to the configure command.) You may need to do this as root to gain access to installation directories. +``` make install +``` -2.5 Uninstallation +### Uninstallation 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) 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 switches. -3.1 Preprocessing +### Preprocessing 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 single file with line number directives, so that the actual compiler 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 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 module is the root. One can see a human-readable version of the final pform by using the -``-P '' flag to the ``ivl'' subcommand. This will cause ivl -to dump the pform into the file named . (Note that this is not -normally done, unless debugging the ``ivl'' subcommand.) +`-P ` flag to the `ivl` subcommand. This will cause ivl +to dump the pform into the file named ``. (Note that this is not +normally done, unless debugging the `ivl` subcommand.) -3.3 Elaboration +### Elaboration This phase takes the pform and generates a netlist. The driver selects (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 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 -optimized netlist by using the ``-N '' flag to the compiler. If +optimized netlist by using the `-N ` flag to the compiler. If elaboration succeeds, the final netlist (i.e., after optimizations but -before code generation) will be dumped into the file named . +before code generation) will be dumped into the file named ``. Elaboration is performed in two steps: scopes and parameters 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 tree of NetScope objects is built up and placed in the Design object, 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 traversed) includes a scan of the NetScope tree to locate defparam assignments that were collected during scope elaboration. This is when 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 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 simply passing through the pform. -3.4 Optimization +### Optimization This is a collection of processing steps that perform optimizations that do not depend on the target technology. Examples of @@ -226,46 +236,47 @@ some useful transformations are - combinational reduction - constant propagation -The actual functions performed are specified on the ivl command line by -the -F flags (see below). +The actual functions performed are specified on the `ivl` command line by +the `-F` flags (see below). -3.5 Code Generation +### Code Generation This step takes the design netlist and uses it to drive the code generator (see target.h). This may require transforming the 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 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. -3.6 ATTRIBUTES +### ATTRIBUTES - NOTE: The $attribute syntax will soon be deprecated in favour of the - Verilog-2001 attribute syntax, which is cleaner and standardized. +> NOTE: The $attribute syntax will soon be deprecated in favour of the Verilog-2001 attribute syntax, which is cleaner and standardized. The parser accepts, as an extension to Verilog, the $attribute module item. The syntax of the $attribute item is: +``` $attribute (, , ); +``` The $attribute keyword looks like a system task invocation. The difference here is that the parameters are more restricted than those -of a system task. The must be an identifier. This will be -the item to get an attribute. The and are strings, not +of a system task. The `` must be an identifier. This will be +the item to get an attribute. The `` and `` are strings, not expressions, that give the key and the value of the attribute to be attached to the identified object. -Attributes are [ ] pairs and are used to communicate with +Attributes are `[ ]` pairs and are used to communicate with the various processing steps. See the documentation for the processing step for a list of the pertinent attributes. Attributes can also be applied to gate types. When this is done, the attribute is given to every instantiation of the primitive. The syntax -for the attribute statement is the same, except that the +for the attribute statement is the same, except that the `` 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 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 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 -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. +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. -4.1 EXAMPLES +## EXAMPLES -Example: Compiling "hello.vl" +Example: Compiling `"hello.vl"` +``` ------------------------ hello.vl ---------------------------- module main(); @@ -304,25 +316,27 @@ initial 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. To compile the program: - iverilog hello.vl - +``` + iverilog hello.vl +``` (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.) To run the program: +``` ./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 -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 (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. - - 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 - and rtranif0 are not supported. + - tran primitives, i.e. `tran`, `tranif1`, `tranif0`, `rtran`, `rtranif1` + 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;" + `wire #5 foo = bar;` - 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. -5.1 Nonstandard Constructs or Behaviors +## Nonstandard Constructs or Behaviors Icarus Verilog includes some features that are not part of the 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 flag to iverilog. -6.0 CREDITS +## CREDITS Except where otherwise noted, Icarus Verilog, ivl and ivlpp are Copyright Stephen Williams. The proper notices are in the head of each