Merge pull request #1645 from lnis-uofu/xt_fhie

Flexible outputs on command write_fabric_hierarchy

docs/source/manual/file_formats/fabric_hierarchy_file.rst

@@ -0,0 +1,62 @@
+.. _file_format_fabric_hierarchy_file:
+
+Fabric Hierarchy File (.yaml)
+----------------------------------------
+
+This file is generated by command :ref:`openfpga_setup_commands_write_fabric_hierarchy`
+
+
+The fabric hierarchy file aims to show module trees of a number of given roots
+
+This file is created for netlist manipulation and detailed floorplanning during physical design steps
+
+By using the options of the command :ref:`openfpga_setup_commands_write_fabric_hierarchy`, user can selectively output the module tree on their needs.
+
+An example of the file is shown as follows.
+
+.. code-block:: yaml
+
+  fpga_top:
+    tile_0__2_:
+      sb_0__1_:
+        mux_tree_tapbuf_size2:
+          INVTX1
+          const1
+          tap_buf4
+          mux_tree_tapbuf_basis_input2_mem1:
+            - TGATE
+        mux_tree_tapbuf_size2_feedthrough_mem
+        sb_1__config_group_mem_size40:
+          mux_tree_tapbuf_size2_mem:
+            - DFF
+    tile_1__2_:
+      grid_io_top:
+        logical_tile_io_mode_io_:
+          logical_tile_io_mode_physical__iopad:
+            - GPIO
+            - GPIO_feedthrough_DFF_mem
+          direct_interc
+
+In this example, the root module is ``fpga_top``.
+The child modules under ``fpga_top`` are ``tile_0__2_`` and ``tile_1__2_``.
+Note that the leaf nodes are shown as a list, e.g., ``GPIO`` and ``GPIO_feedthrough_DFF_mem``.
+
+When multiple root modules are defined, the output could be
+
+.. code-block:: yaml
+
+  sb_0__1_:
+    - mux_tree_tapbuf_size2
+  sb_1__0_:
+    - mux_tree_tapbuf_size2
+  sb_1__1_:
+    - mux_tree_tapbuf_size2
+  cbx_1__0_:
+    - mux_tree_tapbuf_size4
+  cbx_1__1_:
+    - mux_tree_tapbuf_size4
+  cby_0__1_:
+    - mux_tree_tapbuf_size2
+    - mux_tree_tapbuf_size4
+  cby_1__1_:
+    - mux_tree_tapbuf_size4

docs/source/manual/file_formats/index.rst

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

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

@@ -359,20 +359,33 @@ add_fpga_core_to_fabric
 
     Show verbose log
 
+.. _openfpga_setup_commands_write_fabric_hierarchy:
 
 write_fabric_hierarchy
 ~~~~~~~~~~~~~~~~~~~~~~
 
-  Write the hierarchy of FPGA fabric graph to a plain-text file
+  Write the hierarchy of FPGA fabric graph to a YAML file
 
   .. option:: --file <string> or -f <string>
 
-    Specify the file name to write the hierarchy. 
+    Specify the file name to write the hierarchy.  See details in :ref:`file_format_fabric_hierarchy_file`.
 
   .. option:: --depth <int>
 
     Specify at which depth of the fabric module graph should the writer stop outputting. The root module start from depth 0. For example, if you want a two-level hierarchy, you should specify depth as 1. 
 
+  .. option:: --module <regexp>
+
+    Specify the root module name(s) which should be considered. By default, it is ``fpga_top``. Note that regular expression is supported. For example, ``grid_*`` will output all the modules with a prefix of ``grid_``
+
+  .. option:: --filter <regexp>
+
+    Specify the filter which allows user to select modules to appear under each root module tree. By default, it is ``*``. Regular expression is supported. For example, ``*mux*`` will output all the modules which contains ``mux``. In the other words, the filter defines a white list.
+
+  .. option:: --exclude_empty_modules
+
+    Exclude modules with no qualified children (match the names defined through filter) from the output file
+
   .. option:: --verbose
 
     Show verbose log

openfpga/src/base/openfpga_build_fabric_template.h

@@ -270,6 +270,8 @@ template <class T>
 int write_fabric_hierarchy_template(const T& openfpga_ctx, const Command& cmd,
                                     const CommandContext& cmd_context) {
   CommandOptionId opt_verbose = cmd.option("verbose");
+  CommandOptionId opt_exclude_empty_modules =
+    cmd.option("exclude_empty_modules");
 
   /* Check the option '--file' is enabled or not
    * Actually, it must be enabled as the shell interface will check
@@ -279,6 +281,19 @@ int write_fabric_hierarchy_template(const T& openfpga_ctx, const Command& cmd,
   VTR_ASSERT(true == cmd_context.option_enable(cmd, opt_file));
   VTR_ASSERT(false == cmd_context.option_value(cmd, opt_file).empty());
 
+  CommandOptionId opt_module = cmd.option("module");
+  std::string root_module =
+    openfpga_ctx.module_name_map().name(generate_fpga_top_module_name());
+  if (true == cmd_context.option_enable(cmd, opt_module)) {
+    root_module = cmd_context.option_value(cmd, opt_module);
+  }
+
+  CommandOptionId opt_filter = cmd.option("filter");
+  std::string filter("*");
+  if (true == cmd_context.option_enable(cmd, opt_filter)) {
+    filter = cmd_context.option_value(cmd, opt_filter);
+  }
+
   /* Default depth requirement, will not stop until the leaf */
   int depth = -1;
   CommandOptionId opt_depth = cmd.option("depth");
@@ -297,7 +312,9 @@ int write_fabric_hierarchy_template(const T& openfpga_ctx, const Command& cmd,
   /* Write hierarchy to a file */
   return write_fabric_hierarchy_to_text_file(
     openfpga_ctx.module_graph(), openfpga_ctx.module_name_map(), hie_file_name,
-    size_t(depth), cmd_context.option_enable(cmd, opt_verbose));
+    root_module, filter, size_t(depth),
+    cmd_context.option_enable(cmd, opt_exclude_empty_modules),
+    cmd_context.option_enable(cmd, opt_verbose));
 }
 
 /********************************************************************

openfpga/src/base/openfpga_setup_command_template.h

@@ -461,12 +461,29 @@ ShellCommandId add_write_fabric_hierarchy_command_template(
   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 root module name(s) which should be considered. By default, "
+    "it is fpga_top. Regular expression is supported");
+  shell_cmd.set_option_require_value(opt_module, openfpga::OPT_STRING);
+  CommandOptionId opt_filter =
+    shell_cmd.add_option("filter", false,
+                         "Specify the filter which allows user to select "
+                         "modules to appear under each root module tree. By "
+                         "default, it is *. Regular expression is supported");
+  shell_cmd.set_option_require_value(opt_filter, openfpga::OPT_STRING);
+
   /* Add an option '--depth' */
   CommandOptionId opt_depth = shell_cmd.add_option(
     "depth", false,
     "Specify the depth of hierarchy to which the writer should stop");
   shell_cmd.set_option_require_value(opt_depth, openfpga::OPT_INT);
 
+  shell_cmd.add_option("exclude_empty_modules", false,
+                       "Exclude modules with no qualified children (match the "
+                       "names defined through filter) from the output file");
+
   /* Add an option '--verbose' */
   shell_cmd.add_option("verbose", false, "Show verbose outputs");