comments and moving header includes to source files

Author: soheilshahrouz

vpr/src/noc/bfs_routing.cpp

@@ -1,4 +1,5 @@
-#
+
+#include <queue>
 
 #include "bfs_routing.h"
 
@@ -19,7 +20,7 @@ void BFSRouting::route_flow(NocRouterId src_router_id,
      * Keeps track of which routers have been reached already
      * while traversing the NoC. This variable will help prevent 
      * the algorithm from getting stuck visiting routers that
-     * jave already been visited.
+     * have already been visited.
      * 
      */
     std::unordered_set<NocRouterId> visited_routers;
@@ -50,7 +51,7 @@ void BFSRouting::route_flow(NocRouterId src_router_id,
     }
 
     // Explore the NoC from the starting router and try to find a path to the destination router
-    // We finish searching when there are no more routers to process or we found the destination router
+    // We finish searching when there are no more routers to process, or we found the destination router
     while (!routers_to_process.empty() && !found_sink_router) {
         // get the next router to process
         NocRouterId processing_router = routers_to_process.front();
@@ -92,13 +93,17 @@ void BFSRouting::route_flow(NocRouterId src_router_id,
         generate_route(sink_router_id, flow_route, noc_model, router_parent_link);
     } else {
         // a path was not found so throw an error to the user
-        VPR_FATAL_ERROR(VPR_ERROR_OTHER, "No route could be found from starting router with id:'%d' and the destination router with id:'%d' using the breadth-first search routing algorithm.", src_router.get_router_user_id(), sink_router.get_router_user_id());
+        VPR_FATAL_ERROR(VPR_ERROR_OTHER,
+                        "No route could be found from starting router with id:'%d' and the destination router with id:'%d' using the breadth-first search routing algorithm.",
+                        src_router.get_router_user_id(),
+                        sink_router.get_router_user_id());
     }
-
-    return;
 }
 
-void BFSRouting::generate_route(NocRouterId start_router_id, std::vector<NocLinkId>& flow_route, const NocStorage& noc_model, const std::unordered_map<NocRouterId, NocLinkId>& router_parent_link) {
+void BFSRouting::generate_route(NocRouterId start_router_id,
+                                std::vector<NocLinkId>& flow_route,
+                                const NocStorage& noc_model,
+                                const std::unordered_map<NocRouterId, NocLinkId>& router_parent_link) {
     // The intermediate router being visited while tracing the path back from the destination router to the starting router in the flow.
     // Initially this is set to the router at the end of the path (destination router)
     NocRouterId curr_intermediate_router = start_router_id;
@@ -108,11 +113,11 @@ void BFSRouting::generate_route(NocRouterId start_router_id, std::vector<NocLink
     auto route_beginning = flow_route.begin();
 
     // get the parent link of the start router
-    std::unordered_map<NocRouterId, NocLinkId>::const_iterator curr_intermediate_router_parent_link = router_parent_link.find(curr_intermediate_router);
+    auto curr_intermediate_router_parent_link = router_parent_link.find(curr_intermediate_router);
 
-    // keep tracking baackwards from each router in the path until a router doesn't have a parent link (this means we reached the starting router in the flow)
+    // keep tracking backwards from each router in the path until a router doesn't have a parent link (this means we reached the starting router in the flow)
     while (curr_intermediate_router_parent_link != router_parent_link.end()) {
-        // add the parent link to the path. Since we are tracing backwards we need to store the links in fron of the last link.
+        // add the parent link to the path. Since we are tracing backwards we need to store the links in front of the last link.
         flow_route.emplace(route_beginning, curr_intermediate_router_parent_link->second);
 
         // update the reference to the beginning of the route
@@ -123,6 +128,4 @@ void BFSRouting::generate_route(NocRouterId start_router_id, std::vector<NocLink
         // now get the parent of the router we moved to
         curr_intermediate_router_parent_link = router_parent_link.find(curr_intermediate_router);
     }
-
-    return;
 }

vpr/src/noc/bfs_routing.h

@@ -14,13 +14,13 @@
  * traffic flow. Once the destination router is found a path from the source to
  * the destination router is generated. The main advantage of this algorithm is
  * that the found path from the source to the destination router uses the 
- * minimum number of links required within the NoC.
- * 
+ * minimum number of links required within the NoC. This algorithm does not
+ * guarantee deadlock freedom. In other words, the algorithm might generate
+ * routes that form cycles in channel dependency graph.
  */
 
 #include <vector>
 #include <unordered_map>
-#include <queue>
 
 #include "noc_routing.h"
 
@@ -81,7 +81,10 @@ class BFSRouting : public NocRouting {
      * router in the NoC (parent link is the link used to visit the router during
      * the BFS routing algorithm).
      */
-    void generate_route(NocRouterId sink_router_id, std::vector<NocLinkId>& flow_route, const NocStorage& noc_model, const std::unordered_map<NocRouterId, NocLinkId>& router_parent_link);
+    void generate_route(NocRouterId sink_router_id,
+                        std::vector<NocLinkId>& flow_route,
+                        const NocStorage& noc_model,
+                        const std::unordered_map<NocRouterId, NocLinkId>& router_parent_link);
 };
 
 #endif

vpr/src/noc/channel_dependency_graph.h

@@ -1,19 +1,53 @@
 #ifndef VTR_CHANNEL_DEPENDENCY_GRAPH_H
 #define VTR_CHANNEL_DEPENDENCY_GRAPH_H
 
+/**
+ * @file
+ * @brief This file declares the ChannelDependencyGraph class.
+ *
+ * Overview
+ * ========
+ * The NoC routing algorithm might generate routes that cause a deadlock.
+ * The Channel Dependency Graph (CDG) is formed by associating a node with each
+ * link in the NoC topology. For each traffic flow route, we consider the
+ * consecutive links traversed to reach the destination. For each consecutively
+ * traversed link pair (Li, Lj) in the given topology, we add an directed edge from
+ * Vi to Vj, where Vi and Vj are nodes in CDG that are associated with Li and Lj.
+ * Absence of cycles in the formed CDG guarantees deadlock freedom.
+ *
+ * To learn more about channel dependency graph, refer to the following papers:
+ * 1) Glass, C. J., & Ni, L. M. (1992). The turn model for adaptive routing.
+ * ACM SIGARCH Computer Architecture News, 20(2), 278-287.
+ * 2) Dally, & Seitz. (1987). Deadlock-free message routing in multiprocessor
+ * interconnection networks. IEEE Transactions on computers, 100(5), 547-553.
+ */
+
 #include "vtr_vector.h"
 #include "noc_data_types.h"
 
 class ChannelDependencyGraph {
   public:
     ChannelDependencyGraph() = delete;
 
+    /**
+     * @brief Constructor
+     *
+     * @param n_links The total number of NoC links.
+     * @param traffic_flow_routes Generated traffic flow routes by the routing
+     * algorithm.
+     */
     ChannelDependencyGraph(size_t n_links,
                            const vtr::vector<NocTrafficFlowId, std::vector<NocLinkId>>& traffic_flow_routes);
 
+    /**
+     * @brief Checks whether CDG has any cycles.
+     *
+     * @return True if the CDG has any cycles, otherwise false is returned.
+     */
     bool has_cycles();
 
   private:
+    /** An adjacency list used to represent channel dependency graph.*/
     vtr::vector<NocLinkId, std::vector<NocLinkId>> adjacency_list_;
 };
 

vpr/src/noc/noc_routing.h

@@ -24,7 +24,6 @@
 #include <vector>
 
 #include "noc_data_types.h"
-#include "noc_traffic_flows.h"
 #include "noc_storage.h"
 
 class NocRouting {

vpr/src/noc/noc_routing_algorithm_creator.cpp

@@ -1,7 +1,14 @@
 
 #include "noc_routing_algorithm_creator.h"
+#include "xy_routing.h"
+#include "bfs_routing.h"
+#include "west_first_routing.h"
+#include "north_last_routing.h"
+#include "negative_first_routing.h"
+#include "odd_even_routing.h"
 #include "vpr_error.h"
 
+
 std::unique_ptr<NocRouting> NocRoutingAlgorithmCreator::create_routing_algorithm(const std::string& routing_algorithm_name) {
     std::unique_ptr<NocRouting> noc_routing_algorithm;
 

vpr/src/noc/noc_routing_algorithm_creator.h

@@ -21,12 +21,6 @@
 #include <memory>
 
 #include "noc_routing.h"
-#include "xy_routing.h"
-#include "bfs_routing.h"
-#include "west_first_routing.h"
-#include "north_last_routing.h"
-#include "negative_first_routing.h"
-#include "odd_even_routing.h"
 
 class NocRoutingAlgorithmCreator {
   public:

vpr/src/noc/turn_model_routing.cpp

@@ -1,3 +1,4 @@
+
 #include "turn_model_routing.h"
 
 TurnModelRouting::~TurnModelRouting() = default;
@@ -87,9 +88,6 @@ NocLinkId TurnModelRouting::move_to_next_router(NocRouterId& curr_router_id,
                                                 TurnModelRouting::Direction next_step_direction,
                                                 std::unordered_set<NocRouterId>& visited_routers,
                                                 const NocStorage& noc_model) {
-    // represents the router that will be visited when taking an outgoing link
-    NocRouterId next_router_id(-1);
-
     // next link to be added to the route, initialized with INVALID
     auto next_link = NocLinkId();
 
@@ -108,7 +106,7 @@ NocLinkId TurnModelRouting::move_to_next_router(NocRouterId& curr_router_id,
         const NocLink& curr_outgoing_link = noc_model.get_single_noc_link(connecting_link);
 
         // get the next router that we will visit if we travel across the current link
-        next_router_id = curr_outgoing_link.get_sink_router();
+        auto next_router_id = curr_outgoing_link.get_sink_router();
         const NocRouter& next_router = noc_model.get_single_noc_router(next_router_id);
 
         // get the coordinates of the next router
@@ -169,18 +167,17 @@ NocLinkId TurnModelRouting::move_to_next_router(NocRouterId& curr_router_id,
     return next_link;
 }
 
-uint32_t TurnModelRouting::murmur_32_scramble(uint32_t k) {
-    k *= 0xcc9e2d51;
-    k = (k << 15) | (k >> 17);
-    k *= 0x1b873593;
-    return k;
-}
-
 uint32_t TurnModelRouting::murmur3_32(const std::vector<uint32_t>& key, uint32_t seed) {
     uint32_t h = seed;
 
-    for (uint32_t k : key) {
+    auto murmur_32_scramble = [](uint32_t k) -> uint32_t {
+        k *= 0xcc9e2d51;
+        k = (k << 15) | (k >> 17);
+        k *= 0x1b873593;
+        return k;
+    };
 
+    for (uint32_t k : key) {
         h ^= murmur_32_scramble(k);
         h = (h << 13) | (h >> 19);
         h = h * 5 + 0xe6546b64;
@@ -224,7 +221,8 @@ TurnModelRouting::Direction TurnModelRouting::select_horizontal_direction(const
     return TurnModelRouting::Direction::INVALID;
 }
 
-TurnModelRouting::Direction TurnModelRouting::select_direction_other_than(const std::vector<TurnModelRouting::Direction>& directions, TurnModelRouting::Direction other_than) {
+TurnModelRouting::Direction TurnModelRouting::select_direction_other_than(const std::vector<TurnModelRouting::Direction>& directions,
+                                                                          TurnModelRouting::Direction other_than) {
     // Iterate over all given directions and return the first one which is not "other_than"
     for (const auto& direction : directions) {
         if (direction != other_than) {