Merge pull request #2139 from verilog-to-routing/yosys_plugins_docs

Update Documentation with recent changes for Yosys Plugins

Author: vaughnbetz

doc/src/odin/quickstart.md

@@ -28,24 +28,24 @@ To build you may use the Makefile wrapper in the $VTR_ROOT/ODIN_II ``make build`
 
 ./odin_II [arguments]
 
-*Requires one and only one of `-c`, `-V`, or `-b`
+*Requires one and only one of `-c`, `-v`, or `-b`
 
-| arg  | following argument     | Description                                                        |
+| arg  | following argument     | Description                                                                           |
 |------|---|---|
-| `-c` | XML Configuration File | an XML configuration file dictating the runtime parameters of odin |
-| `-V` | Verilog HDL FIle       | You may specify multiple verilog HDL files                         |
-| `-b` | BLIF File              | You may specify multiple blif files                                |
-| `-o` | BLIF output file    | full output path and file name for the blif output file  |
-| `-a` | architecture file   | You may specify multiple verilog HDL files for synthesis |
-| `-h` |                     | Print help                                               |
+| `-c` | XML Configuration File | an XML configuration file dictating the runtime parameters of odin                    |
+| `-v` | Verilog HDL File       | You may specify multiple space-separated verilog HDL files                            |
+| `-b` | BLIF File              | You may specify multiple space-separated blif files                                   |
+| `-o` | BLIF output file       | full output path and file name for the blif output file                               |
+| `-a` | architecture file      | You may not specify the architecture file, which results in pure soft logic synthesis |
+| `-h` |                        | Print help                                                                            |
 
 ## Example Usage
 
 The following are simple command-line arguments and a description of what they do. 
 It is assumed that they are being performed in the Odin_II directory.
 
 ```bash
-   ./odin_II -V <path/to/verilog/File>
+   ./odin_II -v <path/to/verilog/File>
 ```
 
 Passes a verilog HDL file to Odin II where it is synthesized. 
@@ -58,7 +58,7 @@ Warnings and errors may appear regarding the HDL code.
 Passes a blif file to Odin II where it is synthesized.
 
 ```bash
-   ./odin_II -V <path/to/verilog/File> -a <path/to/arch/file> -o myModel.blif
+   ./odin_II -v <path/to/verilog/File> -a <path/to/arch/file> -o myModel.blif
 ```
 
 Passes a verilog HDL file and and architecture to Odin II where it is synthesized. 

doc/src/odin/user_guide.md

@@ -4,15 +4,15 @@
 
 |  arg  | following argument      | Description                                            |
 |-------|:-----------------------:|------------------------------------------------------- |
-| `-c`  |  XML Configuration File | XML runtime directives for the syntesizer such as the verilog file, and parametrized synthesis |
-|  `-V` |  Verilog HDL FIle       | You may specify multiple verilog HDL files for synthesis|
-|  `-b` |  BLIF File              |                                                        |
-|  `-o` |  BLIF output file       | full output path and file name for the blif output file                              |
-|  `-a` |  architecture file      | You may specify multiple verilog HDL files for synthesis                             |
-|  `-G` |                         | Output netlist graph in GraphViz viewable .dot format. (net.dot, opens with dotty)  |
-|  `-A` |                         | Output AST graph in in GraphViz viewable .dot format.                               |
-|  `-W` |                         | Print all warnings. (Can be substantial.)                                           |
-|  `-h` |                         | Print help                                                                          |
+|  `-c` |  XML Configuration File | XML runtime directives for the syntesizer such as the verilog file, and parametrized synthesis |
+|  `-v` |  Verilog HDL File       | You may specify multiple space-separated verilog HDL files for synthesis                       |
+|  `-b` |  BLIF File              | You may **not** specify multiple BLIF files as only single input BLIF file is accepted         |
+|  `-o` |  BLIF output file       | full output path and file name for the BLIF output file                                        |
+|  `-a` |  architecture file      | You may specify multiple space-separated Verilog HDL files for synthesis                       |
+|  `-G` |                         | Output netlist graph in GraphViz viewable .dot format. (net.dot, opens with dotty)             |
+|  `-A` |                         | Output AST graph in in GraphViz viewable .dot format.                                          |
+|  `-W` |                         | Print all warnings. (Can be substantial.)                                                      |
+|  `-h` |                         | Print help                                                                                     |
 
 ## Simulation Arguments
 
@@ -111,7 +111,7 @@ Simulation always produces the folowing files:
 > a distinct shared object file for each instance of the block you wish
 > to simulate. The method signature the simulator expects contains only
 > int and int[] parameters, leaving the code provided to simulate the
-> hard blokc agnostic of the internal Odin II data structures. However,
+> hard block agnostic of the internal Odin II data structures. However,
 > a cycle parameter is included to provide researchers with the ability
 > to delay results of operations performed by the simulation code.
 >
@@ -158,15 +158,15 @@ A very useful function of Odin II is to compare the simulated output vector file
 To do this the command line should be:
 
 ```shell
