README

   1
   2 yosys -- Yosys Open SYnthesis Suite
   3 ===================================
   4
   5 This is a framework for RTL synthesis tools. It is highly
   6 experimental and under construction. The goal for now is
   7 to implement an extensible Verilog-2005 synthesis tool.
   8
   9 The aim of this tool is to generate valid logic netlists
  10 from HDL designs in a manner that allows for easy addition
  11 of extra synthesis passes. This tool does not aim at generating
  12 efficient logic netlists. This can be done by passing the
  13 output of Yosys to a low-level synthesis tool such as ABC.
  14
  15 Yosys is free software licensed under the ISC license (a GPL
  16 compatible licence that is similar in terms to the MIT license
  17 or the 2-clause BSD license).
  18
  19
  20 Getting Started
  21 ===============
  22
  23 To build Yosys simply typoe 'make' in this directory. You need
  24 a C++ compiler with C++11 support (up-to-date CLANG or GCC is
  25 recommended) and some standard tools such as GNU Flex, GNU Bison,
  26 and GNU Make. It might be neccessary to make some changes to
  27 the config section of the Makefile.
  28
  29         $ vi Makefile
  30         $ make
  31         $ make test
  32         $ sudo make install
  33
  34 Yosys can be used using the interactive command shell, using
  35 synthesis scripts or using command line arguments. Let's perform
  36 a simple synthesis job using the interactive command shell:
  37
  38         $ ./yosys
  39         yosys>
  40
  41 reading the design using the verilog frontend:
  42
  43         yosys> read_verilog tests/simple/fiedler-cooley.v
  44
  45 writing the design to the console in yosys's internal format:
  46
  47         yosys> write_ilang
  48
  49 convert processes (always blocks) to netlist elements and perform
  50 some simple optimizations:
  51
  52         yosys> proc; opt
  53
  54 display design netlist using 'gv' as postscript viewer:
  55
  56         yosys> show -viewer gv
  57
  58 translating netlist to gate logic and perform some simple optimizations:
  59
  60         yosys> techmap; opt
  61
  62 write design netlist to a new verilog file:
  63
  64         yosys> write_verilog synth.v
  65
  66 a simmilar synthesis can be performed using yosys command line options only:
  67
  68         $ ./yosys -o synth.v -p proc -p opt -p techmap -p opt tests/simple/fiedler-cooley.v
  69
  70 or using a simple synthesis script:
  71
  72         $ cat synth.ys
  73         read_verilog tests/simple/fiedler-cooley.v
  74         proc; opt; techmap; opt
  75         write_verilog synth.v
  76
  77         $ ./yosys synth.ys
  78
  79 It is also possible to only have the synthesis commands but not the read/write
  80 commands in the synthesis script:
  81
  82         $ cat synth.ys
  83         proc; opt; techmap; opt
  84
  85         $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys
  86
  87 The following synthesis script works reasonable for all designs:
  88
  89         # check design hierarchy
  90         hierarchy
  91
  92         # translate processes (always blocks) and memories (arrays)
  93         proc; memory; opt
  94
  95         # detect and optimize FSM encodings
  96         fsm; opt
  97
  98         # convert to gate logic
  99         techmap; opt
 100
 101 If ABC (http://www.eecs.berkeley.edu/~alanmi/abc/) is installed and
 102 a cell library is given in the file liberty mycells.lib, the following
 103 synthesis script will synthesize for the given cell library:
 104
 105         # the high-level stuff
 106         hierarchy; proc; memory; opt; fsm; opt
 107
 108         # mapping to internal cell library
 109         techmap
 110
 111         # mapping flip-flops to mycells.lib
 112         dfflibmap -liberty mycells.lib
 113
 114         # mapping logic to mycells.lib
 115         abc -liberty mycells.lib
 116
 117         # cleanup
 118         opt
 119
 120 Yosys is under construction. A more detailed documentation will follow.
 121
 122
 123 Unsupported Verilog-2005 Features
 124 =================================
 125
 126 The following Verilog-2005 features are not supported by
 127 yosys and there are currently no plans to add support
 128 for them:
 129
 130 - Non-sythesizable language features as defined in
 131         IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002
 132
 133 - The "tri", "triand", "trior", "wand" and "wor" net types
 134
 135 - The "library" and "configuration" source file formats
 136
 137 - The "disable" and "primitive" statements
 138
 139 - Latched logic (is synthesized as logic with feedback loops)
 140
 141
 142 Verilog Attributes and non-standard features
 143 ============================================
 144
 145 - The 'full_case' attribute on case statements is supported
 146   (also the non-standard "// synopsys full_case" directive)
 147
 148 - The "// synopsys translate_off" and "// synopsys translate_on"
 149   directives are also supported (but the use of `ifdef .. `endif
 150   is strongly recommended instead).
 151
 152 - The "nomem2reg" attribute on modules or arrays prohibits the
 153   automatic early conversion of arrays to seperate registers.
 154
 155 - The "nolatches" attribute on modules or always-blocks
 156   prohibits the generation of logic-loops for latches. Instead
 157   all not explicitly assigned values default to x-bits.
 158
 159 - In addition to the (* ... *) attribute syntax, yosys supports
 160   the non-standard {* ... *} attribute syntax to set default attributes
 161   for everything that comes after the {* ... *} statement. (Reset
 162   by adding an empty {* *} statement.) The preprocessor define
 163   __YOSYS_ENABLE_DEFATTR__ must be set in order for this featre to be active.
 164
 165
 166 TODOs / Open Bugs
 167 =================
 168
 169 - Write "design and implementation of.." document
 170
 171 - Add brief sourcecode documentation to:
 172
 173    - Most passes and kernel functionalities
 174
 175 - Implement missing Verilog 2005 features:
 176
 177   - Signed constants
 178   - ROM modelling using "initial" blocks
 179   - Builtin primitive gates (and, nand, cmos, nmos, pmos, etc..)
 180   - Ignore what needs to be ignored (e.g. drive and charge strenghts)
 181   - Check standard vs. implementation to identify missing features
 182
 183 - Actually use range information on parameters
 184
 185 - Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
 186
 187 - TCL and Python interfaces to frontends, passes, backends and RTLIL
 188
 189 - Additional internal cell types: $pla and $lut
 190
 191 - Subsystem for selecting stuff (and limiting scope of passes)
 192
 193 - Support for registering designs (as collection of modules) to CellTypes
 194
 195 - Kernel support for collections of cells (from input/output cones, etc)
 196
 197 - Smarter resource sharing pass (add MUXes and get rid of duplicated cells)
 198
 199 - Better FSM state encoding and technology mapping
 200