RR Graph Overlay Creation and Deploy new node_type() API of Overlay

vpr/src/base/vpr_context.h

@@ -9,7 +9,9 @@
 #include "vtr_vector.h"
 #include "atom_netlist.h"
 #include "clustered_netlist.h"
+#include "rr_graph_view.h"
 #include "rr_graph_storage.h"
+#include "rr_graph_builder.h"
 #include "rr_node.h"
 #include "rr_rc_data.h"
 #include "tatum/TimingGraph.hpp"
@@ -145,7 +147,6 @@ struct DeviceContext : public Context {
     /*
      * Structures to define the routing architecture of the FPGA.
      */
-
     t_rr_graph_storage rr_nodes; // autogenerated in build_rr_graph
 
     std::vector<t_rr_indexed_data> rr_indexed_data; // [0 .. num_rr_indexed_data-1]
@@ -162,6 +163,21 @@ struct DeviceContext : public Context {
     ///@brief The indicies of rr nodes of a given type at a specific x,y grid location
     t_rr_node_indices rr_node_indices; // [0..NUM_RR_TYPES-1][0..grid.width()-1][0..grid.width()-1][0..size-1]
 
+    /* TODO: remove this interface from device_context once the code refactoring is completed
+     * because it should be part of the rr_graph view
+     */
+    RRSpatialLookup rr_spatial_lookup{rr_node_indices};
+
+    /* A read-only view of routing resource graph to be the ONLY database 
+     * for client functions: GUI, placer, router, timing analyzer etc.
+     */
+    RRGraphView rr_graph{rr_nodes, rr_spatial_lookup};
+
+    /* A writeable view of routing resource graph to be the ONLY database 
+     * for routing resource graph builder functions.
+     */
+    RRGraphBuilder rr_graph_builder{&rr_nodes, &rr_spatial_lookup};
+
     ///@brief Autogenerated in build_rr_graph based on switch fan-in. [0..(num_rr_switches-1)]
     std::vector<t_rr_switch_inf> rr_switch_inf;
 

vpr/src/device/rr_graph_builder.cpp

@@ -0,0 +1,15 @@
+#include "rr_graph_builder.h"
+
+RRGraphBuilder::RRGraphBuilder(t_rr_graph_storage* node_storage,
+                               RRSpatialLookup* node_lookup)
+    : node_storage_(*node_storage)
+    , node_lookup_(*node_lookup) {
+}
+
+t_rr_graph_storage& RRGraphBuilder::node_storage() {
+    return node_storage_;
+}
+
+RRSpatialLookup& RRGraphBuilder::node_lookup() {
+    return node_lookup_;
+}

vpr/src/device/rr_graph_builder.h

@@ -0,0 +1,58 @@
+#ifndef RR_GRAPH_BUILDER_H
+#define RR_GRAPH_BUILDER_H
+
+#include "rr_graph_storage.h"
+#include "rr_spatial_lookup.h"
+
+/* A data structure allows data modification on a routing resource graph 
+ *
+ * Note that the builder does not own the storage
+ * It serves a virtual protocol for
+ * - node_storage: store the node list 
+ * - node_lookup: store a fast look-up for the nodes
+ *
+ * Note:
+ * - This is the only data structre allowed to modify a routing resource graph
+ *
+ */
+class RRGraphBuilder {
+    /* -- Constructors -- */
+  public:
+    /* See detailed comments about the data structures in the internal data storage section of this file */
+    RRGraphBuilder(t_rr_graph_storage* node_storage,
+                   RRSpatialLookup* node_lookup);
+
+    /* Disable copy constructors and copy assignment operator
+     * This is to avoid accidental copy because it could be an expensive operation considering that the 
+     * memory footprint of the data structure could ~ Gb
+     * Using the following syntax, we prohibit accidental 'pass-by-value' which can be immediately caught 
+     * by compiler
+     */
+    RRGraphBuilder(const RRGraphBuilder&) = delete;
+    void operator=(const RRGraphBuilder&) = delete;
+
+    /* -- Mutators -- */
+  public:
+    /* Return a writable object for rr_nodes */
+    t_rr_graph_storage& node_storage();
+    /* Return a writable object for update the fast look-up of rr_node */
+    RRSpatialLookup& node_lookup();
+
+    /* -- Internal data storage -- */
+  private:
+    /* TODO: When the refactoring effort finishes, 
+     * the builder data structure will be the owner of the data storages. 
+     * That is why the reference to storage/lookup is used here.
+     * It can avoid a lot of code changes once the refactoring is finished 
+     * (there is no function get data directly through the node_storage in DeviceContext).
+     * If pointers are used, it may cause many codes in client functions 
+     * or inside the data structures to be changed later.
+     * That explains why the reference is used here temporarily
+     */
+    /* node-level storage including edge storages */
+    t_rr_graph_storage& node_storage_;
+    /* Fast look-up for rr nodes */
+    RRSpatialLookup& node_lookup_;
+};
+
+#endif

vpr/src/device/rr_graph_view.cpp

@@ -0,0 +1,15 @@
+#include "rr_graph_view.h"
+
+RRGraphView::RRGraphView(const t_rr_graph_storage& node_storage,
+                         const RRSpatialLookup& node_lookup)
+    : node_storage_(node_storage)
+    , node_lookup_(node_lookup) {
+}
+
+t_rr_type RRGraphView::node_type(RRNodeId node) const {
+    return node_storage_.node_type(node);
+}
+
+const RRSpatialLookup& RRGraphView::node_lookup() const {
+    return node_lookup_;
+}

vpr/src/device/rr_graph_view.h

@@ -0,0 +1,70 @@
+#ifndef RR_GRAPH_VIEW_H
+#define RR_GRAPH_VIEW_H
+
+#include "rr_graph_storage.h"
+#include "rr_spatial_lookup.h"
+
+/* An read-only routing resource graph
+ * which is an unified object including pointors to
+ * - node storage
+ * - TODO: edge_storage
+ * - TODO: node_ptc_storage
+ * - TODO: node_fan_in_storage
+ * - rr_node_indices
+ *
+ * Note that the RRGraphView does not own the storage
+ * It serves a virtual read-only protocol for
+ * - placer
+ * - router
+ * - timing analyzer
+ * - GUI
+ *
+ * Note that each client of rr_graph may get a frame view of the object
+ * The RRGraphView is the complete frame view of the routing resource graph
+ * - This helps to reduce the memory footprint for each client
+ * - This avoids massive changes for each client on using the APIs
+ *   as each frame view provides adhoc APIs for each client
+ *
+ * TODO: more compact frame views will be created, e.g., 
+ * - a mini frame view: contains only node and edges, representing the connectivity of the graph
+ * - a geometry frame view: an extended mini frame view with node-level attributes, 
+ *                          in particular geometry information (type, x, y etc).
+ *
+ */
+class RRGraphView {
+    /* -- Constructors -- */
+  public:
+    /* See detailed comments about the data structures in the internal data storage section of this file */
+    RRGraphView(const t_rr_graph_storage& node_storage,
+                const RRSpatialLookup& node_lookup);
+
+    /* Disable copy constructors and copy assignment operator
+     * This is to avoid accidental copy because it could be an expensive operation considering that the 
+     * memory footprint of the data structure could ~ Gb
+     * Using the following syntax, we prohibit accidental 'pass-by-value' which can be immediately caught 
+     * by compiler
+     */
+    RRGraphView(const RRGraphView&) = delete;
+    void operator=(const RRGraphView&) = delete;
+
+    /* -- Accessors -- */
+    /* TODO: The accessors may be turned into private later if they are replacable by 'questionin' 
+     * kind of accessors
+     */
+  public:
+    /* Get the type of a routing resource node */
+    t_rr_type node_type(RRNodeId node) const;
+
+    /* Return the fast look-up data structure for queries from client functions */
+    const RRSpatialLookup& node_lookup() const;
+
+    /* -- Internal data storage -- */
+    /* Note: only read-only object or data structures are allowed!!! */
+  private:
+    /* node-level storage including edge storages */
+    const t_rr_graph_storage& node_storage_;
+    /* Fast look-up for rr nodes */
+    const RRSpatialLookup& node_lookup_;
+};
+
+#endif

vpr/src/device/rr_spatial_lookup.cpp

@@ -0,0 +1,108 @@
+#include "vtr_assert.h"
+#include "rr_spatial_lookup.h"
+
+RRSpatialLookup::RRSpatialLookup(t_rr_node_indices& rr_node_indices)
+    : rr_node_indices_(rr_node_indices) {
+}
+
+RRNodeId RRSpatialLookup::find_node(int x,
+                                    int y,
+                                    t_rr_type type,
+                                    int ptc,
+                                    e_side side) const {
+    /* Find actual side to be used
+     * - For the node which are input/outputs of a grid, there must be a specific side for them.
+     *   Because they should have a specific pin location on the perimeter of a grid.
+     * - For other types of nodes, there is no need to define a side. However, a default value
+     *   is needed when store the node in the fast look-up data structure.
+     *   Here we just arbitrary use the first side of the SIDE vector as the default value.
+     *   We may consider to use NUM_SIDES as the default value but it will cause an increase
+     *   in the dimension of the fast look-up data structure.
+     *   Please note that in the add_node function, we should keep the SAME convention!
+     */
+    e_side node_side = side;
+    if (type == IPIN || type == OPIN) {
+        VTR_ASSERT_MSG(side != NUM_SIDES, "IPIN/OPIN must specify desired side (can not be default NUM_SIDES)");
+    } else {
+        VTR_ASSERT_SAFE(type != IPIN && type != OPIN);
+        node_side = SIDES[0];
+    }
+
+    /* Pre-check: the x, y, side and ptc should be non negative numbers! Otherwise, return an invalid id */
+    if ((0 > x) || (0 > y) || (NUM_SIDES == node_side) || (0 > ptc)) {
+        return RRNodeId::INVALID();
+    }
+
+    /* Currently need to swap x and y for CHANX because of chan, seg convention 
+     * This is due to that the fast look-up builders uses (y, x) coordinate when
+     * registering a CHANX node in the look-up
+     * TODO: Once the builders is reworked for use consistent (x, y) convention,
+     * the following swapping can be removed
+     */
+    size_t node_x = x;
+    size_t node_y = y;
+    if (CHANX == type) {
+        std::swap(node_x, node_y);
+    }
+
+    VTR_ASSERT_SAFE(3 == rr_node_indices_[type].ndims());
+
+    /* Sanity check to ensure the x, y, side and ptc are in range 
+     * - Return an valid id by searching in look-up when all the parameters are in range
+     * - Return an invalid id if any out-of-range is detected
+     */
+    if (size_t(type) >= rr_node_indices_.size()) {
+        return RRNodeId::INVALID();
+    }
+
+    if (node_x >= rr_node_indices_[type].dim_size(0)) {
+        return RRNodeId::INVALID();
+    }
+
+    if (node_y >= rr_node_indices_[type].dim_size(1)) {
+        return RRNodeId::INVALID();
+    }
+
+    if (node_side >= rr_node_indices_[type].dim_size(2)) {
+        return RRNodeId::INVALID();
+    }
+
+    if (size_t(ptc) >= rr_node_indices_[type][node_x][node_y][node_side].size()) {
+        return RRNodeId::INVALID();
+    }
+
+    return RRNodeId(rr_node_indices_[type][node_x][node_y][node_side][ptc]);
+}
+
+void RRSpatialLookup::add_node(RRNodeId node,
+                               int x,
+                               int y,
+                               t_rr_type type,
+                               int ptc,
+                               e_side side) {
+    VTR_ASSERT(node);
+    VTR_ASSERT_SAFE(3 == rr_node_indices_[type].ndims());
+
+    /* Expand the fast look-up if the new node is out-of-range
+     * This may seldom happen because the rr_graph building function
+     * should ensure the fast look-up well organized  
+     */
+    VTR_ASSERT(type < rr_node_indices_.size());
+    VTR_ASSERT(0 <= x);
+    VTR_ASSERT(0 <= y);
+
+    if ((x >= int(rr_node_indices_[type].dim_size(0)))
+        || (y >= int(rr_node_indices_[type].dim_size(1)))
+        || (size_t(side) >= rr_node_indices_[type].dim_size(2))) {
+        rr_node_indices_[type].resize({std::max(rr_node_indices_[type].dim_size(0), size_t(x) + 1),
+                                       std::max(rr_node_indices_[type].dim_size(1), size_t(y) + 1),
+                                       std::max(rr_node_indices_[type].dim_size(2), size_t(side) + 1)});
+    }
+
+    if (size_t(ptc) >= rr_node_indices_[type][x][y][side].size()) {
+        rr_node_indices_[type][x][y][side].resize(ptc + 1);
+    }
+
+    /* Resize on demand finished; Register the node */
+    rr_node_indices_[type][x][y][side][ptc] = int(size_t(node));
+}