.. _file_formats_fabric_key: Fabric Key (.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 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 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. .. option:: - ``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. .. 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