mirror of
https://github.com/ARM-software/arm-trusted-firmware.git
synced 2025-04-08 05:43:53 +00:00
b50838bae7
The Getting started section is very difficult to follow. Building the fip comes before building the files it needs, the BL33 requirement is given in a somewhat hand wavy way, and the Arm Developer website download provides a lot of targets and the guide is not clear which ones are needed on download. Swapping the initial build and supporting tools sections makes the flow more natural and the supporting tools section then becomes clear. Explicitly mentioning the GCC targets avoids confusion for people less familiar with the project (eg. new starters). Signed-off-by: Boyan Karatotev <boyan.karatotev@arm.com> Change-Id: I02e88f8c279db6d8eda68f634e8473c02b733963
179 lines
5.3 KiB
ReStructuredText
179 lines
5.3 KiB
ReStructuredText
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/
|