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