resolved conflict with master branch

Author: saaramahmoudi

.github/workflows/nightly_test.yml

@@ -1,6 +1,23 @@
 name: NightlyTest
 
 on:
+  # We want to run the CI when anything is pushed to master.
+  # Since master is a protected branch this only happens when a PR is merged.
+  # This is a double check in case the PR was stale and had some issues.
+  push:
+    branches:
+      - master
+    paths-ignore: # Prevents from running if only docs are updated
+      - 'doc/**'
+      - '**/*README*'
+      - '**.md'
+      - '**.rst'
+  pull_request:
+    paths-ignore: # Prevents from running if only docs are updated
+      - 'doc/**'
+      - '**/*README*'
+      - '**.md'
+      - '**.rst'
   workflow_dispatch:
   schedule:
   - cron: '0 0 * * *' # daily
@@ -45,9 +62,9 @@ jobs:
           - {test: "vtr_reg_strong",             cores: "16", options: "",          cmake: "-DVTR_ASSERT_LEVEL=3",                                         extra_pkgs: "libeigen3-dev"}
           - {test: "vtr_reg_strong_odin",        cores: "16", options: "",          cmake: "-DVTR_ASSERT_LEVEL=3 -DWITH_ODIN=ON",                          extra_pkgs: "libeigen3-dev"}
           - {test: "vtr_reg_strong_odin",        cores: "16", options: "-skip_qor", cmake: "-DVTR_ASSERT_LEVEL=3 -DVTR_ENABLE_SANITIZE=ON -DWITH_ODIN=ON", extra_pkgs: "libeigen3-dev"}
-          - {test: "vtr_reg_system_verilog",     cores: "16", options: "",          cmake: "-DYOSYS_F4PGA_PLUGINS=ON",                                     extra_pkgs: ""}
+          # - {test: "vtr_reg_system_verilog",     cores: "16", options: "",          cmake: "-DYOSYS_F4PGA_PLUGINS=ON",                                     extra_pkgs: ""} # Test turned off -> F4PGA conflicts with Yosys (version 42)
           - {test: "odin_reg_strong",            cores: "16", options: "",          cmake: "-DWITH_ODIN=ON",                                               extra_pkgs: ""}
-          - {test: "parmys_reg_strong",          cores: "16", options: "",          cmake: "-DYOSYS_F4PGA_PLUGINS=ON",                                     extra_pkgs: ""}
+          - {test: "parmys_reg_strong",          cores: "16", options: "",          cmake: "-DYOSYS_F4PGA_PLUGINS=OFF",                                     extra_pkgs: ""}
 
     env:
       DEBIAN_FRONTEND: "noninteractive"

.github/workflows/test.yml

@@ -141,6 +141,11 @@ jobs:
             params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on',
             suite: 'vtr_reg_basic'
           },
