[ClusterLegalizer] Updated Based on PR Comments

Added more documentation. Cleaned up one set which should have been a
vector.

Author: AlexandreSinger

vpr/src/base/vpr_api.cpp

@@ -15,6 +15,7 @@
 #include <cstring>
 #include <cmath>
 
+#include "cluster_util.h"
 #include "vpr_context.h"
 #include "vtr_assert.h"
 #include "vtr_math.h"
@@ -616,7 +617,7 @@ bool vpr_pack_flow(t_vpr_setup& vpr_setup, const t_arch& arch) {
 
         }
 
-        // Load cluster_constraints data structure here since loading pack file
+        // Load cluster_constraints data structure.
         load_cluster_constraints();
 
         /* Sanity check the resulting netlist */
@@ -708,11 +709,7 @@ void vpr_load_packing(t_vpr_setup& vpr_setup, const t_arch& arch) {
                                          vpr_setup.PackerOpts.pack_verbosity);
 
     /* Load the mapping between clusters and their atoms */
-    cluster_ctx.atoms_lookup.resize(cluster_ctx.clb_nlist.blocks().size());
-    for (AtomBlockId atom_blk_id : atom_ctx.nlist.blocks()) {
-        ClusterBlockId atom_cluster_blk_id = atom_ctx.lookup.atom_clb(atom_blk_id);
-        cluster_ctx.atoms_lookup[atom_cluster_blk_id].insert(atom_blk_id);
-    }
+    init_clb_atoms_lookup(cluster_ctx.atoms_lookup, atom_ctx, cluster_ctx.clb_nlist);
 
     process_constant_nets(g_vpr_ctx.mutable_atom().nlist,
                           atom_ctx.lookup,

vpr/src/pack/cluster_legalizer.cpp

@@ -4,7 +4,7 @@
  * @date    September 2024
  * @brief   The implementation of the Cluster Legalizer class.
  *
- * Most of the code in this file was original part of cluster_util.cpp and was
+ * Most of the code in this file was originally part of cluster_util.cpp and was
  * highly integrated with the clusterer in VPR. All code that was used for
  * legalizing the clusters was moved into this file and all the functionality
  * was moved into the ClusterLegalizer class.
@@ -40,6 +40,8 @@
 
 /*
  * @brief Gets the max cluster size that any logical block can have.
+ *
+ * This is the maximum number of primitives any cluster can contain.
  */
 static size_t calc_max_cluster_size(const std::vector<t_logical_block_type>& logical_block_types) {
     size_t max_cluster_size = 0;
@@ -63,11 +65,6 @@ static void alloc_and_load_pb_stats(t_pb* pb, const int feasible_block_array_siz
 
     pb->pb_stats = new t_pb_stats;
 
-    /* If statement below is for speed.  If nets are reasonably low-fanout,  *
-     * only a relatively small number of blocks will be marked, and updating *
-     * only those atom block structures will be fastest.  If almost all blocks    *
-     * have been touched it should be faster to just run through them all    *
-     * in order (less addressing and better cache locality).                 */
     pb->pb_stats->input_pins_used = std::vector<std::unordered_map<size_t, AtomNetId>>(pb->pb_graph_node->num_input_pin_class);
     pb->pb_stats->output_pins_used = std::vector<std::unordered_map<size_t, AtomNetId>>(pb->pb_graph_node->num_output_pin_class);
     pb->pb_stats->lookahead_input_pins_used = std::vector<std::vector<AtomNetId>>(pb->pb_graph_node->num_input_pin_class);
@@ -304,10 +301,10 @@ static bool check_cluster_noc_group(AtomBlockId atom_blk_id,
 }
 
 /**
- * This function takes the root block of a chain molecule and a proposed
- * placement primitive for this block. The function then checks if this
- * chain root block has a placement constraint (such as being driven from
- * outside the cluster) and returns the status of the placement accordingly.
+ * @brief This function takes the root block of a chain molecule and a proposed
+ *        placement primitive for this block. The function then checks if this
+ *        chain root block has a placement constraint (such as being driven from
+ *        outside the cluster) and returns the status of the placement accordingly.
  */
 static enum e_block_pack_status check_chain_root_placement_feasibility(const t_pb_graph_node* pb_graph_node,
                                                                 const t_pack_molecule* molecule,
@@ -368,7 +365,7 @@ static enum e_block_pack_status check_chain_root_placement_feasibility(const t_p
 
 /*
  * @brief Check that the two atom blocks blk_id and sibling_blk_id (which should
- *        both be memory slices) are feasible, in the sence that they have
+ *        both be memory slices) are feasible, in the sense that they have
  *        precicely the same net connections (with the exception of nets in data
  *        port classes).
  *
@@ -480,7 +477,7 @@ static bool primitive_feasible(const AtomBlockId blk_id, t_pb* cur_pb) {
 }
 
 /**
- * Try place atom block into current primitive location
+ * @brief Try to place atom block into current primitive location
  */
 static enum e_block_pack_status
 try_place_atom_block_rec(const t_pb_graph_node* pb_graph_node,
@@ -613,7 +610,10 @@ try_place_atom_block_rec(const t_pb_graph_node* pb_graph_node,
     return block_pack_status;
 }
 
-/* Resets nets used at different pin classes for determining pin feasibility */
+/*
+ * @brief Resets nets used at different pin classes for determining pin
+ *        feasibility.
+ */
 static void reset_lookahead_pins_used(t_pb* cur_pb) {
     const t_pb_type* pb_type = cur_pb->pb_graph_node->pb_type;
     if (cur_pb->pb_stats == nullptr) {
@@ -674,7 +674,7 @@ static int net_sinks_reachable_in_cluster(const t_pb_graph_pin* driver_pb_gpin,
 }
 
 /**
- * Returns the pb_graph_pin of the atom pin defined by the driver_pin_id in the driver_pb
+ * @brief Returns the pb_graph_pin of the atom pin defined by the driver_pin_id in the driver_pb
  */
 static t_pb_graph_pin* get_driver_pb_graph_pin(const t_pb* driver_pb, const AtomPinId driver_pin_id) {
     const AtomContext& atom_ctx = g_vpr_ctx.atom();
@@ -701,12 +701,12 @@ static t_pb_graph_pin* get_driver_pb_graph_pin(const t_pb* driver_pb, const Atom
 }
 
 /**
- * Given a pin and its assigned net, mark all pin classes that are affected.
- * Check if connecting this pin to it's driver pin or to all sink pins will
- * require leaving a pb_block starting from the parent pb_block of the
- * primitive till the root block (depth = 0). If leaving a pb_block is
- * required add this net to the pin class (to increment the number of used
- * pins from this class) that should be used to leave the pb_block.
+ * @brief Given a pin and its assigned net, mark all pin classes that are affected.
+ *        Check if connecting this pin to it's driver pin or to all sink pins will
+ *        require leaving a pb_block starting from the parent pb_block of the
+ *        primitive till the root block (depth = 0). If leaving a pb_block is
+ *        required add this net to the pin class (to increment the number of used
+ *        pins from this class) that should be used to leave the pb_block.
  */
 static void compute_and_mark_lookahead_pins_used_for_pin(const t_pb_graph_pin* pb_graph_pin,
                                                          const t_pb* primitive_pb,
@@ -834,7 +834,9 @@ static void compute_and_mark_lookahead_pins_used_for_pin(const t_pb_graph_pin* p
 }
 
 
-/* Determine if pins of speculatively packed pb are legal */
+/*
+ * @brief Determine if pins of speculatively packed pb are legal
+ */
 static void compute_and_mark_lookahead_pins_used(const AtomBlockId blk_id,
                                                  const vtr::vector_map<AtomBlockId, LegalizationClusterId>& atom_cluster) {
     const AtomContext& atom_ctx = g_vpr_ctx.atom();
@@ -851,7 +853,9 @@ static void compute_and_mark_lookahead_pins_used(const AtomBlockId blk_id,
     }
 }
 
-/* Determine if speculatively packed cur_pb is pin feasible
+/*
+ * @brief Determine if speculatively packed cur_pb is pin feasible
+ *
  * Runtime is actually not that bad for this.  It's worst case O(k^2) where k is the
  * number of pb_graph pins.  Can use hash tables or make incremental if becomes an issue.
  */
@@ -881,7 +885,10 @@ static void try_update_lookahead_pins_used(t_pb* cur_pb,
     }
 }
 
-/* Check if the number of available inputs/outputs for a pin class is sufficient for speculatively packed blocks */
+/*
+ * @brief Check if the number of available inputs/outputs for a pin class is
+ *        sufficient for speculatively packed blocks.
+ */
 static bool check_lookahead_pins_used(t_pb* cur_pb, t_ext_pin_util max_external_pin_util) {
     const t_pb_type* pb_type = cur_pb->pb_graph_node->pb_type;
 
@@ -943,11 +950,11 @@ static bool check_lookahead_pins_used(t_pb* cur_pb, t_ext_pin_util max_external_
 }
 
 /**
- * This function takes a chain molecule, and the pb_graph_node that is chosen
- * for packing the molecule's root block. Using the given root_primitive, this
- * function will identify which chain id this molecule is being mapped to and
- * will update the chain id value inside the chain info data structure of this
- * molecule
+ * @brief This function takes a chain molecule, and the pb_graph_node that is
+ *        chosen for packing the molecule's root block. Using the given
+ *        root_primitive, this function will identify which chain id this
+ *        molecule is being mapped to and will update the chain id value inside
+ *        the chain info data structure of this molecule.
  */
 static void update_molecule_chain_info(t_pack_molecule* chain_molecule, const t_pb_graph_node* root_primitive) {
     VTR_ASSERT(chain_molecule->chain_info->chain_id == -1 && chain_molecule->chain_info->is_long_chain);
@@ -969,7 +976,8 @@ static void update_molecule_chain_info(t_pack_molecule* chain_molecule, const t_
     VTR_ASSERT(false);
 }
 
-/* Revert trial atom block iblock and free up memory space accordingly
+/*
+ * @brief Revert trial atom block iblock and free up memory space accordingly.
  */
 static void revert_place_atom_block(const AtomBlockId blk_id,
                                     t_lb_router_data* router_data,
@@ -1021,7 +1029,9 @@ static void revert_place_atom_block(const AtomBlockId blk_id,
     mutable_atom_ctx.lookup.set_atom_pb(blk_id, nullptr);
 }
 
-/* Speculation successful, commit input/output pins used */
+/*
+ * @brief Speculation successful, commit input/output pins used.
+ */
 static void commit_lookahead_pins_used(t_pb* cur_pb) {
     const t_pb_type* pb_type = cur_pb->pb_graph_node->pb_type;
 
@@ -1055,7 +1065,7 @@ static void commit_lookahead_pins_used(t_pb* cur_pb) {
 }
 
 /**
- * Cleans up a pb after unsuccessful molecule packing
+ * @brief Cleans up a pb after unsuccessful molecule packing
  *
  * Recursively frees pbs from a t_pb tree. The given root pb itself is not
  * deleted.
@@ -1135,7 +1145,7 @@ e_block_pack_status ClusterLegalizer::try_pack_molecule(t_pack_molecule* molecul
     VTR_ASSERT_DEBUG(cluster.pb != nullptr);
     VTR_ASSERT_DEBUG(cluster.type != nullptr);
 
-    // TODO: Remove these global accesses.
+    // TODO: Remove these global accesses to the contexts.
     // AtomContext used for:
     //  - printing verbose statements
     //  - Looking up the primitive pb
@@ -1349,7 +1359,7 @@ e_block_pack_status ClusterLegalizer::try_pack_molecule(t_pack_molecule* molecul
                 cluster.noc_grp_id = new_cluster_noc_grp_id;
 
                 // Insert the molecule into the cluster for bookkeeping.
-                cluster.molecules.insert(molecule);
+                cluster.molecules.push_back(molecule);
 
                 for (int i = 0; i < molecule_size; i++) {
                     AtomBlockId atom_blk_id = molecule->atom_block_ids[i];
@@ -1653,10 +1663,13 @@ ClusterLegalizer::ClusterLegalizer(const AtomNetlist& atom_netlist,
     feasible_block_array_size_ = feasible_block_array_size;
     log_verbosity_ = log_verbosity;
     // Get the target external pin utilization
-    // NOTE: This is really silly, but this can potentially fail. If it does
-    //       it is important that everything is allocated. If not, when it fails
-    //       it will call the reset method when only parts of the class are
-    //       allocated which may cause havoc...
+    // NOTE: This has to be initialized last due to the fact that VPR_FATA_ERROR
+    //       may be called within the constructor of t_ext_pin_util_targets. If
+    //       this occurs, an excpetion is thrown which will drain the stack. If
+    //       the cluster legalizer object is stored on the stack, this can call
+    //       the destructor prematurely (before certain structures are allocated).
+    //       Therefore, this is created at the end, when the class is in a state
+    //       where it can be destroyed.
     target_external_pin_util_ = t_ext_pin_util_targets(target_external_pin_util_str);
 }
 

vpr/src/pack/cluster_legalizer.h

@@ -1,7 +1,19 @@
+/**
+ * @file
+ * @author  Alex Singer
+ * @date    September 2024
+ * @brief   The declaration of the Cluster Legalizer class.
+ *
+ * This file declares a class called the ClusterLegalizer which encapsulates all
+ * logic for creating legal clusters from prepacked molecules. This class is
+ * designed to be self-contained to the point that it is able to be called
+ * externally to the Packer in VPR.
+ */
+
 #pragma once
 
-#include <set>
 #include <unordered_map>
+#include <vector>
 #include "atom_netlist_fwd.h"
 #include "noc_data_types.h"
 #include "partition_region.h"
@@ -49,12 +61,15 @@ struct LegalizationCluster {
     /// @brief A list of the molecules in the cluster. By design, a cluster will
     ///        only contain molecules which have been previously legalized into
     ///        the cluster using a legalization strategy.
-    std::set<t_pack_molecule*> molecules;
+    std::vector<t_pack_molecule*> molecules;
 
     /// @brief The logical block of this cluster.
     /// TODO: We should be more careful with how this is allocated. Instead of
     ///       pointers, we really should use IDs and store them in a standard
-    ///       container.
+    ///       container. Currently this is being allocated with the new keyword
+    ///       and freed when the cluster is destroyed; however this is used
+    ///       externally to the class and it can be dangerous to pass around
+    ///       a pointer to this object.
     t_pb* pb;
 
     /// @brief The logical block type this cluster represents.
@@ -79,7 +94,7 @@ struct LegalizationCluster {
 };
 
 /*
- * @brief A manager class which manages the legalization of cluster. As clusters
+ * @brief A manager class which manages the legalization of clusters. As clusters
  *        are created, this class will legalize for each molecule added. It also
  *        provides methods which are helpful for clustering.
  *
@@ -99,13 +114,15 @@ struct LegalizationCluster {
  * look something like this. Note, this example is simplified and the result
  * of the packings should be checked and handled.
  *
- * ClusterLegalizer legalizer(...);
+ * ClusterLegalizer legalizer(...,
+ *                            ClusterLegalizationStrategy::SKIP_INTRA_LB_ROUTE,
+ *                            ...);
  *
  * std::tie(status, new_cluster_id) = legalizer.start_new_cluster(seed_mol,
  *                                                                cluster_type,
  *                                                                mode);
  * for mol in molecules_to_add:
- *      // Cheaper additions, but may pack a molecule that wouldnt route.
+ *      // Cheaper additions, but may pack a molecule that wouldn't route.
  *      status = legalizer.add_mol_to_cluster(mol, new_cluster_id);
  *      if (status != e_block_pack_status::BLK_PASSED)
  *          break;
@@ -114,16 +131,20 @@ struct LegalizationCluster {
  * if (!legalizer.check_cluster_legality(new_cluster_id))
  *      // Destroy the illegal cluster.
  *      legalizer.destroy_cluster(new_cluster_id);
+ *      // Clean-up the internal bookeeping of the class (required after
+ *      // destroying a cluster).
  *      legalizer.compress();
  *      // Handle how to try again (maybe use FULL strategy).
  *
  * 2) FULL Legalization Strategy Example:
  * This strategy will fully route the internal connections of the clusters for
  * each molecule added. This is much more expensive to run; however, will ensure
  * that the cluster is fully legalized while it is being created. An example
- * of how to sue this strategy would look something like this:
+ * of how to use this strategy would look something like this:
  *
- * Clusterlegalizer legalizer(...);
+ * Clusterlegalizer legalizer(...,
+ *                            ClusterLegalizationStrategy::FULL,
+ *                            ...);
  *
  * std::tie(pack_result, new_cluster_id) = legalizer.start_new_cluster(seed_mol,
  *                                                                     cluster_type,
@@ -174,6 +195,46 @@ class ClusterLegalizer {
      * @brief Initialize the ClusterLegalizer class.
      *
      * Allocates internal state.
+     *
+     *  @param atom_netlist     The complete atom netlist. Used to allocate
+     *                          internal structures to the correct size.
+     *  @param prepacker        The prepacker object used to prepack the atoms
+     *                          into molecules. A reference to this object is
+     *                          stored internally to be used to lookup the
+     *                          molecules of atoms.
+     *  @param logical_block_types Used to allocate internal objects. Used to
+     *                             get the max number of primitives in any block
+     *                             type.
+     *  @param lb_type_rr_graphs The routing resource graph internal to the
+     *                           different cluster types. A reference is stored
+     *                           in the class to be used to allocate and load
+     *                           the router data.
+     *  @param num_models       The total number of models in the architecture.
+     *                          This is the sum of the number of the user and
+     *                          library models. Used internally to allocate data
+     *                          structures.
+     *  @param target_external_pin_util_str A string used to initialize the
+     *                                      target external pin utilization of
+     *                                      each cluster type.
+     *  @param high_fanout_thresholds An object that stores the thresholds for
+     *                                a net to be considered high fanout for
+     *                                different block types.
+     *  @param cluster_legalization_strategy The legalization strategy to be
+     *                                       used when creating clusters and
+     *                                       adding molecules to clusters.
+     *                                       Controls the checks that are performed.
+     *  @param enable_pin_feasibility_filter A flag to turn on/off the check for
+     *                                       pin usage feasibility.
+     *  @param feasible_block_array_size The largest number of feasible blocks
+     *                                   that can be stored in a cluster. Used
+     *                                   to allocate an internal structure.
+     *  @param log_verbosity     Controls how verbose the log messages will
+     *                           be within this class.
+     *
+     *  TODO: A lot of these arguments are only used to allocate C-style arrays
+     *        since the original author was avoiding dynamic allocations. It may
+     *        be more space efficient (and cleaner) to make these dynamic arrays
+     *        and not pass these arguments in.
      */
     ClusterLegalizer(const AtomNetlist& atom_netlist,
                      const Prepacker& prepacker,
@@ -211,7 +272,12 @@ class ClusterLegalizer {
     /*
      * @brief Add an unclustered molecule to the given legalization cluster.
      *
-     * If the addition was unsuccessful, the molecule will remain unclustered.
+     * The ClusterLegalizationStrategy (set either in the constructor or by the
+     * set_cluster_legalization_strategy method) decides what checks are
+     * performed when adding a molecule to the cluster.
+     *
+     * If the addition was unsuccessful (i.e. a check fails), the molecule will
+     * remain unclustered.
      *
      *  @param molecule         The molecule to add to the cluster.
      *  @param cluster_id       The ID of the cluster to add the molecule to.
@@ -234,8 +300,8 @@ class ClusterLegalizer {
     void destroy_cluster(LegalizationClusterId cluster_id);
 
     /*
-     * @brief Compress the internal storage of clusters. Should be called after
-     *        a cluster is destroyed.
+     * @brief Compress the internal storage of clusters. Should be called
+     *        eventually after one or more clusters are destroyed.
      *
      * Similar to the Netlist compress method. Will invalidate all Legalization
      * Cluster IDs.
@@ -246,7 +312,7 @@ class ClusterLegalizer {
     void compress();
 
     /*
-     * @brief A list of all cluster IDs in the legalizer.
+     * @brief A range of all cluster IDs in the legalizer.
      *
      * If the legalizer has been compressed (or no clusters have been destroyed)
      * then all cluster IDs in this list will be valid and represent a non-empty
@@ -288,14 +354,15 @@ class ClusterLegalizer {
     void clean_cluster(LegalizationClusterId cluster_id);
 
     /*
-     * @brief Verify that all atoms have been clustered into a cluster.
+     * @brief Verify that all atoms have been clustered into some cluster.
      *
      * This will not verify if all the clusters are fully legal.
      */
     void verify();
 
     /*
-     * @brief Finalize the clustering.
+     * @brief Finalize the clustering. Required for generating a Clustered
+     *        Netlist.
      *
      * Before generating a Clustered Netlist, each cluster needs to allocate and
      * load a pb_route. This method will generate a pb_route for each cluster
@@ -339,6 +406,14 @@ class ClusterLegalizer {
     }
 
     /// @brief Gets the cluster placement stats of the given cluster.
+    ///
+    /// The cluster placement stats are statistics used to monitor which atoms
+    /// have been physically clustered into the pb (more specifically what site
+    /// they will go). This can be used externally to the legalizer to detect
+    /// if an atom could physically go into a cluster (exists_free_primitive_for_atom_block).
+    ///
+    /// TODO: Releasing the whole stats can be dangerous. Ideally there should
+    ///       just be a method to see if an atom could physically go in a cluster.
     inline t_cluster_placement_stats* get_cluster_placement_stats(LegalizationClusterId cluster_id) const {
         VTR_ASSERT_SAFE(cluster_id.is_valid() && (size_t)cluster_id < legalization_clusters_.size());
         return &(cluster_placement_stats_[get_cluster_type(cluster_id)->index]);
@@ -358,6 +433,9 @@ class ClusterLegalizer {
     }
 
     /// @bried Gets the max size a cluster could physically be.
+    ///
+    /// This is the maximum number of primitives any cluster could ever have
+    /// in the architecture.
     inline size_t get_max_cluster_size() const {
         return max_cluster_size_;
     }
@@ -411,7 +489,10 @@ class ClusterLegalizer {
 
     /// @brief Stores the NoC group ID of each atom block. Atom blocks that
     ///        belong to different NoC groups can't be clustered with each other
-    ///        into the same clustered block.
+    ///        into the same clustered block. Under some optimization settings
+    ///        to improve placement locality / NoC usage. Atoms with different
+    ///        NoC group IDs belong to logic that is disjoint except through
+    ///        NoC traffic.
     vtr::vector<AtomBlockId, NocGroupId> atom_noc_grp_id_;
 
     /// @brief Stats keeper for placement information during packing/clustering.
@@ -422,17 +503,17 @@ class ClusterLegalizer {
     ///        should stored per cluster.
     t_cluster_placement_stats* cluster_placement_stats_ = nullptr;
 
-    /// @brief The utilization of external input/output pins during packing
-    ///        (between 0 and 1).
+    /// @brief The maximum fractional utilization of cluster external
+    ///        input/output pins during packing (between 0 and 1).
     t_ext_pin_util_targets target_external_pin_util_;
 
     /// @brief The max size of any molecule. This is used to allocate a dynamic
     ///        array within the legalizer, and in its current form this is a bit
     ///        expensive to calculate from the prepacker.
     size_t max_molecule_size_;
 
-    /// @brief The max size a cluster could physically be. This is used to
-    ///        allocate dynamic arrays.
+    /// @brief The max number of primitives a cluster could physically have.
+    ///        This is used to allocate dynamic arrays.
     size_t max_cluster_size_;
 
     /// @brief A vector of routing resource nodes within each logical block type

vpr/src/pack/cluster_util.cpp

@@ -7,6 +7,15 @@
 class AtomNetId;
 class ClusterLegalizer;
 
+/// @brief Output the clustering, given by the ClusterLegalizer or a clustered
+///        netlist, to a clustered netlist file.
+///
+/// The clustering can be output from the following sources:
+///     1) From the clustering
+///     2) From another clustered netlist
+/// If from_legalizer is true, the ClusterLegalizer will be used to generate the
+/// clustered netlist. If from_legalizer is false, the clustered netlist currently
+/// in the global scope will be used.
 void output_clustering(ClusterLegalizer* cluster_legalizer_ptr,
                        bool global_clocks,
                        const std::unordered_set<AtomNetId>& is_clock,

vpr/src/pack/cluster_util.h

@@ -200,6 +200,10 @@ bool try_pack(t_packer_opts* packer_opts,
                 t_ext_pin_util pin_util(1.0, 1.0);
                 // TODO: This line assumes the logic block name is "clb" which
                 //       may not be the case. This may need to be investigated.
+                //       Probably we should do this update of ext_pin_util for
+                //       all types that were overused. Or if that is hard, just
+                //       do it for all block types. Doing it only for a clb
+                //       string is dangerous -VB.
                 cluster_legalizer.get_target_external_pin_util().set_block_pin_util("clb", pin_util);
             }
 

vpr/src/pack/output_clustering.h

@@ -193,6 +193,8 @@ int get_max_nets_in_pb_type(const t_pb_type* pb_type);
 bool primitive_type_feasible(AtomBlockId blk_id, const t_pb_type* cur_pb_type);
 t_pb_graph_pin* get_pb_graph_node_pin_from_model_port_pin(const t_model_ports* model_port, const int model_pin, const t_pb_graph_node* pb_graph_node);
 const t_pb_graph_pin* find_pb_graph_pin(const AtomNetlist& netlist, const AtomLookup& netlist_lookup, const AtomPinId pin_id);
+/// @brief Gets the pb_graph_node pin at the given pin index for the given
+///        pb_graph_node.
 t_pb_graph_pin* get_pb_graph_node_pin_from_pb_graph_node(t_pb_graph_node* pb_graph_node, int ipin);
 t_pb_graph_pin* get_pb_graph_node_pin_from_block_pin(ClusterBlockId iblock, int ipin);
 vtr::vector<ClusterBlockId, t_pb**> alloc_and_load_pin_id_to_pb_mapping();