[RouterLookahead] Router Lookahead Report

Added an option to generate a report on the router lookahead. This
reports profiles the router lookahead by performing a set of trial
routes from source RR nodes to all target RR nodes and comparing the
estimated cost from the router lookahead to the actual cost of the path.

Notably, this report tries to show the mean squared error of the router
lookahead and the maximum overestimation of the router lookahead.

The mean squared error is a measure of how accurate the router lookahead
is. The more accurate the router lookahead is, the faster the path
search will be (with less loss in quality). The max overestimation is a
measure of the admissibility of the router lookahead heuristic. The more
the router lookahead overestimates, the worse the quality of the path
found (theoretically).

Author: AlexandreSinger

doc/src/vpr/command_line_usage.rst

@@ -1840,6 +1840,17 @@ The following options are only valid when the router is in timing-driven mode (t
 
      **Default:** ``map``
 
+.. option:: --generate_router_lookahead_report {on | off}
+
+   If turned on, generates a detailed report on the router lookahead: report_router_lookahead.rpt
+
+   This report contains information on how accurate the router lookahead is and
+   if and when it overestimates the cost from a node to a target node. It does
+   this by doing a set of trial routes and comparing the estimated cost from the
+   router lookahead to the actual cost of the route path.
+
+   **Default:** ``off``
+
 .. option:: --router_initial_acc_cost_chan_congestion_threshold <float>
 
     Utilization threshold above which initial accumulated routing cost (acc_cost) is increased to penalize congested channels.

libs/librrgraph/src/base/rr_node_types.h

@@ -32,6 +32,31 @@ enum class e_rr_type : unsigned char {
     NUM_RR_TYPES
 };
 
+/**
+ * @brief Get the string representation of the given node type. This is useful
+ *        for logging the type of an RR node.
+ */
+inline std::string get_rr_node_type_str(e_rr_type type) {
+    switch (type) {
+        case e_rr_type::SOURCE:
+            return "SOURCE";
+        case e_rr_type::SINK:
+            return "SINK";
+        case e_rr_type::IPIN:
+            return "IPIN";
+        case e_rr_type::OPIN:
+            return "OPIN";
+        case e_rr_type::CHANX:
+            return "CHANX";
+        case e_rr_type::CHANY:
+            return "CHANY";
+        case e_rr_type::NUM_RR_TYPES:
+            return "NUM_RR_TYPES";
+        default:
+            return "UNKNOWN";
+    }
+}
+
 /// Used to iterate for different e_rr_type values in range-based for loops.
 constexpr std::array<e_rr_type, (size_t)e_rr_type::NUM_RR_TYPES> RR_TYPES = {{e_rr_type::SOURCE, e_rr_type::SINK, e_rr_type::IPIN,
                                                                       e_rr_type::OPIN, e_rr_type::CHANX, e_rr_type::CHANY}};

vpr/src/base/SetupVPR.cpp

@@ -516,6 +516,8 @@ static void SetupRouterOpts(const t_options& Options, t_router_opts* RouterOpts)
     RouterOpts->has_choke_point = Options.router_opt_choke_points;
     RouterOpts->custom_3d_sb_fanin_fanout = Options.custom_3d_sb_fanin_fanout;
     RouterOpts->with_timing_analysis = Options.timing_analysis;
+
+    RouterOpts->generate_router_lookahead_report = Options.generate_router_lookahead_report.value();
 }
 
 static void SetupAnnealSched(const t_options& Options,

vpr/src/base/ShowSetup.cpp

@@ -383,7 +383,7 @@ static void ShowRouterOpts(const t_router_opts& RouterOpts) {
         VTR_LOG("RouterOpts.router_profiler_astar_fac: %f\n", RouterOpts.router_profiler_astar_fac);
         VTR_LOG("RouterOpts.enable_parallel_connection_router: %s\n", RouterOpts.enable_parallel_connection_router ? "true" : "false");
         VTR_LOG("RouterOpts.post_target_prune_fac: %f\n", RouterOpts.post_target_prune_fac);
-        VTR_LOG("RouterOpts.post_target_prune_offset: %f\n", RouterOpts.post_target_prune_offset);
+        VTR_LOG("RouterOpts.post_target_prune_offset: %g\n", RouterOpts.post_target_prune_offset);
         VTR_LOG("RouterOpts.multi_queue_num_threads: %d\n", RouterOpts.multi_queue_num_threads);
         VTR_LOG("RouterOpts.multi_queue_num_queues: %d\n", RouterOpts.multi_queue_num_queues);
         VTR_LOG("RouterOpts.multi_queue_direct_draining: %s\n", RouterOpts.multi_queue_direct_draining ? "true" : "false");

vpr/src/base/read_options.cpp

@@ -2936,6 +2936,16 @@ argparse::ArgumentParser create_arg_parser(const std::string& prog_name, t_optio
         .default_value("map")
         .show_in(argparse::ShowIn::HELP_ONLY);
 
+    route_timing_grp.add_argument<bool, ParseOnOff>(args.generate_router_lookahead_report, "--generate_router_lookahead_report")
+        .help("If turned on, generates a detailed report on the router lookahead: report_router_lookahead.rpt\n"
+              "\n"
+              "This report contains information on how accurate the router lookahead is and "
+              "if and when it overestimates the cost from a node to a target node. It does "
+              "this by doing a set of trial routes and comparing the estimated cost from the "
+              "router lookahead to the actual cost of the route path.")
+        .default_value("off")
+        .show_in(argparse::ShowIn::HELP_ONLY);
+
     route_timing_grp.add_argument<double>(args.router_initial_acc_cost_chan_congestion_threshold, "--router_initial_acc_cost_chan_congestion_threshold")
         .help("Utilization threshold above which initial accumulated routing cost (acc_cost) "
               "is increased to penalize congested channels. Used to bias routing away from "

vpr/src/base/read_options.h

@@ -256,6 +256,7 @@ struct t_options {
     argparse::ArgValue<int> router_debug_sink_rr;
     argparse::ArgValue<int> router_debug_iteration;
     argparse::ArgValue<e_router_lookahead> router_lookahead_type;
+    argparse::ArgValue<bool> generate_router_lookahead_report;
     argparse::ArgValue<double> router_initial_acc_cost_chan_congestion_threshold;
     argparse::ArgValue<double> router_initial_acc_cost_chan_congestion_weight;
     argparse::ArgValue<int> router_max_convergence_count;

vpr/src/base/vpr_types.h

@@ -1347,6 +1347,8 @@ struct t_router_opts {
     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;
+
+    bool generate_router_lookahead_report;
 };
 
 struct t_analysis_opts {

vpr/src/route/route.cpp

@@ -10,6 +10,7 @@
 #include "route_profiling.h"
 #include "route_utils.h"
 #include "rr_graph.h"
+#include "router_lookahead_report.h"
 #include "vtr_time.h"
 
 bool route(const Netlist<>& net_list,
@@ -152,6 +153,12 @@ bool route(const Netlist<>& net_list,
 
     VTR_ASSERT(router_lookahead != nullptr);
 
+    // After the router lookahead has been fully created, generate the router
+    // lookahead report if requested.
+    if (router_opts.generate_router_lookahead_report) {
+        generate_router_lookahead_report(router_lookahead, router_opts);
+    }
+
     /* Routing parameters */
     float pres_fac = router_opts.first_iter_pres_fac;
     update_draw_pres_fac(pres_fac); /* Typically 0 -> ignore cong. */