Making edits to to main NoC datastructure documentation and also adding NoC routing algorithm associated documentation

Author: Srivat97

doc/src/api/vprinternals/noc_data_types.rst

@@ -2,8 +2,7 @@
 NoC Data Types
 ==============
 
-Types
------
+Data Types
+----------
 .. doxygenfile:: noc_data_types.h
-   :project: vpr
-   :sections: typedef
+   :project: vpr

doc/src/api/vprinternals/noc_routing.rst

@@ -5,4 +5,19 @@ NoC Routing
 NocRouting
 ---------------
 .. doxygenfile:: noc_routing.h
+   :project: vpr
+
+NocRoutingAlgorithmCreator
+--------------------------
+.. doxygenfile:: noc_routing_algorithm_creator.h
+   :project: vpr
+
+XYRouting
+---------
+.. doxygenfile:: xy_routing.h
+   :project: vpr
+
+BFSRouting
+----------
+.. doxygenfile:: bfs_routing.h
    :project: vpr

vpr/src/noc/noc_data_types.h

@@ -1,6 +1,12 @@
 #ifndef NOC_DATA_TYPES_H
 #define NOC_DATA_TYPES_H
 
+/** 
+ * @file 
+ * @brief This file contains datatype definitions which are used by the NoC datastructures.
+ *  
+ */
+
 #include "vtr_strong_id.h"
 
 // data types used to index the routers and links within the noc

vpr/src/noc/noc_link.h

@@ -23,14 +23,14 @@
  * exceeds the links supported capability).
  * 
  * Example:
- * 
+ * ```
  *  ----------                       ----------
  *  /        /        link           /        /
  *  / router / --------------------->/ router /
  *  /   a    /                       /   b    /
  *  /        /                       /        /
  *  /--------/                       /--------/
- * 
+ * ```
  * In the example above the links source router would be router a and
  * the sink router would be router b. 
  * 
