2 /-----------------------------------------------------------------------------\
4 | yosys -- Yosys Open SYnthesis Suite |
6 | Copyright (C) 2012 Clifford Wolf <clifford@clifford.at> |
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. |
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. |
20 \-----------------------------------------------------------------------------/
23 yosys -- Yosys Open SYnthesis Suite
24 ===================================
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.
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++
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).
43 More information and documentation can be found on the Yosys web site:
45 http://www.clifford.at/yosys/
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:
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
74 To configure the build system to use a specific set of compiler and
75 build configuration, use one of
77 $ make config-clang-debug
78 $ make config-gcc-debug
81 For other compilers and build configurations it might be
82 necessary to make some changes to the config section of the
87 To build Yosys simply type 'make' in this directory.
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.
96 To also build and install ABC (recommended) use the following commands:
99 $ sudo make install-abc
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:
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:
113 reading the design using the verilog frontend:
115 yosys> read_verilog tests/simple/fiedler-cooley.v
117 writing the design to the console in yosys's internal format:
121 convert processes ("always" blocks) to netlist elements and perform
122 some simple optimizations:
126 display design netlist using the yosys svg viewer:
130 the same thing using 'gv' as postscript viewer:
132 yosys> show -format ps -viewer gv
134 translating netlist to gate logic and perform some simple optimizations:
138 write design netlist to a new verilog file:
140 yosys> write_verilog synth.v
142 a simmilar synthesis can be performed using yosys command line options only:
144 $ ./yosys -o synth.v -p proc -p opt -p techmap -p opt tests/simple/fiedler-cooley.v
146 or using a simple synthesis script:
149 read_verilog tests/simple/fiedler-cooley.v
150 proc; opt; techmap; opt
151 write_verilog synth.v
155 It is also possible to only have the synthesis commands but not the read/write
156 commands in the synthesis script:
159 proc; opt; techmap; opt
161 $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys
163 The following synthesis script works reasonable for all designs:
165 # check design hierarchy
168 # translate processes (always blocks) and memories (arrays)
171 # detect and optimize FSM encodings
174 # convert to gate logic
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:
181 # the high-level stuff
182 hierarchy; proc; memory; opt; fsm; opt
184 # mapping to internal cell library
187 # mapping flip-flops to mycells.lib
188 dfflibmap -liberty mycells.lib
190 # mapping logic to mycells.lib
191 abc -liberty mycells.lib
196 If you do not have a liberty file but want to test this synthesis script,
197 you can use the file techlibs/cmos/cmos_cells.lib from the yosys sources.
199 Yosys is under construction. A more detailed documentation will follow.
202 Unsupported Verilog-2005 Features
203 =================================
205 The following Verilog-2005 features are not supported by
206 yosys and there are currently no plans to add support
209 - Non-sythesizable language features as defined in
210 IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002
212 - The "tri", "triand", "trior", "wand" and "wor" net types
214 - The "config" keyword and library map files
216 - The "disable", "primitive" and "specify" statements
218 - Latched logic (is synthesized as logic with feedback loops)
221 Verilog Attributes and non-standard features
222 ============================================
224 - The 'full_case' attribute on case statements is supported
225 (also the non-standard "// synopsys full_case" directive)
227 - The 'parallel_case' attribute on case statements is supported
228 (also the non-standard "// synopsys parallel_case" directive)
230 - The "// synopsys translate_off" and "// synopsys translate_on"
231 directives are also supported (but the use of `ifdef .. `endif
232 is strongly recommended instead).
234 - The "nomem2reg" attribute on modules or arrays prohibits the
235 automatic early conversion of arrays to separate registers.
237 - The "mem2reg" attribute on modules or arrays forces the early
238 conversion of arrays to separate registers.
240 - The "nolatches" attribute on modules or always-blocks
241 prohibits the generation of logic-loops for latches. Instead
242 all not explicitly assigned values default to x-bits. This does
243 not affect clocked storage elements such as flip-flops.
245 - The "nosync" attribute on registers prohibits the generation of a
246 storage element. The register itself will always have all bits set
247 to 'x' (undefined). The variable may only be used as blocking assigned
248 temporary variable within an always block. This is mostly used internally
249 by yosys to synthesize verilog functions and access arrays.
251 - The "placeholder" attribute on modules is used to mark empty stub modules
252 that have the same ports as the real thing but do not contain information
253 on the internal configuration. This modules are only used by the synthesis
254 passes to identify input and output ports of cells. The verilog backend
255 also does not output placeholder modules on default.
257 - The "keep" attribute on cells and wires is used to mark objects that should
258 never be removed by the optimizer. This is used for example for cells that
259 have hidden connections that are not part of the netlist, such as IO pads.
261 - The "init" attribute on wires is set by the frontend when a register is
262 initialized "FPGA-style" with 'reg foo = val'. It can be used during synthesis
263 to add the necessary reset logic.
265 - In addition to the (* ... *) attribute syntax, yosys supports
266 the non-standard {* ... *} attribute syntax to set default attributes
267 for everything that comes after the {* ... *} statement. (Reset
268 by adding an empty {* *} statement.) The preprocessor define
269 __YOSYS_ENABLE_DEFATTR__ must be set in order for this feature to be active.
272 Workarounds for known build problems
273 ====================================
275 You might get an error message like this one during build when building with
276 a recent version of gcc:
278 /usr/include/minisat/utils/Options.h:285:29: error:
279 unable to find string literal operator ‘operator"" PRIi64’
281 This is a bug in the minisat header. It can be fixed by adding spaces before
282 and after each occurrence of PRIi64 in the header file:
284 sudo sed -i 's/PRIi64/ & /' /usr/include/minisat/utils/Options.h
287 Roadmap / Large-scale TODOs
288 ===========================
290 - Verification and Regression Tests
291 - VlogHammer: http://www.clifford.at/yosys/vloghammer.html
292 - yosys-bigsim: https://github.com/cliffordwolf/yosys-bigsim
294 - Missing Verilog-2005 features to be implemented soon:
295 - Fix corner cases with contextual name lookup
296 - Part select on memory read
297 - Indexed part selects
299 - Technology mapping for real-world applications
300 - Add "mini synth script" feature to techmap pass
301 - Add const-folding via cell parameters to techmap pass
302 - Rewrite current stdcells.v techmap rules (modular and clean)
303 - Improve Xilinx FGPA synthesis (RAMB, CARRY4, SLR, etc.)
305 - Implement SAT-based formal equivialence checker
306 - Add x-state support to SAT model generator
307 - Rewrite freduce pass with input-cone analysis
308 - Write equiv pass, base hypothesis on input cones
310 - Re-implement Verilog frontend (far future)
311 - cleaner (easier to use, harder to use wrong) AST format
312 - pipeline of well structured AST transformations
313 - true contextual name lookup
319 - Implement missing Verilog 2005 features:
321 - Multi-dimensional arrays
322 - ROM modeling using "initial" blocks
323 - Ignore what needs to be ignored (e.g. drive and charge strengths)
324 - Check standard vs. implementation to identify missing features
326 - Miscellaneous TODO items:
328 - Add brief source code documentation to most passes and kernel code
329 - Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
330 - Add edit commands for changing the design (delete, add, modify objects)
331 - Add full support for $lut cell type (const evaluation, sat solving, etc.)
332 - Smarter resource sharing pass (add MUXes and get rid of duplicated cells)