More commenting

Author: MohamedElgammal

vpr/src/base/vpr_context.h

@@ -289,9 +289,9 @@ struct ClusteringContext : public Context {
 };
 
 /**
- * @brief State relating to helper data structure using in clustering
+ * @brief State relating to helper data structure using in the clustering stage
  * 
- * This should contain helper data structures that is useful in clustering/packing.
+ * This should contain helper data structures that are useful in the clustering/packing stage.
  * They are encapsulated here as they are useful in clustering and reclustering algorithms that may be used
  * in packing or placement stages.
  */
@@ -314,10 +314,10 @@ struct ClusteringHelperContext : public Context {
     // total number of CLBs
     int total_clb_num;
 
-    // A vector of routing resource nodes within each of logic cluster_ctx.blocks types
+    // A vector of routing resource nodes within each of logic cluster_ctx.blocks types [0 .. num_logical_block_type-1]
     std::vector<t_lb_type_rr_node>* lb_type_rr_graphs;
 
-    // the utilization of external input/output pins during packing
+    // the utilization of external input/output pins during packing (between 0 and 1)
     t_ext_pin_util_targets target_external_pin_util;
 
     ~ClusteringHelperContext() {

vpr/src/base/vpr_types.cpp

@@ -147,24 +147,6 @@ const t_pb* t_pb::find_pb_for_model(const std::string& blif_model) const {
     return nullptr; //Not found
 }
 
-/**
- * @brief Deep copy function for t_pb class
- * 
- * This funcion deeply copies some data members of
- * t_pb class to be used to retrieve pb.
- * 
- * This function is currently used in re-clustering API.
- */
-void t_pb::pb_deep_copy(const t_pb* rhs) {
-    name = rhs->name;
-    pb_graph_node = rhs->pb_graph_node;
-    mode = rhs->mode;
-    parent_pb = rhs->parent_pb;
-    pb_stats = rhs->pb_stats;
-    clock_net = rhs->clock_net;
-    pin_rotations_ = rhs->pin_rotations_;
-}
-
 /**
  * @brief Returns the root pb containing this pb
  */
@@ -281,4 +263,4 @@ void free_cluster_placement_stats(t_cluster_placement_stats* cluster_placement_s
         free(cluster_placement_stats_list[index].valid_primitives);
     }
     free(cluster_placement_stats_list);
-}
+}

vpr/src/base/vpr_types.h

