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 To also build and install ABC (recommended) use the following commands:
  67
  68         $ make abc
  69         $ sudo make install-abc
  70
  71 Yosys can be used with the interactive command shell, with
  72 synthesis scripts or with command line arguments. Let's perform
  73 a simple synthesis job using the interactive command shell:
  74
  75         $ ./yosys
  76         yosys>
  77
  78 the command "help" can be used to print a list of all available
  79 commands and "help <command>" to print details on the specified command:
  80
  81         yosys> help help
  82
  83 reading the design using the verilog frontend:
  84
  85         yosys> read_verilog tests/simple/fiedler-cooley.v
  86
  87 writing the design to the console in yosys's internal format:
  88
  89         yosys> write_ilang
  90
  91 convert processes ("always" blocks) to netlist elements and perform
  92 some simple optimizations:
  93
  94         yosys> proc; opt
  95
  96 display design netlist using the yosys svg viewer:
  97
  98         yosys> show
  99
 100 the same thing using 'gv' as postscript viewer:
 101
 102         yosys> show -format ps -viewer gv
 103
 104 translating netlist to gate logic and perform some simple optimizations:
 105
 106         yosys> techmap; opt
 107
 108 write design netlist to a new verilog file:
 109
 110         yosys> write_verilog synth.v
 111
 112 a simmilar synthesis can be performed using yosys command line options only:
 113
 114         $ ./yosys -o synth.v -p proc -p opt -p techmap -p opt tests/simple/fiedler-cooley.v
 115
 116 or using a simple synthesis script:
 117
 118         $ cat synth.ys
 119         read_verilog tests/simple/fiedler-cooley.v
 120         proc; opt; techmap; opt
 121         write_verilog synth.v
 122
 123         $ ./yosys synth.ys
 124
 125 It is also possible to only have the synthesis commands but not the read/write
 126 commands in the synthesis script:
 127
 128         $ cat synth.ys
 129         proc; opt; techmap; opt
 130
 131         $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys
 132
 133 The following synthesis script works reasonable for all designs:
 134
 135         # check design hierarchy
 136         hierarchy
 137
 138         # translate processes (always blocks) and memories (arrays)
 139         proc; memory; opt
 140
 141         # detect and optimize FSM encodings
 142         fsm; opt
 143
 144         # convert to gate logic
 145         techmap; opt
 146
 147 If ABC (http://www.eecs.berkeley.edu/~alanmi/abc/) is installed and
 148 a cell library is given in the liberty file mycells.lib, the following
 149 synthesis script will synthesize for the given cell library:
 150
 151         # the high-level stuff
 152         hierarchy; proc; memory; opt; fsm; opt
 153
 154         # mapping to internal cell library
 155         techmap; opt
 156
 157         # mapping flip-flops to mycells.lib
 158         dfflibmap -liberty mycells.lib
 159
 160         # mapping logic to mycells.lib
 161         abc -liberty mycells.lib
 162
 163         # cleanup
 164         opt
 165
 166 Yosys is under construction. A more detailed documentation will follow.
 167
 168
 169 Unsupported Verilog-2005 Features
 170 =================================
 171
 172 The following Verilog-2005 features are not supported by
 173 yosys and there are currently no plans to add support
 174 for them:
 175
 176 - Non-sythesizable language features as defined in
 177         IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002
 178
 179 - The "tri", "triand", "trior", "wand" and "wor" net types
 180
 181 - The "config" keyword and library map files
 182
 183 - The "disable", "primitive" and "specify" statements
 184
 185 - Latched logic (is synthesized as logic with feedback loops)
 186
 187
 188 Verilog Attributes and non-standard features
 189 ============================================
 190
 191 - The 'full_case' attribute on case statements is supported
 192   (also the non-standard "// synopsys full_case" directive)
 193
 194 - The 'parallel_case' attribute on case statements is supported
 195   (also the non-standard "// synopsys parallel_case" directive)
 196
 197 - The "// synopsys translate_off" and "// synopsys translate_on"
 198   directives are also supported (but the use of `ifdef .. `endif
 199   is strongly recommended instead).
 200
 201 - The "nomem2reg" attribute on modules or arrays prohibits the
 202   automatic early conversion of arrays to separate registers.
 203
 204 - The "mem2reg" attribute on modules or arrays forces the early
 205   conversion of arrays to separate registers.
 206
 207 - The "nolatches" attribute on modules or always-blocks
 208   prohibits the generation of logic-loops for latches. Instead
 209   all not explicitly assigned values default to x-bits.
 210
 211 - The "nosync" attribute on registers prohibits the generation of a
 212   storage element. The register itself will always have all bits set
 213   to 'x' (undefined). The variable may only be used as blocking assigned
 214   temporary variable within an always block. This is mostly used internally
 215   by yosys to synthesize verilog functions and access arrays.
 216
 217 - The "placeholder" attribute on modules is used to mark empty stub modules
 218   that have the same ports as the real thing but do not contain information
 219   on the internal configuration. This modules are only used by the synthesis
 220   passes to identify input and output ports of cells. The verilog backend
 221   also does not output placeholder modules on default.
 222
 223 - In addition to the (* ... *) attribute syntax, yosys supports
 224   the non-standard {* ... *} attribute syntax to set default attributes
 225   for everything that comes after the {* ... *} statement. (Reset
 226   by adding an empty {* *} statement.) The preprocessor define
 227   __YOSYS_ENABLE_DEFATTR__ must be set in order for this feature to be active.
 228
 229
 230 TODOs / Open Bugs
 231 =================
 232
 233 - Write "design and implementation of.." document
 234
 235   - Source tree layout
 236   - Data formats (c++ classes, etc.)
 237   - Internal misc. frameworks (log, select)
 238   - Build system and pass registration
 239   - Internal cell library
 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   - Additional internal cell types: $pla and $lut
 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