diff --git a/README.md b/README.md index 23e0dd2c28df91b4228ca19e4ec765480b9ac704..a2c36492cafda4f4424c3e2eedf34af025252b53 100644 --- a/README.md +++ b/README.md @@ -1,164 +1,147 @@ # Getting Started with EpicSim -EpicSim is a Verilog compiler. It is suitable for use as a -simulator. EpicSim is recommended to run under RedHat and Centos. -Instructions are generally applicable to all environments. +EpicSim is a Verilog compiler. It is suitable for use as a simulator and recommended to run under Red Hat and CentOS. Instructions in this document are generally applicable to all environments. -Project is developed based on icarus iverilog under LGPL. -Special thanks to Stephen Williams (steve@icarus.com). +The project is developed based on icarus iverilog under LGPL. Special thanks to Stephen Williams (steve@icarus.com). ## 1. Install From Source -In this case, see INSTALL_INSTRUCTION.txt that comes with the 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 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. + +### 1.1 Compile Time Prerequisites + +You need the following softwares to compile EpicSim from source on a UNIX-like system: + +- CMake +- GNU Make +- ISO C++ Compiler +- bison and flex +- gperf 3.0 or later +- readline 4.2 or later +- termcap +- bash + +### 1.2 Compilation + +Unpack the tar-ball and compile the source with the commands: +```bash + cd EpicSim + mkdir build + cd build + cmake .. + make install +``` +After the installtion, set the environment variables with the commands: +```bash + cd EpicSim + #bash + export PATH="target_installation_path/EpicSim/install/bin:$PATH" + #cshell + setenv PATH target_installation_path/EpicSim/install/bin:$PATH" +``` ## 2. Hello, World! -The first thing you want to do as a user is learn how to compile and -execute even the most trivial design. For the purposes of simulation, -we use as our example *the* most trivial simulation: +As a user, the first thing you want to do is probably learning how to compile and execute even the most trivial design. For simulation, we use the following design as an example: ```verilog module main; - initial begin $display("Hello, World"); $finish ; end - endmodule ``` -By a text editor (or copy hello.vl from the EpicSim examples -directory) arrange for this program to be in a text file, "hello.vl". -Next, compile this program with a command like this: +1. Arrange for the above program to be in a text file, `hello.vl` using a text editor or copy the `hello.vl` file from the EpicSim examples directory. +2. Compile the program with the `epicsim` command: + ```bash + % epicsim hello.vl + ``` +3. The results of this compile are placed into the `epicsim-run` file, and it is excuted: + ```bash + Hello, World + ``` +The compiled program can also be executed by two steps: ```bash -% epicsim hello.vl - Hello, World +% epicsim-driver hello.vl -o epicsim-run +% epicsim-vvp ./epicsim-run ``` -The results of this compile are placed into the file "epicsim-run", -and it is excuted. - -The compiled program can also be excuted like so: ```bash -% epicsim-driver hello.vl -o epicsim-run -% epicsim-vvp ./epicsim-run - Hello, World +Hello, World ``` -And there it is, the program has been executed. So what happened? The -first step, the "epicsim-driver" command, read and interpreted the source -file, then generated a compiled result. The compiled form may be -selected by command line switches, but the default form is the VVP -format, which is actually run by the "epicsim-vvp" command. - -The "epicsim-driver" and "epicsim-vvp" commands are the only commands -that users use to invoke EpicSim. What the compiler actually does is -controlled by command line switches. In our little example, we asked -the compiler to compile the source program to the default epicsim-vvp form, -which is in turn executed by the epicsim-vvp program. +And there it is, the program has been executed. So what happened? The first step, the `epicsim-driver` command, read and interpreted the source file, then generated a compiled result. The compiled form may be selected by command line switches, but the default form is `vvp`, which is actually run by the `epicsim-vvp` command. + +The `epicsim-driver` and `epicsim-vvp` commands are the only commands that users use to invoke EpicSim. What the compiler actually does is controlled by command line switches. In our little example, we asked the compiler to compile the source program to the default `vvp` form, which is in turn executed by the `epicsim-vvp` program. ## 3. How EpicSim Works -This tool includes a parser which reads in Verilog (plus extensions) -and generates an internal netlist. The netlist is passed to various -processing steps that transform the design to more optimal/practical -forms, then is passed to a code generator for final output. The -processing steps and the code generator are selected by command line -switches. +This tool includes a parser which reads in Verilog (plus extensions) and generates an internal netlist. The netlist is passed to various processing steps that transform the design to more optimal or practical 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 -There is a separate program, ivlpp, that does the preprocessing. This -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. +The preprocessing is done by a separate program, `ivlpp`. This 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 -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 -step. There may be dangling references, and it is not yet clear which -module is the root. +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` is mostly a direct reflection of the compilation step (see `pform.h`). 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.) +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.) ### 3.3 Elaboration -This phase takes the pform and generates a netlist. The driver selects -(by user request or lucky guess) the root module to elaborate, -resolves references and expands the instantiations to form the design -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 elaboration takes the `pform` and generates a netlist. The driver selects (by user request or lucky guess) the root module to elaborate, resolves references and expands the instantiations to form the design netlist (see `netlist.txt`). Final semantic checks and some simple optimizations are performed during elaboration. 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 -elaboration succeeds, the final netlist (i.e., after optimizations but -before code generation) will be dumped into the file named . +One can see a human-readable version of the final, elaborated and 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 ``. -Elaboration is performed in two steps: scopes and parameters -first, followed by the structural and behavioural elaboration. +The elaboration is performed in two steps: +- Scopes and parameters elaboration +- Structural and behavioural elaboration. #### 3.3.1 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. +The scope elaboration traverses the `pform` looking for scopes and parameters. A NetScope object tree is built 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 step. -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. +The tail of the elaborate_scope behaviour (after the pform is traversed) includes a scan of the NetScope object tree to locate the defparam assignments that were collected during scope elaboration. This is when the defparam overrides are applied to the parameters. #### 3.3.2 Netlist Elaboration -After the scopes and parameters are generated and the NetScope tree -fully formed, the elaboration runs through the pform again, this time -generating the structural and behavioural netlist. Parameters are -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. +After the scopes and parameters are generated and the NetScope project tree is fully formed, the elaboration traverses the `pform` again to generate the structural and behavioural netlist. The parameters are also elaborated and evaluated, so all the constants of code generation are now known locally and the netlist can be generated by simply passing through the `pform`. ### 3.4 Optimization -This is a collection of processing steps that perform -optimizations that do not depend on the target technology. Examples of -some useful transformations are - +The optimization is a collection of processing steps that perform optimizations that do not depend on the target technology. Examples of some useful transformations are as follows: +- Eliminate null effect circuitry +- Combinational reduction +- Constant propagation. - - eliminate null effect circuitry - - 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. ### 3.5 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 code generation 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 -through the design elements, calling target functions as the need arises -to generate actual output. +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 -command line. +The user selects the target code generator with the `-t` flag on the command line. ## 4 Unsupported Constructs -- Specify blocks are parsed but ignored in general. -- trireg is not supported. tri0 and tri1 are supported. -- tran primitives, i.e. tran, tranif1, tranif0, rtran, rtranif1 and rtranif0 are not supported. -- Event controls inside non-blocking assignments are not supported. i.e.: -```verilog -a <= @(posedge clk) b; -``` \ No newline at end of file +- Specify blocks are parsed but ignored in general. +- Trireg is not supported. `tri0` and `tri1` are supported. +- Tran primitives, i.e. `tran`, `tranif1`, `tranif0`, `rtran`, `rtranif1`, and `rtranif0` are not supported. +- Event controls inside non-blocking assignments are not supported, for example: + ```verilog + a <= @(posedge clk) b; + ``` + +## 5 Commonly Used Flags/Options + +`-o `: Output the compilation result file. +`-f `: Read in files with options. +`-D `: Assign a value to the macro. +`-s `: Set the root module to elaborate. +`T min|typ|max`: Select the timings (minimum, typical, and maximum) to use for simulation. The default set is typical. +