Merge branch 'master' into cschai-openfpga-lutram

VERSION.md

@@ -1 +1 @@
-1.2.1979
+1.2.1986

docs/source/manual/file_formats/fabric_pin_physical_location_file.rst

@@ -0,0 +1,109 @@
+.. _file_format_fabric_pin_physical_location_file:
+
+Fabric Pin Physical Location File (.xml)
+----------------------------------------
+
+This file is generated by command :ref:`openfpga_setup_commands_write_fabric_pin_physical_location`
+
+
+The fabric pin physical location file aims to show 
+
+- Pin names of each module in an eFPGA fabric
+- Preferred physical side of each pin on its module
+
+This file is created for pin guidelines during physical design steps
+
+An example of the file is shown as follows.
+
+.. code-block:: xml
+
+  <pin_location>
+    <module name="sb_1__1_">
+      <loc pin="chany_bottom_in[0:0]" side="bottom"/>
+      <loc pin="chany_bottom_in[1:1]" side="bottom"/>
+      <loc pin="chany_bottom_in[2:2]" side="bottom"/>
+      <loc pin="chany_bottom_in[3:3]" side="bottom"/>
+      <loc pin="chany_bottom_in[4:4]" side="bottom"/>
+      <loc pin="chany_bottom_in[5:5]" side="bottom"/>
+      <loc pin="chany_bottom_in[6:6]" side="bottom"/>
+      <loc pin="chany_bottom_in[7:7]" side="bottom"/>
+      <loc pin="chany_bottom_in[8:8]" side="bottom"/>
+      <loc pin="chany_bottom_in[9:9]" side="bottom"/>
+      <loc pin="chany_bottom_in[10:10]" side="bottom"/>
+      <loc pin="chany_bottom_in[11:11]" side="bottom"/>
+      <loc pin="chany_bottom_in[12:12]" side="bottom"/>
+      <loc pin="chany_bottom_out[0:0]" side="bottom"/>
+      <loc pin="chany_bottom_out[1:1]" side="bottom"/>
+      <loc pin="chany_bottom_out[2:2]" side="bottom"/>
+      <loc pin="chany_bottom_out[3:3]" side="bottom"/>
+      <loc pin="chany_bottom_out[4:4]" side="bottom"/>
+      <loc pin="chany_bottom_out[5:5]" side="bottom"/>
+      <loc pin="chany_bottom_out[6:6]" side="bottom"/>
+      <loc pin="chany_bottom_out[7:7]" side="bottom"/>
+      <loc pin="chany_bottom_out[8:8]" side="bottom"/>
+      <loc pin="chany_bottom_out[9:9]" side="bottom"/>
+      <loc pin="chany_bottom_out[10:10]" side="bottom"/>
+      <loc pin="chany_bottom_out[11:11]" side="bottom"/>
+      <loc pin="chany_bottom_out[12:12]" side="bottom"/>
+      <loc pin="bottom_right_grid_left_width_0_height_0_subtile_0__pin_inpad_0_[0:0]" side="bottom"/>
+      <loc pin="bottom_right_grid_left_width_0_height_0_subtile_1__pin_inpad_0_[0:0]" side="bottom"/>
+      <loc pin="bottom_right_grid_left_width_0_height_0_subtile_2__pin_inpad_0_[0:0]" side="bottom"/>
+      <loc pin="bottom_right_grid_left_width_0_height_0_subtile_3__pin_inpad_0_[0:0]" side="bottom"/>
+      <loc pin="bottom_right_grid_left_width_0_height_0_subtile_4__pin_inpad_0_[0:0]" side="bottom"/>
+      <loc pin="bottom_right_grid_left_width_0_height_0_subtile_5__pin_inpad_0_[0:0]" side="bottom"/>
+      <loc pin="bottom_right_grid_left_width_0_height_0_subtile_6__pin_inpad_0_[0:0]" side="bottom"/>
+      <loc pin="bottom_right_grid_left_width_0_height_0_subtile_7__pin_inpad_0_[0:0]" side="bottom"/>
+      <loc pin="bottom_left_grid_right_width_0_height_0_subtile_0__pin_O_3_[0:0]" side="bottom"/>
+      <loc pin="chanx_left_in[0:0]" side="left"/>
+      <loc pin="chanx_left_in[1:1]" side="left"/>
+      <loc pin="chanx_left_in[2:2]" side="left"/>
+      <loc pin="chanx_left_in[3:3]" side="left"/>
+      <loc pin="chanx_left_in[4:4]" side="left"/>
+      <loc pin="chanx_left_in[5:5]" side="left"/>
+      <loc pin="chanx_left_in[6:6]" side="left"/>
+      <loc pin="chanx_left_in[7:7]" side="left"/>
+      <loc pin="chanx_left_in[8:8]" side="left"/>
+      <loc pin="chanx_left_in[9:9]" side="left"/>
+      <loc pin="chanx_left_in[10:10]" side="left"/>
+      <loc pin="chanx_left_in[11:11]" side="left"/>
+      <loc pin="chanx_left_in[12:12]" side="left"/>
+      <loc pin="chanx_left_out[0:0]" side="left"/>
+      <loc pin="chanx_left_out[1:1]" side="left"/>
+      <loc pin="chanx_left_out[2:2]" side="left"/>
+      <loc pin="chanx_left_out[3:3]" side="left"/>
+      <loc pin="chanx_left_out[4:4]" side="left"/>
+      <loc pin="chanx_left_out[5:5]" side="left"/>
+      <loc pin="chanx_left_out[6:6]" side="left"/>
+      <loc pin="chanx_left_out[7:7]" side="left"/>
+      <loc pin="chanx_left_out[8:8]" side="left"/>
+      <loc pin="chanx_left_out[9:9]" side="left"/>
+      <loc pin="chanx_left_out[10:10]" side="left"/>
+      <loc pin="chanx_left_out[11:11]" side="left"/>
+      <loc pin="chanx_left_out[12:12]" side="left"/>
+      <loc pin="left_top_grid_bottom_width_0_height_0_subtile_0__pin_inpad_0_[0:0]" side="left"/>
+      <loc pin="left_top_grid_bottom_width_0_height_0_subtile_1__pin_inpad_0_[0:0]" side="left"/>
+      <loc pin="left_top_grid_bottom_width_0_height_0_subtile_2__pin_inpad_0_[0:0]" side="left"/>
+      <loc pin="left_top_grid_bottom_width_0_height_0_subtile_3__pin_inpad_0_[0:0]" side="left"/>
+      <loc pin="left_top_grid_bottom_width_0_height_0_subtile_4__pin_inpad_0_[0:0]" side="left"/>
+      <loc pin="left_top_grid_bottom_width_0_height_0_subtile_5__pin_inpad_0_[0:0]" side="left"/>
+      <loc pin="left_top_grid_bottom_width_0_height_0_subtile_6__pin_inpad_0_[0:0]" side="left"/>
+      <loc pin="left_top_grid_bottom_width_0_height_0_subtile_7__pin_inpad_0_[0:0]" side="left"/>
+      <loc pin="left_bottom_grid_top_width_0_height_0_subtile_0__pin_O_2_[0:0]" side="left"/>
+    </module>
+  </pin_location>
+
+.. option:: name="<string>"
+
+  The module name in FPGA fabric, which should be a valid module defined in output Verilog netlist.
+
+  .. note:: You should be find the exact module in the FPGA fabric if you output the Verilog netlists.
+
+.. option:: pin="<string>"
+
+  The name of the pin in FPGA fabric. Note that all the bus port will be flatten in this file.
+
+  .. note:: You should be find the exact pin in the module if you output the Verilog netlists.
+
+.. option:: side="<string>"
+
+  The physical side of the pin should appear on the perimeter of the module. 

