or the 2-clause BSD license).
+Web Site
+========
+
+More information and documentation can be found on the Yosys web site:
+
+ http://www.clifford.at/yosys/
+
+
Getting Started
===============
You need a C++ compiler with C++11 support (up-to-date CLANG or GCC is
-recommended) and some standard tools such as GNU Flex, GNU Bison, and
-GNU Make. The extensive tests require Icarus Verilog.
+recommended) and some standard tools such as GNU Flex, GNU Bison, and GNU Make.
+The Qt4 library is needed for the yosys SVG viewer, that is used to display
+schematics, the minisat library is required for the SAT features in yosys
+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:
+
+ $ 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
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.
$ make test
$ sudo make install
+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
a simple synthesis job using the interactive command shell:
yosys> write_ilang
+elaborate design hierarchy:
+
+ yosys> hierarchy
+
convert processes ("always" blocks) to netlist elements and perform
some simple optimizations:
yosys> proc; opt
-display design netlist using 'gv' as postscript viewer:
+display design netlist using the yosys svg viewer:
- yosys> show -viewer gv
+ yosys> show
+
+the same thing using 'gv' as postscript viewer:
+
+ yosys> show -format ps -viewer gv
translating netlist to gate logic and perform some simple optimizations:
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
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
# 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
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.
- The "nolatches" attribute on modules or always-blocks
prohibits the generation of logic-loops for latches. Instead
- all not explicitly assigned values default to x-bits.
+ all not explicitly assigned values default to x-bits. This does
+ not affect clocked storage elements such as flip-flops.
- The "nosync" attribute on registers prohibits the generation of a
storage element. The register itself will always have all bits set
temporary variable within an always block. This is mostly used internally
by yosys to synthesize verilog functions and access arrays.
+- The "blackbox" attribute on modules is used to mark empty stub modules
+ that have the same ports as the real thing but do not contain information
+ on the internal configuration. This modules are only used by the synthesis
+ passes to identify input and output ports of cells. The verilog backend
+ also does not output blackbox modules on default.
+
+- The "keep" attribute on cells and wires is used to mark objects that should
+ never be removed by the optimizer. This is used for example for cells that
+ have hidden connections that are not part of the netlist, such as IO pads.
+
+- The "init" attribute on wires is set by the frontend when a register is
+ initialized "FPGA-style" with 'reg foo = val'. It can be used during synthesis
+ to add the necessary reset logic.
+
+- The "top" attribute on a module marks this module as the top of the
+ design hierarchy. The "hierarchy" command sets this attribute when called
+ with "-top". Other commands, such as "flatten" and various backends
+ use this attribute to determine the top module.
+
- In addition to the (* ... *) attribute syntax, yosys supports
the non-standard {* ... *} attribute syntax to set default attributes
for everything that comes after the {* ... *} statement. (Reset
- by adding an empty {* *} statement.) The preprocessor define
- __YOSYS_ENABLE_DEFATTR__ must be set in order for this feature to be active.
+ by adding an empty {* *} statement.)
+
+- 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
+===========================
+
+- Verification and Regression Tests
+ - VlogHammer: http://www.clifford.at/yosys/vloghammer.html
+ - yosys-bigsim: https://github.com/cliffordwolf/yosys-bigsim
+
+- Technology mapping for real-world applications
+ - Rewrite current techmap.v rules (modular and clean)
+ - Improve Xilinx FGPA synthesis (RAMB, CARRY4, SLR, etc.)
+- Implement SAT-based formal equivialence checker
+ - Write equiv pass based on hint-based register mapping
-TODOs / Open Bugs
-=================
+- Re-implement Verilog frontend (far future)
+ - cleaner (easier to use, harder to use wrong) AST format
+ - pipeline of well structured AST transformations
+ - true contextual name lookup
-- Write "design and implementation of.." document
- - Source tree layout
- - Data formats (c++ classes, etc.)
- - Internal misc. frameworks (log, select)
- - Build system and pass registration
- - Internal cell library
+Other Unsorted TODOs
+====================
- Implement missing Verilog 2005 features:
- - Signed constants
- - Constant functions
- - Indexed part selects
- - Multi-dimensional arrays
- - ROM modeling using "initial" blocks
- - The "defparam <cell_name>.<parameter_name> = <value>;" syntax
- - Built-in primitive gates (and, nand, cmos, nmos, pmos, etc..)
+ - 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
- Miscellaneous TODO items:
- - Actually use range information on parameters
- Add brief source code documentation to most passes and kernel code
- Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
- - Add commands 'delete' (remove objects) and 'attr' (get, set and remove attributes)
- - TCL and Python interfaces to frontends, passes, backends and RTLIL
- - Additional internal cell types: $pla and $lut
- - Support for registering designs (as collection of modules) to CellTypes
+ - 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)
- - For pass' "fsm_detect" help: add notes what criteria lets it detect an FSM
- - Better FSM state encoding
projects / yosys.git / blobdiff