Added $alu support to test_cell
[yosys.git] / README
diff --git a/README b/README
index 2277ef129f210ba996d830f023499e618578821d..2e713ffef40c1639b611c6a44a699236b75a65f0 100644 (file)
--- a/README
+++ b/README
@@ -56,20 +56,15 @@ and TCL for the scripting functionality. The extensive test suite requires
 Icarus Verilog. For example on Ubuntu Linux 12.04 LTS the following commands
 will install all prerequisites for building yosys:
 
-       $ sudo apt-get install git
-       $ sudo apt-get install g++
-       $ sudo apt-get install clang
-       $ sudo apt-get install make
-       $ sudo apt-get install bison
-       $ sudo apt-get install flex
-       $ sudo apt-get install libreadline-dev
-       $ sudo apt-get install tcl8.5-dev
-       $ sudo apt-get install minisat
-       $ sudo apt-get install zlib1g-dev
-       $ sudo apt-get install libqt4-dev
-       $ sudo apt-get install mercurial
-       $ sudo apt-get install iverilog
-       $ sudo apt-get install graphviz
+       $ yosys_deps="git g++ clang make bison flex libreadline-dev
+                     tcl8.5-dev zlib1g-dev libqt4-dev libffi-dev
+                     mercurial iverilog graphviz"
+       $ sudo apt-get install $yosys_deps
+
+There are also pre-compiled packages for Yosys on Ubuntu. Visit the Yosys
+download page to learn more about this:
+
+       http://www.clifford.at/yosys/download.html 
 
 To configure the build system to use a specific set of compiler and
 build configuration, use one of
@@ -82,7 +77,8 @@ For other compilers and build configurations it might be
 necessary to make some changes to the config section of the
 Makefile.
 
-       $ vi Makefile
+       $ vi Makefile             ..or..
+       $ vi Makefile.conf
 
 To build Yosys simply type 'make' in this directory.
 
@@ -90,13 +86,8 @@ To build Yosys simply type 'make' in this directory.
        $ make test
        $ sudo make install
 
-If you encounter any problems during build, make sure to check the section
-"Workarounds for known build problems" at the end of this README file.
-
-To also build and install ABC (recommended) use the following commands:
-
-       $ make abc
-       $ sudo make install-abc
+Note that this also downloads, builds and installs ABC (using yosys-abc
+as executeable name).
 
 Yosys can be used with the interactive command shell, with
 synthesis scripts or with command line arguments. Let's perform
@@ -118,6 +109,10 @@ writing the design to the console in yosys's internal format:
 
        yosys> write_ilang
 
+elaborate design hierarchy:
+
+       yosys> hierarchy
+
 convert processes ("always" blocks) to netlist elements and perform
 some simple optimizations:
 
@@ -139,15 +134,16 @@ write design netlist to a new verilog file:
 
        yosys> write_verilog synth.v
 
-a simmilar synthesis can be performed using yosys command line options only:
+a similar synthesis can be performed using yosys command line options only:
 
-       $ ./yosys -o synth.v -p proc -p opt -p techmap -p opt tests/simple/fiedler-cooley.v
+       $ ./yosys -o synth.v -p hierarchy -p proc -p opt \
+                            -p techmap -p opt tests/simple/fiedler-cooley.v
 
 or using a simple synthesis script:
 
        $ cat synth.ys
        read_verilog tests/simple/fiedler-cooley.v
-       proc; opt; techmap; opt
+       hierarchy; proc; opt; techmap; opt
        write_verilog synth.v
 
        $ ./yosys synth.ys
@@ -156,7 +152,7 @@ It is also possible to only have the synthesis commands but not the read/write
 commands in the synthesis script:
 
        $ cat synth.ys
-       proc; opt; techmap; opt
+       hierarchy; proc; opt; techmap; opt
 
        $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys
 
@@ -174,9 +170,9 @@ The following synthesis script works reasonable for all designs:
        # convert to gate logic
        techmap; opt
 
