Added some comments and updated some VTRLOG messages

Author: sfkhalid

vpr/src/base/ShowSetup.cpp

@@ -31,7 +31,7 @@ void ShowSetup(const t_vpr_setup& vpr_setup) {
     VTR_LOG("Circuit placement file: %s\n", vpr_setup.FileNameOpts.PlaceFile.c_str());
     VTR_LOG("Circuit routing file: %s\n", vpr_setup.FileNameOpts.RouteFile.c_str());
     VTR_LOG("Circuit SDC file: %s\n", vpr_setup.Timing.SDCFile.c_str());
-    VTR_LOG("Vpr Constraints file: %s\n", vpr_setup.FileNameOpts.read_vpr_constraints_file.c_str());
+    VTR_LOG("Vpr floorplanning constraints file: %s\n", vpr_setup.FileNameOpts.read_vpr_constraints_file.c_str());
     VTR_LOG("\n");
 
     VTR_LOG("Packer: %s\n", (vpr_setup.PackerOpts.doPacking ? "ENABLED" : "DISABLED"));

vpr/src/base/constraints_load.cpp

@@ -23,7 +23,7 @@ void print_region(FILE* fp, Region region) {
 
 void print_partition(FILE* fp, Partition part) {
     std::string name = part.get_name();
-    fprintf(fp, "\npartition_name: %s\n", name.c_str());
+    fprintf(fp, "partition_name: %s\n", name.c_str());
 
     PartitionRegion pr = part.get_part_region();
 
@@ -51,6 +51,7 @@ void print_constraints(FILE* fp, VprConstraints constraints, int num_parts) {
 
         temp_part = constraints.get_partition(part_id);
 
+        fprintf(fp, "\npartition_id: %zu\n", size_t(part_id));
         print_partition(fp, temp_part);
 
         atoms = constraints.get_part_atoms(part_id);

vpr/src/base/read_options.cpp

@@ -1382,7 +1382,7 @@ argparse::ArgumentParser create_arg_parser(std::string prog_name, t_options& arg
         .show_in(argparse::ShowIn::HELP_ONLY);
 
     file_grp.add_argument(args.read_vpr_constraints_file, "--read_vpr_constraints")
-        .help("Reads the constraints data from the constraints file.")
+        .help("Reads the floorplanning constraints from the specified XML file.")
         .show_in(argparse::ShowIn::HELP_ONLY);
 
     file_grp.add_argument(args.read_router_lookahead, "--read_router_lookahead")

vpr/src/base/vpr_constraints_reader.cpp

@@ -27,7 +27,7 @@ void load_vpr_constraints_file(const char* read_vpr_constraints_name) {
     } else {
         VTR_LOG_WARN(
             "VPR constraints file '%s' may be in incorrect format. "
-            "Expecting .xml format\n",
+            "Expecting .xml format. Not reading file.\n",
             read_vpr_constraints_name);
     }
 

vpr/src/base/vpr_constraints_reader.h

@@ -1,4 +1,6 @@
-/* Defines the function used to load a vpr constraints file written in xml format into vpr*/
+/* Defines the function used to load a vpr constraints file written in XML format into vpr
+ * The functions loads up the VprConstraints, Partition, Region, and PartitionRegion data structures
+ * according to the data provided in the XML file*/
 
 #ifndef VPR_CONSTRAINTS_READER_H_
 #define VPR_CONSTRAINTS_READER_H_

vpr/src/base/vpr_constraints_serializer.h

@@ -12,6 +12,44 @@
 
 #include "vpr_constraints_uxsdcxx_interface.h"
 
+/**
+ * @file
+ * @brief The reading of vpr floorplanning constraints is now done via uxsdcxx and the 'vpr_constraints.xsd' file.
+ *        The interface between the generated code and VPR is provided by VprConstraintsBase, which is in the
+ *        file 'vpr/src/base/gen/vpr_constraints_uxsdcxx_interface.h'.
+ * 		  This file implements the virtual functions from VprConstraintsBase.
+ *
+ * Overview
+ * ========
+ * 'vpr_constraints.xsd' is an XML schema that specifies the desired format for a VPR constraints file.
+ * If this schema is changed, the following files must be regenerated: 'vpr/src/base/gen/vpr_constraints_uxsdcxx.h' and
+ * 'vpr/src/base/gen/vpr_constraints_uxsdcxx_interface.h'.
+ *
+ * Instructions to Update the Files
+ * ================================
+ *
+ * 1. Clone https://github.com/duck2/uxsdcxx/
+ * 2. Run 'python3 -mpip install --user -r requirements.txt'
+ * 3. Run 'python3 uxsdcxx.py vpr/src/base/vpr_constraints.xsd'
+ * 4. Copy 'vpr_constraints_uxsdcxx.h' and 'vpr_constraints_uxsdcxx_interface.h' to vpr/src/base/gen
+ * 5. Run 'make format'
+ * 6. Update 'vpr/src/base/vpr_constraints_serializer.h' (this file) by adding or changing functions as needed.
+ *    If the schema has changed, the compiler will complain that virtual functions are missing if they are
+ *    not implemented here.
+ *
+ * Functions in this file
+ * ======================
+ *
+ * This file implements all the functions that are necessary for the load/read interface of uxsdcxx. These are start_load, finish_load,
+ * error_encountered, and any function starting with 'set', 'add', 'preallocate' or 'finish'. Some of the load functions (ex. finish_load and
+ * the preallocate functions) have been stubbed out because the load could be successfully completed without implementing them.
+ *
+ * The functions related to the write interface have also been stubbed out because writing vpr_constraints XML files is not needed at this time.
+ * These functions can be implemented to make the write interface if needed.
+ *
+ * For more detail on how the load and write interfaces work with uxsdcxx, refer to 'vpr/src/route/SCHEMA_GENERATOR.md'
+ */
+
 struct VprConstraintsContextTypes : public uxsd::DefaultVprConstraintsContextTypes {
     using AddAtomReadContext = void*;
     using AddRegionReadContext = void*;
@@ -61,11 +99,16 @@ class VprConstraintsSerializer final : public uxsd::VprConstraintsBase<VprConstr
 
         auto atom_name_regex = std::regex(atom_name);
 
-        std::vector<AtomBlockId> clear_atoms;
-        atoms_ = clear_atoms;
+        atoms_.clear();
 
         atom_id_ = atom_ctx.nlist.find_block(name_pattern);
 
+        /* The constraints file may either provide a specific atom name or a regex.
+         * If the a valid atom ID is found for the atom name, then a specific atom name
+         * must have been read in from the file. The if condition checks for this case.
+         * The else statement checks for atoms that may match a regex.
+         * This code may get slow if many regexes are given in the file.
+         */
         if (atom_id_ != AtomBlockId::INVALID()) {
             atoms_.push_back(atom_id_);
         } else {
@@ -75,8 +118,7 @@ class VprConstraintsSerializer final : public uxsd::VprConstraintsBase<VprConstr
             for (auto block_id : atom_ctx.nlist.blocks()) {
                 auto block_name = atom_ctx.nlist.block_name(block_id);
 
-                if (std::regex_match(block_name, atom_name_regex)) {
-                    VTR_LOG("Matched block %s with ID %d to regex\n", block_name.c_str(), block_id);
+                if (std::regex_search(block_name, atom_name_regex)) {
                     atoms_.push_back(block_id);
                 }
             }
@@ -154,9 +196,7 @@ class VprConstraintsSerializer final : public uxsd::VprConstraintsBase<VprConstr
         PartitionId part_id(num_partitions_);
 
         for (unsigned int i = 0; i < atoms_.size(); i++) {
-            if (atoms_[i] != AtomBlockId::INVALID()) {
-                constraints_.add_constrained_atom(atoms_[i], part_id);
-            }
+            constraints_.add_constrained_atom(atoms_[i], part_id);
         }
     }
 
@@ -259,12 +299,20 @@ class VprConstraintsSerializer final : public uxsd::VprConstraintsBase<VprConstr
 
     //temp data for loads
     const std::function<void(const char*)>* report_error_;
+
+    //temp data structures to be loaded during file reading
     Region loaded_region;
     Partition loaded_partition;
     PartitionRegion loaded_part_region;
     VprConstraints constraints_;
+
+    //temp string used when a method must return a const char*
     std::string temp_;
+
+    //used to count the number of partitions read in from the file
     int num_partitions_ = 0;
+
+    //used when reading in atom names and regular expressions for atoms
     AtomBlockId atom_id_;
     std::vector<AtomBlockId> atoms_;
 };