From: Aleks-Daniel Jakimenko-Aleksejev Date: Sat, 12 Nov 2016 21:33:28 +0000 (+0200) Subject: Markdownify README X-Git-Tag: yosys-0.8~590^2 X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=d4e15926099244eabdeee2515a11da6e840ef495;p=yosys.git Markdownify README This is the first commit in series. There are many other things that could be improved, this is just the first renderable version. --- diff --git a/README b/README deleted file mode 100644 index 8e43d4446..000000000 --- a/README +++ /dev/null @@ -1,451 +0,0 @@ - - /-----------------------------------------------------------------------------\ - | | - | yosys -- Yosys Open SYnthesis Suite | - | | - | Copyright (C) 2012 - 2016 Clifford Wolf | - | | - | Permission to use, copy, modify, and/or distribute this software for any | - | purpose with or without fee is hereby granted, provided that the above | - | copyright notice and this permission notice appear in all copies. | - | | - | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | - | WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | - | MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | - | ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | - | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | - | ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | - | OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | - | | - \-----------------------------------------------------------------------------/ - - -yosys -- Yosys Open SYnthesis Suite -=================================== - -This is a framework for RTL synthesis tools. It currently has -extensive Verilog-2005 support and provides a basic set of -synthesis algorithms for various application domains. - -Yosys can be adapted to perform any synthesis job by combining -the existing passes (algorithms) using synthesis scripts and -adding additional passes as needed by extending the yosys C++ -code base. - -Yosys is free software licensed under the ISC license (a GPL -compatible license that is similar in terms to the MIT license -or the 2-clause BSD license). - - -Web Site -======== - -More information and documentation can be found on the Yosys web site: - - http://www.clifford.at/yosys/ - - -Getting Started -=============== - -You need a C++ compiler with C++11 support (up-to-date CLANG or GCC is -recommended) and some standard tools such as GNU Flex, GNU Bison, and GNU Make. -TCL, readline and libffi are optional (see ENABLE_* settings in Makefile). -Xdot (graphviz) is used by the "show" command in yosys to display schematics. -For example on Ubuntu Linux 16.04 LTS the following commands will install all -prerequisites for building yosys: - - $ sudo apt-get install build-essential clang bison flex \ - libreadline-dev gawk tcl-dev libffi-dev git mercurial \ - graphviz xdot pkg-config python3 - -There are also pre-compiled Yosys binary packages for Ubuntu and Win32 as well -as a source distribution for Visual Studio. Visit the Yosys download page for -more information: - - http://www.clifford.at/yosys/download.html - -To configure the build system to use a specific compiler, use one of - - $ make config-clang - $ make config-gcc - -For other compilers and build configurations it might be -necessary to make some changes to the config section of the -Makefile. - - $ vi Makefile ..or.. - $ vi Makefile.conf - -To build Yosys simply type 'make' in this directory. - - $ make - $ make test - $ sudo make install - -Note that this also downloads, builds and installs ABC (using yosys-abc -as executable name). - -Yosys can be used with the interactive command shell, with -synthesis scripts or with command line arguments. Let's perform -a simple synthesis job using the interactive command shell: - - $ ./yosys - yosys> - -the command "help" can be used to print a list of all available -commands and "help " to print details on the specified command: - - yosys> help help - -reading the design using the Verilog frontend: - - yosys> read_verilog tests/simple/fiedler-cooley.v - -writing the design to the console in yosys's internal format: - - yosys> write_ilang - -elaborate design hierarchy: - - yosys> hierarchy - -convert processes ("always" blocks) to netlist elements and perform -some simple optimizations: - - yosys> proc; opt - -display design netlist using xdot: - - yosys> show - -the same thing using 'gv' as postscript viewer: - - yosys> show -format ps -viewer gv - -translating netlist to gate logic and perform some simple optimizations: - - yosys> techmap; opt - -write design netlist to a new Verilog file: - - yosys> write_verilog synth.v - -a similar synthesis can be performed using yosys command line options only: - - $ ./yosys -o synth.v -p hierarchy -p proc -p opt \ - -p techmap -p opt tests/simple/fiedler-cooley.v - -or using a simple synthesis script: - - $ cat synth.ys - read_verilog tests/simple/fiedler-cooley.v - hierarchy; proc; opt; techmap; opt - write_verilog synth.v - - $ ./yosys synth.ys - -It is also possible to only have the synthesis commands but not the read/write -commands in the synthesis script: - - $ cat synth.ys - hierarchy; proc; opt; techmap; opt - - $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys - -The following very basic synthesis script should work well with all designs: - - # check design hierarchy - hierarchy - - # translate processes (always blocks) - proc; opt - - # detect and optimize FSM encodings - fsm; opt - - # implement memories (arrays) - memory; opt - - # convert to gate logic - techmap; opt - -If ABC is enabled in the Yosys build configuration and a cell library is given -in the liberty file mycells.lib, the following synthesis script will synthesize -for the given cell library: - - # the high-level stuff - hierarchy; proc; fsm; opt; memory; opt - - # mapping to internal cell library - techmap; opt - - # mapping flip-flops to mycells.lib - dfflibmap -liberty mycells.lib - - # mapping logic to mycells.lib - abc -liberty mycells.lib - - # cleanup - clean - -If you do not have a liberty file but want to test this synthesis script, -you can use the file examples/cmos/cmos_cells.lib from the yosys sources. - -Liberty file downloads for and information about free and open ASIC standard -cell libraries can be found here: - - http://www.vlsitechnology.org/html/libraries.html - http://www.vlsitechnology.org/synopsys/vsclib013.lib - -The command "synth" provides a good default synthesis script (see "help synth"). -If possible a synthesis script should borrow from "synth". For example: - - # the high-level stuff - hierarchy - synth -run coarse - - # mapping to internal cells - techmap; opt -fast - dfflibmap -liberty mycells.lib - abc -liberty mycells.lib - clean - -Yosys is under construction. A more detailed documentation will follow. - - -Unsupported Verilog-2005 Features -================================= - -The following Verilog-2005 features are not supported by -yosys and there are currently no plans to add support -for them: - -- Non-synthesizable language features as defined in - IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002 - -- The "tri", "triand", "trior", "wand" and "wor" net types - -- The "config" keyword and library map files - -- The "disable", "primitive" and "specify" statements - -- Latched logic (is synthesized as logic with feedback loops) - - -Verilog Attributes and non-standard features -============================================ - -- The 'full_case' attribute on case statements is supported - (also the non-standard "// synopsys full_case" directive) - -- The 'parallel_case' attribute on case statements is supported - (also the non-standard "// synopsys parallel_case" directive) - -- The "// synopsys translate_off" and "// synopsys translate_on" - directives are also supported (but the use of `ifdef .. `endif - is strongly recommended instead). - -- The "nomem2reg" attribute on modules or arrays prohibits the - automatic early conversion of arrays to separate registers. This - is potentially dangerous. Usually the front-end has good reasons - for converting an array to a list of registers. Prohibiting this - step will likely result in incorrect synthesis results. - -- The "mem2reg" attribute on modules or arrays forces the early - conversion of arrays to separate registers. - -- The "nomeminit" attribute on modules or arrays prohibits the - creation of initialized memories. This effectively puts "mem2reg" - on all memories that are written to in an "initial" block and - are not ROMs. - -- The "nolatches" attribute on modules or always-blocks - prohibits the generation of logic-loops for latches. Instead - all not explicitly assigned values default to x-bits. This does - not affect clocked storage elements such as flip-flops. - -- The "nosync" attribute on registers prohibits the generation of a - storage element. The register itself will always have all bits set - to 'x' (undefined). The variable may only be used as blocking assigned - temporary variable within an always block. This is mostly used internally - by yosys to synthesize Verilog functions and access arrays. - -- The "onehot" attribute on wires mark them as onehot state register. This - is used for example for memory port sharing and set by the fsm_map pass. - -- The "blackbox" attribute on modules is used to mark empty stub modules - that have the same ports as the real thing but do not contain information - on the internal configuration. This modules are only used by the synthesis - passes to identify input and output ports of cells. The Verilog backend - also does not output blackbox modules on default. - -- The "keep" attribute on cells and wires is used to mark objects that should - never be removed by the optimizer. This is used for example for cells that - have hidden connections that are not part of the netlist, such as IO pads. - Setting the "keep" attribute on a module has the same effect as setting it - on all instances of the module. - -- The "keep_hierarchy" attribute on cells and modules keeps the "flatten" - command from flattening the indicated cells and modules. - -- The "init" attribute on wires is set by the frontend when a register is - initialized "FPGA-style" with 'reg foo = val'. It can be used during synthesis - to add the necessary reset logic. - -- The "top" attribute on a module marks this module as the top of the - design hierarchy. The "hierarchy" command sets this attribute when called - with "-top". Other commands, such as "flatten" and various backends - use this attribute to determine the top module. - -- The "src" attribute is set on cells and wires created by to the string - ":" by the HDL front-end and is then carried - through the synthesis. When entities are combined, a new |-separated - string is created that contains all the string from the original entities. - -- In addition to the (* ... *) attribute syntax, yosys supports - the non-standard {* ... *} attribute syntax to set default attributes - for everything that comes after the {* ... *} statement. (Reset - by adding an empty {* *} statement.) - -- In module parameter and port declarations, and cell port and parameter - lists, a trailing comma is ignored. This simplifies writing verilog code - generators a bit in some cases. - -- Modules can be declared with "module mod_name(...);" (with three dots - instead of a list of module ports). With this syntax it is sufficient - to simply declare a module port as 'input' or 'output' in the module - body. - -- When defining a macro with `define, all text between triple double quotes - is interpreted as macro body, even if it contains unescaped newlines. The - tipple double quotes are removed from the macro body. For example: - - `define MY_MACRO(a, b) """ - assign a = 23; - assign b = 42; - """ - -- The attribute "via_celltype" can be used to implement a Verilog task or - function by instantiating the specified cell type. The value is the name - of the cell type to use. For functions the name of the output port can - be specified by appending it to the cell type separated by a whitespace. - The body of the task or function is unused in this case and can be used - to specify a behavioral model of the cell type for simulation. For example: - - module my_add3(A, B, C, Y); - parameter WIDTH = 8; - input [WIDTH-1:0] A, B, C; - output [WIDTH-1:0] Y; - ... - endmodule - - module top; - ... - (* via_celltype = "my_add3 Y" *) - (* via_celltype_defparam_WIDTH = 32 *) - function [31:0] add3; - input [31:0] A, B, C; - begin - add3 = A + B + C; - end - endfunction - ... - endmodule - -- A limited subset of DPI-C functions is supported. The plugin mechanism - (see "help plugin") can be used to load .so files with implementations - of DPI-C routines. As a non-standard extension it is possible to specify - a plugin alias using the ":" syntax. for example: - - module dpitest; - import "DPI-C" function foo:round = real my_round (real); - parameter real r = my_round(12.345); - endmodule - - $ yosys -p 'plugin -a foo -i /lib/libm.so; read_verilog dpitest.v' - -- Sized constants (the syntax 's?[bodh]) support constant - expressions as . If the expression is not a simple identifier, it - must be put in parentheses. Examples: WIDTH'd42, (4+2)'b101010 - -- The system tasks $finish and $display are supported in initial blocks - in an unconditional context (only if/case statements on parameters - and constant values). The intended use for this is synthesis-time DRC. - - -Non-standard or SystemVerilog features for formal verification -============================================================== - -- Support for "assert", "assume", and "restrict" is enabled when - read_verilog is called with -formal. - -- The system task $initstate evaluates to 1 in the initial state and - to 0 otherwise. - -- The system task $anyconst evaluates to any constant value. - -- The system task $anyseq evaluates to any value, possibly a different - value in each cycle. - -- The SystemVerilog tasks $past, $stable, $rose and $fell are supported - in any clocked block. - -- The syntax @($global_clock) can be used to create FFs that have no - explicit clock input ($ff cells). - - -Supported features from SystemVerilog -===================================== - -When read_verilog is called with -sv, it accepts some language features -from SystemVerilog: - -- The "assert" statement from SystemVerilog is supported in its most basic - form. In module context: "assert property ();" and within an - always block: "assert();". It is transformed to a $assert cell. - -- The "assume" and "restrict" statements from SystemVerilog are also - supported. The same limitations as with the "assert" statement apply. - -- The keywords "always_comb", "always_ff" and "always_latch", "logic" and - "bit" are supported. - -- SystemVerilog packages are supported. Once a SystemVerilog file is read - into a design with "read_verilog", all its packages are available to - SystemVerilog files being read into the same design afterwards. - - -Building the documentation -========================== - -Note that there is no need to build the manual if you just want to read it. -Simply download the PDF from http://www.clifford.at/yosys/documentation.html -instead. - -On Ubuntu, texlive needs these packages to be able to build the manual: - - sudo apt-get install texlive-binaries - sudo apt-get install texlive-science # install algorithm2e.sty - sudo apt-get install texlive-bibtex-extra # gets multibib.sty - sudo apt-get install texlive-fonts-extra # gets skull.sty and dsfont.sty - sudo apt-get install texlive-publishers # IEEEtran.cls - -Also the non-free font luximono should be installed, there is unfortunately -no Ubuntu package for this so it should be installed separately using -`getnonfreefonts`: - - wget https://tug.org/fonts/getnonfreefonts/install-getnonfreefonts - sudo texlua install-getnonfreefonts # will install to /usr/local by default, can be changed by editing BINDIR at MANDIR at the top of the script - getnonfreefonts luximono # installs to /home/user/texmf - -Then execute, from the root of the repository: - - make manual - -Notes: - -- To run `make manual` you need to have installed yosys with `make install`, - otherwise it will fail on finding `kernel/yosys.h` while building - `PRESENTATION_Prog`. - diff --git a/README.md b/README.md new file mode 100644 index 000000000..0517f9253 --- /dev/null +++ b/README.md @@ -0,0 +1,444 @@ +``` +yosys -- Yosys Open SYnthesis Suite + +Copyright (C) 2012 - 2016 Clifford Wolf + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +``` + + +yosys – Yosys Open SYnthesis Suite +=================================== + +This is a framework for RTL synthesis tools. It currently has +extensive Verilog-2005 support and provides a basic set of +synthesis algorithms for various application domains. + +Yosys can be adapted to perform any synthesis job by combining +the existing passes (algorithms) using synthesis scripts and +adding additional passes as needed by extending the yosys C++ +code base. + +Yosys is free software licensed under the ISC license (a GPL +compatible license that is similar in terms to the MIT license +or the 2-clause BSD license). + + +Web Site +======== + +More information and documentation can be found on the Yosys web site: +http://www.clifford.at/yosys/ + + +Getting Started +=============== + +You need a C++ compiler with C++11 support (up-to-date CLANG or GCC is +recommended) and some standard tools such as GNU Flex, GNU Bison, and GNU Make. +TCL, readline and libffi are optional (see ENABLE_* settings in Makefile). +Xdot (graphviz) is used by the "show" command in yosys to display schematics. +For example on Ubuntu Linux 16.04 LTS the following commands will install all +prerequisites for building yosys: + + $ sudo apt-get install build-essential clang bison flex \ + libreadline-dev gawk tcl-dev libffi-dev git mercurial \ + graphviz xdot pkg-config python3 + +There are also pre-compiled Yosys binary packages for Ubuntu and Win32 as well +as a source distribution for Visual Studio. Visit the Yosys download page for +more information: http://www.clifford.at/yosys/download.html + +To configure the build system to use a specific compiler, use one of + + $ make config-clang + $ make config-gcc + +For other compilers and build configurations it might be +necessary to make some changes to the config section of the +Makefile. + + $ vi Makefile # ..or.. + $ vi Makefile.conf + +To build Yosys simply type 'make' in this directory. + + $ make + $ make test + $ sudo make install + +Note that this also downloads, builds and installs ABC (using yosys-abc +as executable name). + +Yosys can be used with the interactive command shell, with +synthesis scripts or with command line arguments. Let's perform +a simple synthesis job using the interactive command shell: + + $ ./yosys + yosys> + +the command "help" can be used to print a list of all available +commands and "help " to print details on the specified command: + + yosys> help help + +reading the design using the Verilog frontend: + + yosys> read_verilog tests/simple/fiedler-cooley.v + +writing the design to the console in yosys's internal format: + + yosys> write_ilang + +elaborate design hierarchy: + + yosys> hierarchy + +convert processes ("always" blocks) to netlist elements and perform +some simple optimizations: + + yosys> proc; opt + +display design netlist using xdot: + + yosys> show + +the same thing using 'gv' as postscript viewer: + + yosys> show -format ps -viewer gv + +translating netlist to gate logic and perform some simple optimizations: + + yosys> techmap; opt + +write design netlist to a new Verilog file: + + yosys> write_verilog synth.v + +a similar synthesis can be performed using yosys command line options only: + + $ ./yosys -o synth.v -p hierarchy -p proc -p opt \ + -p techmap -p opt tests/simple/fiedler-cooley.v + +or using a simple synthesis script: + + $ cat synth.ys + read_verilog tests/simple/fiedler-cooley.v + hierarchy; proc; opt; techmap; opt + write_verilog synth.v + + $ ./yosys synth.ys + +It is also possible to only have the synthesis commands but not the read/write +commands in the synthesis script: + + $ cat synth.ys + hierarchy; proc; opt; techmap; opt + + $ ./yosys -o synth.v tests/simple/fiedler-cooley.v synth.ys + +The following very basic synthesis script should work well with all designs: + + # check design hierarchy + hierarchy + + # translate processes (always blocks) + proc; opt + + # detect and optimize FSM encodings + fsm; opt + + # implement memories (arrays) + memory; opt + + # convert to gate logic + techmap; opt + +If ABC is enabled in the Yosys build configuration and a cell library is given +in the liberty file mycells.lib, the following synthesis script will synthesize +for the given cell library: + + # the high-level stuff + hierarchy; proc; fsm; opt; memory; opt + + # mapping to internal cell library + techmap; opt + + # mapping flip-flops to mycells.lib + dfflibmap -liberty mycells.lib + + # mapping logic to mycells.lib + abc -liberty mycells.lib + + # cleanup + clean + +If you do not have a liberty file but want to test this synthesis script, +you can use the file examples/cmos/cmos_cells.lib from the yosys sources. + +Liberty file downloads for and information about free and open ASIC standard +cell libraries can be found here: + +- http://www.vlsitechnology.org/html/libraries.html +- http://www.vlsitechnology.org/synopsys/vsclib013.lib + +The command "synth" provides a good default synthesis script (see "help synth"). +If possible a synthesis script should borrow from "synth". For example: + + # the high-level stuff + hierarchy + synth -run coarse + + # mapping to internal cells + techmap; opt -fast + dfflibmap -liberty mycells.lib + abc -liberty mycells.lib + clean + +Yosys is under construction. A more detailed documentation will follow. + + +Unsupported Verilog-2005 Features +================================= + +The following Verilog-2005 features are not supported by +yosys and there are currently no plans to add support +for them: + +- Non-synthesizable language features as defined in + IEC 62142(E):2005 / IEEE Std. 1364.1(E):2002 + +- The "tri", "triand", "trior", "wand" and "wor" net types + +- The "config" keyword and library map files + +- The "disable", "primitive" and "specify" statements + +- Latched logic (is synthesized as logic with feedback loops) + + +Verilog Attributes and non-standard features +============================================ + +- The 'full_case' attribute on case statements is supported + (also the non-standard "// synopsys full_case" directive) + +- The 'parallel_case' attribute on case statements is supported + (also the non-standard "// synopsys parallel_case" directive) + +- The "// synopsys translate_off" and "// synopsys translate_on" + directives are also supported (but the use of ``` `ifdef .. `endif ``` + is strongly recommended instead). + +- The "nomem2reg" attribute on modules or arrays prohibits the + automatic early conversion of arrays to separate registers. This + is potentially dangerous. Usually the front-end has good reasons + for converting an array to a list of registers. Prohibiting this + step will likely result in incorrect synthesis results. + +- The "mem2reg" attribute on modules or arrays forces the early + conversion of arrays to separate registers. + +- The "nomeminit" attribute on modules or arrays prohibits the + creation of initialized memories. This effectively puts "mem2reg" + on all memories that are written to in an "initial" block and + are not ROMs. + +- The "nolatches" attribute on modules or always-blocks + prohibits the generation of logic-loops for latches. Instead + all not explicitly assigned values default to x-bits. This does + not affect clocked storage elements such as flip-flops. + +- The "nosync" attribute on registers prohibits the generation of a + storage element. The register itself will always have all bits set + to 'x' (undefined). The variable may only be used as blocking assigned + temporary variable within an always block. This is mostly used internally + by yosys to synthesize Verilog functions and access arrays. + +- The "onehot" attribute on wires mark them as onehot state register. This + is used for example for memory port sharing and set by the fsm_map pass. + +- The "blackbox" attribute on modules is used to mark empty stub modules + that have the same ports as the real thing but do not contain information + on the internal configuration. This modules are only used by the synthesis + passes to identify input and output ports of cells. The Verilog backend + also does not output blackbox modules on default. + +- The "keep" attribute on cells and wires is used to mark objects that should + never be removed by the optimizer. This is used for example for cells that + have hidden connections that are not part of the netlist, such as IO pads. + Setting the "keep" attribute on a module has the same effect as setting it + on all instances of the module. + +- The "keep_hierarchy" attribute on cells and modules keeps the "flatten" + command from flattening the indicated cells and modules. + +- The "init" attribute on wires is set by the frontend when a register is + initialized "FPGA-style" with 'reg foo = val'. It can be used during synthesis + to add the necessary reset logic. + +- The "top" attribute on a module marks this module as the top of the + design hierarchy. The "hierarchy" command sets this attribute when called + with "-top". Other commands, such as "flatten" and various backends + use this attribute to determine the top module. + +- The "src" attribute is set on cells and wires created by to the string + ":" by the HDL front-end and is then carried + through the synthesis. When entities are combined, a new |-separated + string is created that contains all the string from the original entities. + +- In addition to the ``(* ... *)`` attribute syntax, yosys supports + the non-standard ``{* ... *}`` attribute syntax to set default attributes + for everything that comes after the ``{* ... *}`` statement. (Reset + by adding an empty ``{* *}`` statement.) + +- In module parameter and port declarations, and cell port and parameter + lists, a trailing comma is ignored. This simplifies writing verilog code + generators a bit in some cases. + +- Modules can be declared with "module mod_name(...);" (with three dots + instead of a list of module ports). With this syntax it is sufficient + to simply declare a module port as 'input' or 'output' in the module + body. + +- When defining a macro with `define, all text between triple double quotes + is interpreted as macro body, even if it contains unescaped newlines. The + tipple double quotes are removed from the macro body. For example: + + `define MY_MACRO(a, b) """ + assign a = 23; + assign b = 42; + """ + +- The attribute "via_celltype" can be used to implement a Verilog task or + function by instantiating the specified cell type. The value is the name + of the cell type to use. For functions the name of the output port can + be specified by appending it to the cell type separated by a whitespace. + The body of the task or function is unused in this case and can be used + to specify a behavioral model of the cell type for simulation. For example: + + module my_add3(A, B, C, Y); + parameter WIDTH = 8; + input [WIDTH-1:0] A, B, C; + output [WIDTH-1:0] Y; + ... + endmodule + + module top; + ... + (* via_celltype = "my_add3 Y" *) + (* via_celltype_defparam_WIDTH = 32 *) + function [31:0] add3; + input [31:0] A, B, C; + begin + add3 = A + B + C; + end + endfunction + ... + endmodule + +- A limited subset of DPI-C functions is supported. The plugin mechanism + (see "help plugin") can be used to load .so files with implementations + of DPI-C routines. As a non-standard extension it is possible to specify + a plugin alias using the ":" syntax. for example: + + module dpitest; + import "DPI-C" function foo:round = real my_round (real); + parameter real r = my_round(12.345); + endmodule + + $ yosys -p 'plugin -a foo -i /lib/libm.so; read_verilog dpitest.v' + +- Sized constants (the syntax 's?[bodh]) support constant + expressions as . If the expression is not a simple identifier, it + must be put in parentheses. Examples: WIDTH'd42, (4+2)'b101010 + +- The system tasks $finish and $display are supported in initial blocks + in an unconditional context (only if/case statements on parameters + and constant values). The intended use for this is synthesis-time DRC. + + +Non-standard or SystemVerilog features for formal verification +============================================================== + +- Support for "assert", "assume", and "restrict" is enabled when + read_verilog is called with -formal. + +- The system task $initstate evaluates to 1 in the initial state and + to 0 otherwise. + +- The system task $anyconst evaluates to any constant value. + +- The system task $anyseq evaluates to any value, possibly a different + value in each cycle. + +- The SystemVerilog tasks $past, $stable, $rose and $fell are supported + in any clocked block. + +- The syntax @($global_clock) can be used to create FFs that have no + explicit clock input ($ff cells). + + +Supported features from SystemVerilog +===================================== + +When read_verilog is called with -sv, it accepts some language features +from SystemVerilog: + +- The "assert" statement from SystemVerilog is supported in its most basic + form. In module context: "assert property ();" and within an + always block: "assert();". It is transformed to a $assert cell. + +- The "assume" and "restrict" statements from SystemVerilog are also + supported. The same limitations as with the "assert" statement apply. + +- The keywords "always_comb", "always_ff" and "always_latch", "logic" and + "bit" are supported. + +- SystemVerilog packages are supported. Once a SystemVerilog file is read + into a design with "read_verilog", all its packages are available to + SystemVerilog files being read into the same design afterwards. + + +Building the documentation +========================== + +Note that there is no need to build the manual if you just want to read it. +Simply download the PDF from http://www.clifford.at/yosys/documentation.html +instead. + +On Ubuntu, texlive needs these packages to be able to build the manual: + + sudo apt-get install texlive-binaries + sudo apt-get install texlive-science # install algorithm2e.sty + sudo apt-get install texlive-bibtex-extra # gets multibib.sty + sudo apt-get install texlive-fonts-extra # gets skull.sty and dsfont.sty + sudo apt-get install texlive-publishers # IEEEtran.cls + +Also the non-free font luximono should be installed, there is unfortunately +no Ubuntu package for this so it should be installed separately using +`getnonfreefonts`: + + wget https://tug.org/fonts/getnonfreefonts/install-getnonfreefonts + sudo texlua install-getnonfreefonts # will install to /usr/local by default, can be changed by editing BINDIR at MANDIR at the top of the script + getnonfreefonts luximono # installs to /home/user/texmf + +Then execute, from the root of the repository: + + make manual + +Notes: + +- To run `make manual` you need to have installed yosys with `make install`, + otherwise it will fail on finding `kernel/yosys.h` while building + `PRESENTATION_Prog`.