Merge pull request verilog-to-routing#2446 from verilog-to-routing/ro…

…uting_constraints Global Nets Routing constraints
SymbiFlow · Jun 4, 2024 · 7c79bb1 · 7c79bb1
2 parents 95555a8 + 32983bc
commit 7c79bb1
Show file tree

Hide file tree

Showing 62 changed files with 2,916 additions and 1,232 deletions.
diff --git a/dev/pylint_check.py b/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",

diff --git a/doc/_exts/constraintsdomain/__init__.py b/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"]),
+                    ],
+                ),
+            ),
+        )
+    )
diff --git a/doc/src/arch/reference.rst b/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:
 

diff --git a/doc/src/conf.py b/doc/src/conf.py
@@ -45,6 +45,7 @@
     "sphinx_markdown_tables",
     "sdcdomain",
     "archdomain",
+    "constraintsdomain",
     "rrgraphdomain",
     "myst_parser",
     "sphinx.ext.autodoc",

diff --git a/doc/src/vpr/command_line_usage.rst b/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>
 

diff --git a/doc/src/vpr/global_routing_constraints.rst b/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>
diff --git a/doc/src/vpr/index.rst b/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

diff --git a/doc/src/vpr/placement_constraints.rst b/doc/src/vpr/placement_constraints.rst
@@ -1,39 +1,40 @@
 
-VPR Placement Constraints
-=========================
-.. _vpr_constraints_file:
+Placement Constraints
+======================
+.. _placement_constraints:
+
 VPR supports running flows with placement constraints. Placement constraints are set on primitives to lock them down to specified regions on the FPGA chip. For example, a user may use placement constraints to lock down pins to specific locations on the chip. Also, groups of primitives may be locked down to regions on the chip in CAD flows that use floorplanning or modular design, or to hand-place a timing critical piece.
 
 The placement constraints should be specified by the user using an XML constraints file format, as described in the section below. When VPR is run with placement constraints, both the packing and placement flows are performed in such a way that the constraints are respected. The packing stage does not pack any primitives together that have conflicting floorplan constraints. The placement stage considers the floorplan constraints when choosing a location for each clustered block during initial placement, and does not move any block outside of its constraint boundaries during place moves.
 
-A Constraints File Example
---------------------------
+A Placement Constraints File Example
+------------------------------------
 
 .. code-block:: xml
 	:caption: An example of a placement constraints file in XML format.
 	:linenos:
 
 	<vpr_constraints tool_name="vpr">
-     		<partition_list>
-	  	<partition name="Part0">
-	       		<add_atom name_pattern="li354"/>
-	       		<add_atom name_pattern="alu*"/> <!-- Regular expressions can be used to provide name patterns of the primitives to be added -->
-	       		<add_atom name_pattern="n877"/>
-	      		 <add_region x_low="3" y_low="1" x_high="7" y_high="2"/> <!-- Two rectangular regions are specified, together describing an L-shaped region -->
-	       		<add_region x_low="7" y_low="3" x_high="7" y_high="6"/>
-	  	 </partition>
-	 	 <partition name="Part1">
-	       		<add_region x_low="3" y_low="3" x_high="7" y_high="7" subtile="0"/> <!-- One specific location is specified -->
-	       		<add_atom name_pattern="n4917"/>
-	      		<add_atom name_pattern="n6010"/>
-	  	</partition>
-     		</partition_list>
+		<partition_list>
+			<partition name="Part0">
+					<add_atom name_pattern="li354"/>
+					<add_atom name_pattern="alu*"/> <!-- Regular expressions can be used to provide name patterns of the primitives to be added -->
+					<add_atom name_pattern="n877"/>
+					<add_region x_low="3" y_low="1" x_high="7" y_high="2"/> <!-- Two rectangular regions are specified, together describing an L-shaped region -->
+					<add_region x_low="7" y_low="3" x_high="7" y_high="6"/>
+			</partition>
+			<partition name="Part1">
+					<add_region x_low="3" y_low="3" x_high="7" y_high="7" subtile="0"/> <!-- One specific location is specified -->
+					<add_atom name_pattern="n4917"/>
+					<add_atom name_pattern="n6010"/>
+			</partition>
+		</partition_list>
 	</vpr_constraints>
 
 .. _end:
 
-Constraints File Format
------------------------
+Placement Constraints File Format
+---------------------------------
 
 VPR has a specific XML format which must be used when creating a placement constraints file. The purpose of this constraints file is to specify 
 
@@ -42,9 +43,7 @@ VPR has a specific XML format which must be used when creating a placement const
 
 The file is passed as an input to VPR when running with placement constraints. When the file is read in, its information is used during the packing and placement stages of VPR. The hierarchy of the file is set up as follows.
 
