[doc] add example file and file format details

docs/source/manual/file_formats/fabric_hierarchy_file.rst

@@ -0,0 +1,61 @@
+.. _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_``.
+
+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

@@ -368,7 +368,7 @@ write_fabric_hierarchy
   
   .. 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>