From 55da97c9bab2d5239bf655f3635fec7a67064b2c Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 12 Nov 2024 17:41:17 +1300 Subject: [PATCH] Docs: Formatting recent md -> rst converts --- .../extending_yosys/contributing.rst | 26 +- .../extending_yosys/test_suites.rst | 53 ++-- docs/source/yosys_internals/verilog.rst | 272 +++++++++--------- 3 files changed, 181 insertions(+), 170 deletions(-) diff --git a/docs/source/yosys_internals/extending_yosys/contributing.rst b/docs/source/yosys_internals/extending_yosys/contributing.rst index 364067f8efc..e06de61b165 100644 --- a/docs/source/yosys_internals/extending_yosys/contributing.rst +++ b/docs/source/yosys_internals/extending_yosys/contributing.rst @@ -9,19 +9,19 @@ Formatting of code - Yosys code is using tabs for indentation. Tabs are 8 characters. -- A continuation of a statement in the following line is indented by - two additional tabs. +- A continuation of a statement in the following line is indented by two + additional tabs. -- Lines are as long as you want them to be. A good rule of thumb is - to break lines at about column 150. +- Lines are as long as you want them to be. A good rule of thumb is to break + lines at about column 150. -- Opening braces can be put on the same or next line as the statement - opening the block (if, switch, for, while, do). Put the opening brace - on its own line for larger blocks, especially blocks that contains - blank lines. +- Opening braces can be put on the same or next line as the statement opening + the block (if, switch, for, while, do). Put the opening brace on its own line + for larger blocks, especially blocks that contains blank lines. -- Otherwise stick to the Linux Kernel Coding Style: - https://www.kernel.org/doc/Documentation/process/coding-style.rst +- Otherwise stick to the `Linux Kernel Coding Style`_. + +.. _Linux Kernel Coding Style: https://www.kernel.org/doc/Documentation/process/coding-style.rst C++ Language @@ -29,8 +29,8 @@ C++ Language Yosys is written in C++17. -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) +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 :file:`kernel/yosys.h`) Use range-based for loops whenever applicable. diff --git a/docs/source/yosys_internals/extending_yosys/test_suites.rst b/docs/source/yosys_internals/extending_yosys/test_suites.rst index 8a9c4711ef8..264b97ce1db 100644 --- a/docs/source/yosys_internals/extending_yosys/test_suites.rst +++ b/docs/source/yosys_internals/extending_yosys/test_suites.rst @@ -40,30 +40,31 @@ page`_. * 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. + well with C/C++ code. Hence, `google test`_ was chosen, because it is widely + used and it is relatively easy learn. + + .. _google test: https://github.com/google/googletest 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: + 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 + * 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 - ``` + .. code-block:: console + + cmake -DBUILD_SHARED_LIBS=ON . + make - * After compilation, copy all "*.so" inside directory "googlemock" and - "googlemock/gtest" to "/usr/lib/" + * 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. @@ -76,23 +77,25 @@ page`_. If you want to add new unit tests for Yosys, just follow the steps below: - * Go to directory "yosys/test/unit/" + * Go to directory :file:`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; + 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 - ``` + + .. code-block:: console + + make unit-test If you want to remove all unit test files, type: - ``` - make clean-unit-test - ``` + + .. code-block:: console + + make clean-unit-test diff --git a/docs/source/yosys_internals/verilog.rst b/docs/source/yosys_internals/verilog.rst index 1c9031a4fa9..20fd0ac9f4b 100644 --- a/docs/source/yosys_internals/verilog.rst +++ b/docs/source/yosys_internals/verilog.rst @@ -21,64 +21,63 @@ for them: Verilog Attributes and non-standard features -------------------------------------------- -- The ``full_case`` attribute on case statements is supported - (also the non-standard ``// synopsys full_case`` directive) +- 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 ``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 ``// 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 ``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 ``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 ``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 ``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 ``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 ``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 ``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`` +- 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. + ``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 ``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. @@ -94,70 +93,69 @@ Verilog Attributes and non-standard features 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`` +- 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 ``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. + through the synthesis. When entities are combined, a new \|-separated string + is created that contains all the strings 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 ``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). +- 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``. + 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. + 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. + 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_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``. + 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 ``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 ``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_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`. + 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 @@ -174,38 +172,41 @@ Verilog Attributes and non-standard features ``proc_dlatch``. - The cell attribute ``wildcard_port_conns`` represents wildcard port - connections (SystemVerilog ``.*``). These are resolved to concrete - connections to matching wires in ``hierarchy``. + 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 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. +- 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. + 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 +- 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: +.. code-block:: verilog + `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: + 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: + +.. code-block:: verilog module my_add3(A, B, C, Y); parameter WIDTH = 8; @@ -230,24 +231,28 @@ Verilog Attributes and non-standard features - 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. +- 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. -- 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: -- 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: +.. code-block:: verilog module dpitest; import "DPI-C" function foo:round = real my_round (real); parameter real r = my_round(12.345); endmodule +.. code-block:: + $ yosys -p 'plugin -a foo -i /lib/libm.so; read_verilog dpitest.v' - Sized constants (the syntax ``'s?[bodh]``) support constant @@ -256,17 +261,17 @@ Verilog Attributes and non-standard features - 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. + 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.) + 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`` + 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 @@ -274,6 +279,8 @@ Verilog Attributes and non-standard features ``smtlib2_comb_expr`` attribute can be used on output ports to define their value using an SMT-LIB 2 expression. For example: +.. code-block:: verilog + (* blackbox *) (* smtlib2_module *) module submod(a, b); @@ -286,48 +293,49 @@ Non-standard or SystemVerilog features for formal verification -------------------------------------------------------------- - Support for ``assert``, ``assume``, ``restrict``, and ``cover`` is enabled - when ``read_verilog`` is called with ``-formal``. + 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 ``$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.) + 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.) + 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 + 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. +- 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. + ``@(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 +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. + 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. @@ -340,9 +348,9 @@ from SystemVerilog: - 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. +- 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