[APPack] Updated Comments

Updated comments and some variables names as per VB review.

Author: AlexandreSinger

vpr/src/base/load_flat_place.cpp

@@ -21,6 +21,26 @@
 #include "vtr_assert.h"
 #include "vtr_log.h"
 #include "vtr_vector_map.h"
+#include "vtr_version.h"
+
+/**
+ * @brief Prints the header for the flat placement file. This includes helpful
+ *        information on how to read the file and when it was generated.
+ *
+ *  @param fp
+ *          File pointer to the file the cluster is printed to.
+ */
+static void print_flat_placement_file_header(FILE* fp) {
+    fprintf(fp, "# Flat Placement File\n");
+    fprintf(fp, "# Auto-generated by VPR %s\n",
+            vtr::VERSION);
+    fprintf(fp, "# Created: %s\n",
+            vtr::BUILD_TIMESTAMP);
+    fprintf(fp, "#\n");
+    fprintf(fp, "# This file prints the following information for each atom in the netlist:\n");
+    fprintf(fp, "# <atom_name> <x> <y> <layer> <atom_sub_tile> <atom_site_idx> #<clb_blk_id> <atom_pb_type>\n");
+    fprintf(fp, "\n");
+}
 
 /**
  * @brief Prints flat placement file entries for the atoms in one placed
@@ -76,6 +96,9 @@ void write_flat_placement(const char* flat_place_file_path,
     // Create a file in write mode for the flat placement.
     FILE* fp = fopen(flat_place_file_path, "w");
 
+    // Add a header to the flat placement file.
+    print_flat_placement_file_header(fp);
+
     // For each cluster, write out the atoms in the cluster at this cluster's
     // location.
     for (ClusterBlockId iblk : cluster_netlist.blocks()) {
@@ -181,7 +204,7 @@ void log_flat_placement_reconstruction_info(
                             const FlatPlacementInfo& flat_placement_info,
                             const vtr::vector_map<ClusterBlockId, t_block_loc>& block_locs,
                             const vtr::vector<ClusterBlockId, std::unordered_set<AtomBlockId>>& atoms_lookup,
-                            const AtomLookup& lookup,
+                            const AtomLookup& cluster_of_atom_lookup,
                             const AtomNetlist& atom_netlist,
                             const ClusteredNetlist& clustered_netlist) {
     // Go through each cluster and see how many clusters have atoms that
@@ -217,6 +240,8 @@ void log_flat_placement_reconstruction_info(
             // If the atom's flat placement more than half a block in any
             // direction from the flat placement centroid, then it does not
             // want to be in this cluster.
+            // FIXME: This should take into account large blocks somehow, just
+            //        being 0.5 tiles away may not be sufficient.
             if (std::abs(centroid_x - flat_placement_info.blk_x_pos[atom_blk_id]) > 0.5f ||
                 std::abs(centroid_y - flat_placement_info.blk_y_pos[atom_blk_id]) > 0.5f ||
                 std::abs(centroid_layer - flat_placement_info.blk_layer[atom_blk_id]) > 0.5f ||
@@ -245,10 +270,12 @@ void log_flat_placement_reconstruction_info(
         int blk_layer = flat_placement_info.blk_layer[atom_blk_id];
 
         // Get the (x, y, layer) position of the cluster that contains this block.
-        ClusterBlockId atom_clb_id = lookup.atom_clb(atom_blk_id);
+        ClusterBlockId atom_clb_id = cluster_of_atom_lookup.atom_clb(atom_blk_id);
         const t_block_loc& clb_loc = block_locs[atom_clb_id];
 
         // Compute the distance between these two positions.
+        // FIXME: This will overreport large blocks. This should really be
+        //        the distance outside of the tile you want to be placed in.
         float dx = blk_x - clb_loc.loc.x;
         float dy = blk_y - clb_loc.loc.y;
         float dlayer = blk_layer - clb_loc.loc.layer;

vpr/src/base/load_flat_place.h

@@ -72,7 +72,7 @@ bool load_flat_placement(t_vpr_setup& vpr_setup, const t_arch& arch);
  *                  The location of each cluster in the netlist.
  *  @param atoms_lookup
  *                  A lookup between each cluster and the atoms it contains.
- *  @param lookup
+ *  @param cluster_of_atom_lookup
  *                  A lookup between each atom and the cluster that contains it.
  *  @param atom_netlist
  *                  The netlist of atoms the flat placement was over.
@@ -84,7 +84,7 @@ void log_flat_placement_reconstruction_info(
                 const FlatPlacementInfo& flat_placement_info,
                 const vtr::vector_map<ClusterBlockId, t_block_loc>& block_locs,
                 const vtr::vector<ClusterBlockId, std::unordered_set<AtomBlockId>>& atoms_lookup,
-                const AtomLookup& lookup,
+                const AtomLookup& cluster_of_atom_lookup,
                 const AtomNetlist& atom_netlist,
                 const ClusteredNetlist& clustered_netlist);
 

vpr/src/base/vpr_context.h

@@ -81,8 +81,8 @@ struct AtomContext : public Context {
     /// @brief Mappings to/from the Atom Netlist to physically described .blif models
     AtomLookup lookup;
 
-    /// @brief Placement information on each atom known before packing and
-    ///        placement.
+    /// @brief Placement information on each atom known (from a file or another
+    ///        algorithm) before packing and the cluster-level placement.
     FlatPlacementInfo flat_placement_info;
 };
 

vpr/src/pack/greedy_candidate_selector.h

@@ -405,7 +405,7 @@ class GreedyCandidateSelector {
 
     /**
      * @brief Add molecules that are "close" to the seed molecule in the flat
-     *        placement tot he list of feasible blocks.
+     *        placement to the list of feasible blocks.
      */
     void add_cluster_molecule_candidates_by_flat_placement(
                                 ClusterGainStats& cluster_gain_stats,
@@ -547,10 +547,15 @@ class GreedyCandidateSelector {
      *        flat placement information for clustering.
      */
     struct FlatTileMoleculeList {
-        // A list of molecules in the undefined sub-tile at this tile.
-        std::vector<t_pack_molecule*> undefined_sub_tile_mols;
-        // A list of molecule in each sub_tile at this tile.
+        // A list of molecule in each sub_tile at this tile. Where each index
+        // in the first dimension is the subtile [0, num_sub_tiles - 1].
         std::vector<std::vector<t_pack_molecule*>> sub_tile_mols;
+
+        // A list of molecules in the undefined sub-tile at this tile. An
+        // undefined sub-tile is the location molecules go when the sub-tile
+        // in the flat placement is unspecified for this atom.
+        // Currently unused, but can be used to support that feature.
+        std::vector<t_pack_molecule*> undefined_sub_tile_mols;
     };
 
     /// @brief Pre-computed information on the flat placement. Lists all of the

vpr/src/place/initial_placement.cpp

@@ -560,6 +560,9 @@ static bool try_centroid_placement(const t_pl_macro& pl_macro,
         find_centroid_loc_from_flat_placement(pl_macro, centroid_loc, flat_placement_info);
         // If a centroid could not be found, or if the tile is not legal
         // fall-back on the centroid of the neighbor blocks of this block.
+        // TODO: This may be more disruptive than needed for flat placement
+        //       reconstruction. Ideally, we would search for a new tile
+        //       location near the flat placement centroid.
         if (!is_loc_on_chip({centroid_loc.x, centroid_loc.y, centroid_loc.layer}) ||
             !is_loc_legal(centroid_loc, pr, block_type)) {
             unplaced_blocks_to_update_their_score = find_centroid_loc(pl_macro, centroid_loc, blk_loc_registry);

vtr_flow/tasks/regression_tests/vtr_reg_strong/strong_flat_placement/read_write/constraints/old_placement.fplace

@@ -1,3 +1,10 @@
+# Flat Placement File
+# Auto-generated by VPR 9.0.0-dev+v8.0.0-12075-g53e90e62b-dirty
+# Created: 2025-01-28T09:59:25
+#
+# This file prints the following information for each atom in the netlist:
+# <atom_name> <x> <y> <layer> <atom_sub_tile> <atom_site_idx> #<clb_blk_id> <atom_pb_type>
+
 n523  6 8 0 0 3 #0 lut
 n522  6 8 0 0 5 #0 lut
 n520  6 8 0 0 2 #0 lut