add some comments

vpr/src/place/place.cpp

@@ -57,7 +57,8 @@ void try_place(const Netlist<>& net_list,
     const auto& device_ctx = g_vpr_ctx.device();
 
     /* Placement delay model is independent of the placement and can be shared across
-     * multiple placers. So, it is created and initialized once. */
+     * multiple placers if we are performing parallel annealing.
+     * So, it is created and initialized once. */
     std::shared_ptr<PlaceDelayModel> place_delay_model;
 
     if (placer_opts.place_algorithm.is_timing_driven()) {
@@ -84,6 +85,11 @@ void try_place(const Netlist<>& net_list,
     VTR_LOG("\n");
 
     auto& place_ctx = g_vpr_ctx.mutable_placement();
+
+    /* Make the global instance of BlkLocRegistry inaccessible through the getter methods of the
+     * placement context. This is done to make sure that the placement stage only accesses its
+     * own local instances of BlkLocRegistry.
+     */
     place_ctx.lock_loc_vars();
     place_ctx.compressed_block_grids = create_compressed_block_grids();
 

vpr/src/place/place_log_util.cpp

@@ -165,6 +165,7 @@ void PlacementLogPrinter::print_placement_swaps_stats() const {
     VTR_LOG("\tSwaps aborted: %*d (%4.1f %%)\n", num_swap_print_digits,
             swap_stats.num_swap_aborted, 100 * abort_rate);
 }
+
 void PlacementLogPrinter::print_initial_placement_stats() const {
     if (quiet_) {
         return;

vpr/src/place/placer.cpp

@@ -79,7 +79,7 @@ Placer::Placer(const Netlist<>& net_list,
 
 #ifdef ENABLE_ANALYTIC_PLACE
     /*
-     * Analytic Placer:
+     * Cluster-level Analytic Placer:
      *  Passes in the initial_placement via vpr_context, and passes its placement back via locations marked on
      *  both the clb_netlist and the gird.
      *  Most of anneal is disabled later by setting initial temperature to 0 and only further optimizes in quench
@@ -284,7 +284,7 @@ void Placer::place() {
 #endif
 
    if (!skip_anneal) {
-       //Table header
+       // Table header
        log_printer_.print_place_status_header();
 
        // Outer loop of the simulated annealing begins
@@ -309,12 +309,6 @@ void Placer::place() {
 
            log_printer_.print_place_status(temperature_timer.elapsed_sec());
 
-           //#ifdef VERBOSE
-           //            if (getEchoEnabled()) {
-           //                print_clb_placement("first_iteration_clb_placement.echo");
-           //            }
-           //#endif
-
            // Outer loop of the simulated annealing ends
        } while (annealer_->outer_loop_update_state());
    } //skip_anneal ends
@@ -372,12 +366,6 @@ void Placer::place() {
        print_place(nullptr, nullptr, filename.c_str(), placer_state_.mutable_block_locs());
     }
 
-    //#ifdef VERBOSE
-    //    if (getEchoEnabled() && isEchoFileEnabled(E_ECHO_END_CLB_PLACEMENT)) {
-    //        print_clb_placement(getEchoFileName(E_ECHO_END_CLB_PLACEMENT));
-    //    }
-    //#endif
-
     // Update physical pin values
     for (const ClusterBlockId block_id : cluster_ctx.clb_nlist.blocks()) {
        placer_state_.mutable_blk_loc_registry().place_sync_external_block_connections(block_id);

vpr/src/place/placer.h

@@ -79,28 +79,67 @@ class Placer {
 
     /// Stores a placement state as a retrievable checkpoint in case the placement quality deteriorates later.
     t_placement_checkpoint placement_checkpoint_;
-
+    /// It holds a setup timing analysis engine. Other placement timing object usually have a reference or pointer to timing_info.
     std::shared_ptr<SetupTimingInfo> timing_info_;
+    /// Post-clustering delay calculator. Its API allows extraction of delay for each timing edge.
     std::shared_ptr<PlacementDelayCalculator> placement_delay_calc_;
+    /// Stores setup slack of the clustered netlist connections.
     std::unique_ptr<PlacerSetupSlacks> placer_setup_slacks_;
+    /// Stores criticalities of the clustered netlist connections.
     std::unique_ptr<PlacerCriticalities> placer_criticalities_;
+    /// Used to invalidate timing edges corresponding to the pins of moved blocks.
     std::unique_ptr<NetPinTimingInvalidator> pin_timing_invalidator_;
+    /// Stores information about the critical path. This is usually updated after that timing info is updated.
     tatum::TimingPathInfo critical_path_;
 
     std::unique_ptr<vtr::ScopedStartFinishTimer> timer_;
 
     IntraLbPbPinLookup pb_gpin_lookup_;
     ClusteredPinAtomPinsLookup netlist_pin_lookup_;
 
+    /// Performs random swaps and implements the simulated annealer optimizer.
     std::unique_ptr<PlacementAnnealer> annealer_;
 
+    /* These variables store timing analysis profiling information
+     * at different stages of the placement to be printed at the end
+     */
     t_timing_analysis_profile_info pre_place_timing_stats_;
     t_timing_analysis_profile_info pre_quench_timing_stats_;
     t_timing_analysis_profile_info post_quench_timing_stats_;
 
+    /* PlacementLogPrinter is made a friend of this class, so it can
+     * access its private member variables without getter methods.
+     * PlacementLogPrinter holds a constant reference to an object of type
+     * Placer to avoid modifying its member variables.
+     */
     friend class PlacementLogPrinter;
 
   private:
+    /**
+     * @brief Constructs and initializes timing-related objects.
+     *
+     * This function performs the following steps to set up timing analysis:
+     *
+     * 1. Constructs a `tatum::DelayCalculator` for post-clustering delay calculations.
+     *    This calculator holds a reference to `PlacerTimingContext::connection_delay`,
+     *    which contains net delays based on block locations.
+     *
+     * 2. Creates and stores a `SetupTimingInfo` object in `timing_info_`.
+     *    This object utilizes the delay calculator to compute delays on timing edges
+     *    and calculate setup times.
+     *
+     * 3. Constructs `PlacerSetupSlacks` and `PlacerCriticalities` objects,
+     *    which translate arrival and required times into slacks and criticalities,
+     *    respectively.
+     *
+     * 4. Creates a `NetPinTimingInvalidator` object to mark timing edges
+     *    corresponding to the pins of moved blocks as invalid.
+     *
+     * 5. Performs a full timing analysis by marking all pins as invalid.
+     *
+     * @param net_list The netlist used for iterating over pins.
+     * @param analysis_opts Analysis options, including whether to echo the timing graph.
+     */
     void alloc_and_init_timing_objects_(const Netlist<>& net_list,
                                         const t_analysis_opts& analysis_opts);
 

vpr/src/timing/timing_info.h

@@ -62,7 +62,7 @@ class SetupTimingInfo : public virtual TimingInfo {
     //Return the critical path with the least slack
     virtual tatum::TimingPathInfo least_slack_critical_path() const = 0;
 
-    //Return the critical path the the longest absolute delay
+    //Return the critical path the longest absolute delay
     virtual tatum::TimingPathInfo longest_critical_path() const = 0;
 
     //Return the set of critical paths between all clock domain pairs