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,56 @@
+#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 any duplication of the object
+     * as it is only interface allowed to modify routing resource graph
+     */
+    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,68 @@
+#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 any duplication of the object
+     * as it is only interface allowed to access routing resource graph
+     */
+    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,93 @@
+#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 */
+    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(type != IPIN && type != OPIN);
+        node_side = SIDES[0];
+    }
+
+    /* 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_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));
+}

vpr/src/device/rr_spatial_lookup.h

@@ -0,0 +1,97 @@
+#ifndef RR_SPATIAL_LOOKUP_H
+#define RR_SPATIAL_LOOKUP_H
+
+#include "vpr_types.h"
+
+/******************************************************************** 
+ * A data structure storing the fast look-up for the nodes
+ * in a routing resource graph
+ *
+ * The data structure allows users to 
+ * - Update the look-up with new nodes
+ * - Find the id of a node with given information, e.g., x, y, type etc.
+ ********************************************************************/
+class RRSpatialLookup {
+    /* -- Constructors -- */
+  public:
+    /* Explicitly define the only way to create an object */
+    explicit RRSpatialLookup(t_rr_node_indices& rr_node_indices);
+
+    /* Disable copy constructors and copy assignment operator
+     * This is to avoid any duplication of the object
+     * as it is only interface allowed to access node look-up of a routing resource graph
+     */
+    RRSpatialLookup(const RRSpatialLookup&) = delete;
+    void operator=(const RRSpatialLookup&) = delete;
+
+    /* -- Accessors -- */
+  public:
+    /* Returns the index of the specified routing resource node.  (x,y) are
+     * the location within the FPGA, rr_type specifies the type of resource,
+     * and ptc gives the number of this resource.  ptc is the class number,
+     * pin number or track number, depending on what type of resource this
+     * is.  All ptcs start at 0 and go up to pins_per_clb-1 or the equivalent.
+     * There are class_inf size SOURCEs + SINKs, type->num_pins IPINs + OPINs,
+     * and max_chan_width CHANX and CHANY (each).
+     *
+     * Note that for segments (CHANX and CHANY) of length > 1, the segment is
+     * given an rr_index based on the (x,y) location at which it starts (i.e.
+     * lowest (x,y) location at which this segment exists).
+     * This routine also performs error checking to make sure the node in
+     * question exists.
+     *
+     * The 'side' argument only applies to IPIN/OPIN types, and specifies which
+     * side of the grid tile the node should be located on. The value is ignored
+     * for non-IPIN/OPIN types
+     */
+    RRNodeId find_node(int x,
+                       int y,
+                       t_rr_type type,
+                       int ptc,
+                       e_side side = NUM_SIDES) const;
+
+    /* -- Mutators -- */
+  public:
+    /* Register a node in the fast look-up 
+     * - You must have a node id
+     *   1. a valid one is to register a node in the lookup
+     *   2. an invalid id means the removal of a node from the lookup
+     * - (x, y) are the coordinate of the node to be indexable in the fast look-up
+     * - type is the type of a node
+     * - ptc is a feature number of a node, which can be
+     *   1. pin index in a tile when type is OPIN/IPIN
+     *   2. track index in a routing channel when type is CHANX/CHANY
+     * - side is the side of node on the tile, applicable to OPIN/IPIN 
+     *
+     * Note that the add node here will not create a node in the node list
+     * You MUST add the node in the t_rr_node_storage so that the node is valid  
+     *
+     * TODO: Consider to try to return a reference to *this so that we can do chain calls
+     *   - .add_node(...)
+     *   - .add_node(...)
+     *   - .add_node(...)
+     *   As such, multiple node addition could be efficiently implemented
+     */
+    void add_node(RRNodeId node,
+                  int x,
+                  int y,
+                  t_rr_type type,
+                  int ptc,
+                  e_side side);
+
+    /* -- Internal data storage -- */
+  private:
+    /* TODO: When the refactoring effort finishes, 
+     * the data structure will be the owner of the data storages. 
+     * That is why the reference 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 rr_node_indices 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
+     */
+    /* Fast look-up */
+    t_rr_node_indices& rr_node_indices_;
+};
+
+#endif