[Docs]: Adding comments for the usage of Yosys plugins

Signed-off-by: Seyed Alireza Damghani <[email protected]>

Author: sdamghan

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 for performing 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -186,10 +224,6 @@ Detailed Command-line Options
     additional parameters for ODIN II that are provided from within the 
     .xml file.
 
-.. option:: -adder_cin_global
-    
-    Tells ODIN II to connect the first cin in an adder/subtractor chain to a global gnd/vdd net.
-
 .. option:: -use_odin_simulation 
 
     Tells ODIN II to run simulation.
@@ -218,32 +252,32 @@ Detailed Command-line Options
 
 .. option:: -coarsen
 
-    Notifies ODIN II if the input BLIF is coarse-grain
+    Notifies ODIN II if the input BLIF is coarse-grained
 
     **Default:** False
 
 .. option:: -fflegalize
 
-    Makes flip-flops rising edge for coarse-grain input BLIFs in the techmap (ODIN II synthesis flow generates rising edge FFs by default, should be used for Yosys+Odin-II)
+    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
+    Enables ODIN II utilization of operation-type-encoded naming style for Yosys coarse-grained RTLIL nodes
 
     **Default:** False
 
 .. option:: -yosys_script <YOSYS_SCRIPT>
 
-    Supplies Yosys with a .ys script file (similar to Tcl script), including synthesis steps.
+    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 determine the parser based on the input file extension if this argument is not used.
+    The script considers the Yosys conventional Verilog parser if this argument is not used.
 
     **Default:** yosys
 
@@ -252,31 +286,3 @@ Detailed Command-line Options
     The ``-parser`` option is only available for the Yosys standalone front-end.
     On the other hand, the Yosys+Odin-II front-end automatically determine the Yosys HDL parser according to the input file extension.
     If the input HDL type is not supported by the Yosys conventional Verilog front-end (i.e., ``read_verilog -sv``) and the Yosys plugins are not installed, the Yosys+Odin-II flow results in failure.
-
-
-.. code-block:: bash
-
-    ./run_vtr_flow <path/to/Verilog/File> <path/to/arch/file> -elaborator yosys -fflegalize
-    ./run_vtr_flow <path/to/SystemVerilog/File> <path/to/arch/file> -elaborator yosys -fflegalize
-    ./run_vtr_flow <path/to/UHDM/File> <path/to/arch/file> -elaborator yosys -fflegalize
-
-Passes a Verilog/SystemVerilog/UHDM file to Yosys for performing 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
-
-    ./run_vtr_flow <path/to/Verilog/File> <path/to/arch/file> -start yosys
-    ./run_vtr_flow <path/to/SystemVerilog/File> <path/to/arch/file> -start yosys
-
-Running the VTR flow with the default behaviour 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
-
-./run_vtr_flow <path/to/SystemVerilog/File> <path/to/arch/file> -start yosys -parser yosys-plugin
-./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.
-In above cases, 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 frontend. 

doc/src/yosys+odin/quickstart.rst

@@ -82,9 +82,16 @@ It is assumed that they are being performed in the Odin-II directory.
 
 .. code-block:: bash
 
-   ./odin_II --elaborator yosys -v <path/to/Verilog/File>
-   ./odin_II --elaborator yosys -s <path/to/SystemVerilog/File>
-   ./odin_II --elaborator yosys -u <path/to/UHDM/File>
+    # Elaborate the input file using Yosys convetional Verilog parser and then partial map the coarse-grained netlist using Odin-II
+    ./odin_II --elaborator yosys -v <path/to/Verilog/File>
+
+    # Elaborate the input file using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys convetional Verilog parser 
+    # and then partial map the coarse-grained netlist using Odin-II
+    ./odin_II --elaborator yosys -s <path/to/SystemVerilog/File>
+    
+    # Elaborate the input file using the Surelog plugin if installed, otherwise failure on the unsupported type. 
+    # If succeed, then Odin-II performs the partial mapping on the coarse-grained netlist
+    ./odin_II --elaborator yosys -u <path/to/UHDM/File>
 
 
 Passes a Verilog/SystemVerilog/UHDM HDL file to Yosys for elaboration, then Odin-II performs the partial mapping and optimization. 

doc/src/yosys+odin/user_guide.rst

