Merge remote-tracking branch 'origin/add_enable_pin_counting_filter_option_to_recluster_util' into add_enable_pin_counting_filter_option_to_recluster_util

Author: KA7E

.github/workflows/containers.yml

@@ -1,12 +1,24 @@
 name: Containers
 
 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
   pull_request:
   workflow_dispatch:
   schedule:
   - cron: '0 0 * * 0' # weekly
 
+# 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
+
 jobs:
 
   Image:

.github/workflows/test.yml

@@ -1,12 +1,24 @@
 name: Test
 
 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
   pull_request:
   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"
@@ -74,6 +86,9 @@ jobs:
         NUM_CORES: ${{ matrix.cores }}
 
     - 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

.gitmodules

@@ -3,5 +3,4 @@
 	url = https://github.com/catchorg/Catch2.git
 [submodule "libs/EXTERNAL/sockpp"]
 	path = libs/EXTERNAL/sockpp
-	#url = git@github.com:fpagliughi/sockpp.git
-	url = git@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
+	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

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",

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.
@@ -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",

doc/src/vpr/command_line_usage.rst

@@ -360,11 +360,11 @@ Use the options below to override this default naming behaviour.
 
 .. option:: --read_vpr_constraints <file>
 
-    Reads the :ref:`floorplanning constraints <vpr_constraints_file>` that packing and placement must respect from the specified XML file.
+    Reads the :ref:`VPR constraints <vpr_constraints>` that the flow must respect from the specified XML file.
 
 .. option:: --write_vpr_constraints <file>
 
-    Writes out new :ref:`floorplanning constraints <vpr_constraints_file>` based on current placement to the specified XML file.
+    Writes out new :ref:`floorplanning constraints <placement_constraints>` based on the current placement to the specified XML file.
 
 .. option:: --read_router_lookahead <file>
 

doc/src/vpr/global_routing_constraints.rst

