From fbb5c0cf8f27184b40e7b55730b00aa9b49537a8 Mon Sep 17 00:00:00 2001
From: tangxifan <tangxifan@gmail.com>
Date: Tue, 19 Jan 2021 18:04:45 -0700
Subject: [PATCH] [Doc] Add pin constraints to documentation

---
 .../file_formats/pin_constraints_file.rst     | 25 +++++++++++++++++++
 docs/source/manual/index.rst                  |  2 ++
 .../fpga_verilog_commands.rst                 |  2 ++
 3 files changed, 29 insertions(+)
 create mode 100644 docs/source/manual/file_formats/pin_constraints_file.rst

diff --git a/docs/source/manual/file_formats/pin_constraints_file.rst b/docs/source/manual/file_formats/pin_constraints_file.rst
new file mode 100644
index 000000000..d810f5ffe
--- /dev/null
+++ b/docs/source/manual/file_formats/pin_constraints_file.rst
@@ -0,0 +1,25 @@
+.. _file_format_pin_constraints_file:
+
+Pin Constraints File
+--------------------
+
+The *Pin Constraints File* (PCF) aims to create pin binding between an implementation and an FPGA fabric
+
+An example of design constraints is shown as follows.
+
+.. code-block:: xml
+
+  <pin_constraints>
+    <set_io pin="clk[0]" net="clk0"/>
+    <set_io pin="clk[1]" net="clk1"/>
+    <set_io pin="clk[2]" net="OPEN"/>
+    <set_io pin="clk[3]" net="OPEN"/>
+  </pin_constraints>
+
+.. option:: pin="<string>"
+
+  The pin name of the FPGA fabric to be constrained, which should be a valid pin defined in OpenFPGA architecture description. Explicit index is required, e.g., ``clk[1:1]``. Otherwise, default index ``0`` will be considered, e.g., ``clk`` will be translated as ``clk[0:0]``.
+
+.. 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.
diff --git a/docs/source/manual/index.rst b/docs/source/manual/index.rst
index 65e5b13bb..a00dce30a 100644
--- a/docs/source/manual/index.rst
+++ b/docs/source/manual/index.rst
@@ -16,3 +16,5 @@
 
    fpga_bitstream/index
 
+   file_formats/index
+
diff --git a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst
index 667acb7c2..0c5137b91 100644
--- a/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst
+++ b/docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst
@@ -33,6 +33,8 @@ write_verilog_testbench
 
   - ``--reference_benchmark_file_path`` Must specify the reference benchmark Verilog file if you want to output any testbenches
 
+  - ``--pin_constraints_file`` specify the *Pin Constraints File* (PCF) if you want to custom stimulus in  testbenches. Strongly recommend for multi-clock simulations. See detailed file format about :ref:`file_format_pin_constraints_file`.
+
   - ``--fast_configuration`` Enable fast configuration phase for the top-level testbench in order to reduce runtime of simulations. It is applicable to configuration chain, memory bank and frame-based configuration protocols. For configuration chain, when enabled, the zeros at the head of the bitstream will be skipped. For memory bank and frame-based, when enabled, all the zero configuration bits will be skipped. So ensure that your memory cells can be correctly reset to zero with a reset signal. 
 
     .. note:: If both reset and set ports are defined in the circuit modeling for programming, OpenFPGA will pick the one that will bring largest benefit in speeding up configuration.