Adding Custom RR Graph Builder to OpenFPGA

.gitmodules

@@ -16,6 +16,9 @@
 [submodule "libs/EXTERNAL/yosys-slang"]
 	path = libs/EXTERNAL/yosys-slang
 	url = https://github.com/povik/yosys-slang.git
+[submodule "libs/EXTERNAL/yaml-cpp"]
+	path = libs/EXTERNAL/yaml-cpp
+	url = https://github.com/jbeder/yaml-cpp.git
 [submodule "libs/EXTERNAL/libsdcparse"]
 	path = libs/EXTERNAL/libsdcparse
 	url = https://github.com/verilog-to-routing/libsdcparse.git

doc/src/vpr/custom_rr_graph.rst

@@ -0,0 +1,102 @@
+.. _custom_rr_graph:
+
+Custom RR Graph
+===============
+
+For users who want more control over how connections are made in the routing resource graph, VPR provides a way to describe them through a Custom RR Graph (CRR) generator.
+
+Currently, the CRR Generator is only based on the tileable RR Graph. Support for the default VPR RR Graph Generator is in progress. To generate a CRR, the following files are required:
+
+* Switch block map file
+* Switch block template files
+
+Switch Block Map File
+~~~~~~~~~~~~~~~~~~~~~~
+
+This is a YAML file that specifies which switch block template should be used for each tile. The mapping format supports the following patterns:
+
+* ``SB_1__1_: [sb_template.csv]`` - Tile at location (1, 1) uses switch block template ``sb_template.csv``
+* ``SB_1__*_: [sb_template.csv]`` - All tiles with x coordinate 1 use switch block template ``sb_template.csv``
+* ``SB_[7,20]__[2:32:3]_: [sb_template.csv]`` - Tiles with x equal to 7 or 20, and y coordinates from 2 to 32 (inclusive) with step 3 use switch block template ``sb_template.csv``
+
+**Important:** The order in which patterns are defined matters, as the first matching pattern is used.
+
+Switch Block Template Files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Terminology
+-----------
+
+Before describing the template files, let's define some key terminology:
+
+**Lane:** A group of wires with the same length. The starting points of consecutive wires in a lane are one switch block apart.
+
+**Tap:** A switch block location where a wire passes through and can have fan-out connections.
+
+See the figure below for an illustration:
+
+.. figure:: images/lane_and_tap.png
+   :alt: Lane and Tap
+   :width: 50%
+   :align: center
+
+   In the figure above, the taps for the red wire are shown, and the lanes are separated by dotted lines. Note that the figure is simplified for illustration purposes.
+
+In the actual RR Graph, when a wire passes through a switch block, its track number changes. Below is a more realistic example:
+
+.. figure:: images/lane_and_tap_realistic.png
+   :alt: Lane and Tap Realistic
+   :width: 50%
+   :align: center
+
+   A more realistic example of a lane and a tap. Each box contains a lane.
+
+Template File Format
+--------------------
+
+There should be a directory containing the pattern files specified in the switch block maps file. Each template is a CSV file with the following format:
+
+* **Rows** represent source nodes
+* **Columns** represent sink nodes
+* An **'x' mark** at an intersection indicates that the source and sink nodes are connected
+* A **number** at an intersection indicates that the nodes are connected with the switch delay specified by that number
+
+**Note:** The pattern currently only supports uni-directional segments. Therefore, wires can only be driven from their starting point.
+
+Row Headers (Source Nodes)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each row has four header columns describing the source node:
+
+1. **Column 1 - Direction:** The side from which the source node is entering the switch block (e.g., 'left', 'right', 'top', 'bottom')
+2. **Column 2 - Segment Type:** The segment length to which the source node belongs
+3. **Column 3 - Lane Number:** The lane to which the source node belongs (see terminology above)
+4. **Column 4 - Tap Number:** Which tap of the source node is at this switch block
+
+Column Headers (Sink Nodes)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each column has header rows describing the sink node:
+
+1. **Row 1 - Direction:** The side from which the sink node is exiting the switch block
+2. **Row 2 - Segment Type:** The segment length to which the sink node belongs
+3. **Row 3 - Fan-in:** The fan-in of the sink node (optional)
+4. **Row 4 - Lane Number:** The lane to which the sink node belongs
+
+Example
+^^^^^^^
+
+Let’s consider an architecture with a channel width of 16 that contains only wire segments of length 4.
+
+The number of rows should be calculated as:
+
+- ``4`` (number of sides) × ``160/2`` (number of tracks in one direction) = ``320`` rows.
+
+On each side, there should be:
+
+- ``20`` lanes (``80 / 4``), and
+- each lane requires ``4`` rows (because length-4 wires require 4 tap positions).
+
+For the columns, the count should be:
+
+- ``4`` (number of sides) × ``160/2`` (number of tracks in one direction) ÷ ``4`` (number of starting tracks per lane) = ``80`` columns.

