Improved the comments in overuse_report.h and overuse_report.cpp. Changed all major comments to Doxygen style. Added subtile occupany checking in t_grid_blocks. Fixed a bug where the overuse report may try to print out information for EMPTY_BLOCK_ID when overused IPIN/OPIN nodes are unoccupied by clustered blocks.

Author: Bill-hbrhbr

vpr/src/base/vpr_types.h

@@ -706,8 +706,25 @@ struct t_block_loc {
 
 ///@brief Stores the clustered blocks placed at a particular grid location
 struct t_grid_blocks {
-    int usage;                          ///<How many valid blocks are in use at this location
-    std::vector<ClusterBlockId> blocks; ///<The clustered blocks associated with this grid location
+    int usage; ///<How many valid blocks are in use at this location
+
+    /**
+     * @brief The clustered blocks associated with this grid location.
+     *
+     * Index range: [0..device_ctx.grid[x_loc][y_loc].type->capacity]
+     */
+    std::vector<ClusterBlockId> blocks;
+
+    /**
+     * @brief Test if a subtile at a grid location is occupied by a block.
+     *
+     * Returns true if the subtile corresponds to the passed-in id is not
+     * occupied by a block at this grid location. The subtile id serves
+     * as the z-dimensional offset in the grid indexing.
+     */
+    inline bool subtile_empty(size_t isubtile) {
+        return blocks[isubtile] == EMPTY_BLOCK_ID;
+    }
 };
 
 ///@brief Names of various files

vpr/src/route/overuse_report.cpp

@@ -4,6 +4,14 @@
 #include "globals.h"
 #include "vtr_log.h"
 
+/**
+ * @brief Definitions of global and helper routines related to printing RR node overuse info.
+ *
+ * All the global routines defined here are declared in the header file overuse_report.h
+ * The helper routines that are called by the global routine should stay local to this file.
+ * They provide subroutine hierarchy to allow easier customization of the logfile/report format.
+ */
+
 static void report_overused_ipin_opin(std::ostream& os, RRNodeId node_id);
 static void report_overused_chanx_chany(std::ostream& os, RRNodeId node_id);
 static void report_overused_source_sink(std::ostream& os, RRNodeId node_id);
@@ -12,6 +20,12 @@ static void report_congested_nets(std::ostream& os, const std::set<ClusterNetId>
 static void log_overused_nodes_header();
 static void log_single_overused_node_status(int overuse_index, RRNodeId inode);
 
+/**
+ * @brief Print out RR node overuse info in the VPR logfile.
+ *
+ * Print out limited amount of overused node info in the vpr.out logfile.
+ * The limit is specified by the VPR option --max_logged_overused_rr_nodes
+ */
 void log_overused_nodes_status(int max_logged_overused_rr_nodes) {
     const auto& device_ctx = g_vpr_ctx.device();
     const auto& route_ctx = g_vpr_ctx.routing();
@@ -36,36 +50,43 @@ void log_overused_nodes_status(int max_logged_overused_rr_nodes) {
     }
 }
 
+/**
+ * @brief Print out RR node overuse info in a post-VPR report file.
+ *
+ * Print all the overused RR nodes' info in the report file report_overused_nodes.rpt.
+ * The report generation is turned on by the VPR option: --generate_rr_node_overuse_report on.
+ */
 void report_overused_nodes() {
     const auto& device_ctx = g_vpr_ctx.device();
     const auto& route_ctx = g_vpr_ctx.routing();
 
-    //Generate overuse info lookup table
+    /* Generate overuse info lookup table */
     std::map<RRNodeId, std::set<ClusterNetId>> nodes_to_nets_lookup;
     generate_overused_nodes_to_congested_net_lookup(nodes_to_nets_lookup);
 
-    //Open the report file
+    /* Open the report file and print header info */
     std::ofstream os("report_overused_nodes.rpt");
     os << "Overused nodes information report on the final failed routing attempt" << '\n';
     os << "Total number of overused nodes = " << nodes_to_nets_lookup.size() << '\n';
 
+    /* Go through each rr node and the nets that pass through it */
     size_t inode = 0;
     for (const auto& lookup_pair : nodes_to_nets_lookup) {
         const RRNodeId node_id = lookup_pair.first;
         const auto& congested_nets = lookup_pair.second;
 
-        os << "************************************************\n\n"; //RR Node Separation line
+        os << "************************************************\n\n"; //Separation line
 
-        //Report Basic info
+        /* Report basic rr node info */
         os << "Overused RR node #" << inode << '\n';
         os << "Node id = " << size_t(node_id) << '\n';
         os << "Occupancy = " << route_ctx.rr_node_route_inf[size_t(node_id)].occ() << '\n';
         os << "Capacity = " << device_ctx.rr_nodes.node_capacity(node_id) << "\n\n";
 
-        //Report Selective info
+        /* Report selective info based on the rr node type */
+        auto node_type = device_ctx.rr_nodes.node_type(node_id);
         os << "Node type = " << device_ctx.rr_nodes.node_type_string(node_id) << '\n';
 
-        auto node_type = device_ctx.rr_nodes.node_type(node_id);
         switch (node_type) {
             case IPIN:
             case OPIN:
@@ -84,7 +105,9 @@ void report_overused_nodes() {
                 break;
         }
 
-        os << "-----------------------------\n"; //Node/net info separation line
+        /* Finished printing the node info. Now print out the  *
+         * info on the nets passing through this overused node */
+        os << "-----------------------------\n"; //Separation line
         report_congested_nets(os, congested_nets);
 
         ++inode;
@@ -93,6 +116,15 @@ void report_overused_nodes() {
     os.close();
 }
 
+/**
+ * @brief Generate a overused RR nodes to congested nets lookup table.
+ *
+ * Uses map data structure to store a lookup table that matches RR nodes
+ * to the nets that pass through them. Only overused nodes and congested
+ * nets will be recorded.
+ *
+ * This routine goes through the trace back linked list of each net.
+ */
 void generate_overused_nodes_to_congested_net_lookup(std::map<RRNodeId, std::set<ClusterNetId>>& nodes_to_nets_lookup) {
     const auto& device_ctx = g_vpr_ctx.device();
     const auto& route_ctx = g_vpr_ctx.routing();
@@ -112,6 +144,7 @@ void generate_overused_nodes_to_congested_net_lookup(std::map<RRNodeId, std::set
     }
 }
 
+///@brief Print out information specific to IPIN/OPIN type rr nodes
 static void report_overused_ipin_opin(std::ostream& os, RRNodeId node_id) {
     const auto& device_ctx = g_vpr_ctx.device();
     const auto& place_ctx = g_vpr_ctx.placement();
@@ -128,33 +161,47 @@ static void report_overused_ipin_opin(std::ostream& os, RRNodeId node_id) {
     //Add block type for IPINs/OPINs in overused rr-node report
     const auto& clb_nlist = g_vpr_ctx.clustering().clb_nlist;
     auto& grid_info = place_ctx.grid_blocks[grid_x][grid_y];
-    auto& grid_blocks = grid_info.blocks;
 
     os << "Grid location: X = " << grid_x << ", Y = " << grid_y << '\n';
-    os << "Number of blocks currently at this grid location = " << grid_info.usage << '\n';
-    for (size_t iblock = 0; iblock < grid_blocks.size(); ++iblock) {
-        ClusterBlockId block_id = grid_blocks[iblock];
+    os << "Number of blocks currently occupying this grid location = " << grid_info.usage << '\n';
+
+    size_t iblock = 0;
+    for (size_t isubtile = 0; isubtile < grid_blocks.size(); ++isubtile) {
+        //Check if the block is empty
+        if (grid_info.subtile_empty[isubtile]) {
+            continue;
+        }
+
+        //Print out the block index, name and type
+        ClusterBlockId block_id = grid_info.blocks[isubtile];
         os << "Block #" << iblock << ": ";
         os << "Block name = " << clb_nlist.block_pb(block_id)->name << ", ";
         os << "Block type = " << clb_nlist.block_type(block_id)->name << '\n';
+        ++iblock;
     }
 }
 
+///@brief Print out information specific to CHANX/CHANY type rr nodes
 static void report_overused_chanx_chany(std::ostream& os, RRNodeId node_id) {
     const auto& device_ctx = g_vpr_ctx.device();
 
     os << "Track number = " << device_ctx.rr_nodes.node_track_num(node_id) << '\n';
     os << "Direction = " << device_ctx.rr_nodes.node_direction_string(node_id) << "\n\n";
 
+    //CHANX/CHANY rr nodes span across several grid locations.
+    //Need to print out their starting and ending locations.
     os << "Grid location: " << '\n';
     os << "Xlow = " << device_ctx.rr_nodes.node_xlow(node_id) << ", ";
     os << "Ylow = " << device_ctx.rr_nodes.node_ylow(node_id) << '\n';
     os << "Xhigh = " << device_ctx.rr_nodes.node_xhigh(node_id) << ", ";
     os << "Yhigh = " << device_ctx.rr_nodes.node_yhigh(node_id) << '\n';
+
+    //Print out associated RC characteristics as they will be non-zero
     os << "Resistance = " << device_ctx.rr_nodes.node_R(node_id) << '\n';
     os << "Capacitance = " << device_ctx.rr_nodes.node_C(node_id) << '\n';
 }
 
+///@brief Print out information specific to SOURCE/SINK type rr nodes
 static void report_overused_source_sink(std::ostream& os, RRNodeId node_id) {
     const auto& device_ctx = g_vpr_ctx.device();
 
@@ -168,7 +215,13 @@ static void report_overused_source_sink(std::ostream& os, RRNodeId node_id) {
     os << "Grid location: X = " << grid_x << ", Y = " << grid_y << '\n';
 }
 
-//Reported congested nets at a specific rr node
+/**
+ * @brief Print out info on congested nets in the router.
+ *
+ * Report information on the congested nets that pass through a specific rr node. *
+ * These nets are congested because the number of nets currently passing through  *
+ * this rr node exceed the node's routing net capacity.
+ */
 static void report_congested_nets(std::ostream& os, const std::set<ClusterNetId>& congested_nets) {
     const auto& clb_nlist = g_vpr_ctx.clustering().clb_nlist;
     os << "Number of nets passing through this RR node = " << congested_nets.size() << '\n';
@@ -186,6 +239,7 @@ static void report_congested_nets(std::ostream& os, const std::set<ClusterNetId>
     os << '\n';
 }
 
+///@brief Print out the header of the overused rr node info in the logfile
 static void log_overused_nodes_header() {
     VTR_LOG("Routing Failure Diagnostics: Printing Overused Nodes Information\n");
     VTR_LOG("------ ------- ---------- --------- -------- ------------ ------- ------- ------- ------- ------- -------\n");
@@ -194,6 +248,7 @@ static void log_overused_nodes_header() {
     VTR_LOG("------ ------- ---------- --------- -------- ------------ ------- ------- ------- ------- ------- -------\n");
 }
 
+///@brief Print out a single-line info that corresponds to a single overused rr node in the logfile
 static void log_single_overused_node_status(int overuse_index, RRNodeId node_id) {
     const auto& device_ctx = g_vpr_ctx.device();
     const auto& route_ctx = g_vpr_ctx.routing();

vpr/src/route/overuse_report.h

@@ -3,6 +3,25 @@
 #include "rr_graph_storage.h"
 #include <map>
 
+/**
+ * @brief Global routines related to displaying RR node overuse info.
+ *
+ * This file contains all the routines that print out the information on overused RR nodes
+ * and congested nets. The main purpose of these routines is to aid the debugging process
+ * should the VPR fail to implement the circuit. Functionalities that resolve these circuit
+ * issues should NOT be included here or in overuse_report.cpp
+ *
+ * An RR node is overused when the number of nets passing through it exceed the node's
+ * routing net capacity. A successfully routed circuit is void of these overused nodes.
+ *
+ * All the nets passing through an overused RR node are flagged as congested nets.
+ */
+
+///@brief Print out RR node overuse info in the VPR logfile.
 void log_overused_nodes_status(int max_logged_overused_rr_nodes);
+
+///@brief Print out RR node overuse info in a post-VPR report file.
 void report_overused_nodes();
+
+///@brief Generate a overused RR nodes to congested nets lookup table.
 void generate_overused_nodes_to_congested_net_lookup(std::map<RRNodeId, std::set<ClusterNetId>>& nodes_to_nets_lookup);