-.. note:: Use the VPR option :vpr:option:`--read_vpr_constraints` to specify the VPR placement constraints file that is to be loaded. 
-
-The top level tag is the ``<vpr_constraints>`` tag. This tag contains one ``<partition_list>`` tag. The ``<partition_list>`` tag can be made up of an unbounded number of ``<partition>`` tags. The ``<partition>`` tags contains all of the detailed information of the placement constraints, and is described in detail below.
+The top level tag is the ``<vpr_constraints>`` tag. This tag can contain one ``<partition_list>`` tag. The ``<partition_list>`` tag can be made up of an unbounded number of ``<partition>`` tags. The ``<partition>`` tags contains all of the detailed information of the placement constraints, and is described in detail below.
 
 Partitions, Atoms, and Regions
 ------------------------------

diff --git a/doc/src/vpr/vpr_constraints.rst b/doc/src/vpr/vpr_constraints.rst
@@ -0,0 +1,32 @@
+VPR Constraints
+=========================
+.. _vpr_constraints:
+
+VPR allows users to run the flow with placement constraints that enable primitives to be locked down to a specific region on the chip and global routing constraints that facilitate the routing of global nets through clock networks.
+
+Users can specify these constraints through a constraints file in XML format, as shown in the format below.
+
+.. code-block:: xml
+   :caption: The overall format of a VPR constraints file
+   :linenos:
+
+   <vpr_constraints tool_name="vpr">
+       <partition_list>
+         <!-- Placement constraints are specified inside this tag -->
+       </partition_list>
+       <global_route_constraints>
+         <!-- Global routing constraints are specified inside this tag -->
+       </global_route_constraints>
+   </vpr_constraints>
+
+.. note:: Use the VPR option :option:`vpr --read_vpr_constraints` to specify the VPR constraints file that is to be loaded.
+
+The top-level tag is the ``<vpr_constraints>`` tag. This tag can contain ``<partition_list>`` and ``<global_route_constraints>`` tags. The ``<partition_list>`` tag contains information related to placement constraints, while ``<global_route_constraints>`` contains information about global routing constraints. The details for each of these constraints are given in the respective sections :ref:`Placement Constraints <placement_constraints>` and :ref:`Global Route Constraints <global_routing_constraints>`.
+
+.. toctree::
+   :maxdepth: 2
+
+   placement_constraints
+   global_routing_constraints
+
+
diff --git a/libs/libarchfpga/src/physical_types.h b/libs/libarchfpga/src/physical_types.h
@@ -1509,6 +1509,22 @@ enum e_parallel_axis {
     Y_AXIS,
     BOTH_AXIS
 };
+
+/**
+ * @brief An attribute of a segment that defines the general category of the wire segment type.
+ *
+ * @details
+ * - `GCLK`: A segment type that is part of the global routing network for clocks.
+ * - `GENERAL`: Describes a segment type that is part of the regular routing network.
+ */
+enum class SegResType {
+    GCLK = 0,
+    GENERAL = 1,
+    NUM_RES_TYPES
+};
+
+constexpr std::array<const char*, static_cast<size_t>(SegResType::NUM_RES_TYPES)> RES_TYPE_STRING = {{"GCLK", "GENERAL"}}; //String versions of segment resource types
+
 enum e_switch_block_type {
     SUBSET,
     WILTON,
@@ -1561,6 +1577,14 @@ enum e_Fc_type {
  *            the segment's index in the unified segment_inf vector. This is *
  *            useful when building the rr_graph for different Y & X channels *
  *            in terms of track distribution and segment type.                *
+ * res_type: Determines the routing network to which the segment belongs.    *
+ *           Possible values are:
+ *              - GENERAL: The segment is part of the general routing        *
+ *                         resources.                                        *
+ *              - GCLK: The segment is part of the global routing network.   *
+ *           For backward compatibility, this attribute is optional. If not  *
+ *           specified, the resource type for the segment is considered to   *
+ *           be GENERAL.                                                     *
  * meta: Table storing extra arbitrary metadata attributes.                  */
 struct t_segment_inf {
     std::string name;
@@ -1579,6 +1603,7 @@ struct t_segment_inf {
     std::vector<bool> cb;
     std::vector<bool> sb;
     int seg_index;
+    enum SegResType res_type = SegResType::GENERAL;
     //float Cmetal_per_m; /* Wire capacitance (per meter) */
 };
 
@@ -2014,6 +2039,7 @@ struct t_arch {
 
     std::string gnd_net = "$__gnd_net";
     std::string vcc_net = "$__vcc_net";
+    std::string default_clock_network_name = "clock_network";
 
     // Luts
     std::vector<t_lut_cell> lut_cells;