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