Merge branch 'master' into yosys_plugins_docs

Author: sdamghan

vpr/src/base/SetupVPR.cpp

@@ -668,6 +668,7 @@ static void SetupNocOpts(const t_options& Options, t_noc_opts* NocOpts) {
     // assign the noc specific options from the command line
     NocOpts->noc = Options.noc;
     NocOpts->noc_flows_file = Options.noc_flows_file;
+    NocOpts->noc_routing_algorithm = Options.noc_routing_algorithm;
 
     return;
 }

vpr/src/base/ShowSetup.cpp

@@ -771,7 +771,6 @@ static void ShowPackerOpts(const t_packer_opts& PackerOpts) {
 
 static void ShowNocOpts(const t_noc_opts& NocOpts) {
     VTR_LOG("NocOpts.noc_flows_file: %s\n", NocOpts.noc_flows_file.c_str());
+    VTR_LOG("NocOpts.noc_routing_algorithm: %s\n", NocOpts.noc_routing_algorithm.c_str());
     VTR_LOG("\n");
-
-    // add future options here (routing algorithm etc...)
 }

vpr/src/base/read_options.cpp

@@ -2635,6 +2635,15 @@ argparse::ArgumentParser create_arg_parser(std::string prog_name, t_options& arg
         .default_value("")
         .show_in(argparse::ShowIn::HELP_ONLY);
 
+    noc_grp.add_argument<std::string>(args.noc_routing_algorithm, "--noc_routing_algorithm")
+        .help(
+            "Controls the algorithm used by the NoC to route packets.\n"
+            "* xy_routing: Uses the direction oriented routing algorithm. This is recommended to be used with mesh NoC topologies.\n"
+            "* bfs_routing: Uses the breadth first search algorithm. The objective is to find a route that uses a minimum number of links.\n"
+            "This can be used with any NoC topology\n")
+        .default_value("bfs_routing")
+        .show_in(argparse::ShowIn::HELP_ONLY);
+
     return parser;
 }
 

vpr/src/base/read_options.h

@@ -142,6 +142,7 @@ struct t_options {
     /*NoC Options*/
     argparse::ArgValue<bool> noc;
     argparse::ArgValue<std::string> noc_flows_file;
+    argparse::ArgValue<std::string> noc_routing_algorithm;
 
     /* Timing-driven placement options only */
     argparse::ArgValue<float> PlaceTimingTradeoff;

vpr/src/base/vpr_api.cpp

@@ -40,6 +40,7 @@
 #include "setup_clocks.h"
 #include "setup_noc.h"
 #include "read_xml_noc_traffic_flows_file.h"
+#include "noc_routing_algorithm_creator.h"
 #include "stats.h"
 #include "read_options.h"
 #include "echo_files.h"
@@ -527,6 +528,8 @@ void vpr_setup_noc(const t_vpr_setup& vpr_setup, const t_arch& arch) {
         setup_noc(arch);
         // read and store the noc traffic flow information
         read_xml_noc_traffic_flows_file(vpr_setup.NocOpts.noc_flows_file.c_str());
+        // create the NoC routing algorithm based on the user input
+        vpr_setup_noc_routing_algorithm(vpr_setup.NocOpts.noc_routing_algorithm);
 
 #ifndef NO_GRAPHICS
         // setup the graphics
@@ -538,6 +541,23 @@ void vpr_setup_noc(const t_vpr_setup& vpr_setup, const t_arch& arch) {
     }
 }
 
+/**
+ * @brief Constructs a NoC routing algorithm that is identified by a user
+ * provided string. Then the newly created routing algorithm is stored
+ * inside the global NoC context.
+ * 
+ * @param noc_routing_algorithm_name A user provided string that identifies a 
+ * NoC routing algorithm
+ */
+void vpr_setup_noc_routing_algorithm(std::string noc_routing_algorithm_name) {
+    // Need to be abke to modify the NoC context, since we will be adding the
+    // newly created routing algorithm to it
+    auto& noc_ctx = g_vpr_ctx.mutable_noc();
+
+    noc_ctx.noc_flows_router = NocRoutingAlgorithmCreator().create_routing_algorithm(noc_routing_algorithm_name);
+    return;
+}
+
 bool vpr_pack_flow(t_vpr_setup& vpr_setup, const t_arch& arch) {
     auto& packer_opts = vpr_setup.PackerOpts;
 
@@ -1134,6 +1154,13 @@ static void free_routing() {
     routing_ctx.net_status.clear();
     routing_ctx.route_bb.clear();
 }
+/**
+ * @brief handles the deletion of NoC related datastructures.
+ */
+static void free_noc() {
+    auto& noc_ctx = g_vpr_ctx.mutable_noc();
+    delete noc_ctx.noc_flows_router;
+}
 
 void vpr_free_vpr_data_structures(t_arch& Arch,
                                   t_vpr_setup& vpr_setup) {
@@ -1145,6 +1172,7 @@ void vpr_free_vpr_data_structures(t_arch& Arch,
     free_placement();
     free_routing();
     free_atoms();
+    free_noc();
 }
 
 void vpr_free_all(t_arch& Arch,

vpr/src/base/vpr_api.h

@@ -128,6 +128,7 @@ void vpr_close_graphics(const t_vpr_setup& vpr_setup);
 void vpr_setup_clock_networks(t_vpr_setup& vpr_setup, const t_arch& Arch);
 
 void vpr_setup_noc(const t_vpr_setup& vpr_setup, const t_arch& arch);
+void vpr_setup_noc_routing_algorithm(std::string noc_routing_algorithm_name);
 
 void vpr_free_vpr_data_structures(t_arch& Arch, t_vpr_setup& vpr_setup);
 void vpr_free_all(t_arch& Arch, t_vpr_setup& vpr_setup);

vpr/src/base/vpr_context.h

@@ -29,6 +29,7 @@
 #include "vpr_constraints.h"
 #include "noc_storage.h"
 #include "noc_traffic_flows.h"
+#include "noc_routing.h"
 
 /**
  * @brief A Context is collection of state relating to a particular part of VPR
@@ -462,7 +463,7 @@ struct NocContext : public Context {
      *
      * Contains all the routers and links that make up the NoC. The routers contain
      * information regarding the physical tile positions they represent. The links
-     * define the connections between every router  (ropology) and also metrics that describe its
+     * define the connections between every router (topology) and also metrics that describe its
      * "usage". 
      * 
      *
@@ -479,6 +480,15 @@ struct NocContext : public Context {
      * This is created from a user supplied .flows file.
      */
     NocTrafficFlows noc_traffic_flows_storage;
+
+    /**
+     * @brief Contains the packet routing algorithm used by the NoC.
+     * 
+     * This should be used to route traffic flows within the NoC.
+     * 
+     * This is created from a user supplied command line option "--noc_routing_algorithm"
+     */
+    NocRouting* noc_flows_router;
 };
 
 /**

vpr/src/base/vpr_types.h

@@ -1260,8 +1260,9 @@ struct t_analysis_opts {
 
 // used to store NoC specific options, when supplied as an input by the user
 struct t_noc_opts {
-    bool noc;                   ///<options to turn on hard NoC modeling & optimization
-    std::string noc_flows_file; ///<name of the file that contains all the traffic flow information in the NoC
+    bool noc;                          ///<options to turn on hard NoC modeling & optimization
+    std::string noc_flows_file;        ///<name of the file that contains all the traffic flow information in the NoC
+    std::string noc_routing_algorithm; ///<controls the routing algorithm used to route packets within the NoC
 };
 
 /**

vpr/src/noc/bfs_routing.cpp

@@ -0,0 +1,124 @@
+#
+
+#include "bfs_routing.h"
+
+BFSRouting::~BFSRouting() {}
+
+void BFSRouting::route_flow(NocRouterId src_router_id, NocRouterId sink_router_id, std::vector<NocLinkId>& flow_route, const NocStorage& noc_model) {
+    const NocRouter src_router = noc_model.get_single_noc_router(src_router_id);
+    const NocRouter sink_router = noc_model.get_single_noc_router(sink_router_id);
+
+    // destroy any previously stored route
+    flow_route.clear();
+
+    /**
+     * 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.
+     * 
+     */
+    std::unordered_set<NocRouterId> visited_routers;
+
+    /*
+     * As the routing goes through the NoC, each router visited has a
+     * corresponding link that was used to reach the router. This
+     * datastructure stores the link that was used to visit each router in 
+     * the NoC.
+     * Once the destination router has been found. This datastructure can be used to
+     * trace the path back to the source router.
+     */
+    std::unordered_map<NocRouterId, NocLinkId> router_parent_link;
+
+    std::queue<NocRouterId> routers_to_process;
+
+    // indicates whether the routing algorithm found the destination router. If the destination
+    // router was not found then this means no route exists between the source and destination router.
+    bool found_sink_router = false;
+
+    // Start by processing the source router of the flow
+    routers_to_process.push(src_router_id);
+    visited_routers.insert(src_router_id);
+
+    //handle case where the source and sink router of the flow are the same
+    if (src_router_id == sink_router_id) {
+        found_sink_router = true;
+    }
+
+    // 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
+    while (!routers_to_process.empty() && !found_sink_router) {
+        // get the next router to process
+        NocRouterId processing_router = routers_to_process.front();
+        routers_to_process.pop();
+
+        // get the links leaving the router currently being processed(these represent possible paths to explore in the NoC)
+        const std::vector<NocLinkId> outgoing_links = noc_model.get_noc_router_connections(processing_router);
+
+        // go through the outgoing links of the current router and process the sink routers connected to these links
+        for (auto link : outgoing_links) {
+            // get the router connected to the current outgoing link
+            NocRouterId connected_router = noc_model.get_single_noc_link(link).get_sink_router();
+
+            // check if we already explored the router we are visiting
+            if (visited_routers.find(connected_router) == visited_routers.end()) {
+                // if we are here then this is the first time visiting this router //
+                // mark this router as visited and add send the router to be processed
+                visited_routers.insert(connected_router);
+                routers_to_process.push(connected_router);
+
+                // set the parent link of this router (link used to visit the router) as the current outgoing link
+                router_parent_link.insert(std::pair<NocRouterId, NocLinkId>(connected_router, link));
+
+                // check if the router visited is the destination router
+                if (connected_router == sink_router_id) {
+                    // mark that the destination router has been found
+                    found_sink_router = true;
+                    // no need to process any more routers
+                    break;
+                }
+            }
+        }
+    }
+
+    // check if the above search found a valid path from the source to the destination
+    // router.
+    if (found_sink_router) {
+        // a legal path was found, so construct it
+        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());
+    }
+
+    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) {
+    // 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;
+
+    // get a reference to the beginning of the vector that stores the found route of the flow
+    // need this since each link we find in the path will be added to the beginning of the vector
+    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);
+
+    // 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)
+    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.
+        flow_route.emplace(route_beginning, curr_intermediate_router_parent_link->second);
+
+        // update the reference to the beginning of the route
+        route_beginning = flow_route.begin();
+
+        // now move to the next intermediate router in the path. This will be the source router of the parent link
+        curr_intermediate_router = noc_model.get_single_noc_link(curr_intermediate_router_parent_link->second).get_source_router();
+        // 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

@@ -0,0 +1,82 @@
+#ifndef BFS_ROUTING
+#define BFS_ROUTING
+
+/**
+ * @file 
+ * @brief This file defines the BFSRouting class.
+ * 
+ * Overview
+ * ========
+ * The BFSRouting class performs packet routing between physical routers in the
+ * FPGA. This class is based on the BFS algorithm.
+ * 
+ * The BFS algorithm is used to explore the NoC from the starting router in the
+ * 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.
+ * 
+ */
+
+#include <vector>
+#include <unordered_map>
+#include <queue>
+
+#include "noc_routing.h"
+
+class BFSRouting : public NocRouting {
+  public:
+    ~BFSRouting() override;
+
+    /**
+     * @brief Finds a route that goes from the starting router in a 
+     * traffic flow to the destination router. Uses the BFS
+     * algorithm to determine the route. A route consists of a series
+     * of links that should be traversed when travelling between two routers
+     * within the NoC.
+     * 
+     * @param src_router_id The source router of a traffic flow. Identifies 
+     * the starting point of the route within the NoC. This represents a 
+     * physical router on the FPGA.
+     * @param sink_router_id The destination router of a traffic flow.
+     * Identifies the ending point of the route within the NoC.This represents a 
+     * physical router on the FPGA.
+     * @param flow_route Stores the path returned by this fuction
+     * as a series of NoC links found by 
+     * a NoC routing algorithm between two routers in a traffic flow.
+     * The function will clear any
+     * previously stored path and re-insert the new found path between the
+     * two routers. 
+     * @param noc_model A model of the NoC. This is used to traverse the
+     * NoC and find a route between the two routers.
+     */
+    void route_flow(NocRouterId src_router_id, NocRouterId sink_router_id, std::vector<NocLinkId>& flow_route, const NocStorage& noc_model) override;
+
+    // internally used helper functions
+  private:
+    /**
+     * @brief Traces the path taken by the BFS routing algorithm from the destination router to the starting router. 
+     * Starting with the destination router, the parent link (link taken to get to this router) is found and is added
+     * to the path. Then the algorithm moves to the source router of the parent link. Then it repeats the previous process
+     * of finding the parent link, adding it to the path and moving to the source router. This is repeated until the
+     * starting router is reached.
+     * 
+     * @param start_router_id The router to use as a starting point
+     * when tracing back the route from the destination router. 
+     * to the the starting router. Generally this
+     * would be the sink router of the flow.
+     * @param flow_route Stores the path as a series of NoC links found by 
+     * a NoC routing algorithm between two routers in a traffic flow.
+     * The function will clear any
+     * previously stored path and re-insert the new found path between the
+     * two routers. 
+     * @param noc_model A model of the NoC. This is used to traverse the
+     * NoC and find a route between the two routers.
+     * @param router_parent_link Contains the parent link associated to each
+     * 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);
+};
+
+#endif

vpr/src/noc/noc_link.cpp

@@ -22,6 +22,16 @@ double NocLink::get_bandwidth_usage(void) const {
 }
 
 //setters
+void NocLink::set_source_router(NocRouterId source) {
+    source_router = source;
+    return;
+}
+
+void NocLink::set_sink_router(NocRouterId sink) {
+    sink_router = sink;
+    return;
+}
+
 void NocLink::set_bandwidth_usage(double new_bandwidth_usage) {
     bandwidth_usage = new_bandwidth_usage;
 }