vpr: router_lookahead: comment on how missing entries are filled - fix gaurd name

Author: amin1377

vpr/src/route/router_lookahead_compressed_map.h

@@ -2,8 +2,8 @@
 // Created by amin on 11/27/23.
 //
 
-#ifndef VTR_ROUTER_LOOKAHEAD_SPARSE_MAP_H
-#define VTR_ROUTER_LOOKAHEAD_SPARSE_MAP_H
+#ifndef VTR_ROUTER_LOOKAHEAD_COMPRESSED_MAP_H
+#define VTR_ROUTER_LOOKAHEAD_COMPRESSED_MAP_H
 
 #include <string>
 #include <limits>
@@ -72,4 +72,4 @@ typedef vtr::NdMatrix<util::Cost_Entry, 5> t_compressed_wire_cost_map; //[0..num
                                                                        // The first index is the layer number that the node under consideration is on, and the forth index
                                                                        // is the layer number that the target node is on.
 
-#endif //VTR_ROUTER_LOOKAHEAD_SPARSE_MAP_H
+#endif //VTR_ROUTER_LOOKAHEAD_COMPRESSED_MAP_H

vpr/src/route/router_lookahead_cost_map.cpp

@@ -26,6 +26,14 @@ static constexpr float PENALTY_FACTOR = 1.f;
 ///@brief Minimum penalty cost that is added when penalizing a delta outside the segment bounding box.
 static constexpr float PENALTY_MIN = 1e-12f;
 
