Merge branch 'master' into openfpga

verilog-to-routing · Jul 30, 2024 · 51bd666 · 51bd666
2 parents 9eef18c + 36ed2b2
commit 51bd666
Show file tree

Hide file tree

Showing 164 changed files with 245,081 additions and 7,543 deletions.
diff --git a/.github/workflows/nightly_test.yml b/.github/workflows/nightly_test.yml
@@ -0,0 +1,110 @@
+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
+
+# We want to cancel previous runs for a given PR or branch / ref if another CI
+# run is requested.
+# See: https://docs.github.com/en/actions/using-jobs/using-concurrency
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  # default compiler for all non-compatibility tests
+  MATRIX_EVAL: "CC=gcc-11 && CXX=g++-11"
+
+jobs:
+  Run-tests:
+    # Prevents from running on forks where no custom runners are available
+    if: ${{ github.repository_owner == 'verilog-to-routing' }}
+
+    timeout-minutes: 420
+
+    container: ubuntu:jammy
+
+    runs-on: [self-hosted, Linux, X64]
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {test: "vtr_reg_nightly_test1",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
+          - {test: "vtr_reg_nightly_test1_odin", cores: "16", options: "",          cmake: "-DWITH_ODIN=ON",                                               extra_pkgs: ""}
+          - {test: "vtr_reg_nightly_test2",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
+          - {test: "vtr_reg_nightly_test2_odin", cores: "16", options: "",          cmake: "-DWITH_ODIN=ON",                                               extra_pkgs: ""}
+          - {test: "vtr_reg_nightly_test3",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
+          - {test: "vtr_reg_nightly_test3_odin", cores: "16", options: "",          cmake: "-DWITH_ODIN=ON",                                               extra_pkgs: ""}
+          - {test: "vtr_reg_nightly_test4",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
+          - {test: "vtr_reg_nightly_test4_odin", cores: "16", options: "",          cmake: "-DWITH_ODIN=ON",                                               extra_pkgs: ""}
+          - {test: "vtr_reg_nightly_test5",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
+          - {test: "vtr_reg_nightly_test6",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
+          - {test: "vtr_reg_nightly_test7",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
+          - {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=ON",                                     extra_pkgs: ""}
+
+    env:
+      DEBIAN_FRONTEND: "noninteractive"
+
+    steps:
+
+      # TODO: This runnner is running on a self-hosted CPU. In order to upgrade
+      #       to v4, need to upgrade the machine to support node20.
+    - uses: actions/checkout@v3
+      with:
+        submodules: 'true'
+
+    - name: Setup
+      run: stdbuf -i0 -i0 -e0 ./.github/scripts/hostsetup.sh
+
+    - name: Install external libraries
+      run: apt install -y ${{ matrix.extra_pkgs }}
+      if: ${{ matrix.extra_pkgs }}
+
+    - name: Execute test script
+      run: stdbuf -i0 -o0 -e0 ./.github/scripts/run-vtr.sh
+      env:
+        VPR_NUM_WORKERS: 4
+        VTR_TEST: ${{ matrix.test }}
+        VTR_TEST_OPTIONS: ${{ matrix.options }}
+        VTR_CMAKE_PARAMS: ${{ matrix.cmake }}
+        NUM_CORES: ${{ matrix.cores }}
+
+    - name: Upload test results
+      # If the job was not cancelled, we want to save the result (this includes
+      # when the job fails). See warning here:
+      # https://docs.github.com/en/actions/learn-github-actions/expressions#always
+      if: ${{ !cancelled() }}
+      # TODO: This runnner is running on a self-hosted CPU. In order to upgrade
+      #       to v4, need to upgrade the machine to support node20.
+      uses: actions/upload-artifact@v3
+      with:
+        name: ${{matrix.test}}_test_results
+        path: |
+          **/results*.gz
+          **/plot_*.svg
+          **/qor_results*.tar.gz
+
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -34,83 +34,6 @@ env:
   MATRIX_EVAL: "CC=gcc-11 && CXX=g++-11"
 
 jobs:
-
-
-  Run-tests:
-    # Prevents from running on forks where no custom runners are available
-    if: ${{ github.repository_owner == 'verilog-to-routing' }}
-
-    timeout-minutes: 420
-
-    container: ubuntu:jammy
-
-    runs-on: [self-hosted, Linux, X64]
-
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - {test: "vtr_reg_nightly_test1",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
-          - {test: "vtr_reg_nightly_test1_odin", cores: "16", options: "",          cmake: "-DWITH_ODIN=ON",                                               extra_pkgs: ""}
-          - {test: "vtr_reg_nightly_test2",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
-          - {test: "vtr_reg_nightly_test2_odin", cores: "16", options: "",          cmake: "-DWITH_ODIN=ON",                                               extra_pkgs: ""}
-          - {test: "vtr_reg_nightly_test3",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
-          - {test: "vtr_reg_nightly_test3_odin", cores: "16", options: "",          cmake: "-DWITH_ODIN=ON",                                               extra_pkgs: ""}
-          - {test: "vtr_reg_nightly_test4",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
-          - {test: "vtr_reg_nightly_test4_odin", cores: "16", options: "",          cmake: "-DWITH_ODIN=ON",                                               extra_pkgs: ""}
-          - {test: "vtr_reg_nightly_test5",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
-          - {test: "vtr_reg_nightly_test6",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
-          - {test: "vtr_reg_nightly_test7",      cores: "16", options: "",          cmake: "",                                                             extra_pkgs: ""}
-          - {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=ON",                                     extra_pkgs: ""}
-
-    env:
-      DEBIAN_FRONTEND: "noninteractive"
-
-    steps:
-
-      # TODO: This runnner is running on a self-hosted CPU. In order to upgrade
-      #       to v4, need to upgrade the machine to support node20.
-    - uses: actions/checkout@v3
-      with:
-        submodules: 'true'
-
-    - name: Setup
-      run: stdbuf -i0 -i0 -e0 ./.github/scripts/hostsetup.sh
-
-    - name: Install external libraries
-      run: apt install -y ${{ matrix.extra_pkgs }}
-      if: ${{ matrix.extra_pkgs }}
-
-    - name: Execute test script
-      run: stdbuf -i0 -o0 -e0 ./.github/scripts/run-vtr.sh
-      env:
-        VPR_NUM_WORKERS: 4
-        VTR_TEST: ${{ matrix.test }}
-        VTR_TEST_OPTIONS: ${{ matrix.options }}
-        VTR_CMAKE_PARAMS: ${{ matrix.cmake }}
-        NUM_CORES: ${{ matrix.cores }}
-
-    - name: Upload test results
-      # If the job was not cancelled, we want to save the result (this includes
-      # when the job fails). See warning here:
-      # https://docs.github.com/en/actions/learn-github-actions/expressions#always
-      if: ${{ !cancelled() }}
-      # TODO: This runnner is running on a self-hosted CPU. In order to upgrade
-      #       to v4, need to upgrade the machine to support node20.
-      uses: actions/upload-artifact@v3
-      with:
-        name: ${{matrix.test}}_test_results
-        path: |
-          **/results*.gz
-          **/plot_*.svg
-          **/qor_results*.tar.gz
-
-
   Build:
     name: 'B: Building VtR'
     runs-on: ubuntu-22.04

diff --git a/BUILDING.md b/BUILDING.md
@@ -46,7 +46,7 @@ If you download a different version of those tools, then those versions may not
 
 To verfiy that VTR has been installed correctly run::
 
-    ./vtr_flow/scripts/run_vtr_task.py regression_tests/vtr_reg_basic/basic_timing
+    ./vtr_flow/scripts/run_vtr_task.py ./vtr_flow/tasks/regression_tests/vtr_reg_basic/basic_timing
 
 The expected output is::
 

diff --git a/README.developers.md b/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).

diff --git a/doc/src/api/vpr/grid.rst b/doc/src/api/vpr/grid.rst
@@ -0,0 +1,10 @@
+========
+Grid
+========
+
+DeviceGrid
+-------
+
+.. doxygenclass:: DeviceGrid
+   :project: vpr
+   :members:
diff --git a/doc/src/api/vpr/index.rst b/doc/src/api/vpr/index.rst
@@ -7,6 +7,7 @@ VPR API
    :maxdepth: 1
 
    contexts
+   grid
    mapping
    netlist
    route_tree

diff --git a/doc/src/api/vpr/rr_graph.rst b/doc/src/api/vpr/rr_graph.rst
@@ -35,3 +35,9 @@ RRSpatialLookup
    :project: librrgraph
    :members:
 
+rr_graph_utils
+---------------
+
+.. doxygenfile:: rr_graph_utils.h
+   :project: librrgraph
+   :sections: briefdescription detaileddescription func prototype user-defined public-func
diff --git a/doc/src/api/vprinternals/router_lookahead.rst b/doc/src/api/vprinternals/router_lookahead.rst
@@ -0,0 +1,35 @@
+==============
+Router Lookahead
+==============
+
+e_router_lookahead
+----------
+.. doxygenenum:: e_router_lookahead
+   :project: vpr
+
+
+RouterLookahead
+----------
+.. doxygenclass:: RouterLookahead
+   :project: vpr
+   :members:
+
+MapLookahead
+----------
+.. doxygenclass:: MapLookahead
+   :project: vpr
+
+make_router_lookahead
+----------
+.. doxygenfunction:: make_router_lookahead
+   :project: vpr
+
+get_cached_router_lookahead
+----------
+.. doxygenfunction:: get_cached_router_lookahead
+   :project: vpr
+
+invalidate_router_lookahead_cache
+----------
+.. doxygenfunction:: invalidate_router_lookahead_cache
+   :project: vpr
diff --git a/doc/src/api/vprinternals/vpr_router.rst b/doc/src/api/vprinternals/vpr_router.rst
@@ -7,4 +7,5 @@ VPR Router
 .. toctree::
    :maxdepth: 1
 
-   router_heap
+   router_heap
+   router_lookahead