[Documentation] Update documentation about the multi-region configuration

docs/source/manual/arch_lang/config_protocol.rst

@@ -62,7 +62,14 @@ It will use the circuit model defined in :numref:`fig_ccff`.
 
 .. option:: num_regions="<int>"
 
-  Specify the number of configuration chains to be used across the fabrics. By default, it will be only 1 configuration chain. The more configuration chain to be used, the fast configuration runtime will be, but at the cost of more I/Os in the FPGA fabrics.
+  Specify the number of configuration chains to be used across the fabrics. By default, it will be only 1 configuration chain. The more configuration chain to be used, the fast configuration runtime will be, but at the cost of more I/Os in the FPGA fabrics. The organization of each configurable region can be customized through the fabric key (see details in :ref:`fabric_key`).
+
+.. figure:: figures/multi_region_config_chains.png
+   :scale: 100%
+   :alt: map to buried treasure
+ 
+   Examples of single- and multiple- region configuration chains
+
 
 Frame-based Example
 ~~~~~~~~~~~~~~~~~~~

docs/source/manual/arch_lang/fabric_key.rst

@@ -1,3 +1,5 @@
+.. _fabric_key:
+
 Fabric Key
 ~~~~~~~~~~
 
@@ -6,6 +8,12 @@ With this key, OpenFPGA can generate correct bitstreams for the FPGA.
 Using a wrong key, OpenFPGA may error out or generate wrong bitstreams.
 The fabric key support allows users to build secured/classified FPGA chips even with an open-source tool.
 
+.. figure:: figures/fabric_key_motivation.png
+   :scale: 60%
+   :alt: map to buried treasure
+ 
+   The use of fabric key to secure the FPGA chip design
+
 .. note:: Users are the only owner of the key. OpenFPGA will not store or replicate the key.
 
 Key Generation
@@ -19,7 +27,56 @@ A fabric key can be achieved in the following ways:
 File Format
 ```````````
 
-A fabric key follows an XML format. As shown in the following XML code, the key file includes the organization of configurable memory blocks in the top-level FPGA fabric: 
+A fabric key follows an XML format. As shown in the following XML code, the key file includes the organization of configurable blocks in the top-level FPGA fabric. 
+
+Configurable Region
+^^^^^^^^^^^^^^^^^^^
+
+The top-level FPGA fabric can consist of several configurable regions, where a region may contain one or multiple configurable blocks. Each configurable region can be configured independently and in parrallel.
+
+.. option:: <region id="<int>"/>
+
+  - ``id`` indicates the unique id of a configurable region in the fabric.
+
+  .. warning:: The id must start from zero!
+
+  .. note:: The number of regions defined in the fabric key must be consistent with the number of regions defined in the configuration protocol of architecture description. (See details in :ref:`config_protocol`).
+
+The following example shows how to define multiple configuration regions in the fabric key.
+
+.. code-block:: xml
+
+  <fabric_key>
+    <region id="0">
+      <key id="0" name="grid_io_bottom" value="0" alias="grid_io_bottom_1__0_"/>
+      <key id="1" name="grid_io_right" value="0" alias="grid_io_right_2__1_"/>
+      <key id="2" name="sb_1__1_" value="0" alias="sb_1__1_"/>
+    </region>
+    <region id="1">
+      <key id="3" name="cbx_1__1_" value="0" alias="cbx_1__1_"/>
+      <key id="4" name="grid_io_top" value="0" alias="grid_io_top_1__2_"/>
+      <key id="5" name="sb_0__1_" value="0" alias="sb_0__1_"/>
+    </region>
+    <region id="2">
+      <key id="6" name="sb_0__0_" value="0" alias="sb_0__0_"/>
+      <key id="7" name="cby_0__1_" value="0" alias="cby_0__1_"/>
+      <key id="8" name="grid_io_left" value="0" alias="grid_io_left_0__1_"/>
+    </region>
+    <region id="3">
+      <key id="9" name="sb_1__0_" value="0" alias="sb_1__0_"/>
+      <key id="10" name="cbx_1__0_" value="0" alias="cbx_1__0_"/>
+      <key id="11" name="cby_1__1_" value="0" alias="cby_1__1_"/>
+      <key id="12" name="grid_clb" value="0" alias="grid_clb_1__1_"/>
+    </region>
+  </fabric_key>
+
+
+Configurable Block
+^^^^^^^^^^^^^^^^^^^
+
+Each configurable block is defined as a key. There are two ways to define a key, either with alias or with name and value. 
+
+.. option:: <key id="<int>" alias="<string>" name="<string>" value="<int>"/>
 
   - ``id`` indicates the sequence of the configurable memory block in the top-level FPGA fabric.
 
@@ -29,7 +86,7 @@ A fabric key follows an XML format. As shown in the following XML code, the key
 
   - ``alias`` indicates the instance name of the configurable memory block in the top-level FPGA fabric. If a valid alias is specified, the ``name`` and ``value`` are not required.
 
-.. note:: For fast loading of fabric key, strongly recommend to use pairs ``name`` and ``alias`` or ``name`` and ``value`` in the fabric key file. Using only ``alias`` may cause long parsing time for fabric key. 
+.. warning:: For fast loading of fabric key, strongly recommend to use pairs ``name`` and ``alias`` or ``name`` and ``value`` in the fabric key file. Using only ``alias`` may cause long parsing time for fabric key. 
 
 The following is an example of a fabric key generate by OpenFPGA for a 2 :math:`\times` 2 FPGA.
 This key contains only ``alias`` which is easy to craft.
@@ -37,6 +94,7 @@ This key contains only ``alias`` which is easy to craft.
 .. code-block:: xml
 
   <fabric_key>
+    <region id="0">
       <key id="0" alias="sb_2__2_"/>
       <key id="1" alias="grid_clb_2_2"/>
       <key id="2" alias="sb_0__1_"/>
@@ -70,6 +128,7 @@ This key contains only ``alias`` which is easy to craft.
       <key id="30" alias="cbx_1__1_"/>
       <key id="31" alias="grid_io_top_1_3"/>
       <key id="32" alias="grid_io_left_0_2"/>
+    </region>
   </fabric_key>
 
 The following shows another example of a fabric key generate by OpenFPGA for a 2 :math:`\times` 2 FPGA.
@@ -78,6 +137,7 @@ This key contains only ``name`` and ``value`` which is fast to parse.
 .. code-block:: xml
 
   <fabric_key>
+    <region id="0">
       <key id="0" name="sb_2__2_" value="0"/>
       <key id="1" name="grid_clb" value="3"/>
       <key id="2" name="sb_0__1_" value="0"/>
@@ -111,4 +171,7 @@ This key contains only ``name`` and ``value`` which is fast to parse.
       <key id="30" name="cbx_1__1_" value="0"/>
       <key id="31" name="grid_io_top" value="0"/>
       <key id="32" name="grid_io_left" value="1"/>
+    </region>
   </fabric_key>
+
+