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