README

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