Merge pull request #2051 from MohamedElgammal/re-cluster-api-cont

Building a re-clustering API (cont.)

Author: vaughnbetz

vpr/src/base/vpr_api.cpp

@@ -351,8 +351,10 @@ void vpr_init_with_options(const t_options* options, t_vpr_setup* vpr_setup, t_a
 
     fflush(stdout);
 
-    auto& helper_ctx = g_vpr_ctx.mutable_helper();
+    auto& helper_ctx = g_vpr_ctx.mutable_cl_helper();
+    auto& device_ctx = g_vpr_ctx.mutable_device();
     helper_ctx.lb_type_rr_graphs = vpr_setup->PackerRRGraph;
+    device_ctx.pad_loc_type = vpr_setup->PlacerOpts.pad_loc_type;
 }
 
 bool vpr_flow(t_vpr_setup& vpr_setup, t_arch& arch) {
@@ -390,7 +392,7 @@ bool vpr_flow(t_vpr_setup& vpr_setup, t_arch& arch) {
 
     //clean packing-placement data
     if (vpr_setup.PackerOpts.doPacking == STAGE_DO) {
-        auto& helper_ctx = g_vpr_ctx.mutable_helper();
+        auto& helper_ctx = g_vpr_ctx.mutable_cl_helper();
         free_cluster_placement_stats(helper_ctx.cluster_placement_stats);
     }
 

vpr/src/base/vpr_context.h

@@ -56,17 +56,33 @@ struct AtomContext : public Context {
     /********************************************************************
      * Atom Netlist
      ********************************************************************/
+    /**
+     * @brief constructor
+     * 
+     * In the constructor initialize the list of pack molecules to nullptr and defines a custom deletor for it
+     */
     AtomContext()
         : list_of_pack_molecules(nullptr, free_pack_molecules) {}
+
     ///@brief Atom netlist
     AtomNetlist nlist;
 
     ///@brief Mappings to/from the Atom Netlist to physically described .blif models
     AtomLookup lookup;
 
-    ///@brief The molecules associated with each atom block
+    /**
+     * @brief The molecules associated with each atom block.
+     * 
+     * This map is loaded in the pre-packing stage and freed at the very end of vpr flow run.
+     * The pointers in this multimap is shared with list_of_pack_molecules.
+     */
     std::multimap<AtomBlockId, t_pack_molecule*> atom_molecules;
 
+    /**
+     * @brief A linked list of all the packing molecules that are loaded in pre-packing stage.
+     * 
+     * Is is useful in freeing the pack molecules at the destructor of the Atom context using free_pack_molecules.
+     */
     std::unique_ptr<t_pack_molecule, decltype(&free_pack_molecules)> list_of_pack_molecules;
 };
 
@@ -219,6 +235,11 @@ struct DeviceContext : public Context {
      * Used to determine when reading rrgraph if file is already loaded.
      */
     std::string read_rr_graph_filename;
+
+    /*******************************************************************
+     * Place Related
+     *******************************************************************/
+    enum e_pad_loc_type pad_loc_type;
 };
 
 /**
@@ -266,23 +287,40 @@ struct ClusteringContext : public Context {
      */
     std::map<ClusterBlockId, std::map<int, ClusterNetId>> post_routing_clb_pin_nets;
     std::map<ClusterBlockId, std::map<int, int>> pre_routing_net_pin_mapping;
-
-    std::map<t_logical_block_type_ptr, size_t> num_used_type_instances;
 };
 
+/**
+ * @brief State relating to helper data structure using in the clustering stage
+ * 
+ * This should contain helper data structures that are useful in the clustering/packing stage.
+ * They are encapsulated here as they are useful in clustering and reclustering algorithms that may be used
+ * in packing or placement stages.
+ */
 struct ClusteringHelperContext : public Context {
+    // A map used to save the number of used instances from each logical block type.
     std::map<t_logical_block_type_ptr, size_t> num_used_type_instances;
+
+    // Stats keeper for placement information during packing/clustering
     t_cluster_placement_stats* cluster_placement_stats;
+
+    // total number of models in the architecture
     int num_models;
+
     int max_cluster_size;
     t_pb_graph_node** primitives_list;
 
     bool enable_pin_feasibility_filter;
     int feasible_block_array_size;
 
+    // total number of CLBs
     int total_clb_num;
+
+    // A vector of routing resource nodes within each of logic cluster_ctx.blocks types [0 .. num_logical_block_type-1]
     std::vector<t_lb_type_rr_node>* lb_type_rr_graphs;
 
+    // the utilization of external input/output pins during packing (between 0 and 1)
+    t_ext_pin_util_targets target_external_pin_util;
+
     ~ClusteringHelperContext() {
         free(primitives_list);
     }
@@ -494,8 +532,8 @@ class VprContext : public Context {
     const ClusteringContext& clustering() const { return clustering_; }
     ClusteringContext& mutable_clustering() { return clustering_; }
 
-    const ClusteringHelperContext& helper() const { return helper_; }
-    ClusteringHelperContext& mutable_helper() { return helper_; }
+    const ClusteringHelperContext& cl_helper() const { return helper_; }
+    ClusteringHelperContext& mutable_cl_helper() { return helper_; }
 
     const PlacementContext& placement() const { return placement_; }
     PlacementContext& mutable_placement() { return placement_; }

vpr/src/base/vpr_types.cpp

@@ -263,4 +263,4 @@ void free_cluster_placement_stats(t_cluster_placement_stats* cluster_placement_s
         free(cluster_placement_stats_list[index].valid_primitives);
     }
     free(cluster_placement_stats_list);
-}
+}

vpr/src/base/vpr_types.h

@@ -1690,7 +1690,14 @@ typedef vtr::vector<ClusterBlockId, std::vector<std::vector<int>>> t_clb_opins_u
 
 typedef std::vector<std::map<int, int>> t_arch_switch_fanin;
 
+/**
+ * @brief Free the linked list that saves all the packing molecules.
+ */
 void free_pack_molecules(t_pack_molecule* list_of_pack_molecules);
+
+/**
+ * @brief Free the linked lists to placement locations based on status of primitive inside placement stats data structure.
+ */
 void free_cluster_placement_stats(t_cluster_placement_stats* cluster_placement_stats);
 
 #endif

vpr/src/pack/cluster.cpp

@@ -147,7 +147,7 @@ std::map<t_logical_block_type_ptr, size_t> do_clustering(const t_packer_opts& pa
     auto& atom_ctx = g_vpr_ctx.atom();
     auto& device_ctx = g_vpr_ctx.mutable_device();
     auto& cluster_ctx = g_vpr_ctx.mutable_clustering();
-    auto& helper_ctx = g_vpr_ctx.mutable_helper();
+    auto& helper_ctx = g_vpr_ctx.mutable_cl_helper();
 
     helper_ctx.enable_pin_feasibility_filter = packer_opts.enable_pin_feasibility_filter;
     helper_ctx.feasible_block_array_size = packer_opts.feasible_block_array_size;

vpr/src/pack/cluster_util.h

@@ -14,6 +14,11 @@
 #include "tatum/echo_writer.hpp"
 #include "tatum/TimingReporter.hpp"
 
+/**
+ * @file
+ * @brief This file includes useful structs and functions for building and modifying clustering
+ */
+
 #define AAPACK_MAX_HIGH_FANOUT_EXPLORE 10 /* For high-fanout nets that are ignored, consider a maximum of this many sinks, must be less than packer_opts.feasible_block_array_size */
 #define AAPACK_MAX_TRANSITIVE_EXPLORE 40  /* When investigating transitive fanout connections in packing, consider a maximum of this many molecules, must be less than packer_opts.feasible_block_array_size */
 
@@ -74,7 +79,7 @@ struct t_cluster_progress_stats {
     int num_unrelated_clustering_attempts = 0;
 };
 
-/* Useful data structures for packing */
+/* Useful data structures for creating or modifying clusters */
 struct t_clustering_data {
     vtr::vector<ClusterBlockId, std::vector<t_intra_lb_net>*> intra_lb_routing;
     int* hill_climbing_inputs_avail;
@@ -85,6 +90,7 @@ struct t_clustering_data {
      * list of blocks with i inputs to be hooked up via external interconnect. */
     t_molecule_link* unclustered_list_head = nullptr;
 
+    //Maintaining a linked list of free molecule data for speed
     t_molecule_link* memory_pool = nullptr;
 
     /* Does the atom block that drives the output of this atom net also appear as a   *

vpr/src/pack/pack.cpp

@@ -42,7 +42,7 @@ bool try_pack(t_packer_opts* packer_opts,
               const t_model* library_models,
               float interc_delay,
               std::vector<t_lb_type_rr_node>* lb_type_rr_graphs) {
-    auto& helper_ctx = g_vpr_ctx.mutable_helper();
+    auto& helper_ctx = g_vpr_ctx.mutable_cl_helper();
 
     std::unordered_set<AtomNetId> is_clock;
     std::unordered_map<AtomBlockId, t_pb_graph_node*> expected_lowest_cost_pb_gnode; //The molecules associated with each atom block
@@ -113,10 +113,10 @@ bool try_pack(t_packer_opts* packer_opts,
         VTR_LOG("Using inter-cluster delay: %g\n", packer_opts->inter_cluster_net_delay);
     }
 
-    t_ext_pin_util_targets target_external_pin_util = parse_target_external_pin_util(packer_opts->target_external_pin_util);
+    helper_ctx.target_external_pin_util = parse_target_external_pin_util(packer_opts->target_external_pin_util);
     t_pack_high_fanout_thresholds high_fanout_thresholds = parse_high_fanout_thresholds(packer_opts->high_fanout_threshold);
 
-    VTR_LOG("Packing with pin utilization targets: %s\n", target_external_pin_util_to_string(target_external_pin_util).c_str());
+    VTR_LOG("Packing with pin utilization targets: %s\n", target_external_pin_util_to_string(helper_ctx.target_external_pin_util).c_str());
     VTR_LOG("Packing with high fanout thresholds: %s\n", high_fanout_thresholds_to_string(high_fanout_thresholds).c_str());
 
     bool allow_unrelated_clustering = false;
@@ -149,7 +149,7 @@ bool try_pack(t_packer_opts* packer_opts,
             allow_unrelated_clustering,
             balance_block_type_util,
             lb_type_rr_graphs,
-            target_external_pin_util,
+            helper_ctx.target_external_pin_util,
             high_fanout_thresholds,
             attraction_groups,
             floorplan_regions_overfull,
@@ -211,7 +211,7 @@ bool try_pack(t_packer_opts* packer_opts,
                 VTR_LOG("Pack iteration is %d\n", pack_iteration);
                 attraction_groups.set_att_group_pulls(4);
                 t_ext_pin_util pin_util(1.0, 1.0);
-                target_external_pin_util.set_block_pin_util("clb", pin_util);
+                helper_ctx.target_external_pin_util.set_block_pin_util("clb", pin_util);
             }
 
         } else {

vpr/src/pack/prepack.h

@@ -18,5 +18,4 @@ void free_pack_pattern(t_pack_patterns* pack_pattern);
 t_pack_molecule* alloc_and_load_pack_molecules(t_pack_patterns* list_of_pack_patterns,
                                                std::unordered_map<AtomBlockId, t_pb_graph_node*>& expected_lowest_cost_pb_gnode,
                                                const int num_packing_patterns);
-
 #endif