From ff0faeb2855e0403cf43ec617b65eb2719aac1dc Mon Sep 17 00:00:00 2001
From: tangxifan <tangxifan@gmail.com>
Date: Wed, 10 Mar 2021 21:41:59 -0700
Subject: [PATCH] [Doc] Update documentation about the extended bitstream
 setting

---
 docs/source/manual/arch_lang/annotate_vpr_arch.rst |  2 ++
 .../manual/file_formats/bitstream_setting.rst      | 14 ++++++++++++--
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/docs/source/manual/arch_lang/annotate_vpr_arch.rst b/docs/source/manual/arch_lang/annotate_vpr_arch.rst
index ea128cb1c..239d10dfb 100644
--- a/docs/source/manual/arch_lang/annotate_vpr_arch.rst
+++ b/docs/source/manual/arch_lang/annotate_vpr_arch.rst
@@ -136,6 +136,8 @@ When a global port, e.g., ``clk``, is defined in ``tile_annotation`` using the f
 
 Clock port ``clk`` of each ``clb`` tile will be connected to a common clock port of the top module, while local clock network is customizable through VPR's architecture description language. For instance, the local clock network can be a programmable clock network. 
 
+.. _annotate_vpr_arch_pb_type_annotation:
+
 Primitive Blocks inside Multi-mode Configurable Logic Blocks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/source/manual/file_formats/bitstream_setting.rst b/docs/source/manual/file_formats/bitstream_setting.rst
index b21bd0c25..d5d4649b4 100644
--- a/docs/source/manual/file_formats/bitstream_setting.rst
+++ b/docs/source/manual/file_formats/bitstream_setting.rst
@@ -9,7 +9,7 @@ This can define a hard-coded bitstream for a reconfigurable resource in FPGA fab
 .. code-block:: xml
 
   <openfpga_bitstream_setting>
-    <pb_type name="<string>" source="eblif" content=".param LUT"/>
+    <pb_type name="<string>" source="eblif" content=".param LUT" is_mode_select_bistream="true" bitstream_offset="1"/>
   </openfpga_bitstream_setting>
 
 .. option:: pb_type="<string>"
@@ -24,4 +24,14 @@ This can define a hard-coded bitstream for a reconfigurable resource in FPGA fab
 
   The content of the ``pb_type`` bitstream, which could be a keyword in a ``.eblif`` file. For example, ``content=".attr LUT"`` means that the bitstream will be extracted from the ``.attr LUT`` line which is defined under the ``.blif model`` (that is defined under the ``pb_type`` in VPR architecture file).
   
-.. warning:: Bitstream is a feature for power-users. It may cause wrong bitstream to be generated. For example, the hard-coded bitstream is not compatible with LUTs whose nets may be swapped during routing stage (cause a change on the truth table as well as bitstream). It is users's responsibility to ensure correct bitstream.
+
+.. option:: is_mode_select_bitstream="<bool>"
+
+  Can be either ``true`` or ``false``. When set ``true``, the bitstream is considered as mode-selection bitstream, which may overwrite ``mode_bits`` definition in ``pb_type_annotation`` of OpenFPGA architecture description. (See details in :ref:`annotate_vpr_arch_pb_type_annotation`)
+
+.. option:: bitstream_offset="<int>"
+
+  Specify the offset to be applied when overloading the bitstream to a target. For example, a LUT may have a 16-bit bitstream. When ``offset=1``, bitstream overloading will skip the first bit and start from the second bit of the 16-bit bitstream.
+
+.. warning:: Bitstream setting is a feature for power-users. It may cause wrong bitstream to be generated. For example, the hard-coded bitstream is not compatible with LUTs whose nets may be swapped during routing stage (cause a change on the truth table as well as bitstream). It is users's responsibility to ensure correct bitstream.
+