addressed some pr comments

Author: soheilshahrouz

vpr/src/noc/odd_even_routing.cpp

@@ -49,6 +49,8 @@ const std::vector<TurnModelRouting::Direction>& OddEvenRouting::get_legal_direct
     /* The implementation below is a carbon copy of the Fig. 2 in the following paper
      * Chiu GM. The odd-even turn model for adaptive routing.
      * IEEE Transactions on parallel and distributed systems. 2000 Jul;11(7):729-38.
+     * In summary, the odd-even algorithm forbids NW and SW turns in odd columns,
+     * while EN and ES turns are forbidden in even columns.
      */
     if (diff_x == 0) { // the same column as the destination. Only north or south are allowed
         if (diff_y > 0) {
@@ -61,6 +63,8 @@ const std::vector<TurnModelRouting::Direction>& OddEvenRouting::get_legal_direct
             if (diff_y == 0) { // already in the same row as the destination. Just move to the east
                 returned_legal_direction.push_back(TurnModelRouting::Direction::RIGHT);
             } else {
+                /* Since EN and ES turns are forbidden in even columns, we move along the vertical
+                 * direction only in we are in an odd column. */
                 if (is_odd(compressed_curr_loc.x) || compressed_curr_loc.x == compressed_src_loc.x) {
                     if (diff_y > 0) {
                         returned_legal_direction.push_back(TurnModelRouting::Direction::UP);
@@ -75,6 +79,8 @@ const std::vector<TurnModelRouting::Direction>& OddEvenRouting::get_legal_direct
             }
         } else { // westbound message
             returned_legal_direction.push_back(TurnModelRouting::Direction::LEFT);
+            /* Since NW and SW turns are forbidden in odd columns, we allow
+             * moving along vertical axis only in even columns */
             if (is_even(compressed_curr_loc.x)) {
                 if (diff_y > 0) {
                     returned_legal_direction.push_back(TurnModelRouting::Direction::UP);

vpr/src/noc/odd_even_routing.h

@@ -3,11 +3,27 @@
 
 #include "turn_model_routing.h"
 
+/**
+ * @file
+ * @brief This file declares the OddEvenRouting class, which implements
+ * the odd-even routing algorithm.
+ *
+ * Overview
+ * ========
+ * The OddEvenRouting class performs packet routing between routers in the
+ * NoC using the odd-even routing algorithm. Unlike other turn model algorithms
+ * that forbid at least two turns, the odd-even algorithm does not forbid
+ * any turns, but only limits the column where the turn can be taken.
+ * More specifically, the odd-even routing algorithms forbids NW and SW turns
+ * in odd columns, while EN and ES turns are not allowed in even columns.
+ */
+
 class OddEvenRouting : public TurnModelRouting{
   public:
     ~OddEvenRouting() override;
 
   private:
+
     const std::vector<TurnModelRouting::Direction>& get_legal_directions(NocRouterId src_router_id,
                                                                          NocRouterId curr_router_id,
                                                                          NocRouterId dst_router_id,
@@ -19,8 +35,18 @@ class OddEvenRouting : public TurnModelRouting{
                                                       NocRouterId curr_router_id,
                                                       NocTrafficFlowId traffic_flow_id,
                                                       const NocStorage& noc_model) override;
-
+    /**
+     * Checks whether the given umber is odd.
+     * @param number An integer number
+     * @return True if the passed number of odd, otherwise false.
+     */
     static inline bool is_odd(int number);
+
+    /**
+     * Checks whether the given umber is even.
+     * @param number An integer number
+     * @return True if the passed number of even, otherwise false.
+     */
     static inline bool is_even(int number);
 };
 

vpr/src/noc/turn_model_routing.h

@@ -11,16 +11,23 @@
  * Overview
  * ========
  * The TurnModelRouting class abstracts Turn Model routing algorithms.
+ * The route_flow() method implemented in this class, routes a traffic flow
+ * by adding a NoC link at a time to form a route between two NoC routers.
+ * The destination router of the last added NoC link is called the current
+ * NoC router.
  * The main idea in Turn Model algorithm is to forbid specific turns
- * for traffic flows based on the source, destination, and current NoC
+ * for traffic flows to avoid deadlock. If at least one clockwise turn
+ * and one anticlockwise turn are forbidden, no cyclic dependency can
+ * happen, making deadlock impossible. Turn model algorithms forbid
+ * specific turns based on the source, destination, and current NoC
  * router locations in a mesh or torus topology. TurnModelRouting class
  * exposes a shared interface for all Turn Model routing algorithms.
  * Derived classes can implement specific routing algorithms by implementing
  * their override of the exposed interface. More specifically,
- * get_legal_directions() method returns legal directions that a
- * traffic flow can follow based on the source, destination, and current
+ * the get_legal_directions() method returns legal directions that a
+ * traffic flow can follow based on where the source, destination, and current
  * NoC routers are located. select_next_direction() selects one of these
- * legal directions. TurnModelRouting() method does not implement these
+ * legal directions. The TurnModelRouting() class does not implement these
  * methods, but calls them in route_flow(). For example, XYRouting can be
  * implemented by overriding these two methods. get_legal_directions()
  * should return horizontal directions when the current router and the
@@ -30,6 +37,16 @@
  * select_next_direction() selects one of two available directions to get
  * closer to the destination.
  *
+ * When the routing algorithm presents two possible direction choices
+ * at a router, we use a biased coin flip to randomly select one of them.
+ * This random decision is biased towards choosing the direction in which
+ * the distance to the destination is longer. For example, if the last router
+ * added to a partial route is located at (3, 5) while the route is destined
+ * for (7, 7), the random decision favors the X-direction twice as much as
+ * the Y-direction. This approach distributes the chance of selecting
+ * a shortest path more evenly among all possible paths between two
+ * NoC routers.
+ *
  * TurnModelRouting also provides multiple helper methods that can be used
  * by derived classes.
  */
@@ -142,7 +159,8 @@ class TurnModelRouting : public NocRouting {
      * sure that the link chosen points in the intended direction.
      *
      * @param curr_router_id The physical router on the FPGA that the routing
-     * algorithm is currently visiting.
+     * algorithm is currently visiting. This argument is updated in this method
+     * returned by reference.
      * @param curr_router_position The grid position of the router that is
      * currently being visited on the FPGA
      * @param next_step_direction The direction to travel next
@@ -164,7 +182,13 @@ class TurnModelRouting : public NocRouting {
 
     /**
      * @brief Computes MurmurHash3 for an array of 32-bit words initialized
-     * with seed.
+     * with seed. As discussed in the comment at the top of this file,
+     * when two possible directions are presented by get_legal_directions(),
+     * we flip a biased coin by favoring the direction along which the distance
+     * to the destination is longer. This hash function is used to generate
+     * a hash value, which is treated as random value. The generated
+     * hash value is compared with a threshold to determine the next
+     * direction to be taken
      * @param key Contains elements to be hashed
      * @param seed The initialization value.
      * @return uint32_t Computed hash value.