doxygen comments in build_scatter_gather.h and utils.h

libs/librrgraph/src/base/rr_graph_builder.h

@@ -238,11 +238,12 @@ class RRGraphBuilder {
         node_storage_.set_node_ptc_num(id, new_ptc_num);
     }
 
-    /** @brief set the layer number at which RRNodeId is located at */
+    /// @brief Set the low layer coordinate where the given node is located at.
     inline void set_node_layer_low(RRNodeId id, int layer){
         node_storage_.set_node_layer_low(id, layer);
     }
 
+    /// @brief Set the high layer coordinate where the given node is located at.
     inline void set_node_layer_high(RRNodeId id, int layer){
         node_storage_.set_node_layer_high(id, layer);
     }

libs/librrgraph/src/base/rr_graph_storage.h

@@ -241,17 +241,12 @@ class t_rr_graph_storage {
         return node_fan_in_[id];
     }
 
-    /** @brief Find the layer number that RRNodeId is located at.
-     * It is zero if the FPGA only has one die.
-     * The layer number start from the base die (base die: 0, the die above it: 1, etc.)
-     */
-    // short node_layer(RRNodeId id) const{
-    //     return node_layer_[id];
-    // }
+    /// @brief Returns the lowest layer where the given node is located at.
     short node_layer_low(RRNodeId id) const {
         return node_layer_low_[id];
     }
 
+    /// @brief Returns the highest layer where the given node is located at.
     short node_layer_high(RRNodeId id) const {
         return node_layer_high_[id];
     }
