[FlatPlacement] Updated Flat Placement Writing Code

Updated the code for writing a post-placement flat placement file.

Updated the documentation to make this option easier to find.

Author: AlexandreSinger

doc/src/vpr/command_line_usage.rst

@@ -408,6 +408,18 @@ Use the options below to override this default naming behaviour.
 
     Prefix for output files
 
+.. option:: --write_flat_place <file>
+
+    Writes the post-placement locations of each atom into a flat placement file.
+
+    For each atom in the netlist, the following information is stored into the
+    flat placement file:
+
+    * The x, y, and sub_tile location of the cluster that contains this atom.
+    * The flat site index of this atom in its cluster. The flat site index is a
+      linearized ID of primitive locations in a cluster. This may be used as a
+      hint to reconstruct clusters.
+
 .. _netlist_options:
 
 Netlist Options

libs/libvtrutil/src/vtr_vector_map.h

@@ -1,5 +1,7 @@
 #ifndef VTR_VECTOR_MAP
 #define VTR_VECTOR_MAP
+#include <cstddef>
+#include <utility>
 #include <vector>
 
 #include "vtr_assert.h"

vpr/src/base/load_flat_place.cpp

@@ -1,48 +1,80 @@
-#include "globals.h"
-#include "load_flat_place.h"
-#include "clustered_netlist_utils.h"
+/**
+ * @file
+ * @author  Alex Singer
+ * @date    January 2025
+ * @brief   Implementation of utility functions for reading and writing flat
+ *          (primitive-level) placements.
+ */
 
+#include "load_flat_place.h"
 
-/* @brief Prints flat placement file entries for the atoms in one placed cluster. */
-static void print_flat_cluster(FILE* fp, ClusterBlockId iblk,
-                               std::vector<AtomBlockId>& atoms);
+#include <unordered_set>
+#include "clustered_netlist.h"
+#include "globals.h"
+#include "vpr_context.h"
+#include "vpr_types.h"
 
