From e5b47b7d3d368478a05c2027981d87519728410e Mon Sep 17 00:00:00 2001
From: tangxifan <tangxifan@gmail.com>
Date: Sat, 10 Apr 2021 15:45:39 -0600
Subject: [PATCH] [Doc] Update documentation on the changes on fabric bitstream
 file formats

---
 .../manual/file_formats/fabric_bitstream.rst  | 49 +++++++++++++++++--
 1 file changed, 44 insertions(+), 5 deletions(-)

diff --git a/docs/source/manual/file_formats/fabric_bitstream.rst b/docs/source/manual/file_formats/fabric_bitstream.rst
index ce321cc81..11faca959 100644
--- a/docs/source/manual/file_formats/fabric_bitstream.rst
+++ b/docs/source/manual/file_formats/fabric_bitstream.rst
@@ -19,11 +19,31 @@ The information depends on the type of configuration procotol.
 
 .. option:: scan_chain
 
-  A line consisting of ``0`` | ``1``
+  Multiple lines consisting of ``0`` | ``1``
+
+  For example, a bitstream for 1 configuration regions:
+
+  .. code-block:: xml 
+
+     0
+     1
+     0
+     0
+
+  For example, a bitstream for 4 configuration regions:
+
+  .. code-block:: xml 
+
+     0000
+     1010
+     0110
+     0120
+
+  .. note:: When there are multiple configuration regions, each line may consist of multiple bits. For example, ``0110`` represents the bits for 4 configuration regions, where the 4 digits correspond to the bits from region ``0, 1, 2, 3`` respectively.
 
 .. option:: memory_bank
 
-  Multiple lines will be included, each of which is organized as <address><space><bit>.
+  Multiple lines will be included, each of which is organized as <address><space><bits>.
   Note that due to the use of Bit-Line and Word-Line decoders, every two lines are paired.
   The first line represents the Bit-Line address and configuration bit.
   The second line represents the Word-Line address and configuration bit.
@@ -39,11 +59,15 @@ The information depends on the type of configuration procotol.
      <bitline_address> <bit_value> 
      <wordline_address> <bit_value> 
 
+  .. note:: When there are multiple configuration regions, each ``<bit_value>`` may consist of multiple bits. For example, ``0110`` represents the bits for 4 configuration regions, where the 4 digits correspond to the bits from region ``0, 1, 2, 3`` respectively.
+
 .. option:: frame_based 
 
-  Multiple lines will be included, each of which is organized as <address><space><bit>.
+  Multiple lines will be included, each of which is organized as <address><space><bits>.
   Note that the address may include don't care bit which is denoted as ``x``.
-  OpenFPGA automatically convert don't care bit to logic ``0`` when generating testbenches.
+
+  .. note:: OpenFPGA automatically convert don't care bit to logic ``0`` when generating testbenches.
+
   For example
    
   .. code-block:: xml 
@@ -53,6 +77,7 @@ The information depends on the type of configuration procotol.
      ...
      <frame_address> <bit_value> 
 
+  .. note:: When there are multiple configuration regions, each ``<bit_value>`` may consist of multiple bits. For example, ``0110`` represents the bits for 4 configuration regions, where the 4 digits correspond to the bits from region ``0, 1, 2, 3`` respectively.
 
 .. _file_formats_fabric_bitstream_xml:
 
@@ -61,7 +86,21 @@ XML (.xml)
 
 This file format is designed to generate testbenches using external tools, e.g., CocoTB.
 
-In principle, the file consist a number of XML node ``<bit>``, each bit contains the following attributes:
+In principle, the file consist a number of XML node ``<region>``, each region has a unique id, and contains a number of XML nodes ``<bit>``.
+
+- ``id``: The unique id of a configuration region in the fabric bitstream.
+
+A quick example:
+
+.. code-block:: xml
+
+  <region id="0">
+    <bit id="0" value="1" path="fpga_top.grid_clb_1__2_.logical_tile_clb_mode_clb__0.mem_fle_9_in_5.mem_out[0]"/>
+    </bit>
+  </region>
+
+
+Each XML node ``<bit>`` contains the following attributes:
 
 - ``id``: The unique id of the configuration bit in the fabric bitstream.