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 TCL, readline and libffi are optional (see ENABLE_* settings in Makefile).
54 Xdot (graphviz) is used by the "show" command in yosys to display schematics.
55 For example on Ubuntu Linux 14.04 LTS the following commands will install all
56 prerequisites for building yosys:
58 $ yosys_deps="build-essential clang bison flex libreadline-dev
59 tcl8.5-dev libffi-dev git mercurial graphviz xdot"
60 $ sudo apt-get install $yosys_deps
62 There are also pre-compiled packages for Yosys on Ubuntu. Visit the Yosys
63 download page to learn more about this:
65 http://www.clifford.at/yosys/download.html
67 To configure the build system to use a specific compiler, use one of
72 For other compilers and build configurations it might be
73 necessary to make some changes to the config section of the
79 To build Yosys simply type 'make' in this directory.
85 Note that this also downloads, builds and installs ABC (using yosys-abc
88 Yosys can be used with the interactive command shell, with
89 synthesis scripts or with command line arguments. Let's perform
90 a simple synthesis job using the interactive command shell:
95 the command "help" can be used to print a list of all available
96 commands and "help <command>" to print details on the specified command:
100 reading the design using the verilog frontend:
102 yosys> read_verilog tests/simple/fiedler-cooley.v
104 writing the design to the console in yosys's internal format:
108 elaborate design hierarchy:
112 convert processes ("always" blocks) to netlist elements and perform
113 some simple optimizations:
117 display design netlist using xdot:
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 hierarchy -p proc -p opt \
136 -p techmap -p opt tests/simple/fiedler-cooley.v
138 or using a simple synthesis script:
141 read_verilog tests/simple/fiedler-cooley.v
142 hierarchy; proc; opt; techmap; opt
143 write_verilog synth.v
147 It is also possible to only have the synthesis commands but not the read/write
148 commands in the synthesis script:
151 hierarchy; proc; opt; techmap; opt
153 $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys
155 The following very basic synthesis script should work well with all designs:
157 # check design hierarchy
160 # translate processes (always blocks)
163 # detect and optimize FSM encodings
166 # implement memories (arrays)
169 # convert to gate logic
172 If ABC is enabled in the Yosys build configuration and a cell library is given
173 in the liberty file mycells.lib, the following synthesis script will synthesize
174 for the given cell library:
176 # the high-level stuff
177 hierarchy; proc; fsm; opt; memory; opt
179 # mapping to internal cell library
182 # mapping flip-flops to mycells.lib
183 dfflibmap -liberty mycells.lib
185 # mapping logic to mycells.lib
186 abc -liberty mycells.lib
191 If you do not have a liberty file but want to test this synthesis script,
192 you can use the file techlibs/cmos/cmos_cells.lib from the yosys sources.
194 Various more complex liberty files (for testing) can be found here:
196 http://vlsiarch.ecen.okstate.edu/flows/MOSIS_SCMOS/latest/..
197 ../cadence/lib/tsmc025/signalstorm/osu025_stdcells.lib
198 ../cadence/lib/ami035/signalstorm/osu035_stdcells.lib
199 ../cadence/lib/tsmc018/signalstorm/osu018_stdcells.lib
200 ../cadence/lib/ami05/signalstorm/osu05_stdcells.lib
202 Yosys is under construction. A more detailed documentation will follow.
205 Unsupported Verilog-2005 Features
206 =================================
208 The following Verilog-2005 features are not supported by
209 yosys and there are currently no plans to add support
212 - Non-sythesizable language features as defined in
213 IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002
215 - The "tri", "triand", "trior", "wand" and "wor" net types
217 - The "config" keyword and library map files
219 - The "disable", "primitive" and "specify" statements
221 - Latched logic (is synthesized as logic with feedback loops)
224 Verilog Attributes and non-standard features
225 ============================================
227 - The 'full_case' attribute on case statements is supported
228 (also the non-standard "// synopsys full_case" directive)
230 - The 'parallel_case' attribute on case statements is supported
231 (also the non-standard "// synopsys parallel_case" directive)
233 - The "// synopsys translate_off" and "// synopsys translate_on"
234 directives are also supported (but the use of `ifdef .. `endif
235 is strongly recommended instead).
237 - The "nomem2reg" attribute on modules or arrays prohibits the
238 automatic early conversion of arrays to separate registers.
240 - The "mem2reg" attribute on modules or arrays forces the early
241 conversion of arrays to separate registers.
243 - The "nolatches" attribute on modules or always-blocks
244 prohibits the generation of logic-loops for latches. Instead
245 all not explicitly assigned values default to x-bits. This does
246 not affect clocked storage elements such as flip-flops.
248 - The "nosync" attribute on registers prohibits the generation of a
249 storage element. The register itself will always have all bits set
250 to 'x' (undefined). The variable may only be used as blocking assigned
251 temporary variable within an always block. This is mostly used internally
252 by yosys to synthesize verilog functions and access arrays.
254 - The "blackbox" attribute on modules is used to mark empty stub modules
255 that have the same ports as the real thing but do not contain information
256 on the internal configuration. This modules are only used by the synthesis
257 passes to identify input and output ports of cells. The verilog backend
258 also does not output blackbox modules on default.
260 - The "keep" attribute on cells and wires is used to mark objects that should
261 never be removed by the optimizer. This is used for example for cells that
262 have hidden connections that are not part of the netlist, such as IO pads.
264 - The "init" attribute on wires is set by the frontend when a register is
265 initialized "FPGA-style" with 'reg foo = val'. It can be used during synthesis
266 to add the necessary reset logic.
268 - The "top" attribute on a module marks this module as the top of the
269 design hierarchy. The "hierarchy" command sets this attribute when called
270 with "-top". Other commands, such as "flatten" and various backends
271 use this attribute to determine the top module.
273 - In addition to the (* ... *) attribute syntax, yosys supports
274 the non-standard {* ... *} attribute syntax to set default attributes
275 for everything that comes after the {* ... *} statement. (Reset
276 by adding an empty {* *} statement.)
278 - Modules can be declared with "module mod_name(...);" (with three dots
279 instead of a list of moudle ports). With this syntax it is sufficient
280 to simply declare a module port as 'input' or 'output' in the module
283 - When defining a macro with `define, all text between tripple double quotes
284 is interpreted as macro body, even if it contains unescaped newlines. The
285 tripple double quotes are removed from the macro body. For example:
287 `define MY_MACRO(a, b) """
292 - The attribute "via_celltype" can be used to implement a verilog task or
293 function by instantiating the specified cell type. The value is the name
294 of the cell type to use. For functions the name of the output port can
295 be specified by appending it to the cell type separated by a whitespace.
296 The body of the task or function is unused in this case and can be used
297 to specify a behavioral model of the cell type for simulation. For example:
299 module my_add3(A, B, C, Y);
301 input [WIDTH-1:0] A, B, C;
302 output [WIDTH-1:0] Y;
308 (* via_celltype = "my_add3 Y" *)
309 (* via_celltype_defparam_WIDTH = 32 *)
310 function [31:0] add3;
311 input [31:0] A, B, C;
319 - A limited subset of DPI-C functions is supported. The plugin mechanism
320 (see "help plugin") can be used load .so files with implementations of
321 DPI-C routines. As a non-standard extension it is possible to specify
322 a plugin alias using the "<alias>:" syntax. for example:
325 import "DPI-C" function foo:round = real my_round (real);
326 parameter real r = my_round(12.345);
329 $ yosys -p 'plugin -a foo -i /lib/libm.so; read_verilog dpitest.v'
331 - Sized constants (the syntax <size>'s?[bodh]<value>) support constant
332 expressions as <size>. If the expresion is not a simple identifier, it
333 must be put in parentheses. Examples: WIDTH'd42, (4+2)'b101010
336 Supported features from SystemVerilog
337 =====================================
339 When read_verilog is called with -sv, it accepts some language features
342 - The "assert" statement from SystemVerilog is supported in its most basic
343 form. In module context: "assert property (<expression>);" and within an
344 always block: "assert(<expression>);". It is transformed to a $assert cell
345 that is supported by the "sat" and "write_btor" commands.
347 - The keywords "always_comb", "always_ff" and "always_latch", "logic" and
351 Roadmap / Large-scale TODOs
352 ===========================
354 - Verification and Regression Tests
355 - VlogHammer: http://www.clifford.at/yosys/vloghammer.html
356 - yosys-bigsim: https://github.com/cliffordwolf/yosys-bigsim
358 - Technology mapping for real-world applications
359 - Rewrite current techmap.v rules (modular and clean)
360 - Improve Xilinx FGPA synthesis (RAMB, CARRY4, SLR, etc.)
362 - Implement SAT-based formal equivialence checker
363 - Write equiv pass based on hint-based register mapping
365 - Re-implement Verilog frontend (far future)
366 - cleaner (easier to use, harder to use wrong) AST format
367 - pipeline of well structured AST transformations
368 - true contextual name lookup
374 - Implement missing Verilog 2005 features:
376 - Support for real (float) const. expressions and parameters
377 - ROM modeling using $readmemh/$readmemb in "initial" blocks
378 - Ignore what needs to be ignored (e.g. drive and charge strengths)
379 - Check standard vs. implementation to identify missing features
381 - Miscellaneous TODO items:
383 - Add brief source code documentation to most passes and kernel code
384 - Implement mux-to-tribuf pass and rebalance mixed mux/tribuf trees
385 - Add more commands for changing the design (delete, add, modify objects)
386 - Add full support for $lut cell type (const evaluation, sat solving, etc.)
387 - Smarter resource sharing pass (add MUXes and get rid of duplicated cells)