-static void print_flat_cluster(FILE* fp, ClusterBlockId iblk,
-                               std::vector<AtomBlockId>& atoms) {
-    const auto& atom_ctx = g_vpr_ctx.atom();
-    const auto& block_locs = g_vpr_ctx.placement().block_locs();
+/**
+ * @brief Prints flat placement file entries for the atoms in one placed
+ *        cluster.
+ *
+ *  @param fp
+ *              File pointer to the file the cluster is printed to.
+ *  @param blk_id
+ *              The ID of the cluster block to print.
+ *  @param block_locs
+ *              The locations of all cluster blocks.
+ *  @param atoms_lookup
+ *              A lookup between all clusters and the atom blocks that they
+ *              contain.
+ */
+static void print_flat_cluster(FILE* fp,
+                               ClusterBlockId blk_id,
+                               const vtr::vector_map<ClusterBlockId, t_block_loc> &block_locs,
+                               const vtr::vector<ClusterBlockId, std::unordered_set<AtomBlockId>>& atoms_lookup) {
+    // Atom context used to get the atom_pb for each atom in the cluster.
+    // NOTE: This is only used for getting the flat site index.
+    const AtomContext& atom_ctx = g_vpr_ctx.atom();
 
-    t_pl_loc loc = block_locs[iblk].loc;
-    size_t bnum = size_t(iblk);
+    // Get the location of this cluster.
+    const t_pl_loc& blk_loc = block_locs[blk_id].loc;
 
-    for (AtomBlockId atom : atoms) {
+    // Print a line for each atom.
+    for (AtomBlockId atom : atoms_lookup[blk_id]) {
+        // Get the atom pb graph node.
         t_pb_graph_node* atom_pbgn = atom_ctx.lookup.atom_pb(atom)->pb_graph_node;
-        fprintf(fp, "%s  %d %d %d %d #%zu %s\n", atom_ctx.nlist.block_name(atom).c_str(),
-                                                loc.x, loc.y, loc.sub_tile,
-                                                atom_pbgn->flat_site_index,
-                                                bnum,
-                                                atom_pbgn->pb_type->name);
+
+        // Print the flat placement information for this atom.
+        fprintf(fp, "%s  %d %d %d %d #%zu %s\n",
+                atom_ctx.nlist.block_name(atom).c_str(),
+                blk_loc.x, blk_loc.y, blk_loc.sub_tile,
+                atom_pbgn->flat_site_index,
+                static_cast<size_t>(blk_id),
+                atom_pbgn->pb_type->name);
     }
 }
 
-/* prints a flat placement file */
-void print_flat_placement(const char* flat_place_file) {
-    const auto& block_locs = g_vpr_ctx.placement().block_locs();
-    
-    FILE* fp;
-
-    ClusterAtomsLookup atoms_lookup;
-    auto& cluster_ctx = g_vpr_ctx.clustering();
-
-    if (!block_locs.empty()) {
-        fp = fopen(flat_place_file, "w");
-        for (ClusterBlockId iblk : cluster_ctx.clb_nlist.blocks()) {
-            auto atoms = atoms_lookup.atoms_in_cluster(iblk);
-            print_flat_cluster(fp, iblk, atoms);
-        }
-        fclose(fp);
+void write_flat_placement(const char* flat_place_file_path,
+                          const ClusteredNetlist& cluster_netlist,
+                          const vtr::vector_map<ClusterBlockId, t_block_loc> &block_locs,
+                          const vtr::vector<ClusterBlockId, std::unordered_set<AtomBlockId>>& atoms_lookup) {
+    // Writes the flat placement to the given flat_place_file_path.
+
+    // Only print a flat placement if the clusters have been placed.
+    if (block_locs.empty())
+        return;
+
+    // Create a file in write mode for the flat placement.
+    FILE* fp = fopen(flat_place_file_path, "w");
+
+    // For each cluster, write out the atoms in the cluster at this cluster's
+    // location.
+    for (ClusterBlockId iblk : cluster_netlist.blocks()) {
+        print_flat_cluster(fp, iblk, block_locs, atoms_lookup);
     }
 
+    // Close the file.
+    fclose(fp);
 }
 
 /* ingests and legalizes a flat placement file  */
@@ -55,3 +87,4 @@ bool load_flat_placement(t_vpr_setup& vpr_setup, const t_arch& arch) {
 
     return false;
 }
+

vpr/src/base/load_flat_place.h

@@ -1,16 +1,47 @@
-#ifndef LOAD_FLAT_PLACE_H
-#define LOAD_FLAT_PLACE_H
+/**
+ * @file
+ * @author  Alex Singer
+ * @date    January 2025
+ * @brief   Utility functions for reading and writing flat placements.
+ *
+ * Flat placements are atom-level placements. These utilities can read and write
+ * flat placement information to different parts of the VPR flow.
+ */
+
+#pragma once
+
+#include <unordered_set>
+#include "vtr_vector_map.h"
+#include "vtr_vector.h"
 
-#include "vpr_types.h"
+// Forward declarations
+class AtomBlockId;
+class ClusterBlockId;
+class ClusteredNetlist;
+struct t_arch;
+struct t_block_loc;
+struct t_vpr_setup;
 
 /**
- * @brief A function that prints a flat placement file
+ * @brief A function that writes a flat placement file after clustering and
+ *        placement.
+ *
+ *  @param flat_place_file_path
+ *                  Path to the file to write the flat placement to.
+ *  @param cluster_netlist
+ *                  The clustered netlist to write to the file path.
+ *  @param block_locs
+ *                  The locations of all of the blocks in the cluster_netlist.
+ *  @param atoms_lookup
+ *                  A lookup between each cluster and the atoms within it.
  */
-void print_flat_placement(const char* flat_place_file);
+void write_flat_placement(const char* flat_place_file_path,
+                          const ClusteredNetlist& cluster_netlist,
+                          const vtr::vector_map<ClusterBlockId, t_block_loc> &block_locs,
+                          const vtr::vector<ClusterBlockId, std::unordered_set<AtomBlockId>>& atoms_lookup);
 
 /**
  * @brief A function that loads and legalizes a flat placement file
  */
 bool load_flat_placement(t_vpr_setup& vpr_setup, const t_arch& arch);
 
-#endif

vpr/src/base/vpr_api.cpp

@@ -769,7 +769,10 @@ bool vpr_load_flat_placement(t_vpr_setup& vpr_setup, const t_arch& arch) {
 
     // echo flat placement (orphan clusters will have -1 for X, Y, subtile coordinates)
     if (getEchoEnabled() && isEchoFileEnabled(E_ECHO_FLAT_PLACE)) {
-        print_flat_placement(getEchoFileName(E_ECHO_FLAT_PLACE));
+        write_flat_placement(getEchoFileName(E_ECHO_FLAT_PLACE),
+                             g_vpr_ctx.clustering().clb_nlist,
+                             g_vpr_ctx.placement().block_locs(),
+                             g_vpr_ctx.clustering().atoms_lookup);
     }
 
     // reset the device grid
@@ -813,7 +816,10 @@ bool vpr_place_flow(const Netlist<>& net_list, t_vpr_setup& vpr_setup, const t_a
     // A flat placement file includes cluster and intra-cluster placement coordinates for
     // each primitive and can be used to reconstruct a clustering and placement solution.
     if (!filename_opts.write_flat_place_file.empty()) {
-        print_flat_placement(vpr_setup.FileNameOpts.write_flat_place_file.c_str());
+        write_flat_placement(filename_opts.write_flat_place_file.c_str(),
+                             g_vpr_ctx.clustering().clb_nlist,
+                             g_vpr_ctx.placement().block_locs(),
+                             g_vpr_ctx.clustering().atoms_lookup);
     }
 
     return true;