Merge branch 'master' into add_parallel_docs

Author: AlexandreSinger

.github/scripts/install_dependencies.sh

@@ -2,40 +2,32 @@
 
 sudo apt update
 
+# Required packages specifically for the CI and not VTR in general.
 sudo apt install -y \
   autoconf \
   automake \
   bash \
-  bison \
   binutils \
   binutils-gold \
-  build-essential \
   capnproto \
   exuberant-ctags \
   curl \
   doxygen \
-  flex \
   fontconfig \
   gdb \
-  git \
   gperf \
   libcairo2-dev \
   libcapnp-dev \
-  libgtk-3-dev \
   libevent-dev \
   libfontconfig1-dev \
   liblist-moreutils-perl \
   libncurses5-dev \
-  libx11-dev \
   libxft-dev \
   libxml2-utils \
   libxml++2.6-dev \
-  libreadline-dev \
   tcllib \
   tcl8.6-dev \
-  libffi-dev \
   perl \
-  pkg-config \
   texinfo \
   time \
   valgrind \
@@ -54,9 +46,10 @@ sudo apt install -y \
   clang-15 \
   clang-16 \
   clang-17 \
-  clang-18 \
-  clang-format-18 \
-  libtbb-dev
+  clang-18
+
+# Standard packages install script.
+./install_apt_packages.sh
 
 pip install -r requirements.txt
 

.github/scripts/install_jammy_dependencies.sh

@@ -2,40 +2,32 @@
 
 sudo apt update
 
+# Required packages specifically for the CI and not VTR in general.
 sudo apt install -y \
   autoconf \
   automake \
   bash \
-  bison \
   binutils \
   binutils-gold \
-  build-essential \
   capnproto \
   exuberant-ctags \
   curl \
   doxygen \
-  flex \
   fontconfig \
   gdb \
-  git \
   gperf \
   libcairo2-dev \
   libcapnp-dev \
-  libgtk-3-dev \
   libevent-dev \
   libfontconfig1-dev \
   liblist-moreutils-perl \
   libncurses5-dev \
-  libx11-dev \
   libxft-dev \
   libxml2-utils \
   libxml++2.6-dev \
-  libreadline-dev \
   tcllib \
   tcl8.6-dev \
-  libffi-dev \
   perl \
-  pkg-config \
   texinfo \
   time \
   valgrind \
@@ -50,9 +42,10 @@ sudo apt install -y \
   g++-11 \
   gcc-11 \
   g++-12 \
-  gcc-12 \
-  clang-format-14 \
-  libtbb-dev
+  gcc-12
+
+# Standard packages install script.
+./install_apt_packages.sh
 
 pip install -r requirements.txt
 

Dockerfile

@@ -11,18 +11,15 @@ ENV PIP_BREAK_SYSTEM_PACKAGES=1
 # Install and cleanup is done in one command to minimize the build cache size
 RUN apt-get update -qq \
 # Extract package names from install_apt_packages.sh
-    && sed '/sudo/d' install_apt_packages.sh | sed '/#/d' | sed 's/ \\//g' | sed '/^$/d' | sed '/^[[:space:]]*$/d' \
+    && sed '/sudo/d' install_apt_packages.sh | sed '/#/d' | sed '/if\s.*then$/d' | sed '/else$/d' | sed '/fi$/d' | sed '/echo\s/d' | sed 's/ \\//g' | sed '/^$/d' | sed '/^[[:space:]]*$/d' | sed 's/\s//g' \
 # Install packages
     | xargs apt-get -y install --no-install-recommends \
 # Additional packages not listed in install_apt_packages.sh
     && apt-get -y install --no-install-recommends \
     wget \
     ninja-build \
-    default-jre \
     libeigen3-dev \
-    libtbb-dev \
     python3-pip \
-    git \
     time \
 # Install python packages
     && pip install -r requirements.txt \

README.developers.md

@@ -179,6 +179,29 @@ For large scale reformatting (should only be performed by VTR maintainers) the s
 
 Python files are automatically checked using `pylint` to ensure they follow established Python conventions.  You can run `pylint` on the entire repository by running `./dev/pylint_check.py`.  Certain files which were created before we adopted Python lint checking are grandfathered and are not checked.  To check *all* files, provide the `--check_grandfathered` argument.  You can also manually check individual files using `./dev/pylint_check.py <path_to_file1> <path_to_file2> ...`.
 
