/-----------------------------------------------------------------------------\
 |                                                                             |
 |  yosys -- Yosys Open SYnthesis Suite                                        |
 |                                                                             |
 |  Copyright (C) 2012  Clifford Wolf <clifford@clifford.at>                   |
 |                                                                             |
 |  Permission to use, copy, modify, and/or distribute this software for any   |
 |  purpose with or without fee is hereby granted, provided that the above     |
 |  copyright notice and this permission notice appear in all copies.          |
 |                                                                             |
 |  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES   |
 |  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF           |
 |  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR    |
 |  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES     |
 |  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN      |
 |  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF    |
 |  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.             |
 |                                                                             |
 \-----------------------------------------------------------------------------/


yosys -- Yosys Open SYnthesis Suite
===================================

This is a framework for RTL synthesis tools. It is highly
experimental and under construction. The goal for now is
to implement an extensible Verilog-2005 synthesis tool.

The aim of this tool is to generate valid logic netlists
from HDL designs in a manner that allows for easy addition
of extra synthesis passes. This tool does not aim at generating
efficient logic netlists. This can be done by passing the
output of Yosys to a low-level synthesis tool such as ABC.

Yosys is free software licensed under the ISC license (a GPL
compatible licence that is similar in terms to the MIT license
or the 2-clause BSD license).


Getting Started
===============

To build Yosys simply typoe 'make' in this directory. 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. It might be neccessary to make some changes to
the config section of the Makefile.

	$ vi Makefile
	$ make
	$ make test
	$ sudo make install

Yosys can be used using the interactive command shell, using
synthesis scripts or using command line arguments. Let's perform
a simple synthesis job using the interactive command shell:

	$ ./yosys
	yosys>

reading the design using the verilog frontend:

	yosys> read_verilog tests/simple/fiedler-cooley.v

writing the design to the console in yosys's internal format:

	yosys> write_ilang

convert processes (always blocks) to netlist elements and perform
some simple optimizations:

	yosys> proc; opt

display design netlist using 'gv' as postscript viewer:

	yosys> show -viewer gv

translating netlist to gate logic and perform some simple optimizations:

	yosys> techmap; opt

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:

	$ ./yosys -o synth.v -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
	write_verilog synth.v

	$ ./yosys synth.ys

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

	$ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys

The following synthesis script works reasonable for all designs:

	# check design hierarchy
	hierarchy

	# translate processes (always blocks) and memories (arrays)
	proc; memory; opt

	# detect and optimize FSM encodings
	fsm; opt

	# 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:

	# the high-level stuff
	hierarchy; proc; memory; opt; fsm; opt

	# mapping to internal cell library
	techmap

	# mapping flip-flops to mycells.lib
	dfflibmap -liberty mycells.lib

	# mapping logic to mycells.lib
	abc -liberty mycells.lib

	# cleanup
	opt

Yosys is under construction. A more detailed documentation will follow.


Unsupported Verilog-2005 Features
=================================

The following Verilog-2005 features are not supported by
yosys and there are currently no plans to add support
for them:

- Non-sythesizable language features as defined in
	IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002

- The "tri", "triand", "trior", "wand" and "wor" net types

- The "config" keyword and library map files

- The "disable", "primitive" and "specify" statements

- Latched logic (is synthesized as logic with feedback loops)


Verilog Attributes and non-standard features
============================================

- The 'full_case' attribute on case statements is supported
  (also the non-standard "// synopsys full_case" directive)

- The "// synopsys translate_off" and "// synopsys translate_on"
  directives are also supported (but the use of `ifdef .. `endif
  is strongly recommended instead).

- The "nomem2reg" attribute on modules or arrays prohibits the
  automatic early conversion of arrays to seperate registers.

- 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.

- 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 featre to be active.


TODOs / Open Bugs
=================

- Write "design and implementation of.." document

- Add brief sourcecode documentation to:

   - Most passes and kernel functionalities

- Implement missing Verilog 2005 features:

  - Signed constants
  - Constant functions
  - Indexed part selects
  - Multi-dimensional arrays
  - ROM modelling using "initial" blocks
  - The "defparam <cell_name>.<parameter_name> = <value>;" syntax
  - Builtin primitive gates (and, nand, cmos, nmos, pmos, etc..)
  - Ignore what needs to be ignored (e.g. drive and charge strenghts)
  - Check standard vs. implementation to identify missing features

- Actually use range information on parameters

- Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees

- TCL and Python interfaces to frontends, passes, backends and RTLIL

- Additional internal cell types: $pla and $lut

- Subsystem for selecting stuff (and limiting scope of passes)

- Support for registering designs (as collection of modules) to CellTypes

- Kernel support for collections of cells (from input/output cones, etc)

- Smarter resource sharing pass (add MUXes and get rid of duplicated cells)

- Better FSM state encoding and technology mapping