docs/source/manual/file_formats/index.rst

@@ -41,3 +41,5 @@ OpenFPGA widely uses XML format for interchangeable files
    module_naming_file
 
    tile_config_file
+
+   fabric_pin_physical_location_file

docs/source/manual/openfpga_shell/openfpga_commands/setup_commands.rst

@@ -392,7 +392,7 @@ write_fabric_io_info
 
   .. option:: --no_time_stamp
 
-    Do not print time stamp in bitstream files
+    Do not print time stamp in output files
 
   .. option:: --verbose
 
@@ -433,7 +433,7 @@ pcf2place
 
   .. option:: --no_time_stamp
 
-    Do not print time stamp in bitstream files
+    Do not print time stamp in output files
 
   .. option:: --verbose
 
@@ -467,7 +467,34 @@ write_module_naming_rules
 
   .. option:: --no_time_stamp
 
-    Do not print time stamp in bitstream files
+    Do not print time stamp in output files
+
+  .. option:: --verbose
+
+    Show verbose log
+
+.. _openfpga_setup_commands_write_fabric_pin_physical_location:
+
+write_fabric_pin_physical_location
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Output the physical location of each pin for each module of an FPGA fabric to a given file
+
+  .. option:: --file <string>
+
+    Specify the file path to be written to. See details in :ref:`file_format_fabric_pin_physical_location_file`.
+
+  .. option:: --module <string>
+
+    Specify the name of modules to be considered. Support regular expression, e.g., ``tile*``. When provided, only pins of selected modules will be outputted. By default, a wildcard ``*`` is considered, which means all the modules will be considered.
+
+  .. option:: --show_invalid_side
+
+    Show sides for each pin, even these pin does not have a specific valid side. This is mainly used for debugging.
+
+  .. option:: --no_time_stamp
+
+    Do not print time stamp in output files
 
   .. option:: --verbose
 

