Merge branch 'master' into Yosys42

Author: amirarjmand93

.github/workflows/test.yml

@@ -64,10 +64,10 @@ 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: "odin_reg_strong",            cores: "16", options: "",          cmake: "-DWITH_ODIN=ON",                                               extra_pkgs: ""}
           - {test: "parmys_reg_strong",          cores: "16", options: "",          cmake: "-DYOSYS_F4PGA_PLUGINS=OFF",                                     extra_pkgs: ""}
 
+
     env:
       DEBIAN_FRONTEND: "noninteractive"
 

.gitignore

@@ -153,4 +153,4 @@ tags
 .idea
 cmake-build-debug
 cmake-build-release
-/.metadata/
+/.metadata/

README.developers.md

@@ -1272,47 +1272,96 @@ make CMAKE_PARAMS="-DVTR_IPO_BUILD=off" -j8 vpr
 
 # Profiling VTR
 
-1. Install `gprof`, `gprof2dot`, and `xdot`. Specifically, the previous two packages require python3, and you should install the last one with `sudo apt install` for all the dependencies you will need for visualizing your profile results.
+## Use GNU Profiler gprof
+
+1. **Installation**: Install `gprof`, `gprof2dot`, and `xdot` (optional).
+   1. `gprof` is part of [GNU Binutils](https://www.gnu.org/software/binutils/), which is a commonly-installed package alongside the standard GCC package on most systems. `gprof` should already exist. If not, use `sudo apt install binutils`.
+   2. `gprof2dot` requires python3 or conda. You can install with `pip3 install gprof2dot` or `conda install -c conda-forge gprof2dot`.
+   3. `xdot` is optional. To install it, use `sudo apt install`.
     ```
-    pip3 install gprof
+    sudo apt install binutils
     pip3 install gprof2dot
-    sudo apt install xdot
+    sudo apt install xdot # optional
     ```
 
     Contact your administrator if you do not have the `sudo` rights.
 
-2. Use the CMake option below to enable VPR profiler build.
+2. **VPR build**: Use the CMake option below to enable VPR profiler build.
     ```
     make CMAKE_PARAMS="-DVTR_ENABLE_PROFILING=ON" vpr
     ```
 
-3. With the profiler build, each time you run the VTR flow script, it will produce an extra file `gmon.out` that contains the raw profile information. 
-    Run `gprof` to parse this file. You will need to specify the path to the VPR executable.
+3. **Profiling**:
+   1. With the profiler build, each time you run the VTR flow script, it will produce an extra file `gmon.out` that contains the raw profile information. Run `gprof` to parse this file. You will need to specify the path to the VPR executable.
+        ```
+        gprof $VTR_ROOT/vpr/vpr gmon.out > gprof.txt
+        ```
+
+   2. Next, use `gprof2dot` to transform the parsed results to a `.dot` file (Graphviz graph description), which describes the graph of your final profile results. If you encounter long function names, specify the `-s` option for a cleaner graph. For other useful options, please refer to its [online documentation](https://github.com/jrfonseca/gprof2dot?tab=readme-ov-file#documentation).
+        ```
+        gprof2dot -s gprof.txt > vpr.dot
+        ```
+
+   - Note: You can chain the above commands to directly produce the `.dot` file:
+        ```
+        gprof $VTR_ROOT/vpr/vpr gmon.out | gprof2dot -s > vpr.dot
+        ```
+
+4. **Visualization**:
+   - **Option 1** (Recommended): Use the [Edotor](https://edotor.net/) online Graphviz visualizer.
+     1. Open a browser and go to [https://edotor.net/](https://edotor.net/) (on any device, not necessarily the one where VPR is running).
+     2. Choose `dot` as the "Engine" at the top navigation bar.
+     3. Next, copy and paste `vpr.dot` into the editor space on the left side of the web view.
+     4. Then, you can interactively (i.e., pan and zoom) view the results and download an SVG or PNG image.
+   - **Option 2**: Use the locally-installed `xdot` visualization tool.
+     1. Use `xdot` to view your results:
+        ```
+        xdot vpr.dot
+        ```
+     2. To save your results as a PNG file:
+        ```
+        dot -Tpng -Gdpi=300 vpr.dot > vpr.png
+        ```
+        Note that you can use the `-Gdpi` option to make your picture clearer if you find the default dpi settings not clear enough.
+
+## Use Linux Perf Tool
+
+1. **Installation**: Install `perf` and `gprof2dot` (optional).
     ```
-    gprof $VTR_ROOT/vpr/vpr gmon.out > gprof.txt
+    sudo apt install linux-tools-common linux-tools-generic
+    pip3 install gprof2dot # optional
     ```
 
-4. Next, use `gprof2dot` to transform the parsed results to a `.dot` file, which describes the graph of your final profile results. If you encounter long function names, specify the `-s` option for a cleaner graph.
+2. **VPR build**: *No need* to enable any CMake options for using `perf`, unless you want to utilize specific features, such as `perf annotate`.
     ```
-    gprof2dot -s gprof.txt > vpr.dot
+    make vpr
     ```
 
-5. You can chain the above commands to directly produce the `.dot` file:
-    ```
-    gprof $VTR_ROOT/vpr/vpr gmon.out | gprof2dot -s > vpr.dot
-    ```
+3. **Profiling**: `perf` needs to know the process ID (i.e., pid) of the running VPR you want to monitor and profile, which can be obtained using the Linux command `top -u <username>`.
+   - **Option 1**: Real-time analysis
+        ```
+        sudo perf top -p <vpr pid>
+        ```
+   - **Option 2** (Recommended): Record and offline analysis
+
+        Use `perf record` to record the profile data and the call graph. (Note: The argument `lbr` for `--call-graph` only works on Intel platforms. If you encounter issues with call graph recording, please refer to the [`perf record` manual](https://perf.wiki.kernel.org/index.php/Latest_Manual_Page_of_perf-record.1) for more information.)
+        ```
+        sudo perf record --call-graph lbr -p <vpr pid>
+        ```
+        After VPR completes its run, or if you stop `perf` with CTRL+C (if you are focusing on a specific portion of the VPR execution), the `perf` tool will produce an extra file `perf.data` containing the raw profile results in the directory where you ran `perf`. You can further analyze the results by parsing this file using `perf report`.
+        ```
+        sudo perf report -i perf.data
+        ```
+   - Note 1: The official `perf` [wiki](https://perf.wiki.kernel.org/index.php/Main_Page) and [tutorial](https://perf.wiki.kernel.org/index.php/Tutorial) are highly recommended for those who want to explore more uses of the tool.
+   - Note 2: It is highly recommended to run `perf` with `sudo`, but you can find a workaround [here](https://superuser.com/questions/980632/run-perf-without-root-rights) to allow running `perf` without root rights.
+   - Note 3: You may also find [Hotspot](https://github.com/KDAB/hotspot) useful if you want to run `perf` with GUI support.
+
+4. **Visualization** (optional): If you want a better illustration of the profiling results, first run the following command to transform the `perf` report into a Graphviz dot graph. The remaining steps are exactly the same as those described under [Use GNU Profiler gprof
+](#use-gnu-profiler-gprof).
+     ```
+     perf script -i perf.data | c++filt | gprof2dot.py -f perf -s > vpr.dot
+     ```
 
-6. Use `xdot` to view your results:
-    ```
-    xdot vpr.dot
-    ```
-
-7. To save your results as a `png` file:
-    ```
-    dot -Tpng -Gdpi=300 vpr.dot > vpr.png
-    ```
-    
-    Note that you can use the `-Gdpi` option to make your picture clearer if you find the default dpi settings not clear enough.
 
 # External Subtrees
 VTR includes some code which is developed in external repositories, and is integrated into the VTR source tree using [git subtrees](https://www.atlassian.com/blog/git/alternatives-to-git-submodule-git-subtree).

doc/src/api/vprinternals/index.rst

@@ -10,3 +10,4 @@ VPR INTERNALS
    vpr_ui
    draw_files
    vpr_noc
+   vpr_router

doc/src/api/vprinternals/router_heap.rst

@@ -0,0 +1,31 @@
+==============
+Router Heap
+==============
+
+t_heap
+----------
+.. doxygenstruct:: t_heap
+   :project: vpr
+   :members:
+
+HeapInterface
+----------
+.. doxygenclass:: HeapInterface
+   :project: vpr
+   :members:
+
+HeapStorage
+----------
+.. doxygenclass:: HeapStorage
+   :project: vpr
+   :members:
+
+KAryHeap
+----------
+.. doxygenclass:: KAryHeap
+   :project: vpr
+
+FourAryHeap
+----------
+.. doxygenclass:: FourAryHeap
+   :project: vpr

doc/src/api/vprinternals/vpr_router.rst

@@ -0,0 +1,10 @@
+.. _router:
+
+=======
+VPR Router
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   router_heap

doc/src/vpr/placement_constraints.rst

@@ -28,6 +28,14 @@ A Placement Constraints File Example
 					<add_atom name_pattern="n4917"/>
 					<add_atom name_pattern="n6010"/>
 			</partition>
+
+            <partition name="Part2">
+					<add_region x_low="3" y_low="3" x_high="85" y_high="85"/> <!-- When the layer is not explicitly specified, layer 0 is assumed. -->
+                    <add_region x_low="8" y_low="5" x_high="142" y_high="29 layer_low="0" layer_high="1"/> <!-- In 3D architectures, the region can span across multiple layers. -->
+                    <add_region x_low="6" y_low="55" x_high="50" y_high="129 layer_low="2" layer_high="2"/> <!-- If the region only covers a non-zero layer, both layer_low and layer_high must be set the same value. -->
+					<add_atom name_pattern="n135"/>
+					<add_atom name_pattern="n7016"/>
+			</partition>
 		</partition_list>
 	</vpr_constraints>
 
@@ -75,7 +83,10 @@ The ``name_pattern`` can be the exact name of the atom from the input atom netli
 Region
 ^^^^^^
 
-An ``<add_region>`` tag is used to add a region to the partition. A ``region`` is a rectangular area on the chip. A partition can contain any number of independent regions - the regions within one partition must not overlap with each other (in order to ease processing when loading in the file). An ``<add_region>`` tag has the following attributes.
+An ``<add_region>`` tag is used to add a region to the partition. A ``region`` is a rectangular area or cubic volume
+on the chip. A partition can contain any number of independent regions - the regions within one partition **must not**
+overlap with each other (in order to ease processing when loading in the file).
+An ``<add_region>`` tag has the following attributes.
 
 :req_param x_low:
    The x value of the lower left point of the rectangle.
@@ -90,11 +101,30 @@ An ``<add_region>`` tag is used to add a region to the partition. A ``region`` i
    The y value of the upper right point of the rectangle.
 
 :opt_param subtile:
-   Each x, y location on the grid may contain multiple locations known as subtiles. This paramter is an optional value specifying the subtile location that the atom(s) of the partition shall be constrained to.
+   Each x, y location on the grid may contain multiple locations known as subtiles. This parameter is an optional value specifying the subtile location that the atom(s) of the partition shall be constrained to.
+
+:opt_param layer_low:
+    The lowest layer number that the region covers. The default value is 0.
+
+:opt_param layer_high:
+    The highest layer number that the region covers. The default value is 0.
 
 The optional ``subtile`` attribute is commonly used when constraining an atom to a specific location on the chip (e.g. an exact I/O location). It is legal to use with larger regions, but uncommon.
 
-If a user would like to specify an area on the chip with an unusual shape (e.g. L-shaped or T-shaped), they can simply add multiple ``<add_region>`` tags to cover the area specified.
+In 2D architectures, ``layer_low`` and ``layer_high`` can be safely ignored as their default value is 0.
+In 3D architectures, a region can span across multiple layers or be assigned to a specific layer.
+For assigning a region to a specific non-zero layer, the user should set both ``layer_low`` and ``layer_high`` to the
+desired layer number. If a layer range is to be covered by the region, the user set ``layer_low`` and ``layer_high`` to
+different values.
+
+If a user would like to specify an area on the chip with an unusual shape (e.g. L-shaped or T-shaped),
+they can simply add multiple ``<add_region>`` tags to cover the area specified.
+
+It is strongly recommended that different partitions do not overlap. The packing algorithm compares the number clustered
+blocks and the number of physical blocks in a region to decide pack atoms inside a partition more aggressively when
+there are not enough resources in a partition. Overlapping partitions causes some physical blocks to be counted in more
+than one partition.
+
 
 
 

libs/libarchfpga/src/arch_util.cpp

@@ -35,7 +35,7 @@ const char* get_arch_file_name() {
     return arch_file_name;
 }
 
-InstPort::InstPort(std::string str) {
+InstPort::InstPort(const std::string& str) {
     std::vector<std::string> inst_port = vtr::split(str, ".");
 
     if (inst_port.size() == 1) {

libs/libarchfpga/src/arch_util.h

@@ -22,7 +22,7 @@ class InstPort {
     static constexpr int UNSPECIFIED = -1;
 
     InstPort() = default;
-    InstPort(std::string str);
+    InstPort(const std::string& str);
     std::string instance_name() const { return instance_.name; }
     std::string port_name() const { return port_.name; }
 

libs/libarchfpga/src/echo_arch.cpp

@@ -236,11 +236,11 @@ void PrintArchInfo(FILE* Echo, const t_arch* arch) {
     }
 
     fprintf(Echo, "\tInput Connect Block Switch Name Within a Same Die: %s\n", arch->ipin_cblock_switch_name[ipin_cblock_switch_index_within_die].c_str());
-    
+
     //if there is more than one layer available, print the connection block switch name that is used for connection between two dice
-    for(const auto& layout : arch->grid_layouts){
+    for (const auto& layout : arch->grid_layouts) {
         int num_layers = (int)layout.layers.size();
-        if(num_layers > 1){
+        if (num_layers > 1) {
             fprintf(Echo, "\tInput Connect Block Switch Name Between Two Dice: %s\n", arch->ipin_cblock_switch_name[ipin_cblock_switch_index_between_dice].c_str());
         }
     }
@@ -295,11 +295,11 @@ void PrintArchInfo(FILE* Echo, const t_arch* arch) {
             fprintf(Echo, "\t\t\t\ttype unidir mux_name for within die connections: %s\n",
                     arch->Switches[seg.arch_wire_switch].name.c_str());
             //if there is more than one layer available, print the segment switch name that is used for connection between two dice
-            for(const auto& layout : arch->grid_layouts){
+            for (const auto& layout : arch->grid_layouts) {
                 int num_layers = (int)layout.layers.size();
-                if(num_layers > 1){
+                if (num_layers > 1) {
                     fprintf(Echo, "\t\t\t\ttype unidir mux_name for between two dice connections: %s\n",
-                        arch->Switches[seg.arch_opin_between_dice_switch].name.c_str());
+                            arch->Switches[seg.arch_opin_between_dice_switch].name.c_str());
                 }
             }
         } else { //Should be bidir