@@ -13,9 +13,9 @@ Synthesis Arguments
              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									   
-     **`-s`**                  **SystemVerilog HDL FIle**        **You may specify multiple SystemVerilog HDL files for synthesis**									   
-     **`-u`**                  **UHDM FIle**                     **You may specify multiple UHDM files for synthesis**									   
+     `-v`                      Verilog HDL File                  You may specify multiple Verilog HDL files for synthesis									   
+     **`-s`**                  **SystemVerilog HDL File**        **You may specify multiple SystemVerilog HDL files for synthesis**									   
+     **`-u`**                  **UHDM File**                     **You may specify multiple UHDM files for synthesis**									   
      `-b`                      BLIF File                                                                               									
      **`-S/--tcl`**            **Tcl Script File**               **You may utilize additional commands for the Yosys elaborator**        						   
      `-o`                      BLIF Output File                  full output path and file name for the BLIF output file                           		
@@ -38,8 +38,13 @@ Additional Examples using Odin-II with the Yosys elaborator
 
 .. code-block:: bash
 
-	./odin_II --elaborator yosys -v <path/to/Verilog/File> --fflegalize
+    # Elaborate the input file using Yosys convetional Verilog parser
+    ./odin_II --elaborator yosys -v <path/to/Verilog/File> --fflegalize
+
+    # Elaborate the input file using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys convetional Verilog parser 
     ./odin_II --elaborator yosys -s <path/to/SystemVerilog/File> --fflegalize
+
+    # Elaborate the input file using the Surelog plugin if installed, otherwise failure on the unsupported type
     ./odin_II --elaborator yosys -u <path/to/UHDM/File> --fflegalize
 
 
@@ -223,9 +228,14 @@ Examples using input/output vector files
 
 .. code-block:: bash
 
-	./odin_II --elaborator yosys -v <Path/to/Verilog/file> -t <Path/to/Input/Vector/File> -T <Path/to/Output/Vector/File>
-	./odin_II --elaborator yosys -s <Path/to/SystemVerilog/file> -t <Path/to/Input/Vector/File> -T <Path/to/Output/Vector/File>
-	./odin_II --elaborator yosys -u <Path/to/UHDM/file> -t <Path/to/Input/Vector/File> -T <Path/to/Output/Vector/File>
+    # Elaborate the input file using Yosys convetional Verilog parser
+    ./odin_II --elaborator yosys -v <Path/to/Verilog/file> -t <Path/to/Input/Vector/File> -T <Path/to/Output/Vector/File>
+
+    # Elaborate the input file using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys convetional Verilog parser 
+    ./odin_II --elaborator yosys -s <Path/to/SystemVerilog/file> -t <Path/to/Input/Vector/File> -T <Path/to/Output/Vector/File>
+    
+    # Elaborate the input file using the Surelog plugin if installed, otherwise failure on the unsupported type
+    ./odin_II --elaborator yosys -u <Path/to/UHDM/file> -t <Path/to/Input/Vector/File> -T <Path/to/Output/Vector/File>
 
 
 A mismatch error will arise if the output vector files do not match with the benchmark output vector, located in the `verilog` directory.

doc/src/yosys/quickstart.rst

@@ -54,4 +54,4 @@ To run the VTR flow with the Yosys front-end, you would need to run the `run_vtr
 
 .. note::
 
-    Please see `Run VTR Flow <https://docs.verilogtorouting.org/en/latest/vtr/run_vtr_flow/>`_ for advanced usage of the Yosys front-end with external plugins.
+    Please see `Run VTR Flow <https://docs.verilogtorouting.org/en/latest/vtr/run_vtr_flow/#advanced-usage>`_ for advanced usage of the Yosys front-end with external plugins.

vtr_flow/scripts/run_vtr_flow.py

@@ -384,8 +384,8 @@ def vtr_command_argparser(prog=None):
         default=None,
         dest="parser",
         help="Specify a parser for the Yosys synthesizer [yosys (Verilog-2005), surelog (UHDM), "
-        + "yosys-plugin (SystemVerilog)].The script determine the parser based on the input file"
-        + " extension if this argument is not used.",
+        + "yosys-plugin (SystemVerilog)]. The script considers the Yosys conventional Verilog"
+        + " parser if this argument is not used.",
     )
     #
     # VPR arguments