openfpga/src/base/openfpga_build_fabric_template.h

@@ -23,6 +23,7 @@
 #include "rename_modules.h"
 #include "vtr_log.h"
 #include "vtr_time.h"
+#include "write_xml_fabric_pin_physical_location.h"
 #include "write_xml_module_name_map.h"
 
 /* begin namespace openfpga */
@@ -419,6 +420,41 @@ int write_module_naming_rules_template(const T& openfpga_ctx,
     cmd_context.option_enable(cmd, opt_verbose));
 }
 
+/********************************************************************
+ * Write fabric pin physical location to a file
+ *******************************************************************/
+template <class T>
+int write_fabric_pin_physical_location_template(
+  const T& openfpga_ctx, const Command& cmd,
+  const CommandContext& cmd_context) {
+  CommandOptionId opt_verbose = cmd.option("verbose");
+  CommandOptionId opt_no_time_stamp = cmd.option("no_time_stamp");
+  CommandOptionId opt_show_invalid_side = cmd.option("show_invalid_side");
+
+  /* Check the option '--file' is enabled or not
+   * Actually, it must be enabled as the shell interface will check
+   * before reaching this fuction
+   */
+  CommandOptionId opt_file = cmd.option("file");
+  VTR_ASSERT(true == cmd_context.option_enable(cmd, opt_file));
+  VTR_ASSERT(false == cmd_context.option_value(cmd, opt_file).empty());
+
+  std::string file_name = cmd_context.option_value(cmd, opt_file);
+
+  std::string module_name("*"); /* Use a wildcard for everything */
+  CommandOptionId opt_module = cmd.option("module");
+  if (true == cmd_context.option_enable(cmd, opt_module)) {
+    module_name = cmd_context.option_value(cmd, opt_module);
+  }
+
+  /* Write hierarchy to a file */
+  return write_xml_fabric_pin_physical_location(
+    file_name.c_str(), module_name, openfpga_ctx.module_graph(),
+    cmd_context.option_enable(cmd, opt_show_invalid_side),
+    !cmd_context.option_enable(cmd, opt_no_time_stamp),
+    cmd_context.option_enable(cmd, opt_verbose));
+}
+
 } /* end namespace openfpga */
 
 #endif

openfpga/src/base/openfpga_naming.cpp

