Merge pull request #1837 from verilog-to-routing/rr_graph_api_doc

vaughnbetz · web-flow · commit eb3be2ba89de · 2021-09-03T16:37:50.000-04:00
Add ``RRGraph``-related API to documentation and clean-up ``RRSpatialLookup`` methods
diff --git 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
@@ -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
@@ -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
@@ -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<RRNodeId> find_grid_nodes_at_all_sides(int x,
@@ -102,29 +111,30 @@ 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,
                        int num_nodes,
                        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<int>(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<RRNodeId, RRNodeId> dest_order);
 
-    /* Clear all the data inside */
+    /** @brief Clear all the data inside */
     void clear();
 
     /* -- Internal data queries -- */

Original file line number	Diff line number	Diff line change
`@@ -8,3 +8,4 @@ VPR API`
`8`	`8`
`9`	`9`	`contexts`
`10`	`10`	`netlist`
	`11`	`+ rr_graph`