+/**
+ * @brief Store the minimum delay and congestion between `min_cost` and `new_cost` in `min_cost`.
+ * @attention The cost in either min_cost or new_cost can be invalid.
+ * @param min_cost
+ * @param new_cost
+ */
+static void assign_min_entry(util::Cost_Entry& min_cost, const util::Cost_Entry& new_cost);
+
 // also known as the L1 norm
 static int manhattan_distance(const vtr::Point<int>& a, const vtr::Point<int>& b) {
     return abs(b.x() - a.x()) + abs(b.y() - a.y());
@@ -341,21 +349,21 @@ std::vector<std::pair<int, int>> CostMap::list_empty() const {
     return results;
 }
 
-static void assign_min_entry(util::Cost_Entry* dst, const util::Cost_Entry& src) {
+static void assign_min_entry(util::Cost_Entry& min_cost, const util::Cost_Entry& new_cost) {
     // The values in src is only being assigned to dst if they are valid
-    if (!std::isnan(src.delay)) {
-        if (std::isnan(dst->delay)) {
-            dst->delay = src.delay;
+    if (!std::isnan(new_cost.delay)) {
+        if (std::isnan(min_cost.delay)) {
+            min_cost.delay = new_cost.delay;
         } else {
-            dst->delay = std::min(dst->delay, src.delay);
+            min_cost.delay = std::min(min_cost.delay, new_cost.delay);
         }
     }
 
-    if (!std::isnan(src.congestion)) {
-        if (std::isnan(dst->congestion)) {
-            dst->congestion = src.congestion;
+    if (!std::isnan(new_cost.congestion)) {
+        if (std::isnan(min_cost.congestion)) {
+            min_cost.congestion = new_cost.congestion;
         } else {
-            dst->congestion = std::min(dst->congestion, src.congestion);
+            min_cost.congestion = std::min(min_cost.congestion, new_cost.congestion);
         }
     }
 }
@@ -384,11 +392,11 @@ std::pair<util::Cost_Entry, int> CostMap::get_nearby_cost_entry(const vtr::NdMat
             int yp = cy + oy;
             int yn = cy - oy;
             if (bounds.contains(vtr::Point<int>(x, yp))) {
-                assign_min_entry(&min_entry, matrix[x][yp]);
+                assign_min_entry(min_entry, matrix[x][yp]);
                 in_bounds = true;
             }
             if (bounds.contains(vtr::Point<int>(x, yn))) {
-                assign_min_entry(&min_entry, matrix[x][yn]);
+                assign_min_entry(min_entry, matrix[x][yn]);
                 in_bounds = true;
             }
         }

vpr/src/route/router_lookahead_map.cpp

@@ -50,6 +50,8 @@
 #    include "serdes_utils.h"
 #endif /* VTR_ENABLE_CAPNPROTO */
 
+const int VALID_NEIGHBOR_NUMBER = 3;
+
 /* when a list of delay/congestion entries at a coordinate in Cost_Entry is boiled down to a single
  * representative entry, this enum is passed-in to specify how that representative entry should be
  * calculated */
@@ -142,6 +144,18 @@ static void fill_in_missing_lookahead_entries(int segment_index, e_rr_type chan_
 /* returns a cost entry in the f_wire_cost_map that is near the specified coordinates (and preferably towards (0,0)) */
 static util::Cost_Entry get_nearby_cost_entry(int from_layer_num, int x, int y, int to_layer_num, int segment_index, int chan_index);
 
+/**
+ * @brief Fill in the missing entry in router lookahead map
+ * If there is a missing entry in the router lookahead, search among its neighbors in a 3x3 window. If there are `VALID_NEIGHBOR_NUMBER` valid entries,
+ * take the average of them and fill in the missing entry.
+ * @param from_layer_num The layer num of the source node
+ * @param missing_dx Dx of the missing input
+ * @param missing_dy Dy of the missing input
+ * @param to_layer_num The layer num of the destination point
+ * @param segment_index The segment index of the source node
+ * @param chan_index The channel index of the source node
+ * @return The cost for the missing entry
+ */
 static util::Cost_Entry get_nearby_cost_entry_average_neighbour(int from_layer_num,
                                                                 int missing_dx,
                                                                 int missing_dy,
@@ -641,13 +655,14 @@ static util::Cost_Entry get_nearby_cost_entry_average_neighbour(int from_layer_n
                                                                 int to_layer_num,
                                                                 int segment_index,
                                                                 int chan_index) {
+    // Make sure that the given loaction doesn't have a valid entry
     VTR_ASSERT(std::isnan(f_wire_cost_map[from_layer_num][chan_index][segment_index][to_layer_num][missing_dx][missing_dy].delay));
     VTR_ASSERT(std::isnan(f_wire_cost_map[from_layer_num][chan_index][segment_index][to_layer_num][missing_dx][missing_dy].congestion));
 
-    int neighbour_num = 0;
-    float neighbour_delay_sum = 0;
-    float neighbour_cong_sum = 0;
-    std::array<int, 3> window = {-1, 0, 1};
+    int neighbour_num = 0; // Number of neighbours with valid entry
+    float neighbour_delay_sum = 0; // Acc of valid delay costs
+    float neighbour_cong_sum = 0; // Acc of valid congestion costs
+    std::array<int, 3> window = {-1, 0, 1}; // Average window size
     for (int dx : window) {
         int neighbour_x = missing_dx + dx;
         if (neighbour_x < 0 || neighbour_x >= (int)f_wire_cost_map.dim_size(4)) {
@@ -668,10 +683,12 @@ static util::Cost_Entry get_nearby_cost_entry_average_neighbour(int from_layer_n
         }
     }
 
-    if (neighbour_num >= 3) {
+    // Store the average only if there are enough number of neighbours with valid entry
+    if (neighbour_num >= VALID_NEIGHBOR_NUMBER) {
         return {neighbour_delay_sum / static_cast<float>(neighbour_num),
                 neighbour_cong_sum / static_cast<float>(neighbour_num)};
     } else {
+        // If there are not enough neighbours with valid entry, retrieve to the previous way of getting the missing cost
         return get_nearby_cost_entry(from_layer_num, missing_dx, missing_dy, to_layer_num, segment_index, chan_index);
     }
 }