From 2232cd471add668ec2d978cdc56dd19485da5332 Mon Sep 17 00:00:00 2001 From: AlexandreSinger Date: Fri, 22 Nov 2024 14:18:22 -0500 Subject: [PATCH] [Packer] Updated Comments Updated comments based on Vaughn's feedback. --- vpr/src/pack/cluster_util.cpp | 3 -- vpr/src/pack/cluster_util.h | 3 ++ vpr/src/pack/greedy_clusterer.cpp | 5 ++- vpr/src/pack/greedy_clusterer.h | 58 ++++++++++++++++++++++++++----- 4 files changed, 56 insertions(+), 13 deletions(-) diff --git a/vpr/src/pack/cluster_util.cpp b/vpr/src/pack/cluster_util.cpp index ee003f0e46..7597516aa4 100644 --- a/vpr/src/pack/cluster_util.cpp +++ b/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(); diff --git a/vpr/src/pack/cluster_util.h b/vpr/src/pack/cluster_util.h index 10a5d10ee5..a5bcd7f1fe 100644 --- a/vpr/src/pack/cluster_util.h +++ b/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& 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); /* diff --git a/vpr/src/pack/greedy_clusterer.cpp b/vpr/src/pack/greedy_clusterer.cpp index 3e89e2bd3c..997d21e7cd 100644 --- a/vpr/src/pack/greedy_clusterer.cpp +++ b/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 * diff --git a/vpr/src/pack/greedy_clusterer.h b/vpr/src/pack/greedy_clusterer.h index 2c3d41825c..816043c91b 100644 --- a/vpr/src/pack/greedy_clusterer.h +++ b/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 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& is_clock_; + + /// @brief A set of atom nets which are considered as global nets. const std::unordered_set& is_global_; /// @brief Pre-computed logical block types for each model in the architecture.