add comments

Author: soheilshahrouz

vpr/src/pack/cluster_util.h

@@ -280,12 +280,44 @@ enum e_block_pack_status try_place_atom_block_rec(const t_pb_graph_node* pb_grap
                                                   int verbosity,
                                                   const int feasible_block_array_size);
 
+
+/**
+ * @brief Checks whether an atom block can be added to a clustered block
+ * without violating floorplanning constraints. It also updates the
+ * clustered block's floorplanning region by taking the intersection of
+ * its current region and the floorplanning region of the given atom block.
+ *
+ * @param blk_id A unique ID for the candidate atom block to be added to the growing cluster.
+ * @param clb_index A unique ID for the clustered block that the atom block wants to be added to.
+ * @param verbosity Controls the detail level of log information printed by this function.
+ * @param temp_cluster_pr The floorplanning regions of the clustered block. This function may
+ * update the given region.
+ * @param cluster_pr_needs_update Indicates whether the floorplanning region of the clustered block
+ * have updated.
+ * @return True if adding the given atom block to the clustered block does not violated any
+ * floorplanning constraints.
+ */
 bool atom_cluster_floorplanning_check(AtomBlockId blk_id,
                                       ClusterBlockId clb_index,
                                       int verbosity,
                                       PartitionRegion& temp_cluster_pr,
                                       bool& cluster_pr_needs_update);
