[Packer] Updated Comments

Updated comments based on Vaughn's feedback.

Author: AlexandreSinger

vpr/src/pack/cluster_util.cpp

@@ -1879,9 +1879,6 @@ void print_pb_type_count_recurr(t_pb_type* pb_type, size_t max_name_chars, size_
     }
 }
 
-/**
- * Print the total number of used physical blocks for each pb type in the architecture
- */
 void print_pb_type_count(const ClusteredNetlist& clb_nlist) {
     auto& device_ctx = g_vpr_ctx.device();
 

vpr/src/pack/cluster_util.h

@@ -481,6 +481,9 @@ void update_le_count(const t_pb* pb, const t_logical_block_type_ptr logic_block_
 
 void print_pb_type_count_recurr(t_pb_type* type, size_t max_name_chars, size_t curr_depth, std::map<t_pb_type*, int>& pb_type_count);
 
+/**
+ * Print the total number of used physical blocks for each pb type in the architecture
+ */
 void print_pb_type_count(const ClusteredNetlist& clb_nlist);
 
 /*

vpr/src/pack/greedy_clusterer.cpp

@@ -1,6 +1,9 @@
 /**
  * @file
- * @author  Vaughn Betz (first revision - VPack), Alexander Marquardt (second revision - T-VPack), Jason Luu (third revision - AAPack)
+ * @author  Vaughn Betz (first revision - VPack),
+ *          Alexander Marquardt (second revision - T-VPack),
+ *          Jason Luu (third revision - AAPack),
+ *          Alex Singer (fourth revision - APPack)
  * @date    June 8, 2011
  * @brief   Main clustering algorithm
  *

vpr/src/pack/greedy_clusterer.h

@@ -29,6 +29,12 @@ struct t_packer_opts;
  *
  * This clusterer generates one cluster at a time by finding candidate molecules
  * and selecting the molecule with the highest gain.
+ *
+ * The clusterer takes an Atom Netlist which has be pre-packed into pack
+ * patterns (e.g. carry chains) as input and produces a set of legal clusters
+ * of these pack molecules as output. Legality here means that it was able to
+ * find a valid intra-lb route for the inputs of the clusters, through the
+ * internal molecules, and to the outputs of the clusters.
  */
 class GreedyClusterer {
 public:
@@ -51,11 +57,20 @@ class GreedyClusterer {
      *              The architecture to cluster over.
      *  @param high_fanout_thresholds
      *              The thresholds for what to consider as a high-fanout net
-     *              for each logical block type.
+     *              for each logical block type. The clusterer will not consider
+     *              nets with fanout higher than this to be important in
+     *              candidate block selection (gain computation).
+     *              A reason for it being per block type is that some blocks,
+     *              like RAMs, have weak gains to other RAM primitives due to
+     *              fairly high fanout address nets, so a higher fanout
+     *              threshold for them is useful in generating a more dense
+     *              packing.
      *  @param is_clock
      *              The set of clock nets in the Atom Netlist.
      *  @param is_global
-     *              The set of global nets in the Atom Netlist.
+     *              The set of global nets in the Atom Netlist. These will be
+     *              routed on special dedicated networks, and hence are less
+     *              relavent to locality / attraction.
      */
     GreedyClusterer(const t_packer_opts& packer_opts,
                     const t_analysis_opts& analysis_opts,
@@ -75,21 +90,30 @@ class GreedyClusterer {
      *              grow clusters by adding molecules to a cluster.
      *  @param prepacker
      *              The prepacker object which contains the pack molecules that
-     *              atoms are pre-packed into before clustering.
+     *              are atoms which are pre-packed before the main clustering
+     *              (due to pack patterns, e.g. carry chains).
      *  @param allow_unrelated_clustering
      *              Allows primitives which have no attraction to the given
-     *              cluster to be packed into it.
+     *              cluster to be packed into it. This can lead to a denser
+     *              packing, but tends to be bad for wirelength and timing.
      *  @param balance_block_type_utilization
      *              When true, tries to create clusters that balance the logical
-     *              block type utilization.
+     *              block type utilization. This is useful when some primitives
+     *              have multiple logical block types to which they can cluster,
+     *              e.g. multiple sizes of physical RAMs exist on the chip.
      *  @param attraction_groups
      *              Information on the attraction groups used during the
-     *              clustering process.
+     *              clustering process. These are groups of primitives that have
+     *              extra attraction to each other; currently they are used to
+     *              guide the clusterer when it must cluster some parts of a
+     *              design densely due to user placement/floorplanning
+     *              constraints. They are created if some floorplan regions are
+     *              overfilled after a clustering attempt.
      *
      *  @return num_used_type_instances
-     *              The number of used logical block types by the clustering.
-     *              This information may be useful when detecting if the
-     *              clustering can fit on the device.
+     *              The number of used logical blocks of each type by the
+     *              clustering. This information may be useful when detecting
+     *              if the clustering can fit on the device.
      */
     std::map<t_logical_block_type_ptr, size_t>
     do_clustering(ClusterLegalizer& cluster_legalizer,
@@ -109,12 +133,28 @@ class GreedyClusterer {
      */
     static constexpr int attraction_groups_max_repeated_molecules_ = 500;
 
+    /// @brief The packer options used to configure the clusterer.
     const t_packer_opts& packer_opts_;
+
+    /// @brief The analysis options used to configure timing analysis within the
+    ///        clusterer.
     const t_analysis_opts& analysis_opts_;
+
+    /// @brief The atom netlist to cluster over.
     const AtomNetlist& atom_netlist_;
+
+    /// @brief The device architecture to cluster onto.
     const t_arch* arch_ = nullptr;
+
+    /// @brief The high-fanout thresholds per logical block type. Used to ignore
+    ///        certain nets when calculating the gain for the next candidate
+    ///        molecule to cluster.
     const t_pack_high_fanout_thresholds& high_fanout_thresholds_;
+
+    /// @brief A set of atom nets which are considered as clocks.
     const std::unordered_set<AtomNetId>& is_clock_;
+
+    /// @brief A set of atom nets which are considered as global nets.
     const std::unordered_set<AtomNetId>& is_global_;
 
     /// @brief Pre-computed logical block types for each model in the architecture.