Yosys can be adapted to perform any synthesis job by combining
the existing passes (algorithms) using synthesis scripts and
-adding additional passes as needed by extending the yosys c++
-codebase.
+adding additional passes as needed by extending the yosys C++
+code base.
Yosys is free software licensed under the ISC license (a GPL
-compatible licence that is similar in terms to the MIT license
+compatible license that is similar in terms to the MIT license
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
===============
-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.
+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 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
+
+ $ make config-clang-debug
+ $ make config-gcc-debug
+ $ make config-release
+
+For other compilers and build configurations it might be
+necessary to make some changes to the config section of the
+Makefile.
+
+ $ vi Makefile ..or..
+ $ vi Makefile.conf
+
+To build Yosys simply type 'make' in this directory.
- $ 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
+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
yosys>
-the command "help" can be used to pritn a list of all available
+the command "help" can be used to print a list of all available
commands and "help <command>" to print details on the specified command:
yosys> help help
yosys> write_ilang
-convert processes (always blocks) to netlist elements and perform
+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 'full_case' attribute on case statements is supported
(also the non-standard "// synopsys full_case" directive)
+- The 'parallel_case' attribute on case statements is supported
+ (also the non-standard "// synopsys parallel_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.
+ automatic early conversion of arrays to separate registers.
+
+- The "mem2reg" attribute on modules or arrays forces the early
+ conversion of arrays to separate 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.
+ 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
+ to 'x' (undefined). The variable may only be used as blocking assigned
+ 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 featre 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.
-TODOs / Open Bugs
-=================
+- 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:
-- Write "design and implementation of.." document
+ `define MY_MACRO(a, b) """
+ assign a = 23;
+ assign b = 42;
+ """
-- Add brief sourcecode documentation to:
+- 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:
- - Most passes and kernel functionalities
+ module my_add3(A, B, C, Y);
+ parameter WIDTH = 8;
+ input [WIDTH-1:0] A, B, C;
+ output [WIDTH-1:0] Y;
+ ...
+ endmodule
-- Implement missing Verilog 2005 features:
+ 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
- - 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
+- 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
+=====================================
-- Actually use range information on parameters
+When read_verilog is called with -sv, it accepts some language features
+from SystemVerilog:
-- Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
+- 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.
-- TCL and Python interfaces to frontends, passes, backends and RTLIL
+- The keywords "always_comb", "always_ff" and "always_latch", "logic" and
+ "bit" are supported.
-- Additional internal cell types: $pla and $lut
-- Support for registering designs (as collection of modules) to CellTypes
+Roadmap / Large-scale TODOs
+===========================
-- Kernel support for collections of cells (from input/output cones, etc)
+- 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
+
+- 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
+
+
+Other Unsorted TODOs
+====================
+
+- Implement missing Verilog 2005 features:
+
+ - 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
-- Smarter resource sharing pass (add MUXes and get rid of duplicated cells)
+- Miscellaneous TODO items:
-- Better FSM state encoding
+ - Add brief source code documentation to most passes and kernel code
+ - Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
+ - 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)