.. _fabric_key:
Fabric Key
~~~~~~~~~~
Fabric key is a secure key for users to generate bitstream for a specific FPGA fabric.
With this key, OpenFPGA can generate correct bitstreams for the FPGA.
Using a wrong key, OpenFPGA may error out or generate wrong bitstreams.
The fabric key support allows users to build secured/classified FPGA chips even with an open-source tool.
.. figure:: figures/fabric_key_motivation.png
:scale: 60%
:alt: map to buried treasure
The use of fabric key to secure the FPGA chip design
.. note:: Users are the only owner of the key. OpenFPGA will not store or replicate the key.
Key Generation
``````````````
A fabric key can be achieved in the following ways:
- OpenFPGA can auto-generate a fabric key using random algorithms (see detail in :ref:`cmd_build_fabric`)
- Users can craft a fabric key based on auto-generated file by following the file format description.
File Format
```````````
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.
.. 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