@@ -413,6 +413,35 @@ std::string generate_sb_module_track_port_name(const t_rr_type& chan_type,
   return port_name;
 }
 
+/*********************************************************************
+ * Get the physical side for a routing track in a Connection Block module
+ * Upper_location: specify if an upper/lower prefix to be added.
+ *                 The location indicates where the bus port should be
+ *                 placed on the perimeter of the connection block
+ *                 - For X-directional CB:
+ *                   - upper is the left side
+ *                   - lower is the right side
+ *                 - For Y-directional CB:
+ *                   - upper is the bottom side
+ *                   - lower is the top side
+ *********************************************************************/
+e_side get_cb_module_track_port_side(const t_rr_type& chan_type,
+                                     const bool& upper_location) {
+  /* Channel must be either CHANX or CHANY */
+  VTR_ASSERT((CHANX == chan_type) || (CHANY == chan_type));
+
+  /* Create a map between chan_type and module_prefix */
+  std::map<t_rr_type, std::map<bool, e_side>> port_side_map;
+  /* TODO: use a constexpr string to replace the fixed name? */
+  /* IMPORTANT: This part must be consistent with the mapping in the
+   * generate_cb_module_track_port_name() !!! */
+  port_side_map[CHANX][true] = LEFT;
+  port_side_map[CHANX][false] = RIGHT;
+  port_side_map[CHANY][true] = BOTTOM;
+  port_side_map[CHANY][false] = TOP;
+  return port_side_map[chan_type][upper_location];
+}
+
 /*********************************************************************
  * Generate the port name for a routing track in a Connection Block module
  * This function is created to ease the PnR for each unique routing module

openfpga/src/base/openfpga_naming.h

@@ -97,6 +97,9 @@ std::string generate_sb_module_track_port_name(const t_rr_type& chan_type,
                                                const e_side& module_side,
                                                const PORTS& port_direction);
 
+e_side get_cb_module_track_port_side(const t_rr_type& chan_type,
+                                     const bool& upper_location);
+
 std::string generate_cb_module_track_port_name(const t_rr_type& chan_type,
                                                const PORTS& port_direction,
                                                const bool& upper_location);

openfpga/src/base/openfpga_setup_command_template.h

@@ -858,6 +858,55 @@ ShellCommandId add_write_module_naming_rules_command_template(
   return shell_cmd_id;
 }
 
+/********************************************************************
+ * - Add a command to Shell environment: write_pin_physical_location
+ * - Add associated options
+ * - Add command dependency
+ *******************************************************************/
+template <class T>
+ShellCommandId add_write_fabric_pin_physical_location_command_template(
+  openfpga::Shell<T>& shell, const ShellCommandClassId& cmd_class_id,
+  const std::vector<ShellCommandId>& dependent_cmds, const bool& hidden) {
+  Command shell_cmd("write_fabric_pin_physical_location");
+  /* Add an option '--file' in short '-f'*/
+  CommandOptionId opt_file = shell_cmd.add_option(
+    "file", true,
+    "file path to the XML file that contains pin physical location");
+  shell_cmd.set_option_short_name(opt_file, "f");
+  shell_cmd.set_option_require_value(opt_file, openfpga::OPT_STRING);
+
+  /* Add an option '--module'*/
+  CommandOptionId opt_module = shell_cmd.add_option(
+    "module", false,
+    "specify the module whose pin physical location should be outputted");
+  shell_cmd.set_option_require_value(opt_module, openfpga::OPT_STRING);
+
+  /* Add an option '--no_time_stamp' */
+  shell_cmd.add_option("no_time_stamp", false,
+                       "Do not print time stamp in output files");
+
+  shell_cmd.add_option(
+    "show_invalid_side", false,
+    "Include pins with invalid sides in output files. Recommended for "
+    "debugging as the output file may include a lot of useless information");
+
+  shell_cmd.add_option("verbose", false, "Show verbose outputs");
+
+  /* Add command to the Shell */
+  ShellCommandId shell_cmd_id = shell.add_command(
+    shell_cmd,
+    "Output the pin physical location of an FPGA fabric to a given file",
+    hidden);
+  shell.set_command_class(shell_cmd_id, cmd_class_id);
+  shell.set_command_const_execute_function(
+    shell_cmd_id, write_fabric_pin_physical_location_template<T>);
+
+  /* Add command dependency to the Shell */
+  shell.set_command_dependency(shell_cmd_id, dependent_cmds);
+
+  return shell_cmd_id;
+}
+
 template <class T>
 void add_setup_command_templates(openfpga::Shell<T>& shell,
                                  const bool& hidden = false) {
@@ -1098,6 +1147,17 @@ void add_setup_command_templates(openfpga::Shell<T>& shell,
   add_write_module_naming_rules_command_template<T>(
     shell, openfpga_setup_cmd_class, cmd_dependency_write_module_naming_rules,
     hidden);
+
+  /********************************
+   * Command 'write_fabric_pin_physical_location'
+   */
+  /* The command should NOT be executed before 'build_fabric' */
+  std::vector<ShellCommandId> cmd_dependency_write_fabric_pin_physical_location;
+  cmd_dependency_write_fabric_pin_physical_location.push_back(
+    build_fabric_cmd_id);
+  add_write_fabric_pin_physical_location_command_template<T>(
+    shell, openfpga_setup_cmd_class,
+    cmd_dependency_write_fabric_pin_physical_location, hidden);
 }
 
 } /* end namespace openfpga */

