Merge pull request #3289 from verilog-to-routing/temp_org_rr_g_remaining_comments

Address remaining comments from #3281

Author: vaughnbetz

libs/libarchfpga/src/physical_types.h

@@ -1532,22 +1532,23 @@ struct t_pb_graph_pin_power {
 /* FPGA Routing architecture                                                                     */
 /*************************************************************************************************/
 
-/* Description of routing channel distribution across the FPGA, only available for global routing
- * Width is standard dev. for Gaussian.  xpeak is where peak     *
- * occurs. dc is the dc offset for Gaussian and pulse waveforms. */
+/// @brief Description of routing channel distribution across the FPGA, only available for global routing
 enum class e_stat {
     UNIFORM,
     GAUSSIAN,
     PULSE,
     DELTA
 };
 
+/// @brief Parameters describing a channel distribution.
+/// @note  If detailed routing is performed, only a uniform (all channels in a given direction are the same width)
+/// distribution is supported.
 struct t_chan {
-    e_stat type;
-    float peak;
-    float width;
-    float xpeak;
-    float dc;
+    e_stat type;  ///< Distribution type
+    float peak;   ///< Peak value. For a UNIFORM distribution, this is the value for all channels (in a given direction).
+    float width;  ///< Standard deviation (Gaussian)
+    float xpeak;  ///< Peak location (Gaussian)
+    float dc;     ///< DC offset (Gaussian, pulse)
 };
 
 /* chan_x_dist: Describes the x-directed channel width distribution.         *
@@ -1754,13 +1755,14 @@ struct t_hash_segment_inf {
     }
 };
 
+/// @brief Enumerates switch types used in the FPGA architecture and RR graph.
 enum class e_switch_type {
-    MUX = 0,   //A configurable (buffered) mux (single-driver)
-    TRISTATE,  //A configurable tristate-able buffer (multi-driver)
-    PASS_GATE, //A configurable pass transistor switch (multi-driver)
-    SHORT,     //A non-configurable electrically shorted connection (multi-driver)
-    BUFFER,    //A non-configurable non-tristate-able buffer (uni-driver)
-    INVALID,   //Unspecified, usually an error
+    MUX = 0,   ///< A configurable (buffered) mux (single-driver)
+    TRISTATE,  ///< A configurable tristate-able buffer (multi-driver)
+    PASS_GATE, ///< A configurable pass transistor switch (multi-driver)
+    SHORT,     ///< A non-configurable electrically shorted connection (multi-driver)
+    BUFFER,    ///< A non-configurable non-tristate-able buffer (uni-driver)
+    INVALID,   ///< Unspecified, usually an error
     NUM_SWITCH_TYPES
 };
 

libs/librrgraph/src/base/rr_edge.h

@@ -29,6 +29,7 @@ struct t_rr_edge_info {
 
 typedef std::vector<t_rr_edge_info> t_rr_edge_info_set;
 
+/// @brief Sorts and removes duplicate RR edges in-place.
 inline void uniquify_edges(t_rr_edge_info_set& rr_edges_to_create) {
     std::stable_sort(rr_edges_to_create.begin(), rr_edges_to_create.end());
     rr_edges_to_create.erase(std::unique(rr_edges_to_create.begin(), rr_edges_to_create.end()), rr_edges_to_create.end());

libs/librrgraph/src/base/rr_switch.h

@@ -5,54 +5,48 @@
 
 #include "physical_types.h"
 
-/* Lists all the important information about an rr switch type.              *
- * The s_rr_switch_inf describes a switch derived from a switch described    *
- * by s_arch_switch_inf. This indirection allows us to vary properties of a  *
- * given switch, such as varying delay with switch fan-in.                   *
- * buffered:  Does this switch isolate it's input/output into separate       *
- *            DC-connected sub-circuits?                                     *
- * configurable: Is this switch is configurable (i.e. can the switch can be  *
- *               turned on or off)?. This allows modelling of non-optional   *
- *               switches (e.g. fixed buffers, or shorted connections) which *
- *               must be used (e.g. expanded by the router) if a connected   *
- *               segment is used.                                            *
- * R:  Equivalent resistance of the buffer/switch.                           *
- * Cin:  Input capacitance.                                                  *
- * Cout:  Output capacitance.                                                *
- * Cinternal: Internal capacitance, see the definition above.                *
- * Tdel:  Intrinsic delay.  The delay through an unloaded switch is          *
- *        Tdel + R * Cout.                                                   *
- * 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
- * intra_tile: Indicate whether this rr_switch is a switch type used inside  *
- *             clusters. These switch types are not specified in the         *
- *             architecture description file and are added when flat router  *
- *             is enabled                                                    */
+/**
+ * @brief Lists all the important information about an RR switch type.
+ *
+ * The t_rr_switch_inf describes a switch derived from a switch described
+ * by t_arch_switch_inf. This indirection allows us to vary properties of a
+ * given switch, such as varying delay with switch fan-in.
+  */
 struct t_rr_switch_inf {
+    /// Equivalent resistance of the buffer/switch.
     float R = 0.;
+    /// Input capacitance.
     float Cin = 0.;
+    /// Output capacitance.
     float Cout = 0.;
+    /// Internal capacitance.
     float Cinternal = 0.;
+    /// Intrinsic delay.  The delay through an unloaded switch is Tdel + R * Cout.
     float Tdel = 0.;
+    /// The area of each transistor in the segment's driving mux measured in minimum width transistor units
     float mux_trans_size = 0.;
+    /// The area of the buffer. If set to zero, area should be calculated from R
     float buf_size = 0.;
     std::string name;
     e_power_buffer_type power_buffer_type = POWER_BUFFER_TYPE_UNDEFINED;
     float power_buffer_size = 0.;
 
+    /// Indicate whether this rr_switch is a switch type used inside clusters.
+    /// These switch types are not specified in the architecture description file
+    /// and are added when flat router is enabled.
     bool intra_tile = false;
 
-  public:
+  public: // Getters
     /// Returns the type of switch
     e_switch_type type() const;
 
     /// Returns true if this switch type isolates its input and output into
     /// separate DC-connected subcircuits
     bool buffered() const;
 
-    /// Returns true if this switch type is configurable
+    /// Returns true if this switch type is configurable (i.e. can the switch can be turned on or off)
+    /// This allows modelling of non-optional switches (e.g. fixed buffers, or shorted connections)
+    /// which must be used (e.g. expanded by the router) if a connected segment is used.
     bool configurable() const;
 
     bool operator==(const t_rr_switch_inf& other) const;
@@ -67,7 +61,7 @@ struct t_rr_switch_inf {
         std::size_t operator()(const t_rr_switch_inf& s) const;
     };
 
-  public:
+  public: // Setters
     void set_type(e_switch_type type_val);
 
   private:

vpr/src/route/rr_graph_generation/rr_graph_switch_utils.h

@@ -1,6 +1,21 @@
 
 #pragma once
 
+/**
+ * @file
+ * @brief Utilities for creating and initializing rr_switch structures from architecture switches.
+ *
+ * This header defines functions that translate high-level architecture switch
+ * descriptions (`t_arch_switch_inf`) into detailed rr_switch items used in RR graph.
+ * These functions:
+ *   - Copy and resolve switch electrical parameters into `t_rr_switch_inf`.
+ *   - Expand architecture switches into fanin-specific rr_switch variants.
+ *   - Provide mappings from (arch_switch, fanin) --> rr_switch index.
+ *
+ * They are invoked during RR graph construction to allocate, initialize,
+ * and remap all switch information.
+ */
+
 #include <map>
 #include <vector>
 

vpr/src/route/rr_graph_generation/rr_graph_tile_nodes.cpp

@@ -12,7 +12,7 @@ void add_classes_rr_graph(RRGraphBuilder& rr_graph_builder,
                           const std::vector<int>& class_num_vec,
                           const t_physical_tile_loc& root_loc,
                           t_physical_tile_type_ptr physical_type) {
-    auto& mutable_device_ctx = g_vpr_ctx.mutable_device();
+    DeviceContext& mutable_device_ctx = g_vpr_ctx.mutable_device();
 
     for (int class_num : class_num_vec) {
         e_pin_type class_type = get_class_type_from_class_physical_num(physical_type, class_num);
@@ -106,7 +106,7 @@ void connect_src_sink_to_pins(RRGraphBuilder& rr_graph_builder,
                               bool switches_remapped) {
     for (int class_num : class_num_vec) {
         const std::vector<int>& pin_list = get_pin_list_from_class_physical_num(physical_type_ptr, class_num);
-        auto class_type = get_class_type_from_class_physical_num(physical_type_ptr, class_num);
+        e_pin_type class_type = get_class_type_from_class_physical_num(physical_type_ptr, class_num);
         RRNodeId class_rr_node_id = get_class_rr_node_id(rr_graph_builder.node_lookup(), physical_type_ptr, tile_loc, class_num);
         VTR_ASSERT(class_rr_node_id != RRNodeId::INVALID());
         for (int pin_num : pin_list) {

vpr/src/route/rr_graph_generation/rr_graph_tile_nodes.h

@@ -1,17 +1,29 @@
 
 #pragma once
 
+/**
+ * @file
+ * @brief Functions for creating RR graph nodes for tile classes and pins.
+ *
+ * This header declares utilities used during RR graph construction:
+ * - Adds SOURCE and SINK nodes for within a tile.
+ * - Adds OPIN and IPIN nodes for physical pins of a tile.
+ * - Provides connections between source/sinks and pins using delayless switches.
+ */
+
 #include <vector>
 #include "physical_types.h"
 #include "rr_edge.h"
 
 class RRGraphBuilder;
 
+/// @brief Create SOURCE and SINK nodes for each class in a tile and set their properties.
 void add_classes_rr_graph(RRGraphBuilder& rr_graph_builder,
                           const std::vector<int>& class_num_vec,
                           const t_physical_tile_loc& root_loc,
                           t_physical_tile_type_ptr physical_type);
 
+/// @brief Create OPIN and IPIN nodes for each pin in a tile and set their properties.
 void add_pins_rr_graph(RRGraphBuilder& rr_graph_builder,
                        const std::vector<int>& pin_num_vec,
                        const t_physical_tile_loc& root_loc,