[libs][rr_graph] add comment for tileable rr graph

Author: amin1377

libs/libarchfpga/src/read_xml_arch_file.cpp

@@ -4137,6 +4137,7 @@ static void process_bend(pugi::xml_node Node, t_segment_inf& segment, const int
                        tmp.c_str());
     }
 
+    // TODO: Add a comment to explain this and this function overall
     int tmp_len = 1;
     int sum_len = 0;
     for (size_t i_len = 0; i_len < list.size(); i_len++) {

libs/libarchfpga/src/read_xml_util.h

@@ -24,6 +24,12 @@ void bad_attribute_value(const pugi::xml_attribute attr,
 InstPort make_inst_port(std::string str, pugi::xml_node node, const pugiutil::loc_data& loc_data);
 InstPort make_inst_port(pugi::xml_attribute attr, pugi::xml_node node, const pugiutil::loc_data& loc_data);
 
+/**
+ * @brief Returns the number of layers in the device layout.
+ * 
+ * @param layout_type_tag The XML node pointing to the <layout> tag.
+ * @param loc_data Points to the location in the architecture file where the parser is reading.
+ */
 int get_number_of_layers(pugi::xml_node layout_type_tag, const pugiutil::loc_data& loc_data);
 
 /**

libs/libarchfpga/src/vib_inf.h

@@ -1,4 +1,12 @@
 #pragma once
+/**
+ * @file
+ * @brief   Methods and classes related to the Versatile Interconnect Blocks (VIB) architecture.
+ *          VIB is an alternative approach for creating the Routing Resource (RR) graph, where the connection block,
+ *          switch block, and intra-cluster crossbar are combined into a single block. This means that each tile has
+ *          only two blocks: a VIB block and a functional block. For further details, please refer to the following paper:
+ *          https://doi.org/10.1109/ICFPT59805.2023.00014
+ */
 
 #include <functional>
 #include <utility>

libs/librrgraph/src/base/check_rr_graph.cpp

@@ -450,6 +450,10 @@ void check_rr_node(const RRGraphView& rr_graph,
 
     int class_max_ptc = get_tile_class_max_ptc(type, is_flat);
     int pin_max_ptc = get_tile_pin_max_ptc(type, is_flat);
+
+    // TODO: This is a temporary fix to ensure that the VIB architecture is supported.
+    //       This should be removed and ** grid ** should be used instead.
+    // If VIB architecture is not used, these are not going to have any effect.
     int mux_max_ptc = -1;
     const VibInf* vib_type = nullptr;
     if (vib_grid.get_num_layers() > 0) {
@@ -458,6 +462,8 @@ void check_rr_node(const RRGraphView& rr_graph,
     if (vib_type) {
         mux_max_ptc = (int)vib_type->get_first_stages().size();
     }
+
+
     e_pin_type class_type = OPEN;
     int class_num_pins = -1;
     switch (rr_type) {

libs/librrgraph/src/base/check_rr_graph.h

@@ -13,6 +13,21 @@ void check_rr_graph(const RRGraphView& rr_graph,
                     const e_graph_type graph_type,
                     bool is_flat);
 
+/**
+ * @brief Checks the validity of the given node in the RR graph.
+ * 
+ * @note This function checks for the following:
+ *       - The node's location is within the legal range.
+ *       - The node's capacity and other properties are consistent with the node's type.
+ *       - The node's type is valid.
+ *       - The node's capacity is consistent with the node's type.
+ *       - The node's capacitance and resistance are non-negative.
+ * 
+ * @note vib_grid is added and used only of VIB architecture is used. This data strucutre
+ *       is used to check for MUX node type PTC number. Ideally, this should be removed and
+ *       ** grid ** should be used instead.
+ * 
+ */
 void check_rr_node(const RRGraphView& rr_graph,
                    const vtr::vector<RRIndexedDataId, t_rr_indexed_data>& rr_indexed_data,
                    const DeviceGrid& grid,

libs/librrgraph/src/base/rr_graph_builder.cpp

@@ -32,7 +32,7 @@ vtr::vector<RRNodeId, std::vector<RREdgeId>>& RRGraphBuilder::node_in_edge_stora
 }
 
 vtr::vector<RRNodeId, std::vector<short>>& RRGraphBuilder::node_ptc_storage() {
-    return node_ptc_nums_;
+    return node_tilable_track_nums_;
 }
 
 void RRGraphBuilder::add_node_to_all_locs(RRNodeId node) {
@@ -75,7 +75,7 @@ RRNodeId RRGraphBuilder::create_node(int layer, int x, int y, e_rr_type type, in
         node_side = side;
     }
     node_storage_.emplace_back();
-    node_ptc_nums_.emplace_back();
+    node_tilable_track_nums_.emplace_back();
     RRNodeId new_node = RRNodeId(node_storage_.size() - 1);
     node_storage_.set_node_layer(new_node, layer);
     node_storage_.set_node_type(new_node, type);
@@ -84,7 +84,6 @@ RRNodeId RRGraphBuilder::create_node(int layer, int x, int y, e_rr_type type, in
     if (e_rr_type::OPIN == type || e_rr_type::IPIN == type) {
         node_storage_.add_node_side(new_node, node_side);
     }
-    // Special for CHANX, being consistent with the rule in find_node()
     node_lookup_.add_node(new_node, layer, x, y, type, ptc, node_side);
 
     return new_node;
@@ -102,7 +101,7 @@ void RRGraphBuilder::clear() {
     node_lookup_.clear();
     node_storage_.clear();
     node_in_edges_.clear();
-    node_ptc_nums_.clear();
+    node_tilable_track_nums_.clear();
     rr_node_metadata_.clear();
     rr_edge_metadata_.clear();
     rr_segments_.clear();
@@ -182,7 +181,7 @@ void RRGraphBuilder::reorder_nodes(e_rr_node_reorder_algorithm reorder_rr_graph_
     });
 }
 
-void RRGraphBuilder::create_edge(RRNodeId src, RRNodeId dest, RRSwitchId edge_switch, bool remapped) {
+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);
     is_edge_dirty_ = true; // Adding a new edge revokes the flag
     is_incoming_edge_dirty_ = true;
@@ -231,53 +230,53 @@ void RRGraphBuilder::set_node_ptc_nums(RRNodeId node, const std::string& ptc_str
     VTR_ASSERT(ptc_tokens.size() >= 1);
     set_node_ptc_num(node, std::stoi(ptc_tokens[0]));
     if (ptc_tokens.size() > 1) {
-        VTR_ASSERT(size_t(node) < node_ptc_nums_.size());
-        node_ptc_nums_[node].resize(ptc_tokens.size());
+        VTR_ASSERT(size_t(node) < node_tilable_track_nums_.size());
+        node_tilable_track_nums_[node].resize(ptc_tokens.size());
         for (size_t iptc = 0; iptc < ptc_tokens.size(); iptc++) {
-          node_ptc_nums_[node][iptc] = std::stoi(ptc_tokens[iptc]);
+          node_tilable_track_nums_[node][iptc] = std::stoi(ptc_tokens[iptc]);
         }
     }
 }
 
 std::string RRGraphBuilder::node_ptc_nums_to_string(RRNodeId node) const {
-    if (node_ptc_nums_.empty()) {
+    if (node_tilable_track_nums_.empty()) {
         return std::to_string(size_t(node_storage_.node_ptc_num(node)));
     }
-    VTR_ASSERT(size_t(node) < node_ptc_nums_.size());
-    if (node_ptc_nums_[node].empty()) {
+    VTR_ASSERT(size_t(node) < node_tilable_track_nums_.size());
+    if (node_tilable_track_nums_[node].empty()) {
         return std::to_string(size_t(node_storage_.node_ptc_num(node)));
     }
     std::string ret;
-    for (size_t iptc = 0; iptc < node_ptc_nums_[node].size(); iptc++) {
-        ret += std::to_string(size_t(node_ptc_nums_[node][iptc])) + ",";
+    for (size_t iptc = 0; iptc < node_tilable_track_nums_[node].size(); iptc++) {
+        ret += std::to_string(size_t(node_tilable_track_nums_[node][iptc])) + ",";
     }
     // Remove the last comma
     ret.pop_back();
     return ret;
 }
 
 bool RRGraphBuilder::node_contain_multiple_ptc(RRNodeId node) const {
-    if (node_ptc_nums_.empty()) {
+    if (node_tilable_track_nums_.empty()) {
         return false;
     }
-    return node_ptc_nums_[node].size() > 1;
+    return node_tilable_track_nums_[node].size() > 1;
 }
 
 void RRGraphBuilder::add_node_track_num(RRNodeId node, vtr::Point<size_t> node_offset, short track_id) {
     VTR_ASSERT(size_t(node) < node_storage_.size());
-    VTR_ASSERT(size_t(node) < node_ptc_nums_.size());
+    VTR_ASSERT(size_t(node) < node_tilable_track_nums_.size());
     VTR_ASSERT_MSG(node_storage_.node_type(node) == e_rr_type::CHANX || node_storage_.node_type(node) == e_rr_type::CHANY, "Track number valid only for CHANX/CHANY RR nodes");
 
     size_t node_length = std::abs(node_storage_.node_xhigh(node) - node_storage_.node_xlow(node))
                        + std::abs(node_storage_.node_yhigh(node) - node_storage_.node_ylow(node));
-    if (node_length + 1 != node_ptc_nums_[node].size()) {
-        node_ptc_nums_[node].resize(node_length + 1);
+    if (node_length + 1 != node_tilable_track_nums_[node].size()) {
+        node_tilable_track_nums_[node].resize(node_length + 1);
     }
 
     size_t offset = node_offset.x() - node_storage_.node_xlow(node) + node_offset.y() - node_storage_.node_ylow(node);
-    VTR_ASSERT(offset < node_ptc_nums_[node].size());
+    VTR_ASSERT(offset < node_tilable_track_nums_[node].size());
 
-    node_ptc_nums_[node][offset] = track_id;
+    node_tilable_track_nums_[node][offset] = track_id;
 }
 
 void RRGraphBuilder::add_track_node_to_lookup(RRNodeId node) {
@@ -301,9 +300,9 @@ void RRGraphBuilder::add_track_node_to_lookup(RRNodeId node) {
             e_rr_type node_type = node_storage_.node_type(node);
             // Routing channel nodes may have different ptc num 
             // Find the track ids using the x/y offset  
-            // FIXME: Special case on assigning CHANX (x,y) should be changed to a natural way!
             if (e_rr_type::CHANX == node_type || e_rr_type::CHANY == node_type) {
-                ptc = node_type == e_rr_type::CHANX ? node_ptc_nums_[node][x - node_storage_.node_xlow(node)] : node_ptc_nums_[node][y - node_storage_.node_ylow(node)];
+                ptc = (node_type == e_rr_type::CHANX) ? node_tilable_track_nums_[node][x - node_storage_.node_xlow(node)] : 
+                    node_tilable_track_nums_[node][y - node_storage_.node_ylow(node)];
                 node_lookup_.add_node(node, node_storage_.node_layer(node), x, y, node_type, ptc); 
             }
         }

libs/librrgraph/src/base/rr_graph_builder.h

@@ -36,16 +36,21 @@ class RRGraphBuilder {
   public:
     /** @brief Return a writable object for rr_nodes */
     t_rr_graph_storage& rr_nodes();
+    
     /** @brief Return a writable object for update the fast look-up of rr_node */
     RRSpatialLookup& node_lookup();
+    
     /** @warning The Metadata should stay as an independent data structure from the rest of the internal data,
      *  e.g., node_lookup! */
     /** @brief Return a writable object for the meta data on the nodes */
     MetadataStorage<int>& rr_node_metadata();
+    
     /** @brief Return a writable object for the meta data on the edge */
     MetadataStorage<std::tuple<int, int, short>>& rr_edge_metadata();
+    
     /** @brief Return a writable object fo the incoming edge storage */
     vtr::vector<RRNodeId, std::vector<RREdgeId>>& node_in_edge_storage();
+    
     /** @brief Return a writable object of the node ptc storage (for tileable routing resource graph) */
     vtr::vector<RRNodeId, std::vector<short>>& node_ptc_storage();
 
@@ -241,9 +246,16 @@ class RRGraphBuilder {
         node_storage_.set_node_track_num(id, new_track_num);
     }
 
+    // ** The following functions are only used for tileable routing resource graph generator **
+
     /** @brief Add a track id for a given node base on the offset in coordinate, applicable only to CHANX and CHANY nodes.
      * This API is used by tileable routing resource graph generator, which requires each routing track has a different
      * track id depending their location in FPGA fabric.
+     * 
+     * @param node The node to add the track id to.
+     * @param node_offset Location of the portion of the node being considered. It is used
+     *                    to calculate the relative location from the beginning of the node.
+     * @param track_id The track id to add to the node.
      */
     void add_node_track_num(RRNodeId node, vtr::Point<size_t> node_offset, short track_id);
 
@@ -256,17 +268,17 @@ class RRGraphBuilder {
     }
 
     /** @brief set_node_mux_num() is designed for routing mux nodes */
-    inline void set_node_mux_num(RRNodeId id, int new_class_num) {
-        node_storage_.set_node_mux_num(id, new_class_num);
+    inline void set_node_mux_num(RRNodeId id, int new_mux_num) {
+        node_storage_.set_node_mux_num(id, new_mux_num);
     }
 
-    /** @brief Add a list of ptc number in string (split by comma) to a given node. This function is used by rr graph reader only. Not suggested for internal builder!!! */
+    /** @brief Add a list of ptc number in string (split by comma) to a given node. This function is used by rr graph reader only. */
     void set_node_ptc_nums(RRNodeId node, const std::string& ptc_str);
 
-    /** @brief With a given node, output ptc numbers into a string (use comma as delima). This function is used by rr graph writer only. Not suggested for internal builder!!! */
+    /** @brief With a given node, output ptc numbers into a string (use comma as delima). This function is used by rr graph writer only. */
     std::string node_ptc_nums_to_string(RRNodeId node) const;
 
-    /** @brief Identify if a node contains multiple ptc numbers. Mainly used by I/O reader only. Not suggest for internal builder */
+    /** @brief Identify if a node contains multiple ptc numbers. It is used for tileable RR Graph and mainly used by I/O reader only. */
     bool node_contain_multiple_ptc(RRNodeId node) const;
 
     /** @brief Set the node direction; The node direction is only available of routing channel nodes, such as x-direction routing tracks (CHANX) and y-direction routing tracks (CHANY). For other nodes types, this value is not meaningful and should be set to NONE. */
@@ -275,8 +287,8 @@ 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(RRNodeId src, RRNodeId dest, RRSwitchId edge_switch, bool remapped);
+     *  @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);
 
     /** @brief Allocate and build actual edges in storage. 
      * Once called, the cached edges will be uniquified and added to routing resource nodes, 
@@ -295,6 +307,8 @@ class RRGraphBuilder {
      */
     std::vector<RREdgeId> node_in_edges(RRNodeId node) const;
 
+    // ** End of functions for tileable routing resource graph generator **
+
     /** @brief Set the node id for clock network virtual sink */
     inline void set_virtual_clock_network_root_idx(RRNodeId virtual_clock_network_root_idx) {
         node_storage_.set_virtual_clock_network_root_idx(virtual_clock_network_root_idx);
@@ -370,11 +384,6 @@ 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 
-     */
-    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,
@@ -393,9 +402,9 @@ class RRGraphBuilder {
     inline void resize_nodes(size_t size) {
         node_storage_.resize(size);
     }
-    /** @brief This function resize node ptc nums. Only used by RR graph I/O reader and writers. Do not use for internal builder */
+    /** @brief This function resize node ptc nums. Only used by RR graph I/O reader and writers. */
     inline void resize_node_ptc_nums(size_t size) {
-        node_ptc_nums_.resize(size);
+        node_tilable_track_nums_.resize(size);
     }
 
 
@@ -404,7 +413,8 @@ class RRGraphBuilder {
         rr_switch_inf_.resize(size);
     }
 
-    /** @brief Validate that edge data is partitioned correctly. Also there are no edges left to be built!
+    /** @brief Validate that edge data is partitioned correctly. This function should be called
+     * when all edges in cache are added.
      * @note This function is used to validate the correctness of the routing resource graph in terms
      * of graph attributes. Strongly recommend to call it when you finish the building a routing resource
      * graph. If you need more advance checks, which are related to architecture features, you should
@@ -459,8 +469,13 @@ class RRGraphBuilder {
 
     /** 
      * @brief A cache for edge-related information, required to build edges for routing resource nodes.
-     * @note It is used when building a routing resource graph by considering memory efficiency.
-     * It will be clear up after calling build_edges().
+     * @note It is used when building a routing resource graph. It is a set of edges that have not yet been 
+     * added to the main rr-graph edge storage to avoid an expensive edge-by-edge reallocation or re-shuffling 
+     * of edges in the main rr-graph edge storage.
+     * 
+     * @note It will be cleared after calling build_edges().
+     * 
+     * @note This data structure is only used for tileable routing resource graph generator.
      *
      * @warning This is a temporary data which is used to collect edges to be built for nodes
      */
@@ -490,15 +505,16 @@ class RRGraphBuilder {
     /** 
      * @brief A list of incoming edges for each routing resource node. 
      * @note This can be built optionally, as required by applications.
-     * By default, it is empty! Call build_in_edges() to construct it!!! 
+     * By default, it is empty! Call build_in_edges() to construct it.
      */
     vtr::vector<RRNodeId, std::vector<RREdgeId>> node_in_edges_;
 
     /** 
      * @brief Extra ptc number for each routing resource node. 
-     * @note This is required by tileable routing resource graph.
+     * @note This is required by tileable routing resource graphs. The first index is the node id, and
+     * the second index is is the relative distance from the starting point of the node.
      * @details 
-     * In a tileable routing architecture, routing tracks, e.g., CHANX and CHANY, follows a staggered organization.
+     * In a tileable routing architecture, routing tracks, e.g., CHANX and CHANY, follow a staggered organization.
      * Hence, a routing track may appear in different routing channels, representing different ptc/track id.
      * Here is an illustrative example of a X-direction routing track (CHANX) in INC direction, which is organized in staggered way.
      *    
@@ -514,7 +530,7 @@ class RRGraphBuilder {
      *           |                               |
      *     starting point                   ending point
      */
-    vtr::vector<RRNodeId, std::vector<short>> node_ptc_nums_;
+    vtr::vector<RRNodeId, std::vector<short>> node_tilable_track_nums_;
 
     /** @warning The Metadata should stay as an independent data structure from the rest of the internal data,
      *  e.g., node_lookup! */
@@ -542,8 +558,15 @@ class RRGraphBuilder {
      */
     MetadataStorage<std::tuple<int, int, short>> rr_edge_metadata_;
 
-    /** @brief a flag to mark the status of edge storage
-     *  dirty means that the edge storage is not complete, should call related APIs to build */
+    /** 
+     * @brief This flag indicates if all the edges in cache are added to the main rr-graph edge storage.
+     * To add all edges in cache to the main rr-graph edge storage, call build_edges().
+     */
     bool is_edge_dirty_;
+
+    /**
+     * @brief This flag indicates whether node_in_edges_ is updated with 
+     * edges in the main rr-graph edge storage.
+     */
     bool is_incoming_edge_dirty_;
 };