diff --git a/doc/src/api/vpr/index.rst b/doc/src/api/vpr/index.rst index f8c915ee9bf..ba05b203396 100644 --- a/doc/src/api/vpr/index.rst +++ b/doc/src/api/vpr/index.rst @@ -8,3 +8,4 @@ VPR API contexts netlist + rr_graph diff --git a/doc/src/api/vpr/rr_graph.rst b/doc/src/api/vpr/rr_graph.rst new file mode 100644 index 00000000000..342885558ac --- /dev/null +++ b/doc/src/api/vpr/rr_graph.rst @@ -0,0 +1,37 @@ +====================== +Routing Resource Graph +====================== + +RRGraphView +----------- + +.. doxygenfile:: rr_graph_view.h + :project: vpr + :sections: detaileddescription + +.. doxygenclass:: RRGraphView + :project: vpr + :members: + +RRGraphBuilder +-------------- + +.. doxygenfile:: rr_graph_builder.h + :project: vpr + :sections: detaileddescription + +.. doxygenclass:: RRGraphBuilder + :project: vpr + :members: + +RRSpatialLookup +--------------- + +.. doxygenfile:: rr_spatial_lookup.h + :project: vpr + :sections: detaileddescription + +.. doxygenclass:: RRSpatialLookup + :project: vpr + :members: + diff --git a/vpr/src/device/rr_graph_builder.h b/vpr/src/device/rr_graph_builder.h index 4937cbe709a..fd722427521 100644 --- a/vpr/src/device/rr_graph_builder.h +++ b/vpr/src/device/rr_graph_builder.h @@ -1,20 +1,21 @@ #ifndef RR_GRAPH_BUILDER_H #define RR_GRAPH_BUILDER_H -#include "rr_graph_storage.h" -#include "rr_spatial_lookup.h" - -/* A data structure allows data modification on a routing resource graph +/** + * @file + * @brief This file defines the RRGraphBuilder data structure which allows data modification on a routing resource graph * - * Note that the builder does not own the storage - * It serves a virtual protocol for - * - node_storage: store the node list - * - node_lookup: store a fast look-up for the nodes + * The builder does not own the storage but it serves a virtual protocol for + * - node_storage: store the node list + * - node_lookup: store a fast look-up for the nodes * - * Note: - * - This is the only data structre allowed to modify a routing resource graph + * @note + * - This is the only data structure allowed to modify a routing resource graph * */ +#include "rr_graph_storage.h" +#include "rr_spatial_lookup.h" + class RRGraphBuilder { /* -- Constructors -- */ public: @@ -32,23 +33,26 @@ class RRGraphBuilder { /* -- Mutators -- */ public: - /* Return a writable object for rr_nodes */ + /** @brief Return a writable object for rr_nodes */ t_rr_graph_storage& node_storage(); - /* Return a writable object for update the fast look-up of rr_node */ + /** @brief Return a writable object for update the fast look-up of rr_node */ RRSpatialLookup& node_lookup(); - /* Add an existing rr_node in the node storage to the node look-up + /** + * @brief Add an existing rr_node in the node storage to the node look-up + * * The node will be added to the lookup for every side it is on (for OPINs and IPINs) * and for every (x,y) location at which it exists (for wires that span more than one (x,y)). + * * This function requires a valid node which has already been allocated in the node storage, with - * - a valid node id - * - valid geometry information: xlow/ylow/xhigh/yhigh - * - a valid node type - * - a valid node ptc number - * - a valid side (applicable to OPIN and IPIN nodes only + * - a valid node id + * - valid geometry information: xlow/ylow/xhigh/yhigh + * - a valid node type + * - a valid node ptc number + * - a valid side (applicable to OPIN and IPIN nodes only */ void add_node_to_all_locs(RRNodeId node); - /* Clear all the underlying data storage */ + /** @brief Clear all the underlying data storage */ void clear(); /* -- Internal data storage -- */ diff --git a/vpr/src/device/rr_spatial_lookup.h b/vpr/src/device/rr_spatial_lookup.h index ab8422a23e6..97d231546da 100644 --- a/vpr/src/device/rr_spatial_lookup.h +++ b/vpr/src/device/rr_spatial_lookup.h @@ -1,19 +1,24 @@ #ifndef RR_SPATIAL_LOOKUP_H #define RR_SPATIAL_LOOKUP_H -#include "vtr_geometry.h" -#include "vtr_vector.h" -#include "vpr_types.h" - -/******************************************************************** +/** + * @file + * @brief This RRSpatialLookup class encapsulates + * the node-lookup for a routing resource graph + * * A data structure built to find the id of an routing resource node * (rr_node) given information about its physical position and type. - * The data structure is mostly needed during rr_graph building + * The data structure is mostly needed during building a routing resource graph * * The data structure allows users to - * - Update the look-up with new nodes - * - Find the id of a node with given information, e.g., x, y, type etc. - ********************************************************************/ + * + * - Update the look-up with new nodes + * - Find the id of a node with given information, e.g., x, y, type etc. + */ +#include "vtr_geometry.h" +#include "vtr_vector.h" +#include "vpr_types.h" + class RRSpatialLookup { /* -- Constructors -- */ public: @@ -32,26 +37,28 @@ class RRSpatialLookup { /* -- Accessors -- */ public: /** - * Returns the index of the specified routing resource node. - * - (x, y) are the grid location within the FPGA - * - rr_type specifies the type of resource, - * - ptc gives a unique number of resources of that type (e.g. CHANX) at that (x,y). - * All ptcs start at 0 and are positive. - * Depending on what type of resource this is, ptc can be - * - the class number of a common SINK/SOURCE node of grid, - * starting at 0 and go up to class_inf size - 1 of SOURCEs + SINKs in a grid - * - pin number of an input/output pin of a grid. They would normally start at 0 - * and go to the number of pins on a block at that (x, y) location - * - track number of a routing wire in a channel. They would normally go from 0 - * to channel_width - 1 at that (x,y) + * @brief Returns the index of the specified routing resource node. + * + * @param (x, y) are the grid location within the FPGA + * @param rr_type specifies the type of resource, + * @param ptc gives a unique number of resources of that type (e.g. CHANX) at that (x,y). * - * An invalid id will be returned if the node does not exist + * @note All ptcs start at 0 and are positive. + * Depending on what type of resource this is, ptc can be + * - the class number of a common SINK/SOURCE node of grid, + * starting at 0 and go up to class_inf size - 1 of SOURCEs + SINKs in a grid + * - pin number of an input/output pin of a grid. They would normally start at 0 + * and go to the number of pins on a block at that (x, y) location + * - track number of a routing wire in a channel. They would normally go from 0 + * to channel_width - 1 at that (x,y) * - * Note that for segments (CHANX and CHANY) of length > 1, the segment is + * @note An invalid id will be returned if the node does not exist + * + * @note For segments (CHANX and CHANY) of length > 1, the segment is * given an rr_index based on the (x,y) location at which it starts (i.e. * lowest (x,y) location at which this segment exists). * - * The 'side' argument only applies to IPIN/OPIN types, and specifies which + * @note The 'side' argument only applies to IPIN/OPIN types, and specifies which * side of the grid tile the node should be located on. The value is ignored * for non-IPIN/OPIN types * @@ -65,12 +72,12 @@ class RRSpatialLookup { e_side side = NUM_SIDES) const; /** - * Returns the indices of the specified routing resource nodes, - * representing routing tracks in a channel. - * - (x, y) are the coordinate of the routing channel within the FPGA - * - rr_type specifies the type of routing channel, either x-direction or y-direction + * @brief Returns the indices of the specified routing resource nodes, representing routing tracks in a channel. + * + * @param (x, y) are the coordinate of the routing channel within the FPGA + * @param rr_type specifies the type of routing channel, either x-direction or y-direction * - * Note: + * @note * - Return an empty list if there are no routing channel at the given (x, y) location * - The node list returned only contain valid ids * For example, if the 2nd routing track does not exist in a routing channel at (x, y) location, @@ -83,7 +90,8 @@ class RRSpatialLookup { t_rr_type type) const; /** - * Like find_node() but returns all matching nodes on all the sides. + * @brief Like find_node() but returns all matching nodes on all the sides. + * * This is particularly useful for getting all instances * of a specific IPIN/OPIN at a specific grid tile (x,y) location. */ @@ -93,7 +101,8 @@ class RRSpatialLookup { int ptc) const; /** - * Returns all matching nodes on all the sides at a specific grid tile (x,y) location. + * @brief Returns all matching nodes on all the sides at a specific grid tile (x,y) location. + * * As this is applicable to grid pins, the type of nodes are limited to SOURCE/SINK/IPIN/OPIN */ std::vector find_grid_nodes_at_all_sides(int x, @@ -102,9 +111,7 @@ class RRSpatialLookup { /* -- Mutators -- */ public: - /** - * Reserve the memory for a list of nodes at (x, y) location with given type and side - */ + /** @brief Reserve the memory for a list of nodes at (x, y) location with given type and side */ void reserve_nodes(int x, int y, t_rr_type type, @@ -112,19 +119,22 @@ class RRSpatialLookup { e_side side = SIDES[0]); /** - * Register a node in the fast look-up - * - You must have a valid node id to register the node in the lookup - * - (x, y) are the coordinate of the node to be indexable in the fast look-up - * - type is the type of a node - * - ptc is a feature number of a node, which can be - * - the class number of a common SINK/SOURCE node of grid, - * - pin index in a tile when type is OPIN/IPIN - * - track index in a routing channel when type is CHANX/CHANY - * - side is the side of node on the tile, applicable to OPIN/IPIN - * - * Note that a node added with this call will not create a node in the rr_graph_storage node list - * You MUST add the node in the rr_graph_storage so that the node is valid + * @brief Register a node in the fast look-up + * + * @note You must have a valid node id to register the node in the lookup * + * @param (x, y) are the coordinate of the node to be indexable in the fast look-up + * @param type is the type of a node + * @param ptc is a feature number of a node, which can be + * - the class number of a common SINK/SOURCE node of grid, + * - pin index in a tile when type is OPIN/IPIN + * - track index in a routing channel when type is CHANX/CHANY + * @param side is the side of node on the tile, applicable to OPIN/IPIN + * + * @note a node added with this call will not create a node in the rr_graph_storage node list + * You MUST add the node in the rr_graph_storage so that the node is valid + */ + /* * TODO: Consider to try to return a reference to *this so that we can do chain calls * - .add_node(...) * - .add_node(...) @@ -139,14 +149,17 @@ class RRSpatialLookup { e_side side = SIDES[0]); /** - * Mirror the last dimension of a look-up, i.e., a list of nodes, from a source coordinate to + * @brief Mirror the last dimension of a look-up, i.e., a list of nodes, from a source coordinate to * a destination coordinate. + * * This function is mostly need by SOURCE and SINK nodes which are indexable in multiple locations. * Considering a bounding box (x, y)->(x + width, y + height) of a multi-height and multi-width grid, * SOURCE and SINK nodes are indexable in any location inside the boundry. * * An example of usage: - * + * + * + * ``` * // Create a empty lookup * RRSpatialLookup rr_lookup; * // Adding other nodes ... @@ -155,14 +168,21 @@ class RRSpatialLookup { * vtr::Point(1, 2), * SOURCE, * TOP); + * ``` * - * Note: currently this function only accepts SOURCE/SINK nodes. May unlock for the other types + * @note currently this function only accepts SOURCE/SINK nodes. May unlock for the other types * depending on needs - * + */ + /* * TODO: Consider to make a high-level API to duplicate the nodes for large blocks. * Then this API can become a private one * For example, + * + * + * ``` * expand_nodes(source_coordinate, bounding_box_coordinate, type, side); + * ``` + * * Alternatively, we can rework the ``find_node()`` API so that we always search the lowest (x,y) * corner when dealing with large blocks. But this may require the data structure to be dependent * on DeviceGrid information (it needs to identify if a grid has height > 1 as well as width > 1) @@ -173,11 +193,13 @@ class RRSpatialLookup { e_side side); /** - * Resize the given 3 dimensions (x, y, side) of the RRSpatialLookup data structure for the given type - * This function will keep any existing data + * @brief Resize the given 3 dimensions (x, y, side) of the RRSpatialLookup data structure for the given type * - * Strongly recommend to use when the sizes of dimensions are deterministic + * This function will keep any existing data * + * @note Strongly recommend to use when the sizes of dimensions are deterministic + */ + /* * TODO: should have a reserve function but vtd::ndmatrix does not have such API * as a result, resize can be an internal one while reserve function is a public mutator */ @@ -186,10 +208,10 @@ class RRSpatialLookup { t_rr_type type, e_side side); - /* Reorder the internal look up to be more memory efficient */ + /** @brief Reorder the internal look up to be more memory efficient */ void reorder(const vtr::vector dest_order); - /* Clear all the data inside */ + /** @brief Clear all the data inside */ void clear(); /* -- Internal data queries -- */