+# Sanitizing Includes
+
+You can use include-what-you-use or the clangd language server to make sure includes are correct and you don't have missing or unused includes.
+
+## include-what-you-use
+
+First, install include-what-you-use. Ubuntu/Debian users can run `sudo apt install iwyu` and Fedora/RHEL users can run `sudo dnf install iwyu`. You can then compile VTR with include-what-you-use enabled to get diagnostic messages about includes in all files with the following command:
+
+```
+make CMAKE_PARAMS="-DCMAKE_CXX_INCLUDE_WHAT_YOU_USE=include-what-you-use"
+```
+
+Note that this method checks all source files and the diagnostic messages can be very long.
+
+## clangd language server
+
+Alternatively, if your editor supports clangd, you can use it to get diagnostic messages for the specific file you are working with. Visual Studio Code users can use the clangd extension to use clangd instead of Microsoft's C/C++ extension. To enable include diagnostics, create a file named `.clangd` in VTR root directory and add the following lines to it:
+```
+Diagnostics:
+  UnusedIncludes: Strict
+  MissingIncludes: Strict
+```
+
 # Running Tests
 
 VTR has a variety of tests which are used to check for correctness, performance and Quality of Result (QoR).

README.md

@@ -36,7 +36,7 @@ See the [full license](LICENSE.md) for details.
 ## How to Cite
 The following paper may be used as a general citation for VTR:
 