@@ -44,10 +44,10 @@
 class NocLink {
   private:
     // the two routers that are connected by this link
-    NocRouterId source_router; /*!< The router which has this link as an outgoing edge*/
+    NocRouterId source_router; /*!< The router which uses this link as an outgoing edge*/
     NocRouterId sink_router;   /*!< The router which uses this link as an incoming edge*/
 
-    double bandwidth_usage; /*!< Represents the bandwidth of the data being transmitted on the link. Units in bps*/
+    double bandwidth_usage; /*!< Represents the bandwidth of the data being transmitted on the link. Units in bits-per-second(bps)*/
 
   public:
     NocLink(NocRouterId source_router, NocRouterId sink_router);
@@ -77,14 +77,14 @@ class NocLink {
     // setters
     /**
      * @brief Can be used to set the source router of the link to a different router. 
-     * @param source_router The identifier representing the router that should be the source of
+     * @param source An identifier representing the router that should be the source of
      * this link
      */
     void set_source_router(NocRouterId source);
 
     /**
      * @brief Can be used to set the sink router of the link to a different router. 
-     * @param sink_router The identifier representing the router that should be the sink of
+     * @param sink An identifier representing the router that should be the sink of
      * this link
      */
     void set_sink_router(NocRouterId sink);

vpr/src/noc/noc_router.h

@@ -38,16 +38,24 @@
 
 class NocRouter {
   private:
-    /** this represents a unique id provided by the user when describing the NoC topology in the arch file. The intended
+    /** This represents a unique id provided by the user when describing the NoC topology in the arch file. The intended
      * use is to report errors with router ids the user understands*/
     int router_user_id;
 
     // device position of the physical router tile
-    int router_grid_position_x; /*<! Represents the horizontal grid position on the device the physical router tile is located*/
-    int router_grid_position_y; /*<! Represents the vertical grid position on the device the physical router is located*/
-    int router_layer_position;  /*<! Represents the layer number of the die that the physical router is located*/
+    /** Represents the horizontal grid position on the device 
+     * the physical router tile is located*/
+    int router_grid_position_x;
+    /** Represents the vertical grid position on the device 
+     * the physical router is located*/ 
+    int router_grid_position_y;
+    /** Represents the layer number of the die 
+     * that the physical router is located*/ 
+    int router_layer_position;  
 
-    ClusterBlockId router_block_ref; /*<! A unique identifier that represents a router block in the clustered netlist that is placed on the physical router*/
+    /** A unique identifier that represents a router block in the 
+     * clustered netlist that is placed on the physical router*/
+    ClusterBlockId router_block_ref; 
 
   public:
     NocRouter(int id, int grid_position_x, int grid_position_y, int layer_position);

vpr/src/noc/noc_routing.h

@@ -2,7 +2,7 @@
 #define VTR_NOCROUTING_H
 
 /**
- * @file NocRouting.h
+ * @file
  * @brief This file defines the NocRouting class, which handles the
  * packet routing between routers within the NoC. It describes the routing
  * algorithm for the NoC.

vpr/src/noc/noc_routing_algorithm_creator.h

@@ -8,7 +8,7 @@
  * 
  * Overview
  * ========
- * There are a number of different available NoC routing algorithms. This class * is a factory object for the NocRouting abstract class. This class constructs 
+ * There are a number of different available NoC routing algorithms. This class is a factory object for the NocRouting abstract class. This class constructs 
  * the appropriate routing algorithm based on the user specification in the
  * command line. The user identifies a 
  * specific routing algorithm in the command line by providing a string

vpr/src/noc/noc_storage.h

@@ -46,13 +46,15 @@
 #include "vtr_assert.h"
 #include "vpr_error.h"
 #include "echo_files.h"
-
+// \cond
 // represents the id of a link that does not exist in the NoC
 constexpr NocLinkId INVALID_LINK_ID(-1);
+// \endcond
 
 class NocStorage {
   private:
-    vtr::vector<NocRouterId, NocRouter> router_storage; /*<! Contains all the routers in the NoC*/
+    /** Contains all the routers in the NoC*/
+    vtr::vector<NocRouterId, NocRouter> router_storage; 
 
     // list of outgoing links for each router
     /**
@@ -63,7 +65,8 @@ class NocStorage {
      */
     vtr::vector<NocRouterId, std::vector<NocLinkId>> router_link_list;
 
-    vtr::vector<NocLinkId, NocLink> link_storage; /*<! Contains all the links in the NoC*/
+    /** Contains all the links in the NoC*/
+    vtr::vector<NocLinkId, NocLink> link_storage; 
 
     /**
      * @brief The user provides an ID for the router when describing the NoC
@@ -409,14 +412,14 @@ class NocStorage {
      * link is returned.
      * 
      * Example:
-     * 
+     * ```
      *  ----------                       ----------
      *  /        /        link 1         /        /
      *  / router / --------------------->/ router /
      *  /   a    / <---------------------/   b    /
      *  /        /        link 2         /        /
      *  /--------/                       /--------/
-     * 
+     * ```
      * In the example above, link 1 and link 2 are parallel.
      * 
      * @param current_link A unique identifier that represents a link

vpr/src/noc/noc_traffic_flows.h

@@ -23,7 +23,7 @@
  * design.
  * 
  * This class will be primarily used during 
- * placement to identify which routers inside the NoC(NocStorage) need to be
+ * placement to identify which routers inside the NoC ( NocStorage ) need to be
  * routed to each other.This is important since the router modules can be moved
  * around to different tiles on the FPGA device.
  * 
@@ -46,12 +46,14 @@
  * 
  */
 struct t_noc_traffic_flow {
-    /** stores the partial names of the router blocks communicating within this traffic flow. Names must uniquely identify router blocks in the netlist.*/
+    /** stores the partial name of the source router block communicating within this traffic flow. Names must uniquely identify router blocks in the netlist.*/
     std::string source_router_module_name;
+    /** stores the partial name of the sink router block communicating within this traffic flow. Names must uniquely identify router blocks in the netlist.*/
     std::string sink_router_module_name;
 
-    /** stores the block id of the two router blocks communicating within this traffic flow. This can be used to retrieve the block information from the clustered netlist*/
+    /** stores the block id of the source router block communicating within this traffic flow. This can be used to retrieve the block information from the clustered netlist*/
     ClusterBlockId source_router_cluster_id;
+    /** stores the block id of the destination router block communicating within this traffic flow. This can be used to retrieve the block information from the clustered netlist*/
     ClusterBlockId sink_router_cluster_id;
 
     /** The bandwidth of the information transferred between the two routers. Units in bytes per second. This parameters will be used to update the link usage in the noc model after routing the traffic flow.*/

vpr/src/noc/xy_routing.h

@@ -41,7 +41,7 @@
  * 
  * Below we have an example of the path determined by this algorithm for a 
  * 3x3 mesh NoC:
- * 
+ * ```
  *   ---------                   ---------                    ---------
  *   /       /                   /       /                    /       /
  *   /   $   / ----------------- /       / ------------------ /       /
@@ -65,7 +65,7 @@
  *   /       / ----------------- /       / ------------------ /   *   /
  *   /       /                   /       /                    /       /
  *   ---------                   ---------                    ---------
- * 
+ * ```
  * In the example above, the router marked with the '*' character is the start
  * and the router marked with the '$' character is the destination. The path
  * determined by the XY-Routing algorithm is shown as "<++++".