update documentation: the addon syntax on VPR and configuration protocols

docs/source/arch_lang/addon_vpr_syntax.rst

@@ -5,11 +5,18 @@ Additional Syntax to Original VPR XML
 
 .. warning:: Note this is only applicable to VPR8!
 
+Models, Complex blocks and Physical Tiles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   
 Each ``<pb_type>`` should contain a ``<mode>`` that describe the physical implementation of the ``<pb_type>``. Note that this is fully compatible to the VPR architecture XML syntax.
   
 ``<model>`` should include the models that describe the primitive ``<pb_type>`` in physical mode.
   
+.. note:: Currently, OpenFPGA only supports 1 ``<equivalent_sites>`` to be defined under each ``<tile>``
+
+Layout
+~~~~~~
+
 ``<layout>`` may include additioinal syntax to enable tileable routing resource graph generation
 
 .. option:: tileable="<bool>"
@@ -35,15 +42,27 @@ Each ``<pb_type>`` should contain a ``<mode>`` that describe the physical implem
   
      Impact on routing architecture when through channel in multi-width and multi-height programmable blocks: (a) disabled; (b) enabled.
 
-  .. warning:: Do NOT enable if you are not using the tileable routing resource graph generator!
+  .. warning:: Do NOT enable ``through_channel`` if you are not using the tileable routing resource graph generator!
+  
+  .. warning:: Currently ``through_channel`` supports only a fixed routing channel width!
 
-  .. warning:: Current through channel supports only a fixed routing channel!
+
+A quick example to show tileable routing is enabled and through channels are disabled:
+
+.. code-block:: xml
+
+  <layout tileable="true" through_channel="false">
+  </layout>
+
+Switch Block
+~~~~~~~~~~~~
 
 ``<switch_block>`` may include addition syntax to enable different connectivity for pass tracks
 
 .. option:: sub_type="<string>"
   
   Connecting type for pass tracks in each switch block
+  The supported connecting patterns are ``subset``, ``universal`` and ``wilton``, being the same as VPR capability
   If not specified, the pass tracks will the same connecting patterns as start/end tracks, which are defined in ``type``
 
 .. option:: sub_Fs="<int>"
@@ -51,10 +70,31 @@ Each ``<pb_type>`` should contain a ``<mode>`` that describe the physical implem
   Connectivity parameter for pass tracks in each switch block. Must be a multiple of 3.
   If not specified, the pass tracks will the same connectivity as start/end tracks, which are defined in ``fs``
 
+A quick example which defines a switch block
+  - Starting/ending routing tracks are connected in the ``wilton`` pattern
+  - Each starting/ending routing track can drive 3 other starting/ending routing tracks
+  - Passing routing tracks are connected in the ``subset`` pattern
+  - Each passing routing track can drive 6 other starting/ending routing tracks
+
+.. code-block:: xml
+
+  <device>
+    <switch_block type="wilton" fs="3" sub_type="subset" sub_fs="6"/>
+  </device>
+
+Routing Segments
+~~~~~~~~~~~~~~~~
+
+OpenFPGA suggests users to give explicit names for each routing segement in ``<segmentlist>`` 
+This is used to link ``circuit_model`` to routing segments.
+
+A quick example which defines a length-4 uni-directional routing segment called ``L4`` :
+
+.. code-block:: xml
+
+  <segmentlist>
+    <segment name="L4" freq="1" length="4" type="undir"/>
+  </segmentlist>
+
 .. note:: Currently, OpenFPGA only supports uni-directional routing architectures
 
-.. note:: Currently, OpenFPGA only supports 1 ``<equivalent_sites>`` to be defined under each ``<tile>``
-
-.. note:: OpenFPGA require explicit names to be defined for each routing segement in ``<segmentlist>`` 
-
-

docs/source/arch_lang/annotate_vpr_arch.rst

@@ -7,27 +7,82 @@ Each defined circuit model should be linked to an FPGA module defined in the ori
 Configuration Protocol
 ~~~~~~~~~~~~~~~~~~~~~~
 
+Configuration protocol is the circuitry designed to program an FPGA.
+As an interface, configuration protocol could be really different in FPGAs, depending on the application context.
+
+Template
+````````
+
 .. code-block:: xml
 
   <configuration_protocol>
     <organization type="<string>" circuit_model_name="<string>"/>
   </configuration_protocol>
 