libs/EXTERNAL/CMakeLists.txt

@@ -12,6 +12,16 @@ add_subdirectory(libsdcparse)
 add_subdirectory(libblifparse)
 add_subdirectory(libtatum)
 add_subdirectory(libcatch2)
+
+add_subdirectory(yaml-cpp)
+# Treat yaml-cpp headers as system headers to suppress warnings
+if(TARGET yaml-cpp)
+    get_target_property(YAML_INCLUDE_DIRS yaml-cpp INTERFACE_INCLUDE_DIRECTORIES)
+    set_target_properties(yaml-cpp PROPERTIES
+        INTERFACE_SYSTEM_INCLUDE_DIRECTORIES "${YAML_INCLUDE_DIRS}"
+    )
+endif()
+
 #add_subdirectory(parmys)
 
 #Proc numbers

libs/librrgraph/src/base/rr_edge.h

@@ -1,20 +1,24 @@
 #pragma once
 
+#include <string>
+
 #include "physical_types.h"
 #include "librrgraph_types.h"
 #include "rr_graph_fwd.h"
 
 struct t_rr_edge_info {
-    t_rr_edge_info(RRNodeId from, RRNodeId to, short type, bool is_remapped) noexcept
+    t_rr_edge_info(RRNodeId from, RRNodeId to, short type, bool is_remapped, std::string crr_id_="") noexcept
         : from_node(from)
         , to_node(to)
         , switch_type(type)
-        , remapped(is_remapped) {}
+        , remapped(is_remapped)
+        , crr_id(std::move(crr_id_)) {}
 
     RRNodeId from_node = RRNodeId::INVALID();
     RRNodeId to_node = RRNodeId::INVALID();
     short switch_type = LIBRRGRAPH_UNDEFINED_VAL;
     bool remapped = false;
+    std::string crr_id = "";
 
     friend bool operator<(const t_rr_edge_info& lhs, const t_rr_edge_info& rhs) {
         VTR_ASSERT(lhs.remapped == rhs.remapped);

libs/librrgraph/src/base/rr_graph_builder.cpp

@@ -176,8 +176,8 @@ void RRGraphBuilder::reorder_nodes(e_rr_node_reorder_algorithm reorder_rr_graph_
     });
 }
 