@@ -0,0 +1,108 @@
+Global Routing Constraints
+==========================
+.. _global_routing_constraints:
+
+VPR allows users to designate specific nets in the input netlist as global and define the routing model for the global nets by utilizing a VPR constraints XML file. These routing constraints for global nets are specified inside the VPR constraints file in XML format, as described in the following section.  
+
+A Global Routing Constraints File Example
+------------------------------------------
+
+.. code-block:: xml
+    :caption: An example of a global routing constraints file in XML format.
+    :linenos:
+
+    <vpr_constraints tool_name="vpr">
+        <global_route_constraints>
+            <set_global_signal name="clock*" route_model="dedicated_network" network_name="clock_network"/>
+        </global_route_constraints>
+    </vpr_constraints>
+
+
+Global Routing Constraints File Format
+---------------------------------------
+.. _global_routing_constraints_file_format:
+
+.. vpr_constraints:tag:: <global_route_constraints>content</global_route_constraints>
+
+    Content inside this tag contains a group of ``<set_global_signal>`` tags that specify the global nets and their assigned routing methods.
+
+.. vpr_constraints:tag:: <set_global_signal name="string" route_model="{ideal|route|dedicated_network}" network_name="string"/>
+
+    :req_param name: The name of the net to be assigned as global. Regular expressions are also accepted. 
+    :req_param route_model: The route model for the specified net.
+       
+        * ``ideal``: The net is not routed. There would be no delay for the global net. 
+
+        * ``route``: The net is routed similarly to other nets using generic routing resources.
+
+        * ``dedicated_network``: The net will be routed through a dedicated clock network.
+
+    :req_param network_name: The name of the clock network through which the net is routed. This parameter is required when ``route_model="dedicated_network"``.
+
+
+Dedicated Clock Networks
+--------------------------
+
+Users can define a clock architecture in two ways. First, through the architecture description outlined in section :ref:`Clocks <clock_architecture>`. By using the ``<clocknetworks>`` tag, users can establish a single clock architecture with the fixed default name "clock_network". When routing a net through the dedicated network described with this tag, the network name must be set to ``"clock_network"``.
+
+Alternatively, users can define a custom clock network architecture by inputting a custom resource routing graph. In this approach, users can specify various clock routing networks, such as a global clock network and multiple regional clock networks.  There are three main considerations for defining a clock network through a custom RR graph definition, as described in the following sections.
+
+Virtual Sinks Definition for Clock Networks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For VPR to route global nets within defined clock networks, there needs to be a virtual sink node defined in the RR graph per each clock network. This virtual sink, which is of the type ``"SINK"``, must have incoming edges from all drive points of the clock network. The two-stage router used for global net routing will initially route to the virtual sink (which serves as the entry point of the clock network) in the first stage and then from the entry point to the actual sink of the net in the second stage.
+
+To indicate that a node represents a clock network virtual sink, users can utilize the ``"clk_res_type"`` attribute on a node setting it to ``"VIRTUAL_SINK"``.
+
+Distinguishing Between Clock Networks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Given the support for multiple clock networks, VPR needs a way to distinguish between different virtual sinks belonging to various clock networks. This is achieved through the optional ``"name"`` attribute for the rr_node, accepting a string used as the clock network name. Therefore, when the ``"clk_res_type"`` is set to  ``"VIRTUAL_SINK"``, the attribute ``"name"`` becomes a requried parameter to enable VPR to determine which clock network the virtual sink belongs to. 
+
+When specifying the network_name in a global routing constraints file for routing a global net through a desired clock network, as described in the :ref:`above <global_routing_constraints_file_format>` section, the name defined as an attribute in the virtual sink of the clock network should be used to reference that clock network.
+
+Segment Definition for Clock Networks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The node types ``"CHANX"`` and ``"CHANY"`` can construct the clock routing architecture, similar to a generic routing network. However, to identify nodes that are part of a clock network, one can define unique segments for clock networks. To indicate that a segment defined is a clock network resource, users can use the optional attribute ``res_type="GCLK"``. Therefore, nodes with a segment ID of this defined segment are considered to be part of a clock network.
+
+While VPR currently does not leverage this distinction of clock network resources, it is recommended to use the ``res_type="GCLK"`` attribute, as this preparation ensures compatibility for future support.
+
+
+Example of RR Graph Definition for Clock Networks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Below are snapshots of a sample RR graph that illustrate how to define a clock network. This example demonstrates the definition of a virtual sink node, a clock network segment, and a CHANY node that is part of the clock network. 
+
+For the node with ``id="12746"``, the ``res_type="VIRTUAL_SINK"`` attribute marks it as the virtual sink node of a clock network named ``"global_network"``, as specified by the ``name`` attribute.
+
+For the segment with ``id="1"``, the ``res_type="GCLK"`` attribute indicates that this segment is a clock network resource.
+
+The ``"CHANY"`` node with the ``id="12746"`` has ``segment_id="1"``, which means this resource belongs to the clock network.
+
+.. code-block:: xml
+    :caption: Example snippets from an RR graph describing part of a clock network.
+    :linenos:
+
+        <rr_nodes>
+            <!-- Definition of a virtual sink node for a clock network named "global_network" -->
+            <node capacity="1" clk_res_type="VIRTUAL_SINK" id="12746" name="global_network" type="SINK">
+                <loc layer="0" ptc="72" xhigh="6" xlow="6" yhigh="6" ylow="6"/>
+                <timing C="0" R="0"/>
+            </node>
+
+            <!-- Definition of a CHANY node as part of the clock network -->
+            <node capacity="1" direction="BI_DIR" id="12668" type="CHANY">
+                <loc layer="0" ptc="20" xhigh="6" xlow="6" yhigh="6" ylow="6"/>
+                <timing C="1.98240038e-13" R="50.4199982"/>
+                <segment segment_id="1"/>
+            </node>
+            
+            <!-- ... other nodes ... -->
+        </rr_nodes>
+
+        <segments>
+            <!-- Definition of a clock network segment -->
+            <segment id="1" name="spine1_drive" res_type="GCLK">
+                <timing C_per_meter="2.06999995e-14" R_per_meter="50.4199982"/>
+            </segment>
+
+            <!-- ... other segments ... -->
+        </segments>

doc/src/vpr/index.rst

@@ -55,7 +55,7 @@ The purpose of VPR is to make the packing, placement, and routing stages of the
    graphics
 
    timing_constraints
-   placement_constraints
+   vpr_constraints
    sdc_commands
 
    file_formats