Change API comments in VPR base to doxygen style

This commit changes the style of code comments in vpr/src/base to
doxygen compatible. The changes allow for using the source files for
generating Sphinx API documentation.

Signed-off-by: Robert Winkler <[email protected]>

Author: rw1nkler

vpr/src/base/SetupGrid.cpp

@@ -1,9 +1,9 @@
-/*
- * Author: Jason Luu
- * Date: October 8, 2008
- *
- * Initializes and allocates the physical logic block grid for VPR.
+/**
+ * @file
+ * @author Jason Luu
+ * @date   October 8, 2008
  *
+ * @brief Initializes and allocates the physical logic block grid for VPR.
  */
 
 #include <cstdio>
@@ -36,7 +36,7 @@ static void CheckGrid(const DeviceGrid& grid);
 
 static void set_grid_block_type(int priority, const t_physical_tile_type* type, size_t x_root, size_t y_root, vtr::Matrix<t_grid_tile>& grid, vtr::Matrix<int>& grid_priorities, const t_metadata_dict* meta);
 
-//Create the device grid based on resource requirements
+///@brief Create the device grid based on resource requirements
 DeviceGrid create_device_grid(std::string layout_name, const std::vector<t_grid_def>& grid_layouts, const std::map<t_logical_block_type_ptr, size_t>& minimum_instance_counts, float target_device_utilization) {
     if (layout_name == "auto") {
         //Auto-size the device
@@ -68,7 +68,7 @@ DeviceGrid create_device_grid(std::string layout_name, const std::vector<t_grid_
     }
 }
 
-//Create the device grid based on dimensions
+///@brief Create the device grid based on dimensions
 DeviceGrid create_device_grid(std::string layout_name, const std::vector<t_grid_def>& grid_layouts, size_t width, size_t height) {
     if (layout_name == "auto") {
         VTR_ASSERT(grid_layouts.size() > 0);
@@ -129,9 +129,12 @@ DeviceGrid create_device_grid(std::string layout_name, const std::vector<t_grid_
     }
 }
 
-//Create a device grid which satisfies the minimum block counts
-//  If a set of fixed grid layouts are specified, the smallest satisfying grid is picked
-//  If an auto grid layouts are specified, the smallest dynamicly sized grid is picked
+/**
+ * @brief Create a device grid which satisfies the minimum block counts
+ *
+ * If a set of fixed grid layouts are specified, the smallest satisfying grid is picked
+ * If an auto grid layouts are specified, the smallest dynamicly sized grid is picked
+ */
 static DeviceGrid auto_size_device_grid(const std::vector<t_grid_def>& grid_layouts, const std::map<t_logical_block_type_ptr, size_t>& minimum_instance_counts, float maximum_device_utilization) {
     VTR_ASSERT(grid_layouts.size() > 0);
 
@@ -223,11 +226,14 @@ static DeviceGrid auto_size_device_grid(const std::vector<t_grid_def>& grid_layo
     return grid; //Unreachable
 }
 
+/**
+ * @brief Estimates what logical block types will be unimplementable due to resource
+ *        limits in the available grid
+ *
+ * Performs a fast counting based estimate, allocating the least
+ * flexible block types (those with the fewestequivalent tiles) first.
+ */
 static std::vector<t_logical_block_type_ptr> grid_overused_resources(const DeviceGrid& grid, std::map<t_logical_block_type_ptr, size_t> instance_counts) {
-    //Estimates what logical block types will be unimplementable due to resource limits in the available grid
-    //
-    //Performs a fast counting based estimate, allocating the least flexible block types (those with the fewest
-    //equivalent tiles) first.
     auto& device_ctx = g_vpr_ctx.device();
 
     std::vector<t_logical_block_type_ptr> overused_resources;
@@ -299,7 +305,7 @@ static bool grid_satisfies_instance_counts(const DeviceGrid& grid, std::map<t_lo
     return true; //OK
 }
 
-//Build the specified device grid
+///@brief Build the specified device grid
 static DeviceGrid build_device_grid(const t_grid_def& grid_def, size_t grid_width, size_t grid_height, bool warn_out_of_range, const std::vector<t_logical_block_type_ptr> limiting_resources) {
     if (grid_def.grid_type == GridDefType::FIXED) {
         if (grid_def.width != int(grid_width) || grid_def.height != int(grid_height)) {
@@ -630,8 +636,8 @@ static void set_grid_block_type(int priority, const t_physical_tile_type* type,
     }
 }
 
+///@brief Check grid is valid
 static void CheckGrid(const DeviceGrid& grid) {
-    /* Check grid is valid */
     for (size_t i = 0; i < grid.width(); ++i) {
         for (size_t j = 0; j < grid.height(); ++j) {
             auto type = grid[i][j].type;

vpr/src/base/SetupGrid.h

@@ -1,29 +1,38 @@
 #ifndef SETUPGRID_H
 #define SETUPGRID_H
 
-/*
- * Author: Jason Luu
- * Date: October 8, 2008
- *
- * Initializes and allocates the physical logic block grid for VPR.
+/**
+ * @file
+ * @author  Jason Luu
+ * @date    October 8, 2008
  *
+ * @brief   Initializes and allocates the physical logic block grid for VPR.
  */
+
 #include <vector>
 #include "physical_types.h"
 
-//Find the device satisfying the specified minimum resources
+///@brief Find the device satisfying the specified minimum resources
 DeviceGrid create_device_grid(std::string layout_name,
                               const std::vector<t_grid_def>& grid_layouts,
                               const std::map<t_logical_block_type_ptr, size_t>& minimum_instance_counts,
                               float target_device_utilization);
 
-//Find the device close in size to the specified dimensions
+///@brief Find the device close in size to the specified dimensions
 DeviceGrid create_device_grid(std::string layout_name, const std::vector<t_grid_def>& grid_layouts, size_t min_width, size_t min_height);
 
-//Calculate the device utilization (i.e. fraction of used grid tiles) for the specified grid and resource requirements
+/**
+ * @brief Calculate the device utilization
+ *
+ * Calculate the device utilization (i.e. fraction of used grid tiles)
+ * foor the specified grid and resource requirements
+ */
 float calculate_device_utilization(const DeviceGrid& grid, std::map<t_logical_block_type_ptr, size_t> instance_counts);
 
-//Returns the effective size of the device (size of the bounding box of non-empty grid tiles)
+/**
+ * @brief Returns the effective size of the device
+ *        (size of the bounding box of non-empty grid tiles)
+ */
 size_t count_grid_tiles(const DeviceGrid& grid);
 
 #endif

vpr/src/base/SetupVPR.cpp

@@ -43,8 +43,12 @@ static void SetupAnalysisOpts(const t_options& Options, t_analysis_opts& analysi
 static void SetupPowerOpts(const t_options& Options, t_power_opts* power_opts, t_arch* Arch);
 static int find_ipin_cblock_switch_index(const t_arch& Arch);
 
-/* Sets VPR parameters and defaults. Does not do any error checking
- * as this should have been done by the various input checkers */
+/**
+ * @brief Sets VPR parameters and defaults.
+ *
+ * Does not do any error checking as this should have been done by
+ * the various input checkers
+ */
 void SetupVPR(const t_options* Options,
               const bool TimingEnabled,
               const bool readArchFile,
@@ -253,8 +257,10 @@ static void SetupTiming(const t_options& Options, const bool TimingEnabled, t_ti
     Timing->SDCFile = Options.SDCFile;
 }
 
-/* This loads up VPR's arch_switch_inf data by combining the switches from
- * the arch file with the special switches that VPR needs. */
+/**
+ * @brief This loads up VPR's arch_switch_inf data by combining the switches
+ *        from the arch file with the special switches that VPR needs.
+ */
 static void SetupSwitches(const t_arch& Arch,
                           t_det_routing_arch* RoutingArch,
                           const t_arch_switch_inf* ArchSwitches,
@@ -301,8 +307,11 @@ static void SetupSwitches(const t_arch& Arch,
     }
 }
 
-/* Sets up routing structures. Since checks are already done, this
- * just copies values across */
+/**
+ * @brief Sets up routing structures.
+ *
+ * Since checks are already done, this just copies values across
+ */
 static void SetupRoutingArch(const t_arch& Arch,
                              t_det_routing_arch* RoutingArch) {
     RoutingArch->switch_block_type = Arch.SBType;
@@ -414,8 +423,12 @@ static void SetupAnnealSched(const t_options& Options,
     AnnealSched->type = Options.anneal_sched_type;
 }
 
-/* Sets up the s_packer_opts structure baesd on users inputs and on the architecture specified.
- * Error checking, such as checking for conflicting params is assumed to be done beforehand
+/**
+ * @brief Sets up the s_packer_opts structure baesd on users inputs and
+ *        on the architecture specified.
+ *
+ * Error checking, such as checking for conflicting params is assumed
+ * to be done beforehand
  */
 void SetupPackerOpts(const t_options& Options,
                      t_packer_opts* PackerOpts) {
@@ -467,8 +480,12 @@ static void SetupNetlistOpts(const t_options& Options, t_netlist_opts& NetlistOp
     NetlistOpts.netlist_verbosity = Options.netlist_verbosity;
 }
 
-/* Sets up the s_placer_opts structure based on users input. Error checking,
- * such as checking for conflicting params is assumed to be done beforehand */
+/**
+ * @brief Sets up the s_placer_opts structure based on users input.
+ *
+ * Error checking, such as checking for conflicting params
+ * is assumed to be done beforehand
+ */
 static void SetupPlacerOpts(const t_options& Options, t_placer_opts* PlacerOpts) {
     if (Options.do_placement) {
         PlacerOpts->doPlacement = STAGE_DO;

vpr/src/base/atom_lookup.h

@@ -12,9 +12,10 @@
 #include "clustered_netlist_fwd.h"
 #include "vpr_types.h"
 #include "tatum/TimingGraphFwd.hpp"
-/*
- * The AtomLookup class describes the mapping between components in the AtomNetlist
- * and other netlists/entities (i.e. atom block <-> t_pb, atom block <-> clb)
+
+/**
+ * @brief The AtomLookup class describes the mapping between components in the AtomNetlist
+ *        and other netlists/entities (i.e. atom block <-> t_pb, atom block <-> clb)
  */
 class AtomLookup {
   public:
@@ -26,67 +27,81 @@ class AtomLookup {
     /*
      * PBs
      */
-    //Returns the leaf pb associated with the atom blk_id
-    //  Note: this is the lowest level pb which corresponds directly to the atom block
+
+    /**
+     * @brief Returns the leaf pb associated with the atom blk_id
+     * @note  this is the lowest level pb which corresponds directly to the atom block
+     */
     const t_pb* atom_pb(const AtomBlockId blk_id) const;
 
-    //Returns the atom block id associated with pb
+    ///@brief Returns the atom block id associated with pb
     AtomBlockId pb_atom(const t_pb* pb) const;
 
-    //Conveneince wrapper around atom_pb to access the associated graph node
+    ///@brief Conveneince wrapper around atom_pb to access the associated graph node
     const t_pb_graph_node* atom_pb_graph_node(const AtomBlockId blk_id) const;
 
-    //Sets the bidirectional mapping between an atom and pb
-    // If either blk_id or pb are not valid any, existing mapping is removed
+    /**
+     * @brief Sets the bidirectional mapping between an atom and pb
+     *
+     * If either blk_id or pb are not valid any, existing mapping is removed
+     */
     void set_atom_pb(const AtomBlockId blk_id, const t_pb* pb);
 
     /*
      * PB Pins
      */
-    //Returns the pb graph pin associated with the specified atom pin
+
+    ///@brief Returns the pb graph pin associated with the specified atom pin
     const t_pb_graph_pin* atom_pin_pb_graph_pin(AtomPinId atom_pin) const;
 
-    //Sets the mapping between an atom pin and pb graph pin
+    ///@brief Sets the mapping between an atom pin and pb graph pin
     void set_atom_pin_pb_graph_pin(AtomPinId atom_pin, const t_pb_graph_pin* gpin);
 
     /*
      * Blocks
      */
-    //Returns the clb index associated with blk_id
+
+    ///@brief Returns the clb index associated with blk_id
     ClusterBlockId atom_clb(const AtomBlockId blk_id) const;
 
-    //Sets the bidirectional mapping between an atom and clb
-    // If either blk_id or clb_index are not valid any existing mapping
-    // is removed
+    /**
+     * @brief Sets the bidirectional mapping between an atom and clb
+     *
+     * If either blk_id or clb_index are not valid any existing mapping is removed
+     */
     void set_atom_clb(const AtomBlockId blk_id, const ClusterBlockId clb);
 
     /*
      * Nets
      */
-    //Returns the atom net id associated with the clb_net_index
+
+    ///@brief Returns the atom net id associated with the clb_net_index
     AtomNetId atom_net(const ClusterNetId clb_net_index) const;
 
-    //Returns the clb net index associated with net_id
+    ///@brief Returns the clb net index associated with net_id
     ClusterNetId clb_net(const AtomNetId net_id) const;
 
-    //Sets the bidirectional mapping between an atom net and a clb net
-    // If either net_id or clb_net_index are not valid any existing mapping
-    // is removed
+    /**
+     * @brief Sets the bidirectional mapping between an atom net and a clb net
+     *
+     * If either net_id or clb_net_index are not valid any existing mapping is removed
+     */
     void set_atom_clb_net(const AtomNetId net_id, const ClusterNetId clb_net_index);
 
     /*
      * Timing Nodes
      */
-    //Returns the timing graph node associated with the specified atom netlist pin
+
+    ///@brief Returns the timing graph node associated with the specified atom netlist pin
     tatum::NodeId atom_pin_tnode(const AtomPinId pin, BlockTnode block_tnode_type = BlockTnode::EXTERNAL) const;
 
-    //Returns the atom netlist pin associated with the specified timing graph node
+    ///@brief Returns the atom netlist pin associated with the specified timing graph node
     AtomPinId tnode_atom_pin(const tatum::NodeId tnode) const;
 
-    //Returns a range of all pin to tnode mappingsg of the specified type
+    ///@brief Returns a range of all pin to tnode mappingsg of the specified type
     AtomLookup::pin_tnode_range atom_pin_tnodes(BlockTnode block_tnode_type) const;
 
-    //Sets the bi-directional mapping between an atom netlist pin and timing graph node
+    ///@brief Sets the bi-directional mapping between an atom netlist pin and timing graph node
     void set_atom_pin_tnode(const AtomPinId pin, const tatum::NodeId node, BlockTnode block_tnode_type);
 
   private: //Types

vpr/src/base/atom_lookup_fwd.h

@@ -4,8 +4,8 @@
 class AtomLookup;
 
 enum class BlockTnode {
-    INTERNAL, //tnodes corresponding to internal paths withing atom blocks
-    EXTERNAL  //tnodes corresponding to exteranl interface of atom blocks
+    INTERNAL, ///<tnodes corresponding to internal paths withing atom blocks
+    EXTERNAL  ///<tnodes corresponding to exteranl interface of atom blocks
 };
 
 #endif