1Building Supporting Tools
2=========================
3
4.. note::
5
6    OpenSSL 3.0 is needed in order to build the tools. A custom installation
7    can be used if not updating the OpenSSL version on the OS. In order to do
8    this, use the ``OPENSSL_DIR`` variable after the ``make`` command to
9    indicate the location of the custom OpenSSL build. Then, to run the tools,
10    use the ``LD_LIBRARY_PATH`` to indicate the location of the built
11    libraries. More info about ``OPENSSL_DIR`` can be found at
12    :ref:`Build Options`.
13
14Building and using the FIP tool
15-------------------------------
16
17The following snippets build a :ref:`FIP<Image Terminology>` for the FVP
18platform. While it is not an intrinsic part of the FIP format, a BL33 image is
19required for these examples. For the purposes of experimentation, `Trusted
20Firmware-A Tests`_ (`tftf.bin``) may be used. Refer to to the `TFTF
21documentation`_ for instructions on building a TFTF binary.
22
23The TF-A build system provides the make target ``fip`` to create a FIP file
24for the specified platform using the FIP creation tool included in the TF-A
25project. Examples below show how to build a FIP file for FVP, packaging TF-A
26and BL33 images.
27
28For AArch64:
29
30.. code:: shell
31
32    make PLAT=fvp BL33=<path-to>/bl33.bin fip
33
34For AArch32:
35
36.. code:: shell
37
38    make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip
39
40The resulting FIP may be found in:
41
42::
43
44    build/fvp/<build-type>/fip.bin
45
46For advanced operations on FIP files, it is also possible to independently build
47the tool and create or modify FIPs using this tool. To do this, follow these
48steps:
49
50It is recommended to remove old artifacts before building the tool:
51
52.. code:: shell
53
54    make -C tools/fiptool clean
55
56Build the tool:
57
58.. code:: shell
59
60    make [DEBUG=1] [V=1] fiptool
61
62The tool binary can be located in:
63
64::
65
66    ./tools/fiptool/fiptool
67
68Invoking the tool with ``help`` will print a help message with all available
69options.
70
71Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31:
72
73.. code:: shell
74
75    ./tools/fiptool/fiptool create \
76        --tb-fw build/<platform>/<build-type>/bl2.bin \
77        --soc-fw build/<platform>/<build-type>/bl31.bin \
78        fip.bin
79
80Example 2: view the contents of an existing Firmware package:
81
82.. code:: shell
83
84    ./tools/fiptool/fiptool info <path-to>/fip.bin
85
86Example 3: update the entries of an existing Firmware package:
87
88.. code:: shell
89
90    # Change the BL2 from Debug to Release version
91    ./tools/fiptool/fiptool update \
92        --tb-fw build/<platform>/release/bl2.bin \
93        build/<platform>/debug/fip.bin
94
95Example 4: unpack all entries from an existing Firmware package:
96
97.. code:: shell
98
99    # Images will be unpacked to the working directory
100    ./tools/fiptool/fiptool unpack <path-to>/fip.bin
101
102Example 5: remove an entry from an existing Firmware package:
103
104.. code:: shell
105
106    ./tools/fiptool/fiptool remove \
107        --tb-fw build/<platform>/debug/fip.bin
108
109Note that if the destination FIP file exists, the create, update and
110remove operations will automatically overwrite it.
111
112The unpack operation will fail if the images already exist at the
113destination. In that case, use -f or --force to continue.
114
115More information about FIP can be found in the :ref:`Firmware Design` document.
116
117.. _tools_build_cert_create:
118
119Building the Certificate Generation Tool
120----------------------------------------
121
122The ``cert_create`` tool is built as part of the TF-A build process when the
123``fip`` make target is specified and TBB is enabled (as described in the
124previous section), but it can also be built separately with the following
125command:
126
127.. code:: shell
128
129    make PLAT=<platform> [DEBUG=1] [V=1] certtool
130
131For platforms that require their own IDs in certificate files, the generic
132'cert_create' tool can be built with the following command. Note that the target
133platform must define its IDs within a ``platform_oid.h`` header file for the
134build to succeed.
135
136.. code:: shell
137
138    make PLAT=<platform> USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool
139
140``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
141verbose. The following command should be used to obtain help about the tool:
142
143.. code:: shell
144
145    ./tools/cert_create/cert_create -h
146
147.. _tools_build_enctool:
148
149Building the Firmware Encryption Tool
150~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151
152The ``encrypt_fw`` tool is built as part of the TF-A build process when the
153``fip`` make target is specified, DECRYPTION_SUPPORT and TBB are enabled, but
154it can also be built separately with the following command:
155
156.. code:: shell
157
158    make PLAT=<platform> [DEBUG=1] [V=1] enctool
159
160``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
161verbose. The following command should be used to obtain help about the tool:
162
163.. code:: shell
164
165    ./tools/encrypt_fw/encrypt_fw -h
166
167Note that the enctool in its current implementation only supports encryption
168key to be provided in plain format. A typical implementation can very well
169extend this tool to support custom techniques to protect encryption key.
170
171Also, a user may choose to provide encryption key or nonce as an input file
172via using ``cat <filename>`` instead of a hex string.
173
174--------------
175
176*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*
177
178.. _Trusted Firmware-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/
179.. _TFTF documentation: https://trustedfirmware-a-tests.readthedocs.io/en/latest/
180