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         $ yosys_deps="git g++ clang make bison flex libreadline-dev
  60                       tcl8.5-dev zlib1g-dev libqt4-dev mercurial
  61                       iverilog graphviz"
  62         $ sudo apt-get install $yosys_deps
  63
  64 There are also pre-compiled packages for Yosys on Ubuntu. Visit the Yosys
  65 download page to learn more about this:
  66
  67         http://www.clifford.at/yosys/download.html
  68
  69 To configure the build system to use a specific set of compiler and
  70 build configuration, use one of
  71
  72         $ make config-clang-debug
  73         $ make config-gcc-debug
  74         $ make config-release
  75
  76 For other compilers and build configurations it might be
  77 necessary to make some changes to the config section of the
  78 Makefile.
  79
  80         $ vi Makefile             ..or..
  81         $ vi Makefile.conf
  82
  83 To build Yosys simply type 'make' in this directory.
  84
  85         $ make
  86         $ make test
  87         $ sudo make install
  88
  89 Note that this also downloads, builds and installs ABC (using yosys-abc
  90 as executeable name).
  91
  92 Yosys can be used with the interactive command shell, with
  93 synthesis scripts or with command line arguments. Let's perform
  94 a simple synthesis job using the interactive command shell:
  95
  96         $ ./yosys
  97         yosys>
  98
  99 the command "help" can be used to print a list of all available
 100 commands and "help <command>" to print details on the specified command:
 101
 102         yosys> help help
 103
 104 reading the design using the verilog frontend:
 105
 106         yosys> read_verilog tests/simple/fiedler-cooley.v
 107
 108 writing the design to the console in yosys's internal format:
 109
 110         yosys> write_ilang
 111
 112 convert processes ("always" blocks) to netlist elements and perform
 113 some simple optimizations:
 114
 115         yosys> proc; opt
 116
 117 display design netlist using the yosys svg viewer:
 118
 119         yosys> show
 120
 121 the same thing using 'gv' as postscript viewer:
 122
 123         yosys> show -format ps -viewer gv
 124
 125 translating netlist to gate logic and perform some simple optimizations:
 126
 127         yosys> techmap; opt
 128
 129 write design netlist to a new verilog file:
 130
 131         yosys> write_verilog synth.v
 132
 133 a similar synthesis can be performed using yosys command line options only:
 134
 135         $ ./yosys -o synth.v -p proc -p opt -p techmap -p opt tests/simple/fiedler-cooley.v
 136
 137 or using a simple synthesis script:
 138
 139         $ cat synth.ys
 140         read_verilog tests/simple/fiedler-cooley.v
 141         proc; opt; techmap; opt
 142         write_verilog synth.v
 143
 144         $ ./yosys synth.ys
 145
 146 It is also possible to only have the synthesis commands but not the read/write
 147 commands in the synthesis script:
 148
 149         $ cat synth.ys
 150         proc; opt; techmap; opt
 151
 152         $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys
 153
 154 The following synthesis script works reasonable for all designs:
 155
 156         # check design hierarchy
 157         hierarchy
 158
 159         # translate processes (always blocks) and memories (arrays)
 160         proc; memory; opt
 161
 162         # detect and optimize FSM encodings
 163         fsm; opt
 164
 165         # convert to gate logic
 166         techmap; opt
 167
 168 If ABC is enabled in the Yosys build configuration and a cell library is given
 169 in the liberty file mycells.lib, the following synthesis script will synthesize
 170 for the given cell library:
 171
 172         # the high-level stuff
 173         hierarchy; proc; memory; opt; fsm; opt
 174
 175         # mapping to internal cell library
 176         techmap; opt
 177
 178         # mapping flip-flops to mycells.lib
 179         dfflibmap -liberty mycells.lib
 180
 181         # mapping logic to mycells.lib
 182         abc -liberty mycells.lib
 183
 184         # cleanup
 185         clean
 186
 187 If you do not have a liberty file but want to test this synthesis script,
 188 you can use the file techlibs/cmos/cmos_cells.lib from the yosys sources.
 189
 190 Yosys is under construction. A more detailed documentation will follow.
 191
 192
 193 Unsupported Verilog-2005 Features
 194 =================================
 195
 196 The following Verilog-2005 features are not supported by
 197 yosys and there are currently no plans to add support
 198 for them:
 199
 200 - Non-sythesizable language features as defined in
 201         IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002
 202
 203 - The "tri", "triand", "trior", "wand" and "wor" net types
 204
 205 - The "config" keyword and library map files
 206
 207 - The "disable", "primitive" and "specify" statements
 208
 209 - Latched logic (is synthesized as logic with feedback loops)
 210
 211
 212 Verilog Attributes and non-standard features
 213 ============================================
 214
 215 - The 'full_case' attribute on case statements is supported
 216   (also the non-standard "// synopsys full_case" directive)
 217
 218 - The 'parallel_case' attribute on case statements is supported
 219   (also the non-standard "// synopsys parallel_case" directive)
 220
 221 - The "// synopsys translate_off" and "// synopsys translate_on"
 222   directives are also supported (but the use of `ifdef .. `endif
 223   is strongly recommended instead).
 224
 225 - The "nomem2reg" attribute on modules or arrays prohibits the
 226   automatic early conversion of arrays to separate registers.
 227
 228 - The "mem2reg" attribute on modules or arrays forces the early
 229   conversion of arrays to separate registers.
 230
 231 - The "nolatches" attribute on modules or always-blocks
 232   prohibits the generation of logic-loops for latches. Instead
 233   all not explicitly assigned values default to x-bits. This does
 234   not affect clocked storage elements such as flip-flops.
 235
 236 - The "nosync" attribute on registers prohibits the generation of a
 237   storage element. The register itself will always have all bits set
 238   to 'x' (undefined). The variable may only be used as blocking assigned
 239   temporary variable within an always block. This is mostly used internally
 240   by yosys to synthesize verilog functions and access arrays.
 241
 242 - The "blackbox" attribute on modules is used to mark empty stub modules
 243   that have the same ports as the real thing but do not contain information
 244   on the internal configuration. This modules are only used by the synthesis
 245   passes to identify input and output ports of cells. The verilog backend
 246   also does not output blackbox modules on default.
 247
 248 - The "keep" attribute on cells and wires is used to mark objects that should
 249   never be removed by the optimizer. This is used for example for cells that
 250   have hidden connections that are not part of the netlist, such as IO pads.
 251
 252 - The "init" attribute on wires is set by the frontend when a register is
 253   initialized "FPGA-style" with 'reg foo = val'. It can be used during synthesis
 254   to add the necessary reset logic.
 255
 256 - The "top" attribute on a module marks this module as the top of the
 257   design hierarchy. The "hierarchy" command sets this attribute when called
 258   with "-top". Other commands, such as "flatten" and various backends
 259   use this attribute to determine the top module.
 260
 261 - In addition to the (* ... *) attribute syntax, yosys supports
 262   the non-standard {* ... *} attribute syntax to set default attributes
 263   for everything that comes after the {* ... *} statement. (Reset
 264   by adding an empty {* *} statement.)
 265
 266 - Sized constants (the syntax <size>'s?[bodh]<value>) support constant
 267   expressions as <size>. If the expresion is not a simple identifier, it
 268   must be put in parentheses. Examples: WIDTH'd42, (4+2)'b101010
 269
 270
 271 Supported features from SystemVerilog
 272 =====================================
 273
 274 When read_verilog is called with -sv, it accepts some language features
 275 from SystemVerilog:
 276
 277 - The "assert" statement from SystemVerilog is supported in its most basic
 278   form. In module context: "assert property (<expression>);" and within an
 279   always block: "assert(<expression>);". It is transformed to a $assert cell
 280   that is supported by the "sat" and "write_btor" commands.
 281
 282 - The keywords "always_comb", "always_ff" and "always_latch", "logic" and
 283   "bit" are supported.
 284
 285
 286 Roadmap / Large-scale TODOs
 287 ===========================
 288
 289 - Verification and Regression Tests
 290    - VlogHammer: http://www.clifford.at/yosys/vloghammer.html
 291    - yosys-bigsim: https://github.com/cliffordwolf/yosys-bigsim
 292
 293 - Technology mapping for real-world applications
 294    - Add bit-wise const-folding via cell parameters to techmap pass
 295    - Rewrite current stdcells.v techmap rules (modular and clean)
 296    - Improve Xilinx FGPA synthesis (RAMB, CARRY4, SLR, etc.)
 297
 298 - Implement SAT-based formal equivialence checker
 299    - Write equiv pass based on hint-based register mapping
 300
 301 - Re-implement Verilog frontend (far future)
 302    - cleaner (easier to use, harder to use wrong) AST format
 303    - pipeline of well structured AST transformations
 304    - true contextual name lookup
 305
 306
 307 Other Unsorted TODOs
 308 ====================
 309
 310 - Implement missing Verilog 2005 features:
 311
 312   - Multi-dimensional arrays
 313   - Support for real (float) const. expressions and parameters
 314   - ROM modeling using $readmemh/$readmemb in "initial" blocks
 315   - Ignore what needs to be ignored (e.g. drive and charge strengths)
 316   - Check standard vs. implementation to identify missing features
 317
 318 - Miscellaneous TODO items:
 319
 320   - Add brief source code documentation to most passes and kernel code
 321   - Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
 322   - Add more commands for changing the design (delete, add, modify objects)
 323   - Add full support for $lut cell type (const evaluation, sat solving, etc.)
 324   - Smarter resource sharing pass (add MUXes and get rid of duplicated cells)
 325