add comments

Author: soheilshahrouz

libs/libarchfpga/src/arch_types.h

@@ -18,9 +18,10 @@
 /* Value for UNDEFINED data */
 constexpr int UNDEFINED = -1;
 
+/** The total number of predefined blif models */
 constexpr int NUM_MODELS_IN_LIBRARY = 4;
 
-/* Maximum value for mininum channel width to avoid overflows of short data type.               */
+/* Maximum value for minimum channel width to avoid overflows of short data type.               */
 constexpr int MAX_CHANNEL_WIDTH = 8000;
 
 /* Built-in library models */

libs/libarchfpga/src/physical_types.h

@@ -1947,8 +1947,14 @@ struct t_noc_inf {
     /** A list of all routers in the NoC*/
     std::vector<t_router> router_list;
 
+    /** Stores NoC routers that have a different latency than the NoC-wide router latency.
+     * (router_user_id, overridden router latency)*/
     std::map<int, double> router_latency_overrides;
+    /** Stores NoC links that have a different latency than the NoC-wide link latency.
+     * ((source router id, destination router id), overridden link latency)*/
     std::map<std::pair<int, int>, double> link_latency_overrides;
+    /** Stores NoC links that have a different bandwidth than the NoC-wide link bandwidth.
+     * ((source router id, destination router id), overridden link bandwidth)*/
     std::map<std::pair<int, int>, double> link_bandwidth_overrides;
 
     /** Represents the name of a router tile on the FPGA device. This should match the name used in the arch file when
@@ -1958,7 +1964,8 @@ struct t_noc_inf {
 
 /*   Detailed routing architecture */
 struct t_arch {
-    /** Stores unique strings used as key and values in <metadata> tags*/
+    /** Stores unique strings used as key and values in <metadata> tags,
+     * i.e. implements a flyweight pattern to save memory.*/
     mutable vtr::string_internment strings;
     std::vector<vtr::interned_string> interned_strings;
 

libs/libarchfpga/src/read_xml_arch_file_noc_tag.cpp

@@ -6,18 +6,65 @@
 #include "vtr_log.h"
 #include "arch_error.h"
 
+/**
+ * @brief Process the <topology> tag under <noc> tag.
+ *
+ * Using <topology> tag, the user can specify a custom
+ * topology.
+ *
+ * @param topology_tag  An XML node pointing to a <topology> tag.
+ * @param loc_data Points to the location in the xml file where the parser is reading.
+ * @param noc_ref To be filled with NoC router locations and their connectivity.
+ */
 static void process_topology(pugi::xml_node topology_tag,
                             const pugiutil::loc_data& loc_data,
                             t_noc_inf* noc_ref);
 
-static void process_mesh_topology(pugi::xml_node mesh_topology_tag,
-                                  const pugiutil::loc_data& loc_data, t_noc_inf* noc_ref);
-
+/**
+ * @brief Process a <router> tag under a <topology> tag.
+ *
+ * A <topology> tag contains multiple <router> tags. Each <router> tag has
+ * attributes that specify its location and connectivity to other NoC routers.
+ *
+ * @param router_tag An XML node pointing to a <router> tag.
+ * @param loc_data Points to the location in the xml file where the parser is reading.
+ * @param noc_ref To be filled with the given router's location and connectivity information.
+ * @param routers_in_arch_info Stores router information that includes the number of connections
+ * a router has within a given topology and also the number of times a router was declared
+ * in the arch file using the <router> tag. [router_id, [n_declarations, n_connections]]
+ */
 static void process_router(pugi::xml_node router_tag,
                            const pugiutil::loc_data& loc_data,
                            t_noc_inf* noc_ref,
-                           std::map<int, std::pair<int, int>>& routers_info_in_arch);
+                           std::map<int, std::pair<int, int>>& routers_in_arch_info);
+
+/**
+ * @brief Processes the <mesh> tag under <noc> tag.
+ *
+ * Using the <mesh> tag, the user can describe a NoC with
+ * mesh topology.
+ *
+ * @param mesh_topology_tag An XML tag pointing to a <mesh> tag.
+ * @param loc_data Points to the location in the xml file where the parser is reading.
+ * @param noc_ref To be filled with NoC router locations and their connectivity.
+ */
+static void process_mesh_topology(pugi::xml_node mesh_topology_tag,
+                                  const pugiutil::loc_data& loc_data, t_noc_inf* noc_ref);
 
+
+/**
+ * Create routers and set their properties so that a mesh grid of routers is created.
+ * Then connect the routers together so that a mesh topology is created.
+ *
+ * @param mesh_topology_tag An XML tag pointing to a <mesh> tag.
+ * @param loc_data Points to the location in the xml file where the parser is reading.
+ * @param noc_ref To be filled with NoC router locations and their connectivity.
+ * @param mesh_region_start_x The location the bottom left NoC router on the X-axis.
+ * @param mesh_region_end_x The location the top right NoC router on the X-axis.
+ * @param mesh_region_start_y The location the bottom left NoC router on the Y-axis.
+ * @param mesh_region_end_y The location the top right NoC router on the Y-axis.
+ * @param mesh_size The number of NoC routers in each row or column.
+ */
 static void generate_noc_mesh(pugi::xml_node mesh_topology_tag,
                               const pugiutil::loc_data& loc_data,
                               t_noc_inf* noc_ref,
@@ -81,12 +128,21 @@ static void update_router_info_in_arch(int router_id,
                                        bool router_updated_as_a_connection,
                                        std::map<int, std::pair<int, int>>& routers_in_arch_info);
 
-
+/**
+ * @brief Process <overrides> tag under <noc> tag.
+ *
+ * The user can override the default latency and bandwidth values
+ * for specific NoC routers and links using <router> and <link>
+ * tags under <overrides> tag.
+ *
+ * @param noc_overrides_tag An XML node pointing to a <overrides> tag.
+ * @param loc_data Points to the location in the xml file where the parser is reading.
+ * @param noc_ref To be filled with parsed overridden latencies and bandwidths.
+ */
 static void process_noc_overrides(pugi::xml_node noc_overrides_tag,
                                   const pugiutil::loc_data& loc_data,
                                   t_noc_inf& noc_ref);
 
-
 void process_noc_tag(pugi::xml_node noc_tag,
                      t_arch* arch,
                      const pugiutil::loc_data& loc_data) {
@@ -195,10 +251,6 @@ static void process_mesh_topology(pugi::xml_node mesh_topology_tag,
     generate_noc_mesh(mesh_topology_tag, loc_data, noc_ref, mesh_region_start_x, mesh_region_end_x, mesh_region_start_y, mesh_region_end_y, mesh_size);
 }
 
-/*
- * Create routers and set their properties so that a mesh grid of routers is created.
- * Then connect the routers together so that a mesh topology is created.
- */
 static void generate_noc_mesh(pugi::xml_node mesh_topology_tag,
                               const pugiutil::loc_data& loc_data,
                               t_noc_inf* noc_ref,

vpr/src/base/setup_noc.cpp

@@ -246,10 +246,14 @@ void create_noc_links(const t_noc_inf& noc_info, NocStorage* noc_model) {
             // get the converted id of the currently connected sink router
             sink_router = noc_model->convert_router_id(conn_router_id);
 
+            // check if this link has an overridden latency
             auto lat_it = noc_info.link_latency_overrides.find({router.id, conn_router_id});
+            // use the link-specific latency if it has an overridden latency, otherwise use the NoC-wide link latency
             double link_lat = (lat_it == noc_info.link_latency_overrides.end()) ? noc_info.link_latency : lat_it->second;
 
+            // check if this link has an overridden bandwidth
             auto bw_it = noc_info.link_bandwidth_overrides.find({router.id, conn_router_id});
+            // use the link-specific bandwidth if it has an overridden bandwidth, otherwise use the NoC-wide link bandwidth
             double link_bw = (bw_it == noc_info.link_bandwidth_overrides.end()) ? noc_info.link_bandwidth : bw_it->second;
 
             // add the link to the Noc

vpr/src/noc/noc_link.h

@@ -51,7 +51,7 @@ class NocLink {
 
     double bandwidth_usage; /*!< Represents the bandwidth of the data being transmitted on the link. Units in bits-per-second(bps)*/
     double bandwidth; /*!< Represents the maximum bits per second that can be transmitted over the link without causing congestion*/
-    double latency;
+    double latency; /*!< The zero-load latency of this link in seconds.*/
 
   public:
     NocLink(NocLinkId link_id, NocRouterId source_router, NocRouterId sink_router,
@@ -64,33 +64,33 @@ class NocLink {
      * edge
      * @return A unique id (NocRouterId) that identifies the source router of the link
      */
-    NocRouterId get_source_router(void) const;
+    NocRouterId get_source_router() const;
 
     /**
      * @brief Provides the id of the router that has this link as an incoming
      * edge
      * @return A unique id (NocRouterId) that identifies the sink router of the link
      */
-    NocRouterId get_sink_router(void) const;
+    NocRouterId get_sink_router() const;
 
     /**
      * @brief Provides the size of the data (bandwidth) being currently transmitted using the link.
      * @return A numeric value of the bandwidth usage of the link
      */
-    double get_bandwidth_usage(void) const;
+    double get_bandwidth_usage() const;
 
     /**
      * @brief Returns the maximum bandwidth that the link can carry without congestion.
      * @return A numeric value of the bandwidth capacity of the link
      */
-    double get_bandwidth(void) const;
+    double get_bandwidth() const;
 
     /**
      * @brief Calculates the extent to which the current bandwidth utilization
      * exceeds the link capacity. Any positive value means the link is congested.
      * @return A numeric value of the bandwidth over-utilization in the link
      */
-    double get_congested_bandwidth(void) const;
+    double get_congested_bandwidth() const;
 
     /**
      * @brief Computes the congested bandwidth to bandwidth capacity ratio.

vpr/src/noc/noc_router.cpp

@@ -14,23 +14,23 @@ NocRouter::NocRouter(int id,
 }
 
 // getters
-int NocRouter::get_router_user_id(void) const {
+int NocRouter::get_router_user_id() const {
     return router_user_id;
 }
 
-int NocRouter::get_router_grid_position_x(void) const {
+int NocRouter::get_router_grid_position_x() const {
     return router_grid_position_x;
 }
 
-int NocRouter::get_router_grid_position_y(void) const {
+int NocRouter::get_router_grid_position_y() const {
     return router_grid_position_y;
 }
 
-int NocRouter::get_router_layer_position(void) const {
+int NocRouter::get_router_layer_position() const {
     return router_layer_position;
 }
 
-t_physical_tile_loc NocRouter::get_router_physical_location(void) const {
+t_physical_tile_loc NocRouter::get_router_physical_location() const {
     const int x = get_router_grid_position_x();
     const int y = get_router_grid_position_y();
     const int layer = get_router_layer_position();
@@ -43,7 +43,7 @@ double NocRouter::get_latency() const {
     return router_latency;
 }
 
-ClusterBlockId NocRouter::get_router_block_ref(void) const {
+ClusterBlockId NocRouter::get_router_block_ref() const {
     return router_block_ref;
 }
 

vpr/src/noc/noc_router.h

@@ -53,6 +53,7 @@ class NocRouter {
      * that the physical router is located*/
     int router_layer_position;
 
+    /** The zero-load latency of this NoC router. */
     double router_latency;
 
     /** A unique identifier that represents a router block in the 
@@ -70,39 +71,43 @@ class NocRouter {
      * @brief Gets the unique id assigned by the user for the physical router
      * @return A numerical value (integer) that represents the physical router id
      */
-    int get_router_user_id(void) const;
+    int get_router_user_id() const;
 
     /**
      * @brief Gets the horizontal position on the FPGA device that the physical router is located
      * @return A numerical value (integer) that represents horizontal position of the physical router
      */
-    int get_router_grid_position_x(void) const;
+    int get_router_grid_position_x() const;
 
     /**
      * @brief Gets the vertical position on the FPGA device that the physical router is located
      * @return A numerical value (integer) that represents vertical position of the physical router
      */
-    int get_router_grid_position_y(void) const;
+    int get_router_grid_position_y() const;
 
     /**
      * @brief Gets the layer number of the die the the physical router is located
      * @return A numerical value (integer) that represents layer position of the physical router
      */
-    int get_router_layer_position(void) const;
+    int get_router_layer_position() const;
 
     /**
      * @brief Gets the physical location where the the physical router is located
      * @return t_physical_tile_loc that contains x-y coordinates and the layer number
      */
-    t_physical_tile_loc get_router_physical_location(void) const;
+    t_physical_tile_loc get_router_physical_location() const;
 
+    /**
+     * @brief Gets the zero-load latency of this NoC router.
+     * @return The zero-load latency in seconds.
+     */
     double get_latency() const;
 
     /**
      * @brief Gets the unique id of the router block that is current placed on the physical router
      * @return A ClusterBlockId that identifies a router block in the clustered netlist
      */
-    ClusterBlockId get_router_block_ref(void) const;
+    ClusterBlockId get_router_block_ref() const;
 
     // setters
     /**