diff --git a/docs/source/manual/index.rst b/docs/source/manual/index.rst index a00dce30a..fd4f4df56 100644 --- a/docs/source/manual/index.rst +++ b/docs/source/manual/index.rst @@ -18,3 +18,5 @@ file_formats/index + utilities/index + diff --git a/docs/source/manual/utilities/fabric_key_assistant.rst b/docs/source/manual/utilities/fabric_key_assistant.rst new file mode 100644 index 000000000..9bd525b91 --- /dev/null +++ b/docs/source/manual/utilities/fabric_key_assistant.rst @@ -0,0 +1,50 @@ +.. _utility_fabric_key_assistant: + +Fabric Key Assistant +-------------------- + +Fabric Key Assistant is a tool to help users to craft fabric key files. +Note that crafting a fabric key is not an easy task for engineers, as its complexity grows exponentially with FPGA sizes. +This tool is developed to assist engineers when finalizing fabric key files. +It can apply sanity checks on hand-crafted fabric key files, helping engineers to correct and debug. +The tool includes the following options: + +.. option:: --reference + + Specifiy a reference fabric key file, which has been already validated by OpenFPGA. For example, the reference fabric key can be a file which is written by OpenFPGA as a default key. The reference fabric key file is treated as the baseline, on which the input fabric key file will be compared to. + + .. note:: The reference fabric key should contain all the syntax, e.g., ``name``, ``value`` and ``alias``. + +.. option:: --input + + Specify the input fabric key file, which is typically hand-crafted by users. Sanity checks will be applied to the input fabric key file by comparing the reference. + + .. note:: The input fabric key should contain only the syntax ``alias``. + +.. option:: --output + + Specify the output fabric key file, which is an updated version of the input fabric key file. Difference from the input file, the output file contains ``name`` and ``value``, which is added by linking the ``alias`` from input file to reference file. For example, the reference fabric key includes a key: + +.. code-block:: xml + + + + while the input fabric key includes a key: + +.. code-block:: xml + + + + the resulting output fabric key file includes a key: + +.. code-block:: xml + + + +.. option:: --verbose + + To enable verbose output + +.. option:: --help + + Show help desk diff --git a/docs/source/manual/utilities/index.rst b/docs/source/manual/utilities/index.rst new file mode 100644 index 000000000..a51774314 --- /dev/null +++ b/docs/source/manual/utilities/index.rst @@ -0,0 +1,13 @@ +Utilities +--------- + +OpenFPGA contains a number of utility tools to help users to craft files. + + +.. _utilities: + Utility Tools + +.. toctree:: + :maxdepth: 2 + + fabric_key_assistant