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.
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::<module name="<string>"/>
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.
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::<region id="<int>"/>
-``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.
-``id`` indicates the sequence of the configurable memory block in the top-level FPGA fabric.
-``name`` indicates the module name of the configurable memory block. This property becomes optional when ``alias`` is defined.
-``value`` indicates the instance id of the configurable memory block in the top-level FPGA fabric. This property becomes optional when ``alias`` is defined.
-``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.
-``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.
..note:: The configurable memory blocks in the same column will share the same Bit Line (BL) bus
-``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.
..note:: The configurable memory blocks in the same row will share the same Word Line (WL) bus
..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.
..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 ``<bl_shift_register_banks>``.
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::<bank id="<int>" range="<ports>"/>
-``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 ``<wl_shift_register_banks>``.
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::<bank id="<int>" range="<ports>"/>
-``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
