Merge branch 'master' into ipa_end_user_doc

Author: w0lek

.github/workflows/containers.yml

@@ -16,7 +16,7 @@ jobs:
     steps:
 
       - name: 🧰 Repository Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: 'true'
 

.github/workflows/labeler.yml

@@ -6,7 +6,7 @@ jobs:
   triage:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/labeler@master
       with:
         repo-token: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/test.yml

@@ -51,6 +51,8 @@ jobs:
 
     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'
@@ -71,9 +73,15 @@ jobs:
         VTR_CMAKE_PARAMS: ${{ matrix.cmake }}
         NUM_CORES: ${{ matrix.cores }}
 
-    - uses: actions/upload-artifact@v3
+    - name: Upload test results
+      # We always want the test results to be uploaded, even when cancelled.
+      # https://docs.github.com/en/actions/learn-github-actions/expressions#always
       if: ${{ always() }}
+      # 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
@@ -92,10 +100,10 @@ jobs:
         - { build_type: 'debug',   verbose: '1' }
     steps:
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: 3.10.10
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: 'true'
     - run: ./.github/scripts/install_dependencies.sh
@@ -122,10 +130,10 @@ jobs:
     name: 'F: ${{ matrix.name }}'
     steps:
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: 3.10.10
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - run: ./.github/scripts/install_dependencies.sh
 
     - name: Test
@@ -137,10 +145,10 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: 3.10.10
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: 'true'
     - run: ./.github/scripts/install_dependencies.sh
@@ -156,10 +164,10 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: 3.10.10
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: 'true'
     - run: ./.github/scripts/install_dependencies.sh
@@ -236,10 +244,10 @@ jobs:
     name: 'R: ${{ matrix.name }}'
     steps:
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: 3.10.10
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: 'true'
     - run: ./.github/scripts/install_dependencies.sh
@@ -255,7 +263,7 @@ jobs:
         ./run_reg_test.py ${{ matrix.suite }} -show_failures -j2
 
     - name: Upload regression run files
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: ${{matrix.name}}_run_files
         path: |
@@ -266,7 +274,7 @@ jobs:
           vtr_flow/**/*.r
 
     - name: Upload regression results
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: ${{matrix.name}}_results
         path: |
@@ -291,10 +299,10 @@ jobs:
     name: 'S: ${{ matrix.name }}'
     steps:
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: 3.10.10
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: 'true'
 
@@ -325,10 +333,10 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
 
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.10.10
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: 'true'
       - run: ./.github/scripts/install_dependencies.sh
@@ -350,10 +358,10 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: 3.10.10
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: 'true'
     - run: ./.github/scripts/install_dependencies.sh
@@ -376,10 +384,10 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: 3.10.10
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: 'true'
     - run: ./.github/scripts/install_dependencies.sh
@@ -411,10 +419,10 @@ jobs:
     name: 'B: ${{ matrix.name }}'
     steps:
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: 3.10.10
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: 'true'
     - run: ./.github/scripts/install_dependencies.sh
@@ -447,10 +455,10 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: 3.10.10
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
         submodules: 'true'
     - run: ./.github/scripts/install_dependencies.sh

.gitmodules

@@ -3,5 +3,4 @@
 	url = https://github.com/catchorg/Catch2.git
 [submodule "libs/EXTERNAL/sockpp"]
 	path = libs/EXTERNAL/sockpp
-	#url = [email protected]:fpagliughi/sockpp.git
-	url = [email protected]:w0lek/sockpp.git # fork where in branch v1.0.0_no_complication_warnings there are compilation warnings fixes for upstream tag v1.0.0 of sockpp
+	url = https://github.com/w0lek/sockpp.git # fork where in branch v1.0.0_no_complication_warnings there are compilation warnings fixes for upstream tag v1.0.0 of sockpp

README.developers.md

@@ -1330,7 +1330,7 @@ Instead changes should be made in the relevant up-stream repository, and then sy
 
     For example to update the `libtatum` subtree:
     ```shell
-    ./dev/external_subtrees.py --update libtatum
+    ./dev/external_subtrees.py --update libtatum -m "commit message describing why component is being updated"
     ```
 
 ## Adding a new Subtree
