[vpr][place] add more comments to net_cost_handler.h

Author: amin1377

vpr/src/place/move_utils.h

@@ -97,9 +97,9 @@ e_create_move create_move(t_pl_blocks_to_be_moved& blocks_affected, ClusterBlock
 
 /**
  * @brief Find the blocks that will be affected by a move of b_from to to_loc
- * @param blocks_affected
- * @param b_from
- * @param to
+ * @param blocks_affected Loaded by this routine and returned via reference; it lists the blocks etc. moved
+ * @param b_from Id of the cluster-level block to be moved
+ * @param to Where b_from will be moved to
  * @return e_block_move_result ABORT if either of the the moving blocks are already stored, or either of the blocks are fixed, to location is not
  * compatible, etc. INVERT if the "from" block is a single block and the "to" block is a macro. VALID otherwise.
  */
@@ -121,7 +121,7 @@ e_block_move_result record_macro_self_swaps(t_pl_blocks_to_be_moved& blocks_affe
  * @brief Check whether the "to" location is legal for the given "blk"
  * @param blk
  * @param to
- * @return
+ * @return True if this would be a legal move, false otherwise
  */
 bool is_legal_swap_to_location(ClusterBlockId blk, t_pl_loc to);
 

vpr/src/place/net_cost_handler.cpp

@@ -1854,28 +1854,6 @@ static void set_bb_delta_cost(const int num_affected_nets, double& bb_delta_c) {
     }
 }
 
-/**
- * @brief Find all the nets and pins affected by this swap and update costs.
- *
- * Find all the nets affected by this swap and update the bounding box (wiring)
- * costs. This cost function doesn't depend on the timing info.
- *
- * Find all the connections affected by this swap and update the timing cost.
- * For a connection to be affected, it not only needs to be on or driven by
- * a block, but it also needs to have its delay changed. Otherwise, it will
- * not be added to the affected_pins structure.
- *
- * For more, see update_td_delta_costs().
- *
- * The timing costs are calculated by getting the new connection delays,
- * multiplied by the connection criticalities returned by the timing
- * analyzer. These timing costs are stored in the proposed_* data structures.
- *
- * The change in the bounding box cost is stored in `bb_delta_c`.
- * The change in the timing cost is stored in `timing_delta_c`.
- *
- * @return The number of affected nets.
- */
 int find_affected_nets_and_update_costs(
     const t_place_algorithm& place_algorithm,
     const PlaceDelayModel* delay_model,
@@ -2258,11 +2236,7 @@ void init_try_swap_net_cost_structs(size_t num_nets, bool cube_bb) {
         layer_ts_bb_coord_new.resize(num_nets, std::vector<t_2D_bb>(num_layers, t_2D_bb()));
     }
 
-    ts_layer_sink_pin_count.resize({num_nets, size_t(num_layers)});
-    for (size_t flat_idx = 0; flat_idx < ts_layer_sink_pin_count.size(); flat_idx++) {
-        auto& elem = ts_layer_sink_pin_count.get(flat_idx);
-        elem = OPEN;
-    }
+    ts_layer_sink_pin_count.resize({num_nets, size_t(num_layers)}, OPEN);
 
     ts_nets_to_update.resize(num_nets, ClusterNetId::INVALID());
 }

vpr/src/place/net_cost_handler.h

@@ -4,21 +4,43 @@
 #include "move_transactions.h"
 #include "place_util.h"
 
+/**
+ * @brief The method used to calculate palcement cost
+ * NORMAL: Compute cost efficiently using incremental techniques.
+ * CHECK: Brute-force cost computation; useful to validate the more complex incremental cost update code.
+ */
 enum e_cost_methods {
     NORMAL,
     CHECK
 };
 
 /**
- * @brief Update the wire length and timing cost of the blocks (ts and proposed_* data structures) and set
- * the delta costs in bb_delta_c and timing_delta_c. This functions is used when the moving bocks are clusters
+ * @brief Find all the nets and pins affected by this swap and update costs.
+ *
+ * Find all the nets affected by this swap and update the bounding box (wiring)
+ * costs. This cost function doesn't depend on the timing info.
+ *
+ * Find all the connections affected by this swap and update the timing cost.
+ * For a connection to be affected, it not only needs to be on or driven by
+ * a block, but it also needs to have its delay changed. Otherwise, it will
+ * not be added to the affected_pins structure.
+ *
+ * For more, see update_td_delta_costs().
+ *
+ * The timing costs are calculated by getting the new connection delays,
+ * multiplied by the connection criticalities returned by the timing
+ * analyzer. These timing costs are stored in the proposed_* data structures.
+ *
+ * The change in the bounding box cost is stored in `bb_delta_c`.
+ * The change in the timing cost is stored in `timing_delta_c`.
+ * 
  * @param place_algorithm
  * @param delay_model
  * @param criticalities
  * @param blocks_affected
  * @param bb_delta_c
  * @param timing_delta_c
- * @return
+ * @return The number of affected nets.
  */
 int find_affected_nets_and_update_costs(
     const t_place_algorithm& place_algorithm,
@@ -29,37 +51,36 @@ int find_affected_nets_and_update_costs(
     double& timing_delta_c);
 
 /**
- * @brief Finds the bb cost from scratch (based on 3D BB).  Done only when the placement   *
-* has been radically changed (i.e. after initial placement).   *
-* Otherwise find the cost change incrementally.  If method     *
-* check is NORMAL, we find bounding boxes that are updatable  *
-* for the larger nets.  If method is CHECK, all bounding boxes *
-* are found via the non_updateable_bb routine, to provide a    *
-* cost which can be used to check the correctness of the       *
-* other routine.                                               *
+ * @brief Finds the bb cost from scratch (based on 3D BB).  
+ * Done only when the placement has been radically changed 
+ * (i.e. after initial placement). Otherwise find the cost 
+ * change incrementally. If method check is NORMAL, we find 
+ * bounding boxes that are updatable for the larger nets.  
+ * If method is CHECK, all bounding boxes are found via the 
+ * non_updateable_bb routine, to provide a cost which can be 
+ * used to check the correctness of the other routine.                                               
  * @param method
- * @return
+ * @return The bounding box cost of the placement, computed by the 3D method.
  */
 double comp_bb_cost(e_cost_methods method);
 
 /**
- * @brief Finds the bb cost from scratch (based on per-layer BB).  Done only when the placement   *
-* has been radically changed (i.e. after initial placement).   *
-* Otherwise find the cost change incrementally.  If method     *
-* check is NORMAL, we find bounding boxes that are updateable  *
-* for the larger nets.  If method is CHECK, all bounding boxes *
-* are found via the non_updateable_bb routine, to provide a    *
-* cost which can be used to check the correctness of the       *
-* other routine.                                               *
+ * @brief Finds the bb cost from scratch (based on per-layer BB).  
+ * Done only when the placement has been radically changed 
+ * (i.e. after initial placement). Otherwise find the cost change 
+ * incrementally.  If method check is NORMAL, we find bounding boxes 
+ * that are updateable for the larger nets.  If method is CHECK, all 
+ * bounding boxes are found via the non_updateable_bb routine, to provide 
+ * a cost which can be used to check the correctness of the other routine.                                              
  * @param method
- * @return
+ * @return The placement bounding box cost, computed by the per layer method.
  */
 double comp_layer_bb_cost(e_cost_methods method);
 
 /**
  * @brief update net cost data structures (in placer context and net_cost in .cpp file) and reset flags (proposed_net_cost and bb_updated_before).
- * @param num_nets_affected
- * @param cube_bb
+ * @param num_nets_affected The number of nets affected by the move. It is used to determine the index up to which elements in ts_nets_to_update are valid.
+ * @param cube_bb True if we should use the 3D bounding box (cube_bb), false otherwise.
  */
 void update_move_nets(int num_nets_affected,
                       const bool cube_bb);
@@ -72,12 +93,13 @@ void reset_move_nets(int num_nets_affected);
 
 /**
  * @brief re-calculates different terms of the cost function (wire-length, timing, NoC) and update "costs" accordingly. It is important to note that
- * in this function bounding box and connection delays are not calculated from scratch. However, it iterated over nets and add their costs from beginning.
+ * in this function bounding box and connection delays are not calculated from scratch. However, it iterates over all nets and connections and updates 
+ * their costs by a complete summation, rather than incrementally.
  * @param placer_opts
  * @param noc_opts
  * @param delay_model
  * @param criticalities
- * @param costs
+ * @param costs passed by reference and computed by this routine (i.e. returned by reference)
  */
 void recompute_costs_from_scratch(const t_placer_opts& placer_opts,
                                 const t_noc_opts& noc_opts,
@@ -89,7 +111,8 @@ void recompute_costs_from_scratch(const t_placer_opts& placer_opts,
  * @brief Allocates and loads the chanx_place_cost_fac and chany_place_cost_fac
  * arrays with the inverse of the average number of tracks per channel
  * between [subhigh] and [sublow].
- * @param place_cost_exp
+ * @param place_cost_exp It is an exponent to which you take the average inverse channel 
+ * capacity; a higher value would favour wider channels more over narrower channels during placement (usually we use 1).
  */
 void alloc_and_load_for_fast_cost_update(float place_cost_exp);
 
@@ -100,7 +123,7 @@ void free_fast_cost_update();
 
 /**
  * @brief Resize net_cost, proposed_net_cost, and  bb_updated_before data structures to accommodate all nets.
- * @param num_nets
+ * @param num_nets Number of nets in the netlist (clustered currently) that the placement engine uses.
  */
 void init_net_cost_structs(size_t num_nets);
 
@@ -110,9 +133,11 @@ void init_net_cost_structs(size_t num_nets);
 void free_net_cost_structs();
 
 /**
- * @brief Resize (layer_)ts_bb_edge_new, (layer_)ts_bb_coord_new, ts_layer_sink_pin_count, and ts_nets_to_update to accommodate all nets.
- * @param num_nets
- * @param cube_bb
+ * @brief Resize temporary storage data structures needed to determine which nets are affected by a move and data needed per net 
+ * about where their terminals are in order to quickly (incrementally) update their wirelength costs. These data structures are  
+ * (layer_)ts_bb_edge_new, (layer_)ts_bb_coord_new, ts_layer_sink_pin_count, and ts_nets_to_update.
+ * @param num_nets Number of nets in the netlist used by the placement engine (currently clustered netlist)
+ * @param cube_bb True if the 3D bounding box should be used, false otherwise.
  */
 void init_try_swap_net_cost_structs(size_t num_nets, bool cube_bb);