-- ``type="scan_chain|memory_bank|standalone"`` Specify the type of configuration circuits.
+.. option:: type="scan_chain|memory_bank|standalone"
 
-:numref:`fig_sram` illustrates an example where a memory organization using memory decoders and 6-transistor SRAMs.
+  Specify the type of configuration circuits.
+
+  OpenFPGA supports different types of configuration protocols to program FPGA fabrics:
+    - ``scan_chain``: configurable memories are connected in a chain. Bitstream is loaded serially to program a FPGA
+    - ``memory_bank``: configurable memories are organized in an array, where each element can be accessed by an unique address to the BL/WL decoders
+    - ``standalone``: configurable memories are directly accessed through ports of FPGA fabrics. In other words, there are no protocol to control the memories. This allows full customization on the configuration protocol for hardware engineers.
+
+  .. note:: Avoid to use ``standalone`` when designing an FPGA chip. It will causes a huge number of I/Os required, far beyond any package size. It is well applicable to eFPGAs, where designers do need customized protocols between FPGA and processors. 
+
+.. warning:: Currently FPGA-SPICE only supports standalone memory organization.
+
+.. warning:: Currently RRAM-based FPGA only supports memory-bank organization for Verilog Generator.
+
+.. option:: circuit_model_name="<string>"
+
+  Specify the name of circuit model to be used as configurable memory.
+  - ``scan_chain`` requires a circuit model type of ``ccff``
+  - ``memory_bank`` requires a circuit model type of ``sram``
+  - ``standalone`` requires a circuit model type of ``sram``
+
+Configuration Chain Example
+```````````````````````````
+The following XML code describes a scan-chain circuitry to configure the core logic of FPGA, as illustrated in :numref:`fig_ccff_fpga`.
+It will use the circuit model defined in :ref:`circuit_model_examples`.
+
+.. code-block:: xml
+
+  <configuration_protocol>
+    <organization type="scan_chain" circuit_model_name="ccff"/>
+  </configuration_protocol>
+
+.. _fig_ccff_fpga:
+
+.. figure:: figures/ccff_fpga.png
+   :scale: 60%
+   :alt: map to buried treasure
+ 
+   Example of a configuration chain to program core logic of a FPGA 
+
+Memory bank Example
+```````````````````
+The following XML code describes a memory-bank circuitry to configure the core logic of FPGA, as illustrated in :numref:`fig_sram`.
+It will use the circuit model defined in :ref:`circuit_model_examples`.
+
+.. code-block:: xml
+
+  <configuration_protocol>
+    <organization type="memory_bank" circuit_model_name="sram"/>
+  </configuration_protocol>
 
 .. _fig_sram:
 
 .. figure:: figures/sram.png
-   :scale: 100%
+   :scale: 60%
    :alt: map to buried treasure
  
    Example of a memory organization using memory decoders 
 
-.. note:: Currently FPGA-SPICE only supports standalone memory organization.
+Standalone SRAM Example
+```````````````````````
 
-.. note:: Currently RRAM-based FPGA only supports memory-bank organization for Verilog Generator.
+.. warning:: TO BE CONSTRUCTED
 
 Switch Blocks
 ~~~~~~~~~~~~~

docs/source/arch_lang/circuit_model_examples.rst

@@ -734,7 +734,7 @@ The code describing this wire is:
 
 This example shows
   - A routing track wire has 1 input and output 
-  - The routing wire will be modelled as a 1-level π-type RC wire model with a total resistance of 103.84Ohm and a total capacitance of 13.89fF
+  - The routing wire will be modelled as a 1-level π-type RC wire model with a total resistance of :math:`103.84\Omega` and a total capacitance of :math:`13.89fF`
 
 I/O pads
 ~~~~~~~~
@@ -790,4 +790,4 @@ This example shows
   - A general purpose I/O cell defined in Verilog netlist ``io.sp`` and SPICE netlist ``io.sp`` 
   - The I/O cell has an ``inout`` port as the bi-directional port
   - The directionality of I/O can be controlled by a configuration-chain flip-flop defined in circuit model ``ccff``
-  - If unused, the I/O cell have be configured to '1'
+  - If unused, the I/O cell will be configured to ``1``