Skip to content

Commit 6905b3e

Browse files
add more comments
1 parent be43312 commit 6905b3e

File tree

2 files changed

+50
-13
lines changed

2 files changed

+50
-13
lines changed

vpr/src/place/placement_log_printer.h

Lines changed: 38 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,9 @@
22
* @file placement_log_printer.h
33
* @brief Declares the PlacementLogPrinter class and associated utilities for logging
44
* and reporting placement-related statistics and timing analysis results.
5-
*
6-
* This file provides tools to monitor and report the progress and results of the placement stage.
7-
*
8-
* ### Key Components:
9-
* - **PlacementLogPrinter**:
10-
* - A utility class for logging placement status, resource utilization, and swap statistics.
11-
* - Prints detailed statistics during the placement process, including initial and post-placement states.
12-
* - Supports a "quiet mode" to suppress output.
13-
*
5+
146
* ### Integration:
15-
* The tools in this file integrate with the Placer class to provide information about
7+
* The PlacementLogPrinter class integrates with the Placer class to provide information about
168
* the placement process for debugging, optimization, and analysis purposes.
179
*/
1810

@@ -33,20 +25,54 @@ struct t_swap_stats;
3325
class BlkLocRegistry;
3426
class Placer;
3527

28+
/**
29+
* @class PlacementLogPrinter
30+
* @brief A utility class for logging placement status and
31+
* updating the screen view when graphics are enabled.
32+
*/
3633
class PlacementLogPrinter {
3734
public:
38-
explicit PlacementLogPrinter(const Placer& placer, bool quiet);
35+
/**
36+
* @param placer The placer object from which the placement status is retrieved.
37+
* @param quiet When set true, the logger doesn't print any information.
38+
*/
39+
PlacementLogPrinter(const Placer& placer,
40+
bool quiet);
3941

42+
/**
43+
* @brief Prints the placement status header that shows which metrics are reported
44+
* in each iteration of the annealer's outer loop.
45+
* @details This method should be called once before the first call to print_place_status().
46+
*/
4047
void print_place_status_header() const;
48+
49+
/**
50+
* @brief Print placement metrics and elapsed time after each outer loop iteration of the annealer.
51+
* If graphics are on, the function will the screen view.
52+
* @param elapsed_sec Time spent in the latest outer loop iteration.
53+
*/
54+
void print_place_status(float elapsed_sec) const;
55+
56+
/// Reports the resource utilization for each block type.
4157
void print_resources_utilization() const;
58+
/// Reports the number of tried temperatures, total swaps, and how many were accepted or rejected.
4259
void print_placement_swaps_stats() const;
43-
void print_place_status(float elapsed_sec) const;
60+
/// Reports placement metrics after the initial placement.
4461
void print_initial_placement_stats() const;
62+
/// Prints final placement metrics and generates timing reports.
4563
void print_post_placement_stats() const;
4664

4765
private:
66+
/**
67+
* @brief A constant reference to the Placer object to access the placement status.
68+
* @details PlacementLogPrinter is a friend class for the Placer class, so it can
69+
* access all its private data members. This reference is made constant to avoid
70+
* any accidental modification of the Placer object.
71+
*/
4872
const Placer& placer_;
73+
/// Specifies whether this object prints logs and updates the graphics.
4974
const bool quiet_;
75+
/// A string buffer to carry the message to shown in the graphical interface.
5076
mutable std::vector<char> msg_;
5177
};
5278

vpr/src/place/placer.h

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @file placer.h
33
* @brief Declares the Placer class, which encapsulates the functionality, data structures,
4-
* and algorithms required for the placement stage.
4+
* and algorithms required for the (annealing-based) placement stage
55
*
66
* The Placer class initializes necessary objects, performs an initial placement,
77
* and runs simulated annealing optimization. This optimization minimizes
@@ -47,6 +47,17 @@ class Placer {
4747
bool is_flat,
4848
bool quiet);
4949

50+
/**
51+
* @brief Executes the simulated annealing algorithm to optimize placement.
52+
*
53+
* This function minimizes placement costs, including bounding box and timing costs,
54+
* using simulated annealing. During the process, it periodically updates timing information
55+
* and saves a checkpoint of the best placement encountered.
56+
*
57+
* After the simulated annealing completes, the final placement is evaluated against the
58+
* checkpoint. If the final placement's quality is worse than the checkpoint, the checkpoint
59+
* is restored. The final placement is then validated for legality.
60+
*/
5061
void place();
5162

5263
/**

0 commit comments

Comments
 (0)