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 elaborate design hierarchy:
116 convert processes ("always" blocks) to netlist elements and perform
117 some simple optimizations:
121 display design netlist using the yosys svg viewer:
125 the same thing using 'gv' as postscript viewer:
127 yosys> show -format ps -viewer gv
129 translating netlist to gate logic and perform some simple optimizations:
133 write design netlist to a new verilog file:
135 yosys> write_verilog synth.v
137 a similar synthesis can be performed using yosys command line options only:
139 $ ./yosys -o synth.v -p hierarchy -p proc -p opt \
140 -p techmap -p opt tests/simple/fiedler-cooley.v
142 or using a simple synthesis script:
145 read_verilog tests/simple/fiedler-cooley.v
146 hierarchy; proc; opt; techmap; opt
147 write_verilog synth.v
151 It is also possible to only have the synthesis commands but not the read/write
152 commands in the synthesis script:
155 hierarchy; proc; opt; techmap; opt
157 $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys
159 The following synthesis script works reasonable for all designs:
161 # check design hierarchy
164 # translate processes (always blocks) and memories (arrays)
167 # detect and optimize FSM encodings
170 # convert to gate logic
173 If ABC is enabled in the Yosys build configuration and a cell library is given
174 in the liberty file mycells.lib, the following synthesis script will synthesize
175 for the given cell library:
177 # the high-level stuff
178 hierarchy; proc; memory; opt; fsm; opt
180 # mapping to internal cell library
183 # mapping flip-flops to mycells.lib
184 dfflibmap -liberty mycells.lib
186 # mapping logic to mycells.lib
187 abc -liberty mycells.lib
192 If you do not have a liberty file but want to test this synthesis script,
193 you can use the file techlibs/cmos/cmos_cells.lib from the yosys sources.
195 Various more complex liberty files (for testing) can be found here:
197 http://vlsiarch.ecen.okstate.edu/flows/MOSIS_SCMOS/latest/..
198 ../cadence/lib/tsmc025/signalstorm/osu025_stdcells.lib
199 ../cadence/lib/ami035/signalstorm/osu035_stdcells.lib
200 ../cadence/lib/tsmc018/signalstorm/osu018_stdcells.lib
201 ../cadence/lib/ami05/signalstorm/osu05_stdcells.lib
203 Yosys is under construction. A more detailed documentation will follow.
206 Unsupported Verilog-2005 Features
207 =================================
209 The following Verilog-2005 features are not supported by
210 yosys and there are currently no plans to add support
213 - Non-sythesizable language features as defined in
214 IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002
216 - The "tri", "triand", "trior", "wand" and "wor" net types
218 - The "config" keyword and library map files
220 - The "disable", "primitive" and "specify" statements
222 - Latched logic (is synthesized as logic with feedback loops)
225 Verilog Attributes and non-standard features
226 ============================================
228 - The 'full_case' attribute on case statements is supported
229 (also the non-standard "// synopsys full_case" directive)
231 - The 'parallel_case' attribute on case statements is supported
232 (also the non-standard "// synopsys parallel_case" directive)
234 - The "// synopsys translate_off" and "// synopsys translate_on"
235 directives are also supported (but the use of `ifdef .. `endif
236 is strongly recommended instead).
238 - The "nomem2reg" attribute on modules or arrays prohibits the
239 automatic early conversion of arrays to separate registers.
241 - The "mem2reg" attribute on modules or arrays forces the early
242 conversion of arrays to separate registers.
244 - The "nolatches" attribute on modules or always-blocks
245 prohibits the generation of logic-loops for latches. Instead
246 all not explicitly assigned values default to x-bits. This does
247 not affect clocked storage elements such as flip-flops.
249 - The "nosync" attribute on registers prohibits the generation of a
250 storage element. The register itself will always have all bits set
251 to 'x' (undefined). The variable may only be used as blocking assigned
252 temporary variable within an always block. This is mostly used internally
253 by yosys to synthesize verilog functions and access arrays.
255 - The "blackbox" attribute on modules is used to mark empty stub modules
256 that have the same ports as the real thing but do not contain information
257 on the internal configuration. This modules are only used by the synthesis
258 passes to identify input and output ports of cells. The verilog backend
259 also does not output blackbox modules on default.
261 - The "keep" attribute on cells and wires is used to mark objects that should
262 never be removed by the optimizer. This is used for example for cells that
263 have hidden connections that are not part of the netlist, such as IO pads.
265 - The "init" attribute on wires is set by the frontend when a register is
266 initialized "FPGA-style" with 'reg foo = val'. It can be used during synthesis
267 to add the necessary reset logic.
269 - The "top" attribute on a module marks this module as the top of the
270 design hierarchy. The "hierarchy" command sets this attribute when called
271 with "-top". Other commands, such as "flatten" and various backends
272 use this attribute to determine the top module.
274 - In addition to the (* ... *) attribute syntax, yosys supports
275 the non-standard {* ... *} attribute syntax to set default attributes
276 for everything that comes after the {* ... *} statement. (Reset
277 by adding an empty {* *} statement.)
279 - Modules can be declared with "module mod_name(...);" (with three dots
280 instead of a list of moudle ports). With this syntax it is sufficient
281 to simply declare a module port as 'input' or 'output' in the module
284 - When defining a macro with `define, all text between tripple double quotes
285 is interpreted as macro body, even if it contains unescaped newlines. The
286 tripple double quotes are removed from the macro body. For example:
288 `define MY_MACRO(a, b) """
293 - Sized constants (the syntax <size>'s?[bodh]<value>) support constant
294 expressions as <size>. If the expresion is not a simple identifier, it
295 must be put in parentheses. Examples: WIDTH'd42, (4+2)'b101010
298 Supported features from SystemVerilog
299 =====================================
301 When read_verilog is called with -sv, it accepts some language features
304 - The "assert" statement from SystemVerilog is supported in its most basic
305 form. In module context: "assert property (<expression>);" and within an
306 always block: "assert(<expression>);". It is transformed to a $assert cell
307 that is supported by the "sat" and "write_btor" commands.
309 - The keywords "always_comb", "always_ff" and "always_latch", "logic" and
313 Roadmap / Large-scale TODOs
314 ===========================
316 - Verification and Regression Tests
317 - VlogHammer: http://www.clifford.at/yosys/vloghammer.html
318 - yosys-bigsim: https://github.com/cliffordwolf/yosys-bigsim
320 - Technology mapping for real-world applications
321 - Rewrite current techmap.v rules (modular and clean)
322 - Improve Xilinx FGPA synthesis (RAMB, CARRY4, SLR, etc.)
324 - Implement SAT-based formal equivialence checker
325 - Write equiv pass based on hint-based register mapping
327 - Re-implement Verilog frontend (far future)
328 - cleaner (easier to use, harder to use wrong) AST format
329 - pipeline of well structured AST transformations
330 - true contextual name lookup
336 - Implement missing Verilog 2005 features:
338 - Support for real (float) const. expressions and parameters
339 - ROM modeling using $readmemh/$readmemb in "initial" blocks
340 - Ignore what needs to be ignored (e.g. drive and charge strengths)
341 - Check standard vs. implementation to identify missing features
343 - Miscellaneous TODO items:
345 - Add brief source code documentation to most passes and kernel code
346 - Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
347 - Add more commands for changing the design (delete, add, modify objects)
348 - Add full support for $lut cell type (const evaluation, sat solving, etc.)
349 - Smarter resource sharing pass (add MUXes and get rid of duplicated cells)