[Doc] Add repack design constraints to documentation

docs/source/manual/fpga_bitstream/index.rst

@@ -12,3 +12,5 @@ FPGA-Bitstream can generate two types of bitstreams:
    generic_bitstream
 
    fabric_dependent_bitstream
+
+   repack_design_constraints

docs/source/manual/fpga_bitstream/repack_design_constraints.rst

@@ -0,0 +1,29 @@
+.. _fpga_bitstream_repack_design_constraints:
+
+Repack Design Constraints
+-------------------------
+
+An example of design constraints is shown as follows.
+
+.. code-block:: xml
+
+  <repack_design_constraints>
+    <pin_constraint pb_type="clb" pin="clk[0]" net="clk0"/>
+    <pin_constraint pb_type="clb" pin="clk[1]" net="clk1"/>
+    <pin_constraint pb_type="clb" pin="clk[2]" net="OPEN"/>
+    <pin_constraint pb_type="clb" pin="clk[3]" net="OPEN"/>
+  </repack_design_constraints>
+
+.. option:: pb_type="<string>"
+
+  The pb_type name to be constrained, which should be consistent with VPR's architecture description.
+
+.. option:: pin="<string>"
+
+  The pin name of the ``pb_type`` to be constrained, which should be consistent with VPR's architecture description.
+
+.. option:: net="<string>"
+
+  The net name of the pin to be mapped, which should be consistent with net definition in your ``.blif`` file. The reserved word ``OPEN`` means that no net should be mapped to a given pin. Please ensure that it is not conflicted with any net names in your ``.blif`` file.
+  
+.. warning:: Design constraints is a feature for power-users. It may cause repack to fail. It is users's responsibility to ensure proper design constraints

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

@@ -6,11 +6,28 @@ FPGA-Bitstream
 repack
 ~~~~~~
 
-  Repack the netlist to physical pbs
+Repack the netlist to physical pbs
+Repack is an essential procedure before building a bitstream, which aims to packing each programmable blocks by considering **only** the physical modes.
+Repack's functionality are in the following aspects:
 
-  .. note:: This must be done before bitstream generator and testbench generation. Strongly recommend it is done after all the fix-up have been applied
+- It annotates the net mapping results from operating modes (considered by VPR) to the physical modes (considered by OpenFPGA)
 
-  - ``--verbose`` Show verbose log
+- It re-routes all the nets by considering the programmable interconnects in physical modes **only**.
+
+.. note:: This must be done before bitstream generator and testbench generation. Strongly recommend it is done after all the fix-up have been applied
+
+.. option:: --design_constraints 
+
+  Apply design constraints from an external file. 
+  Normally, repack takes the net mapping from VPR packing and routing results. 
+  Alternatively, repack can accept the design constraints, in particular, net remapping, from an XML-based design constraint description.
+  See details in :ref:`fpga_bitstream_repack_design_constraints`.
+
+.. warning:: Design constraints are designed to help repacker to identify which clock net to be mapped to which pin, so that multi-clock benchmarks can be correctly implemented, in the case that VPR may not have sufficient vision on clock net mapping. **Try not to use design constraints to remap any other types of nets!!!**
+   
+.. option:: --verbose 
+
+  Show verbose log
 
 build_architecture_bitstream
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~