add implementation and doxygen comments for add_and_connect_non_3d_sg_links()

Author: soheilshahrouz

vpr/src/route/rr_graph_generation/rr_graph.cpp

@@ -378,6 +378,22 @@ static void build_rr_graph(e_graph_type graph_type,
 static int get_delayless_switch_id(const t_det_routing_arch& det_routing_arch,
                                    bool load_rr_graph);
 
+/**
+ * @brief Adds and connects non-3D scatter–gather (SG) links to the RR graph.
+ *
+ * For each bottleneck link, this function creates a corresponding RR node
+ * representing the non-3D SG link, and records edges between the node and
+ * gather and scatter wires. The edges are stored in `non_3d_sg_rr_edges_to_create`
+ * for deferred creation.
+ *
+ * @param rr_graph_builder     Reference to the RR graph builder.
+ * @param sg_links             List of scatter–gather bottleneck links.
+ * @param sg_node_indices      RR node IDs and track numbers for SG links.
+ * @param chan_details_x       Channel details for CHANX segments.
+ * @param chan_details_y       Channel details for CHANY segments.
+ * @param num_seg_types_x      Number of segment types in the X direction.
+ * @param non_3d_sg_rr_edges_to_create  Set collecting RR edges to create later.
+ */
 static void add_and_connect_non_3d_sg_links(RRGraphBuilder& rr_graph_builder,
                                             const std::vector<t_bottleneck_link>& sg_links,
                                             const std::vector<std::pair<RRNodeId, int>>& sg_node_indices,
@@ -2048,6 +2064,7 @@ static void add_and_connect_non_3d_sg_links(RRGraphBuilder& rr_graph_builder,
                                             const t_chan_details& chan_details_y,
                                             size_t num_seg_types_x,
                                             t_rr_edge_info_set& non_3d_sg_rr_edges_to_create) {
+    // Each SG link should have a corresponding RR node index
     VTR_ASSERT(sg_links.size() == sg_node_indices.size());
     const size_t num_links = sg_links.size();
 
@@ -2060,6 +2077,8 @@ static void add_and_connect_non_3d_sg_links(RRGraphBuilder& rr_graph_builder,
         const t_physical_tile_loc& src_loc = link.gather_loc;
         const t_physical_tile_loc& dst_loc = link.scatter_loc;
 
+        // Step 1: Determine the link’s direction and its spatial span.
+        // SG links are confined to one layer (non-3D), but can run in X or Y.
         VTR_ASSERT_SAFE(src_loc.layer_num == dst_loc.layer_num);
         const int layer = src_loc.layer_num;
 
@@ -2087,40 +2106,61 @@ static void add_and_connect_non_3d_sg_links(RRGraphBuilder& rr_graph_builder,
             VTR_ASSERT(false);
         }
 
+        // Retrieve the node ID and track number allocated earlier
         const RRNodeId node_id = sg_node_indices[i].first;
         const int track_num = sg_node_indices[i].second;
 
+        // Step 2: Assign coordinates
         rr_graph_builder.set_node_layer(node_id, layer, layer);
         rr_graph_builder.set_node_coordinates(node_id, xlow, ylow, xhigh, yhigh);
         rr_graph_builder.set_node_capacity(node_id, 1);
 
+        // Step 3: Set cost index based on segment type and orientation
         const size_t cons_index = link.chan_type == e_rr_type::CHANX ? CHANX_COST_INDEX_START + link.parallel_segment_index
                                                                      : CHANX_COST_INDEX_START + num_seg_types_x + link.parallel_segment_index;
         rr_graph_builder.set_node_cost_index(node_id, RRIndexedDataId(cons_index));
 
+        // Step 4: Assign electrical characteristics
         float R = 0;
         float C = 0;
         rr_graph_builder.set_node_rc_index(node_id, NodeRCIndex(find_create_rr_rc_data(R, C, g_vpr_ctx.mutable_device().rr_rc_data)));
+        // Step 5: Set node type, track number, and direction
         rr_graph_builder.set_node_type(node_id, link.chan_type);
         rr_graph_builder.set_node_track_num(node_id, track_num);
-
         rr_graph_builder.set_node_direction(node_id, direction);
 
+        // Step 6: Add incoming edges from gather (fanin) channel wires
+        // Each gather wire connects to this SG link node using the SG wire switch.
         for (const t_sg_candidate& gather_wire : link.gather_fanin_connections) {
             const t_physical_tile_loc& chan_loc = gather_wire.chan_loc.location;
             e_rr_type gather_chan_type = gather_wire.chan_loc.chan_type;
-            RRNodeId gather_node = rr_graph_builder.node_lookup().find_node(chan_loc.layer_num, chan_loc.x, chan_loc.y, gather_chan_type, gather_wire.wire_switchpoint.wire);
 
+            // Locate the source RR node for this gather wire
+            RRNodeId gather_node = rr_graph_builder.node_lookup().find_node(chan_loc.layer_num,
+                                                                            chan_loc.x,
+                                                                            chan_loc.y,
+                                                                            gather_chan_type,
+                                                                            gather_wire.wire_switchpoint.wire);
+            // Record deferred edge creation (gather_node --> sg_node)
             non_3d_sg_rr_edges_to_create.emplace_back(gather_node, node_id, link.arch_wire_switch, false);
         }
 
+        // Step 7: Add outgoing edges to scatter (fanout) channel wires
+        // Each scatter wire connects from this SG link node outward.
         for (const t_sg_candidate& scatter_wire : link.scatter_fanout_connections) {
             const t_physical_tile_loc& chan_loc = scatter_wire.chan_loc.location;
             e_rr_type scatter_chan_type = scatter_wire.chan_loc.chan_type;
             const t_chan_details& chan_details = (scatter_chan_type == e_rr_type::CHANX) ? chan_details_x : chan_details_y;
-            RRNodeId scatter_node = rr_graph_builder.node_lookup().find_node(chan_loc.layer_num, chan_loc.x, chan_loc.y, scatter_chan_type, scatter_wire.wire_switchpoint.wire);
 
+            // Locate the destination RR node for this scatter wire
+            RRNodeId scatter_node = rr_graph_builder.node_lookup().find_node(chan_loc.layer_num,
+                                                                             chan_loc.x,
+                                                                             chan_loc.y,
+                                                                             scatter_chan_type,
+                                                                             scatter_wire.wire_switchpoint.wire);
+            // Determine which architecture switch this edge should use
             int switch_index = chan_details[chan_loc.x][chan_loc.y][scatter_wire.wire_switchpoint.wire].arch_wire_switch();
+            // Record deferred edge creation (sg_node --> scatter_node)
             non_3d_sg_rr_edges_to_create.emplace_back(node_id, scatter_node, switch_index, false);
         }
     }

vtr_flow/tasks/regression_tests/vtr_reg_strong/strong_custom_grid_fixed/config/golden_results.txt

@@ -1,2 +1,2 @@
  arch	  circuit	  script_params	  vtr_flow_elapsed_time	  vtr_max_mem_stage	  vtr_max_mem	  error	  odin_synth_time	  max_odin_mem	  parmys_synth_time	  max_parmys_mem	  abc_depth	  abc_synth_time	  abc_cec_time	  abc_sec_time	  max_abc_mem	  ace_time	  max_ace_mem	  num_clb	  num_io	  num_memories	  num_mult	  vpr_status	  vpr_revision	  vpr_build_info	  vpr_compiler	  vpr_compiled	  hostname	  rundir	  max_vpr_mem	  num_primary_inputs	  num_primary_outputs	  num_pre_packed_nets	  num_pre_packed_blocks	  num_netlist_clocks	  num_post_packed_nets	  num_post_packed_blocks	  device_width	  device_height	  device_grid_tiles	  device_limiting_resources	  device_name	  pack_mem	  pack_time	  initial_placed_wirelength_est	  placed_wirelength_est	  total_swap	  accepted_swap	  rejected_swap	  aborted_swap	  place_mem	  place_time	  place_quench_time	  initial_placed_CPD_est	  placed_CPD_est	  placed_setup_TNS_est	  placed_setup_WNS_est	  placed_geomean_nonvirtual_intradomain_critical_path_delay_est	  place_delay_matrix_lookup_time	  place_quench_timing_analysis_time	  place_quench_sta_time	  place_total_timing_analysis_time	  place_total_sta_time	  ap_mem	  ap_time	  ap_full_legalizer_mem	  ap_full_legalizer_time	  min_chan_width	  routed_wirelength	  min_chan_width_route_success_iteration	  logic_block_area_total	  logic_block_area_used	  min_chan_width_routing_area_total	  min_chan_width_routing_area_per_tile	  min_chan_width_route_time	  min_chan_width_total_timing_analysis_time	  min_chan_width_total_sta_time	  crit_path_num_rr_graph_nodes	  crit_path_num_rr_graph_edges	  crit_path_collapsed_nodes	  crit_path_routed_wirelength	  crit_path_route_success_iteration	  crit_path_total_nets_routed	  crit_path_total_connections_routed	  crit_path_total_heap_pushes	  crit_path_total_heap_pops	  critical_path_delay	  geomean_nonvirtual_intradomain_critical_path_delay	  setup_TNS	  setup_WNS	  hold_TNS	  hold_WNS	  crit_path_routing_area_total	  crit_path_routing_area_per_tile	  router_lookahead_computation_time	  crit_path_route_time	  crit_path_create_rr_graph_time	  crit_path_create_intra_cluster_rr_graph_time	  crit_path_tile_lookahead_computation_time	  crit_path_router_lookahead_computation_time	  crit_path_total_timing_analysis_time	  crit_path_total_sta_time	 
- fixed_grid.xml	  raygentop.v	  common	  17.26	  vpr	  85.18 MiB	  	  -1	  -1	  1.99	  42340	  4	  0.56	  -1	  -1	  36976	  -1	  -1	  127	  236	  1	  6	  success	  v8.0.0-13084-g071ad3865	  release IPO VTR_ASSERT_LEVEL=2	  GNU 13.3.0 on Linux-6.8.0-60-generic x86_64	  2025-06-17T09:37:40	  betzgrp-wintermute	  /home/pooladam/vtr-verilog-to-routing	  87220	  236	  305	  3177	  2989	  1	  1517	  675	  25	  25	  625	  -1	  25x25	  46.3 MiB	  2.03	  30552.8	  14077	  237395	  78558	  156700	  2137	  85.2 MiB	  1.24	  0.02	  6.54728	  4.56956	  -2883.52	  -4.56956	  4.56956	  0.59	  0.00510036	  0.0045553	  0.478327	  0.433095	  -1	  -1	  -1	  -1	  56	  26200	  45	  3.19446e+07	  9.76854e+06	  2.27235e+06	  3635.76	  7.42	  1.96901	  1.80319	  68115	  457904	  -1	  22555	  19	  6811	  19098	  2015069	  507374	  4.83769	  4.83769	  -3127.42	  -4.83769	  0	  0	  2.89946e+06	  4639.14	  0.10	  0.64	  0.31	  -1	  -1	  0.10	  0.288232	  0.270013
+ fixed_grid.xml	  raygentop.v	  common	  17.26	  vpr	  85.18 MiB	  	  -1	  -1	  1.99	  42340	  4	  0.56	  -1	  -1	  36976	  -1	  -1	  127	  236	  1	  6	  success	  v8.0.0-13084-g071ad3865	  release IPO VTR_ASSERT_LEVEL=2	  GNU 13.3.0 on Linux-6.8.0-60-generic x86_64	  2025-06-17T09:37:40	  betzgrp-wintermute	  /home/pooladam/vtr-verilog-to-routing	  87220	  236	  305	  3177	  2989	  1	  1517	  675	  25	  25	  625	  -1	  25x25	  46.3 MiB	  2.03	  30552.8	  14077	  237395	  78558	  156700	  2137	  85.2 MiB	  1.24	  0.02	  6.54728	  4.56956	  -2883.52	  -4.56956	  4.56956	  0.59	  0.00510036	  0.0045553	  0.478327	  0.433095	  -1	  -1	  -1	  -1	  56	  26200	  45	  3.19446e+07	  9.76854e+06	  2.27235e+06	  3635.76	  7.42	  1.96901	  1.80319	  68115	  457904	  -1	  22555	  19	  6811	  19098	  2015069	  507374	  4.83769	  4.83769	  -3127.42	  -4.83769	  0	  0	  2.89946e+06	  4639.14	  0.10	  0.64	  0.31	  -1	  -1	  0.10	  0.288232	  0.270013