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 the yosys svg viewer:
  92
  93         yosys> show
  94
  95 the same thing using 'gv' as postscript viewer:
  96
  97         yosys> show -format ps -viewer gv
  98
  99 translating netlist to gate logic and perform some simple optimizations:
 100
 101         yosys> techmap; opt
 102
 103 write design netlist to a new verilog file:
 104
 105         yosys> write_verilog synth.v
 106
 107 a simmilar synthesis can be performed using yosys command line options only:
 108
 109         $ ./yosys -o synth.v -p proc -p opt -p techmap -p opt tests/simple/fiedler-cooley.v
 110
 111 or using a simple synthesis script:
 112
 113         $ cat synth.ys
 114         read_verilog tests/simple/fiedler-cooley.v
 115         proc; opt; techmap; opt
 116         write_verilog synth.v
 117
 118         $ ./yosys synth.ys
 119
 120 It is also possible to only have the synthesis commands but not the read/write
 121 commands in the synthesis script:
 122
 123         $ cat synth.ys
 124         proc; opt; techmap; opt
 125
 126         $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys
 127
 128 The following synthesis script works reasonable for all designs:
 129
 130         # check design hierarchy
 131         hierarchy
 132
 133         # translate processes (always blocks) and memories (arrays)
 134         proc; memory; opt
 135
 136         # detect and optimize FSM encodings
 137         fsm; opt
 138
 139         # convert to gate logic
 140         techmap; opt
 141
 142 If ABC (http://www.eecs.berkeley.edu/~alanmi/abc/) is installed and
 143 a cell library is given in the liberty file mycells.lib, the following
 144 synthesis script will synthesize for the given cell library:
 145
 146         # the high-level stuff
 147         hierarchy; proc; memory; opt; fsm; opt
 148
 149         # mapping to internal cell library
 150         techmap; opt
 151
 152         # mapping flip-flops to mycells.lib
 153         dfflibmap -liberty mycells.lib
 154
 155         # mapping logic to mycells.lib
 156         abc -liberty mycells.lib
 157
 158         # cleanup
 159         opt
 160
 161 Yosys is under construction. A more detailed documentation will follow.
 162
 163
 164 Unsupported Verilog-2005 Features
 165 =================================
 166
 167 The following Verilog-2005 features are not supported by
 168 yosys and there are currently no plans to add support
 169 for them:
 170
 171 - Non-sythesizable language features as defined in
 172         IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002
 173
 174 - The "tri", "triand", "trior", "wand" and "wor" net types
 175
 176 - The "config" keyword and library map files
 177
 178 - The "disable", "primitive" and "specify" statements
 179
 180 - Latched logic (is synthesized as logic with feedback loops)
 181
 182
 183 Verilog Attributes and non-standard features
 184 ============================================
 185
 186 - The 'full_case' attribute on case statements is supported
 187   (also the non-standard "// synopsys full_case" directive)
 188
 189 - The 'parallel_case' attribute on case statements is supported
 190   (also the non-standard "// synopsys parallel_case" directive)
 191
 192 - The "// synopsys translate_off" and "// synopsys translate_on"
 193   directives are also supported (but the use of `ifdef .. `endif
 194   is strongly recommended instead).
 195
 196 - The "nomem2reg" attribute on modules or arrays prohibits the
 197   automatic early conversion of arrays to separate registers.
 198
 199 - The "mem2reg" attribute on modules or arrays forces the early
 200   conversion of arrays to separate registers.
 201
 202 - The "nolatches" attribute on modules or always-blocks
 203   prohibits the generation of logic-loops for latches. Instead
 204   all not explicitly assigned values default to x-bits.
 205
 206 - The "nosync" attribute on registers prohibits the generation of a
 207   storage element. The register itself will always have all bits set
 208   to 'x' (undefined). The variable may only be used as blocking assigned
 209   temporary variable within an always block. This is mostly used internally
 210   by yosys to synthesize verilog functions and access arrays.
 211
 212 - The "placeholder" attribute on modules is used to mark empty stub modules
 213   that have the same ports as the real thing but do not contain information
 214   on the internal configuration. This modules are only used by the synthesis
 215   passes to identify input and output ports of cells. The verilog backend
 216   also does not output placeholder modules on default.
 217
 218 - In addition to the (* ... *) attribute syntax, yosys supports
 219   the non-standard {* ... *} attribute syntax to set default attributes
 220   for everything that comes after the {* ... *} statement. (Reset
 221   by adding an empty {* *} statement.) The preprocessor define
 222   __YOSYS_ENABLE_DEFATTR__ must be set in order for this feature to be active.
 223
 224
 225 TODOs / Open Bugs
 226 =================
 227
 228 - Write "design and implementation of.." document
 229
 230   - Source tree layout
 231   - Data formats (c++ classes, etc.)
 232   - Internal misc. frameworks (log, select)
 233   - Build system and pass registration
 234   - Internal cell library
 235
 236 - Implement missing Verilog 2005 features:
 237
 238   - Signed constants
 239   - Constant functions
 240   - Indexed part selects
 241   - Multi-dimensional arrays
 242   - ROM modeling using "initial" blocks
 243   - The "defparam <cell_name>.<parameter_name> = <value>;" syntax
 244   - Built-in primitive gates (and, nand, cmos, nmos, pmos, etc..)
 245   - Ignore what needs to be ignored (e.g. drive and charge strengths)
 246   - Check standard vs. implementation to identify missing features
 247
 248 - Miscellaneous TODO items:
 249
 250   - Actually use range information on parameters
 251   - Add brief source code documentation to most passes and kernel code
 252   - Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
 253   - Add 'edit' command for changing the design (delete, add, modify objects)
 254   - Improve TCL support and add 'list' command for inspecting the design from TCL
 255   - Additional internal cell types: $pla and $lut
 256   - Support for registering designs (as collection of modules) to CellTypes
 257   - Smarter resource sharing pass (add MUXes and get rid of duplicated cells)
 258   - For pass' "fsm_detect" help: add notes what criteria lets it detect an FSM
 259   - Better FSM state encoding
 260