-If ABC (http://www.eecs.berkeley.edu/~alanmi/abc/) is installed and
-a cell library is given in the liberty file mycells.lib, the following
-synthesis script will synthesize for the given cell library:
+If ABC is enabled in the Yosys build configuration and a cell library is given
+in the liberty file mycells.lib, the following synthesis script will synthesize
+for the given cell library:
 
        # the high-level stuff
        hierarchy; proc; memory; opt; fsm; opt
@@ -191,11 +187,19 @@ synthesis script will synthesize for the given cell library:
        abc -liberty mycells.lib
 
        # cleanup
-       opt
+       clean
 
 If you do not have a liberty file but want to test this synthesis script,
 you can use the file techlibs/cmos/cmos_cells.lib from the yosys sources.
 
+Various more complex liberty files (for testing) can be found here:
+
+       http://vlsiarch.ecen.okstate.edu/flows/MOSIS_SCMOS/latest/..
+               ../cadence/lib/tsmc025/signalstorm/osu025_stdcells.lib
+               ../cadence/lib/ami035/signalstorm/osu035_stdcells.lib
+               ../cadence/lib/tsmc018/signalstorm/osu018_stdcells.lib
+               ../cadence/lib/ami05/signalstorm/osu05_stdcells.lib
+
 Yosys is under construction. A more detailed documentation will follow.
 
 
@@ -272,20 +276,77 @@ Verilog Attributes and non-standard features
   for everything that comes after the {* ... *} statement. (Reset
   by adding an empty {* *} statement.)
 
-
-Workarounds for known build problems
-====================================
-
-You might get an error message like this one during build when building with
-a recent version of gcc:
-
-       /usr/include/minisat/utils/Options.h:285:29: error:
-       unable to find string literal operator ‘operator"" PRIi64’
-
-This is a bug in the minisat header. It can be fixed by adding spaces before
-and after each occurrence of PRIi64 in the header file:
-
-        sudo sed -i 's/PRIi64/ & /' /usr/include/minisat/utils/Options.h
+- Modules can be declared with "module mod_name(...);" (with three dots
+  instead of a list of moudle ports). With this syntax it is sufficient
+  to simply declare a module port as 'input' or 'output' in the module
+  body.
+
+- When defining a macro with `define, all text between tripple double quotes
+  is interpreted as macro body, even if it contains unescaped newlines. The
+  tripple double quotes are removed from the macro body. For example:
+
+      `define MY_MACRO(a, b) """
+         assign a = 23;
+         assign b = 42;
+      """
+
+- The attribute "via_celltype" can be used to implement a verilog task or
+  function by instantiating the specified cell type. The value is the name
+  of the cell type to use. For functions the name of the output port can
+  be specified by appending it to the cell type separated by a whitespace.
+  The body of the task or function is unused in this case and can be used
+  to specify a behavioral model of the cell type for simulation. For example:
+
+      module my_add3(A, B, C, Y);
+        parameter WIDTH = 8;
+        input [WIDTH-1:0] A, B, C;
+        output [WIDTH-1:0] Y;
+        ...
+      endmodule
+
+      module top;
+        ...
+        (* via_celltype = "my_add3 Y" *)
+        (* via_celltype_defparam_WIDTH = 32 *)
+        function [31:0] add3;
+          input [31:0] A, B, C;
+          begin
+            add3 = A + B + C;
+          end
+        endfunction
+        ...
+      endmodule
+
+- A limited subset of DPI-C functions is supported. The plugin mechanism
+  (see "help plugin") can be used load .so files with implementations of
+  DPI-C routines. As a non-standard extension it is possible to specify
+  a plugin alias using the "<alias>:" syntax. for example:
+
+      module dpitest;
+        import "DPI-C" function foo:round = real my_round (real);
+        parameter real r = my_round(12.345);
+      endmodule
+
+      $ yosys -p 'plugin -a foo -i /lib/libm.so; read_verilog dpitest.v'
+
+- Sized constants (the syntax <size>'s?[bodh]<value>) support constant
+  expressions as <size>. If the expresion is not a simple identifier, it
+  must be put in parentheses. Examples: WIDTH'd42, (4+2)'b101010
+
+
+Supported features from SystemVerilog
+=====================================
+
+When read_verilog is called with -sv, it accepts some language features
+from SystemVerilog:
+
+- The "assert" statement from SystemVerilog is supported in its most basic
+  form. In module context: "assert property (<expression>);" and within an
+  always block: "assert(<expression>);". It is transformed to a $assert cell
+  that is supported by the "sat" and "write_btor" commands.
+
+- The keywords "always_comb", "always_ff" and "always_latch", "logic" and
+  "bit" are supported.
 
 
 Roadmap / Large-scale TODOs
@@ -296,15 +357,11 @@ Roadmap / Large-scale TODOs
    - yosys-bigsim: https://github.com/cliffordwolf/yosys-bigsim
 
 - Technology mapping for real-world applications
-   - Add "mini synth script" feature to techmap pass
-   - Add const-folding via cell parameters to techmap pass
-   - Rewrite current stdcells.v techmap rules (modular and clean)
+   - Rewrite current techmap.v rules (modular and clean)
    - Improve Xilinx FGPA synthesis (RAMB, CARRY4, SLR, etc.)
 
 - Implement SAT-based formal equivialence checker
-   - Add x-state support to SAT model generator
-   - Rewrite freduce pass with input-cone analysis
-   - Write equiv pass, base hypothesis on input cones
+   - Write equiv pass based on hint-based register mapping
 
 - Re-implement Verilog frontend (far future)
    - cleaner (easier to use, harder to use wrong) AST format
@@ -317,8 +374,8 @@ Other Unsorted TODOs
 
 - Implement missing Verilog 2005 features:
 
-  - Multi-dimensional arrays
-  - ROM modeling using "initial" blocks
+  - Support for real (float) const. expressions and parameters
+  - ROM modeling using $readmemh/$readmemb in "initial" blocks
   - Ignore what needs to be ignored (e.g. drive and charge strengths)
   - Check standard vs. implementation to identify missing features
 
@@ -326,7 +383,7 @@ Other Unsorted TODOs
 
   - Add brief source code documentation to most passes and kernel code
   - Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
-  - Add edit commands for changing the design (delete, add, modify objects)
+  - Add more commands for changing the design (delete, add, modify objects)
   - Add full support for $lut cell type (const evaluation, sat solving, etc.)
   - Smarter resource sharing pass (add MUXes and get rid of duplicated cells)