From 263eb6b7fb70c3f34e75813dced6281afa297f5b Mon Sep 17 00:00:00 2001
From: Jingrong Lin <145083116+treelin611@users.noreply.github.com>
Date: Wed, 4 Sep 2024 15:14:41 +0800
Subject: [PATCH] Update unique_blocks.rst
---
.../manual/file_formats/unique_blocks.rst | 317 +++---------------
1 file changed, 40 insertions(+), 277 deletions(-)
diff --git a/docs/source/manual/file_formats/unique_blocks.rst b/docs/source/manual/file_formats/unique_blocks.rst
index e35c8d844..0445de969 100644
--- a/docs/source/manual/file_formats/unique_blocks.rst
+++ b/docs/source/manual/file_formats/unique_blocks.rst
@@ -1,299 +1,62 @@
-.. _file_formats_fabric_key:
+.. _file_formats_unique_blocks:
-Fabric Key (.xml)
+Unique Blocks (.xml)
~~~~~~~~~~~~~~~~~
-A fabric key follows an XML format. As shown in the following XML code, the key file includes the organization of configurable blocks in the top-level FPGA fabric.
-
-Configurable Module
-^^^^^^^^^^^^^^^^^^^
-
-Fabric key can be applied to various modules. Each module can be a top-level FPGA fabric, or a submodule of the FPGA fabric.
-
-.. option::
-
- Under each module, a set of keys can be defined. Note that for the top-level FPGA fabric, not only keys but also regions and shift-register banks can be defined. For non-top-level module, only keys are allowed.
-
- - ``name`` indicates the unique name of a valid module in FPGA fabric. Note that ``fpga_top`` is the considered as the module name of the top-level FPGA fabric.
-
- .. note:: ``fpga_core`` is not applicable to fabric key.
-
-Configurable Region
-^^^^^^^^^^^^^^^^^^^
-
-The top-level FPGA fabric can consist of several configurable regions, where a region may contain one or multiple configurable blocks. Each configurable region can be configured independently and in parrallel.
-
-.. option::
-
- - ``id`` indicates the unique id of a configurable region in the fabric.
-
- .. warning:: The id must start from zero!
-
- .. note:: The number of regions defined in the fabric key must be consistent with the number of regions defined in the configuration protocol of architecture description. (See details in :ref:`config_protocol`).
-
-The following example shows how to define multiple configuration regions in the fabric key.
-
-.. code-block:: xml
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+A unique blocks file is formatted in XML. The unique blocks can be of type ``cbx``, ``cby`` or ``sb``. As illustrated by the XML code below, the file includes the type and coordinates of these unique blocks, as well as the coordinates of their corresponding instances.
Configurable Block
^^^^^^^^^^^^^^^^^^^
-Each configurable block is defined as a key. There are two ways to define a key, either with alias or with name and value.
+Unique blocks can be applied to various blocks, each of which can be of type ``cbx``, ``cby`` or ``sb``, and may have different coordinates.
-.. option::
+.. option::
- - ``id`` indicates the sequence of the configurable memory block in the top-level FPGA fabric.
+ For each block, a set of keys can be defined. For unique blocks, both keys and instances can be specified. However, if a unique block does not have an instance, only keys are permitted.
+
+ - ``type`` specifies the type of the unique block in the FPGA fabric. Valid values for ``type`` are ``cbx``, ``cby`` or ``sb``.
- - ``name`` indicates the module name of the configurable memory block. This property becomes optional when ``alias`` is defined.
+ - ``x`` represents the x-coordinate of the unique block.
- - ``value`` indicates the instance id of the configurable memory block in the top-level FPGA fabric. This property becomes optional when ``alias`` is defined.
+ - ``y`` represents the y-coordinate of the unique block.
- - ``alias`` indicates the instance name of the configurable memory block in the top-level FPGA fabric. If a valid alias is specified, the ``name`` and ``value`` are not required.
+Configurable Instance
+^^^^^^^^^^^^^^^^^^^
- - ``column`` indicates the relative x coordinate for a configurable memory in a configurable region at the top-level FPGA fabric. This is required when the memory bank protocol is selection.
+A specific unique block can have multiple instances, where each instance is a mirrored version of the unique block. Each instance shares the same type as its parent block and includes information about its coordinates.
- .. note:: The configurable memory blocks in the same column will share the same Bit Line (BL) bus
+.. option::
- - ``row`` indicates the relative y coordinate for a configurable memory in a configurable region at the top-level FPGA fabric. This is required when the memory bank protocol is selection.
+ - ``x`` specifies the x-coordinate of the instance.
- .. note:: The configurable memory blocks in the same row will share the same Word Line (WL) bus
+ - ``y`` specifies the y-coordinate of the instance.
-.. warning:: For fast loading of fabric key, strongly recommend to use pairs ``name`` and ``alias`` or ``name`` and ``value`` in the fabric key file. Using only ``alias`` may cause long parsing time for fabric key.
-The following is an example of a fabric key generate by OpenFPGA for a 2 :math:`\times` 2 FPGA.
-This key contains only ``alias`` which is easy to craft.
+The following content provides an example of a unique block file:
.. code-block:: xml
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-The following shows another example of a fabric key generate by OpenFPGA for a 2 :math:`\times` 2 FPGA.
-This key contains only ``name`` and ``value`` which is fast to parse.
-
-.. code-block:: xml
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-The following shows another example of a fabric key generate by OpenFPGA for a 2 :math:`\times` 2 FPGA using memory bank.
-This key contains only ``name``, ``value``, ``row`` and ``column``.
-
-.. code-block:: xml
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-BL Shift Register Banks
-^^^^^^^^^^^^^^^^^^^^^^^
-
-.. note:: The customizable is only available when the shift-register-based memory bank is selected in :ref:`config_protocol`
-
-Each Bit-Line (BL) shift register bank is defined in the code block ````.
-A shift register bank may contain multiple shift register chains.
-- each shift register chain can be defined using the ``bank`` syntax
-- the BLs controlled by each chain can be customized through the ``range`` syntax.
-
-.. option::
-
- - ``id`` indicates the sequence of the shift register chain in the bank. The id denotes the index in the head or tail bus. For example, ``id="0"`` means the head or tail of the shift register will be in the first bit of a head bus ``head[0:4]``
-
- - ``range`` indicates ``BL`` port to be controlled by this shift register chain. Multiple BL ports can be defined but the sequence matters. For example, ``bl[0:3], bl[6:10]`` infers a 9-bit shift register chain whose output ports are connected from ``bl[0]`` to ``bl[10]``.
-
- .. note:: When creating the range, you must know the number of BLs in the configuration region
-
- .. note:: ports must use ``bl`` as the reserved port name
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-WL Shift Register Banks
-^^^^^^^^^^^^^^^^^^^^^^^
-
-.. note:: The customizable is only available when the shift-register-based memory bank is selected in :ref:`config_protocol`
-
-Each Word-Line (WL) shift register bank is defined in the code block ````.
-A shift register bank may contain multiple shift register chains.
-- each shift register chain can be defined using the ``bank`` syntax
-- the BLs controlled by each chain can be customized through the ``range`` syntax.
-
-
-.. option::
-
- - ``id`` indicates the sequence of the shift register chain in the bank. The id denotes the index in the head or tail bus. For example, ``id="0"`` means the head or tail of the shift register will be in the first bit of a head bus ``head[0:4]``
-
- - ``range`` indicates ``WL`` port to be controlled by this shift register chain. Multiple WL ports can be defined but the sequence matters. For example, ``wl[0:3], wl[6:10]`` infers a 9-bit shift register chain whose output ports are connected from ``wl[0]`` to ``wl[10]``.
-
- .. note:: When creating the range, you must know the number of BLs in the configuration region
-
- .. note:: ports must use ``wl`` as the reserved port name
-