From 46d8927ac8521f9c17feee6d335942ac44221291 Mon Sep 17 00:00:00 2001 From: Lin Date: Tue, 24 Sep 2024 16:48:05 +0800 Subject: [PATCH 1/7] add rr graph view annotation --- libs/librrgraph/src/base/rr_graph_view.h | 460 +++++++++++++++-------- 1 file changed, 305 insertions(+), 155 deletions(-) diff --git a/libs/librrgraph/src/base/rr_graph_view.h b/libs/librrgraph/src/base/rr_graph_view.h index b96c7a615b..bdcc1c1601 100644 --- a/libs/librrgraph/src/base/rr_graph_view.h +++ b/libs/librrgraph/src/base/rr_graph_view.h @@ -4,33 +4,35 @@ #include "rr_graph_builder.h" #include "rr_node.h" #include "physical_types.h" -/* An read-only routing resource graph - * which is an unified object including pointors to - * - node storage - * - TODO: edge_storage - * - TODO: node_ptc_storage - * - TODO: node_fan_in_storage - * - rr_node_indices - * - * Note that the RRGraphView does not own the storage - * It serves a virtual read-only protocol for - * - placer - * - router - * - timing analyzer - * - GUI +/** + * @brief The RRGraphView encapsulates a read-only routing resource graph, providing clients with tailored frame views of the object. The RRGraphView represents the full frame view of the routing resource graph, offering several advantages: + + * - It reduces the memory footprint for each client. + * - It minimizes the need for extensive API changes, as each frame view delivers ad-hoc APIs suited to the specific needs of individual clients. * - * Note that each client of rr_graph may get a frame view of the object - * The RRGraphView is the complete frame view of the routing resource graph - * - This helps to reduce the memory footprint for each client - * - This avoids massive changes for each client on using the APIs - * as each frame view provides adhoc APIs for each client + * + * + * A unified object that includes pointers to: + * - Node storage + * - @todo Edge storage + * - @todo Node PTC storage + * - @todo Node fan-in storage + * - RR node indices * - * TODO: more compact frame views will be created, e.g., - * - a mini frame view: contains only node and edges, representing the connectivity of the graph - * - a geometry frame view: an extended mini frame view with node-level attributes, - * in particular geometry information (type, x, y etc). + * @note The RRGraphView does not own the storage. It provides a virtual + * read-only protocol for: + * - Placer + * - Router + * - Timing analyzer + * - GUI * + * @todo More compact frame views will be created, such as: + * - A mini frame view: Contains only nodes and edges, representing the + * connectivity of the graph. + * - A geometry frame view: An extended mini frame view with node-level + * attributes, particularly geometry information (type, x, y, etc.). */ + class RRGraphView { /* -- Constructors -- */ public: @@ -58,37 +60,50 @@ class RRGraphView { * kind of accessors */ public: - /* Aggregates: create range-based loops for nodes - * To iterate over the nodes in a RRGraph, - * using a range-based loop is suggested. - * ----------------------------------------------------------------- - * Example: iterate over all the nodes - * // Strongly suggest to use a read-only rr_graph object - * const RRGraph& rr_graph; - * for (const RRNodeId& node : rr_graph.nodes()) { - * // Do something with each node - * } + /** + * @brief Aggregates for creating range-based loops for nodes. + * + * To iterate over the nodes in an RRGraph, using a range-based loop is recommended. + * + * @code + * // Example: Iterate over all nodes + * // Strongly suggest using a read-only rr_graph object + * const RRGraph& rr_graph; + * for (const RRNodeId& node : rr_graph.nodes()) { + * // Do something with each node + * } + * @endcode */ + inline vtr::StrongIdRange nodes() const { return vtr::StrongIdRange(RRNodeId(0), RRNodeId(num_nodes())); } - /** @brief Return number of nodes. This function is inlined for runtime optimization. */ + /** @brief Get number of nodes. + * @return the number of routing resource nodes + */ inline size_t num_nodes() const { return node_storage_.size(); } - /** @brief Is the RR graph currently empty? */ + /** @brief check whether the RR graph is currently empty + * @return a boolean flag that indicates if the RR graph is empty. + */ inline bool empty() const { return node_storage_.empty(); } - /** @brief Returns a range of RREdgeId's belonging to RRNodeId id. - * If this range is empty, then RRNodeId id has no edges.*/ + /** @brief Get a range of RREdgeId's belonging to RRNodeId id. + * @param id the id of the node. + * @return a range of RREdgeIds + * @note If this range is empty, then RRNodeId id has no edges.*/ inline vtr::StrongIdRange edge_range(RRNodeId id) const { return vtr::StrongIdRange(node_storage_.first_edge(id), node_storage_.last_edge(id)); } - /** @brief Get the type of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the type of a routing resource node. + * @param node the id of the node. + * @return the type of the routing resource node. + */ inline t_rr_type node_type(RRNodeId node) const { return node_storage_.node_type(node); } @@ -96,110 +111,161 @@ class RRGraphView { /** * @brief Retrieve the name assigned to a given node ID. * - * If no name is assigned, an empty optional is returned. - * - * @param id The id of the node. - * @return An optional pointer to the string representing the name if found, + * @param node the id of the node. + * @return an optional pointer to the string representing the name if found, * otherwise an empty optional. + * @note If no name is assigned, an empty optional is returned. */ std::optional node_name(RRNodeId node) const { return node_storage_.node_name(node); } - /** @brief Get the type string of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the node type. + * @param node the id of the ndoe + * @return a string indicating the type of the source node + */ inline const char* node_type_string(RRNodeId node) const { return node_storage_.node_type_string(node); } - /** @brief Get the capacity of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the capacity of a routing resource node. + * @param node the id of the node + * @return capacity of the node + */ inline short node_capacity(RRNodeId node) const { return node_storage_.node_capacity(node); } - /** @brief Get the direction of a routing resource node. This function is inlined for runtime optimization. - * Direction::INC: wire driver is positioned at the low-coordinate end of the wire. - * Direction::DEC: wire_driver is positioned at the high-coordinate end of the wire. - * Direction::BIDIR: wire has multiple drivers, so signals can travel either way along the wire - * Direction::NONE: node does not have a direction, such as IPIN/OPIN + /** + * @brief Get the direction of a routing resource node. + * + * @param node the ID of the node. + * @return The direction of the node. + * + * @note Direction Categories: + * - `Direction::INC`: Wire driver is positioned at the low-coordinate end of the wire. + * - `Direction::DEC`: Wire driver is positioned at the high-coordinate end of the wire. + * - `Direction::BIDIR`: Wire has multiple drivers, allowing signals to travel either way along the wire. + * - `Direction::NONE`: Node does not have a direction, such as IPIN/OPIN. */ inline Direction node_direction(RRNodeId node) const { return node_storage_.node_direction(node); } - /** @brief Get the direction string of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the direction string of a routing resource node. + * @param node the id of the node + * @return a string indicating the direction + */ inline const std::string& node_direction_string(RRNodeId node) const { return node_storage_.node_direction_string(node); } - /** @brief Get the capacitance of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the capacitance of a routing resource node. + * @param node the id of the node + * @return the capacitance C of the routing resource node + */ inline float node_C(RRNodeId node) const { VTR_ASSERT(node_rc_index(node) < (short)rr_rc_data_.size()); return rr_rc_data_[node_rc_index(node)].C; } - /** @brief Get the resistance of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the resistance of a routing resource node. + * @param node the id of the node' + * @return the resistance R of the node + */ inline float node_R(RRNodeId node) const { VTR_ASSERT(node_rc_index(node) < (short)rr_rc_data_.size()); return rr_rc_data_[node_rc_index(node)].R; } - /** @brief Get the rc_index of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the rc_index of a routing resource node. + * @param node the id of the node + * @return the index of the node + */ inline int16_t node_rc_index(RRNodeId node) const { return node_storage_.node_rc_index(node); } - /** @brief Get the fan in of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the fan in count of a routing resource node. + * @param node the id of the node + * @return the fan in count of the node + */ inline t_edge_size node_fan_in(RRNodeId node) const { return node_storage_.fan_in(node); } - /** @brief Get the minimum x-coordinate of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the minimum x-coordinate of a routing resource node. + * @param node the id of the node + * @return the minimum x-coordinate of the node + */ inline short node_xlow(RRNodeId node) const { return node_storage_.node_xlow(node); } - /** @brief Get the maximum x-coordinate of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the maximum x-coordinate of a routing resource node. + * @param node the id of the node + * @return the maximum x-coordinate of the node + */ inline short node_xhigh(RRNodeId node) const { return node_storage_.node_xhigh(node); } - /** @brief Get the minimum y-coordinate of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the minimum y-coordinate of a routing resource node. + * @param node the id of the node + * @return the minimum y-coordinate of the node + */ inline short node_ylow(RRNodeId node) const { return node_storage_.node_ylow(node); } - /** @brief Get the maximum y-coordinate of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the maximum y-coordinate of a routing resource node. + * @param node the id of the node + * @return the maximum y-coordinate of the node + */ inline short node_yhigh(RRNodeId node) const { return node_storage_.node_yhigh(node); } - /** @brief Get the layer num of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the layer num of a routing resource node. + * @param node the id of the node + * @return the layer number of the node + */ inline short node_layer(RRNodeId node) const { return node_storage_.node_layer(node); } - - /** @brief Get the ptc number twist of a routing resource node. This function is inlined for runtime optimization. */ - inline short node_ptc_twist(RRNodeId node) const{ + + /** @brief Get the ptc number twist of a routing resource node. + * @param node the id of the node + * @return the twist number of the node + */ + inline short node_ptc_twist(RRNodeId node) const { return node_storage_.node_ptc_twist(node); } - /** @brief Get the first out coming edge of resource node. This function is inlined for runtime optimization. */ + /** @brief Get the first outgoing edge of resource node. + * @param node the id of the node + * @return the edge id of the first outgoing edge + */ inline RREdgeId node_first_edge(RRNodeId node) const { return node_storage_.first_edge(node); } - /** @brief Get the last out coming edge of resource node. This function is inlined for runtime optimization. */ + /** @brief Get the last outgoing edge of resource node. + * @param node the id of the node + * @return the edge id of the last outgoing edge + */ inline RREdgeId node_last_edge(RRNodeId node) const { return node_storage_.last_edge(node); } /** @brief Get the length (number of grid tile units spanned by the wire, including the endpoints) of a routing resource node. - * node_length() only applies to CHANX or CHANY and is always a positive number - * This function is inlined for runtime optimization. + * @param node the id of the node + * @return the length spanned by the rr node + * @note node_length() only applies to CHANX or CHANY and is always a positive number */ inline int node_length(RRNodeId node) const { VTR_ASSERT(node_type(node) == CHANX || node_type(node) == CHANY); - if(node_direction(node) == Direction::NONE){ + if (node_direction(node) == Direction::NONE) { return 0; //length zero wire } int length = 1 + node_xhigh(node) - node_xlow(node) + node_yhigh(node) - node_ylow(node); @@ -207,7 +273,10 @@ class RRGraphView { return length; } - /** @brief Check if routing resource node is initialized. This function is inlined for runtime optimization. */ + /** @brief Check if routing resource node is initialized. + * @param node the id of the node. + * @return a boolean flag indicating whether the node is initialized or not. + */ inline bool node_is_initialized(RRNodeId node) const { return !((node_type(node) == NUM_RR_TYPES) && (node_xlow(node) == -1) && (node_ylow(node) == -1) @@ -215,9 +284,12 @@ class RRGraphView { } /** @brief Check if two routing resource nodes are adjacent (must be a CHANX and a CHANY). - * This function is used for error checking; it checks if two nodes are physically adjacent (could be connected) based on their geometry. - * It does not check the routing edges to see if they are, in fact, possible to connect in the current routing graph. - * This function is inlined for runtime optimization. */ + + * @param chanx_node the id of the node to be compared + * @param chany_node the id of the node to be compared + * @return a boolean flag indicating whether the two nodes are adjacent + * @note This function performs error checking by determining whether two nodes are physically adjacent based on their geometry. It does not verify the routing edges to confirm if a connection is feasible within the current routing graph. + */ inline bool nodes_are_adjacent(RRNodeId chanx_node, RRNodeId chany_node) const { VTR_ASSERT(node_type(chanx_node) == CHANX && node_type(chany_node) == CHANY); if (node_ylow(chany_node) > node_ylow(chanx_node) + 1 || // verifies that chany_node is not more than one unit above chanx_node @@ -229,9 +301,15 @@ class RRGraphView { return true; } - /** @brief Check if node is within bounding box. - * To return true, the RRNode must be completely contained within the specified bounding box, with the edges of the bounding box being inclusive. - *This function is inlined for runtime optimization. */ + /** + * @brief Check if the node is within the bounding box. + * + * @param node the id of the node. + * @param bounding_box is a 2D rectangle that defines the bounding area. + * @note To return true, the RRNode must be completely contained within the specified bounding box, + * with the edges of the bounding box being inclusive. + */ + inline bool node_is_inside_bounding_box(RRNodeId node, vtr::Rect bounding_box) const { return (node_xhigh(node) <= bounding_box.xmax() && node_xlow(node) >= bounding_box.xmin() @@ -239,26 +317,35 @@ class RRGraphView { && node_ylow(node) >= bounding_box.ymin()); } - /** @brief Check if x is within x-range spanned by the node, inclusive of its endpoints. This function is inlined for runtime optimization. */ + /** @brief Check if x is within x-range spanned by the node, inclusive of its endpoints. + * @param x the coordinate to be checked + * @param node the id of the node + * @return a boolean flag indicating whether the input x falls within the x-range of the node + */ inline bool x_in_node_range(int x, RRNodeId node) const { return !(x < node_xlow(node) || x > node_xhigh(node)); } - /** @brief Check if y is within y-range spanned by the node, inclusive of its endpoints. This function is inlined for runtime optimization. */ + /** @brief Check if y is within y-range spanned by the node, inclusive of its endpoints. + * @param y the coordinate to be checked + * @param node the id of the node + * @return a boolean flag indicating whether the input y falls within the y-range of the node + */ inline bool y_in_node_range(int y, RRNodeId node) const { return !(y < node_ylow(node) || y > node_yhigh(node)); } - /** @brief Get string of information about routing resource node. The string will contain the following information. + /** @brief Get string of information about routing resource node. + * @param node the id of the node + * @return a string that contains the following information: * type, side, x_low, x_high, y_low, y_high, length, direction, segment_name, layer num - * This function is inlined for runtime optimization. */ inline const std::string node_coordinate_to_string(RRNodeId node) const { std::string start_x; //start x-coordinate std::string start_y; //start y-coordinate std::string end_x; //end x-coordinate std::string end_y; //end y-coordinate - std::string start_layer_str; //layer number + std::string start_layer_str; //layer number std::string end_layer_str; //layer number std::string arrow; //direction arrow std::string coordinate_string = node_type_string(node); //write the component's type as a routing resource node @@ -276,7 +363,7 @@ class RRGraphView { coordinate_string += ")"; //add the side of the routing resource node // For OPINs and IPINs the starting and ending coordinate are identical, so we can just arbitrarily assign the start to larger values // and the end to the lower coordinate - start_x = " (" + std::to_string(node_xhigh(node)) + ","; //start and end coordinates are the same for OPINs and IPINs + start_x = " (" + std::to_string(node_xhigh(node)) + ","; //start and end coordinates are the same for OPINs and IPINs start_y = std::to_string(node_yhigh(node)) + ","; start_layer_str = std::to_string(node_layer_num) + ")"; } else if (node_type(node) == SOURCE || node_type(node) == SINK) { @@ -293,7 +380,7 @@ class RRGraphView { arrow = "->"; //we will point the coordinates from start to finish, left to right - if (node_direction(node) == Direction::DEC) { //signal travels along decreasing direction + if (node_direction(node) == Direction::DEC) { //signal travels along decreasing direction start_x = " (" + std::to_string(node_xhigh(node)) + ","; //start coordinates have large value start_y = std::to_string(node_yhigh(node)) + ","; @@ -316,144 +403,203 @@ class RRGraphView { } } - coordinate_string += start_x + start_y + start_layer_str; //Write the starting coordinates - coordinate_string += arrow; //Indicate the direction - coordinate_string += end_x + end_y + end_layer_str; //Write the end coordinates + coordinate_string += start_x + start_y + start_layer_str; //Write the starting coordinates + coordinate_string += arrow; //Indicate the direction + coordinate_string += end_x + end_y + end_layer_str; //Write the end coordinates return coordinate_string; } - /** @brief Check whether a routing node is on a specific side. This function is inlined for runtime optimization. */ + /** @brief Check whether a routing node is on a specific side. + * @param node the id of the node + * @param side the side to be checked + * @return a boolean flag indicating whether a routing node is on the given side + */ inline bool is_node_on_specific_side(RRNodeId node, e_side side) const { return node_storage_.is_node_on_specific_side(node, side); } - /** @brief Get the side string of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the side string of a routing resource node. + * @param node the id of the node + * @return the string representing the side of the node. + */ inline const char* node_side_string(RRNodeId node) const { return node_storage_.node_side_string(node); } - /** @brief Get the node id of the clock network virtual sink */ + /** @brief Get the node id of the clock network virtual sink + * @param clock_network_name the net name of the clock + * @return the node id of the clock net + */ inline RRNodeId virtual_clock_network_root_idx(const char* clock_network_name) const { return node_storage_.virtual_clock_network_root_idx(clock_network_name); } /** * @brief Checks if the specified RRNode ID is a virtual sink for a clock network. - * @param id The ID of an RRNode. - * @return True if the node with the given ID is a virtual sink for a clock network, false otherwise. + * @param id the id of an RRNode. + * @return a boolean flag indicating whether the node is a virtual clock. */ inline bool is_virtual_clock_network_root(RRNodeId id) const { return node_storage_.is_virtual_clock_network_root(id); } - /** @brief Get the switch id that represents the iedge'th outgoing edge from a specific node - * TODO: We may need to revisit this API and think about higher level APIs, like ``switch_delay()`` + /** @brief Get the switch id that represents the iedge'th outgoing edge from a specific node. + * @param id the id of the node. + * @param iedge the outgoing edge index of the node. + * @return the id of the switch used for the specified edge. + * @todo We may need to revisit this API and think about higher level APIs, like ``switch_delay()``. **/ inline short edge_switch(RRNodeId id, t_edge_size iedge) const { return node_storage_.edge_switch(id, iedge); } - /** @brief Get the source node for the specified edge. */ + /** @brief Get the source node for the specified edge. + * @param edge_id the id of the edge. + * @return the id of source node for the given edge. + */ inline RRNodeId edge_src_node(const RREdgeId edge_id) const { return node_storage_.edge_src_node(edge_id); } /** @brief Get the destination node for the iedge'th edge from specified RRNodeId. - * This method should generally not be used, and instead first_edge and - * last_edge should be used.*/ + * @param id the id of the node + * @param iedge the iedge'th edge of the node + * @return destination node id of the specified edge + * @note This method should generally not be used, and instead first_edge and + * last_edge should be used.*/ inline RRNodeId edge_sink_node(RRNodeId id, t_edge_size iedge) const { return node_storage_.edge_sink_node(id, iedge); } - /** @brief Detect if the edge is a configurable edge (controlled by a programmable routing multipler or a tri-state switch). */ + /** @brief Detect if the edge is a configurable edge + * @param id the id of the node + * @param iedge the id of the edge + * @return a boolean flag indicating whether the edge is a configurable edge + * @note a configurable edge can be controlled by a programmable routing multipler or a tri-state switch. + */ inline bool edge_is_configurable(RRNodeId id, t_edge_size iedge) const { return node_storage_.edge_is_configurable(id, iedge, rr_switch_inf_); } - /** @brief Get the number of configurable edges. This function is inlined for runtime optimization. */ + /** @brief Get the number of configurable edges. + * @param node the id of the node + * @return the number of configurable edges + */ inline t_edge_size num_configurable_edges(RRNodeId node) const { return node_storage_.num_configurable_edges(node, rr_switch_inf_); } - /** @brief Get the number of non-configurable edges. This function is inlined for runtime optimization. */ + /** @brief Get the number of non-configurable edges. + * @param node the id of the node. + * @return the number of non-configurable edges. + */ inline t_edge_size num_non_configurable_edges(RRNodeId node) const { return node_storage_.num_non_configurable_edges(node, rr_switch_inf_); } - /** @brief A configurable edge represents a programmable switch between routing resources, which could be - * a multiplexer - * a tri-state buffer - * a pass gate - * This API gets ID range for configurable edges. This function is inlined for runtime optimization. */ + /** @brief Get ID range for configurable edges. + * @param node the id of the node. + * @return id range of the configuranble edges. + * @note A configurable edge represents a programmable switch between routing resources, which could be + * - a multiplexer + * - a tri-state buffer + * - a pass gate + */ inline edge_idx_range configurable_edges(RRNodeId node) const { return vtr::make_range(edge_idx_iterator(0), edge_idx_iterator(node_storage_.num_edges(node) - num_non_configurable_edges(node))); } - /** @brief A non-configurable edge represents a hard-wired connection between routing resources, which could be - * a non-configurable buffer that can not be turned off - * a short metal connection that can not be turned off - * This API gets ID range for non-configurable edges. This function is inlined for runtime optimization. */ + /** @brief Get ID range for non-configurable edges. + * @param node the id of the node. + * @return the id range for non-configurable edges. + * @note A non-configurable edge represents a hard-wired connection between routing resources, which could be + * - a non-configurable buffer that can not be turned off + * - a short metal connection that can not be turned off + */ inline edge_idx_range non_configurable_edges(RRNodeId node) const { return vtr::make_range(edge_idx_iterator(node_storage_.num_edges(node) - num_non_configurable_edges(node)), edge_idx_iterator(num_edges(node))); } - /** @brief Get outgoing edges for a node. - * This API is designed to enable range-based loop to walk through the outgoing edges of a node - * Example: - * RRGraphView rr_graph; // A dummy rr_graph for a short example - * RRNodeId node; // A dummy node for a short example - * for (RREdgeId edge : rr_graph.edges(node)) { + /** + * @brief Retrieve the outgoing edges for a specified node. This API is designed to facilitate range-based loops for traversing the outgoing edges of a node. + * @param id the id of the node + * @return the range of outgoing edges for the given node + * @example + * RRGraphView rr_graph; // A dummy rr_graph for a short example + * RRNodeId node; // A dummy node for a short example + * for (RREdgeId edge : rr_graph.edges(node)) { * // Do something with the edge - * } + * } */ inline edge_idx_range edges(const RRNodeId& id) const { return vtr::make_range(edge_idx_iterator(0), edge_idx_iterator(num_edges(id))); } - /** @brief Get the number of edges. This function is inlined for runtime optimization. */ + /** @brief Get the number of edges. + * @param node the id of the node + * @return the number of edges + */ inline t_edge_size num_edges(RRNodeId node) const { return node_storage_.num_edges(node); } - /** @brief The ptc_num carries different meanings for different node types - * (true in VPR RRG that is currently supported, may not be true in customized RRG) - * CHANX or CHANY: the track id in routing channels - * OPIN or IPIN: the index of pins in the logic block data structure - * SOURCE and SINK: the class id of a pin (indicating logic equivalence of pins) in the logic block data structure - * @note - * This API is very powerful and developers should not use it unless it is necessary, - * e.g the node type is unknown. If the node type is known, the more specific routines, `node_pin_num()`, - * `node_track_num()`and `node_class_num()`, for different types of nodes should be used.*/ + /** + * @brief Retrieve the `ptc_num` of a routing resource node. + * @note ptc_num (Pin, Track, or Class Number) allows for distinguishing overlapping routing elements that occupy the same (x, y) coordinate, ensuring they can be uniquely identified and managed without confusion. For instance, several routing wires or pins might overlap physically, but their ptc_num differentiates them. + * @note The meaning of `ptc_num` varies depending on the node type (relevant to VPR RRG, may not apply to custom RRGs): + * - **CHANX/CHANY**: Represents the track ID in routing channels. + * - **OPIN/IPIN**: Refers to the pin index within the logic block data structure. + * - **SOURCE/SINK**: Denotes the class ID of a pin, indicating logic equivalence in the logic block data structure. + * + * @warning This API is highly versatile and should only be used when necessary (e.g., when the node type is unknown). + * If the node type is known, prefer using more specific APIs such as `node_pin_num()`, `node_track_num()`, + * or `node_class_num()` based on the node type. + */ inline int node_ptc_num(RRNodeId node) const { return node_storage_.node_ptc_num(node); } - /** @brief Get the pin num of a routing resource node. This is designed for logic blocks, - * which are IPIN and OPIN nodes. This function is inlined for runtime optimization. */ + /** @brief Get the pin num of a routing resource node (IPIN and OPIN nodes) + * @param node the id of the node. + * @return the pin num of the specified node. + * @note This function is intended for logic blocks and should only be used with IPIN or OPIN nodes. + */ inline int node_pin_num(RRNodeId node) const { return node_storage_.node_pin_num(node); } - /** @brief Get the track num of a routing resource node. This is designed for routing tracks, - * which are CHANX and CHANY nodes. This function is inlined for runtime optimization. */ + /** @brief Get the track num of a routing resource node. + * @param node the id of the node. + * @return the track num of the node. + * @note This function should only be used with CHANX or CHANY nodes. + */ inline int node_track_num(RRNodeId node) const { return node_storage_.node_track_num(node); } - /** @brief Get the class num of a routing resource node. This is designed for routing source and sinks, - * which are SOURCE and SINK nodes. This function is inlined for runtime optimization. */ + /** @brief Get the class num of a routing resource node. + * @param node the id of the node. + * @return the class id of a pin (indicating logic equivalence of pins) in the logic block data structure. + * @note This function should only be used with SOURCE or SINK nodes. + */ inline int node_class_num(RRNodeId node) const { return node_storage_.node_class_num(node); } - /** @brief Get the cost index of a routing resource node. This function is inlined for runtime optimization. */ + /** @brief Get the cost index of a routing resource node. + * @param node the id of the node. + * @return cost index of the specified node. + */ RRIndexedDataId node_cost_index(RRNodeId node) const { return node_storage_.node_cost_index(node); } - /** @brief Return detailed routing segment information with a given id* @note The routing segments here may not be exactly same as those defined in architecture file. They have been + + /** @brief Return detailed routing segment information of a specified segment + * @param seg_id the id of the segment + * @return detailed information of the segment + * @note The routing segments here may not be exactly same as those defined in architecture file. They have been * adapted to fit the context of routing resource graphs. */ - inline const t_segment_inf& rr_segments(RRSegmentId seg_id) const { return rr_segments_[seg_id]; } @@ -466,8 +612,10 @@ class RRGraphView { return rr_segments_; } - /** @brief Return the switch information that is categorized in the rr_switch_inf with a given id - * rr_switch_inf is created to minimize memory footprint of RRGraph class + /** @brief Return the switch information that is categorized in the rr_switch_inf with a given id. + * @param switch_id the id of a rr switch. + * @return all the important information about an rr switch type. + * @note rr_switch_inf is created to minimize memory footprint of RRGraph class. * While the RRG could contain millions (even much larger) of edges, there are only * a limited number of types of switches. * Hence, we use a flyweight pattern to store switch-related information that differs @@ -502,18 +650,20 @@ class RRGraphView { return node_storage_; } - /** .. warning:: The Metadata should stay as an independent data structure than rest of the internal data, + /** @brief Return the metadata of rr nodes + * @warning The Metadata should stay as an independent data structure than rest of the internal data, * e.g., node_lookup! */ MetadataStorage rr_node_metadata_data() const { return rr_node_metadata_; } - + /** @brief Return the metadata of rr edges + */ MetadataStorage> rr_edge_metadata_data() const { return rr_edge_metadata_; } public: /* Validators */ - /** brief Validate that edge data is partitioned correctly + /** @brief Validate that edge data is partitioned correctly * @note This function is used to validate the correctness of the routing resource graph in terms * of graph attributes. Strongly recommend to call it when you finish the building a routing resource * graph. If you need more advance checks, which are related to architecture features, you should @@ -525,43 +675,43 @@ class RRGraphView { /* -- Internal data storage -- */ /* Note: only read-only object or data structures are allowed!!! */ private: - /* node-level storage including edge storages */ + /// node-level storage including edge storages const t_rr_graph_storage& node_storage_; - /* Fast look-up for rr nodes */ + /// Fast look-up for rr nodes const RRSpatialLookup& node_lookup_; - /** .. warning:: The Metadata should stay as an independent data structure than rest of the internal data, - * e.g., node_lookup! */ - /* Metadata is an extra data on rr-nodes and edges, respectively, that is not used by vpr - * but simply passed through the flow so that it can be used by downstream tools. - * The main (perhaps only) current use of this metadata is the fasm tool of symbiflow, - * which needs extra metadata on which programming bits control which switch in order to produce a bitstream.*/ + /** * @brief Attributes for each rr_node. * - * key: rr_node index - * value: map of - */ + * - key: rr_node index + * - value: map of + * @warning The Metadata should stay as an independent data structure than rest of the internal data, + * e.g., node_lookup! + * @note Metadata is an extra data on rr-nodes and edges, respectively, that is not used by vpr + * but simply passed through the flow so that it can be used by downstream tools. + * The main (perhaps only) current use of this metadata is the fasm tool of symbiflow, + * which needs extra metadata on which programming bits control which switch in order to produce a bitstream.*/ const MetadataStorage& rr_node_metadata_; /** * @brief Attributes for each rr_edge * - * key: - * iswitch: Index of the switch type used to go from this rr_node to + * - key: + * - iswitch: Index of the switch type used to go from this rr_node to * the next one in the routing. OPEN if there is no next node * (i.e. this node is the last one (a SINK) in a branch of the * net's routing). - * value: map of + * - value: map of */ const MetadataStorage>& rr_edge_metadata_; - /* rr_indexed_data_ and rr_segments_ are needed to lookup the segment information in node_coordinate_to_string() */ + /// rr_indexed_data_ and rr_segments_ are needed to lookup the segment information in node_coordinate_to_string() const vtr::vector& rr_indexed_data_; - /* RC data for nodes. This is a flyweight data */ + /// RC data for nodes. This is a flyweight data const std::vector& rr_rc_data_; - /* Segment info for rr nodes */ + /// Segment info for rr nodes const vtr::vector& rr_segments_; - /* switch info for rr nodes */ + /// switch info for rr nodes const vtr::vector& rr_switch_inf_; }; From 54a56d5f898abf074013b468a20c4f4ad2ce3466 Mon Sep 17 00:00:00 2001 From: Lin Date: Tue, 24 Sep 2024 18:12:34 +0800 Subject: [PATCH 2/7] checked --- libs/librrgraph/src/base/rr_graph_builder.h | 8 +- libs/librrgraph/src/base/rr_graph_view.h | 244 ++++++-------------- 2 files changed, 81 insertions(+), 171 deletions(-) diff --git a/libs/librrgraph/src/base/rr_graph_builder.h b/libs/librrgraph/src/base/rr_graph_builder.h index 2ad5cfba50..3a72a9e8d9 100644 --- a/libs/librrgraph/src/base/rr_graph_builder.h +++ b/libs/librrgraph/src/base/rr_graph_builder.h @@ -38,7 +38,7 @@ class RRGraphBuilder { t_rr_graph_storage& rr_nodes(); /** @brief Return a writable object for update the fast look-up of rr_node */ RRSpatialLookup& node_lookup(); - /** .. warning:: The Metadata should stay as an independent data structure than rest of the internal data, + /** @warning The Metadata should stay as an independent data structure than rest of the internal data, * e.g., node_lookup! */ /** @brief Return a writable object for the meta data on the nodes */ MetadataStorage& rr_node_metadata(); @@ -85,7 +85,7 @@ class RRGraphBuilder { return segment_id; } /** TODO @brief Return a writable list of all the rr_segments - * .. warning:: It is not recommended to use this API unless you have to. The API may be deprecated later, and future APIs will designed to return a specific data from the rr_segments. + * @warning It is not recommended to use this API unless you have to. The API may be deprecated later, and future APIs will designed to return a specific data from the rr_segments. */ inline vtr::vector& rr_segments() { return rr_segments_; @@ -104,7 +104,7 @@ class RRGraphBuilder { return switch_id; } /** TODO @brief Return a writable list of all the rr_switches - * .. warning:: It is not recommended to use this API unless you have to. The API may be deprecated later, and future APIs will designed to return a specific data from the rr_switches. + * @warning It is not recommended to use this API unless you have to. The API may be deprecated later, and future APIs will designed to return a specific data from the rr_switches. */ inline vtr::vector& rr_switch() { return rr_switch_inf_; @@ -388,7 +388,7 @@ class RRGraphBuilder { /* Detailed information about the switches, which are used in the RRGraph */ vtr::vector rr_switch_inf_; - /** .. warning:: The Metadata should stay as an independent data structure than rest of the internal data, + /** @warning The Metadata should stay as an independent data structure than rest of the internal data, * e.g., node_lookup! */ /* Metadata is an extra data on rr-nodes and edges, respectively, that is not used by vpr * but simply passed through the flow so that it can be used by downstream tools. diff --git a/libs/librrgraph/src/base/rr_graph_view.h b/libs/librrgraph/src/base/rr_graph_view.h index bdcc1c1601..1b9e9b27da 100644 --- a/libs/librrgraph/src/base/rr_graph_view.h +++ b/libs/librrgraph/src/base/rr_graph_view.h @@ -1,37 +1,41 @@ #ifndef RR_GRAPH_VIEW_H #define RR_GRAPH_VIEW_H -#include "rr_graph_builder.h" -#include "rr_node.h" -#include "physical_types.h" /** - * @brief The RRGraphView encapsulates a read-only routing resource graph, providing clients with tailored frame views of the object. The RRGraphView represents the full frame view of the routing resource graph, offering several advantages: - - * - It reduces the memory footprint for each client. - * - It minimizes the need for extensive API changes, as each frame view delivers ad-hoc APIs suited to the specific needs of individual clients. - * + * @file + * @brief The RRGraphView encapsulates a read-only routing resource graph, providing clients with tailored frame views of the object. * + * The RRGraphView represents the full frame view of the routing resource graph, offering several advantages: + * - Reduces the memory footprint for each client. + * - Minimizes the need for extensive API changes, as each frame view delivers ad-hoc APIs suited to the specific needs of individual clients. * * A unified object that includes pointers to: - * - Node storage - * - @todo Edge storage - * - @todo Node PTC storage - * - @todo Node fan-in storage - * - RR node indices + * - Node storage + * \internal + * - TODO: Edge storage + * - TODO: Node PTC storage + * - TODO: Node fan-in storage + * \endinternal + * - RR node indices * * @note The RRGraphView does not own the storage. It provides a virtual * read-only protocol for: - * - Placer - * - Router - * - Timing analyzer - * - GUI + * - Placer + * - Router + * - Timing analyzer + * - GUI * - * @todo More compact frame views will be created, such as: + * \internal + * TODO: More compact frame views will be created, such as: * - A mini frame view: Contains only nodes and edges, representing the * connectivity of the graph. * - A geometry frame view: An extended mini frame view with node-level * attributes, particularly geometry information (type, x, y, etc.). + * \endinternal */ +#include "rr_graph_builder.h" +#include "rr_node.h" +#include "physical_types.h" class RRGraphView { /* -- Constructors -- */ @@ -66,9 +70,8 @@ class RRGraphView { * To iterate over the nodes in an RRGraph, using a range-based loop is recommended. * * @code - * // Example: Iterate over all nodes - * // Strongly suggest using a read-only rr_graph object - * const RRGraph& rr_graph; + * + * // Strongly suggest using a read-only rr_graph object const RRGraph& rr_graph; * for (const RRNodeId& node : rr_graph.nodes()) { * // Do something with each node * } @@ -79,68 +82,51 @@ class RRGraphView { return vtr::StrongIdRange(RRNodeId(0), RRNodeId(num_nodes())); } - /** @brief Get number of nodes. - * @return the number of routing resource nodes + /** @brief Return number of routing resource nodes. */ inline size_t num_nodes() const { return node_storage_.size(); } /** @brief check whether the RR graph is currently empty - * @return a boolean flag that indicates if the RR graph is empty. */ inline bool empty() const { return node_storage_.empty(); } - /** @brief Get a range of RREdgeId's belonging to RRNodeId id. - * @param id the id of the node. - * @return a range of RREdgeIds - * @note If this range is empty, then RRNodeId id has no edges.*/ + /** @brief Return a range of RREdgeIds that belong to a specified node. + * @note If this range is empty, then the specified node has no edges.*/ inline vtr::StrongIdRange edge_range(RRNodeId id) const { return vtr::StrongIdRange(node_storage_.first_edge(id), node_storage_.last_edge(id)); } - /** @brief Get the type of a routing resource node. - * @param node the id of the node. - * @return the type of the routing resource node. + /** @brief Return the type of a specified node. */ inline t_rr_type node_type(RRNodeId node) const { return node_storage_.node_type(node); } /** - * @brief Retrieve the name assigned to a given node ID. - * - * @param node the id of the node. - * @return an optional pointer to the string representing the name if found, - * otherwise an empty optional. + * @brief Return the name of a specified node. * @note If no name is assigned, an empty optional is returned. */ std::optional node_name(RRNodeId node) const { return node_storage_.node_name(node); } - /** @brief Get the node type. - * @param node the id of the ndoe - * @return a string indicating the type of the source node + /** @brief Return a string indicating the type of the specified node. */ inline const char* node_type_string(RRNodeId node) const { return node_storage_.node_type_string(node); } - /** @brief Get the capacity of a routing resource node. - * @param node the id of the node - * @return capacity of the node + /** @brief Return the capacity of a specified node. */ inline short node_capacity(RRNodeId node) const { return node_storage_.node_capacity(node); } /** - * @brief Get the direction of a routing resource node. - * - * @param node the ID of the node. - * @return The direction of the node. + * @brief Return the direction of a specified node. * * @note Direction Categories: * - `Direction::INC`: Wire driver is positioned at the low-coordinate end of the wire. @@ -152,115 +138,87 @@ class RRGraphView { return node_storage_.node_direction(node); } - /** @brief Get the direction string of a routing resource node. - * @param node the id of the node - * @return a string indicating the direction + /** @brief Return the direction string of a specified node. */ inline const std::string& node_direction_string(RRNodeId node) const { return node_storage_.node_direction_string(node); } - /** @brief Get the capacitance of a routing resource node. - * @param node the id of the node - * @return the capacitance C of the routing resource node + /** @brief Return the capacitance of a specified node. */ inline float node_C(RRNodeId node) const { VTR_ASSERT(node_rc_index(node) < (short)rr_rc_data_.size()); return rr_rc_data_[node_rc_index(node)].C; } - /** @brief Get the resistance of a routing resource node. - * @param node the id of the node' - * @return the resistance R of the node + /** @brief Return the resistance of a specified node. */ inline float node_R(RRNodeId node) const { VTR_ASSERT(node_rc_index(node) < (short)rr_rc_data_.size()); return rr_rc_data_[node_rc_index(node)].R; } - /** @brief Get the rc_index of a routing resource node. - * @param node the id of the node - * @return the index of the node + /** @brief Return the rc_index of a specified node. */ inline int16_t node_rc_index(RRNodeId node) const { return node_storage_.node_rc_index(node); } - /** @brief Get the fan in count of a routing resource node. - * @param node the id of the node - * @return the fan in count of the node + /** @brief Return the fan in count of a specified node. */ inline t_edge_size node_fan_in(RRNodeId node) const { return node_storage_.fan_in(node); } - /** @brief Get the minimum x-coordinate of a routing resource node. - * @param node the id of the node - * @return the minimum x-coordinate of the node + /** @brief Return the minimum x-coordinate of a specified node. */ inline short node_xlow(RRNodeId node) const { return node_storage_.node_xlow(node); } - /** @brief Get the maximum x-coordinate of a routing resource node. - * @param node the id of the node - * @return the maximum x-coordinate of the node + /** @brief Return the maximum x-coordinate of a specified node. */ inline short node_xhigh(RRNodeId node) const { return node_storage_.node_xhigh(node); } - /** @brief Get the minimum y-coordinate of a routing resource node. - * @param node the id of the node - * @return the minimum y-coordinate of the node + /** @brief Return the minimum y-coordinate of a specified node. */ inline short node_ylow(RRNodeId node) const { return node_storage_.node_ylow(node); } - /** @brief Get the maximum y-coordinate of a routing resource node. - * @param node the id of the node - * @return the maximum y-coordinate of the node + /** @brief Return the maximum y-coordinate of a specified node. */ inline short node_yhigh(RRNodeId node) const { return node_storage_.node_yhigh(node); } - /** @brief Get the layer num of a routing resource node. - * @param node the id of the node - * @return the layer number of the node + /** @brief Return the layer num of a specified node. */ inline short node_layer(RRNodeId node) const { return node_storage_.node_layer(node); } - /** @brief Get the ptc number twist of a routing resource node. - * @param node the id of the node - * @return the twist number of the node + /** @brief Return the ptc number twist of a specified node. */ inline short node_ptc_twist(RRNodeId node) const { return node_storage_.node_ptc_twist(node); } - /** @brief Get the first outgoing edge of resource node. - * @param node the id of the node - * @return the edge id of the first outgoing edge + /** @brief Return the first outgoing edge of a specified node. */ inline RREdgeId node_first_edge(RRNodeId node) const { return node_storage_.first_edge(node); } - /** @brief Get the last outgoing edge of resource node. - * @param node the id of the node - * @return the edge id of the last outgoing edge + /** @brief Return the last outgoing edge of a specified node. */ inline RREdgeId node_last_edge(RRNodeId node) const { return node_storage_.last_edge(node); } - /** @brief Get the length (number of grid tile units spanned by the wire, including the endpoints) of a routing resource node. - * @param node the id of the node - * @return the length spanned by the rr node + /** @brief Return the length (number of grid tile units spanned by the wire, including the endpoints) of a specified node. * @note node_length() only applies to CHANX or CHANY and is always a positive number */ inline int node_length(RRNodeId node) const { @@ -273,9 +231,7 @@ class RRGraphView { return length; } - /** @brief Check if routing resource node is initialized. - * @param node the id of the node. - * @return a boolean flag indicating whether the node is initialized or not. + /** @brief Check if a routing resource node is initialized. */ inline bool node_is_initialized(RRNodeId node) const { return !((node_type(node) == NUM_RR_TYPES) @@ -284,10 +240,6 @@ class RRGraphView { } /** @brief Check if two routing resource nodes are adjacent (must be a CHANX and a CHANY). - - * @param chanx_node the id of the node to be compared - * @param chany_node the id of the node to be compared - * @return a boolean flag indicating whether the two nodes are adjacent * @note This function performs error checking by determining whether two nodes are physically adjacent based on their geometry. It does not verify the routing edges to confirm if a connection is feasible within the current routing graph. */ inline bool nodes_are_adjacent(RRNodeId chanx_node, RRNodeId chany_node) const { @@ -305,7 +257,7 @@ class RRGraphView { * @brief Check if the node is within the bounding box. * * @param node the id of the node. - * @param bounding_box is a 2D rectangle that defines the bounding area. + * @param bounding_box a 2D rectangle that defines the bounding area. * @note To return true, the RRNode must be completely contained within the specified bounding box, * with the edges of the bounding box being inclusive. */ @@ -317,27 +269,20 @@ class RRGraphView { && node_ylow(node) >= bounding_box.ymin()); } - /** @brief Check if x is within x-range spanned by the node, inclusive of its endpoints. - * @param x the coordinate to be checked - * @param node the id of the node - * @return a boolean flag indicating whether the input x falls within the x-range of the node + /** @brief Check if x is within x-range spanned by a specified node, inclusive of its endpoints. */ inline bool x_in_node_range(int x, RRNodeId node) const { return !(x < node_xlow(node) || x > node_xhigh(node)); } - /** @brief Check if y is within y-range spanned by the node, inclusive of its endpoints. - * @param y the coordinate to be checked - * @param node the id of the node - * @return a boolean flag indicating whether the input y falls within the y-range of the node + /** @brief Check if y is within y-range spanned by a specified node, inclusive of its endpoints. */ inline bool y_in_node_range(int y, RRNodeId node) const { return !(y < node_ylow(node) || y > node_yhigh(node)); } - /** @brief Get string of information about routing resource node. - * @param node the id of the node - * @return a string that contains the following information: + /** @brief Return string of information about a specified node. + * @note The returned string can contain the following information: * type, side, x_low, x_high, y_low, y_high, length, direction, segment_name, layer num */ inline const std::string node_coordinate_to_string(RRNodeId node) const { @@ -409,59 +354,50 @@ class RRGraphView { return coordinate_string; } - /** @brief Check whether a routing node is on a specific side. - * @param node the id of the node - * @param side the side to be checked - * @return a boolean flag indicating whether a routing node is on the given side + /** @brief Check whether a routing resource node is on a specific side. */ inline bool is_node_on_specific_side(RRNodeId node, e_side side) const { return node_storage_.is_node_on_specific_side(node, side); } - /** @brief Get the side string of a routing resource node. - * @param node the id of the node - * @return the string representing the side of the node. + /** @brief Return the side string of a routing resource node. */ inline const char* node_side_string(RRNodeId node) const { return node_storage_.node_side_string(node); } - /** @brief Get the node id of the clock network virtual sink - * @param clock_network_name the net name of the clock - * @return the node id of the clock net + /** @brief Return the node id of the clock network virtual sink */ inline RRNodeId virtual_clock_network_root_idx(const char* clock_network_name) const { return node_storage_.virtual_clock_network_root_idx(clock_network_name); } /** - * @brief Checks if the specified RRNode ID is a virtual sink for a clock network. - * @param id the id of an RRNode. - * @return a boolean flag indicating whether the node is a virtual clock. + * @brief Checks if the specified node is a virtual sink for a clock network. */ inline bool is_virtual_clock_network_root(RRNodeId id) const { return node_storage_.is_virtual_clock_network_root(id); } - /** @brief Get the switch id that represents the iedge'th outgoing edge from a specific node. + /** @brief Return the switch id that represents the iedge'th outgoing edge from a specific node. * @param id the id of the node. * @param iedge the outgoing edge index of the node. - * @return the id of the switch used for the specified edge. + * @return the id of the switch used for the specified edge. + * \internal * @todo We may need to revisit this API and think about higher level APIs, like ``switch_delay()``. - **/ + * \endinternal + */ inline short edge_switch(RRNodeId id, t_edge_size iedge) const { return node_storage_.edge_switch(id, iedge); } - /** @brief Get the source node for the specified edge. - * @param edge_id the id of the edge. - * @return the id of source node for the given edge. + /** @brief Return the source node for the specified edge. */ inline RRNodeId edge_src_node(const RREdgeId edge_id) const { return node_storage_.edge_src_node(edge_id); } - /** @brief Get the destination node for the iedge'th edge from specified RRNodeId. + /** @brief Return the destination node for the iedge'th edge from specified RRNodeId. * @param id the id of the node * @param iedge the iedge'th edge of the node * @return destination node id of the specified edge @@ -472,46 +408,34 @@ class RRGraphView { } /** @brief Detect if the edge is a configurable edge - * @param id the id of the node - * @param iedge the id of the edge - * @return a boolean flag indicating whether the edge is a configurable edge - * @note a configurable edge can be controlled by a programmable routing multipler or a tri-state switch. + * @note A configurable edge represents a programmable switch between routing resources, which could be + * - a multiplexer + * - a tri-state buffer + * - a pass gate */ inline bool edge_is_configurable(RRNodeId id, t_edge_size iedge) const { return node_storage_.edge_is_configurable(id, iedge, rr_switch_inf_); } - /** @brief Get the number of configurable edges. - * @param node the id of the node - * @return the number of configurable edges + /** @brief Return the number of configurable edges. */ inline t_edge_size num_configurable_edges(RRNodeId node) const { return node_storage_.num_configurable_edges(node, rr_switch_inf_); } - /** @brief Get the number of non-configurable edges. - * @param node the id of the node. - * @return the number of non-configurable edges. + /** @brief Return the number of non-configurable edges. */ inline t_edge_size num_non_configurable_edges(RRNodeId node) const { return node_storage_.num_non_configurable_edges(node, rr_switch_inf_); } - /** @brief Get ID range for configurable edges. - * @param node the id of the node. - * @return id range of the configuranble edges. - * @note A configurable edge represents a programmable switch between routing resources, which could be - * - a multiplexer - * - a tri-state buffer - * - a pass gate + /** @brief Return ID range for configurable edges. */ inline edge_idx_range configurable_edges(RRNodeId node) const { return vtr::make_range(edge_idx_iterator(0), edge_idx_iterator(node_storage_.num_edges(node) - num_non_configurable_edges(node))); } - /** @brief Get ID range for non-configurable edges. - * @param node the id of the node. - * @return the id range for non-configurable edges. + /** @brief Return ID range for non-configurable edges. * @note A non-configurable edge represents a hard-wired connection between routing resources, which could be * - a non-configurable buffer that can not be turned off * - a short metal connection that can not be turned off @@ -535,9 +459,7 @@ class RRGraphView { return vtr::make_range(edge_idx_iterator(0), edge_idx_iterator(num_edges(id))); } - /** @brief Get the number of edges. - * @param node the id of the node - * @return the number of edges + /** @brief Return the number of edges. */ inline t_edge_size num_edges(RRNodeId node) const { return node_storage_.num_edges(node); @@ -559,44 +481,34 @@ class RRGraphView { return node_storage_.node_ptc_num(node); } - /** @brief Get the pin num of a routing resource node (IPIN and OPIN nodes) - * @param node the id of the node. - * @return the pin num of the specified node. + /** @brief Return the pin num of a routing resource node. * @note This function is intended for logic blocks and should only be used with IPIN or OPIN nodes. */ inline int node_pin_num(RRNodeId node) const { return node_storage_.node_pin_num(node); } - /** @brief Get the track num of a routing resource node. - * @param node the id of the node. - * @return the track num of the node. + /** @brief Return the track num of a routing resource node. * @note This function should only be used with CHANX or CHANY nodes. */ inline int node_track_num(RRNodeId node) const { return node_storage_.node_track_num(node); } - /** @brief Get the class num of a routing resource node. - * @param node the id of the node. - * @return the class id of a pin (indicating logic equivalence of pins) in the logic block data structure. + /** @brief Return the class num of a routing resource node. * @note This function should only be used with SOURCE or SINK nodes. */ inline int node_class_num(RRNodeId node) const { return node_storage_.node_class_num(node); } - /** @brief Get the cost index of a routing resource node. - * @param node the id of the node. - * @return cost index of the specified node. + /** @brief Return the cost index of a routing resource node. */ RRIndexedDataId node_cost_index(RRNodeId node) const { return node_storage_.node_cost_index(node); } /** @brief Return detailed routing segment information of a specified segment - * @param seg_id the id of the segment - * @return detailed information of the segment * @note The routing segments here may not be exactly same as those defined in architecture file. They have been * adapted to fit the context of routing resource graphs. */ @@ -612,9 +524,7 @@ class RRGraphView { return rr_segments_; } - /** @brief Return the switch information that is categorized in the rr_switch_inf with a given id. - * @param switch_id the id of a rr switch. - * @return all the important information about an rr switch type. + /** @brief Return the switch information that is categorized in the rr_switch_inf with a given id. * @note rr_switch_inf is created to minimize memory footprint of RRGraph class. * While the RRG could contain millions (even much larger) of edges, there are only * a limited number of types of switches. From a3e4c4cbb2591593378ef9d094458fa7c23a8a6c Mon Sep 17 00:00:00 2001 From: Lin Date: Tue, 24 Sep 2024 18:26:31 +0800 Subject: [PATCH 3/7] final check --- libs/librrgraph/src/base/rr_graph_builder.h | 12 ++++++++++-- libs/librrgraph/src/base/rr_graph_view.h | 8 ++++---- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/libs/librrgraph/src/base/rr_graph_builder.h b/libs/librrgraph/src/base/rr_graph_builder.h index 3a72a9e8d9..86dceaa2a6 100644 --- a/libs/librrgraph/src/base/rr_graph_builder.h +++ b/libs/librrgraph/src/base/rr_graph_builder.h @@ -84,7 +84,11 @@ class RRGraphBuilder { return segment_id; } - /** TODO @brief Return a writable list of all the rr_segments + /** + * \internal + * TODO + * \endinternal + * @brief Return a writable list of all the rr_segments * @warning It is not recommended to use this API unless you have to. The API may be deprecated later, and future APIs will designed to return a specific data from the rr_segments. */ inline vtr::vector& rr_segments() { @@ -103,7 +107,11 @@ class RRGraphBuilder { return switch_id; } - /** TODO @brief Return a writable list of all the rr_switches + /** + * \internal + * TODO + * \endinternal + * @brief Return a writable list of all the rr_switches * @warning It is not recommended to use this API unless you have to. The API may be deprecated later, and future APIs will designed to return a specific data from the rr_switches. */ inline vtr::vector& rr_switch() { diff --git a/libs/librrgraph/src/base/rr_graph_view.h b/libs/librrgraph/src/base/rr_graph_view.h index 1b9e9b27da..a4d6014158 100644 --- a/libs/librrgraph/src/base/rr_graph_view.h +++ b/libs/librrgraph/src/base/rr_graph_view.h @@ -138,7 +138,7 @@ class RRGraphView { return node_storage_.node_direction(node); } - /** @brief Return the direction string of a specified node. + /** @brief Return a string representing the direction of the specified node. */ inline const std::string& node_direction_string(RRNodeId node) const { return node_storage_.node_direction_string(node); @@ -281,7 +281,7 @@ class RRGraphView { return !(y < node_ylow(node) || y > node_yhigh(node)); } - /** @brief Return string of information about a specified node. + /** @brief Return a string containing information about the specified node. * @note The returned string can contain the following information: * type, side, x_low, x_high, y_low, y_high, length, direction, segment_name, layer num */ @@ -360,7 +360,7 @@ class RRGraphView { return node_storage_.is_node_on_specific_side(node, side); } - /** @brief Return the side string of a routing resource node. + /** @brief Return a string representing the side of a routing resource node. */ inline const char* node_side_string(RRNodeId node) const { return node_storage_.node_side_string(node); @@ -407,7 +407,7 @@ class RRGraphView { return node_storage_.edge_sink_node(id, iedge); } - /** @brief Detect if the edge is a configurable edge + /** @brief Check if the edge is a configurable edge * @note A configurable edge represents a programmable switch between routing resources, which could be * - a multiplexer * - a tri-state buffer From be2688f40e2a48d308584f744e686ca5500347d4 Mon Sep 17 00:00:00 2001 From: Lin Date: Wed, 25 Sep 2024 11:08:38 +0800 Subject: [PATCH 4/7] rewrite rrgraphview brief --- libs/librrgraph/src/base/rr_graph_builder.h | 4 ++-- libs/librrgraph/src/base/rr_graph_view.h | 20 ++++++++++++++------ 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/libs/librrgraph/src/base/rr_graph_builder.h b/libs/librrgraph/src/base/rr_graph_builder.h index 86dceaa2a6..cc367395bc 100644 --- a/libs/librrgraph/src/base/rr_graph_builder.h +++ b/libs/librrgraph/src/base/rr_graph_builder.h @@ -38,7 +38,7 @@ class RRGraphBuilder { t_rr_graph_storage& rr_nodes(); /** @brief Return a writable object for update the fast look-up of rr_node */ RRSpatialLookup& node_lookup(); - /** @warning The Metadata should stay as an independent data structure than rest of the internal data, + /** @warning The Metadata should stay as an independent data structure from the rest of the internal data, * e.g., node_lookup! */ /** @brief Return a writable object for the meta data on the nodes */ MetadataStorage& rr_node_metadata(); @@ -396,7 +396,7 @@ class RRGraphBuilder { /* Detailed information about the switches, which are used in the RRGraph */ vtr::vector rr_switch_inf_; - /** @warning The Metadata should stay as an independent data structure than rest of the internal data, + /** @warning The Metadata should stay as an independent data structure from the rest of the internal data, * e.g., node_lookup! */ /* Metadata is an extra data on rr-nodes and edges, respectively, that is not used by vpr * but simply passed through the flow so that it can be used by downstream tools. diff --git a/libs/librrgraph/src/base/rr_graph_view.h b/libs/librrgraph/src/base/rr_graph_view.h index a4d6014158..87af6ebedd 100644 --- a/libs/librrgraph/src/base/rr_graph_view.h +++ b/libs/librrgraph/src/base/rr_graph_view.h @@ -3,20 +3,28 @@ /** * @file - * @brief The RRGraphView encapsulates a read-only routing resource graph, providing clients with tailored frame views of the object. + * @brief The RRGraphView class provides a read-only interface to access the RRGraph. * - * The RRGraphView represents the full frame view of the routing resource graph, offering several advantages: - * - Reduces the memory footprint for each client. - * - Minimizes the need for extensive API changes, as each frame view delivers ad-hoc APIs suited to the specific needs of individual clients. + * The RRGraphView class offers tools like routing algorithms, graphics, and statistical analysis + * a read-only interface to the underlying RRGraph, which models the programmable routing fabric + * of the FPGA. The fundamental data structure of the RRGraph is a graph consisting of nodes + * (representing routing resources) and outgoing edges (representing connections between routing resources). * + * Each node and edge is enhanced with additional metadata, such as the location of the node within + * the chip and electrical parameters, to make algorithms more efficient, aid in drawing the chip, + * and estimate signal delays. RRGraphView ensures that tools can access this data safely without + * modifying the underlying structure. + * + * + * \internal * A unified object that includes pointers to: * - Node storage - * \internal * - TODO: Edge storage * - TODO: Node PTC storage * - TODO: Node fan-in storage - * \endinternal * - RR node indices + * \endinternal + * * @note The RRGraphView does not own the storage. It provides a virtual * read-only protocol for: From d31435ef0329d0bcb796459715c2309d0f768268 Mon Sep 17 00:00:00 2001 From: Lin Date: Wed, 25 Sep 2024 11:22:19 +0800 Subject: [PATCH 5/7] shorten --- libs/librrgraph/src/base/rr_graph_view.h | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/libs/librrgraph/src/base/rr_graph_view.h b/libs/librrgraph/src/base/rr_graph_view.h index 87af6ebedd..32e337946a 100644 --- a/libs/librrgraph/src/base/rr_graph_view.h +++ b/libs/librrgraph/src/base/rr_graph_view.h @@ -5,15 +5,14 @@ * @file * @brief The RRGraphView class provides a read-only interface to access the RRGraph. * - * The RRGraphView class offers tools like routing algorithms, graphics, and statistical analysis - * a read-only interface to the underlying RRGraph, which models the programmable routing fabric - * of the FPGA. The fundamental data structure of the RRGraph is a graph consisting of nodes - * (representing routing resources) and outgoing edges (representing connections between routing resources). + * The RRGraphView class provides a read-only interface for tools like the router, timing analyzer, + * and others that require access to the RRGraph without modifying it. The RRGraph models the + * programmable routing fabric of the FPGA as a graph, consisting of nodes (representing routing resources) + * and outgoing edges (representing connections between these resources). * - * Each node and edge is enhanced with additional metadata, such as the location of the node within - * the chip and electrical parameters, to make algorithms more efficient, aid in drawing the chip, - * and estimate signal delays. RRGraphView ensures that tools can access this data safely without - * modifying the underlying structure. + * Each node and edge is supplemented with additional metadata, such as the physical location within + * the chip and electrical properties, to optimize algorithm efficiency, aid in visualizing the chip layout, + * and estimate signal delays. * * * \internal From b0380c2ae25c650ddb74c331e63e217c56c650a0 Mon Sep 17 00:00:00 2001 From: Lin Date: Wed, 25 Sep 2024 11:41:27 +0800 Subject: [PATCH 6/7] reformat --- libs/librrgraph/src/base/rr_graph_view.h | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/libs/librrgraph/src/base/rr_graph_view.h b/libs/librrgraph/src/base/rr_graph_view.h index 32e337946a..e04fde9d15 100644 --- a/libs/librrgraph/src/base/rr_graph_view.h +++ b/libs/librrgraph/src/base/rr_graph_view.h @@ -3,14 +3,11 @@ /** * @file - * @brief The RRGraphView class provides a read-only interface to access the RRGraph. + * @brief The RRGraphView encapsulates a read-only routing resource graph as most clients (router, timing analyzer, etc.) only need to read a routing-resource graph. * - * The RRGraphView class provides a read-only interface for tools like the router, timing analyzer, - * and others that require access to the RRGraph without modifying it. The RRGraph models the + * The RRGraph models the * programmable routing fabric of the FPGA as a graph, consisting of nodes (representing routing resources) - * and outgoing edges (representing connections between these resources). - * - * Each node and edge is supplemented with additional metadata, such as the physical location within + * and outgoing edges (representing connections between these resources). Each node and edge is supplemented with additional metadata, such as the physical location within * the chip and electrical properties, to optimize algorithm efficiency, aid in visualizing the chip layout, * and estimate signal delays. * From 8f7c3a9257d2e130b1fea6223fc1c581d898ee0e Mon Sep 17 00:00:00 2001 From: Lin Date: Wed, 25 Sep 2024 14:54:39 +0800 Subject: [PATCH 7/7] fix small bug: brief sections don't show up in the html documentation --- doc/src/api/vpr/rr_graph.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/src/api/vpr/rr_graph.rst b/doc/src/api/vpr/rr_graph.rst index 44f8854859..b9d653bedb 100644 --- a/doc/src/api/vpr/rr_graph.rst +++ b/doc/src/api/vpr/rr_graph.rst @@ -7,7 +7,7 @@ RRGraphView .. doxygenfile:: rr_graph_view.h :project: librrgraph - :sections: detaileddescription + :sections: briefdescription detaileddescription func prototype user-defined public-func .. doxygenclass:: RRGraphView :project: librrgraph @@ -18,7 +18,7 @@ RRGraphBuilder .. doxygenfile:: rr_graph_builder.h :project: librrgraph - :sections: detaileddescription + :sections: briefdescription detaileddescription func prototype user-defined public-func .. doxygenclass:: RRGraphBuilder :project: librrgraph @@ -29,7 +29,7 @@ RRSpatialLookup .. doxygenfile:: rr_spatial_lookup.h :project: librrgraph - :sections: detaileddescription + :sections: briefdescription detaileddescription func prototype user-defined public-func .. doxygenclass:: RRSpatialLookup :project: librrgraph