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 currently has
  27 extensive Verilog-2005 support and provides a basic set of
  28 synthesis algorithms for various application domains.
  29
  30 Yosys can be adapted to perform any synthesis job by combining
  31 the existing passes (algorithms) using synthesis scripts and
  32 adding additional passes as needed by extending the yosys c++
  33 codebase.
  34
  35 Yosys is free software licensed under the ISC license (a GPL
  36 compatible licence that is similar in terms to the MIT license
  37 or the 2-clause BSD license).
  38
  39
  40 Getting Started
  41 ===============
  42
  43 To build Yosys simply typoe 'make' in this directory. You need
  44 a C++ compiler with C++11 support (up-to-date CLANG or GCC is
  45 recommended) and some standard tools such as GNU Flex, GNU Bison,
  46 and GNU Make. It might be neccessary to make some changes to
  47 the config section of the Makefile.
  48
  49         $ vi Makefile
  50         $ make
  51         $ make test
  52         $ sudo make install
  53
  54 Yosys can be used using the interactive command shell, using
  55 synthesis scripts or using command line arguments. Let's perform
  56 a simple synthesis job using the interactive command shell:
  57
  58         $ ./yosys
  59         yosys>
  60
  61 the command "help" can be used to pritn a list of all available
  62 commands and "help <command>" to print details on the specified command:
  63
  64         yosys> help help
  65
  66 reading the design using the verilog frontend:
  67
  68         yosys> read_verilog tests/simple/fiedler-cooley.v
  69
  70 writing the design to the console in yosys's internal format:
  71
  72         yosys> write_ilang
  73
  74 convert processes (always blocks) to netlist elements and perform
  75 some simple optimizations:
  76
  77         yosys> proc; opt
  78
  79 display design netlist using 'gv' as postscript viewer:
  80
  81         yosys> show -viewer gv
  82
  83 translating netlist to gate logic and perform some simple optimizations:
  84
  85         yosys> techmap; opt
  86
  87 write design netlist to a new verilog file:
  88
  89         yosys> write_verilog synth.v
  90
  91 a simmilar synthesis can be performed using yosys command line options only:
  92
  93         $ ./yosys -o synth.v -p proc -p opt -p techmap -p opt tests/simple/fiedler-cooley.v
  94
  95 or using a simple synthesis script:
  96
  97         $ cat synth.ys
  98         read_verilog tests/simple/fiedler-cooley.v
  99         proc; opt; techmap; opt
 100         write_verilog synth.v
 101
 102         $ ./yosys synth.ys
 103
 104 It is also possible to only have the synthesis commands but not the read/write
 105 commands in the synthesis script:
 106
 107         $ cat synth.ys
 108         proc; opt; techmap; opt
 109
 110         $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys
 111
 112 The following synthesis script works reasonable for all designs:
 113
 114         # check design hierarchy
 115         hierarchy
 116
 117         # translate processes (always blocks) and memories (arrays)
 118         proc; memory; opt
 119
 120         # detect and optimize FSM encodings
 121         fsm; opt
 122
 123         # convert to gate logic
 124         techmap; opt
 125
 126 If ABC (http://www.eecs.berkeley.edu/~alanmi/abc/) is installed and
 127 a cell library is given in the liberty file mycells.lib, the following
 128 synthesis script will synthesize for the given cell library:
 129
 130         # the high-level stuff
 131         hierarchy; proc; memory; opt; fsm; opt
 132
 133         # mapping to internal cell library
 134         techmap; opt
 135
 136         # mapping flip-flops to mycells.lib
 137         dfflibmap -liberty mycells.lib
 138
 139         # mapping logic to mycells.lib
 140         abc -liberty mycells.lib
 141
 142         # cleanup
 143         opt
 144
 145 Yosys is under construction. A more detailed documentation will follow.
 146
 147
 148 Unsupported Verilog-2005 Features
 149 =================================
 150
 151 The following Verilog-2005 features are not supported by
 152 yosys and there are currently no plans to add support
 153 for them:
 154
 155 - Non-sythesizable language features as defined in
 156         IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002
 157
 158 - The "tri", "triand", "trior", "wand" and "wor" net types
 159
 160 - The "config" keyword and library map files
 161
 162 - The "disable", "primitive" and "specify" statements
 163
 164 - Latched logic (is synthesized as logic with feedback loops)
 165
 166
 167 Verilog Attributes and non-standard features
 168 ============================================
 169
 170 - The 'full_case' attribute on case statements is supported
 171   (also the non-standard "// synopsys full_case" directive)
 172
 173 - The 'parallel_case' attribute on case statements is supported
 174   (also the non-standard "// synopsys parallel_case" directive)
 175
 176 - The "// synopsys translate_off" and "// synopsys translate_on"
 177   directives are also supported (but the use of `ifdef .. `endif
 178   is strongly recommended instead).
 179
 180 - The "nomem2reg" attribute on modules or arrays prohibits the
 181   automatic early conversion of arrays to seperate registers.
 182
 183 - The "nolatches" attribute on modules or always-blocks
 184   prohibits the generation of logic-loops for latches. Instead
 185   all not explicitly assigned values default to x-bits.
 186
 187 - In addition to the (* ... *) attribute syntax, yosys supports
 188   the non-standard {* ... *} attribute syntax to set default attributes
 189   for everything that comes after the {* ... *} statement. (Reset
 190   by adding an empty {* *} statement.) The preprocessor define
 191   __YOSYS_ENABLE_DEFATTR__ must be set in order for this featre to be active.
 192
 193
 194 TODOs / Open Bugs
 195 =================
 196
 197 - Write "design and implementation of.." document
 198
 199 - Add brief sourcecode documentation to:
 200
 201    - Most passes and kernel functionalities
 202
 203 - Implement missing Verilog 2005 features:
 204
 205   - Signed constants
 206   - Constant functions
 207   - Indexed part selects
 208   - Multi-dimensional arrays
 209   - ROM modelling using "initial" blocks
 210   - The "defparam <cell_name>.<parameter_name> = <value>;" syntax
 211   - Builtin primitive gates (and, nand, cmos, nmos, pmos, etc..)
 212   - Ignore what needs to be ignored (e.g. drive and charge strenghts)
 213   - Check standard vs. implementation to identify missing features
 214
 215 - Actually use range information on parameters
 216
 217 - Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
 218
 219 - Add commands 'delete' (remove objects) and 'attr' (get, set and remove attributes)
 220
 221 - TCL and Python interfaces to frontends, passes, backends and RTLIL
 222
 223 - Additional internal cell types: $pla and $lut
 224
 225 - Support for registering designs (as collection of modules) to CellTypes
 226
 227 - Kernel support for collections of cells (from input/output cones, etc)
 228
 229 - Smarter resource sharing pass (add MUXes and get rid of duplicated cells)
 230
 231 - Better FSM state encoding
 232