reformat comments of t_arch_switch_inf

Author: soheilshahrouz

libs/libarchfpga/src/physical_types.h

@@ -1697,51 +1697,46 @@ enum class BufferSize {
     ABSOLUTE
 };
 
-/* Lists all the important information about a switch type read from the     *
- * architecture file.                                                        *
- * [0 .. Arch.num_switch]                                                    *
- * buffered:  Does this switch include a buffer?                             *
- * R:  Equivalent resistance of the buffer/switch.                           *
- * Cin:  Input capacitance.                                                  *
- * Cout:  Output capacitance.                                                *
- * Cinternal: Since multiplexers and tristate buffers are modeled as a       *
- *            parallel stream of pass transistors feeding into a buffer,     *
- *            we would expect an additional "internal capacitance"           *
- *            to arise when the pass transistor is enabled and the signal    *
- *            must propagate to the buffer. See diagram of one stream below: *
- *                                                                           *
- *                  Pass Transistor                                          *
- *                       |                                                   *
- *                     -----                                                 *
- *                     -----      Buffer                                     *
- *                    |     |       |\                                       *
- *              ------       -------| \--------                              *
- *                |             |   | /    |                                 *
- *              =====         ===== |/   =====                               *
- *              =====         =====      =====                               *
- *                |             |          |                                 *
- *             Input C    Internal C    Output C                             *
- *                                                                           *
- * Tdel_map: A map where the key is the number of inputs and the entry       *
- *           is the corresponding delay. If there is only one entry at key   *
- *           UNDEFINED, then delay is a constant (doesn't vary with fan-in). *
- *	         A map saves us the trouble of sorting, and has lower access     *
- *           time for interpolation/extrapolation purposes                   *
- * mux_trans_size:  The area of each transistor in the segment's driving mux *
- *                  measured in minimum width transistor units               *
- * buf_size:  The area of the buffer. If set to zero, area should be         *
- *            calculated from R                                              */
+/**
+ * @struct t_arch_switch_inf
+ * @brief Lists all the important information about a switch type read from the architecture file.
+ */
 struct t_arch_switch_inf {
   public:
     static constexpr int UNDEFINED_FANIN = -1;
 
     std::string name;
+    /// Equivalent resistance of the buffer/switch
     float R = 0.;
+    /// Input capacitance
     float Cin = 0.;
+    /// Output capacitance
     float Cout = 0.;
+    /**
+     * @brief   The internal capacitance.
+     * @details Since multiplexers and tristate buffers are modeled as a
+     *          parallel stream of pass transistors feeding into a buffer,
+     *          we would expect an additional "internal capacitance
+     *          to arise when the pass transistor is enabled and the signal
+     *          must propagate to the buffer. See diagram of one stream below:
+     *
+     *              Pass Transistor
+     *                   |
+     *                 -----
+     *                 -----      Buffer
+     *                |     |       |\
+     *          ------       -------| \ -----
+     *            |             |   | /    |
+     *          =====         ===== |/   =====
+     *          =====         =====      =====
+     *            |             |          |
+     *          Input C    Internal C    Output C
+     */
     float Cinternal = 0.;
+    /// The area of each transistor in the segment's driving mux measured in minimum width transistor units
     float mux_trans_size = 1.;
     BufferSize buf_size_type = BufferSize::AUTO;
+    /// The area of the buffer. If set to zero, area should be calculated from R
     float buf_size = 0.;
     e_power_buffer_type power_buffer_type = POWER_BUFFER_TYPE_AUTO;
     float power_buffer_size = 0.;
@@ -1774,6 +1769,15 @@ struct t_arch_switch_inf {
 
   private:
     SwitchType type_ = SwitchType::INVALID;
+
+    /**
+     * @brief   Maps the number of inputs to a delay.
+     * @details A map where the key is the number of inputs and the entry
+     *          is the corresponding delay. If there is only one entry at key
+     *          UNDEFINED, then delay is a constant (doesn't vary with fan-in).
+     *          A map saves us the trouble of sorting, and has lower access
+     *          time for interpolation/extrapolation purposes
+     */
     std::map<int, double> Tdel_map_;
 
     friend void PrintArchInfo(FILE*, const t_arch*);
@@ -2048,7 +2052,8 @@ struct t_arch {
     mutable vtr::string_internment strings;
     std::vector<vtr::interned_string> interned_strings;
 
-    char* architecture_id; //Secure hash digest of the architecture file to uniquely identify this architecture
+    /// Secure hash digest of the architecture file to uniquely identify this architecture
+    char* architecture_id;
 
     t_chan_width_dist Chans;
     enum e_switch_block_type SBType;
@@ -2059,6 +2064,7 @@ struct t_arch {
     float grid_logic_tile_area;
     std::vector<t_segment_inf> Segments;
 
+    /// Contains information from all switch types defined in the architecture file.
     std::vector<t_arch_switch_inf> switches;
 
     /// Contains information about all direct chain connections in the architecture
@@ -2115,7 +2121,7 @@ struct t_arch {
 
     t_clock_arch_spec clock_arch; // Clock related data types
 
-    // if we have an embedded NoC in the architecture, then we store it here
+    /// Stores NoC-related architectural information when there is an embedded NoC
     t_noc_inf* noc = nullptr;
 };
 

vpr/src/base/blk_loc_registry.h

@@ -128,7 +128,6 @@ class BlkLocRegistry {
      */
     void revert_move_blocks(const t_pl_blocks_to_be_moved& blocks_affected);
 
-    ///@brief Helper function that returns the x, y coordinates of a pin
     /**
      * @brief Returns the coordinates of a cluster pin
      * @param pin The unique Id of the cluster pin whose coordinates is desired.

vpr/src/place/centroid_move_generator.h

@@ -77,23 +77,12 @@ class CentroidMoveGenerator : public MoveGenerator {
 
     /**
      * @brief Calculates the exact centroid location
-     *
-     * This function is very useful in centroid and weightedCentroid moves as it calculates
-     * the centroid location. It returns the calculated location in centroid.
-     *
      * When NoC attraction is enabled, the computed centroid is slightly adjusted towards the location
      * of NoC routers that are in the same NoC group b_from.
      *
      * @param b_from The block Id of the moving block
-     * @param timing_weights Determines whether to calculate centroid or
-     * weighted centroid location. If true, use the timing weights (weighted centroid).
      * @param criticalities A pointer to the placer criticalities which is used when
      * calculating weighted centroid (send a NULL pointer in case of centroid)
-     * @param noc_attraction_enabled Indicates whether the computed centroid location
-     * should be adjusted towards NoC routers in the NoC group of the given block.
-     * @param noc_attraction_weight When NoC attraction is enabled, this weight
-     * specifies to which extent the computed centroid should be adjusted. A value
-     * in range [0, 1] is expected.
      *
      * @return The calculated location is returned in centroid parameter that is sent by reference
      */

vpr/src/place/move_transactions.h

@@ -32,7 +32,7 @@ struct t_pl_moved_block {
 
 class MoveAbortionLogger {
   public:
-    /// Records a reasons for an aborted move.
+    /// Records reasons for an aborted move.
     void log_move_abort(std::string_view reason);
 
     /// Prints a brief report about aborted move reasons and counts.

vpr/src/place/place_macro.cpp

@@ -71,7 +71,7 @@ void PlaceMacros::alloc_and_load_placement_macros(const std::vector<t_direct_inf
      * only at first. Allocate for the second dimension when I know
      * the size. Otherwise, the array is going to be of size
      * cluster_ctx.clb_nlist.blocks().size()^2 (There are big
-     * benckmarks VPR that have cluster_ctx.clb_nlist.blocks().size()
+     * benchmarks VPR that have cluster_ctx.clb_nlist.blocks().size()
      * in the 100k's range).
      *
      * The placement macro array is freed by the caller(s).
@@ -378,15 +378,9 @@ static bool try_combine_macros(std::vector<std::vector<ClusterBlockId>>& pl_macr
     return true;
 }
 
-int PlaceMacros::get_imacro_from_iblk(ClusterBlockId iblk) const{
-    /* This mapping is needed for fast lookups whether the block with index *
-     * iblk belongs to a placement macro or not.                             *
-     *                                                                       *
-     * The array imacro_from_iblk_ is used for the mapping for speed reason *
-     * [0...cluster_ctx.clb_nlist.blocks().size()-1]                                                    */
-
+int PlaceMacros::get_imacro_from_iblk(ClusterBlockId iblk) const {
     int imacro;
-    if (iblk) {
+    if (iblk != ClusterBlockId::INVALID()) {
         /* Return the imacro for the block. */
         imacro = imacro_from_iblk_[iblk];
     } else {
@@ -396,53 +390,31 @@ int PlaceMacros::get_imacro_from_iblk(ClusterBlockId iblk) const{
     return imacro;
 }
 
-void PlaceMacros::set_imacro_for_iblk(int imacro, ClusterBlockId blk_id) {
-    auto& cluster_ctx = g_vpr_ctx.clustering();
-
-    imacro_from_iblk_.resize(cluster_ctx.clb_nlist.blocks().size());
-    imacro_from_iblk_.insert(blk_id, imacro);
-}
-
 void PlaceMacros::alloc_and_load_idirect_from_blk_pin_(const std::vector<t_direct_inf>& directs) {
-    /* Allocates and loads idirect_from_blk_pin and direct_type_from_blk_pin arrays.    *
-     *                                                                                  *
-     * For a bus (multiple bits) direct connection, all the pins in the bus are marked. *
-     *                                                                                  *
-     * idirect_from_blk_pin array allow us to quickly find pins that could be in a      *
-     * direct connection. Values stored is the index of the possible direct connection  *
-     * as specified in the arch file, OPEN (-1) is stored for pins that could not be    *
-     * part of a direct chain connection.                                               *
-     *                                                                                  *
-     * direct_type_from_blk_pin array stores the value SOURCE if the pin is the         *
-     * from_pin, SINK if the pin is the to_pin in the direct connection as specified in *
-     * the arch file, OPEN (-1) is stored for pins that could not be part of a direct   *
-     * chain connection.                                                                *
-     *                                                                                  *
-     * Stores the pointers to the two 2D arrays in the addresses passed in.             *
-     *                                                                                  *
-     * The two arrays are freed by the caller(s).                                       */
+    const auto& device_ctx = g_vpr_ctx.device();
+
     constexpr size_t MAX_STRING_LEN = 512;
 
-    char to_pb_type_name[MAX_STRING_LEN + 1], to_port_name[MAX_STRING_LEN + 1],
-        from_pb_type_name[MAX_STRING_LEN + 1], from_port_name[MAX_STRING_LEN + 1];
+    char to_pb_type_name[MAX_STRING_LEN + 1];
+    char to_port_name[MAX_STRING_LEN + 1];
+    char from_pb_type_name[MAX_STRING_LEN + 1];
+    char from_port_name[MAX_STRING_LEN + 1];
 
-    int to_start_pin_index = -1, to_end_pin_index = -1;
-    int from_start_pin_index = -1, from_end_pin_index = -1;
-    auto& device_ctx = g_vpr_ctx.device();
+    int to_start_pin_index = -1;
+    int to_end_pin_index = -1;
+    int from_start_pin_index = -1;
+    int from_end_pin_index = -1;
 
-    /* Allocate and initialize the values to OPEN (-1). */
+    // Allocate and initialize the values to OPEN (-1).
     idirect_from_blk_pin_.resize(device_ctx.physical_tile_types.size());
     direct_type_from_blk_pin_.resize(device_ctx.physical_tile_types.size());
-    for (const auto& type : device_ctx.physical_tile_types) {
+    for (const t_physical_tile_type& type : device_ctx.physical_tile_types) {
         if (is_empty_type(&type)) {
             continue;
         }
 
-        int itype = type.index;
-        int num_type_pins = type.num_pins;
-
-        idirect_from_blk_pin_[itype].resize(num_type_pins, OPEN);
-        direct_type_from_blk_pin_[itype].resize(num_type_pins, OPEN);
+        idirect_from_blk_pin_[type.index].resize(type.num_pins, OPEN);
+        direct_type_from_blk_pin_[type.index].resize(type.num_pins, OPEN);
     }
 
     /* Load the values */
@@ -679,10 +651,6 @@ bool PlaceMacros::net_is_driven_by_direct_(ClusterNetId clb_net) {
     return direct != OPEN;
 }
 
-//t_pl_macro& PlaceMacros::operator[](size_t idx) {
-//    return pl_macros_[idx];
-//}
-
 const t_pl_macro& PlaceMacros::operator[](int idx) const {
     return pl_macros_[idx];
 }

vpr/src/place/place_macro.h

@@ -133,12 +133,12 @@
 struct t_pl_macro_member {
     ///@brief The cluster_ctx.blocks index of this block.
     ClusterBlockId blk_index;
-    ///@brief The offset from the first macro member to this member
+    ///@brief The location offset from the first macro member to this member
     t_pl_offset offset;
 };
 
 struct t_pl_macro {
-    ///@brief An array of blocks in this macro [0:num_macro-1].
+    ///@brief A vector of blocks in this macro [0:num_macro-1].
     std::vector<t_pl_macro_member> members;
 };
 
@@ -165,10 +165,14 @@ class PlaceMacros {
      */
     void alloc_and_load_placement_macros(const std::vector<t_direct_inf>& directs);
 
+    /**
+     * @brief Returns the placement macro index to which the given block belongs.
+     * @param iblk The unique ID of a clustered block whose placement macro is of interest.
+     * @return The placement macro index that the given block is part of. A negative integer
+     * in returned if the block is not part of a macro.
+     */
     int get_imacro_from_iblk(ClusterBlockId iblk) const;
 
-    void set_imacro_for_iblk(int imacro, ClusterBlockId blk_id);
-
     /**
      * @brief Finds the head block of the macro that contains a given clustered block
      * @details Placement macro head is the base of the macro, where the locations of the other macro members can be
@@ -178,10 +182,17 @@ class PlaceMacros {
      */
     ClusterBlockId macro_head(ClusterBlockId blk) const;
 
+    /// @brief Returns a constant reference to all placement macros.
     const std::vector<t_pl_macro>& macros() const;
 
-//    t_pl_macro& operator[](size_t idx);
-    const t_pl_macro&  operator[](int idx) const;
+    /**
+     * @brief Returns the placement macro associated with a macro index.
+     * @param idx An index specifying a macro. get_imacro_from_iblk() can
+     * be called to find out a the macro index of the placement macro a
+     * clustered block is part of.
+     * @return A placement macro associated with the given index.
+     */
+    const t_pl_macro& operator[](int idx) const;
 
   private:
 
@@ -223,6 +234,21 @@ class PlaceMacros {
 
     bool net_is_driven_by_direct_(ClusterNetId clb_net);
 
+    /**
+     * @brief Allocates and loads idirect_from_blk_pin and direct_type_from_blk_pin arrays.
+     *
+     * @details For a bus (multiple bits) direct connection, all the pins in the bus are marked.
+     * idirect_from_blk_pin vector allow us to quickly find pins that could be in a
+     * direct connection. Values stored is the index of the possible direct connection
+     * as specified in the arch file, OPEN (-1) is stored for pins that could not be
+     * part of a direct chain connection.
+     *
+     * direct_type_from_blk_pin vector stores the value SOURCE if the pin is the
+     * from_pin, SINK if the pin is the to_pin in the direct connection as specified in
+     * the arch file, OPEN (-1) is stored for pins that could not be part of a direct
+     * chain connection.
+     * @param directs Contains information about all direct connections in the architecture.
+     */
     void alloc_and_load_idirect_from_blk_pin_(const std::vector<t_direct_inf>& directs);
 };
 

vpr/src/place/simpleRL_move_generator.h

@@ -29,7 +29,7 @@ class KArmedBanditAgent {
      * @brief Update the agent Q-table based on the reward received by the SA algorithm
      *
      *   @param reward A double value calculated in "place.cpp" file showing how placement cost was affected by the prior action taken
-     *   @param reward_func The reward function used by the agent, detail explanation can be found on "m.h" file
+     *   @param reward_func The reward function used by the agent.
      */
     void process_outcome(double, e_reward_function);