-
+/**
+ * @brief Checks if an atom block can be added to a clustered block without
+ * violating NoC group constraints. For passing this check, either both clustered
+ * and atom blocks must belong to the same NoC group, or at least one of them should
+ * not belong to any NoC group. If the atom block is associated with a NoC group while
+ * the clustered block does not belong to any NoC groups, the NoC group ID of the atom block
+ * is assigned to the clustered block when the atom is added to it.
+ * block
+ *
+ * @param blk_id A unique ID for the candidate atom block to be added to the growing cluster.
+ * @param clb_index A unique ID for the clustered block that the atom block wants to be added to.
+ * @param verbosity Controls the detail level of log information printed by this function.
+ * @param temp_cluster_noc_grp_id The NoC group ID of the clustered block. This function may update
+ * this ID.
+ * @return True if adding the atom block the cluster does not violate NoC group constraints.
+ */
 bool atom_cluster_noc_group_check(AtomBlockId blk_id,
                                   ClusterBlockId clb_index,
                                   int verbosity,

vpr/src/place/centroid_move_generator.h

@@ -20,12 +20,41 @@
  */
 class CentroidMoveGenerator : public MoveGenerator {
   public:
+    /**
+     * The move generator created by calling this constructor only consider
+     * netlist connectivity for computing the centroid location.
+     */
     CentroidMoveGenerator();
+
+    /**
+     * The move generator created by calling this constructor considers both
+     * netlist connectivity and NoC reachability for computing the centroid.
+     * The constructor also forms NoC groups by finding connected components
+     * in the graph representing the clustered netlist. When finding connected
+     * components, none of the nets whose fanout is larger than high_fanout_net
+     * are traversed.
+     * @param noc_attraction_weight Specifies how much the computed centroid
+     * is adjusted towards the location of NoC routers in the same NoC group as
+     * the clustered block to be moved.
+     * @param high_fanout_net All nets with a fanout larger than this number are
+     * ignored when forming NoC groups.
+     */
     CentroidMoveGenerator(float noc_attraction_weight, size_t high_fanout_net);
 
 
+    /**
+     * Returns all NoC routers that are in the NoC group with a given ID.
+     * @param noc_grp_id The NoC group ID whose NoC routers are requested.
+     * @return The clustered block ID of all NoC routers in the given NoC group.
+     */
     static const std::vector<ClusterBlockId>& get_noc_group_routers(NocGroupId noc_grp_id);
 
+    /**
+     * Returns the NoC group ID of clustered block.
+     * @param blk_id The clustered block whose NoC group ID is requested.
+     * @return The NoC group ID of the given clustered block or INVALID if
+     * the given clustered block does not belong to any NoC groups.
+     */
     static NocGroupId get_cluster_noc_group(ClusterBlockId blk_id);
 
   private:
@@ -43,7 +72,7 @@ class CentroidMoveGenerator : public MoveGenerator {
     /** Indicates whether the centroid calculation is NoC-biased.*/
     bool noc_attraction_enabled_;
 
-    /** Stores all non-router blocks for each NoC group*/
+    /** Stores the ids of all non-router clustered blocks for each NoC group*/
     static vtr::vector<NocGroupId, std::vector<ClusterBlockId>> noc_group_clusters_;
 
     /** Stores NoC routers in each NoC group*/

vpr/src/place/directed_moves_util.h

@@ -25,11 +25,21 @@ void get_coordinate_of_pin(ClusterPinId pin, t_physical_tile_loc& tile_loc);
  * This function is very useful in centroid and weightedCentroid moves as it calculates
  * the centroid location. It returns the calculated location in centroid.
  *
- *      @param b_from: The block Id of the moving block
- *      @param timing_weights: Determines whether to calculate centroid or weighted centroid location. If true, use the timing weights (weighted centroid)
- *      @param criticalities: A pointer to the placer criticalities which is used when calculating weighted centroid (send a NULL pointer in case of centroid)
+ * When NoC attraction is enabled, the computed centroid is slightly adjusted towards the location
+ * of NoC routers that are in the same NoC group b_from.
+ *
+ * @param b_from The block Id of the moving block
+ * @param timing_weights Determines whether to calculate centroid or
+ * weighted centroid location. If true, use the timing weights (weighted centroid).
+ * @param criticalities A pointer to the placer criticalities which is used when
+ * calculating weighted centroid (send a NULL pointer in case of centroid)
+ * @param noc_attraction_enabled Indicates whether the computed centroid location
+ * should be adjusted towards NoC routers in the NoC group of the given block.
+ * @param noc_attraction_weight When NoC attraction is enabled, this weight
+ * specifies to which extent the computed centroid should be adjusted. A value
+ * in range [0, 1] is expected.
  * 
- *      @return The calculated location is returned in centroid parameter that is sent by reference
+ * @return The calculated location is returned in centroid parameter that is sent by reference
  */
 void calculate_centroid_loc(ClusterBlockId b_from,
                             bool timing_weights,
@@ -42,7 +52,7 @@ inline void calculate_centroid_loc(ClusterBlockId b_from,
                                    bool timing_weights,
                                    t_pl_loc& centroid,
                                    const PlacerCriticalities* criticalities) {
-    calculate_centroid_loc(b_from, timing_weights,centroid, criticalities,false, 0.0f);
+    calculate_centroid_loc(b_from, timing_weights, centroid, criticalities, false, 0.0f);
 }
 
 #endif

vpr/src/place/move_utils.cpp

@@ -254,13 +254,13 @@ e_block_move_result record_macro_macro_swaps(t_pl_blocks_to_be_moved& blocks_aff
     //Continue walking along the overlapping parts of the from and to macros, recording
     //each block swap.
     //
-    //At the momemnt we only support swapping the two macros if they have the same shape.
+    //At the moment we only support swapping the two macros if they have the same shape.
     //This will be the case with the common cases we care about (i.e. carry-chains), so
     //we just abort in any other cases (if these types of macros become more common in
     //the future this could be updated).
     //
-    //Unless the two macros have thier root blocks aligned (i.e. the mutual overlap starts
-    //at imember_from == 0), then theree will be a fixed offset between the macros' relative
+    //Unless the two macros have their root blocks aligned (i.e. the mutual overlap starts
+    //at imember_from == 0), then there will be a fixed offset between the macros' relative
     //position. We record this as from_to_macro_*_offset which is used to verify the shape
     //of the macros is consistent.
     //
@@ -1036,7 +1036,8 @@ void compressed_grid_to_loc(t_logical_block_type_ptr blk_type,
     to_loc = t_pl_loc(grid_loc.x, grid_loc.y, sub_tile, grid_loc.layer_num);
 }
 
-int has_empty_compatible_subtile(t_logical_block_type_ptr type, const t_physical_tile_loc& to_loc) {
+int find_empty_compatible_subtile(t_logical_block_type_ptr type,
+                                  const t_physical_tile_loc& to_loc) {
     auto& device_ctx = g_vpr_ctx.device();
     auto& place_ctx = g_vpr_ctx.placement();
 
@@ -1148,7 +1149,7 @@ bool find_compatible_compressed_loc_in_range(t_logical_block_type_ptr type,
             if (from_loc.x == to_loc.x && from_loc.y == to_loc.y && from_loc.layer_num == to_layer_num) {
                 continue;                  //Same from/to location -- try again for new y-position
             } else if (search_for_empty) { // Check if the location has at least one empty sub-tile
-                legal = has_empty_compatible_subtile(type, to_loc) >= 0;
+                legal = find_empty_compatible_subtile(type, to_loc) >= 0;
             } else {
                 legal = true;
             }

vpr/src/place/move_utils.h

@@ -225,16 +225,19 @@ void compressed_grid_to_loc(t_logical_block_type_ptr blk_type,
                             t_pl_loc& to_loc);
 
 /**
- * @brief Checks whether the given location has a compatible empty subtile with
- * the given type.
+ * @brief Tries to find an compatible empty subtile with the given type at
+ * the given location. If such a subtile could be found, the subtile number
+ * is returned. Otherwise, -1 is returned to indicate that there are no
+ * compatible subtiles at the given location.
  *
  * @param type logical block type
  * @param to_loc The location to be checked
  *
- * @return bool True if the given location has at least one empty compatible subtile.
+ * @return int The subtile number if there is an empty compatible subtile, otherwise -1
+ * is returned to indicate that there are no empty subtiles compatible with the given type..
  */
-int has_empty_compatible_subtile(t_logical_block_type_ptr type,
-                                 const t_physical_tile_loc& to_loc);
+int find_empty_compatible_subtile(t_logical_block_type_ptr type,
+                                  const t_physical_tile_loc& to_loc);
 
 /**
  * @brief find compressed location in a compressed range for a specific type in the given layer (to_layer_num)

vpr/src/util/vpr_utils.cpp

@@ -23,7 +23,7 @@
 
 /* This defines the maximum string length that could be parsed by functions  *
  * in vpr_utils.                                                             */
-static constexpr size_t MAX_STRING_LEN = 128;
+static constexpr size_t MAX_STRING_LEN = 512;
 
 /******************** File-scope variables declarations **********************/