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