diff options
Diffstat (limited to 'docs/getting_started/tools-build.rst')
| -rw-r--r-- | docs/getting_started/tools-build.rst | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/docs/getting_started/tools-build.rst b/docs/getting_started/tools-build.rst new file mode 100644 index 0000000..166b527 --- /dev/null +++ b/docs/getting_started/tools-build.rst @@ -0,0 +1,179 @@ +Building Supporting Tools +========================= + +.. note:: + + OpenSSL 3.0 is needed in order to build the tools. A custom installation + can be used if not updating the OpenSSL version on the OS. In order to do + this, use the ``OPENSSL_DIR`` variable after the ``make`` command to + indicate the location of the custom OpenSSL build. Then, to run the tools, + use the ``LD_LIBRARY_PATH`` to indicate the location of the built + libraries. More info about ``OPENSSL_DIR`` can be found at + :ref:`Build Options`. + +Building and using the FIP tool +------------------------------- + +The following snippets build a :ref:`FIP<Image Terminology>` for the FVP +platform. While it is not an intrinsic part of the FIP format, a BL33 image is +required for these examples. For the purposes of experimentation, `Trusted +Firmware-A Tests`_ (`tftf.bin``) may be used. Refer to to the `TFTF +documentation`_ for instructions on building a TFTF binary. + +The TF-A build system provides the make target ``fip`` to create a FIP file +for the specified platform using the FIP creation tool included in the TF-A +project. Examples below show how to build a FIP file for FVP, packaging TF-A +and BL33 images. + +For AArch64: + +.. code:: shell + + make PLAT=fvp BL33=<path-to>/bl33.bin fip + +For AArch32: + +.. code:: shell + + make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip + +The resulting FIP may be found in: + +:: + + build/fvp/<build-type>/fip.bin + +For advanced operations on FIP files, it is also possible to independently build +the tool and create or modify FIPs using this tool. To do this, follow these +steps: + +It is recommended to remove old artifacts before building the tool: + +.. code:: shell + + make -C tools/fiptool clean + +Build the tool: + +.. code:: shell + + make [DEBUG=1] [V=1] fiptool + +The tool binary can be located in: + +:: + + ./tools/fiptool/fiptool + +Invoking the tool with ``help`` will print a help message with all available +options. + +Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31: + +.. code:: shell + + ./tools/fiptool/fiptool create \ + --tb-fw build/<platform>/<build-type>/bl2.bin \ + --soc-fw build/<platform>/<build-type>/bl31.bin \ + fip.bin + +Example 2: view the contents of an existing Firmware package: + +.. code:: shell + + ./tools/fiptool/fiptool info <path-to>/fip.bin + +Example 3: update the entries of an existing Firmware package: + +.. code:: shell + + # Change the BL2 from Debug to Release version + ./tools/fiptool/fiptool update \ + --tb-fw build/<platform>/release/bl2.bin \ + build/<platform>/debug/fip.bin + +Example 4: unpack all entries from an existing Firmware package: + +.. code:: shell + + # Images will be unpacked to the working directory + ./tools/fiptool/fiptool unpack <path-to>/fip.bin + +Example 5: remove an entry from an existing Firmware package: + +.. code:: shell + + ./tools/fiptool/fiptool remove \ + --tb-fw build/<platform>/debug/fip.bin + +Note that if the destination FIP file exists, the create, update and +remove operations will automatically overwrite it. + +The unpack operation will fail if the images already exist at the +destination. In that case, use -f or --force to continue. + +More information about FIP can be found in the :ref:`Firmware Design` document. + +.. _tools_build_cert_create: + +Building the Certificate Generation Tool +---------------------------------------- + +The ``cert_create`` tool is built as part of the TF-A build process when the +``fip`` make target is specified and TBB is enabled (as described in the +previous section), but it can also be built separately with the following +command: + +.. code:: shell + + make PLAT=<platform> [DEBUG=1] [V=1] certtool + +For platforms that require their own IDs in certificate files, the generic +'cert_create' tool can be built with the following command. Note that the target +platform must define its IDs within a ``platform_oid.h`` header file for the +build to succeed. + +.. code:: shell + + make PLAT=<platform> USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool + +``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more +verbose. The following command should be used to obtain help about the tool: + +.. code:: shell + + ./tools/cert_create/cert_create -h + +.. _tools_build_enctool: + +Building the Firmware Encryption Tool +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``encrypt_fw`` tool is built as part of the TF-A build process when the +``fip`` make target is specified, DECRYPTION_SUPPORT and TBB are enabled, but +it can also be built separately with the following command: + +.. code:: shell + + make PLAT=<platform> [DEBUG=1] [V=1] enctool + +``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more +verbose. The following command should be used to obtain help about the tool: + +.. code:: shell + + ./tools/encrypt_fw/encrypt_fw -h + +Note that the enctool in its current implementation only supports encryption +key to be provided in plain format. A typical implementation can very well +extend this tool to support custom techniques to protect encryption key. + +Also, a user may choose to provide encryption key or nonce as an input file +via using ``cat <filename>`` instead of a hex string. + +-------------- + +*Copyright (c) 2019-2022, Arm Limited. All rights reserved.* + +.. _Trusted Firmware-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/ +.. _TFTF documentation: https://trustedfirmware-a-tests.readthedocs.io/en/latest/ |