diff --git a/README.md b/README.md index e2fb4c9d8..0780b8fc4 100644 --- a/README.md +++ b/README.md @@ -273,371 +273,6 @@ source with another tool such as ``verilator --lint-only``. -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`` and ``trior`` net types - -- The ``config`` and ``disable`` keywords and library map files - - -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 ``nowrshmsk`` attribute on a register prohibits the generation of - shift-and-mask type circuits for writing to bit slices of that register. - -- The ``onehot`` attribute on wires mark them as one-hot 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. ``read_verilog``, unless - called with ``-noblackbox`` will automatically set the blackbox attribute - on any empty module it reads. - -- The ``noblackbox`` attribute set on an empty module prevents ``read_verilog`` - from automatically setting the blackbox attribute on the module. - -- The ``whitebox`` attribute on modules triggers the same behavior as - ``blackbox``, but is for whitebox modules, i.e. library modules that - contain a behavioral model of the cell type. - -- The ``lib_whitebox`` attribute overwrites ``whitebox`` when ``read_verilog`` - is run in `-lib` mode. Otherwise it's automatically removed. - -- The ``dynports`` attribute is used by the Verilog front-end to mark modules - that have ports with a width that depends on a parameter. - -- The ``hdlname`` attribute is used by some passes to document the original - (HDL) name of a module when renaming a module. It should contain a single - name, or, when describing a hierarchical name in a flattened design, multiple - names separated by a single space character. - -- 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 `gate_cost_equivalent` attribute on a module can be used to specify - the estimated cost of the module as a number of basic gate instances. See - the help message of command `keep_hierarchy` which interprets this - attribute. - -- 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. - -- The ``defaultvalue`` attribute is used to store default values for - module inputs. The attribute is attached to the input wire by the HDL - front-end when the input is declared with a default value. - -- The ``parameter`` and ``localparam`` attributes are used to mark wires - that represent module parameters or localparams (when the HDL front-end - is run in ``-pwires`` mode). - -- Wires marked with the ``hierconn`` attribute are connected to wires with the - same name (format ``cell_name.identifier``) when they are imported from - sub-modules by ``flatten``. - -- The ``clkbuf_driver`` attribute can be set on an output port of a blackbox - module to mark it as a clock buffer output, and thus prevent ``clkbufmap`` - from inserting another clock buffer on a net driven by such output. - -- The ``clkbuf_sink`` attribute can be set on an input port of a module to - request clock buffer insertion by the ``clkbufmap`` pass. - -- The ``clkbuf_inv`` attribute can be set on an output port of a module - with the value set to the name of an input port of that module. When - the ``clkbufmap`` would otherwise insert a clock buffer on this output, - it will instead try inserting the clock buffer on the input port (this - is used to implement clock inverter cells that clock buffer insertion - will "see through"). - -- The ``clkbuf_inhibit`` is the default attribute to set on a wire to prevent - automatic clock buffer insertion by ``clkbufmap``. This behaviour can be - overridden by providing a custom selection to ``clkbufmap``. - -- The ``invertible_pin`` attribute can be set on a port to mark it as - invertible via a cell parameter. The name of the inversion parameter - is specified as the value of this attribute. The value of the inversion - parameter must be of the same width as the port, with 1 indicating - an inverted bit and 0 indicating a non-inverted bit. - -- The ``iopad_external_pin`` attribute on a blackbox module's port marks - it as the external-facing pin of an I/O pad, and prevents ``iopadmap`` - from inserting another pad cell on it. - -- The module attribute ``abc9_lut`` is an integer attribute indicating to - `abc9` that this module describes a LUT with an area cost of this value, and - propagation delays described using `specify` statements. - -- The module attribute ``abc9_box`` is a boolean specifying a black/white-box - definition, with propagation delays described using `specify` statements, for - use by `abc9`. - -- The port attribute ``abc9_carry`` marks the carry-in (if an input port) and - carry-out (if output port) ports of a box. This information is necessary for - `abc9` to preserve the integrity of carry-chains. Specifying this attribute - onto a bus port will affect only its most significant bit. - -- The module attribute ``abc9_flop`` is a boolean marking the module as a - flip-flop. This allows `abc9` to analyse its contents in order to perform - sequential synthesis. - -- The frontend sets attributes ``always_comb``, ``always_latch`` and - ``always_ff`` on processes derived from SystemVerilog style always blocks - according to the type of the always. These are checked for correctness in - ``proc_dlatch``. - -- The cell attribute ``wildcard_port_conns`` represents wildcard port - connections (SystemVerilog ``.*``). These are resolved to concrete - connections to matching wires in ``hierarchy``. - -- 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 - triple 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 - -- The ``wiretype`` attribute is added by the verilog parser for wires of a - typedef'd type to indicate the type identifier. - -- Various ``enum_value_{value}`` attributes are added to wires of an enumerated type - to give a map of possible enum items to their values. - -- The ``enum_base_type`` attribute is added to enum items to indicate which - enum they belong to (enums -- anonymous and otherwise -- are - automatically named with an auto-incrementing counter). Note that enums - are currently not strongly typed. - -- 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``, ``$stop`` and ``$display`` are supported in - initial blocks in an unconditional context (only if/case statements on - expressions over parameters and constant values are allowed). The intended - use for this is synthesis-time DRC. - -- There is limited support for converting ``specify`` .. ``endspecify`` - statements to special ``$specify2``, ``$specify3``, and ``$specrule`` cells, - for use in blackboxes and whiteboxes. Use ``read_verilog -specify`` to - enable this functionality. (By default these blocks are ignored.) - -- The ``reprocess_after`` internal attribute is used by the Verilog frontend to - mark cells with bindings which might depend on the specified instantiated - module. Modules with such cells will be reprocessed during the ``hierarchy`` - pass once the referenced module definition(s) become available. - -- The ``smtlib2_module`` attribute can be set on a blackbox module to specify a - formal model directly using SMT-LIB 2. For such a module, the - ``smtlib2_comb_expr`` attribute can be used on output ports to define their - value using an SMT-LIB 2 expression. For example: - - (* blackbox *) - (* smtlib2_module *) - module submod(a, b); - input [7:0] a; - (* smtlib2_comb_expr = "(bvnot a)" *) - output [7:0] b; - endmodule - -Non-standard or SystemVerilog features for formal verification -============================================================== - -- Support for ``assert``, ``assume``, ``restrict``, and ``cover`` 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 function ``$anyconst`` evaluates to any constant value. This is - equivalent to declaring a reg as ``rand const``, but also works outside - of checkers. (Yosys also supports ``rand const`` outside checkers.) - -- The system function ``$anyseq`` evaluates to any value, possibly a different - value in each cycle. This is equivalent to declaring a reg as ``rand``, - but also works outside of checkers. (Yosys also supports ``rand`` - variables outside checkers.) - -- The system functions ``$allconst`` and ``$allseq`` can be used to construct - formal exist-forall problems. Assumptions only hold if the trace satisfies - the assumption for all ``$allconst/$allseq`` values. For assertions and cover - statements it is sufficient if just one ``$allconst/$allseq`` value triggers - the property (similar to ``$anyconst/$anyseq``). - -- Wires/registers declared using the ``anyconst/anyseq/allconst/allseq`` attribute - (for example ``(* anyconst *) reg [7:0] foobar;``) will behave as if driven - by a ``$anyconst/$anyseq/$allconst/$allseq`` function. - -- 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). The same can be achieved by using - ``@(posedge )`` or ``@(negedge )`` when ```` - is marked with the ``(* gclk *)`` Verilog attribute. - -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 an ``$assert`` cell. - -- The ``assume``, ``restrict``, and ``cover`` 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. - -- Declaring free variables with ``rand`` and ``rand const`` is supported. - -- Checkers without a port list that do not need to be instantiated (but instead - behave like a named block) 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. - -- typedefs are supported (including inside packages) - - type casts are currently not supported - -- enums are supported (including inside packages) - - but are currently not strongly typed - -- packed structs and unions are supported - - arrays of packed structs/unions are currently not supported - - structure literals are currently not supported - -- multidimensional arrays are supported - - array assignment of unpacked arrays is currently not supported - - array literals are currently not supported - -- SystemVerilog interfaces (SVIs) are supported. Modports for specifying whether - ports are inputs or outputs are supported. - -- Assignments within expressions are supported. - - Building the documentation ========================== @@ -673,3 +308,68 @@ From the root of the repository, run `make docs`. This will build/rebuild yosys as necessary before generating the website documentation from the yosys help commands. To build for pdf instead of html, call `make docs DOC_TARGET=latexpdf`. + +Building for Windows +==================== + +Creating the Visual Studio Template Project +------------------------------------------- + +1. Create an empty Visual C++ Win32 Console App project + + Microsoft Visual Studio Express 2013 for Windows Desktop + Open New Project Wizard (File -> New Project..) + + Project Name: YosysVS + Solution Name: YosysVS + [X] Create directory for solution + [ ] Add to source control + + [X] Console applications + [X] Empty Project + [ ] SDL checks + +2. Open YosysVS Project Properties + + Select Configuration: All Configurations + + C/C++ -> General -> Additional Include Directories + Add: ..\yosys + + C/C++ -> Preprocessor -> Preprocessor Definitions + Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS + +3. Resulting file system tree: + + YosysVS/ + YosysVS/YosysVS + YosysVS/YosysVS/YosysVS.vcxproj + YosysVS/YosysVS/YosysVS.vcxproj.filters + YosysVS/YosysVS.sdf + YosysVS/YosysVS.sln + YosysVS/YosysVS.v12.suo + +4. Zip YosysVS as YosysVS-Tpl-v1.zip + +Compiling with Visual Studio +---------------------------- + +Visual Studio builds are not directly supported by build scripts, but they are still possible. + +1. Easy way + + - Go to https://github.com/YosysHQ/yosys/actions/workflows/vs.yml?query=branch%3Amain + - Click on the most recent completed run + - In Artifacts region find vcxsrc and click on it to download + - Unpack downloaded ZIP file + - Open YosysVS.sln with Visual Studio + +2. Using WSL or MSYS2 + + - Make sure to have make, python3 and git available + - Git clone yosys repository + - Execute ```make vcxsrc YOSYS_VER=latest``` + - File yosys-win32-vcxsrc-latest.zip will be created + - Transfer that file to location visible by Windows application + - Unpack ZIP + - Open YosysVS.sln with Visual Studio diff --git a/guidelines/CodingStyle b/docs/source/yosys_internals/extending_yosys/contributing.rst similarity index 86% rename from guidelines/CodingStyle rename to docs/source/yosys_internals/extending_yosys/contributing.rst index 491507cdd..364067f8e 100644 --- a/guidelines/CodingStyle +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -1,9 +1,11 @@ -Coding Style -============ +Contributing to Yosys +===================== +Coding Style +------------ Formatting of code ------------------- +~~~~~~~~~~~~~~~~~~ - Yosys code is using tabs for indentation. Tabs are 8 characters. @@ -23,7 +25,7 @@ Formatting of code C++ Language -------------- +~~~~~~~~~~~~ Yosys is written in C++17. @@ -31,4 +33,4 @@ In general Yosys uses "int" instead of "size_t". To avoid compiler warnings for implicit type casts, always use "GetSize(foobar)" instead of "foobar.size()". (GetSize() is defined in kernel/yosys.h) -Use range-based for loops whenever applicable. \ No newline at end of file +Use range-based for loops whenever applicable. diff --git a/docs/source/yosys_internals/extending_yosys/index.rst b/docs/source/yosys_internals/extending_yosys/index.rst index 88f36d526..4ee21517b 100644 --- a/docs/source/yosys_internals/extending_yosys/index.rst +++ b/docs/source/yosys_internals/extending_yosys/index.rst @@ -11,5 +11,6 @@ of interest for developers looking to customise Yosys builds. extensions build_verific functional_ir + contributing test_suites diff --git a/docs/source/yosys_internals/extending_yosys/test_suites.rst b/docs/source/yosys_internals/extending_yosys/test_suites.rst index 7a6b74977..8a9c4711e 100644 --- a/docs/source/yosys_internals/extending_yosys/test_suites.rst +++ b/docs/source/yosys_internals/extending_yosys/test_suites.rst @@ -1,7 +1,7 @@ Testing Yosys ============= -.. todo:: more about the included test suite +.. TODO:: more about the included test suite and how to add tests Automatic testing ----------------- @@ -23,3 +23,76 @@ For up to date information, including OS versions, refer to `the git actions page`_. .. _the git actions page: https://github.com/YosysHQ/yosys/actions + +.. todo:: are unit tests currently working + +.. + How to add a unit test + ---------------------- + + Unit test brings some advantages, briefly, we can list some of them (reference + [1](https://en.wikipedia.org/wiki/Unit_testing)): + + * Tests reduce bugs in new features; + * Tests reduce bugs in existing features; + * Tests are good documentation; + * Tests reduce the cost of change; + * Tests allow refactoring; + + With those advantages in mind, it was required to choose a framework which fits + well with C/C++ code. Hence, it was chosen (google test) + [https://github.com/google/googletest], because it is largely used and it is + relatively easy learn. + + Install and configure google test (manually) + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + In this section, you will see a brief description of how to install google + test. However, it is strongly recommended that you take a look to the official + repository (https://github.com/google/googletest) and refers to that if you + have any problem to install it. Follow the steps below: + + * Install: cmake and pthread + * Clone google test project from: https://github.com/google/googletest and + enter in the project directory + * Inside project directory, type: + + ``` + cmake -DBUILD_SHARED_LIBS=ON . + make + ``` + + * After compilation, copy all "*.so" inside directory "googlemock" and + "googlemock/gtest" to "/usr/lib/" + * Done! Now you can compile your tests. + + If you have any problem, go to the official repository to find help. + + Ps.: Some distros already have googletest packed. If your distro supports it, + you can use it instead of compile. + + Create a new unit test + ~~~~~~~~~~~~~~~~~~~~~~ + + If you want to add new unit tests for Yosys, just follow the steps below: + + * Go to directory "yosys/test/unit/" + * In this directory you can find something similar Yosys's directory structure. + To create your unit test file you have to follow this pattern: + fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the + unit test for kernel/celledges.cc, you will need to create a file like this: + tests/unit/kernel/celledgesTest.cc; + * Implement your unit test + + Run unit tests + ~~~~~~~~~~~~~~ + + To compile and run all unit tests, just go to yosys root directory and type: + ``` + make unit-test + ``` + + If you want to remove all unit test files, type: + ``` + make clean-unit-test + ``` diff --git a/docs/source/yosys_internals/index.rst b/docs/source/yosys_internals/index.rst index efd865623..9631e8653 100644 --- a/docs/source/yosys_internals/index.rst +++ b/docs/source/yosys_internals/index.rst @@ -38,3 +38,4 @@ as reference to implement a similar system in any language. formats/index extending_yosys/index techmap + verilog diff --git a/docs/source/yosys_internals/verilog.rst b/docs/source/yosys_internals/verilog.rst new file mode 100644 index 000000000..3dc16eecc --- /dev/null +++ b/docs/source/yosys_internals/verilog.rst @@ -0,0 +1,369 @@ +Notes on Verilog support in Yosys +================================= + +.. TODO:: how much of this is specific to the read_verilog and should be in :doc:`/yosys_internals/flow/verilog_frontend`? + +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`` and ``trior`` net types + +- The ``config`` and ``disable`` keywords and library map files + + +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 ``nowrshmsk`` attribute on a register prohibits the generation of + shift-and-mask type circuits for writing to bit slices of that register. + +- The ``onehot`` attribute on wires mark them as one-hot 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. ``read_verilog``, unless + called with ``-noblackbox`` will automatically set the blackbox attribute + on any empty module it reads. + +- The ``noblackbox`` attribute set on an empty module prevents ``read_verilog`` + from automatically setting the blackbox attribute on the module. + +- The ``whitebox`` attribute on modules triggers the same behavior as + ``blackbox``, but is for whitebox modules, i.e. library modules that + contain a behavioral model of the cell type. + +- The ``lib_whitebox`` attribute overwrites ``whitebox`` when ``read_verilog`` + is run in `-lib` mode. Otherwise it's automatically removed. + +- The ``dynports`` attribute is used by the Verilog front-end to mark modules + that have ports with a width that depends on a parameter. + +- The ``hdlname`` attribute is used by some passes to document the original + (HDL) name of a module when renaming a module. It should contain a single + name, or, when describing a hierarchical name in a flattened design, multiple + names separated by a single space character. + +- 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 `gate_cost_equivalent` attribute on a module can be used to specify + the estimated cost of the module as a number of basic gate instances. See + the help message of command `keep_hierarchy` which interprets this + attribute. + +- 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. + +- The ``defaultvalue`` attribute is used to store default values for + module inputs. The attribute is attached to the input wire by the HDL + front-end when the input is declared with a default value. + +- The ``parameter`` and ``localparam`` attributes are used to mark wires + that represent module parameters or localparams (when the HDL front-end + is run in ``-pwires`` mode). + +- Wires marked with the ``hierconn`` attribute are connected to wires with the + same name (format ``cell_name.identifier``) when they are imported from + sub-modules by ``flatten``. + +- The ``clkbuf_driver`` attribute can be set on an output port of a blackbox + module to mark it as a clock buffer output, and thus prevent ``clkbufmap`` + from inserting another clock buffer on a net driven by such output. + +- The ``clkbuf_sink`` attribute can be set on an input port of a module to + request clock buffer insertion by the ``clkbufmap`` pass. + +- The ``clkbuf_inv`` attribute can be set on an output port of a module + with the value set to the name of an input port of that module. When + the ``clkbufmap`` would otherwise insert a clock buffer on this output, + it will instead try inserting the clock buffer on the input port (this + is used to implement clock inverter cells that clock buffer insertion + will "see through"). + +- The ``clkbuf_inhibit`` is the default attribute to set on a wire to prevent + automatic clock buffer insertion by ``clkbufmap``. This behaviour can be + overridden by providing a custom selection to ``clkbufmap``. + +- The ``invertible_pin`` attribute can be set on a port to mark it as + invertible via a cell parameter. The name of the inversion parameter + is specified as the value of this attribute. The value of the inversion + parameter must be of the same width as the port, with 1 indicating + an inverted bit and 0 indicating a non-inverted bit. + +- The ``iopad_external_pin`` attribute on a blackbox module's port marks + it as the external-facing pin of an I/O pad, and prevents ``iopadmap`` + from inserting another pad cell on it. + +- The module attribute ``abc9_lut`` is an integer attribute indicating to + `abc9` that this module describes a LUT with an area cost of this value, and + propagation delays described using `specify` statements. + +- The module attribute ``abc9_box`` is a boolean specifying a black/white-box + definition, with propagation delays described using `specify` statements, for + use by `abc9`. + +- The port attribute ``abc9_carry`` marks the carry-in (if an input port) and + carry-out (if output port) ports of a box. This information is necessary for + `abc9` to preserve the integrity of carry-chains. Specifying this attribute + onto a bus port will affect only its most significant bit. + +- The module attribute ``abc9_flop`` is a boolean marking the module as a + flip-flop. This allows `abc9` to analyse its contents in order to perform + sequential synthesis. + +- The frontend sets attributes ``always_comb``, ``always_latch`` and + ``always_ff`` on processes derived from SystemVerilog style always blocks + according to the type of the always. These are checked for correctness in + ``proc_dlatch``. + +- The cell attribute ``wildcard_port_conns`` represents wildcard port + connections (SystemVerilog ``.*``). These are resolved to concrete + connections to matching wires in ``hierarchy``. + +- 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 + triple 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 + +- The ``wiretype`` attribute is added by the verilog parser for wires of a + typedef'd type to indicate the type identifier. + +- Various ``enum_value_{value}`` attributes are added to wires of an enumerated type + to give a map of possible enum items to their values. + +- The ``enum_base_type`` attribute is added to enum items to indicate which + enum they belong to (enums -- anonymous and otherwise -- are + automatically named with an auto-incrementing counter). Note that enums + are currently not strongly typed. + +- 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``, ``$stop`` and ``$display`` are supported in + initial blocks in an unconditional context (only if/case statements on + expressions over parameters and constant values are allowed). The intended + use for this is synthesis-time DRC. + +- There is limited support for converting ``specify`` .. ``endspecify`` + statements to special ``$specify2``, ``$specify3``, and ``$specrule`` cells, + for use in blackboxes and whiteboxes. Use ``read_verilog -specify`` to + enable this functionality. (By default these blocks are ignored.) + +- The ``reprocess_after`` internal attribute is used by the Verilog frontend to + mark cells with bindings which might depend on the specified instantiated + module. Modules with such cells will be reprocessed during the ``hierarchy`` + pass once the referenced module definition(s) become available. + +- The ``smtlib2_module`` attribute can be set on a blackbox module to specify a + formal model directly using SMT-LIB 2. For such a module, the + ``smtlib2_comb_expr`` attribute can be used on output ports to define their + value using an SMT-LIB 2 expression. For example: + + (* blackbox *) + (* smtlib2_module *) + module submod(a, b); + input [7:0] a; + (* smtlib2_comb_expr = "(bvnot a)" *) + output [7:0] b; + endmodule + +Non-standard or SystemVerilog features for formal verification +-------------------------------------------------------------- + +- Support for ``assert``, ``assume``, ``restrict``, and ``cover`` 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 function ``$anyconst`` evaluates to any constant value. This is + equivalent to declaring a reg as ``rand const``, but also works outside + of checkers. (Yosys also supports ``rand const`` outside checkers.) + +- The system function ``$anyseq`` evaluates to any value, possibly a different + value in each cycle. This is equivalent to declaring a reg as ``rand``, + but also works outside of checkers. (Yosys also supports ``rand`` + variables outside checkers.) + +- The system functions ``$allconst`` and ``$allseq`` can be used to construct + formal exist-forall problems. Assumptions only hold if the trace satisfies + the assumption for all ``$allconst/$allseq`` values. For assertions and cover + statements it is sufficient if just one ``$allconst/$allseq`` value triggers + the property (similar to ``$anyconst/$anyseq``). + +- Wires/registers declared using the ``anyconst/anyseq/allconst/allseq`` attribute + (for example ``(* anyconst *) reg [7:0] foobar;``) will behave as if driven + by a ``$anyconst/$anyseq/$allconst/$allseq`` function. + +- 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). The same can be achieved by using + ``@(posedge )`` or ``@(negedge )`` when ```` + is marked with the ``(* gclk *)`` Verilog attribute. + + +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 an ``$assert`` cell. + +- The ``assume``, ``restrict``, and ``cover`` 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. + +- Declaring free variables with ``rand`` and ``rand const`` is supported. + +- Checkers without a port list that do not need to be instantiated (but instead + behave like a named block) 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. + +- typedefs are supported (including inside packages) + - type casts are currently not supported + +- enums are supported (including inside packages) + - but are currently not strongly typed + +- packed structs and unions are supported + - arrays of packed structs/unions are currently not supported + - structure literals are currently not supported + +- multidimensional arrays are supported + - array assignment of unpacked arrays is currently not supported + - array literals are currently not supported + +- SystemVerilog interfaces (SVIs) are supported. Modports for specifying whether + ports are inputs or outputs are supported. + +- Assignments within expressions are supported. diff --git a/guidelines/Checklists b/guidelines/Checklists deleted file mode 100644 index 75af12fa9..000000000 --- a/guidelines/Checklists +++ /dev/null @@ -1,116 +0,0 @@ -Checklist for adding internal cell types -======================================== - -Things to do right away: - - - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells) - - Add to InternalCellChecker::check() in kernel/rtlil.cc - - Add to techlibs/common/simlib.v - - Add to techlibs/common/techmap.v - -Things to do after finalizing the cell interface: - - - Add support to kernel/satgen.h for the new cell type - - Add to docs/source/CHAPTER_CellLib.rst (or just add a fixme to the bottom) - - Maybe add support to the Verilog backend for dumping such cells as expression - - - -Checklist for creating Yosys releases -===================================== - -Update the CHANGELOG file: - - cd ~yosys - gitk & - vi CHANGELOG - - -Update and check documentation: - - cd ~yosys - make docs - - sanity check the figures in docs/images - - if there are any odd things -> investigate - - cd ~yosys - vi README guidelines/* - - is the information provided in those file still up to date - - -Then with default config setting: - - cd ~yosys - make vgtest - - cd ~yosys - ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v - ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v - ./yosys -p 'synth; show' tests/simple/fiedler-cooley.v - ./yosys -p 'synth_xilinx -top up3down5; show' tests/simple/fiedler-cooley.v - - cd ~yosys/examples/cmos - bash testbench.sh - - cd ~yosys/examples/basys3 - bash run.sh - - -Test building plugins with various of the standard passes: - - yosys-config --build test.so equiv_simple.cc - - also check the code examples in guidelines/GettingStarted - - -And if a version of the verific library is currently available: - - cd ~yosys - cat frontends/verific/build_amd64.txt - - follow instructions - - cd frontends/verific - ../../yosys test_navre.ys - - -Finally run all tests with "make config-{clang,gcc}": - - cd ~yosys - make clean - make test - make ystests - make vloghtb - make install - - cd ~yosys-bigsim - make clean - make full - - cd ~vloghammer - make purge gen_issues gen_samples - make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world - chromium-browser report.html - - -Release: - - - set YOSYS_VER to x.y.z in Makefile - - remove "bumpversion" target from Makefile - - update version string in CHANGELOG - git commit -am "Yosys x.y.z" - - - push tag to github - - post changelog on github - - post short release note on reddit - - -Updating the website: - - cd ~yosys - make install - - cd ~yosys-web - make update_show - git commit -am update - make push - - - Read the Docs updates handled by Jenkins on source change diff --git a/guidelines/CodeOfConduct b/guidelines/CodeOfConduct deleted file mode 100644 index 92decd3b6..000000000 --- a/guidelines/CodeOfConduct +++ /dev/null @@ -1,72 +0,0 @@ -Contributor Covenant Code of Conduct - -Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -Our Responsibilities - -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -Scope - -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at contact@yosyshq.com and/or -claire@clairexen.net. All complaints will be reviewed and investigated and -will result in a response that is deemed necessary and appropriate to the -circumstances. The project team is obligated to maintain confidentiality with -regard to the reporter of an incident. Further details of specific enforcement -policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -Attribution - -This Code of Conduct is adapted from the Contributor Covenant, version 1.4, -available at http://contributor-covenant.org/version/1/4/ diff --git a/guidelines/UnitTests b/guidelines/UnitTests deleted file mode 100644 index d42a63ce5..000000000 --- a/guidelines/UnitTests +++ /dev/null @@ -1,69 +0,0 @@ -How to add unit test -==================== - -Unit test brings some advantages, briefly, we can list some of them (reference -[1](https://en.wikipedia.org/wiki/Unit_testing)): - -* Tests reduce bugs in new features; -* Tests reduce bugs in existing features; -* Tests are good documentation; -* Tests reduce the cost of change; -* Tests allow refactoring; - -With those advantages in mind, it was required to choose a framework which fits -well with C/C++ code. Hence, it was chosen (google test) -[https://github.com/google/googletest], because it is largely used and it is -relatively easy learn. - -Install and configure google test (manually) --------------------------------------------- - -In this section, you will see a brief description of how to install google -test. However, it is strongly recommended that you take a look to the official -repository (https://github.com/google/googletest) and refers to that if you -have any problem to install it. Follow the steps below: - -* Install: cmake and pthread -* Clone google test project from: https://github.com/google/googletest and - enter in the project directory -* Inside project directory, type: - -``` -cmake -DBUILD_SHARED_LIBS=ON . -make -``` - -* After compilation, copy all "*.so" inside directory "googlemock" and - "googlemock/gtest" to "/usr/lib/" -* Done! Now you can compile your tests. - -If you have any problem, go to the official repository to find help. - -Ps.: Some distros already have googletest packed. If your distro supports it, -you can use it instead of compile. - -Create new unit test --------------------- - -If you want to add new unit tests for Yosys, just follow the steps below: - -* Go to directory "yosys/test/unit/" -* In this directory you can find something similar Yosys's directory structure. - To create your unit test file you have to follow this pattern: - fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the - unit test for kernel/celledges.cc, you will need to create a file like this: - tests/unit/kernel/celledgesTest.cc; -* Implement your unit test - -Run unit test -------------- - -To compile and run all unit tests, just go to yosys root directory and type: -``` -make unit-test -``` - -If you want to remove all unit test files, type: -``` -make clean-unit-test -``` diff --git a/guidelines/Windows b/guidelines/Windows deleted file mode 100644 index c4548c37c..000000000 --- a/guidelines/Windows +++ /dev/null @@ -1,83 +0,0 @@ -Creating the Visual Studio Template Project -=========================================== - -1. Create an empty Visual C++ Win32 Console App project - - Microsoft Visual Studio Express 2013 for Windows Desktop - Open New Project Wizard (File -> New Project..) - - Project Name: YosysVS - Solution Name: YosysVS - [X] Create directory for solution - [ ] Add to source control - - [X] Console applications - [X] Empty Project - [ ] SDL checks - -2. Open YosysVS Project Properties - - Select Configuration: All Configurations - - C/C++ -> General -> Additional Include Directories - Add: ..\yosys - - C/C++ -> Preprocessor -> Preprocessor Definitions - Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS - -3. Resulting file system tree: - - YosysVS/ - YosysVS/YosysVS - YosysVS/YosysVS/YosysVS.vcxproj - YosysVS/YosysVS/YosysVS.vcxproj.filters - YosysVS/YosysVS.sdf - YosysVS/YosysVS.sln - YosysVS/YosysVS.v12.suo - -4. Zip YosysVS as YosysVS-Tpl-v1.zip - -Compiling with Visual Studio -============================ - -Visual Studio builds are not directly supported by build scripts, but they are still possible. - -1. Easy way - - - Go to https://github.com/YosysHQ/yosys/actions/workflows/vs.yml?query=branch%3Amain - - Click on the most recent completed run - - In Artifacts region find vcxsrc and click on it to download - - Unpack downloaded ZIP file - - Open YosysVS.sln with Visual Studio - -2. Using WSL or MSYS2 - - - Make sure to have make, python3 and git available - - Git clone yosys repository - - Execute ```make vcxsrc YOSYS_VER=latest``` - - File yosys-win32-vcxsrc-latest.zip will be created - - Transfer that file to location visible by Windows application - - Unpack ZIP - - Open YosysVS.sln with Visual Studio - -Cross-Building for Windows with MXE -=================================== - -Check http://mxe.cc/#requirements and install all missing requirements. - -As root (or other user with write access to /usr/local/src): - - cd /usr/local/src - git clone https://github.com/mxe/mxe.git - cd mxe - - make -j$(nproc) MXE_PLUGIN_DIRS="plugins/tcl.tk" \ - MXE_TARGETS="i686-w64-mingw32.static" \ - gcc tcl readline - -Then as regular user in some directory where you build stuff: - - git clone https://github.com/YosysHQ/yosys.git yosys-win32 - cd yosys-win32 - make config-mxe - make -j$(nproc) mxebin diff --git a/kernel/rtlil.cc b/kernel/rtlil.cc index 087d3ff92..b279cce6e 100644 --- a/kernel/rtlil.cc +++ b/kernel/rtlil.cc @@ -2147,6 +2147,21 @@ namespace { check_expected(); return; } + /* + * Checklist for adding internal cell types + * ======================================== + * Things to do right away: + * - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells) + * - Add to InternalCellChecker::check() in kernel/rtlil.cc + * - Add to techlibs/common/simlib.v + * - Add to techlibs/common/techmap.v + * + * Things to do after finalizing the cell interface: + * - Add support to kernel/satgen.h for the new cell type + * - Add to docs/source/CHAPTER_CellLib.rst (or just add a fixme to the bottom) + * - Maybe add support to the Verilog backend for dumping such cells as expression + * + */ error(__LINE__); } };