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 $ yosys_deps="git g++ clang make bison flex libreadline-dev
60 tcl8.5-dev zlib1g-dev libqt4-dev mercurial
62 $ sudo apt-get install $yosys_deps
64 There are also pre-compiled packages for Yosys on Ubuntu. Visit the Yosys
65 download page to learn more about this:
67 http://www.clifford.at/yosys/download.html
69 To configure the build system to use a specific set of compiler and
70 build configuration, use one of
72 $ make config-clang-debug
73 $ make config-gcc-debug
76 For other compilers and build configurations it might be
77 necessary to make some changes to the config section of the
83 To build Yosys simply type 'make' in this directory.
89 Note that this also downloads, builds and installs ABC (using yosys-abc
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:
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:
104 reading the design using the verilog frontend:
106 yosys> read_verilog tests/simple/fiedler-cooley.v
108 writing the design to the console in yosys's internal format:
112 convert processes ("always" blocks) to netlist elements and perform
113 some simple optimizations:
117 display design netlist using the yosys svg viewer:
121 the same thing using 'gv' as postscript viewer:
123 yosys> show -format ps -viewer gv
125 translating netlist to gate logic and perform some simple optimizations:
129 write design netlist to a new verilog file:
131 yosys> write_verilog synth.v
133 a similar synthesis can be performed using yosys command line options only:
135 $ ./yosys -o synth.v -p proc -p opt -p techmap -p opt tests/simple/fiedler-cooley.v
137 or using a simple synthesis script:
140 read_verilog tests/simple/fiedler-cooley.v
141 proc; opt; techmap; opt
142 write_verilog synth.v
146 It is also possible to only have the synthesis commands but not the read/write
147 commands in the synthesis script:
150 proc; opt; techmap; opt
152 $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys
154 The following synthesis script works reasonable for all designs:
156 # check design hierarchy
159 # translate processes (always blocks) and memories (arrays)
162 # detect and optimize FSM encodings
165 # convert to gate logic
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:
172 # the high-level stuff
173 hierarchy; proc; memory; opt; fsm; opt
175 # mapping to internal cell library
178 # mapping flip-flops to mycells.lib
179 dfflibmap -liberty mycells.lib
181 # mapping logic to mycells.lib
182 abc -liberty mycells.lib
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.
190 Yosys is under construction. A more detailed documentation will follow.
193 Unsupported Verilog-2005 Features
194 =================================
196 The following Verilog-2005 features are not supported by
197 yosys and there are currently no plans to add support
200 - Non-sythesizable language features as defined in
201 IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002
203 - The "tri", "triand", "trior", "wand" and "wor" net types
205 - The "config" keyword and library map files
207 - The "disable", "primitive" and "specify" statements
209 - Latched logic (is synthesized as logic with feedback loops)
212 Verilog Attributes and non-standard features
213 ============================================
215 - The 'full_case' attribute on case statements is supported
216 (also the non-standard "// synopsys full_case" directive)
218 - The 'parallel_case' attribute on case statements is supported
219 (also the non-standard "// synopsys parallel_case" directive)
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).
225 - The "nomem2reg" attribute on modules or arrays prohibits the
226 automatic early conversion of arrays to separate registers.
228 - The "mem2reg" attribute on modules or arrays forces the early
229 conversion of arrays to separate registers.
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.
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.
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.
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.
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.
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.
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.)
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
271 Supported features from SystemVerilog
272 =====================================
274 When read_verilog is called with -sv, it accepts some language features
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.
282 - The keywords "always_comb", "always_ff" and "always_latch", "logic" and
286 Roadmap / Large-scale TODOs
287 ===========================
289 - Verification and Regression Tests
290 - VlogHammer: http://www.clifford.at/yosys/vloghammer.html
291 - yosys-bigsim: https://github.com/cliffordwolf/yosys-bigsim
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.)
298 - Implement SAT-based formal equivialence checker
299 - Write equiv pass based on hint-based register mapping
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
310 - Implement missing Verilog 2005 features:
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
318 - Miscellaneous TODO items:
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)