diff --git a/doc/src/odin/quickstart.md b/doc/src/odin/quickstart.md index 93f56439cd7..c70acc8302b 100644 --- a/doc/src/odin/quickstart.md +++ b/doc/src/odin/quickstart.md @@ -28,16 +28,16 @@ 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 @@ -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 + ./odin_II -v ``` 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 -a -o myModel.blif + ./odin_II -v -a -o myModel.blif ``` Passes a verilog HDL file and and architecture to Odin II where it is synthesized. diff --git a/doc/src/odin/user_guide.md b/doc/src/odin/user_guide.md index 6c12575bfa0..daacc481f28 100644 --- a/doc/src/odin/user_guide.md +++ b/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,7 +158,7 @@ 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 -t -T +./odin_II -v -t -T ``` An error will arrise if the output vector files do not match. @@ -166,7 +166,7 @@ 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 -t +./odin_II -v -t ``` 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 -g 10 +./odin_II -v -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. diff --git a/doc/src/vtr/run_vtr_flow.rst b/doc/src/vtr/run_vtr_flow.rst index 24eff4020d5..a4b1d9ce8dd 100644 --- a/doc/src/vtr/run_vtr_flow.rst +++ b/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 `. +.. code-block:: bash + + # Using the Yosys conventional Verilog parser + ./run_vtr_flow -elaborator yosys -fflegalize + + # Using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys conventional Verilog parser + ./run_vtr_flow -elaborator yosys -fflegalize + + # Using the Surelog plugin if installed, otherwise failure on the unsupported file type + ./run_vtr_flow -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 -start yosys + + # Using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys conventional Verilog parser + ./run_vtr_flow -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 -start yosys -parser yosys-plugin + + # Using the Surelog plugin if installed, otherwise failure on the unsupported file type + ./run_vtr_flow -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 + + Tells ODIN II the minimum multiplier size (in bits) to be implemented using hard multiplier. + + **Default:** 3 + +.. option:: -min_hard_adder_size + + Tells ODIN II the minimum adder size (in bits) that should be implemented using hard adder. + + **Default:** 1 + +.. option:: -elaborator + + Specifies the elaborator of the synthesis flow for ODIN II [odin, yosys] + + **Default:** odin + +.. option:: -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 `_) 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 + + Supplies Yosys with a .ys script file (similar to Tcl script), including the synthesis steps. + + **Default:** None + +.. option:: -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] `_ + 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 `_, `Surelog] `_ \ No newline at end of file diff --git a/doc/src/yosys+odin/dev_guide/contributing.rst b/doc/src/yosys+odin/dev_guide/contributing.rst index cc0db069af0..4b392523e8b 100644 --- a/doc/src/yosys+odin/dev_guide/contributing.rst +++ b/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. diff --git a/doc/src/yosys+odin/quickstart.rst b/doc/src/yosys+odin/quickstart.rst index 55efe133d5f..084831c1213 100644 --- a/doc/src/yosys+odin/quickstart.rst +++ b/doc/src/yosys+odin/quickstart.rst @@ -34,7 +34,12 @@ To ease this process, you can build Yosys+Odin-II with Odin-II in debug mode usi The second approach to build the VTR flow with the Yosys+Odin-II front-end is to use the main VTR Makefile. i.e., calling ``make`` in the `$VTR_ROOT` directory. In this approach, the compile flag ``-DODIN_USE_YOSYS=ON`` should be passed to the CMake parameters as follows: ``make CMAKE_PARAMS="-DODIN_USE_YOSYS=ON"``. - + +.. note:: + + Compiling the VTR flow with the ``-DYOSYS_SV_UHDM_PLUGIN=ON`` flag is required to build and install Yosys SystemVerilog and UHDM plugins. + Using this compile flag, the `Yosys-F4PGA-Plugins `_ and `Surelog `_ repositories are cloned in the ``$VTR_ROOT/libs/EXTERNAL`` directory and then will be compiled and added as external plugins to the Yosys front-end. + .. note:: Yosys uses Makefile as its build system. Since CMake provides portable, cross-platform build systems with many useful features, we provide a CMake wrapper to successfully embeds the Yosys library into the VTR flow. @@ -51,20 +56,22 @@ Basic Usage ./odin_II --elaborator yosys [arguments] -*Requires one and only one of `-c`, `-V` or `-b`* +*Requires one and only one of `-c`, `-v`, `-s`, `-u` or `-b`* .. table:: - ==== ========================== ======================================================================= + ==== ========================== =================================================================================================== 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 + `-v` Verilog HDL File You may specify multiple space-separated Verilog HDL files + `-s` System Verilog HDL File You may specify multiple space-separated System Verilog files + `-u` UHDM File You may specify multiple space-separated UHDM files (require compiling with the ``-DYOSYS_SV_UHDM_PLUGIN=ON`` flag) + `-b` BLIF File You may specify multiple space-separated BLIF files (require compiling with the ``-DYOSYS_SV_UHDM_PLUGIN=ON`` flag) + `-o` BLIF Output File full output path and file name for the BLIF output file + `-a` Architecture File VPR XML architecture file. You may not specify the architecture file, which results in pure soft logic synthesis `-h` Print help - ==== ========================== ======================================================================= + ==== ========================== =================================================================================================== Example Usage @@ -73,38 +80,46 @@ 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. +The following commands pass a Verilog/SystemVerilog/UHDM HDL file to Yosys for elaboration, then Odin-II performs the partial mapping and optimization into pure soft logic. +Warnings and errors may appear regarding the HDL code by Yosys. + .. code-block:: bash - ./odin_II --elaborator yosys -V + # Elaborate the input file using Yosys conventional Verilog parser and then partial map the coarse-grained netlist using Odin-II + ./odin_II --elaborator yosys -v + # Elaborate the input file using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys conventional Verilog parser + # and then partial map the coarse-grained netlist using Odin-II + ./odin_II --elaborator yosys -s + + # 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 -Passes a Verilog HDL file to Yosys for elaboration, then Odin-II performs the partial mapping and optimization. -Warnings and errors may appear regarding the HDL code by Yosys. .. note:: The entire log file of the Yosys elaboration for each run is outputted into a file called ``elaboration.yosys.log`` located in the same directory of the final output BLIF file. -.. code-block:: bash - - ./odin_II --elaborator yosys -V -a -o output.blif - -Passes a Verilog HDL file and architecture to Yosys+Odin-II, where it is synthesized. +The following command passes a Verilog HDL file and architecture to Yosys+Odin-II, where it is synthesized. Yosys will use the HDL files to perform elaboration. Then, Odin-II will use the architecture to do partial technology mapping, and will output the BLIF in the current directory at ``./output.blif``. If the output BLIF file is not specified, ``default_out.blif`` is considered the output file name, again located in the current directory. +.. code-block:: bash + + ./odin_II --elaborator yosys -v -a -o output.blif + .. note:: Once the elaboration is fully executed, Yosys generates a coarse-grained BLIF file that the Odin-II BLIF reader will read to create a netlist. This file is named ``coarsen_netlist.yosys.blif`` located in the current directory. +The following command passes a Tcl script file, including commands for the elaboration by Yosys, along with the architecture file. .. code-block:: bash ./odin_II -S -a -o myModel.blif -Passes a Tcl script file, including commands for the elaboration by Yosys, along with the architecture file. - .. note:: The Tcl script file should follow the same generic synthesis flow, brought as an example in the `$VTR_ROOT/ODIN_II/regression_test/tools/synth.tcl`. diff --git a/doc/src/yosys+odin/user_guide.rst b/doc/src/yosys+odin/user_guide.rst index de65c2ede8a..08f901f4fc3 100644 --- a/doc/src/yosys+odin/user_guide.rst +++ b/doc/src/yosys+odin/user_guide.rst @@ -9,15 +9,17 @@ Synthesis Arguments .. table:: - ======================= ============================== ================================================================================================= + ======================= ============================== ===================================================================================================================================================================== 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 + `-v` Verilog HDL File You may specify multiple space-separated Verilog HDL files for synthesis + **`-s`** **SystemVerilog HDL File** **You may specify multiple space-separated SystemVerilog HDL files for synthesis** + **`-u`** **UHDM File** **You may specify multiple space-separated UHDM files for synthesis** + `-b` BLIF File You may **not** specify multiple BLIF files as only single input BLIF file is accepted **`-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 - `-a` Architecture File You may specify multiple verilog HDL files for synthesis + `-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.) @@ -26,9 +28,8 @@ Synthesis Arguments **`--elaborator`** **[odin (default), yosys]** **Specify the tool that should perform the HDL elaboration** **`--fflegalize`** **Converts latches' sensitivity to the rising edge as required by VPR** **`--show_yosys_log`** **Showing the Yosys elaboration logs in the console window** - **`--decode_names`** **Enable extracting hierarchical information from Yosys coarse-grained BLIF file for signal naming \ - (the VTR flow scripts take advantage of this option by default)** - ======================= ============================== ================================================================================================= + **`--decode_names`** **Enable extracting hierarchical information from Yosys coarse-grained BLIF file for signal naming (the VTR flow scripts take advantage of this option by default)** + ======================= ============================== ===================================================================================================================================================================== @@ -37,16 +38,23 @@ Additional Examples using Odin-II with the Yosys elaborator .. code-block:: bash - ./odin_II --elaborator yosys -V --fflegalize + # Elaborate the input file using Yosys conventional Verilog parser + ./odin_II --elaborator yosys -v --fflegalize + # Elaborate the input file using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys conventional Verilog parser + ./odin_II --elaborator yosys -s --fflegalize -Passes a Verilog file to Yosys for performing elaboration. + # Elaborate the input file using the Surelog plugin if installed, otherwise failure on the unsupported type + ./odin_II --elaborator yosys -u --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. However, all latches in the Yosys+Odin-II output file will be rising edge. .. code-block:: bash - ./odin_II --elaborator yosys -V --decode_names + ./odin_II --elaborator yosys -v --decode_names Performs the design elaboration by Yosys parsers and generates a coarse-grained netlist in BLIF. @@ -77,60 +85,82 @@ Example of Tcl script for Yosys+Odin-II .. 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. - - # 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. + + # 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 + # "undriven" 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; .. note:: @@ -151,8 +181,8 @@ Example of .xml configuration file for `-c` - - + + Verilog PATH_TO_CIRCUIT.v @@ -198,7 +228,14 @@ Examples using input/output vector files .. code-block:: bash - ./odin_II --elaborator yosys -V -t -T + # Elaborate the input file using Yosys conventional Verilog parser + ./odin_II --elaborator yosys -v -t -T + + # Elaborate the input file using the Yosys-SystemVerilog plugin if installed, otherwise the Yosys conventional Verilog parser + ./odin_II --elaborator yosys -s -t -T + + # Elaborate the input file using the Surelog plugin if installed, otherwise failure on the unsupported type + ./odin_II --elaborator yosys -u -t -T A mismatch error will arise if the output vector files do not match with the benchmark output vector, located in the `verilog` directory. diff --git a/doc/src/yosys/dev_guide.rst b/doc/src/yosys/dev_guide.rst index bbbb061083c..09760ff018c 100644 --- a/doc/src/yosys/dev_guide.rst +++ b/doc/src/yosys/dev_guide.rst @@ -71,89 +71,114 @@ For instance, the HDL instantiation of the ``multiply_fp_clk`` complex block def Yosys Synthesis Script File --------------------------- -.. code-block:: tcl - - # XXX (input circuit) is replaced with filename by the run_vtr_flow script - read_verilog -nolatches XXX - - # These commands follow the generic `synth` - # command script inside Yosys - # The -libdir argument allows Yosys to search the current - # directory for any definitions to modules it doesn't know - # about, such as hand-instantiated (not inferred) memories - hierarchy -check -auto-top -libdir . - proc - - # Check that there are no combinational loops - scc -select - select -assert-none % - select -clear - - - opt_expr - opt_clean - check - opt -nodffe -nosdff - fsm - opt - wreduce - peepopt - opt_clean - share - opt - memory -nomap - opt -full - - # Transform all async FFs into synchronous ones - techmap -map +/adff2dff.v - techmap -map TTT/../../../ODIN_II/techlib/adffe2dff.v - - # Map multipliers, DSPs, and add/subtracts according to yosys_models.v - techmap -map YYY */t:$mul */t:$mem */t:$sub */t:$add - opt -fast -full - - memory_map - # Taking care to remove any undefined muxes that - # are introduced to promote resource sharing - opt -full - - # Then techmap all other `complex` blocks into basic - # (lookup table) logic - techmap - opt -fast - - # We read the definitions for all the VTR primitives - # as blackboxes - read_verilog -lib TTT/adder.v - read_verilog -lib TTT/multiply.v - read_verilog -lib SSS #(SSS) will be replaced by single_port_ram.v by python script - read_verilog -lib DDD #(DDD) will be replaced by dual_port_ram.v by python script - - # Rename singlePortRam to single_port_ram - # Rename dualPortRam to dualZ_port_ram - # rename function of Yosys not work here - # since it may outcome hierarchy error - read_verilog SSR #(SSR) will be replaced by spram_rename.v by python script - read_verilog DDR #(DDR) will be replaced by dpram_rename.v by python script - - # Flatten the netlist - flatten - # Turn all DFFs into simple latches - dffunmap - opt -fast -noff - - # Lastly, check the hierarchy for any unknown modules, - # and purge all modules (including blackboxes) that - # aren't used - hierarchy -check -purge_lib - tee -o /dev/stdout stat - - autoname - - # Then write it out as a blif file, remembering to call - # the internal `$true`/`$false` signals vcc/gnd, but - # switch `-impltf` doesn't output them - # ZZZ will be replaced by run_vtr_flow.pl - write_blif -true + vcc -false + gnd -undef + unconn -blackbox ZZZ - +.. code-block:: Tcl + + yosys -import + + # Read the HDL file with pre-defined parser in the run_vtr_flow script + # XXX (input circuit) is replaced with filename by the run_vtr_flow script + if {$env(PARSER) == "surelog" } { + puts "Using Yosys read_uhdm command" + plugin -i systemverilog + yosys -import + read_uhdm -debug XXX + } elseif {$env(PARSER) == "yosys-plugin" } { + puts "Using Yosys read_systemverilog command" + plugin -i systemverilog + yosys -import + read_systemverilog -debug XXX + } elseif {$env(PARSER) == "yosys" } { + puts "Using Yosys read_verilog command" + read_verilog -sv -nolatches XXX + } else { + error "Invalid PARSER" + } + + # read the custom complex blocks in the architecture + read_verilog -lib CCC + + # These commands follow the generic `synth' + # command script inside Yosys + # The -libdir argument allows Yosys to search the current + # directory for any definitions to modules it doesn't know + # about, such as hand-instantiated (not inferred) memories + hierarchy -check -auto-top -libdir . + procs + + # Check that there are no combinational loops + scc -select + select -assert-none % + select -clear + + + opt_expr + opt_clean + check + opt -nodffe -nosdff + fsm + opt + wreduce + peepopt + opt_clean + share + opt + memory -nomap + opt -full + + # Transform all async FFs into synchronous ones + techmap -map +/adff2dff.v + techmap -map TTT/../../../ODIN_II/techlib/adffe2dff.v + + # Map multipliers, DSPs, and add/subtracts according to yosys_models.v + techmap -map YYY */t:\$mul */t:\$mem */t:\$sub */t:\$add + opt -fast -full + + memory_map + # Taking care to remove any undefined muxes that + # are introduced to promote resource sharing + opt -full + + # Then techmap all other `complex' blocks into basic + # (lookup table) logic + techmap + opt -fast + + # read the definitions for all the VTR primitives + # as blackboxes + read_verilog -lib TTT/adder.v + read_verilog -lib TTT/multiply.v + #(SSS) will be replaced by single_port_ram.v by python script + read_verilog -lib SSS + #(DDD) will be replaced by dual_port_ram.v by python script + read_verilog -lib DDD + + # Rename singlePortRam to single_port_ram + # Rename dualPortRam to dual_port_ram + # rename function of Yosys not work here + # since it may outcome hierarchy error + #(SSR) will be replaced by spram_rename.v by python script + read_verilog SSR + #(DDR) will be replaced by dpram_rename.v by python script + read_verilog DDR + + # Flatten the netlist + flatten + # Turn all DFFs into simple latches + dffunmap + opt -fast -noff + + # Lastly, check the hierarchy for any unknown modules, + # and purge all modules (including blackboxes) that + # aren't used + hierarchy -check -purge_lib + tee -o /dev/stdout stat + + autoname + + # Then write it out as a blif file, remembering to call + # the internal `$true'/`$false' signals vcc/gnd, but + # switch `-impltf' doesn't output them + # ZZZ will be replaced by run_vtr_flow.pl + write_blif -true + vcc -false + gnd -undef + unconn -blackbox ZZZ + **Algorithm 2** - The Yosys Tcl Script File \ No newline at end of file diff --git a/doc/src/yosys/quickstart.rst b/doc/src/yosys/quickstart.rst index bb23756ad37..022b591f15b 100644 --- a/doc/src/yosys/quickstart.rst +++ b/doc/src/yosys/quickstart.rst @@ -30,7 +30,13 @@ Building -------- To build the VTR flow with the Yosys front-end you may use the VTR Makefile wrapper, by calling the ``make CMAKE_PARAMS="-DWITH_YOSYS=ON"`` command in the `$VTR_ROOT` directory. -The compile flag ``-DWITH_YOSYS=ON`` should be passed to the CMake parameters to enable Yosys compilation process. +The compile flag ``-DWITH_YOSYS=ON`` should be passed to the CMake parameters to enable the Yosys compilation process. + +.. note:: + + Compiling the VTR flow with the ``-DYOSYS_SV_UHDM_PLUGIN=ON`` flag is required to build and install Yosys SystemVerilog and UHDM plugins. + Using this compile flag, the `Yosys-F4PGA-Plugins `_ and `Surelog `_ repositories are cloned in the ``$VTR_ROOT/libs/EXTERNAL`` directory and then will be compiled and added as external plugins to the Yosys front-end. + .. note:: @@ -44,4 +50,8 @@ To run the VTR flow with the Yosys front-end, you would need to run the `run_vtr .. code-block:: bash - ./run_vtr_flow `PATH_TO_VERILOG_FILE.v` `PATH_TO_ARCH_FILE.xml` -start yosys \ No newline at end of file + ./run_vtr_flow `PATH_TO_VERILOG_FILE.v` `PATH_TO_ARCH_FILE.xml` -start yosys + +.. note:: + + Please see `Run VTR Flow `_ for advanced usage of the Yosys front-end with external plugins. diff --git a/vtr_flow/scripts/run_vtr_flow.py b/vtr_flow/scripts/run_vtr_flow.py index aa2524b81ef..fd12a601a90 100755 --- a/vtr_flow/scripts/run_vtr_flow.py +++ b/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 used the Yosys conventional Verilog" + + " parser if this argument is not specified.", ) # # VPR arguments