Merge pull request #81 from LNIS-Projects/dev

Update documentation and debugging aid

docs/source/manual/arch_lang/annotate_vpr_arch.rst

@@ -111,6 +111,8 @@ The ``circuit_model_name`` should match the given name of a ``circuit_model`` de
 
   .. note:: This should be applied to primitive ``pb_type``, i.e., ``pb_type`` have no children.
 
+  .. note:: This definition should be placed directly under the XML node ``<pb_type_annotation>`` without any intermediate XML nodes!
+
   - ``name="<string>"`` specifiy the full name of a ``pb_type`` in the hierarchy of VPR architecture.
 
   - ``physical_pb_type_name=<string>`` creates the link on ``pb_type`` between operating and physical modes. This syntax is mandatory for every primitive ``pb_type`` in an operating mode ``pb_type``. It should be a valid name of primitive ``pb_type`` in physical mode.   
@@ -125,10 +127,12 @@ The ``circuit_model_name`` should match the given name of a ``circuit_model`` de
 
 .. option:: <interconnect name="<string>" circuit_model_name="<string>">
 
-  - ``name="<string>"`` specifiy the name of a ``interconnect`` in VPR architecture. Different from ``pb_type``, hierarchical name is not required here.
+  - ``name="<string>"`` specify the name of a ``interconnect`` in VPR architecture. Different from ``pb_type``, hierarchical name is not required here.
 
   - ``circuit_model_name="<string>"`` For the interconnection type direct, the type of the linked circuit model should be wire. For multiplexers, the type of linked circuit model should be ``mux``. For complete, the type of the linked circuit model can be either ``mux`` or ``wire``, depending on the case.
 
+  .. note:: A ``<pb_type name="<string>">`` parent XML node is required for the interconnect-to-circuit bindings whose interconnects are defined under the ``pb_type`` in VPR architecture description. 
+
 .. option:: <port name="<string>" physical_mode_port="<string>"
              physical_mode_pin_initial_offset="<int>" physical_mode_pin_rotate_offset="<int>"/>
 

docs/source/motivation.rst

@@ -9,7 +9,7 @@ OpenFPGA aims to be an open-source framework that enables rapid prototyping of c
    :scale: 50%
    :alt: OpenFPGA: a fast prototyping framework for customizable FPGAs
 
-   Comparison on engineering time and effort to prototype an FPGA using OpenFPGA and conventional approaches
+   Comparison on engineering time and effort to prototype an FPGA using OpenFPGA and conventional approaches [All the layout figures are permitted to publish under proper licenses]
 
 Using OpenFPGA, the development cycle in both hardware and software can be significantly accelerated. OpenFPGA can automatically generate Verilog netlists describing a full FPGA fabric based on an XML-based description file. Thanks to modern semi-custom design tools, production-ready layout generation can be achieved within 24 hours. To help sign-off, OpenFPGA can auto-generate Verilog testbenches to validate the correctness of FPGA fabric using modern verification tools.
 OpenFPGA also provides native bitstream generation support based the same XML-based description file used in Verilog generation. This avoid the recurring engineering in developing CAD tools for different FPGAs. Once the FPGA architecture is finalized, the CAD tool is ready to use.

openfpga/src/annotation/check_pb_type_annotation.cpp

@@ -194,7 +194,7 @@ void rec_check_vpr_pb_type_circuit_model_annotation(t_pb_type* cur_pb_type,
     /* Every physical pb_type should be linked to a valid circuit model */
     if (CircuitModelId::INVALID() == vpr_device_annotation.pb_type_circuit_model(cur_pb_type)) {
       VTR_LOG_ERROR("Found a physical pb_type '%s' missing circuit model binding!\n",
-                    cur_pb_type->name);
+                    generate_pb_type_hierarchy_path(cur_pb_type).c_str());
       num_err++;
       return; /* Invalid id already, further check is not applicable */
     }