@@ -1372,8 +1372,66 @@ To add a new external subtree to VTR do the following:
     This will create two commits to the repository.
     The first will squash all the upstream changes, the second will merge those changes into the current branch.
 
+## Pushing VTR Changes Back to Upstream Subtree
 
-## Subtree Rational
+If there are changes in the VTR repo in a subtree that should be merged back
+into the source repo of the subtree, the changes can be pushed back manually.
+
+The instructions above used a Python script to simplify updating subtrees in
+VTR. This is fine for pulling in changes from a remote repo; however, it is not
+good for pushing changes back. This is because these changes need to be pushed
+somewhere, and it is not a good idea to just push it back to the master branch
+directly. Instead, it should be pushed to a temporary branch. Then a PR can be
+made to bring the changes into the target repo.
+
+To push changes VTR made to a subtree do the following:
+
+1. Create a fork of the target repo. Optionally you can create a branch to be
+   the target of the push, or you can just use master.
+
+2. Run:
+   ```shell
+   cd $VTR_ROOT
+   git subtree push --prefix=<subtree_path> <forked_repo_url> <branch_name>
+   ```
+   The prefix is the internal path to the subtree, as written in
+   `dev/subtree_config.xml`.
+
+3. Create a PR from your forked repo to the main repo, sharing the amazing
+   changes with the world.
+
+## Tutorial: Syncing Tatum with VTR
+
+This tutorial will show you how to synchronize `libtatum` in VTR and
+[Tatum](https://github.com/verilog-to-routing/tatum); however, similar steps
+can be done to synchronize any subtree in VTR.
+
+First, we will pull in (update) any changes in Tatum that are not in VTR yet.
+On a clean branch (based off master), execute the following:
+```shell
+cd $VTR_ROOT
+./dev/external_subtrees.py --update libtatum -m "Pulling in changes from Tatum."
+```
+If the output in the terminal says `Subtree is already at commit <commit_hash>`,
+then there is nothing to pull in. If it says changes were pulled in, a commit
+would have already been made for you. Push these changes to your branch and
+raise a PR on VTR to merge these changes in.
+
+After pulling in all the changes from Tatum, without changing branches, we will
+push our VTR changes to Tatum. This is a bit more complicated since, as stated
+in the section on pushing to subtrees, the changes cannot just be pushed to
+master.
+
+Create a fork of Tatum and make sure the master branch of that fork is
+synchronized with Tatum's master branch. Then execute the following:
+```shell
+cd $VTR_ROOT
+git subtree push --prefix=libs/EXTERNAL/libtatum <forked_repo_url> master
+```
+After that command finishes, raise a PR from your forked repo onto the Tatum
+repo for the changes to be reviewed and merged in.
+
+## Subtree Rationale
 
 VTR uses subtrees to allow easy tracking of upstream dependencies.
 
@@ -1469,4 +1527,5 @@ The following outlines the procedure to following when making an official VTR re
  * GitHub will automatically create a release based on the tag
  * Add the new change log entry to the [GitHub release description](https://github.com/verilog-to-routing/vtr-verilog-to-routing/releases)
  * Update the [ReadTheDocs configuration](https://readthedocs.org/projects/vtr/versions/) to build and serve documentation for the relevant tag (e.g. `v8.0.0`)
- * Send a release announcement email to the [vtr-announce](mailto:[email protected]) mailing list (make sure to thank all contributors!)
+ * Send a release announcement email to the [vtr-announce](mailto:[email protected]) mailing list (make sure to thank all contributors!)
+

dev/pylint_check.py

@@ -60,6 +60,7 @@
     repo_path / "doc/_exts/rrgraphdomain/__init__.py",
     repo_path / "doc/_exts/sdcdomain/__init__.py",
     repo_path / "doc/_exts/archdomain/__init__.py",
+    repo_path / "doc/_exts/constraintsdomain/__init__.py",
     repo_path / "vpr/scripts/compare_timing_reports.py",
     repo_path / "vpr/scripts/profile/util.py",
     repo_path / "vpr/scripts/profile/parse_and_plot_detailed.py",

dev/subtree_config.xml

@@ -33,7 +33,7 @@
         name="capnproto"
         internal_path="libs/EXTERNAL/capnproto"
         external_url="https://github.com/capnproto/capnproto.git"
-        default_external_ref="v0.9.1"/>
+        default_external_ref="v1.0.2"/>
     <subtree
         name="libinterchange"
         internal_path="libs/EXTERNAL/libinterchange"

doc/_exts/constraintsdomain/__init__.py

@@ -0,0 +1,27 @@
+from sphinxcontrib.domaintools import custom_domain
+from sphinx.util.docfields import *
+
+
+def setup(app):
+    app.add_domain(
+        custom_domain(
+            "VPRConstraintsDomain",
+            name="vpr_constraints",
+            label="Place and Route Constraints",
+            elements=dict(
+                tag=dict(
+                    objname="Attribute",
+                    indextemplate="pair: %s; Tag Attribute",
+                    fields=[
+                        GroupedField(
+                            "required_parameter", label="Required Attributes", names=["req_param"]
+                        ),
+                        GroupedField(
+                            "optional_parameter", label="Optional Attributes", names=["opt_param"]
+                        ),
+                        Field("required", label="Tag Required", names=["required"]),
+                    ],
+                ),
+            ),
+        )
+    )

doc/src/arch/reference.rst

@@ -1955,7 +1955,7 @@ Wire Segments
 The content within the ``<segmentlist>`` tag consists of a group of ``<segment>`` tags.
 The ``<segment>`` tag and its contents are described below.
 
-.. arch:tag:: <segment axis="{x|y}" name="unique_name" length="int" type="{bidir|unidir}" freq="float" Rmetal="float" Cmetal="float">content</segment>
+.. arch:tag:: <segment axis="{x|y}" name="unique_name" length="int" type="{bidir|unidir}" res_type="{GCLK|GENERAL}" freq="float" Rmetal="float" Cmetal="float">content</segment>
 
 
     :opt_param axis:
@@ -1975,6 +1975,10 @@ The ``<segment>`` tag and its contents are described below.
 
         .. note:: ``longline`` is only supported on with ``bidir`` routing
 
+    :opt_param res_type:
+        Specifies whether the segment belongs to the general or a clock routing network. If this tag is not specified, the resource type for
+        the segment is considered to be GENERAL (i.e. regular routing).
+  
     :req_param freq:
         The supply of routing tracks composed of this type of segment.
         VPR automatically determines the percentage of tracks for each segment type by taking the frequency for the type specified and dividing with the sum of all frequencies.
@@ -2026,15 +2030,15 @@ 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.
+    :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.
 
     .. 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:: <wire_switch name="string"/>
 
-    :req_param name: Name of the switch type used by other wires to drive this type of segment.
+    :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.
 
     .. note:: For BIDIRECTIONAL only.
 
@@ -2092,6 +2096,7 @@ Specifing a Clock Architecture
 
 The element ``<clocknetworks>`` contains three sub-elements that collectively describe the clock architecture: the wiring parameters ``<metal_layers>``, the clock distribution ``<clock_network>``, and the clock connectivity ``<clock_routing>``.
 
+    .. note:: The clock network architecture defined in this structure is assigned the fixed default name ``"clock_network"``. When the user wants to specify a net to be routed through the defined clock architecture using a :ref:`global routing constraints file <global_routing_constraints>`, the network name attribute in the constraint tag must be set to ``"clock_network"``.
 
 .. _clock_arch_example:
 

doc/src/conf.py

@@ -45,6 +45,7 @@
     "sphinx_markdown_tables",
     "sdcdomain",
     "archdomain",
+    "constraintsdomain",
     "rrgraphdomain",
     "myst_parser",
     "sphinx.ext.autodoc",