@@ -915,13 +910,14 @@ class t_rr_graph_storage {
     /** @brief Fan in counts for each RR node. */
     vtr::vector<RRNodeId, t_edge_size> node_fan_in_;
 
-    /** @brief
-     * Layer number that each RR node is located at
-     * Layer number refers to the die that the node belongs to. The layer number of base die is zero and die above it one, etc.
-     * This data is also considered as a hot data since it is used in inner loop of router, but since it didn't fit nicely into t_rr_node_data due to alignment issues, we had to store it
-     * in a separate vector.
-     */
+    // Layer number refers to the die that the node belongs to.
+    // The layer number of base die is zero and die above it one, etc.
+    // This data is also considered as a hot data since it is used in inner loop of router,
+    // but since it didn't fit nicely into t_rr_node_data due to alignment issues, we had to store it in a separate vector.
+
+    /// @brief The lowest layer number where a given node is located at.
     vtr::vector<RRNodeId, char> node_layer_low_;
+    /// @brief The highest layer number where a given node is located at.
     vtr::vector<RRNodeId, char> node_layer_high_;
 
     /**
@@ -1107,20 +1103,12 @@ class t_rr_graph_view {
         return node_fan_in_[id];
     }
 
-    /**
-     * @brief Retrieve the layer (die) number where the given RRNodeId is located.
-     *
-     * @param id The RRNodeId for which to retrieve the layer number.
-     * @return The layer number (die) where the RRNodeId is located.
-     */
-    // short node_layer(RRNodeId id) const {
-    //     return node_layer_[id];
-    // }
-
+    /// @brief Retrieve the lowest layer (die) number where the given RRNodeId is located.
     short node_layer_low(RRNodeId id) const {
         return node_layer_low_[id];
     }
 
+    /// @brief Retrieve the highest layer (die) number where the given RRNodeId is located.
     short node_layer_high(RRNodeId id) const {
         return node_layer_high_[id];
     }

libs/librrgraph/src/base/rr_node.cpp

@@ -1,7 +1,7 @@
 #include "rr_node.h"
 #include "rr_graph_storage.h"
 
-//Returns the max 'length' over the x or y direction
+//Returns the max 'length' over the x or y or z direction
 short t_rr_node::length() const {
     return std::max({storage_->node_yhigh(id_) - storage_->node_ylow(id_),
                      storage_->node_xhigh(id_) - storage_->node_xlow(id_),

vpr/src/route/rr_graph_generation/build_scatter_gathers.h

@@ -7,25 +7,45 @@
 
 #include <vector>
 
+/// Identifies a specific channel location in the device grid.
 struct t_chan_loc {
-    t_physical_tile_loc location;
-    e_rr_type chan_type;
-    e_side side;
+    t_physical_tile_loc location;   ///< Physical grid location of the channel
+    e_rr_type chan_type;            ///< Type of routing channel (e.g., CHANX, CHANY)
+    e_side side;                    ///< Side of the reference switch block the channel lies on
 };
 
+/// Represents a wire candidate for scatter/gather connections.
 struct t_sg_candidate {
-    t_chan_loc chan_loc;
-    t_wire_switchpoint wire_switchpoint;
+    t_chan_loc chan_loc;                    ///< Channel location (coordinates, type, side) where the wire lies.
+    t_wire_switchpoint wire_switchpoint;    ///< Wire index and its valid switchpoint
 };
 
+/// Represents a scatter/gather bottleneck connection between two locations.
 struct t_bottleneck_link {
-    t_physical_tile_loc gather_loc;
-    t_physical_tile_loc scatter_loc;
-    int arch_wire_switch;
-    std::vector<t_sg_candidate> gather_fanin_connections;
-    std::vector<t_sg_candidate> scatter_fanout_connections;
+    t_physical_tile_loc gather_loc;                         ///< Source switchblock location.
+    t_physical_tile_loc scatter_loc;                        ///< Destination switchblock location.
+    int arch_wire_switch;                                   ///< The switch (mux) used to drive the bottleneck wire.
+    std::vector<t_sg_candidate> gather_fanin_connections;   ///< Wires driving the bottleneck link at  `gather_loc`
+    std::vector<t_sg_candidate> scatter_fanout_connections; ///< Wires driven by the bottleneck link at `scatter_loc`
 };
 
+/**
+ * @brief Builds scatter/gather bottleneck connections across the device grid.
+ *
+ * For each scatter/gather pattern, this routine finds candidate gather and scatter
+ * wires, evaluates connection limits from user-specified formulas, and creates
+ * bottleneck links between the corresponding locations. Both intra-die and inter-die
+ * (3D) connections are handled.
+ *
+ * @param scatter_gather_patterns List of scatter/gather connection patterns.
+ * @param inter_cluster_rr Flags indicating whether each layer has inter-cluster routing resources.
+ * @param segment_inf Wire segment type information.
+ * @param chan_details_x Channel details for horizontal routing channels.
+ * @param chan_details_y Channel details for vertical routing channels.
+ * @param nodes_per_chan Channel width data.
+ * @param interdie_3d_links Output: matrix storing inter-die (3D) bottleneck links.
+ * @return Vector of intra-die bottleneck links.
+ */
 std::vector<t_bottleneck_link> alloc_and_load_scatter_gather_connections(const std::vector<t_scatter_gather_pattern>& scatter_gather_patterns,
                                                                          const std::vector<bool>& inter_cluster_rr,
                                                                          const std::vector<t_segment_inf>& segment_inf,

vpr/src/route/rr_graph_generation/build_switchblocks.cpp

@@ -152,7 +152,6 @@ struct t_wireconn_scratchpad {
     std::vector<t_wire_switchpoint> scratch_wires;
 };
 
-
 /************ Function Declarations ************/
 
 /* Compute the wire(s) that the wire at (x, y, from_side, to_side, from_wire) should connect to.

vpr/src/route/rr_graph_generation/switchblock_scatter_gather_common_utils.cpp

@@ -7,6 +7,10 @@
 #include "rr_types.h"
 #include "vtr_expr_eval.h"
 
+//
+// Static Function Declarations
+//
+
 /**
  * Returns wire segment length based on either:
  * 1) the wire length specified in the segment details variable for this wire (if this wire segment doesn't span entire FPGA)
@@ -88,6 +92,10 @@ static bool is_core_sb(const DeviceGrid& grid, const t_physical_tile_loc& loc) {
     return is_core;
 }
 
+//
+// Static Function Definitions
+//
+
 static bool match_sb_xy(const DeviceGrid& grid,
                         const t_physical_tile_loc& loc,
                         const t_specified_loc& specified_loc) {
@@ -243,6 +251,10 @@ static int get_wire_segment_length(e_rr_type chan_type,
     return wire_length;
 }
 
+//
+// Non-static Function Definitions
+//
+
 bool sb_not_here(const DeviceGrid& grid,
                  const std::vector<bool>& inter_cluster_rr,
                  const t_physical_tile_loc& loc,

vpr/src/route/rr_graph_generation/switchblock_scatter_gather_common_utils.h

@@ -96,6 +96,12 @@ int get_switchpoint_of_wire(e_rr_type chan_type,
                             int seg_coord,
                             e_side sb_side);
 
+/**
+* @brief Evaluates a connection formula for scatter/gather and custom switchblock patterns.
+*
+* Sets variables "from" and "to" to the given wire counts and evaluates
+* the formula string using the provided parser
+*/
 int evaluate_num_conns_formula(vtr::FormulaParser& formula_parser,
                                vtr::t_formula_data& formula_data,
                                const std::string& num_conns_formula,