Added documentation according to review comments.

Author: Bill-hbrhbr

vpr/src/place/place_util.cpp

@@ -1,38 +1,54 @@
 /**
  * @file place_util.cpp
- * @brief Definitions of structure routines declared in place_util.h.
+ * @brief Definitions of structure methods and routines declared in place_util.h.
+ *        These are mainly utility functions used by the placer.
  */
 
 #include "place_util.h"
 #include "globals.h"
 #include "draw_global.h"
 
+/* File-scope routines */
 static vtr::Matrix<t_grid_blocks> init_grid_blocks();
 
+/**
+ * @brief Initialize the placer's block-grid dual direction mapping.
+ *
+ * Forward direction - block to grid: place_ctx.block_locs.
+ * Reverse direction - grid to block: place_ctx.grid_blocks.
+ *
+ * Initialize both of them to empty states.
+ */
 void init_placement_context() {
     auto& place_ctx = g_vpr_ctx.mutable_placement();
     auto& cluster_ctx = g_vpr_ctx.clustering();
 
+    /* Intialize the lookup of CLB block positions */
     place_ctx.block_locs.clear();
     place_ctx.block_locs.resize(cluster_ctx.clb_nlist.blocks().size());
 
+    /* Initialize the reverse lookup of CLB block positions */
     place_ctx.grid_blocks = init_grid_blocks();
 }
 
+/**
+ * @brief Initialize `grid_blocks`, the inverse structure of `block_locs`.
+ *
+ * The container at each grid block location should have a length equal to the
+ * subtile capacity of that block. Unused subtile would be marked EMPTY_BLOCK_ID.
+ */
 static vtr::Matrix<t_grid_blocks> init_grid_blocks() {
     auto& device_ctx = g_vpr_ctx.device();
 
+    /* Structure should have the same dimensions as the grid. */
     auto grid_blocks = vtr::Matrix<t_grid_blocks>({device_ctx.grid.width(), device_ctx.grid.height()});
+
     for (size_t x = 0; x < device_ctx.grid.width(); ++x) {
         for (size_t y = 0; y < device_ctx.grid.height(); ++y) {
             auto type = device_ctx.grid[x][y].type;
-
-            int capacity = type->capacity;
-
-            grid_blocks[x][y].blocks.resize(capacity, EMPTY_BLOCK_ID);
+            grid_blocks[x][y].blocks.resize(type->capacity, EMPTY_BLOCK_ID);
         }
     }
-
     return grid_blocks;
 }
 
@@ -54,12 +70,13 @@ void t_placer_costs::update_norm_factors() {
     }
 }
 
-///@brief Constructor: Initialize all annealing state variables.
+///@brief Constructor: Initialize all annealing state variables and macros.
 t_annealing_state::t_annealing_state(const t_annealing_sched& annealing_sched,
                                      float first_t,
                                      float first_rlim,
                                      int first_move_lim,
                                      float first_crit_exponent) {
+    num_temps = 0;
     alpha = annealing_sched.alpha_min;
     t = first_t;
     restart_t = first_t;
@@ -74,8 +91,10 @@ t_annealing_state::t_annealing_state(const t_annealing_sched& annealing_sched,
         move_lim = move_lim_max;
     }
 
+    /* Store this inverse value for speed when updating crit_exponent. */
     INVERSE_DELTA_RLIM = 1 / (first_rlim - FINAL_RLIM);
 
+    /* The range limit cannot exceed the largest grid size. */
     auto& grid = g_vpr_ctx.device().grid;
     UPPER_RLIM = std::max(grid.width() - 1, grid.height() - 1);
 }
@@ -212,7 +231,7 @@ bool t_annealing_state::outer_loop_update(const t_placer_costs& costs,
 }
 
 /**
- * @brief Update the range limited to keep acceptance prob. near 0.44.
+ * @brief Update the range limiter to keep acceptance prob. near 0.44.
  *
  * Use a floating point rlim to allow gradual transitions at low temps.
  * The range is bounded by 1 (FINAL_RLIM) and the grid size (UPPER_RLIM).
@@ -275,4 +294,4 @@ double get_std_dev(int n, double sum_x_squared, double av_x) {
 
     /* Very small variances sometimes round negative. */
     return (std_dev > 0.) ? sqrt(std_dev) : 0.;
-}
+}

vpr/src/place/place_util.h

@@ -1,7 +1,7 @@
 /**
  * @file place_util.h
  * @brief Utility structures representing various states of the
- *        placement. Also contains declarations of related routines.
+ *        placement and utility functions used by the placer.
  */
 
 #pragma once
@@ -65,21 +65,31 @@ class t_placer_costs {
  * loop iteration. It stores various important variables that need to
  * be accessed during the placement inner loop.
  *
+ * Private variables are not given accessor functions. They serve as
+ * macros originally defined in place.cpp as global scope variables.
+ *
  * Public members:
  *   @param t
  *              Temperature for simulated annealing.
- *   @param rlim
- *              Range limit for block swaps.
- *   @param alpha
- *              Temperature decays factor (multiplied each outer loop iteration).
  *   @param restart_t
  *              Temperature used after restart due to minimum success ratio.
+ *              Currently only used and updated by DUSTY_SCHED.
+ *   @param alpha
+ *              Temperature decays factor (multiplied each outer loop iteration).
+ *   @param num_temps
+ *              The count of how many temperature iterations have passed.
+ *
+ *   @param rlim
+ *              Range limit for block swaps.
+ *              Currently only updated by DUSTY_SCHED and AUTO_SCHED.
  *   @param crit_exponent
  *              Used by timing-driven placement to "sharpen" the timing criticality.
- *   @param move_lim_max
- *              Maximum block move limit.
+ *              Depends on rlim. Currently only updated by DUSTY_SCHED and AUTO_SCHED.
  *   @param move_lim
  *              Current block move limit.
+ *              Currently only updated by DUSTY_SCHED.
+ *   @param move_lim_max
+ *              Maximum block move limit.
  *
  * Private members:
  *   @param UPPER_RLIM
@@ -99,14 +109,15 @@ class t_placer_costs {
 class t_annealing_state {
   public:
     float t;
-    float rlim;
-    float alpha;
     float restart_t;
+    float alpha;
+    int num_temps;
+
+    float rlim;
     float crit_exponent;
-    int move_lim_max;
     int move_lim;
+    int move_lim_max;
     float success_rate;
-    int num_temps = 0;
 
   private:
     float UPPER_RLIM;
@@ -131,11 +142,11 @@ class t_annealing_state {
     inline void update_move_lim(float success_target);
 };
 
-///@brief Initialize the placement context.
+///@brief Initialize the placer's block-grid dual direction mapping.
 void init_placement_context();
 
 ///@brief Get the initial limit for inner loop block move attempt limit.
 int get_initial_move_lim(const t_placer_opts& placer_opts, const t_annealing_sched& annealing_sched);
 
 ///@brief Returns the standard deviation of data set x.
-double get_std_dev(int n, double sum_x_squared, double av_x);
+double get_std_dev(int n, double sum_x_squared, double av_x);