[doc] add documentation about mock fpga wrapper

docs/source/manual/fpga_verilog/index.rst

@@ -10,3 +10,5 @@ FPGA-Verilog
    fabric_netlist
  
    testbench
+
+   mock_fpga_wrapper

docs/source/manual/fpga_verilog/mock_fpga_wrapper.rst

@@ -0,0 +1,25 @@
+.. _fpga_verilog_mock_fpga_wrapper:
+
+Mock FPGA Wrapper
+-----------------
+
+OpenFPGA can generates HDL netlists that model a complete eFPGA fabric (see details in :ref:`fabric_netlists`).
+Through bitstream forcing, users can verify the eFPGAs that are mapped by various applications in the context of SoC (see details in :numref:`fig_preconfig_module`).
+However, the complete eFPGA fabric is very costly in design verification runtime.
+To reduce runtime, a mock eFPGA wrapper is required to bridge the application HDL and other components in the SoC.
+As illustrated in :numref:`fig_mock_fpga_wrapper`, a 3-bit counter application is mapped to an FPGA, while a mock wrapper is interfacing the signals between the counter module and the SoC.
+The mock wrapper consists of the same ports as the FPGA fabric, which is generated by the OpenFPGA command ``write_fabric_verilog``. See :ref:`openfpga_verilog_commands` for its detailed usage. 
+The only difference lies in that the mock wrapper contains an instance of the application HDL design which is implemented on the FPGA, while the FPGA fabric contains a complete structure of programmable resources.
+
+.. note:: The mock wrapper is useful for connectivity checks on FPGA datapaths. It does not cover any configuration protocols (see details in :ref:`config_protocol`)
+
+
+.. _fig_mock_fpga_wrapper:
+
+.. figure:: figures/mock_fpga_wrapper.png
+   :width: 100%
+   :alt: Illustraion of a mock FPGA wrapper
+
+   Principles of a mock FPGA wrapper: ease SoC-level design verification
+
+

docs/source/manual/fpga_verilog/testbench.rst

@@ -22,7 +22,7 @@ To enable self-testing, the FPGA and user's RTL design (simulate using an HDL si
 .. _fig_verilog_testbench_organization:
 
 .. figure:: figures/full_testbench_block_diagram.svg
-   :scale: 50%
+   :width: 100%
    :alt: Verilog testbench principles
 
    Principles of Verilog testbenches: (1) using common input stimuli; (2) applying bitstream; (3) checking output vectors.
@@ -30,7 +30,7 @@ To enable self-testing, the FPGA and user's RTL design (simulate using an HDL si
 .. _fig_verilog_full_testbench_waveform:
 
 .. figure:: figures/full_testbench_waveform.svg
-   :scale: 50%
+   :width: 100%
    :alt: Full testbench waveform
 
    Illustration on the waveforms in full testbench
@@ -48,7 +48,7 @@ Formal-oriented Testbench
 The formal-oriented testbench aims to test a programmed FPGA is instantiated with the user's bitstream.
 The module of the programmed FPGA is encapsulated with the same port mapping as the user's RTL design and thus can be fed to a formal tool for a 100% coverage formal verification. Compared to the full testbench, this skips the time-consuming configuration phase, reducing the simulation time, potentially also significantly accelerating the functional verification, especially for large FPGAs.
 
-.. warning:: Formal-oriented testbenches do not validate the configuration protocol of FPGAs. It is used to  validate FPGA with a wide range of benchmarks.
+.. warning:: Formal-oriented testbenches do not validate the configuration protocol of FPGAs. It is used to validate FPGA with a wide range of benchmarks.
 
 General Usage
 ~~~~~~~~~~~~~
@@ -59,7 +59,7 @@ Inside the directory, the Verilog testbenches are organized as illustrated in :n
 .. _fig_verilog_testbench_hierarchy:
 
 .. figure:: ./figures/verilog_testbench_hierarchy.svg
-   :scale: 100%
+   :width: 100%
 
    Hierarchy of Verilog testbenches for a FPGA fabric implemented with an application
 
@@ -91,7 +91,7 @@ Inside the directory, the Verilog testbenches are organized as illustrated in :n
 .. _fig_preconfig_module:
 
 .. figure:: ./figures/preconfig_module.png
-   :scale: 25%
+   :width: 100%
 
    Internal structure of a pre-configured FPGA module
 

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

@@ -166,6 +166,41 @@ __ iverilog_website_
 
     Show verbose log
 
+write_mock_fpga_wrapper
+~~~~~~~~~~~~~~~~~~~~~~~
+ 
+  Write the Verilog wrapper which mockes a mapped FPGA fabric. See details in :ref:`fpga_verilog_mock_fpga_wrapper`.
+
+  .. option:: --file <string> or -f <string>
+     
+    The output directory for the netlists. We suggest the use of same output directory as fabric Verilog netlists. For example, ``--file /temp/testbench``
+
+  .. option:: --pin_constraints_file <string> or -pcf <string>
+
+    Specify the *Pin Constraints File* (PCF) if you want to custom stimulus in testbenches. For example, ``-pin_constraints_file pin_constraints.xml``
+    Strongly recommend for multi-clock simulations. See detailed file format about :ref:`file_format_pin_constraints_file`.
+
+  .. option:: --bus_group_file <string> or -bgf <string>
+
+    Specify the *Bus Group File* (BGF) if you want to group pins to buses. For example, ``-bgf bus_group.xml``
+    Strongly recommend when input HDL contains bus ports. See detailed file format about :ref:`file_format_bus_group_file`.
+
+  .. option:: --explicit_port_mapping
+
+    Use explicit port mapping when writing the Verilog netlists
+
+  .. option:: --default_net_type <string>
+
+    Specify the default net type for the Verilog netlists. Currently, supported types are ``none`` and ``wire``. Default value: ``none``.
+
+  .. option:: --no_time_stamp
+
+    Do not print time stamp in Verilog netlists
+
+  .. option:: --verbose
+
+    Show verbose log
+
 write_preconfigured_testbench
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~