@@ -277,16 +277,6 @@ class t_pb {
 
     // Member functions
 
-    /**
-     * @brief Deep copy function for t_pb class
-     * 
-     * This funcion deeply copies some data members of
-     * t_pb class to be used to retrieve pb.
-     * 
-     * This function is currently used in re-clustering API.
-     */
-    void pb_deep_copy(const t_pb* rhs);
-
     ///@brief Returns true if this block has not parent pb block
     bool is_root() const { return parent_pb == nullptr; }
 

vpr/src/pack/re_cluster.cpp

@@ -37,7 +37,7 @@ bool move_mol_to_new_cluster(t_pack_molecule* molecule,
 
     //remove the molecule from its current cluster
     std::vector<AtomBlockId> old_clb_atoms = cluster_to_atoms(old_clb);
-    if(old_clb_atoms.size() == 1) {
+    if (old_clb_atoms.size() == 1) {
         VTR_LOGV(verbosity > 4, "Atom: %zu move failed. This is the last atom in its cluster.\n");
         return false;
     }
@@ -109,7 +109,7 @@ bool move_mol_to_existing_cluster(t_pack_molecule* molecule,
 
     //remove the molecule from its current cluster
     std::vector<AtomBlockId> old_clb_atoms = cluster_to_atoms(old_clb);
-    if(old_clb_atoms.size() == 1) {
+    if (old_clb_atoms.size() == 1) {
         VTR_LOGV(verbosity > 4, "Atom: %zu move failed. This is the last atom in its cluster.\n");
         return false;
     }
@@ -128,7 +128,7 @@ bool move_mol_to_existing_cluster(t_pack_molecule* molecule,
 
     //Add the atom to the new cluster
     t_lb_router_data* new_router_data = nullptr;
-    is_added = pack_mol_in_existing_cluster(molecule, new_clb, new_clb_atoms, during_packing, clustering_data, false, new_router_data);
+    is_added = pack_mol_in_existing_cluster(molecule, new_clb, new_clb_atoms, during_packing, false, clustering_data, new_router_data);
 
     //Commit or revert the move
     if (is_added) {
@@ -184,23 +184,21 @@ bool swap_two_molecules(t_pack_molecule* molecule_1,
     std::vector<AtomBlockId> clb_1_atoms = cluster_to_atoms(clb_1);
     std::vector<AtomBlockId> clb_2_atoms = cluster_to_atoms(clb_2);
 
-    if(clb_1_atoms.size() == 1 || clb_2_atoms.size() == 1) {
+    if (clb_1_atoms.size() == 1 || clb_2_atoms.size() == 1) {
         VTR_LOGV(verbosity > 4, "Atom: %zu, %zu swap failed. This is the last atom in its cluster.\n", molecule_1->atom_block_ids[molecule_1->root], molecule_2->atom_block_ids[molecule_2->root]);
         return false;
     }
 
     //remove the molecule from its current cluster
     remove_mol_from_cluster(molecule_1, molecule_1_size, clb_1, clb_1_atoms, old_1_router_data);
     commit_mol_removal(molecule_1, molecule_1_size, clb_1, during_packing, old_1_router_data, clustering_data);
-    
+
     remove_mol_from_cluster(molecule_2, molecule_2_size, clb_2, clb_2_atoms, old_2_router_data);
-    commit_mol_removal(molecule_2, molecule_2_size, clb_2, during_packing, old_2_router_data, clustering_data); 
-    
+    commit_mol_removal(molecule_2, molecule_2_size, clb_2, during_packing, old_2_router_data, clustering_data);
 
     //Add the atom to the new cluster
-    mol_1_success = pack_mol_in_existing_cluster(molecule_1, clb_2, clb_2_atoms, during_packing, clustering_data, true, old_2_router_data);
-    mol_2_success = pack_mol_in_existing_cluster(molecule_2, clb_1, clb_1_atoms, during_packing, clustering_data, true, old_1_router_data);
-    
+    mol_1_success = pack_mol_in_existing_cluster(molecule_1, clb_2, clb_2_atoms, during_packing, true, clustering_data, old_2_router_data);
+    mol_2_success = pack_mol_in_existing_cluster(molecule_2, clb_1, clb_1_atoms, during_packing, true, clustering_data, old_1_router_data);
 
     //commit the move if succeeded or revert if failed
     if (mol_1_success && mol_2_success) {
@@ -211,7 +209,6 @@ bool swap_two_molecules(t_pack_molecule* molecule_1,
         VTR_LOGV(verbosity > 4, "Molecules swap failed\n");
     }
 
-
     //If the move is done after packing not during it, some fixes need to be done on the clustered netlist
     if (mol_1_success && mol_2_success && !during_packing) {
         fix_clustered_netlist(molecule_1, molecule_1_size, clb_1, clb_2);
@@ -221,4 +218,4 @@ bool swap_two_molecules(t_pack_molecule* molecule_1,
     //return the move result
     return (mol_1_success && mol_2_success);
 }
-#endif
+#endif

vpr/src/pack/re_cluster.h

@@ -15,12 +15,13 @@
 #include "cluster_util.h"
 
 /**
- * @brief This function moves a molecule out of its cluster and create a new cluster for it
+ * @brief This function moves a molecule out of its cluster and creates a new cluster for it
  * 
  * This function can be called from 2 spots in the vpr flow. 
  *   - First, during packing to optimize the initial clustered netlist 
  *             (during_packing variable should be true.)
- *   - Second, during placement (during_packing variable should be false)
+ *   - Second, during placement (during_packing variable should be false). In this case, the clustered
+ *              netlist is updated.
  */
 bool move_mol_to_new_cluster(t_pack_molecule* molecule,
                              bool during_packing,
@@ -33,7 +34,8 @@ bool move_mol_to_new_cluster(t_pack_molecule* molecule,
  * This function can be called from 2 spots in the vpr flow. 
  *   - First, during packing to optimize the initial clustered netlist 
  *             (during_packing variable should be true.)
- *   - Second, during placement (during_packing variable should be false)
+ *   - Second, during placement (during_packing variable should be false). In this case, the clustered
+ *              netlist is updated.
  */
 bool move_mol_to_existing_cluster(t_pack_molecule* molecule,
                                   const ClusterBlockId& new_clb,
@@ -47,11 +49,12 @@ bool move_mol_to_existing_cluster(t_pack_molecule* molecule,
  * This function can be called from 2 spots in the vpr flow. 
  *   - First, during packing to optimize the initial clustered netlist 
  *             (during_packing variable should be true.)
- *   - Second, during placement (during_packing variable should be false)
+ *   - Second, during placement (during_packing variable should be false). In this case, the clustered
+ *              netlist is updated.
  */
 bool swap_two_molecules(t_pack_molecule* molecule_1,
                         t_pack_molecule* molecule_2,
                         bool during_packing,
                         int verbosity,
                         t_clustering_data& clustering_data);
-#endif
+#endif

vpr/src/pack/re_cluster_util.cpp

@@ -58,10 +58,6 @@ void remove_mol_from_cluster(const t_pack_molecule* molecule,
                              t_lb_router_data*& router_data) {
     auto& helper_ctx = g_vpr_ctx.mutable_cl_helper();
 
-    //Determine the cluster ID
-    old_clb = atom_to_cluster(molecule->atom_block_ids[molecule->root]);
-    //std::vector<AtomBlockId> old_clb_atoms = cluster_to_atoms(old_clb);
-
     //re-build router_data structure for this cluster
     router_data = lb_load_router_data(helper_ctx.lb_type_rr_graphs, old_clb, old_clb_atoms);
 
@@ -80,6 +76,7 @@ void commit_mol_move(const ClusterBlockId& old_clb,
                      bool new_clb_created) {
     auto& device_ctx = g_vpr_ctx.device();
 
+    //Place the new cluster if this function called during placement (after the initial placement is done)
     if (!during_packing && new_clb_created) {
         int imacro;
         g_vpr_ctx.mutable_placement().block_locs.resize(g_vpr_ctx.placement().block_locs.size() + 1);
@@ -166,6 +163,7 @@ bool start_new_cluster_for_mol(t_pack_molecule* molecule,
         clb_index = cluster_ctx.clb_nlist.create_block(new_name.c_str(), pb, type);
         helper_ctx.total_clb_num++;
 
+        //If you are still in packing, update the clustering data. Otherwise, update the clustered netlist.
         if (during_packing) {
             clustering_data.intra_lb_routing.push_back((*router_data)->saved_lb_nets);
             (*router_data)->saved_lb_nets = nullptr;
@@ -188,8 +186,8 @@ bool pack_mol_in_existing_cluster(t_pack_molecule* molecule,
                                   const ClusterBlockId new_clb,
                                   const std::vector<AtomBlockId>& new_clb_atoms,
                                   bool during_packing,
-                                  t_clustering_data& clustering_data,
                                   bool is_swap,
+                                  t_clustering_data& clustering_data,
                                   t_lb_router_data*& router_data) {
     auto& helper_ctx = g_vpr_ctx.mutable_cl_helper();
     auto& cluster_ctx = g_vpr_ctx.mutable_clustering();
@@ -204,7 +202,7 @@ bool pack_mol_in_existing_cluster(t_pack_molecule* molecule,
     rebuild_cluster_placemet_stats(new_clb, new_clb_atoms, cluster_ctx.clb_nlist.block_type(new_clb)->index, cluster_ctx.clb_nlist.block_pb(new_clb)->mode);
 
     //re-build router_data structure for this cluster
-    if(!is_swap)
+    if (!is_swap)
         router_data = lb_load_router_data(helper_ctx.lb_type_rr_graphs, new_clb, new_clb_atoms);
 
     pack_result = try_pack_molecule(&(helper_ctx.cluster_placement_stats[block_type->index]),
@@ -225,6 +223,7 @@ bool pack_mol_in_existing_cluster(t_pack_molecule* molecule,
 
     // If clustering succeeds, add it to the clb netlist
     if (pack_result == BLK_PASSED) {
+        //If you are still in packing, update the clustering data. Otherwise, update the clustered netlist.
         if (during_packing) {
             free_intra_lb_nets(clustering_data.intra_lb_routing[new_clb]);
             clustering_data.intra_lb_routing[new_clb] = router_data->saved_lb_nets;
@@ -235,12 +234,12 @@ bool pack_mol_in_existing_cluster(t_pack_molecule* molecule,
         }
     }
 
-    if(pack_result == BLK_PASSED || !is_swap ) {
+    if (pack_result == BLK_PASSED || !is_swap) {
         //Free clustering router data
         free_router_data(router_data);
         router_data = nullptr;
     }
-    
+
     return (pack_result == BLK_PASSED);
 }
 
@@ -277,6 +276,7 @@ void revert_mol_move(const ClusterBlockId& old_clb,
                                                         temp_cluster_pr_original);
 
     VTR_ASSERT(pack_result == BLK_PASSED);
+    //If you are still in packing, update the clustering data. Otherwise, update the clustered netlist.
     if (during_packing) {
         free_intra_lb_nets(clustering_data.intra_lb_routing[old_clb]);
         clustering_data.intra_lb_routing[old_clb] = old_router_data->saved_lb_nets;
@@ -384,8 +384,10 @@ static void fix_cluster_pins_after_moving(const ClusterBlockId clb_index) {
     int iport, ipb_pin, ipin, rr_node_index;
 
     ipin = 0;
+    // iterating over input ports
     for (iport = 0; iport < num_input_ports; iport++) {
         ClusterPortId input_port_id = cluster_ctx.clb_nlist.find_port(clb_index, block_type->pb_type->ports[iport].name);
+        // iterating over physical block pins of each input port
         for (ipb_pin = 0; ipb_pin < pb->pb_graph_node->num_input_pins[iport]; ipb_pin++) {
             pb_graph_pin = &pb->pb_graph_node->input_pins[iport][ipb_pin];
             rr_node_index = pb_graph_pin->pin_count_in_cluster;
@@ -408,8 +410,10 @@ static void fix_cluster_pins_after_moving(const ClusterBlockId clb_index) {
         }
     }
 
+    // iterating over output ports
     for (iport = 0; iport < num_output_ports; iport++) {
         ClusterPortId output_port_id = cluster_ctx.clb_nlist.find_port(clb_index, block_type->pb_type->ports[num_input_ports + iport].name);
+        // iterating over physical block pins of each output port
         for (ipb_pin = 0; ipb_pin < pb->pb_graph_node->num_output_pins[iport]; ipb_pin++) {
             pb_graph_pin = &pb->pb_graph_node->output_pins[iport][ipb_pin];
             rr_node_index = pb_graph_pin->pin_count_in_cluster;
@@ -437,8 +441,10 @@ static void fix_cluster_pins_after_moving(const ClusterBlockId clb_index) {
         }
     }
 
+    // iterating over clock ports
     for (iport = 0; iport < num_clock_ports; iport++) {
         ClusterPortId clock_port_id = cluster_ctx.clb_nlist.find_port(clb_index, block_type->pb_type->ports[num_input_ports + num_output_ports + iport].name);
+        // iterating over physical block pins of each clock port
         for (ipb_pin = 0; ipb_pin < pb->pb_graph_node->num_clock_pins[iport]; ipb_pin++) {
             pb_graph_pin = &pb->pb_graph_node->clock_pins[iport][ipb_pin];
             rr_node_index = pb_graph_pin->pin_count_in_cluster;
@@ -651,6 +657,7 @@ void commit_mol_removal(const t_pack_molecule* molecule,
 
     cleanup_pb(cluster_ctx.clb_nlist.block_pb(old_clb));
 
+    //If you are still in packing, update the clustering data. Otherwise, update the clustered netlist.
     if (during_packing) {
         free_intra_lb_nets(clustering_data.intra_lb_routing[old_clb]);
         clustering_data.intra_lb_routing[old_clb] = router_data->saved_lb_nets;
@@ -679,4 +686,4 @@ bool check_type_and_mode_compitability(const ClusterBlockId& old_clb,
     }
 
     return true;
-}
+}