Add requested documentation

Author: HackerFoo

vpr/src/base/read_options.cpp

@@ -164,8 +164,8 @@ struct ParseRouterAlgorithm {
 };
 
 struct ParseNodeReorderAlgorithm {
-    ConvertedValue<e_node_reorder_algorithm> from_str(std::string str) {
-        ConvertedValue<e_node_reorder_algorithm> conv_value;
+    ConvertedValue<e_rr_node_reorder_algorithm> from_str(std::string str) {
+        ConvertedValue<e_rr_node_reorder_algorithm> conv_value;
         if (str == "none")
             conv_value.set_value(DONT_REORDER);
         else if (str == "degree_bfs")
@@ -174,13 +174,13 @@ struct ParseNodeReorderAlgorithm {
             conv_value.set_value(RANDOM_SHUFFLE);
         else {
             std::stringstream msg;
-            msg << "Invalid conversion from '" << str << "' to e_node_reorder_algorithm (expected one of: " << argparse::join(default_choices(), ", ") << ")";
+            msg << "Invalid conversion from '" << str << "' to e_rr_node_reorder_algorithm (expected one of: " << argparse::join(default_choices(), ", ") << ")";
             conv_value.set_error(msg.str());
         }
         return conv_value;
     }
 
-    ConvertedValue<std::string> to_str(e_node_reorder_algorithm val) {
+    ConvertedValue<std::string> to_str(e_rr_node_reorder_algorithm val) {
         ConvertedValue<std::string> conv_value;
         if (val == DONT_REORDER)
             conv_value.set_value("none");
@@ -1932,7 +1932,7 @@ argparse::ArgumentParser create_arg_parser(std::string prog_name, t_options& arg
         .default_value("off")
         .show_in(argparse::ShowIn::HELP_ONLY);
 
-    route_grp.add_argument<e_node_reorder_algorithm, ParseNodeReorderAlgorithm>(args.reorder_rr_graph_nodes_algorithm, "--reorder_rr_graph_nodes_algorithm")
+    route_grp.add_argument<e_rr_node_reorder_algorithm, ParseNodeReorderAlgorithm>(args.reorder_rr_graph_nodes_algorithm, "--reorder_rr_graph_nodes_algorithm")
         .help(
             "Specifies the node reordering algorithm to use.\n"
             " * none: don't reorder nodes\n"

vpr/src/base/read_options.h

@@ -150,7 +150,7 @@ struct t_options {
     argparse::ArgValue<e_check_route_option> check_route;
     argparse::ArgValue<size_t> max_logged_overused_rr_nodes;
     argparse::ArgValue<bool> generate_rr_node_overuse_report;
-    argparse::ArgValue<e_node_reorder_algorithm> reorder_rr_graph_nodes_algorithm;
+    argparse::ArgValue<e_rr_node_reorder_algorithm> reorder_rr_graph_nodes_algorithm;
     argparse::ArgValue<int> reorder_rr_graph_nodes_threshold;
     argparse::ArgValue<int> reorder_rr_graph_nodes_seed;
 

vpr/src/base/vpr_types.h

@@ -977,7 +977,8 @@ enum e_router_algorithm {
     TIMING_DRIVEN,
 };
 
-enum e_node_reorder_algorithm {
+// Node reordering algorithms for rr_nodes
+enum e_rr_node_reorder_algorithm {
     DONT_REORDER,
     DEGREE_BFS,
     RANDOM_SHUFFLE,
@@ -1035,9 +1036,6 @@ enum class e_incr_reroute_delay_ripup {
 constexpr int NO_FIXED_CHANNEL_WIDTH = -1;
 
 struct t_router_opts {
-    e_node_reorder_algorithm reorder_rr_graph_nodes_algorithm = DONT_REORDER;
-    int reorder_rr_graph_nodes_threshold = 0;
-    int reorder_rr_graph_nodes_seed = 1;
     bool read_rr_edge_metadata = false;
     bool do_check_rr_graph = true;
     float first_iter_pres_fac;
@@ -1097,6 +1095,11 @@ struct t_router_opts {
 
     size_t max_logged_overused_rr_nodes;
     bool generate_rr_node_overuse_report;
+
+    // Options related to rr_node reordering, for testing and possible cache optimization
+    e_rr_node_reorder_algorithm reorder_rr_graph_nodes_algorithm = DONT_REORDER;
+    int reorder_rr_graph_nodes_threshold = 0;
+    int reorder_rr_graph_nodes_seed = 1;
 };
 
 struct t_analysis_opts {

vpr/src/route/rr_graph_storage.cpp

@@ -740,9 +740,24 @@ t_rr_graph_view t_rr_graph_storage::view() const {
         vtr::make_const_array_view_id(edge_switch_));
 }
 
+// Given `order`, a vector mapping each RRNodeId to a new one (old -> new),
+// and `inverse_order`, its inverse (new -> old), update the t_rr_graph_storage
+// data structure to an isomorphic graph using the new RRNodeId's.
+//
+// Because the RRNodeId's affect the memory layout, this can be used to
+// optimize cache locality.
+//
+// Preconditions:
+//   order[inverse_order[x]] == x
+//   inverse_order[order[x]] == x
+//   x != y <===> order[x] != order[y]
+//
+// NOTE: Re-ordering will invalidate any external references, so this
+//       should generally be called before creating such references.
 void t_rr_graph_storage::reorder(const vtr::vector<RRNodeId, RRNodeId>& order,
                                  const vtr::vector<RRNodeId, RRNodeId>& inverse_order) {
     VTR_ASSERT_SAFE(validate());
+    VTR_ASSERT(order.size() == inverse_order.size());
     {
         auto old_node_storage = node_storage_;
 

vpr/src/route/rr_graph_storage.h

@@ -435,6 +435,12 @@ class t_rr_graph_storage {
         node_storage_.emplace_back();
         node_ptc_.emplace_back();
     }
+
+    // Given `order`, a vector mapping each RRNodeId to a new one (old -> new),
+    // and `inverse_order`, its inverse (new -> old), update the t_rr_graph_storage
+    // data structure to an isomorphic graph using the new RRNodeId's.
+    // NOTE: Re-ordering will invalidate any external references, so this
+    //       should generally be called before creating such references.
     void reorder(const vtr::vector<RRNodeId, RRNodeId>& order,
                  const vtr::vector<RRNodeId, RRNodeId>& inverse_order);
 

vpr/src/route/rr_graph_util.cpp

@@ -81,6 +81,18 @@ int seg_index_of_sblock(int from_node, int to_node) {
     }
 }
 
+// Reorder RRNodeId's using one of these algorithms:
+//   - DONT_REORDER: The identity reordering (does nothing.)
+//   - DEGREE_BFS: Order by degree primarily, and BFS traversal order secondarily.
+//   - RANDOM_SHUFFLE: Shuffle using the specified seed. Great for testing.
+// The DEGREE_BFS algorithm was selected because it had the best performance of seven
+// existing algorithms here: https://github.com/SymbiFlow/vtr-rrgraph-reordering-tool
+// It might be worth further research, as the DEGREE_BFS algorithm is simple and
+// makes some arbitrary choices, such as the starting node.
+// Nonetheless, it does improve performance ~7% for the SymbiFlow Xilinx Artix 7 graph.
+//
+// NOTE: Re-ordering will invalidate any references to rr_graph nodes, so this
+//       should generally be called before creating such references.
 void reorder_rr_graph_nodes(const t_router_opts& router_opts) {
     auto& device_ctx = g_vpr_ctx.mutable_device();
     auto& graph = device_ctx.rr_nodes;
@@ -97,11 +109,15 @@ void reorder_rr_graph_nodes(const t_router_opts& router_opts) {
         n = RRNodeId(cur_idx++);
     }
 
+    // This method works well. The intution is that highly connected nodes are enumerated first (together),
+    // and since there will be a lot of nodes with the same degree, they are then ordered based on some
+    // distance from the starting node.
     if (router_opts.reorder_rr_graph_nodes_algorithm == DEGREE_BFS) {
         vtr::vector<RRNodeId, size_t> bfs_idx(v_num);
         vtr::vector<RRNodeId, size_t> degree(v_num);
         std::queue<RRNodeId> que;
 
+        // Compute both degree (in + out) and an index based on the BFS traversal
         cur_idx = 0;
         for (size_t i = 0; i < v_num; ++i) {
             if (bfs_idx[RRNodeId(i)]) continue;
@@ -121,6 +137,7 @@ void reorder_rr_graph_nodes(const t_router_opts& router_opts) {
             }
         }
 
+        // Sort by degree primarily, and BFS order secondarily
         sort(src_order.begin(), src_order.end(),
              [&](auto a, auto b) -> bool {
                  auto deg_a = degree[a];
@@ -138,7 +155,7 @@ void reorder_rr_graph_nodes(const t_router_opts& router_opts) {
 
     graph.reorder(dest_order, src_order);
 
-    // update rr_node_indices
+    // update rr_node_indices, a map to optimize rr_index lookups
     for (auto& grid : device_ctx.rr_node_indices) {
         for (size_t x = 0; x < grid.dim_size(0); x++) {
             for (size_t y = 0; y < grid.dim_size(1); y++) {