@@ -202,7 +202,8 @@ void rec_check_vpr_pb_type_circuit_model_annotation(t_pb_type* cur_pb_type,
     for (t_port* port : pb_type_ports(cur_pb_type)) {
       if (CircuitPortId::INVALID() == vpr_device_annotation.pb_circuit_port(port)) {
         VTR_LOG_ERROR("Found a port '%s' of physical pb_type '%s' missing circuit port binding!\n",
-                      port->name, cur_pb_type->name);
+                      port->name,
+                      generate_pb_type_hierarchy_path(cur_pb_type).c_str());
         num_err++;
       }
     }
@@ -217,7 +218,7 @@ void rec_check_vpr_pb_type_circuit_model_annotation(t_pb_type* cur_pb_type,
       VTR_LOG_ERROR("Found an interconnect '%s' under physical mode '%s' of pb_type '%s' missing circuit model binding!\n",
                     interc->name,
                     physical_mode->name,
-                    cur_pb_type->name);
+                    generate_pb_type_hierarchy_path(cur_pb_type).c_str());
       num_err++;
       continue;
     }
@@ -226,7 +227,7 @@ void rec_check_vpr_pb_type_circuit_model_annotation(t_pb_type* cur_pb_type,
       VTR_LOG_ERROR("Found an interconnect '%s' under physical mode '%s' of pb_type '%s' linked to a circuit model '%s' with a wrong type!\nExpect: '%s' Linked: '%s'\n",
                     interc->name,
                     physical_mode->name, 
-                    cur_pb_type->name,
+                    generate_pb_type_hierarchy_path(cur_pb_type).c_str(),
                     circuit_lib.model_name(interc_circuit_model).c_str(),
                     CIRCUIT_MODEL_TYPE_STRING[circuit_lib.model_type(interc_circuit_model)],
                     CIRCUIT_MODEL_TYPE_STRING[required_circuit_model_type]);

openfpga/src/utils/pb_type_utils.cpp

@@ -324,4 +324,42 @@ std::vector<t_port*> find_pb_type_ports_match_circuit_model_port_type(t_pb_type*
   return ports;
 }
 
+/*********************************************************************
+ * Generate the full hierarchy for a pb_type
+ * The final name will be in the following format:
+ * <top_pb_type_name>[<mode_name>].<parent_pb_type_name> ... <current_pb_type_name>
+ *
+ * TODO: This function should be part of the VPR libarchfpga parser
+ **********************************************************************/
+std::string generate_pb_type_hierarchy_path(t_pb_type* cur_pb_type) {
+  std::string hie_name(cur_pb_type->name);
+
+  t_pb_type* parent_pb_type = cur_pb_type;
+
+  /* Backward trace until we meet the top-level pb_type */
+  while (1) {
+    /* If there is no parent mode, this is a top-level pb_type, quit the loop here */
+    t_mode* parent_mode = parent_pb_type->parent_mode;
+    if (NULL == parent_mode) {
+      break;
+    }
+    
+    /* Add the mode name to the full hierarchy */
+    hie_name = std::string("[") + std::string(parent_mode->name) + std::string("].") + hie_name;
+
+    /* Backtrace to the upper level */
+    parent_pb_type = parent_mode->parent_pb_type;
+
+    /* If there is no parent pb_type, this is a top-level pb_type, quit the loop here */
+    if (NULL == parent_pb_type) {
+      break;
+    }
+
+    /* Add the current pb_type name to the hierarchy name */
+    hie_name = std::string(parent_pb_type->name) + hie_name;
+  }
+
+  return hie_name;
+}
+
 } /* end namespace openfpga */

openfpga/src/utils/pb_type_utils.h

@@ -57,6 +57,8 @@ std::vector<t_port*> find_pb_type_ports_match_circuit_model_port_type(t_pb_type*
                                                                       const e_circuit_model_port_type& port_type,
                                                                       const VprDeviceAnnotation& vpr_device_annotation);
 
+std::string generate_pb_type_hierarchy_path(t_pb_type* cur_pb_type);
+
 } /* end namespace openfpga */
 
 #endif