vpr: Rename t_heap::previous -> t_heap::nodes

Also update t_heap comments to clarify data members

Author: kmurray

vpr/src/route/route_breadth_first.cpp

@@ -204,7 +204,7 @@ static bool breadth_first_route_net(ClusterNetId net_id, float bend_cost) {
                 VTR_LOG("    New best cost %g\n", new_pcost);
 #endif
 
-                for (t_heap_prev prev : current->previous) {
+                for (t_heap_prev prev : current->nodes) {
 #ifdef ROUTER_DEBUG
                     VTR_LOG("    Setting routing paths for associated node %d\n", prev.to_node);
 #endif
@@ -420,7 +420,7 @@ static void breadth_first_expand_non_configurable_recurr(const float path_cost,
         current->cost = std::min(current->cost, new_path_cost);
 
         //Record how we reached this node
-        current->previous.emplace_back(to_node, from_node, iconn);
+        current->nodes.emplace_back(to_node, from_node, iconn);
 
         //Consider any non-configurable edges which must be expanded for correctness
         auto& device_ctx = g_vpr_ctx.device();

vpr/src/route/route_common.cpp

@@ -97,7 +97,7 @@ static int num_linked_f_pointer_allocated = 0;
  *                                                                          */
 
 /******************** Subroutines local to route_common.c *******************/
-static t_trace_branch traceback_branch(int node, const std::vector<t_heap_prev>& previous, std::unordered_set<int>& main_branch_visited);
+static t_trace_branch traceback_branch(int node, const std::vector<t_heap_prev>& nodes, std::unordered_set<int>& main_branch_visited);
 static std::pair<t_trace*,t_trace*> add_trace_non_configurable(t_trace* head, t_trace* tail, int node, std::unordered_set<int>& visited);
 static std::pair<t_trace*,t_trace*> add_trace_non_configurable_recurr(int node, std::unordered_set<int>& visited, int depth=0);
 
@@ -562,7 +562,7 @@ update_traceback(t_heap *hptr, ClusterNetId net_id) {
 
     VTR_ASSERT_SAFE(validate_trace_nodes(route_ctx.trace[net_id].head, trace_nodes));
 
-    t_trace_branch branch = traceback_branch(hptr->index, hptr->previous, trace_nodes);
+    t_trace_branch branch = traceback_branch(hptr->index, hptr->nodes, trace_nodes);
 
     VTR_ASSERT_SAFE(validate_trace_nodes(branch.head, trace_nodes));
 
@@ -581,7 +581,7 @@ update_traceback(t_heap *hptr, ClusterNetId net_id) {
 
 //Traces back a new routing branch starting from the specified 'node' and working backwards to any existing routing.
 //Returns the new branch, and also updates trace_nodes for any new nodes which are included in the branches traceback.
-static t_trace_branch traceback_branch(int node, const std::vector<t_heap_prev>& previous, std::unordered_set<int>& trace_nodes) {
+static t_trace_branch traceback_branch(int node, const std::vector<t_heap_prev>& nodes, std::unordered_set<int>& trace_nodes) {
     auto& device_ctx = g_vpr_ctx.device();
     auto& route_ctx = g_vpr_ctx.routing();
 
@@ -604,7 +604,7 @@ static t_trace_branch traceback_branch(int node, const std::vector<t_heap_prev>&
 
     std::vector<int> new_nodes_added_to_traceback = {node};
 
-    for (t_heap_prev prev : previous) {
+    for (t_heap_prev prev : nodes) {
         int inode = prev.from_node;
         int iedge = prev.from_edge;
 
@@ -811,8 +811,8 @@ void node_to_heap(int inode, float total_cost, int prev_node, int prev_edge,
 	t_heap* hptr = alloc_heap_data();
 	hptr->index = inode;
 	hptr->cost = total_cost;
-    VTR_ASSERT(hptr->previous.empty());
-	hptr->previous.emplace_back(inode, prev_node, prev_edge);
+    VTR_ASSERT(hptr->nodes.empty());
+	hptr->nodes.emplace_back(inode, prev_node, prev_edge);
 	hptr->backward_path_cost = backward_path_cost;
 	hptr->R_upstream = R_upstream;
 	add_to_heap(hptr);
@@ -1290,7 +1290,7 @@ namespace heap_ {
 		t_heap* hptr = alloc_heap_data();
 		hptr->index = inode;
 		hptr->cost = total_cost;
-        hptr->previous.emplace_back(inode, prev_node, prev_edge);
+        hptr->nodes.emplace_back(inode, prev_node, prev_edge);
 		hptr->backward_path_cost = backward_path_cost;
 		hptr->R_upstream = R_upstream;
 		push_back(hptr);
@@ -1412,7 +1412,7 @@ alloc_heap_data() {
     temp_ptr->backward_path_cost = 0.;
     temp_ptr->R_upstream = 0.;
     temp_ptr->index = OPEN;
-    temp_ptr->previous.clear();
+    temp_ptr->nodes.clear();
 	return (temp_ptr);
 }
 
@@ -1430,7 +1430,7 @@ void invalidate_heap_entries(int sink_node, int ipin_node) {
 
 	for (int i = 1; i < heap_tail; i++) {
 		if (heap[i]->index == sink_node) {
-            for (t_heap_prev prev : heap[i]->previous) {
+            for (t_heap_prev prev : heap[i]->nodes) {
                 if (prev.from_node == ipin_node) {
                     heap[i]->index = OPEN; /* Invalid. */
                     break;

vpr/src/route/route_common.h

@@ -14,33 +14,44 @@ struct t_heap_prev {
 };
 
 
-/* Used by the heap as its fundamental data structure.                      *
- * index:   Index (ID) of this routing resource node.                       *
- * cost:    Cost up to and including this node.                             *
- * u.prev_node:  Index (ID) of the predecessor to this node for             *
- *          use in traceback.  NO_PREVIOUS if none.                         *
- * u.next:  pointer to the next s_heap structure in the free                *
- *          linked list.  Not used when on the heap.                        *
- * prev_edge:  Index of the edge (between 0 and num_edges-1) used to        *
- *             connect the previous node to this one.  NO_PREVIOUS if       *
- *             there is no previous node.                                   *
- * backward_path_cost:  Used only by the timing-driven router.  The "known" *
- *                      cost of the path up to and including this node.     *
- *                      In this case, the .cost member contains not only    *
- *                      the known backward cost but also an expected cost   *
- *                      to the target.                                      *
- * R_upstream: Used only by the timing-driven router.  Stores the upstream  *
- *             resistance to ground from this node, including the           *
- *             resistance of the node itself (device_ctx.rr_nodes[index].R).*/
+/* Used by the heap as its fundamental data structure.
+ * Each heap element represents a partial route.
+ *
+ * next:    pointer to the next s_heap structure in the free
+ *          linked list.  Not used when on the heap.
+ *
+ * cost:    The cost used to sort heap.
+ *          For the timing-driven router this is the backward_path_cost +
+ *          expected cost to the target.
+ *          For the breadth-first router it is the node cost to reach this
+ *          point.
+ * backward_path_cost:  Used only by the timing-driven router.  The "known"
+ *                      cost of the path up to and including this node.
+ *                      In this case, the .cost member contains not only
+ *                      the known backward cost but also an expected cost
+ *                      to the target.
+ * R_upstream: Used only by the timing-driven router.  Stores the upstream 
+ *             resistance to ground from this node, including the
+ *             resistance of the node itself (device_ctx.rr_nodes[index].R).
+ *
+ * index: The RR node index associated with the costs/R_upstream values
+ * nodes: The set of nodes represented by this heap element.
+ *        Usually this contains a single element corresponding to index.
+ *        However in some cases (e.g. non-configurable edges) multiple RR 
+ *        nodes may be required to be used together. In such cases each
+ *        node will be inclued in 'nodes' and 'cost', 'backward_path_cost',
+ *        R_upstream will be those associated with the lowest cost node (who's
+ *        index is stored in 'index' for reference).
+ */
 struct t_heap {
     t_heap *next = nullptr;
 
 	float cost = 0.;
 	float backward_path_cost = 0.;
 	float R_upstream = 0.;
-	int index = OPEN;
 
-    std::vector<t_heap_prev> previous;
+	int index = OPEN;
+    std::vector<t_heap_prev> nodes;
 };
 
 /******* Subroutines in route_common used only by other router modules ******/

vpr/src/route/route_timing.cpp

@@ -1400,7 +1400,7 @@ static void timing_driven_expand_cheapest(t_heap* cheapest,
     if (old_total_cost > new_total_cost && old_back_cost > new_back_cost) {
 
         VTR_LOGV_DEBUG(f_router_debug, "    Better cost to %d\n", inode);
-        for (t_heap_prev prev : cheapest->previous) {
+        for (t_heap_prev prev : cheapest->nodes) {
             VTR_LOGV_DEBUG(f_router_debug, "      Setting path costs for assicated node %d (from %d edge %d)\n", prev.to_node, prev.from_node, prev.from_edge);
 
             add_to_mod_list(prev.to_node, modified_rr_node_inf);
@@ -1744,7 +1744,6 @@ static void timing_driven_expand_neighbours(t_heap *current,
 
     //For each node associated with the current heap element, expand all of it's neighbours
     for (const t_heap_prev& prev : current->nodes) {
-
         int num_edges = device_ctx.rr_nodes[prev.to_node].num_edges();
         for (int iconn = 0; iconn < num_edges; iconn++) {
             int to_node = device_ctx.rr_nodes[prev.to_node].edge_sink_node(iconn);
@@ -1889,7 +1888,7 @@ static void timing_driven_expand_node(const t_conn_cost_params cost_params,
                         from_node, to_node, iconn, target_node);
 
     //Record how we reached this node
-    current->previous.emplace_back(to_node, from_node, iconn);
+    current->nodes.emplace_back(to_node, from_node, iconn);
 
     //Since this heap element may represent multiple (non-configurably connected) nodes,
     //keep the minimum cost to the target

vpr/src/route/route_tree_timing.cpp

@@ -305,7 +305,7 @@ add_subtree_to_route_tree(t_heap *hptr, t_rt_node ** sink_rt_node_ptr) {
 	downstream_rt_node = sink_rt_node;
 
     std::unordered_set<int> main_branch_visited;
-    for (t_heap_prev prev : hptr->previous) {
+    for (t_heap_prev prev : hptr->nodes) {
         inode = prev.from_node;
         iedge = prev.from_edge;
         iswitch = device_ctx.rr_nodes[inode].edge_switch(iedge);