openfpga/src/fabric/build_grid_module_duplicated_pins.cpp

@@ -123,8 +123,10 @@ void add_grid_module_duplicated_pb_type_ports(
             }
             BasicPort grid_port(port_name, 0, 0);
             /* Add the port to the module */
-            module_manager.add_port(grid_module, grid_port,
-                                    pin_type2type_map[pin_class_type]);
+            ModulePortId grid_port_id = module_manager.add_port(
+              grid_module, grid_port, pin_type2type_map[pin_class_type]);
+            /* Set port side */
+            module_manager.set_port_side(grid_module, grid_port_id, side);
           } else {
             /* For each DRIVER pin, we create two copies.
              * One with a postfix of upper, indicating it is located on the
@@ -136,15 +138,19 @@ void add_grid_module_duplicated_pb_type_ports(
               iwidth, iheight, subtile_index, side, pin_info, true);
             BasicPort grid_upper_port(upper_port_name, 0, 0);
             /* Add the port to the module */
-            module_manager.add_port(grid_module, grid_upper_port,
-                                    pin_type2type_map[pin_class_type]);
+            ModulePortId grid_upper_port_id = module_manager.add_port(
+              grid_module, grid_upper_port, pin_type2type_map[pin_class_type]);
+            /* Set port side */
+            module_manager.set_port_side(grid_module, grid_upper_port_id, side);
 
             std::string lower_port_name = generate_grid_duplicated_port_name(
               iwidth, iheight, subtile_index, side, pin_info, false);
             BasicPort grid_lower_port(lower_port_name, 0, 0);
             /* Add the port to the module */
-            module_manager.add_port(grid_module, grid_lower_port,
-                                    pin_type2type_map[pin_class_type]);
+            ModulePortId grid_lower_port_id = module_manager.add_port(
+              grid_module, grid_lower_port, pin_type2type_map[pin_class_type]);
+            /* Set port side */
+            module_manager.set_port_side(grid_module, grid_lower_port_id, side);
           }
         }
       }

openfpga/src/fabric/build_grid_modules.cpp

@@ -103,8 +103,10 @@ static void add_grid_module_pb_type_ports(
           }
           BasicPort grid_port(port_name, 0, 0);
           /* Add the port to the module */
-          module_manager.add_port(grid_module, grid_port,
-                                  pin_type2type_map[pin_class_type]);
+          ModulePortId grid_port_id = module_manager.add_port(
+            grid_module, grid_port, pin_type2type_map[pin_class_type]);
+          /* Set port side */
+          module_manager.set_port_side(grid_module, grid_port_id, side);
         }
       }
     }