[APPack] Updated Documentation and Comments

Author: AlexandreSinger

doc/src/vpr/command_line_usage.rst

@@ -1384,14 +1384,17 @@ Analytical Placement is generally split into three stages:
 
     **Default:** ``auto``
 
-.. option:: --appack_max_dist_th { auto | <regex>:<float>,<float> }
+.. option:: --appack_unrelated_clustering_args { auto | <regex>:<float>,<float> }
 
-   Sets parameters used for unrelated clustering for the logical block types
-   used by APPack. APPack uses the primitive-level placement produced by the
+   Sets parameters used for unrelated clustering (the max search distance and max attempts)
+   used by APPack.
+   APPack uses the primitive-level placement produced by the
    global placer to cluster primitives together. APPack uses this information
    to help increase the density of clusters (if needed) by searching for
    unrelated molecules to pack together. It does this by searching out from
    the centroid of the cluster being created until it finds a valid molecule.
+   If a valid molecule is found, but it fails, the packer may do another attempt
+   (up to a maximum number of attempts).
    This argument allows the user to select the maximum distance the code will
    search and how many attempts it will try to search for each cluster.
 

libs/libarchfpga/src/arch_util.cpp

@@ -1030,7 +1030,7 @@ bool pb_type_contains_blif_model(const t_pb_type* pb_type, const std::string& bl
 }
 
 bool pb_type_contains_memory_pbs(const t_pb_type* pb_type) {
-    // TODO: This should eb a graph traversal instead of a recursive function.
+    // TODO: This should be a graph traversal instead of a recursive function.
 
     if (pb_type == nullptr)
         return false;

vpr/src/base/read_options.cpp

@@ -2012,12 +2012,15 @@ argparse::ArgumentParser create_arg_parser(const std::string& prog_name, t_optio
 
     ap_grp.add_argument(args.appack_unrelated_clustering_args, "--appack_unrelated_clustering_args")
         .help(
-            "Sets parameters used for unrelated clustering for the logical block types "
-            "used by APPack. APPack uses the primitive-level placement produced by the "
+            "Sets parameters used for unrelated clustering (the max search distance and max attempts) "
+            "used by APPack. "
+            "APPack uses the primitive-level placement produced by the "
             "global placer to cluster primitives together. APPack uses this information "
             "to help increase the density of clusters (if needed) by searching for "
             "unrelated molecules to pack together. It does this by searching out from "
             "the centroid of the cluster being created until it finds a valid molecule. "
+            "If a valid molecule is found, but it fails, the packer may do another attempt "
+            "(up to a maximum number of attempts). "
             "This argument allows the user to select the maximum distance the code will "
             "search and how many attempts it will try to search for each cluster."
             "\n"

vpr/src/pack/appack_unrelated_clustering_manager.cpp

@@ -25,12 +25,14 @@ void APPackUnrelatedClusteringManager::init(
     max_unrelated_clustering_attempts_.resize(logical_block_types.size(),
                                               default_max_unrelated_clustering_attempts_);
 
-    // For memories, we do not perform unrelated clustering.
+    // For memories (such as BRAMs and MLABs), we do not perform unrelated clustering.
     for (const t_logical_block_type& lb_ty : logical_block_types) {
         // Skip the empty logical block type. This should not have any blocks.
         if (lb_ty.is_empty())
             continue;
 
+        // If the logical block type contains a pb_type which is a memory class,
+        // it is assumed to be a BRAM or an MLAB.
         bool has_memory = pb_type_contains_memory_pbs(lb_ty.pb_type);
         if (!has_memory)
             continue;

vpr/src/pack/appack_unrelated_clustering_manager.h

@@ -16,10 +16,10 @@
  * @brief Manager class for unrelated clustering in APPack.
  *
  * After searching for candidates by connectivity and timing, the user may
- * turn on unrelated clustering, which will allow molecules which are
- * unrelated to the cluster being created to be attempted to be packed in.
- * APPack uses flat placement information to decide which unrelated
- * molecules to try.
+ * turn on unrelated clustering, which attempt to pack into the cluster molecules
+ * which are not attracted to the molecules within the current cluster (according
+ * to the standard packing heuristics). APPack uses flat placement information
+ * to decide which unrelated molecules to try.
  *
  * APPack will search for unrelated molecules in the tile which contains
  * the flat location of the cluster.  It will then look farther out, tile