+          {
+            name: 'Basic with highest assertion level',
+            params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=4 -DWITH_BLIFEXPLORER=on',
+            suite: 'vtr_reg_basic'
+          },
           {
             name: 'Basic_odin',
             params: '-DCMAKE_COMPILE_WARNING_AS_ERROR=on -DVTR_ASSERT_LEVEL=3 -DWITH_BLIFEXPLORER=on -DWITH_PARMYS=OFF -DWITH_ODIN=on',

.gitignore

@@ -144,6 +144,7 @@ tags
 #
 .vscode
 .history
+.cache
 #eclipse project
 .project
 
@@ -153,4 +154,4 @@ tags
 .idea
 cmake-build-debug
 cmake-build-release
-/.metadata/
+/.metadata/

CMakeLists.txt

@@ -130,11 +130,6 @@ endif()
 # Build type flags
 #
 
-set(EXTRA_FLAGS "")
-if(VPR_ENABLE_INTERCHANGE)
-    set(EXTRA_FLAGS "-lz")
-endif()
-
 if(NOT MSVC)
     # for GCC and Clang
     set(CMAKE_C_FLAGS_DEBUG "${CMAKE_C_FLAGS_DEBUG} -O0 -g3")
@@ -298,6 +293,7 @@ endif()
 #
 # Increased debugging vebosity
 #
+set(EXTRA_FLAGS "")
 if(VTR_ENABLE_VERBOSE)
     set(EXTRA_FLAGS "${EXTRA_FLAGS} -DVTR_ENABLE_DEBUG_LOGGING")
     message(STATUS "Enabling increased debugging verbosity")

doc/src/arch/index.rst

@@ -4,7 +4,7 @@ FPGA Architecture Description
 =============================
 
 VTR uses an XML-based architecture description language to describe the targeted FPGA architecture.
-This flexible description langauge allows the user to describe a large number of hypothetical and commercial-like FPGA architectures.
+This flexible description language allows the user to describe a large number of hypothetical and commercial-like FPGA architectures.
 
 See the :ref:`arch_tutorial` for an introduction to the architecture description langauge.
 For a detailed reference on the supported options see the :ref:`arch_reference`.

doc/src/arch/reference.rst

@@ -2031,11 +2031,40 @@ The ``<segment>`` tag and its contents are described below.
 .. arch:tag:: <mux name="string"/>
 
     :req_param name: Name of the mux switch type used to drive this type of segment by default, from both block outputs and other wires. This information is used during rr-graph construction, and a custom switch block can override this switch type for specific connections if desired.
+                     The switch type specified with the <mux> tag will be used for both the incrementing and decrementing wires within this segment. 
+                     If more control is needed, the mux_inc and mux_dec tags can be used to assign different muxes to drive incremental and decremental wires within the segment.
 
     .. note:: For UNIDIRECTIONAL only.
 
     Tag must be included and ``name`` must be the same as the name you give in ``<switch type="mux" name="...``
 
+.. arch:tag:: <mux_inc name="string"/>
+
+    :req_param name: 
+        Name of the mux switch type used to drive the incremental wires in this segment from both block outputs and other wires.
+        Incremental wires are tracks within this segment that are heading in the "right" direction on the x-axis and the "top" direction on the y-axis.
+        This information is used during rr-graph construction, and a custom switch block can override this switch type for specific connections if desired.
+
+    .. note:: For UNIDIRECTIONAL only.
+
+.. arch:tag:: <mux_dec name="string">
+    
+    :req_param name: 
+        Name of the mux switch type used to drive the decremental wires in this segment from both block outputs and other wires.
+        Incremental wires are tracks within this segment that are heading in the "left" direction on the x-axis and the "bottom" direction on the y-axis.
+        This information is used during rr-graph construction, and a custom switch block can override this switch type for specific connections if desired.
+
+    .. note:: For UNIDIRECTIONAL only.
+
+    .. note:: For unidirectional segments, either <mux> tag or both <mux_inc> and <mux_dec> should be defined in the architecture file. If only the <mux> tag is defined, we assume that the same mux drives both incremental and decremental wires within this segment.     
+
+.. arch:tag:: <mux_inter_die name="string"/>
+
+    :req_param name: Name of the mux switch type used to drive this segment type when the driver (block outputs and other wires) is located on a different die than the segment. This information is utilized during rr-graph construction.
+
+    Tag must be included and ``name`` must be the same as the name you give in ``<switch type="mux" name="...``
+
+
 .. arch:tag:: <wire_switch name="string"/>
 
     :req_param name: Name of the switch type used by other wires to drive this type of segment by default. This information is used during rr-graph construction, and a custom switch block can override this switch type for specific connections if desired.

doc/src/quickstart/index.rst

@@ -2,22 +2,22 @@
 VTR Quick Start
 ###############
 
-This is a quick introduction to VTR which covers how to run VTR and some if its associated tools (:ref:`VPR`, :ref:`odin_ii`, :ref:`ABC`).
+This is a quick introduction to VTR which covers how to run VTR and some of its associated tools (:ref:`VPR`, :ref:`odin_ii`, :ref:`ABC`).
 
 Setting Up VTR
 ==============
 
 Download VTR
 ------------
 
-The first step is to `download VTR <https://verilogtorouting.org/download/>`_ and extract VTR on your local machine.
+The first step is to `download VTR <https://verilogtorouting.org/download/>`_ and extract it on your local machine.
 
 .. note:: Developers planning to modify VTR should clone the `VTR git repository <https://github.com/verilog-to-routing/vtr-verilog-to-routing/>`_.
 
 
 Environment Setup
 -----------------
-If you cloned the repository you will need to set up the git submodules (if you downloaded and extracted a release, you can skip this step):
+If you cloned the repository, you will need to set up the git submodules (if you downloaded and extracted a release, you can skip this step):
 
 .. code-block:: bash
 
@@ -77,12 +77,12 @@ For more details on building VTR on various operating systems/platforms see :doc
 Running VPR
 ===========
 
-Lets now try taking a simple pre-synthesized circuit (consisting of LUTs and Flip-Flops) and use the VPR tool to implement it on a specific FPGA architecture.
+Let's now try taking a simple pre-synthesized circuit (consisting of LUTs and Flip-Flops) and use the VPR tool to implement it on a specific FPGA architecture.
 
 Running VPR on a Pre-Synthesized Circuit
 ----------------------------------------
 
-First, lets make a directory in our home directory where we can work:
+First, let's make a directory in our home directory where we can work:
 
 .. code-block:: bash
 
@@ -211,13 +211,13 @@ Running the VTR Flow
 In the previous section we have implemented a pre-synthesized circuit onto a pre-existing FPGA architecture using VPR, and visualized the result.
 We now turn to how we can implement *our own circuit* on a pre-existing FPGA architecture.
 
-To do this we begin by describing a circuit behaviourly using the Verilog Hardware Description Language (HDL).
+To do this, we begin by describing a circuit behaviourally using the Verilog Hardware Description Language (HDL).
 This allows us to quickly and consisely define the circuit's behaviour.
 We will then use the VTR Flow to synthesize the behavioural Verilog description it into a circuit netlist, and implement it onto an FPGA.
 
 Example Circuit
 ---------------
-We will use the following simple example circuit, which causes it's output to toggle on and off:
+We will use the following simple example circuit, which causes its output to toggle on and off:
 
 .. literalinclude:: blink.v
     :language: verilog
@@ -230,7 +230,7 @@ If the count is below ``16`` it drives the output (``o_led``) high, otherwise it
 
 Manually Running the VTR Flow
 -----------------------------
-Lets start by making a fresh directory for us to work in:
+Let's start by making a fresh directory for us to work in:
 
 .. code-block:: bash
 
@@ -241,15 +241,15 @@ Next we need to run the three main sets of tools:
 
 * :ref:`odin_ii` performs 'synthesis' which converts our behavioural Verilog (``.v`` file) into a circuit netlist (``.blif`` file) consisting of logic equations and FPGA architecture primitives (Flip-Flops, adders etc.),
 * :ref:`ABC` performs 'logic optimization' which simplifies the circuit logic, and 'technology mapping' which converts logic equations into the Look-Up-Tables (LUTs) available on an FPGA, and
-* :ref:`VPR` which performs packing, placement and routing of the circuit to implement it on the targetted FPGA architecture.
+* :ref:`VPR` which performs packing, placement and routing of the circuit to implement it on the targeted FPGA architecture.
 
 .. _synthesizing_with_odin_ii:
 Synthesizing with ODIN II
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 First we'll run ODIN II on our Verilog file to synthesize it into a circuit netlist, providing the options:
 
- * ``-a $VTR_ROOT/vtr_flow/arch/timing/EArch.xml`` which specifies what FPGA architecture we are targetting,
+ * ``-a $VTR_ROOT/vtr_flow/arch/timing/EArch.xml`` which specifies what FPGA architecture we are targeting,
  * ``-V $VTR_ROOT/doc/src/quickstart/blink.v`` which specifies the verilog file we want to synthesize, and
  * ``-o blink.odin.blif`` which specifies the name of the generated ``.blif`` circuit netlist.
 
@@ -400,7 +400,7 @@ Automatically Running the VTR Flow
 Running each stage of the flow manually is time consuming (and potentially error prone).
 For convenience, VTR provides a script (:ref:`run_vtr_flow`) which automates this process.
 
-First, make sure you sure you have activated the Python virtual environment created at the beginning of this tutorial:
+First, make sure you have activated the Python virtual environment created at the beginning of this tutorial:
 
 .. code-block:: bash
 

doc/src/vpr/command_line_usage.rst

@@ -979,15 +979,16 @@ The following options are only valid when the placement engine is in timing-driv
 
     **Default:** ``8.0``
 
-.. option:: --place_delay_model {delta, delta_override}
+.. option:: --place_delay_model {simple, delta, delta_override}
 
     Controls how the timing-driven placer estimates delays.
 
-     * ``delta`` The router is used to profile delay from various locations in the grid for various differences in position
+     * ``simple`` The placement delay estimator is built from the router lookahead. This takes less CPU time to build and it and still as accurate as the ``delta` model.
+     * ``delta`` The router is used to profile delay from various locations in the grid for various differences in position.
      * ``delta_override`` Like ``delta`` but also includes special overrides to ensure effects of direct connects between blocks are accounted for.
        This is potentially more accurate but is more complex and depending on the architecture (e.g. number of direct connects) may increase place run-time.
 
-    **Default:** ``delta``
+    **Default:** ``simple``
 
 .. option:: --place_delay_model_reducer {min, max, median, arithmean, geomean}
 
@@ -1292,6 +1293,13 @@ VPR uses a negotiated congestion algorithm (based on Pathfinder) to perform rout
     * `swns` - setup Worst Negative Slack (sWNS) [ns]
     * `stns` - Setup Total Negative Slack (sTNS) [ns]
 
+.. option:: --route_verbosity <int>
+
+    Controls the verbosity of routing output.
+    High values produce more detailed output, which can be useful for debugging or understanding the routing process.
+
+    **Default**: ``1``
+
 .. _timing_driven_router_options:
 
 Timing-Driven Router Options
@@ -1306,6 +1314,15 @@ The following options are only valid when the router is in timing-driven mode (t
 
     **Default:** ``1.2``
 
+.. option:: --astar_offset <float>
+
+    Sets how aggressive the directed search used by the timing-driven router is.
+    It is a subtractive adjustment to the lookahead heuristic.
+
+    Values between 0 and 1e-9 are resonable; higher values may increase quality at the expense of run-time.
+
+    **Default:** ``0.0``
+
 .. option:: --router_profiler_astar_fac <float>
 
     Controls the directedness of the timing-driven router's exploration when doing router delay profiling of an architecture.

doc/src/vpr/file_formats.rst

@@ -616,23 +616,32 @@ The io pad is set to inpad mode and is driven by the inpad:
 
 Placement File Format (.place)
 ------------------------------
+The placement file format is used to specify the position of cluster-level blocks in an FPGA design. It includes information about the netlist and architecture files, the size of the logic block array, and the placement details of each block in the CLB netlist..
+
 The first line of the placement file lists the netlist (.net) and architecture (.xml) files used to create this placement.
-This information is used to ensure you are warned if you accidentally route this placement with a different architecture or netlist file later.
+This information is used to ensure you are warned if you accidentally route this placement with a different architecture or netlist file later. 
 The second line of the file gives the size of the logic block array used by this placement.
-All the following lines have the format::
 
-    block_name    x        y   subtile_number
+All subsequent lines follow this format:
+
+    block_name    x    y    subblk    [layer_number]    [#block_number]
+
+- **block_name**: Refers to either:
+  - The name of a clustered block, as given in the input .net formatted netlist.
+  - The name of a primitive within a clustered block.
+
+- **x** and **y**: Represent the row and column in which the block is placed, respectively.
 
-The ``block_name`` is the name of this block, as given in the input .net formatted netlist.
-``x`` and ``y`` are the row and column in which the block is placed, respectively.
+- **subblk**: Specifies which of several possible subtile locations in row **x** and column **y** contains this block, which is useful when the tile capacity is greater than 1. The subtile number should be in the range `0` to `(grid[i][j].capacity - 1)`. The subtile numbers for a particular **x, y** location do not have to be used in order.
+
+- **layer_number**: Indicates the layer (or die) on which the block is placed. If omitted, the block is assumed to be placed on layer `0` (a single die system). In 3D FPGA architectures, multiple dies can be stacked, with the bottom die considered as layer `0`.
+
+The placement files output by VPR also include (as a comment) an extra field: the id (number) of the block in the CLB netlist. This is the internal index used by VPR to identify a CLB level block -- it may be useful to know this index if you are modifying VPR and trying to debug something.
 
 .. note:: The blocks in a placement file can be listed in any order.
 
-Since we can have more than one block in a row or column when the block capacity is set to be greater than 1 in the architecture file, the subtile number specifies which of the several possible subtile locations in row x and column y contains this block.
-Note that the subtile number used should be in the range 0 to (grid[i][j].capacity - 1). The subtile numbers for a particular x,y location do not have to be used in order.
 
-The placement files output by VPR also include (as a comment) a fifth field:  the block number.
-This is the internal index used by VPR to identify a block -- it may be useful to know this index if you are modifying VPR and trying to debug something.
+.. note:: A `#` character on a line indicates that all text after the `#` to the end of a line is a comment.
 
 .. _fig_fpga_coord_system:
 
@@ -649,10 +658,10 @@ All pads either have x equal to ``0`` or ``nx + 1`` or y equal to ``0`` or ``ny
 
 Placement File Format Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-An example placement file is:
+
 
 .. code-block:: none
-    :caption: Example placement file.
+    :caption: Example 2D Placement File
     :linenos:
 
     Netlist file: xor5.net   Architecture file: sample.xml
@@ -669,6 +678,23 @@ An example placement file is:
     xor5        1       2       0       #6
     [1]         1       1       0       #7
 
+.. code-block:: none
+    :caption: Example 3D Placement File with Layer Column
+    :linenos:
+
+    Netlist file: xor5.net   Architecture file: sample.xml
+    Array size: 2 x 2 logic blocks
+
+    #block name x       y       subblk  layer  block number
+    #---------- --      --      ------- ------ -----------
+    a           0       1       0       0      #0  -- NB: block number is a comment.
+    b           1       0       0       1      #1
+    c           0       2       1       0      #2
+    d           1       3       0       1      #3
+    e           1       3       1       0      #4
+    out:xor5    0       2       0       1      #5
+    xor5        1       2       0       0      #6
+    [1]         1       1       0       1      #7
 
 .. _vpr_route_file:
 

doc/src/vpr/vpr_constraints.rst

@@ -2,9 +2,7 @@ VPR Constraints
 =========================
 .. _vpr_constraints:
 
-VPR allows users to run the flow with placement constraints that enable primitives to be locked down to a specific region on the chip and global routing constraints that facilitate the routing of global nets through clock networks.
-
-Users can specify these constraints through a constraints file in XML format, as shown in the format below.
+Users can specify placement and/or global routing constraints on all or part of a design through a constraints file in XML format, as shown in the format below. These constraints are optional and allow detailed control of the region on the chip in which parts of the design are placed, and of the routing of global nets through dedicated (usually clock) networks. 
 
 .. code-block:: xml
    :caption: The overall format of a VPR constraints file