-void RRGraphBuilder::create_edge_in_cache(RRNodeId src, RRNodeId dest, RRSwitchId edge_switch, bool remapped) {
-    edges_to_build_.emplace_back(src, dest, size_t(edge_switch), remapped);
+void RRGraphBuilder::create_edge_in_cache(RRNodeId src, RRNodeId dest, RRSwitchId edge_switch, bool remapped, std::string crr_id_) {
+    edges_to_build_.emplace_back(src, dest, size_t(edge_switch), remapped, std::move(crr_id_));
     is_edge_dirty_ = true; // Adding a new edge revokes the flag
     is_incoming_edge_dirty_ = true;
 }

libs/librrgraph/src/base/rr_graph_builder.h

@@ -12,6 +12,7 @@
  *
  */
 
+#include <string>
 #include "rr_graph_storage.h"
 #include "rr_spatial_lookup.h"
 #include "metadata_storage.h"
@@ -289,7 +290,7 @@ class RRGraphBuilder {
 
     /** @brief Add a new edge to the cache of edges to be built 
      *  @note This will not add an edge to storage. You need to call build_edges() after all the edges are cached. */
-    void create_edge_in_cache(RRNodeId src, RRNodeId dest, RRSwitchId edge_switch, bool remapped);
+    void create_edge_in_cache(RRNodeId src, RRNodeId dest, RRSwitchId edge_switch, bool remapped, std::string crr_id_="");
 
     /** @brief Add a new edge to the cache of edges to be built 
      *  @note This will not add an edge to storage! You need to call build_edges() after all the edges are cached! */
@@ -332,8 +333,8 @@ class RRGraphBuilder {
      * remap the arch switch id to rr switch id, the edge switch id of this edge shouldn't be changed. For example, when the intra-cluster graph
      * is built and the rr-graph related to global resources are read from a file, this parameter is true since the intra-cluster switches are
      * also listed in rr-graph file. So, we use that list to use the rr switch id instead of passing arch switch id for intra-cluster edges.*/
-    inline void emplace_back_edge(RRNodeId src, RRNodeId dest, short edge_switch, bool remapped) {
-        node_storage_.emplace_back_edge(src, dest, edge_switch, remapped);
+    inline void emplace_back_edge(RRNodeId src, RRNodeId dest, short edge_switch, bool remapped, std::string crr_id="") {
+        node_storage_.emplace_back_edge(src, dest, edge_switch, remapped, std::move(crr_id));
     }
     /** @brief Append 1 more RR node to the RR graph. */
     inline void emplace_back() {
@@ -401,6 +402,16 @@ class RRGraphBuilder {
         return node_storage_.count_rr_switches(arch_switch_inf, arch_switch_fanins);
     }
 
+    /**
+     * @brief Unlock storage; required to modify an routing resource graph after edge is read
+     * @note This function is used by OpenFPGA and currently doesn't have any use in VPR code.
+     */
+    inline void unlock_storage() {
+        node_storage_.edges_read_ = false;
+        node_storage_.partitioned_ = false;
+        node_storage_.clear_node_first_edge();
+    }
+
     /** @brief Reserve the lists of nodes, edges, switches etc. to be memory efficient.
      * This function is mainly used to reserve memory space inside RRGraph,
      * when adding a large number of nodes/edge/switches/segments,
@@ -420,7 +431,6 @@ class RRGraphBuilder {
         node_storage_.resize(size);
     }
 
-
     /** @brief This function resize rr_switch to accommodate size RR Switch. */
     inline void resize_switches(size_t size) {
         rr_switch_inf_.resize(size);

libs/librrgraph/src/base/rr_graph_storage.cpp

@@ -16,15 +16,17 @@ void t_rr_graph_storage::reserve_edges(size_t num_edges) {
     edge_dest_node_.reserve(num_edges);
     edge_switch_.reserve(num_edges);
     edge_remapped_.reserve(num_edges);
+    edge_crr_id_.reserve(num_edges);
 }
 
-void t_rr_graph_storage::emplace_back_edge(RRNodeId src, RRNodeId dest, short edge_switch, bool remapped) {
+void t_rr_graph_storage::emplace_back_edge(RRNodeId src, RRNodeId dest, short edge_switch, bool remapped, std::string crr_id) {
     // Cannot mutate edges once edges have been read!
     VTR_ASSERT(!edges_read_);
     edge_src_node_.emplace_back(src);
     edge_dest_node_.emplace_back(dest);
     edge_switch_.emplace_back(edge_switch);
     edge_remapped_.emplace_back(remapped);
+    edge_crr_id_.emplace_back(crr_id);
 }
 
 // Typical node to edge ratio.  This allows a preallocation guess for the edges
@@ -49,14 +51,16 @@ void t_rr_graph_storage::alloc_and_load_edges(const t_rr_edge_info_set* rr_edges
         edge_dest_node_.reserve(new_capacity);
         edge_switch_.reserve(new_capacity);
         edge_remapped_.reserve(new_capacity);
+        edge_crr_id_.reserve(new_capacity);
     }
 
     for (const t_rr_edge_info& new_edge : *rr_edges_to_create) {
         emplace_back_edge(
             new_edge.from_node,
             new_edge.to_node,
             new_edge.switch_type,
-            new_edge.remapped);
+            new_edge.remapped,
+            new_edge.crr_id);
     }
 }
 
@@ -87,6 +91,7 @@ void t_rr_graph_storage::remove_edges(std::vector<RREdgeId>& rr_edges_to_remove)
         edge_src_node_[erase_idx] = edge_src_node_[RREdgeId(edge_list_end)];
         edge_switch_[erase_idx] = edge_switch_[RREdgeId(edge_list_end)];
         edge_remapped_[erase_idx] = edge_remapped_[RREdgeId(edge_list_end)];
+        edge_crr_id_[erase_idx] = edge_crr_id_[RREdgeId(edge_list_end)];
 
         // At this point we have no copies of what was at erase_idx and two copies of
         // what was at the end of the list. If we make the list one element shorter,
@@ -101,6 +106,7 @@ void t_rr_graph_storage::remove_edges(std::vector<RREdgeId>& rr_edges_to_remove)
     edge_src_node_.erase(edge_src_node_.begin() + edge_list_end + 1, edge_src_node_.end());
     edge_switch_.erase(edge_switch_.begin() + edge_list_end + 1, edge_switch_.end());
     edge_remapped_.erase(edge_remapped_.begin() + edge_list_end + 1, edge_remapped_.end());
+    edge_crr_id_.erase(edge_crr_id_.begin() + edge_list_end + 1, edge_crr_id_.end());
 
     VTR_ASSERT(edge_dest_node_.size() == (starting_edge_count - rr_edges_to_remove.size()));
 
@@ -126,6 +132,7 @@ void t_rr_graph_storage::assign_first_edges() {
     VTR_ASSERT(edge_dest_node_.size() == num_edges);
     VTR_ASSERT(edge_switch_.size() == num_edges);
     VTR_ASSERT(edge_remapped_.size() == num_edges);
+    VTR_ASSERT(edge_crr_id_.size() == num_edges);
 
     while (true) {
         VTR_ASSERT(first_edge_id < num_edges);
@@ -808,6 +815,7 @@ t_rr_graph_view t_rr_graph_storage::view() const {
         vtr::make_const_array_view_id(edge_src_node_),
         vtr::make_const_array_view_id(edge_dest_node_),
         vtr::make_const_array_view_id(edge_switch_),
+        vtr::make_const_array_view_id(edge_crr_id_),
         virtual_clock_network_root_idx_,
         vtr::make_const_array_view_id(node_bend_start_),
         vtr::make_const_array_view_id(node_bend_end_));
@@ -846,6 +854,7 @@ void t_rr_graph_storage::reorder(const vtr::vector<RRNodeId, RRNodeId>& order,
         auto old_edge_dest_node = edge_dest_node_;
         auto old_edge_switch = edge_switch_;
         auto old_edge_remapped = edge_remapped_;
+        auto old_edge_crr_id = edge_crr_id_;
         RREdgeId cur_edge(0);
 
         // Reorder edges by source node
@@ -859,6 +868,7 @@ void t_rr_graph_storage::reorder(const vtr::vector<RRNodeId, RRNodeId>& order,
                 edge_dest_node_[cur_edge] = order[old_edge_dest_node[e]];
                 edge_switch_[cur_edge] = old_edge_switch[e];
                 edge_remapped_[cur_edge] = old_edge_remapped[e];
+                edge_crr_id_[cur_edge] = old_edge_crr_id[e];
                 cur_edge = RREdgeId(size_t(cur_edge) + 1);
             }
         }