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