[AP][PartialLegalizer] Updated Comments and Verification

Author: AlexandreSinger

vpr/src/analytical_place/flat_placement_bins.h

@@ -14,6 +14,7 @@
 #include "ap_netlist.h"
 #include "vtr_assert.h"
 #include "vtr_geometry.h"
+#include "vtr_log.h"
 #include "vtr_range.h"
 #include "vtr_strong_id.h"
 #include "vtr_vector.h"
@@ -133,6 +134,51 @@ class FlatPlacementBins {
         bin_contained_blocks_[bin_id].clear();
     }
 
+    /**
+     * @brief Verify the internal members of this class are consistent.
+     */
+    inline bool verify() const {
+        // Ensure all bin IDs are valid and consistent.
+        for (FlatPlacementBinId bin_id : bin_ids_) {
+            if (!bin_id.is_valid()) {
+                VTR_LOG("Bin Verify: Invalid bin ID in bins.\n");
+                return false;
+            }
+            if (bin_ids_.count(bin_id) != 1) {
+                VTR_LOG("Bin Verify: Found a bin ID not in the bin IDs array.\n");
+                return false;
+            }
+            if (bin_ids_[bin_id] != bin_id) {
+                VTR_LOG("Bin Verify: Bin ID found which is not consistent.\n");
+                return false;
+            }
+        }
+
+        // Ensure the data members of this class are all the correct size.
+        size_t num_bins = bin_ids_.size();
+        if (bin_contained_blocks_.size() != num_bins) {
+            VTR_LOG("Bin Verify: bin_constained_blocks_ not the correct size.\n");
+            return false;
+        }
+        if (bin_region_.size() != num_bins) {
+            VTR_LOG("Bin Verify: bin_region_ not the correct size.\n");
+            return false;
+        }
+
+        // Make sure that the bin_contained_blocks_ and the block_bin_ are
+        // consistent.
+        for (FlatPlacementBinId bin_id : bin_ids_) {
+            for (APBlockId blk_id : bin_contained_blocks_[bin_id]) {
+                if (block_bin_[blk_id] != bin_id) {
+                    VTR_LOG("Bin Verify: Block is contained within a bin but does not agree.\n");
+                    return false;
+                }
+            }
+        }
+
+        return true;
+    }
+
 private:
     /// @brief A vector of the Flat Placement Bin IDs. If any of them are invalid,
     ///        then that means that the bin has been destroyed.

vpr/src/analytical_place/flat_placement_density_manager.cpp

@@ -193,7 +193,7 @@ vtr::Point<double> FlatPlacementDensityManager::get_block_location_in_bin(
 
 void FlatPlacementDensityManager::export_placement_from_bins(PartialPlacement& p_placement) const {
     // Updates the partial placement with the location of the blocks in the bin
-    // by moiving the blocks to the point with the bin closest to where they
+    // by moving the blocks to the point with the bin closest to where they
     // were originally.
     for (APBlockId blk_id : ap_netlist_.blocks()) {
         // Only the moveable block locations should be exported.
@@ -227,6 +227,11 @@ void FlatPlacementDensityManager::empty_bins() {
 }
 
 bool FlatPlacementDensityManager::verify() const {
+    // Verify the bins for consistency.
+    if (!bins_.verify()) {
+        VTR_LOG("Bins failed to verify.\n");
+        return false;
+    }
     // Make sure that every block has a bin.
     for (APBlockId blk_id : ap_netlist_.blocks()) {
         if (!bins_.block_bin(blk_id).is_valid()) {

vpr/src/analytical_place/flat_placement_density_manager.h

@@ -38,14 +38,16 @@ struct t_physical_tile_type;
  * bins and how overfilled / underfilled they are.
  *
  * Currently, a bin is created for each tile in the FPGA grid (with a unique
- * root tile location). The capacity of each bin is the capacity of the tile
- * it represents (as computed by the flat placement mass calculator). When
- * AP blocks are added / removed from bins, this class will maintain the current
- * utilization of the bin. Since these masses / capacities are repesented by
- * M-dimensional quantities (where M is the number of models in the architecture),
- * the overfill and underfill of each bin is given as an M-dimensional vector.
- * For example, in an architecture of only LUTs and FFs, an overfill of <3, 1>
- * means that a bin has 3 too many LUTs and 1 too many FFs.
+ * root tile location). For example, a CLB taking up a single tile would be a
+ * 1x1 bin, while a DSP block taking up multiple tiles may be a 4x1 bin. The
+ * capacity of each bin is the capacity of the tile it represents (as computed
+ * by the flat placement mass calculator). When AP blocks are added / removed
+ * from bins, this class will maintain the current utilization of the bin. Since
+ * these masses / capacities are repesented by M-dimensional quantities (where
+ * M is the number of models in the architecture), the overfill and underfill of
+ * each bin is given as an M-dimensional vector. For example, in an architecture
+ * of only LUTs and FFs, an overfill of <3, 1> means that a bin has 3 too many
+ * LUTs and 1 too many FFs.
  *
  * This class is able to answer questions about the current density of the flat
  * placement such as which bins are currently overfilled, what bin is at the
@@ -199,6 +201,15 @@ class FlatPlacementDensityManager {
      *
      * This will return the position of the block that is closest to the position
      * in the given flat placement, while still being within the the bin region.
+     *
+     * For example, if the block is located within the bin, its position will
+     * be returned (unmodified). If the block is located to the left of the bin
+     * (y coordinate is within the bounds of the bin), then this will return
+     * the point on the left edge of the bin with the same y coordinate as the
+     * block.
+     *
+     * TODO: It may be a good idea to investigate placing blocks at the input
+     *       or output pin locations of the bin.
      */
     vtr::Point<double> get_block_location_in_bin(APBlockId blk_id,
                                                  const vtr::Rect<double>& bin_region,
@@ -235,6 +246,8 @@ class FlatPlacementDensityManager {
 
     /// @brief Spatial lookup for an (layer, x, y) position to the bin at that
     ///        location.
+    ///
+    /// Access: [0..grid.num_layers-1][0..grid.width-1][0..grid.height-1]
     vtr::NdMatrix<FlatPlacementBinId, 3> bin_spatial_lookup_;
 
     /// @brief The capacity of each bin.