Update Documentation with recent changes for Yosys Plugins

doc/src/odin/quickstart.md

@@ -28,12 +28,12 @@ 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                                                        |
 |------|---|---|
 | `-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                         |
+| `-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 |
@@ -45,7 +45,7 @@ The following are simple command-line arguments and a description of what they d
 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

@@ -5,7 +5,7 @@
 |  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|
+|  `-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                             |
@@ -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 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -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,66 @@ 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 to be implemented using hard multiplier.
+
+    **Default:** 3
+
+.. option:: -min_hard_adder_size <MIN_HARD_ADDER_SIZE>
+
+    Tells ODIN II the minimum adder size 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
+
+.. 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
+
+    **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 considers the Yosys conventional Verilog parser if this argument is not used.
+
+    **Default:** yosys
+
+.. note::
+
+    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.

doc/src/yosys+odin/dev_guide/contributing.rst

@@ -28,60 +28,82 @@ The flow is depicted in the figure below.
 
 .. code-block:: tcl
 
-	# FILE: $VTR_ROOT/ODIN_II/regression_test/tools/synth.tcl #
-	yosys -import
-
-	# the environment variable VTR_ROOT is set by Odin-II.
-	# Feel free to specify file paths using "$env(VTR_ROOT)/ ..." 
-
-	# Read the hardware decription Verilog
-	read_verilog -nomem2reg -nolatches PATH_TO_VERILOG_FILE.v;
-	# Check that cells match libraries and find top module
-	hierarchy -check -auto-top;
-
-	# Make name convention more readable
-	autoname;
-	# Translate processes to netlist components such as MUXs, FFs and latches
-	procs; opt;
-	# Extraction and optimization of finite state machines
-	fsm; opt;
-	# Collects memories, their port and create multiport memory cells
-	memory_collect; memory_dff; opt;
-
-	# Looking for combinatorial loops, wires with multiple drivers and used wires without any driver.
-	check;
-	# resolve asynchronous dffs
-	techmap -map $VTR_ROOT/ODIN_II/techlib/adff2dff.v;
-	techmap -map $VTR_ROOT/ODIN_II/techlib/adffe2dff.v;
+    # FILE: $VTR_ROOT/ODIN_II/regression_test/tools/synth.tcl #
+    yosys -import
+
+    # the environment variable VTR_ROOT is set by Odin-II.
+    # Feel free to specify file paths using "$env(VTR_ROOT)/ ..." 
+    # Read VTR baseline library first
+    read_verilog -nomem2reg $env(ODIN_TECHLIB)/../../vtr_flow/primitives.v
+    setattr -mod -set keep_hierarchy 1 single_port_ram
+    setattr -mod -set keep_hierarchy 1 dual_port_ram
+
+    # Read the HDL file with pre-defined parer in the "run_yosys.sh" script
+    if {$env(PARSER) == "surelog" } {
+    	puts "Using Yosys read_uhdm command"
+    	plugin -i systemverilog;
+    	yosys -import
+    	read_uhdm -debug $env(TCL_CIRCUIT);
+    } elseif {$env(PARSER) == "yosys-plugin" } {
+    	puts "Using Yosys read_systemverilog command"
+    	plugin -i systemverilog;
+    	yosys -import
+    	read_systemverilog -debug $env(TCL_CIRCUIT)
+    } elseif {$env(PARSER) == "yosys" } {
+    	puts "Using Yosys read_verilog command"
+    	read_verilog -sv -nomem2reg -nolatches $env(TCL_CIRCUIT);
+    } else {
+    	error "Invalid PARSER"
+    }
+
+    # Read the hardware decription Verilog
+    read_verilog -nomem2reg -nolatches PATH_TO_VERILOG_FILE.v;
+    # Check that cells match libraries and find top module
+    hierarchy -check -auto-top;
+
+    # Make name convention more readable
+    autoname;
+    # Translate processes to netlist components such as MUXs, FFs and latches
+    procs; opt;
+    # Extraction and optimization of finite state machines
+    fsm; opt;
+    # Collects memories, their port and create multiport memory cells
+    memory_collect; memory_dff; opt;
+
+    # Looking for combinatorial loops, wires with multiple drivers and used wires without any driver.
+    check;
+    # resolve asynchronous dffs
+    techmap -map $VTR_ROOT/ODIN_II/techlib/adff2dff.v;
+    techmap -map $VTR_ROOT/ODIN_II/techlib/adffe2dff.v;
     # To resolve Yosys internal indexed part-select circuitry
-    techmap */t:$shift */t:$shiftx;
-
-	## Utilizing the "memory_bram" command and the Verilog design provided at "$VTR_ROOT/ODIN_II/techlib/mem_map.v"
-	## we could map Yosys memory blocks to BRAMs and ROMs before the Odin-II partial mapping phase.
-	## However, Yosys complains about expression widths more than 24 bits.
-	## E.g. reg [63:0] memory [18:0] ==> ERROR: Expression width 33554432 exceeds implementation limit of 16777216!
-	## Although we provided the required design files for this process (located in ODIN_II/techlib), we will handle
-	## memory blocks in the Odin-II BLIF elaborator and partial mapper. 
-	# memory_bram -rules $VTR_ROOT/ODIN_II/techlib/mem_rules.txt
-	# techmap -map $VTR_ROOT/ODIN_II/techlib/mem_map.v; 
-
-	# Transform the design into a new one with single top module
-	flatten;
-	# Transforms pmux into trees of regular multiplexers
-	pmuxtree;
+    techmap */t:\$shift */t:\$shiftx;
+    
+    ## Utilizing the "memory_bram" command and the Verilog design provided at "$VTR_ROOT/ODIN_II/techlib/mem_map.v"
+    ## we could map Yosys memory blocks to BRAMs and ROMs before the Odin-II partial mapping phase.
+    ## However, Yosys complains about expression widths more than 24 bits.
+    ## E.g. reg [63:0] memory [18:0] ==> ERROR: Expression width 33554432 exceeds implementation limit of 16777216!
+    ## Although we provided the required design files for this process (located in ODIN_II/techlib), we will handle
+    ## memory blocks in the Odin-II BLIF elaborator and partial mapper. 
+    # memory_bram -rules $VTR_ROOT/ODIN_II/techlib/mem_rules.txt
+    # techmap -map $VTR_ROOT/ODIN_II/techlib/mem_map.v; 
+    
+    # Transform the design into a new one with single top module
+    flatten;
+    # Transforms pmux into trees of regular multiplexers
+    pmuxtree;
     # To possibly reduce words size
     wreduce;
-	# "undirven" to ensure there is no wire without drive
+    # "undirven" to ensure there is no wire without drive
     # "opt_muxtree" removes dead branches, "opt_expr" performs constant folding,
     # removes "undef" inputs from mux cells, and replaces muxes with buffers and inverters.
     # "-noff" a potential option to remove all sdff and etc. Only dff will remain
-	opt -undriven -full; opt_muxtree; opt_expr -mux_undef -mux_bool -fine;;;
-	# Make name convention more readable
-	autoname;
-	# Print statistics
-	stat;
-	# Output BLIF
-	write_blif -param -impltf TCL_BLIF;
+    opt -undriven -full; opt_muxtree; opt_expr -mux_undef -mux_bool -fine;;;
+    # Make name convention more readable
+    autoname;
+    # Print statistics
+    stat;
+    # Output BLIF
+    write_blif -param -impltf TCL_BLIF;
 
 **Algorithm 1** - The Yosys+Odin-II Tcl Script File
 
@@ -94,7 +116,7 @@ As shown in Algorithm 1, the Tcl script, including the step-by-step generic coar
 Utilizing these commands for the Yosys API inside the Odin-II codebase, the Yosys synthesizer performs the elaboration of the input digital design.
 The generic coarse-grained synthesis commands includes: 
 
-1. Parsing the hardware description Verilog files. The option ``-nomem2reg`` prevents Yosys from exploding implicit memories to an array of registers. The option ``-nolatches`` is used for both VTR primitives and input circuit design to avoid Yosys generating logic loops.
+1. Parsing the hardware description Verilog/SystemVerilog/UHDM files. The option ``-nomem2reg`` prevents Yosys from exploding implicit memories to an array of registers. The option ``-nolatches`` is used for both VTR primitives and input circuit design to avoid Yosys generating logic loops.
 2. Checking that the design cells match the libraries and detecting the top module using ``hierarchy``.
 3. Translating the processes to netlist components such as multiplexers, flip-flops, and latches, by the ``procs`` command.
 4. Performing extraction and optimization of finite state machines by the ``fsm`` command.