-./odin_II -V <Path/to/verilog/file> -t <Path/to/Input/Vector/File> -T <Path/to/Output/Vector/File>
+./odin_II -v <Path/to/verilog/file> -t <Path/to/Input/Vector/File> -T <Path/to/Output/Vector/File>
 ```
 
 An error will arrise if the output vector files do not match.
 
 Without an expected vector output file the command line would be:
 
 ```shell
-./odin_II -V <Path/to/verilog/file> -t <Path/to/Input/Vector/File>
+./odin_II -v <Path/to/verilog/file> -t <Path/to/Input/Vector/File>
 ```
 
 The generated output file can be found in the current directory under the name output_vectors.
@@ -176,7 +176,7 @@ The generated output file can be found in the current directory under the name o
 This function generates N amounnt of random input vectors for Odin II to simulate with.
 
 ```shell
-./odin_II -V <Path/to/verilog/file> -g 10
+./odin_II -v <Path/to/verilog/file> -g 10
 ```
 
 This example will produce 10 autogenerated input vectors. These vectors can be found in the current directory under input_vectors  and the resulting output vectors can be found under output_vectors.

doc/src/vtr/run_vtr_flow.rst

@@ -60,6 +60,44 @@ For example::
 will run the VTR flow to map the circuit ``my_circuit.v`` onto the architecture ``my_arch.xml``; the arguments ``--pack`` and ``--place`` will be passed to VPR (since they are unrecognized arguments to ``run_vtr_flow.py``).
 They will cause VPR to perform only :ref:`packing and placement <general_options>`.
 
+.. code-block:: bash
+
+    # Using the Yosys conventional Verilog parser
+    ./run_vtr_flow <path/to/Verilog/File> <path/to/arch/file> -elaborator yosys -fflegalize
+
+    # Using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys conventional Verilog parser
+    ./run_vtr_flow <path/to/SystemVerilog/File> <path/to/arch/file> -elaborator yosys -fflegalize
+    
+    # Using the Surelog plugin if installed, otherwise failure on the unsupported file type
+    ./run_vtr_flow <path/to/UHDM/File> <path/to/arch/file> -elaborator yosys -fflegalize
+
+Passes a Verilog/SystemVerilog/UHDM file to Yosys to perform elaboration. 
+The BLIF elaboration and partial mapping phases will be executed on the generated netlist by Odin-II, and all latches in the Yosys+Odin-II output file will be rising edge.
+Then ABC and VPR perform the default behaviour for the VTR flow, respectively.
+
+.. code-block:: bash
+
+    # Using the Yosys conventional Verilog parser
+    ./run_vtr_flow <path/to/Verilog/File> <path/to/arch/file> -start yosys
+
+    # Using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys conventional Verilog parser
+    ./run_vtr_flow <path/to/SystemVerilog/File> <path/to/arch/file> -start yosys
+
+Running the VTR flow with the default configuration using the Yosys standalone front-end.
+The parser for these runs is considered the Yosys conventional Verilog/SystemVerilog parser (i.e., ``read_verilog -sv``), as the parser is not explicitly specified.
+
+.. code-block:: bash
+
+    # Using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys conventional Verilog parser
+    ./run_vtr_flow <path/to/SystemVerilog/File> <path/to/arch/file> -start yosys -parser yosys-plugin
+
+    # Using the Surelog plugin if installed, otherwise failure on the unsupported file type
+    ./run_vtr_flow <path/to/UHDM/File> <path/to/arch/file> -start yosys -parser surelog
+
+Running the default VTR flow using the Yosys standalone front-end.
+The Yosys HDL parser is considered as Yosys-SystemVerilog plugin (i.e., ``read_systemverilog``) and Yosys UHDM plugin (i.e., ``read_uhdm``), respectively.
+It is worth mentioning that utilizing Yosys plugins requires passing the ``-DYOSYS_SV_UHDM_PLUGIN=ON`` compile flag to build and install the plugins for the Yosys front-end. 
+
 Detailed Command-line Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -72,6 +110,7 @@ Detailed Command-line Options
     Accepted values:
 
       * ``odin``
+      * ``yosys``
       * ``abc``
       * ``scripts``
       * ``vpr``
@@ -86,6 +125,7 @@ Detailed Command-line Options
     Accepted values:
 
       * ``odin``
+      * ``yosys``
       * ``abc``
       * ``scripts``
       * ``vpr``
@@ -183,3 +223,93 @@ Detailed Command-line Options
     scenarios. This option is needed for running the entire VTR flow with 
     additional parameters for ODIN II that are provided from within the 
     .xml file.
+
+.. option:: -use_odin_simulation 
+    
+    Tells ODIN II to run simulation.
+
+.. option:: -min_hard_mult_size <min_hard_mult_size>
+    
+    Tells ODIN II the minimum multiplier size (in bits) to be implemented using hard multiplier.
+    
+    **Default:** 3
+
+.. option:: -min_hard_adder_size <MIN_HARD_ADDER_SIZE>
+    
+    Tells ODIN II the minimum adder size (in bits) that should be implemented using hard adder.
+    
+    **Default:** 1
+
+.. option:: -elaborator <ELABORATOR>
+    
+    Specifies the elaborator of the synthesis flow for ODIN II [odin, yosys]
+
+    **Default:** odin
+
+.. option:: -top_module <TOP_MODULE>
+    
+    Specifies the name of the module in the design that should be considered as top
+
+.. option:: -coarsen
+    
+    Notifies ODIN II if the input BLIF is coarse-grained.
+
+    **Default:** False
+
+.. note::
+
+    A coarse-grained BLIF file is defined as a BLIF file inclduing unmapped cells with the Yosys internal cell (listed `here <https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/b913727959e22ae7a535ac8b907d0aaa9a3eda3d/ODIN_II/SRC/enum_str.cpp#L402-L494>`_) format which are represented by the ``.subckt`` tag in coarse-grained BLIF.
+    
+.. option:: -fflegalize
+    
+    Makes flip-flops rising edge for coarse-grained input BLIFs in the partial technology mapping phase (ODIN II synthesis flow generates rising edge FFs by default, should be used for Yosys+Odin-II)
+    
+    **Default:** False
+
+.. option:: -encode_names
+    
+    Enables ODIN II utilization of operation-type-encoded naming style for Yosys coarse-grained RTLIL nodes.
+    
+    .. code-block::
+
+        # example of a DFF subcircuit in the Yosys coarse-grained BLIF
+        .subckt $dff CLK=clk D=a Q=inst1.inst2.temp
+        .param CLK_POLARITY 1
+
+        .names inst1.inst2.temp o
+        1 1
+
+        # fine-grained BLIF file with enabled encode_names option for Odin-II partial mapper
+        .latch test^a test^inst1.inst2.temp^FF~0 re test^clk 3
+
+        .names test^inst1.inst2.temp^FF~0 test^o
+        1 1
+
+        # fine-grained BLIF file with disabled encode_names option for Odin-II partial mapper
+        .latch test^a test^$dff^FF~0 re test^clk 3
+
+        .names test^$dff^FF~0 test^o
+        1 1
+
+    **Default:** False
+
+.. option:: -yosys_script <YOSYS_SCRIPT>
+    
+    Supplies Yosys with a .ys script file (similar to Tcl script), including the synthesis steps.
+    
+    **Default:** None
+
+.. option:: -parser <PARSER>
+
+    Specify a parser for the Yosys synthesizer [yosys (Verilog-2005), surelog (UHDM), yosys-plugin (SystemVerilog)].
+    The script uses the Yosys conventional Verilog parser if this argument is not used.
+    
+    **Default:** yosys
+
+.. note::
+
+    Universal Hardware Data Model (UHDM) is a complete modeling of the IEEE SystemVerilog Object Model with VPI Interface, Elaborator, Serialization, Visitor and Listener.
+    UHDM is used as a compiled interchange format in between SystemVerilog tools.
+    The ``yosys-plugins`` parser, which represents the ``read_systemverilog`` command, reads SystemVerilog files directly in Yosys.
+    It executes Surelog with provided filenames and converts them (in memory) into UHDM file. Then, this UHDM file is converted into Yosys AST. `[Yosys-SystemVerilog] <https://github.com/antmicro/yosys-systemverilog#usage>`_
+    On the other hand, the ``surelog`` parser, which uses the ``read_uhdm`` Yosys command, walks the design tree and converts its nodes into Yosys AST nodes using Surelog. `[UHDM-Yosys <https://github.com/chipsalliance/UHDM-integration-tests#uhdm-yosys>`_, `Surelog] <https://github.com/chipsalliance/Surelog#surelog>`_