-M. A. Elgammal, A. Mohaghegh, S. G. Shahrouz, F. Mahmoudi, F. Kosar, K. Talaei, J. Fife, D. Khadivi, K. Murray, A. Boutros, K. B. Kent, J. Geoders, and V. Betz "VTR 9: Open-Source CAD for Fabric and Beyond FPGA Architecture Exploration", ACM TRETS, 2025.
+M. A. Elgammal, A. Mohaghegh, S. G. Shahrouz, F. Mahmoudi, F. Kosar, K. Talaei, J. Fife, D. Khadivi, K. Murray, A. Boutros, K. B. Kent, J. Goeders, and V. Betz "VTR 9: Open-Source CAD for Fabric and Beyond FPGA Architecture Exploration", ACM TRETS, 2025. [PDF](https://dl.acm.org/doi/epdf/10.1145/3734798)
 
 Bibtex:
 ```

doc/src/vpr/command_line_usage.rst

@@ -1523,6 +1523,35 @@ 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:: --generate_net_timing_report {on | off}
+
+    Generates a report that lists the bounding box, slack, and delay of every routed connection in a design in CSV format (``report_net_timing.csv``). Each row in the CSV corresponds to a single net.
+
+    The report can later be used by other tools to enable further optimizations. For example, the Synopsys synthesis tool (Synplify) can use this information to re-synthesize the design and improve the Quality of Results (QoR).
+
+    Fields in the report are:
+
+    .. code-block:: none
+        
+        netname         : The name assigned to the net in the atom netlist
+        Fanout          : Net's fanout (number of sinks)
+        bb_xmin         : X coordinate of the net's bounding box's bottom-left corner
+        bb_ymin         : Y coordinate of the net's bounding box's bottom-left corner
+        bb_layer_min    : Lowest layer number of the net's bounding box
+        bb_xmax         : X coordinate of the net's bounding box's top-right corner
+        bb_ymax         : Y coordinate of the net's bounding box's top-right corner
+        bb_layer_max    : Highest layer number of the net's bounding box
+        src_pin_name    : Name of the net's source pin
+        src_pin_slack   : Setup slack of the net's source pin
+        sinks           : A semicolon-separated list of sink pin entries, each in the format:
+                          <sink_pin_name>,<sink_pin_slack>,<sink_pin_delay>
+
+    Example value for the ``sinks`` field:
+    ``"U2.B,0.12,0.5;U3.C,0.10,0.6;U4.D,0.08,0.7"``
+
+    **Default:** ``off``
+
 .. option:: --route_verbosity <int>
 
     Controls the verbosity of routing output.

doc/src/zreferences.rst

@@ -1,5 +1,18 @@
 Publications & References
 =========================
 
+How to cite
+-----------
+`M. A. Elgammal`, `A. Mohaghegh`, `S. G. Shahrouz`, `F. Mahmoudi`, `F. Kosar`, `K. Talaei`, `J. Fife`, `D. Khadivi`, `K. Murray`, `A. Boutros`, `K. B. Kent`, `J. Goeders`, and `V. Betz`, "VTR 9: Open-Source CAD for Fabric and Beyond FPGA Architecture Exploration," *ACM TRETS*, 2025. [`PDF <https://dl.acm.org/doi/epdf/10.1145/3734798>`__]
+
+Previous Publications
+---------------------
+* `K. E. Murray`, `O. Petelin`, `S. Zhong`, `J. M. Wang`, `M. ElDafrawy`, `J.-P. Legault`, `E. Sha`, `A. G. Graham`, `J. Wu`, `M. J. P. Walker`, `H. Zeng`, `P. Patros`, `J. Luu`, `K. B. Kent` and `V. Betz`, "VTR 8: High Performance CAD and Customizable FPGA Architecture Modelling", *ACM TRETS*, 2020.
+
+* `J. LUU`, `J. Goeders`, `M. Wainberg`, `A. Somerville`, `T. Yu`, `K. Nasartschuk`, `M. Nasr`, `S. Wang`, `T. L`, `N. Ahmed`, `K. B. Kent`, `J. Anderson`, `J. Rose`, `V. Betz`, "VTR 7.0: Next Generation Architecture and CAD System for FPGAs", *ACM TRETS*, 2014.
+
+References
+----------
+
 .. bibliography:: z_references.bib
     :all:

install_apt_packages.sh

@@ -10,7 +10,11 @@ sudo apt-get install -y \
     flex \
     python3-dev \
     python3-venv
-    
+
+# Packages for more complex features of VTR that most people will use.
+sudo apt-get install -y \
+    libtbb-dev
+
 # Required for graphics
 sudo apt-get install -y \
     libgtk-3-dev \
@@ -42,6 +46,11 @@ sudo apt-get install -y \
     sphinx-common
 
 # Required for code formatting
-sudo apt-get install -y \
-    clang-format-18
-
+# NOTE: clang-format-18 may only be found on specific distributions. Only
+#       install it if the distribution has this version of clang format.
+if apt-cache search '^clang-format-18$' | grep -q 'clang-format-18'; then
+    sudo apt-get install -y \
+        clang-format-18
+else
+    echo "clang-format-18 not found in apt-cache. Skipping installation."
+fi

libs/librrgraph/src/base/rr_graph_builder.cpp

@@ -31,31 +31,29 @@ void RRGraphBuilder::add_node_to_all_locs(RRNodeId node) {
     short node_layer = node_storage_.node_layer(node);
     short node_twist = node_storage_.node_ptc_twist(node);
     int node_offset = 0;
+
     for (int ix = node_storage_.node_xlow(node); ix <= node_storage_.node_xhigh(node); ix++) {
         for (int iy = node_storage_.node_ylow(node); iy <= node_storage_.node_yhigh(node); iy++) {
             node_ptc_num += node_twist * node_offset;
             node_offset++;
+
             switch (node_type) {
                 case e_rr_type::SOURCE:
                 case e_rr_type::SINK:
                 case e_rr_type::CHANY:
-                    node_lookup_.add_node(node, node_layer, ix, iy, node_type, node_ptc_num, TOTAL_2D_SIDES[0]);
-                    break;
                 case e_rr_type::CHANX:
-                    /* Currently need to swap x and y for CHANX because of chan, seg convention 
-                     * TODO: Once the builders is reworked for use consistent (x, y) convention,
-                     * the following swapping can be removed
-                     */
-                    node_lookup_.add_node(node, node_layer, iy, ix, node_type, node_ptc_num, TOTAL_2D_SIDES[0]);
+                    node_lookup_.add_node(node, node_layer, ix, iy, node_type, node_ptc_num, TOTAL_2D_SIDES[0]);
                     break;
+
                 case e_rr_type::OPIN:
                 case e_rr_type::IPIN:
-                    for (const e_side& side : TOTAL_2D_SIDES) {
+                    for (const e_side side : TOTAL_2D_SIDES) {
                         if (node_storage_.is_node_on_specific_side(node, side)) {
                             node_lookup_.add_node(node,node_layer, ix, iy, node_type, node_ptc_num, side);
                         }
                     }
                     break;
+
                 default:
                     VTR_LOG_ERROR("Invalid node type for node '%lu' in the routing resource graph file", size_t(node));
                     break;

libs/librrgraph/src/base/rr_graph_view.h

@@ -351,7 +351,7 @@ class RRGraphView {
 
                 start_x = " (" + std::to_string(node_xhigh(node)) + ","; //start coordinates have large value
                 start_y = std::to_string(node_yhigh(node)) + ",";
-                start_layer_str = std::to_string(node_layer_num);
+                start_layer_str = std::to_string(node_layer_num) + ")";
                 end_x = " (" + std::to_string(node_xlow(node)) + ","; //end coordinates have smaller value
                 end_y = std::to_string(node_ylow(node)) + ",";
                 end_layer_str = std::to_string(node_layer_num) + ")";
@@ -360,7 +360,7 @@ class RRGraphView {
             else {                                                      // signal travels in increasing direction, stays at same point, or can travel both directions
                 start_x = " (" + std::to_string(node_xlow(node)) + ","; //start coordinates have smaller value
                 start_y = std::to_string(node_ylow(node)) + ",";
-                start_layer_str = std::to_string(node_layer_num);
+                start_layer_str = std::to_string(node_layer_num) + ")";
                 end_x = " (" + std::to_string(node_xhigh(node)) + ","; //end coordinates have larger value
                 end_y = std::to_string(node_yhigh(node)) + ",";
                 end_layer_str = std::to_string(node_layer_num) + ")"; //layer number