blob: 606546447dc3bc49c3ad5c2009a7b722b942e1c0 [file] [log] [blame]
Paul Beesley8aa05052019-03-07 15:47:15 +00001User Guide
2==========
Douglas Raillard6f625742017-06-28 15:23:03 +01003
Dan Handley4def07d2018-03-01 18:44:00 +00004This document describes how to build Trusted Firmware-A (TF-A) and run it with a
Douglas Raillard6f625742017-06-28 15:23:03 +01005tested set of other software components using defined configurations on the Juno
Dan Handley4def07d2018-03-01 18:44:00 +00006Arm development platform and Arm Fixed Virtual Platform (FVP) models. It is
Douglas Raillard6f625742017-06-28 15:23:03 +01007possible to use other software components, configurations and platforms but that
8is outside the scope of this document.
9
10This document assumes that the reader has previous experience running a fully
11bootable Linux software stack on Juno or FVP using the prebuilt binaries and
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +010012filesystems provided by `Linaro`_. Further information may be found in the
13`Linaro instructions`_. It also assumes that the user understands the role of
14the different software components required to boot a Linux system:
Douglas Raillard6f625742017-06-28 15:23:03 +010015
16- Specific firmware images required by the platform (e.g. SCP firmware on Juno)
17- Normal world bootloader (e.g. UEFI or U-Boot)
18- Device tree
19- Linux kernel image
20- Root filesystem
21
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +010022This document also assumes that the user is familiar with the `FVP models`_ and
Douglas Raillard6f625742017-06-28 15:23:03 +010023the different command line options available to launch the model.
24
25This document should be used in conjunction with the `Firmware Design`_.
26
27Host machine requirements
28-------------------------
29
30The minimum recommended machine specification for building the software and
31running the FVP models is a dual-core processor running at 2GHz with 12GB of
32RAM. For best performance, use a machine with a quad-core processor running at
332.6GHz with 16GB of RAM.
34
Joel Huttonbf7008a2018-03-19 11:59:57 +000035The software has been tested on Ubuntu 16.04 LTS (64-bit). Packages used for
Douglas Raillard6f625742017-06-28 15:23:03 +010036building the software were installed from that distribution unless otherwise
37specified.
38
39The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE,
David Cunado31f2f792017-06-29 12:01:33 +010040Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain.
Douglas Raillard6f625742017-06-28 15:23:03 +010041
42Tools
43-----
44
Dan Handley4def07d2018-03-01 18:44:00 +000045Install the required packages to build TF-A with the following command:
Douglas Raillard6f625742017-06-28 15:23:03 +010046
Paul Beesley29c02522019-03-13 15:11:04 +000047.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +010048
Sathees Balyabefcbdf2018-07-10 14:46:51 +010049 sudo apt-get install device-tree-compiler build-essential gcc make git libssl-dev
Douglas Raillard6f625742017-06-28 15:23:03 +010050
David Cunadoeb19da92017-12-19 16:33:25 +000051TF-A has been tested with Linaro Release 18.04.
David Cunado31f2f792017-06-29 12:01:33 +010052
Louis Mayencourt0042f572019-03-08 15:35:40 +000053Download and install the AArch32 or AArch64 little-endian GCC cross compiler. If
54you would like to use the latest features available, download GCC 8.2-2019.01
55compiler from `arm Developer page`_. Otherwise, the `Linaro Release Notes`_
56documents which version of the compiler to use for a given Linaro Release. Also,
57these `Linaro instructions`_ provide further guidance and a script, which can be
58used to download Linaro deliverables automatically.
Douglas Raillard6f625742017-06-28 15:23:03 +010059
Roberto Vargas00b7db32018-04-16 15:43:26 +010060Optionally, TF-A can be built using clang version 4.0 or newer or Arm
61Compiler 6. See instructions below on how to switch the default compiler.
Douglas Raillard6f625742017-06-28 15:23:03 +010062
63In addition, the following optional packages and tools may be needed:
64
Sathees Balya2eadd342018-08-17 10:22:01 +010065- ``device-tree-compiler`` (dtc) package if you need to rebuild the Flattened Device
66 Tree (FDT) source files (``.dts`` files) provided with this software. The
67 version of dtc must be 1.4.6 or above.
Douglas Raillard6f625742017-06-28 15:23:03 +010068
Dan Handley4def07d2018-03-01 18:44:00 +000069- For debugging, Arm `Development Studio 5 (DS-5)`_.
Douglas Raillard6f625742017-06-28 15:23:03 +010070
Antonio Nino Diaz6feb9e82017-05-23 11:49:22 +010071- To create and modify the diagram files included in the documentation, `Dia`_.
72 This tool can be found in most Linux distributions. Inkscape is needed to
Antonio Nino Diaz8fd9d4d2018-08-08 16:28:43 +010073 generate the actual \*.png files.
Antonio Nino Diaz6feb9e82017-05-23 11:49:22 +010074
Dan Handley4def07d2018-03-01 18:44:00 +000075Getting the TF-A source code
76----------------------------
Douglas Raillard6f625742017-06-28 15:23:03 +010077
Louis Mayencourt63fdda22019-03-22 11:47:22 +000078Clone the repository from the Gerrit server. The project details may be found
79on the `arm-trusted-firmware-a project page`_. We recommend the "`Clone with
80commit-msg hook`" clone method, which will setup the git commit hook that
81automatically generates and inserts appropriate `Change-Id:` lines in your
82commit messages.
Douglas Raillard6f625742017-06-28 15:23:03 +010083
Paul Beesley93fbc712019-01-21 12:06:24 +000084Checking source code style
85~~~~~~~~~~~~~~~~~~~~~~~~~~
86
87Trusted Firmware follows the `Linux Coding Style`_ . When making changes to the
88source, for submission to the project, the source must be in compliance with
89this style guide.
90
91Additional, project-specific guidelines are defined in the `Trusted Firmware-A
92Coding Guidelines`_ document.
93
94To assist with coding style compliance, the project Makefile contains two
95targets which both utilise the `checkpatch.pl` script that ships with the Linux
96source tree. The project also defines certain *checkpatch* options in the
97``.checkpatch.conf`` file in the top-level directory.
98
Paul Beesleye1c50262019-03-13 16:20:44 +000099.. note::
100 Checkpatch errors will gate upstream merging of pull requests.
101 Checkpatch warnings will not gate merging but should be reviewed and fixed if
102 possible.
Paul Beesley93fbc712019-01-21 12:06:24 +0000103
104To check the entire source tree, you must first download copies of
105``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available
106in the `Linux master tree`_ *scripts* directory, then set the ``CHECKPATCH``
107environment variable to point to ``checkpatch.pl`` (with the other 2 files in
108the same directory) and build the `checkcodebase` target:
109
Paul Beesley29c02522019-03-13 15:11:04 +0000110.. code:: shell
Paul Beesley93fbc712019-01-21 12:06:24 +0000111
112 make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase
113
114To just check the style on the files that differ between your local branch and
115the remote master, use:
116
Paul Beesley29c02522019-03-13 15:11:04 +0000117.. code:: shell
Paul Beesley93fbc712019-01-21 12:06:24 +0000118
119 make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch
120
121If you wish to check your patch against something other than the remote master,
122set the ``BASE_COMMIT`` variable to your desired branch. By default, ``BASE_COMMIT``
123is set to ``origin/master``.
124
Dan Handley4def07d2018-03-01 18:44:00 +0000125Building TF-A
126-------------
Douglas Raillard6f625742017-06-28 15:23:03 +0100127
Dan Handley4def07d2018-03-01 18:44:00 +0000128- Before building TF-A, the environment variable ``CROSS_COMPILE`` must point
129 to the Linaro cross compiler.
Douglas Raillard6f625742017-06-28 15:23:03 +0100130
131 For AArch64:
132
Paul Beesley29c02522019-03-13 15:11:04 +0000133 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +0100134
135 export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
136
137 For AArch32:
138
Paul Beesley29c02522019-03-13 15:11:04 +0000139 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +0100140
141 export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
142
Roberto Vargas4a98f0e2018-04-23 08:38:12 +0100143 It is possible to build TF-A using Clang or Arm Compiler 6. To do so
144 ``CC`` needs to point to the clang or armclang binary, which will
145 also select the clang or armclang assembler. Be aware that the
146 GNU linker is used by default. In case of being needed the linker
Paul Beesley8aabea32019-01-11 18:26:51 +0000147 can be overridden using the ``LD`` variable. Clang linker version 6 is
Roberto Vargas4a98f0e2018-04-23 08:38:12 +0100148 known to work with TF-A.
149
150 In both cases ``CROSS_COMPILE`` should be set as described above.
Douglas Raillard6f625742017-06-28 15:23:03 +0100151
Dan Handley4def07d2018-03-01 18:44:00 +0000152 Arm Compiler 6 will be selected when the base name of the path assigned
Douglas Raillard6f625742017-06-28 15:23:03 +0100153 to ``CC`` matches the string 'armclang'.
154
Dan Handley4def07d2018-03-01 18:44:00 +0000155 For AArch64 using Arm Compiler 6:
Douglas Raillard6f625742017-06-28 15:23:03 +0100156
Paul Beesley29c02522019-03-13 15:11:04 +0000157 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +0100158
159 export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
160 make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all
161
162 Clang will be selected when the base name of the path assigned to ``CC``
163 contains the string 'clang'. This is to allow both clang and clang-X.Y
164 to work.
165
166 For AArch64 using clang:
167
Paul Beesley29c02522019-03-13 15:11:04 +0000168 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +0100169
170 export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
171 make CC=<path-to-clang>/bin/clang PLAT=<platform> all
172
Dan Handley4def07d2018-03-01 18:44:00 +0000173- Change to the root directory of the TF-A source tree and build.
Douglas Raillard6f625742017-06-28 15:23:03 +0100174
175 For AArch64:
176
Paul Beesley29c02522019-03-13 15:11:04 +0000177 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +0100178
179 make PLAT=<platform> all
180
181 For AArch32:
182
Paul Beesley29c02522019-03-13 15:11:04 +0000183 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +0100184
185 make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all
186
187 Notes:
188
189 - If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the
190 `Summary of build options`_ for more information on available build
191 options.
192
193 - (AArch32 only) Currently only ``PLAT=fvp`` is supported.
194
195 - (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100196 corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp_min, is
Dan Handley4def07d2018-03-01 18:44:00 +0000197 provided by TF-A to demonstrate how PSCI Library can be integrated with
198 an AArch32 EL3 Runtime Software. Some AArch32 EL3 Runtime Software may
199 include other runtime services, for example Trusted OS services. A guide
200 to integrate PSCI library with AArch32 EL3 Runtime Software can be found
201 `here`_.
Douglas Raillard6f625742017-06-28 15:23:03 +0100202
203 - (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
204 image, is not compiled in by default. Refer to the
205 `Building the Test Secure Payload`_ section below.
206
207 - By default this produces a release version of the build. To produce a
208 debug version instead, refer to the "Debugging options" section below.
209
210 - The build process creates products in a ``build`` directory tree, building
211 the objects and binaries for each boot loader stage in separate
212 sub-directories. The following boot loader binary files are created
213 from the corresponding ELF files:
214
215 - ``build/<platform>/<build-type>/bl1.bin``
216 - ``build/<platform>/<build-type>/bl2.bin``
217 - ``build/<platform>/<build-type>/bl31.bin`` (AArch64 only)
218 - ``build/<platform>/<build-type>/bl32.bin`` (mandatory for AArch32)
219
220 where ``<platform>`` is the name of the chosen platform and ``<build-type>``
221 is either ``debug`` or ``release``. The actual number of images might differ
222 depending on the platform.
223
224- Build products for a specific build variant can be removed using:
225
Paul Beesley29c02522019-03-13 15:11:04 +0000226 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +0100227
228 make DEBUG=<D> PLAT=<platform> clean
229
230 ... where ``<D>`` is ``0`` or ``1``, as specified when building.
231
232 The build tree can be removed completely using:
233
Paul Beesley29c02522019-03-13 15:11:04 +0000234 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +0100235
236 make realclean
237
238Summary of build options
239~~~~~~~~~~~~~~~~~~~~~~~~
240
Dan Handley4def07d2018-03-01 18:44:00 +0000241The TF-A build system supports the following build options. Unless mentioned
242otherwise, these options are expected to be specified at the build command
243line and are not to be modified in any component makefiles. Note that the
244build system doesn't track dependency for build options. Therefore, if any of
245the build options are changed from a previous build, a clean build must be
Douglas Raillard6f625742017-06-28 15:23:03 +0100246performed.
247
248Common build options
249^^^^^^^^^^^^^^^^^^^^
250
Antonio Nino Diaz8fd9d4d2018-08-08 16:28:43 +0100251- ``AARCH32_INSTRUCTION_SET``: Choose the AArch32 instruction set that the
252 compiler should use. Valid values are T32 and A32. It defaults to T32 due to
253 code having a smaller resulting size.
254
Douglas Raillard6f625742017-06-28 15:23:03 +0100255- ``AARCH32_SP`` : Choose the AArch32 Secure Payload component to be built as
256 as the BL32 image when ``ARCH=aarch32``. The value should be the path to the
257 directory containing the SP source, relative to the ``bl32/``; the directory
258 is expected to contain a makefile called ``<aarch32_sp-value>.mk``.
259
Dan Handley4def07d2018-03-01 18:44:00 +0000260- ``ARCH`` : Choose the target build architecture for TF-A. It can take either
261 ``aarch64`` or ``aarch32`` as values. By default, it is defined to
262 ``aarch64``.
Douglas Raillard6f625742017-06-28 15:23:03 +0100263
Dan Handley4def07d2018-03-01 18:44:00 +0000264- ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when
265 compiling TF-A. Its value must be numeric, and defaults to 8 . See also,
266 *Armv8 Architecture Extensions* and *Armv7 Architecture Extensions* in
267 `Firmware Design`_.
Douglas Raillard6f625742017-06-28 15:23:03 +0100268
Dan Handley4def07d2018-03-01 18:44:00 +0000269- ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when
270 compiling TF-A. Its value must be a numeric, and defaults to 0. See also,
271 *Armv8 Architecture Extensions* in `Firmware Design`_.
Douglas Raillard6f625742017-06-28 15:23:03 +0100272
Douglas Raillard6f625742017-06-28 15:23:03 +0100273- ``BL2``: This is an optional build option which specifies the path to BL2
Dan Handley4def07d2018-03-01 18:44:00 +0000274 image for the ``fip`` target. In this case, the BL2 in the TF-A will not be
275 built.
Douglas Raillard6f625742017-06-28 15:23:03 +0100276
277- ``BL2U``: This is an optional build option which specifies the path to
Dan Handley4def07d2018-03-01 18:44:00 +0000278 BL2U image. In this case, the BL2U in TF-A will not be built.
Douglas Raillard6f625742017-06-28 15:23:03 +0100279
John Tsichritzis677ad322018-06-06 09:38:10 +0100280- ``BL2_AT_EL3``: This is an optional build option that enables the use of
Roberto Vargas4cd17692017-11-20 13:36:10 +0000281 BL2 at EL3 execution level.
282
John Tsichritzis677ad322018-06-06 09:38:10 +0100283- ``BL2_IN_XIP_MEM``: In some use-cases BL2 will be stored in eXecute In Place
Jiafei Pan7d173fc2018-03-21 07:20:09 +0000284 (XIP) memory, like BL1. In these use-cases, it is necessary to initialize
285 the RW sections in RAM, while leaving the RO sections in place. This option
286 enable this use-case. For now, this option is only supported when BL2_AT_EL3
287 is set to '1'.
288
Douglas Raillard6f625742017-06-28 15:23:03 +0100289- ``BL31``: This is an optional build option which specifies the path to
Dan Handley4def07d2018-03-01 18:44:00 +0000290 BL31 image for the ``fip`` target. In this case, the BL31 in TF-A will not
291 be built.
Douglas Raillard6f625742017-06-28 15:23:03 +0100292
293- ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
294 file that contains the BL31 private key in PEM format. If ``SAVE_KEYS=1``,
295 this file name will be used to save the key.
296
297- ``BL32``: This is an optional build option which specifies the path to
Dan Handley4def07d2018-03-01 18:44:00 +0000298 BL32 image for the ``fip`` target. In this case, the BL32 in TF-A will not
299 be built.
Douglas Raillard6f625742017-06-28 15:23:03 +0100300
John Tsichritzis677ad322018-06-06 09:38:10 +0100301- ``BL32_EXTRA1``: This is an optional build option which specifies the path to
Summer Qin71fb3962017-04-20 16:28:39 +0100302 Trusted OS Extra1 image for the ``fip`` target.
303
John Tsichritzis677ad322018-06-06 09:38:10 +0100304- ``BL32_EXTRA2``: This is an optional build option which specifies the path to
Summer Qin71fb3962017-04-20 16:28:39 +0100305 Trusted OS Extra2 image for the ``fip`` target.
306
Douglas Raillard6f625742017-06-28 15:23:03 +0100307- ``BL32_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
308 file that contains the BL32 private key in PEM format. If ``SAVE_KEYS=1``,
309 this file name will be used to save the key.
310
311- ``BL33``: Path to BL33 image in the host file system. This is mandatory for
Dan Handley4def07d2018-03-01 18:44:00 +0000312 ``fip`` target in case TF-A BL2 is used.
Douglas Raillard6f625742017-06-28 15:23:03 +0100313
314- ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
315 file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``,
316 this file name will be used to save the key.
317
318- ``BUILD_MESSAGE_TIMESTAMP``: String used to identify the time and date of the
319 compilation of each build. It must be set to a C string (including quotes
320 where applicable). Defaults to a string that contains the time and date of
321 the compilation.
322
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100323- ``BUILD_STRING``: Input string for VERSION_STRING, which allows the TF-A
Dan Handley4def07d2018-03-01 18:44:00 +0000324 build to be uniquely identified. Defaults to the current git commit id.
Douglas Raillard6f625742017-06-28 15:23:03 +0100325
326- ``CFLAGS``: Extra user options appended on the compiler's command line in
327 addition to the options set by the build system.
328
329- ``COLD_BOOT_SINGLE_CPU``: This option indicates whether the platform may
330 release several CPUs out of reset. It can take either 0 (several CPUs may be
331 brought up) or 1 (only one CPU will ever be brought up during cold reset).
332 Default is 0. If the platform always brings up a single CPU, there is no
333 need to distinguish between primary and secondary CPUs and the boot path can
334 be optimised. The ``plat_is_my_cpu_primary()`` and
335 ``plat_secondary_cold_boot_setup()`` platform porting interfaces do not need
336 to be implemented in this case.
337
338- ``CRASH_REPORTING``: A non-zero value enables a console dump of processor
339 register state when an unexpected exception occurs during execution of
340 BL31. This option defaults to the value of ``DEBUG`` - i.e. by default
341 this is only enabled for a debug build of the firmware.
342
343- ``CREATE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
344 certificate generation tool to create new keys in case no valid keys are
345 present or specified. Allowed options are '0' or '1'. Default is '1'.
346
347- ``CTX_INCLUDE_AARCH32_REGS`` : Boolean option that, when set to 1, will cause
348 the AArch32 system registers to be included when saving and restoring the
349 CPU context. The option must be set to 0 for AArch64-only platforms (that
350 is on hardware that does not implement AArch32, or at least not at EL1 and
351 higher ELs). Default value is 1.
352
353- ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP
354 registers to be included when saving and restoring the CPU context. Default
355 is 0.
356
John Tsichritzis6d0512f2019-05-07 14:13:07 +0100357- ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, allows
358 Pointer Authentication for **Secure world**. This will cause the
359 Armv8.3-PAuth registers to be included when saving and restoring the CPU
360 context as part of a world switch. Default value is 0. Pointer Authentication
361 is an experimental feature.
362
363 Note that, if the CPU supports it, Pointer Authentication is allowed for
364 Non-secure world irrespectively of the value of this flag. "Allowed" means
365 that accesses to PAuth-related registers or execution of PAuth-related
366 instructions will not be trapped to EL3. As such, usage or not of PAuth in
367 Non-secure world images, depends on those images themselves.
Antonio Nino Diaz52839622019-01-31 11:58:00 +0000368
Douglas Raillard6f625742017-06-28 15:23:03 +0100369- ``DEBUG``: Chooses between a debug and release build. It can take either 0
370 (release) or 1 (debug) as values. 0 is the default.
371
Christoph Müllner9e4609f2019-04-24 09:45:30 +0200372- ``DISABLE_BIN_GENERATION``: Boolean option to disable the generation
373 of the binary image. If set to 1, then only the ELF image is built.
374 0 is the default.
375
John Tsichritzis677ad322018-06-06 09:38:10 +0100376- ``DYN_DISABLE_AUTH``: Provides the capability to dynamically disable Trusted
377 Board Boot authentication at runtime. This option is meant to be enabled only
Roberto Vargased51b512018-09-24 17:20:48 +0100378 for development platforms. ``TRUSTED_BOARD_BOOT`` flag must be set if this
379 flag has to be enabled. 0 is the default.
Soby Mathew209a60c2018-03-26 12:43:37 +0100380
Douglas Raillard6f625742017-06-28 15:23:03 +0100381- ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of
382 the normal boot flow. It must specify the entry point address of the EL3
383 payload. Please refer to the "Booting an EL3 payload" section for more
384 details.
385
Dimitris Papastamos0319a972017-10-16 11:40:10 +0100386- ``ENABLE_AMU``: Boolean option to enable Activity Monitor Unit extensions.
Dimitris Papastamos380559c2017-10-12 13:02:29 +0100387 This is an optional architectural feature available on v8.4 onwards. Some
388 v8.2 implementations also implement an AMU and this option can be used to
389 enable this feature on those systems as well. Default is 0.
Dimitris Papastamos0319a972017-10-16 11:40:10 +0100390
Douglas Raillard6f625742017-06-28 15:23:03 +0100391- ``ENABLE_ASSERTIONS``: This option controls whether or not calls to ``assert()``
392 are compiled out. For debug builds, this option defaults to 1, and calls to
393 ``assert()`` are left in place. For release builds, this option defaults to 0
394 and calls to ``assert()`` function are compiled out. This option can be set
395 independently of ``DEBUG``. It can also be used to hide any auxiliary code
396 that is only required for the assertion and does not fit in the assertion
397 itself.
398
Douglas Raillard0c628832018-08-21 12:54:45 +0100399- ``ENABLE_BACKTRACE``: This option controls whether to enables backtrace
400 dumps or not. It is supported in both AArch64 and AArch32. However, in
401 AArch32 the format of the frame records are not defined in the AAPCS and they
402 are defined by the implementation. This implementation of backtrace only
403 supports the format used by GCC when T32 interworking is disabled. For this
404 reason enabling this option in AArch32 will force the compiler to only
405 generate A32 code. This option is enabled by default only in AArch64 debug
Paul Beesley8aabea32019-01-11 18:26:51 +0000406 builds, but this behaviour can be overridden in each platform's Makefile or
407 in the build command line.
Douglas Raillard0c628832018-08-21 12:54:45 +0100408
Jeenu Viswambharan5f835912018-07-31 16:13:33 +0100409- ``ENABLE_MPAM_FOR_LOWER_ELS``: Boolean option to enable lower ELs to use MPAM
410 feature. MPAM is an optional Armv8.4 extension that enables various memory
411 system components and resources to define partitions; software running at
412 various ELs can assign themselves to desired partition to control their
413 performance aspects.
414
415 When this option is set to ``1``, EL3 allows lower ELs to access their own
416 MPAM registers without trapping into EL3. This option doesn't make use of
417 partitioning in EL3, however. Platform initialisation code should configure
418 and use partitions in EL3 as required. This option defaults to ``0``.
419
John Tsichritzis6d0512f2019-05-07 14:13:07 +0100420- ``ENABLE_PAUTH``: Boolean option to enable Armv8.3 Pointer Authentication
421 for **TF-A BL images themselves**. If enabled, the compiler must support the
422 ``-msign-return-address`` option. This flag defaults to 0. Pointer
423 Authentication is an experimental feature.
424
425 If this flag is enabled, ``CTX_INCLUDE_PAUTH_REGS`` must also be enabled.
Antonio Nino Diazb86048c2019-02-19 11:53:51 +0000426
Soby Mathew3bd17c02018-08-28 11:13:55 +0100427- ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE)
428 support within generic code in TF-A. This option is currently only supported
429 in BL31. Default is 0.
430
Douglas Raillard6f625742017-06-28 15:23:03 +0100431- ``ENABLE_PMF``: Boolean option to enable support for optional Performance
432 Measurement Framework(PMF). Default is 0.
433
434- ``ENABLE_PSCI_STAT``: Boolean option to enable support for optional PSCI
435 functions ``PSCI_STAT_RESIDENCY`` and ``PSCI_STAT_COUNT``. Default is 0.
436 In the absence of an alternate stat collection backend, ``ENABLE_PMF`` must
437 be enabled. If ``ENABLE_PMF`` is set, the residency statistics are tracked in
438 software.
439
440- ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime
Dan Handley4def07d2018-03-01 18:44:00 +0000441 instrumentation which injects timestamp collection points into TF-A to
442 allow runtime performance to be measured. Currently, only PSCI is
443 instrumented. Enabling this option enables the ``ENABLE_PMF`` build option
444 as well. Default is 0.
Douglas Raillard6f625742017-06-28 15:23:03 +0100445
Jeenu Viswambharanc1232c32017-07-19 13:52:12 +0100446- ``ENABLE_SPE_FOR_LOWER_ELS`` : Boolean option to enable Statistical Profiling
Dimitris Papastamosc776dee2017-10-13 15:07:45 +0100447 extensions. This is an optional architectural feature for AArch64.
448 The default is 1 but is automatically disabled when the target architecture
449 is AArch32.
Jeenu Viswambharanc1232c32017-07-19 13:52:12 +0100450
Sandrine Bailleux1843a192018-09-20 12:44:39 +0200451- ``ENABLE_SPM`` : Boolean option to enable the Secure Partition Manager (SPM).
452 Refer to the `Secure Partition Manager Design guide`_ for more details about
453 this feature. Default is 0.
454
David Cunado1a853372017-10-20 11:30:57 +0100455- ``ENABLE_SVE_FOR_NS``: Boolean option to enable Scalable Vector Extension
456 (SVE) for the Non-secure world only. SVE is an optional architectural feature
457 for AArch64. Note that when SVE is enabled for the Non-secure world, access
458 to SIMD and floating-point functionality from the Secure world is disabled.
459 This is to avoid corruption of the Non-secure world data in the Z-registers
460 which are aliased by the SIMD and FP registers. The build option is not
461 compatible with the ``CTX_INCLUDE_FPREGS`` build option, and will raise an
462 assert on platforms where SVE is implemented and ``ENABLE_SVE_FOR_NS`` set to
463 1. The default is 1 but is automatically disabled when the target
464 architecture is AArch32.
465
Douglas Raillard6f625742017-06-28 15:23:03 +0100466- ``ENABLE_STACK_PROTECTOR``: String option to enable the stack protection
Louis Mayencourtfd7b2872019-03-26 16:59:26 +0000467 checks in GCC. Allowed values are "all", "strong", "default" and "none". The
468 default value is set to "none". "strong" is the recommended stack protection
469 level if this feature is desired. "none" disables the stack protection. For
470 all values other than "none", the ``plat_get_stack_protector_canary()``
471 platform hook needs to be implemented. The value is passed as the last
472 component of the option ``-fstack-protector-$ENABLE_STACK_PROTECTOR``.
Douglas Raillard6f625742017-06-28 15:23:03 +0100473
474- ``ERROR_DEPRECATED``: This option decides whether to treat the usage of
475 deprecated platform APIs, helper functions or drivers within Trusted
476 Firmware as error. It can take the value 1 (flag the use of deprecated
477 APIs as error) or 0. The default is 0.
478
Jeenu Viswambharan21b818c2017-09-22 08:32:10 +0100479- ``EL3_EXCEPTION_HANDLING``: When set to ``1``, enable handling of exceptions
480 targeted at EL3. When set ``0`` (default), no exceptions are expected or
481 handled at EL3, and a panic will result. This is supported only for AArch64
482 builds.
483
Paul Beesley8aabea32019-01-11 18:26:51 +0000484- ``FAULT_INJECTION_SUPPORT``: ARMv8.4 extensions introduced support for fault
Jeenu Viswambharan1a7c1cf2017-12-08 12:13:51 +0000485 injection from lower ELs, and this build option enables lower ELs to use
486 Error Records accessed via System Registers to inject faults. This is
487 applicable only to AArch64 builds.
488
489 This feature is intended for testing purposes only, and is advisable to keep
490 disabled for production images.
491
Douglas Raillard6f625742017-06-28 15:23:03 +0100492- ``FIP_NAME``: This is an optional build option which specifies the FIP
493 filename for the ``fip`` target. Default is ``fip.bin``.
494
495- ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU
496 FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``.
497
498- ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create``
499 tool to create certificates as per the Chain of Trust described in
500 `Trusted Board Boot`_. The build system then calls ``fiptool`` to
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100501 include the certificates in the FIP and FWU_FIP. Default value is '0'.
Douglas Raillard6f625742017-06-28 15:23:03 +0100502
503 Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support
504 for the Trusted Board Boot feature in the BL1 and BL2 images, to generate
505 the corresponding certificates, and to include those certificates in the
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100506 FIP and FWU_FIP.
Douglas Raillard6f625742017-06-28 15:23:03 +0100507
508 Note that if ``TRUSTED_BOARD_BOOT=0`` and ``GENERATE_COT=1``, the BL1 and BL2
509 images will not include support for Trusted Board Boot. The FIP will still
510 include the corresponding certificates. This FIP can be used to verify the
511 Chain of Trust on the host machine through other mechanisms.
512
513 Note that if ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=0``, the BL1 and BL2
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100514 images will include support for Trusted Board Boot, but the FIP and FWU_FIP
Douglas Raillard6f625742017-06-28 15:23:03 +0100515 will not include the corresponding certificates, causing a boot failure.
516
Jeenu Viswambharan74dce7f2017-09-22 08:32:09 +0100517- ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have
518 inherent support for specific EL3 type interrupts. Setting this build option
519 to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both
520 by `platform abstraction layer`__ and `Interrupt Management Framework`__.
521 This allows GICv2 platforms to enable features requiring EL3 interrupt type.
522 This also means that all GICv2 Group 0 interrupts are delivered to EL3, and
523 the Secure Payload interrupts needs to be synchronously handed over to Secure
524 EL1 for handling. The default value of this option is ``0``, which means the
525 Group 0 interrupts are assumed to be handled by Secure EL1.
526
527 .. __: `platform-interrupt-controller-API.rst`
528 .. __: `interrupt-framework-design.rst`
529
Julius Werner24f671f2018-08-28 14:45:43 -0700530- ``HANDLE_EA_EL3_FIRST``: When set to ``1``, External Aborts and SError
531 Interrupts will be always trapped in EL3 i.e. in BL31 at runtime. When set to
532 ``0`` (default), these exceptions will be trapped in the current exception
533 level (or in EL1 if the current exception level is EL0).
Douglas Raillard6f625742017-06-28 15:23:03 +0100534
Dan Handley4def07d2018-03-01 18:44:00 +0000535- ``HW_ASSISTED_COHERENCY``: On most Arm systems to-date, platform-specific
Douglas Raillard6f625742017-06-28 15:23:03 +0100536 software operations are required for CPUs to enter and exit coherency.
John Tsichritzis076b5f02019-03-19 17:20:52 +0000537 However, newer systems exist where CPUs' entry to and exit from coherency
538 is managed in hardware. Such systems require software to only initiate these
539 operations, and the rest is managed in hardware, minimizing active software
540 management. In such systems, this boolean option enables TF-A to carry out
541 build and run-time optimizations during boot and power management operations.
542 This option defaults to 0 and if it is enabled, then it implies
543 ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled.
544
545 If this flag is disabled while the platform which TF-A is compiled for
546 includes cores that manage coherency in hardware, then a compilation error is
547 generated. This is based on the fact that a system cannot have, at the same
548 time, cores that manage coherency in hardware and cores that don't. In other
549 words, a platform cannot have, at the same time, cores that require
550 ``HW_ASSISTED_COHERENCY=1`` and cores that require
551 ``HW_ASSISTED_COHERENCY=0``.
Douglas Raillard6f625742017-06-28 15:23:03 +0100552
Jeenu Viswambharan64ee2632018-04-27 15:17:03 +0100553 Note that, when ``HW_ASSISTED_COHERENCY`` is enabled, version 2 of
554 translation library (xlat tables v2) must be used; version 1 of translation
555 library is not supported.
556
Douglas Raillard6f625742017-06-28 15:23:03 +0100557- ``JUNO_AARCH32_EL3_RUNTIME``: This build flag enables you to execute EL3
558 runtime software in AArch32 mode, which is required to run AArch32 on Juno.
559 By default this flag is set to '0'. Enabling this flag builds BL1 and BL2 in
560 AArch64 and facilitates the loading of ``SP_MIN`` and BL33 as AArch32 executable
561 images.
562
Soby Mathew20917552017-08-31 11:49:32 +0100563- ``KEY_ALG``: This build flag enables the user to select the algorithm to be
564 used for generating the PKCS keys and subsequent signing of the certificate.
Antonio Nino Diaz73308612019-02-28 13:35:21 +0000565 It accepts 3 values: ``rsa``, ``rsa_1_5`` and ``ecdsa``. The option
566 ``rsa_1_5`` is the legacy PKCS#1 RSA 1.5 algorithm which is not TBBR
567 compliant and is retained only for compatibility. The default value of this
568 flag is ``rsa`` which is the TBBR compliant PKCS#1 RSA 2.1 scheme.
Soby Mathew20917552017-08-31 11:49:32 +0100569
Qixiang Xu9a3088a2017-11-09 13:56:29 +0800570- ``HASH_ALG``: This build flag enables the user to select the secure hash
Antonio Nino Diaz73308612019-02-28 13:35:21 +0000571 algorithm. It accepts 3 values: ``sha256``, ``sha384`` and ``sha512``.
Qixiang Xu9a3088a2017-11-09 13:56:29 +0800572 The default value of this flag is ``sha256``.
573
Douglas Raillard6f625742017-06-28 15:23:03 +0100574- ``LDFLAGS``: Extra user options appended to the linkers' command line in
575 addition to the one set by the build system.
576
Douglas Raillard6f625742017-06-28 15:23:03 +0100577- ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log
578 output compiled into the build. This should be one of the following:
579
580 ::
581
582 0 (LOG_LEVEL_NONE)
Daniel Boulby9bd5a4c2018-06-14 10:07:40 +0100583 10 (LOG_LEVEL_ERROR)
584 20 (LOG_LEVEL_NOTICE)
Douglas Raillard6f625742017-06-28 15:23:03 +0100585 30 (LOG_LEVEL_WARNING)
586 40 (LOG_LEVEL_INFO)
587 50 (LOG_LEVEL_VERBOSE)
588
John Tsichritzisea75ffd2018-10-05 12:02:29 +0100589 All log output up to and including the selected log level is compiled into
590 the build. The default value is 40 in debug builds and 20 in release builds.
Douglas Raillard6f625742017-06-28 15:23:03 +0100591
592- ``NON_TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
593 specifies the file that contains the Non-Trusted World private key in PEM
594 format. If ``SAVE_KEYS=1``, this file name will be used to save the key.
595
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100596- ``NS_BL2U``: Path to NS_BL2U image in the host file system. This image is
Douglas Raillard6f625742017-06-28 15:23:03 +0100597 optional. It is only needed if the platform makefile specifies that it
598 is required in order to build the ``fwu_fip`` target.
599
600- ``NS_TIMER_SWITCH``: Enable save and restore for non-secure timer register
601 contents upon world switch. It can take either 0 (don't save and restore) or
602 1 (do save and restore). 0 is the default. An SPD may set this to 1 if it
603 wants the timer registers to be saved and restored.
604
Sandrine Bailleux337e2f12019-02-08 10:50:28 +0100605- ``OVERRIDE_LIBC``: This option allows platforms to override the default libc
Varun Wadekar77f1f7a2019-01-31 09:22:30 -0800606 for the BL image. It can be either 0 (include) or 1 (remove). The default
607 value is 0.
608
Douglas Raillard6f625742017-06-28 15:23:03 +0100609- ``PL011_GENERIC_UART``: Boolean option to indicate the PL011 driver that
610 the underlying hardware is not a full PL011 UART but a minimally compliant
611 generic UART, which is a subset of the PL011. The driver will not access
612 any register that is not part of the SBSA generic UART specification.
613 Default value is 0 (a full PL011 compliant UART is present).
614
Dan Handley4def07d2018-03-01 18:44:00 +0000615- ``PLAT``: Choose a platform to build TF-A for. The chosen platform name
616 must be subdirectory of any depth under ``plat/``, and must contain a
617 platform makefile named ``platform.mk``. For example, to build TF-A for the
618 Arm Juno board, select PLAT=juno.
Douglas Raillard6f625742017-06-28 15:23:03 +0100619
620- ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image
621 instead of the normal boot flow. When defined, it must specify the entry
622 point address for the preloaded BL33 image. This option is incompatible with
623 ``EL3_PAYLOAD_BASE``. If both are defined, ``EL3_PAYLOAD_BASE`` has priority
624 over ``PRELOADED_BL33_BASE``.
625
626- ``PROGRAMMABLE_RESET_ADDRESS``: This option indicates whether the reset
627 vector address can be programmed or is fixed on the platform. It can take
628 either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a
629 programmable reset address, it is expected that a CPU will start executing
630 code directly at the right address, both on a cold and warm reset. In this
631 case, there is no need to identify the entrypoint on boot and the boot path
632 can be optimised. The ``plat_get_my_entrypoint()`` platform porting interface
633 does not need to be implemented in this case.
634
635- ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats
Antonio Nino Diaz73308612019-02-28 13:35:21 +0000636 possible for the PSCI power-state parameter: original and extended State-ID
637 formats. This flag if set to 1, configures the generic PSCI layer to use the
638 extended format. The default value of this flag is 0, which means by default
639 the original power-state format is used by the PSCI implementation. This flag
640 should be specified by the platform makefile and it governs the return value
641 of PSCI_FEATURES API for CPU_SUSPEND smc function id. When this option is
642 enabled on Arm platforms, the option ``ARM_RECOM_STATE_ID_ENC`` needs to be
643 set to 1 as well.
Douglas Raillard6f625742017-06-28 15:23:03 +0100644
Jeenu Viswambharan14c60162018-04-04 16:07:11 +0100645- ``RAS_EXTENSION``: When set to ``1``, enable Armv8.2 RAS features. RAS features
646 are an optional extension for pre-Armv8.2 CPUs, but are mandatory for Armv8.2
647 or later CPUs.
648
649 When ``RAS_EXTENSION`` is set to ``1``, ``HANDLE_EA_EL3_FIRST`` must also be
650 set to ``1``.
651
652 This option is disabled by default.
653
Douglas Raillard6f625742017-06-28 15:23:03 +0100654- ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead
655 of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
656 entrypoint) or 1 (CPU reset to BL31 entrypoint).
657 The default value is 0.
658
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100659- ``RESET_TO_SP_MIN``: SP_MIN is the minimal AArch32 Secure Payload provided
660 in TF-A. This flag configures SP_MIN entrypoint as the CPU reset vector
Dan Handley4def07d2018-03-01 18:44:00 +0000661 instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100662 entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default value is 0.
Douglas Raillard6f625742017-06-28 15:23:03 +0100663
664- ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
665 file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this
666 file name will be used to save the key.
667
668- ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
669 certificate generation tool to save the keys used to establish the Chain of
670 Trust. Allowed options are '0' or '1'. Default is '0' (do not save).
671
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100672- ``SCP_BL2``: Path to SCP_BL2 image in the host file system. This image is optional.
673 If a SCP_BL2 image is present then this option must be passed for the ``fip``
Douglas Raillard6f625742017-06-28 15:23:03 +0100674 target.
675
676- ``SCP_BL2_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100677 file that contains the SCP_BL2 private key in PEM format. If ``SAVE_KEYS=1``,
Douglas Raillard6f625742017-06-28 15:23:03 +0100678 this file name will be used to save the key.
679
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100680- ``SCP_BL2U``: Path to SCP_BL2U image in the host file system. This image is
Douglas Raillard6f625742017-06-28 15:23:03 +0100681 optional. It is only needed if the platform makefile specifies that it
682 is required in order to build the ``fwu_fip`` target.
683
Jeenu Viswambharanb7cb1332017-10-16 08:43:14 +0100684- ``SDEI_SUPPORT``: Setting this to ``1`` enables support for Software
685 Delegated Exception Interface to BL31 image. This defaults to ``0``.
686
687 When set to ``1``, the build option ``EL3_EXCEPTION_HANDLING`` must also be
688 set to ``1``.
689
Douglas Raillard6f625742017-06-28 15:23:03 +0100690- ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be
691 isolated on separate memory pages. This is a trade-off between security and
692 memory usage. See "Isolating code and read-only data on separate memory
693 pages" section in `Firmware Design`_. This flag is disabled by default and
694 affects all BL images.
695
Dan Handley4def07d2018-03-01 18:44:00 +0000696- ``SPD``: Choose a Secure Payload Dispatcher component to be built into TF-A.
697 This build option is only valid if ``ARCH=aarch64``. The value should be
698 the path to the directory containing the SPD source, relative to
699 ``services/spd/``; the directory is expected to contain a makefile called
700 ``<spd-value>.mk``.
Douglas Raillard6f625742017-06-28 15:23:03 +0100701
702- ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can
703 take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops
704 execution in BL1 just before handing over to BL31. At this point, all
705 firmware images have been loaded in memory, and the MMU and caches are
706 turned off. Refer to the "Debugging options" section for more details.
707
Antonio Nino Diazb726c162018-05-11 11:15:10 +0100708- ``SP_MIN_WITH_SECURE_FIQ``: Boolean flag to indicate the SP_MIN handles
Etienne Carriere71816092017-08-09 15:48:53 +0200709 secure interrupts (caught through the FIQ line). Platforms can enable
710 this directive if they need to handle such interruption. When enabled,
711 the FIQ are handled in monitor mode and non secure world is not allowed
712 to mask these events. Platforms that enable FIQ handling in SP_MIN shall
713 implement the api ``sp_min_plat_fiq_handler()``. The default value is 0.
714
Douglas Raillard6f625742017-06-28 15:23:03 +0100715- ``TRUSTED_BOARD_BOOT``: Boolean flag to include support for the Trusted Board
716 Boot feature. When set to '1', BL1 and BL2 images include support to load
717 and verify the certificates and images in a FIP, and BL1 includes support
718 for the Firmware Update. The default value is '0'. Generation and inclusion
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100719 of certificates in the FIP and FWU_FIP depends upon the value of the
Douglas Raillard6f625742017-06-28 15:23:03 +0100720 ``GENERATE_COT`` option.
721
Paul Beesleye1c50262019-03-13 16:20:44 +0000722 .. warning::
723 This option depends on ``CREATE_KEYS`` to be enabled. If the keys
724 already exist in disk, they will be overwritten without further notice.
Douglas Raillard6f625742017-06-28 15:23:03 +0100725
726- ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
727 specifies the file that contains the Trusted World private key in PEM
728 format. If ``SAVE_KEYS=1``, this file name will be used to save the key.
729
730- ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or
731 synchronous, (see "Initializing a BL32 Image" section in
732 `Firmware Design`_). It can take the value 0 (BL32 is initialized using
733 synchronous method) or 1 (BL32 is initialized using asynchronous method).
734 Default is 0.
735
736- ``TSP_NS_INTR_ASYNC_PREEMPT``: A non zero value enables the interrupt
737 routing model which routes non-secure interrupts asynchronously from TSP
738 to EL3 causing immediate preemption of TSP. The EL3 is responsible
739 for saving and restoring the TSP context in this routing model. The
740 default routing model (when the value is 0) is to route non-secure
741 interrupts to TSP allowing it to save its context and hand over
742 synchronously to EL3 via an SMC.
743
Paul Beesleye1c50262019-03-13 16:20:44 +0000744 .. note::
745 When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT``
746 must also be set to ``1``.
Jeenu Viswambharan60277962018-01-11 14:30:22 +0000747
Varun Wadekarc2ad38c2019-01-11 14:47:48 -0800748- ``USE_ARM_LINK``: This flag determines whether to enable support for ARM
749 linker. When the ``LINKER`` build variable points to the armlink linker,
750 this flag is enabled automatically. To enable support for armlink, platforms
751 will have to provide a scatter file for the BL image. Currently, Tegra
752 platforms use the armlink support to compile BL3-1 images.
753
Douglas Raillard6f625742017-06-28 15:23:03 +0100754- ``USE_COHERENT_MEM``: This flag determines whether to include the coherent
755 memory region in the BL memory map or not (see "Use of Coherent memory in
Dan Handley4def07d2018-03-01 18:44:00 +0000756 TF-A" section in `Firmware Design`_). It can take the value 1
Douglas Raillard6f625742017-06-28 15:23:03 +0100757 (Coherent memory region is included) or 0 (Coherent memory region is
758 excluded). Default is 1.
759
John Tsichritzis5a8f0a32019-03-19 12:12:55 +0000760- ``USE_ROMLIB``: This flag determines whether library at ROM will be used.
761 This feature creates a library of functions to be placed in ROM and thus
762 reduces SRAM usage. Refer to `Library at ROM`_ for further details. Default
763 is 0.
764
Douglas Raillard6f625742017-06-28 15:23:03 +0100765- ``V``: Verbose build. If assigned anything other than 0, the build commands
766 are printed. Default is 0.
767
Dan Handley4def07d2018-03-01 18:44:00 +0000768- ``VERSION_STRING``: String used in the log output for each TF-A image.
769 Defaults to a string formed by concatenating the version number, build type
770 and build string.
Douglas Raillard6f625742017-06-28 15:23:03 +0100771
772- ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on
773 the CPU after warm boot. This is applicable for platforms which do not
774 require interconnect programming to enable cache coherency (eg: single
775 cluster platforms). If this option is enabled, then warm boot path
776 enables D-caches immediately after enabling MMU. This option defaults to 0.
777
Dan Handley4def07d2018-03-01 18:44:00 +0000778Arm development platform specific build options
Douglas Raillard6f625742017-06-28 15:23:03 +0100779^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
780
781- ``ARM_BL31_IN_DRAM``: Boolean option to select loading of BL31 in TZC secured
782 DRAM. By default, BL31 is in the secure SRAM. Set this flag to 1 to load
783 BL31 in TZC secured DRAM. If TSP is present, then setting this option also
784 sets the TSP location to DRAM and ignores the ``ARM_TSP_RAM_LOCATION`` build
785 flag.
786
Douglas Raillard6f625742017-06-28 15:23:03 +0100787- ``ARM_CONFIG_CNTACR``: boolean option to unlock access to the ``CNTBase<N>``
788 frame registers by setting the ``CNTCTLBase.CNTACR<N>`` register bits. The
789 frame number ``<N>`` is defined by ``PLAT_ARM_NSTIMER_FRAME_ID``, which should
790 match the frame used by the Non-Secure image (normally the Linux kernel).
791 Default is true (access to the frame is allowed).
792
793- ``ARM_DISABLE_TRUSTED_WDOG``: boolean option to disable the Trusted Watchdog.
Dan Handley4def07d2018-03-01 18:44:00 +0000794 By default, Arm platforms use a watchdog to trigger a system reset in case
Douglas Raillard6f625742017-06-28 15:23:03 +0100795 an error is encountered during the boot process (for example, when an image
796 could not be loaded or authenticated). The watchdog is enabled in the early
797 platform setup hook at BL1 and disabled in the BL1 prepare exit hook. The
798 Trusted Watchdog may be disabled at build time for testing or development
799 purposes.
800
Antonio Nino Diazb726c162018-05-11 11:15:10 +0100801- ``ARM_LINUX_KERNEL_AS_BL33``: The Linux kernel expects registers x0-x3 to
802 have specific values at boot. This boolean option allows the Trusted Firmware
803 to have a Linux kernel image as BL33 by preparing the registers to these
Manish Pandeyed2c4f42018-11-02 13:28:25 +0000804 values before jumping to BL33. This option defaults to 0 (disabled). For
805 AArch64 ``RESET_TO_BL31`` and for AArch32 ``RESET_TO_SP_MIN`` must be 1 when
806 using it. If this option is set to 1, ``ARM_PRELOADED_DTB_BASE`` must be set
807 to the location of a device tree blob (DTB) already loaded in memory. The
808 Linux Image address must be specified using the ``PRELOADED_BL33_BASE``
809 option.
Antonio Nino Diazb726c162018-05-11 11:15:10 +0100810
Sandrine Bailleuxe9ebd542019-01-31 13:12:41 +0100811- ``ARM_PLAT_MT``: This flag determines whether the Arm platform layer has to
812 cater for the multi-threading ``MT`` bit when accessing MPIDR. When this flag
813 is set, the functions which deal with MPIDR assume that the ``MT`` bit in
814 MPIDR is set and access the bit-fields in MPIDR accordingly. Default value of
815 this flag is 0. Note that this option is not used on FVP platforms.
816
Douglas Raillard6f625742017-06-28 15:23:03 +0100817- ``ARM_RECOM_STATE_ID_ENC``: The PSCI1.0 specification recommends an encoding
818 for the construction of composite state-ID in the power-state parameter.
819 The existing PSCI clients currently do not support this encoding of
820 State-ID yet. Hence this flag is used to configure whether to use the
821 recommended State-ID encoding or not. The default value of this flag is 0,
822 in which case the platform is configured to expect NULL in the State-ID
823 field of power-state parameter.
824
825- ``ARM_ROTPK_LOCATION``: used when ``TRUSTED_BOARD_BOOT=1``. It specifies the
826 location of the ROTPK hash returned by the function ``plat_get_rotpk_info()``
Dan Handley4def07d2018-03-01 18:44:00 +0000827 for Arm platforms. Depending on the selected option, the proper private key
Douglas Raillard6f625742017-06-28 15:23:03 +0100828 must be specified using the ``ROT_KEY`` option when building the Trusted
829 Firmware. This private key will be used by the certificate generation tool
830 to sign the BL2 and Trusted Key certificates. Available options for
831 ``ARM_ROTPK_LOCATION`` are:
832
833 - ``regs`` : return the ROTPK hash stored in the Trusted root-key storage
834 registers. The private key corresponding to this ROTPK hash is not
835 currently available.
836 - ``devel_rsa`` : return a development public key hash embedded in the BL1
837 and BL2 binaries. This hash has been obtained from the RSA public key
838 ``arm_rotpk_rsa.der``, located in ``plat/arm/board/common/rotpk``. To use
839 this option, ``arm_rotprivk_rsa.pem`` must be specified as ``ROT_KEY`` when
840 creating the certificates.
Qixiang Xu9db9c652017-08-24 15:12:20 +0800841 - ``devel_ecdsa`` : return a development public key hash embedded in the BL1
842 and BL2 binaries. This hash has been obtained from the ECDSA public key
843 ``arm_rotpk_ecdsa.der``, located in ``plat/arm/board/common/rotpk``. To use
844 this option, ``arm_rotprivk_ecdsa.pem`` must be specified as ``ROT_KEY``
845 when creating the certificates.
Douglas Raillard6f625742017-06-28 15:23:03 +0100846
847- ``ARM_TSP_RAM_LOCATION``: location of the TSP binary. Options:
848
Qixiang Xu7ca267b2017-10-13 09:04:12 +0800849 - ``tsram`` : Trusted SRAM (default option when TBB is not enabled)
Douglas Raillard6f625742017-06-28 15:23:03 +0100850 - ``tdram`` : Trusted DRAM (if available)
John Tsichritzis677ad322018-06-06 09:38:10 +0100851 - ``dram`` : Secure region in DRAM (default option when TBB is enabled,
852 configured by the TrustZone controller)
Douglas Raillard6f625742017-06-28 15:23:03 +0100853
Dan Handley4def07d2018-03-01 18:44:00 +0000854- ``ARM_XLAT_TABLES_LIB_V1``: boolean option to compile TF-A with version 1
855 of the translation tables library instead of version 2. It is set to 0 by
856 default, which selects version 2.
Douglas Raillard6f625742017-06-28 15:23:03 +0100857
Dan Handley4def07d2018-03-01 18:44:00 +0000858- ``ARM_CRYPTOCELL_INTEG`` : bool option to enable TF-A to invoke Arm®
859 TrustZone® CryptoCell functionality for Trusted Board Boot on capable Arm
860 platforms. If this option is specified, then the path to the CryptoCell
Douglas Raillard6f625742017-06-28 15:23:03 +0100861 SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag.
862
Dan Handley4def07d2018-03-01 18:44:00 +0000863For a better understanding of these options, the Arm development platform memory
Douglas Raillard6f625742017-06-28 15:23:03 +0100864map is explained in the `Firmware Design`_.
865
Dan Handley4def07d2018-03-01 18:44:00 +0000866Arm CSS platform specific build options
Douglas Raillard6f625742017-06-28 15:23:03 +0100867^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
868
869- ``CSS_DETECT_PRE_1_7_0_SCP``: Boolean flag to detect SCP version
870 incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards
871 compatible change to the MTL protocol, used for AP/SCP communication.
Dan Handley4def07d2018-03-01 18:44:00 +0000872 TF-A no longer supports earlier SCP versions. If this option is set to 1
873 then TF-A will detect if an earlier version is in use. Default is 1.
Douglas Raillard6f625742017-06-28 15:23:03 +0100874
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100875- ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP_BL2 and
876 SCP_BL2U to the FIP and FWU_FIP respectively, and enables them to be loaded
Douglas Raillard6f625742017-06-28 15:23:03 +0100877 during boot. Default is 1.
878
Soby Mathew18e279e2017-06-12 12:37:10 +0100879- ``CSS_USE_SCMI_SDS_DRIVER``: Boolean flag which selects SCMI/SDS drivers
880 instead of SCPI/BOM driver for communicating with the SCP during power
881 management operations and for SCP RAM Firmware transfer. If this option
882 is set to 1, then SCMI/SDS drivers will be used. Default is 0.
Douglas Raillard6f625742017-06-28 15:23:03 +0100883
Dan Handley4def07d2018-03-01 18:44:00 +0000884Arm FVP platform specific build options
Douglas Raillard6f625742017-06-28 15:23:03 +0100885^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
886
887- ``FVP_CLUSTER_COUNT`` : Configures the cluster count to be used to
Dan Handley4def07d2018-03-01 18:44:00 +0000888 build the topology tree within TF-A. By default TF-A is configured for dual
889 cluster topology and this option can be used to override the default value.
Douglas Raillard6f625742017-06-28 15:23:03 +0100890
891- ``FVP_INTERCONNECT_DRIVER``: Selects the interconnect driver to be built. The
892 default interconnect driver depends on the value of ``FVP_CLUSTER_COUNT`` as
893 explained in the options below:
894
895 - ``FVP_CCI`` : The CCI driver is selected. This is the default
896 if 0 < ``FVP_CLUSTER_COUNT`` <= 2.
897 - ``FVP_CCN`` : The CCN driver is selected. This is the default
898 if ``FVP_CLUSTER_COUNT`` > 2.
899
Jeenu Viswambharanfe7210c2018-01-31 14:52:08 +0000900- ``FVP_MAX_CPUS_PER_CLUSTER``: Sets the maximum number of CPUs implemented in
901 a single cluster. This option defaults to 4.
902
Jeenu Viswambharan11ad8f22016-11-15 13:53:57 +0000903- ``FVP_MAX_PE_PER_CPU``: Sets the maximum number of PEs implemented on any CPU
904 in the system. This option defaults to 1. Note that the build option
905 ``ARM_PLAT_MT`` doesn't have any effect on FVP platforms.
906
Douglas Raillard6f625742017-06-28 15:23:03 +0100907- ``FVP_USE_GIC_DRIVER`` : Selects the GIC driver to be built. Options:
908
909 - ``FVP_GIC600`` : The GIC600 implementation of GICv3 is selected
910 - ``FVP_GICV2`` : The GICv2 only driver is selected
911 - ``FVP_GICV3`` : The GICv3 only driver is selected (default option)
Douglas Raillard6f625742017-06-28 15:23:03 +0100912
913- ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer
914 for functions that wait for an arbitrary time length (udelay and mdelay).
915 The default value is 0.
916
Soby Mathewb2a68f82018-02-16 14:52:52 +0000917- ``FVP_HW_CONFIG_DTS`` : Specify the path to the DTS file to be compiled
918 to DTB and packaged in FIP as the HW_CONFIG. See `Firmware Design`_ for
919 details on HW_CONFIG. By default, this is initialized to a sensible DTS
920 file in ``fdts/`` folder depending on other build options. But some cases,
921 like shifted affinity format for MPIDR, cannot be detected at build time
922 and this option is needed to specify the appropriate DTS file.
923
924- ``FVP_HW_CONFIG`` : Specify the path to the HW_CONFIG blob to be packaged in
925 FIP. See `Firmware Design`_ for details on HW_CONFIG. This option is
926 similar to the ``FVP_HW_CONFIG_DTS`` option, but it directly specifies the
927 HW_CONFIG blob instead of the DTS file. This option is useful to override
928 the default HW_CONFIG selected by the build system.
929
Summer Qin60a23fd2018-03-02 15:51:14 +0800930ARM JUNO platform specific build options
931^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
932
933- ``JUNO_TZMP1`` : Boolean option to configure Juno to be used for TrustZone
934 Media Protection (TZ-MP1). Default value of this flag is 0.
935
Douglas Raillard6f625742017-06-28 15:23:03 +0100936Debugging options
937~~~~~~~~~~~~~~~~~
938
939To compile a debug version and make the build more verbose use
940
Paul Beesley29c02522019-03-13 15:11:04 +0000941.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +0100942
943 make PLAT=<platform> DEBUG=1 V=1 all
944
945AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for
946example DS-5) might not support this and may need an older version of DWARF
947symbols to be emitted by GCC. This can be achieved by using the
948``-gdwarf-<version>`` flag, with the version being set to 2 or 3. Setting the
949version to 2 is recommended for DS-5 versions older than 5.16.
950
951When debugging logic problems it might also be useful to disable all compiler
952optimizations by using ``-O0``.
953
Paul Beesleye1c50262019-03-13 16:20:44 +0000954.. warning::
955 Using ``-O0`` could cause output images to be larger and base addresses
956 might need to be recalculated (see the **Memory layout on Arm development
957 platforms** section in the `Firmware Design`_).
Douglas Raillard6f625742017-06-28 15:23:03 +0100958
959Extra debug options can be passed to the build system by setting ``CFLAGS`` or
960``LDFLAGS``:
961
Paul Beesley29c02522019-03-13 15:11:04 +0000962.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +0100963
964 CFLAGS='-O0 -gdwarf-2' \
965 make PLAT=<platform> DEBUG=1 V=1 all
966
967Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be
968ignored as the linker is called directly.
969
970It is also possible to introduce an infinite loop to help in debugging the
Dan Handley4def07d2018-03-01 18:44:00 +0000971post-BL2 phase of TF-A. This can be done by rebuilding BL1 with the
972``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the `Summary of build options`_
Douglas Raillard6f625742017-06-28 15:23:03 +0100973section. In this case, the developer may take control of the target using a
974debugger when indicated by the console output. When using DS-5, the following
975commands can be used:
976
977::
978
979 # Stop target execution
980 interrupt
981
982 #
983 # Prepare your debugging environment, e.g. set breakpoints
984 #
985
986 # Jump over the debug loop
987 set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4
988
989 # Resume execution
990 continue
991
992Building the Test Secure Payload
993~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
994
995The TSP is coupled with a companion runtime service in the BL31 firmware,
996called the TSPD. Therefore, if you intend to use the TSP, the BL31 image
997must be recompiled as well. For more information on SPs and SPDs, see the
998`Secure-EL1 Payloads and Dispatchers`_ section in the `Firmware Design`_.
999
Dan Handley4def07d2018-03-01 18:44:00 +00001000First clean the TF-A build directory to get rid of any previous BL31 binary.
1001Then to build the TSP image use:
Douglas Raillard6f625742017-06-28 15:23:03 +01001002
Paul Beesley29c02522019-03-13 15:11:04 +00001003.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001004
1005 make PLAT=<platform> SPD=tspd all
1006
1007An additional boot loader binary file is created in the ``build`` directory:
1008
1009::
1010
1011 build/<platform>/<build-type>/bl32.bin
1012
Douglas Raillard6f625742017-06-28 15:23:03 +01001013
1014Building and using the FIP tool
1015~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1016
Dan Handley4def07d2018-03-01 18:44:00 +00001017Firmware Image Package (FIP) is a packaging format used by TF-A to package
1018firmware images in a single binary. The number and type of images that should
1019be packed in a FIP is platform specific and may include TF-A images and other
1020firmware images required by the platform. For example, most platforms require
1021a BL33 image which corresponds to the normal world bootloader (e.g. UEFI or
1022U-Boot).
Douglas Raillard6f625742017-06-28 15:23:03 +01001023
Dan Handley4def07d2018-03-01 18:44:00 +00001024The TF-A build system provides the make target ``fip`` to create a FIP file
1025for the specified platform using the FIP creation tool included in the TF-A
1026project. Examples below show how to build a FIP file for FVP, packaging TF-A
1027and BL33 images.
Douglas Raillard6f625742017-06-28 15:23:03 +01001028
1029For AArch64:
1030
Paul Beesley29c02522019-03-13 15:11:04 +00001031.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001032
Ambroise Vincent68126052019-03-14 10:53:16 +00001033 make PLAT=fvp BL33=<path-to>/bl33.bin fip
Douglas Raillard6f625742017-06-28 15:23:03 +01001034
1035For AArch32:
1036
Paul Beesley29c02522019-03-13 15:11:04 +00001037.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001038
Ambroise Vincent68126052019-03-14 10:53:16 +00001039 make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip
Douglas Raillard6f625742017-06-28 15:23:03 +01001040
1041The resulting FIP may be found in:
1042
1043::
1044
1045 build/fvp/<build-type>/fip.bin
1046
1047For advanced operations on FIP files, it is also possible to independently build
1048the tool and create or modify FIPs using this tool. To do this, follow these
1049steps:
1050
1051It is recommended to remove old artifacts before building the tool:
1052
Paul Beesley29c02522019-03-13 15:11:04 +00001053.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001054
1055 make -C tools/fiptool clean
1056
1057Build the tool:
1058
Paul Beesley29c02522019-03-13 15:11:04 +00001059.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001060
1061 make [DEBUG=1] [V=1] fiptool
1062
1063The tool binary can be located in:
1064
1065::
1066
1067 ./tools/fiptool/fiptool
1068
Alexei Fedorov06715f82019-03-13 11:05:07 +00001069Invoking the tool with ``help`` will print a help message with all available
Douglas Raillard6f625742017-06-28 15:23:03 +01001070options.
1071
1072Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31:
1073
Paul Beesley29c02522019-03-13 15:11:04 +00001074.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001075
1076 ./tools/fiptool/fiptool create \
1077 --tb-fw build/<platform>/<build-type>/bl2.bin \
1078 --soc-fw build/<platform>/<build-type>/bl31.bin \
1079 fip.bin
1080
1081Example 2: view the contents of an existing Firmware package:
1082
Paul Beesley29c02522019-03-13 15:11:04 +00001083.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001084
1085 ./tools/fiptool/fiptool info <path-to>/fip.bin
1086
1087Example 3: update the entries of an existing Firmware package:
1088
Paul Beesley29c02522019-03-13 15:11:04 +00001089.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001090
1091 # Change the BL2 from Debug to Release version
1092 ./tools/fiptool/fiptool update \
1093 --tb-fw build/<platform>/release/bl2.bin \
1094 build/<platform>/debug/fip.bin
1095
1096Example 4: unpack all entries from an existing Firmware package:
1097
Paul Beesley29c02522019-03-13 15:11:04 +00001098.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001099
1100 # Images will be unpacked to the working directory
1101 ./tools/fiptool/fiptool unpack <path-to>/fip.bin
1102
1103Example 5: remove an entry from an existing Firmware package:
1104
Paul Beesley29c02522019-03-13 15:11:04 +00001105.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001106
1107 ./tools/fiptool/fiptool remove \
1108 --tb-fw build/<platform>/debug/fip.bin
1109
1110Note that if the destination FIP file exists, the create, update and
1111remove operations will automatically overwrite it.
1112
1113The unpack operation will fail if the images already exist at the
1114destination. In that case, use -f or --force to continue.
1115
1116More information about FIP can be found in the `Firmware Design`_ document.
1117
Douglas Raillard6f625742017-06-28 15:23:03 +01001118Building FIP images with support for Trusted Board Boot
1119~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1120
1121Trusted Board Boot primarily consists of the following two features:
1122
1123- Image Authentication, described in `Trusted Board Boot`_, and
1124- Firmware Update, described in `Firmware Update`_
1125
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01001126The following steps should be followed to build FIP and (optionally) FWU_FIP
Douglas Raillard6f625742017-06-28 15:23:03 +01001127images with support for these features:
1128
1129#. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser
1130 modules by checking out a recent version of the `mbed TLS Repository`_. It
Dan Handley4def07d2018-03-01 18:44:00 +00001131 is important to use a version that is compatible with TF-A and fixes any
Douglas Raillard6f625742017-06-28 15:23:03 +01001132 known security vulnerabilities. See `mbed TLS Security Center`_ for more
Dan Handley4def07d2018-03-01 18:44:00 +00001133 information. The latest version of TF-A is tested with tag
John Tsichritzis62e2d972019-03-12 16:11:17 +00001134 ``mbedtls-2.16.0``.
Douglas Raillard6f625742017-06-28 15:23:03 +01001135
1136 The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS
1137 source files the modules depend upon.
1138 ``include/drivers/auth/mbedtls/mbedtls_config.h`` contains the configuration
1139 options required to build the mbed TLS sources.
1140
1141 Note that the mbed TLS library is licensed under the Apache version 2.0
Dan Handley4def07d2018-03-01 18:44:00 +00001142 license. Using mbed TLS source code will affect the licensing of TF-A
1143 binaries that are built using this library.
Douglas Raillard6f625742017-06-28 15:23:03 +01001144
1145#. To build the FIP image, ensure the following command line variables are set
Dan Handley4def07d2018-03-01 18:44:00 +00001146 while invoking ``make`` to build TF-A:
Douglas Raillard6f625742017-06-28 15:23:03 +01001147
1148 - ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>``
1149 - ``TRUSTED_BOARD_BOOT=1``
1150 - ``GENERATE_COT=1``
1151
Dan Handley4def07d2018-03-01 18:44:00 +00001152 In the case of Arm platforms, the location of the ROTPK hash must also be
Douglas Raillard6f625742017-06-28 15:23:03 +01001153 specified at build time. Two locations are currently supported (see
1154 ``ARM_ROTPK_LOCATION`` build option):
1155
1156 - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted
1157 root-key storage registers present in the platform. On Juno, this
1158 registers are read-only. On FVP Base and Cortex models, the registers
1159 are read-only, but the value can be specified using the command line
1160 option ``bp.trusted_key_storage.public_key`` when launching the model.
1161 On both Juno and FVP models, the default value corresponds to an
1162 ECDSA-SECP256R1 public key hash, whose private part is not currently
1163 available.
1164
1165 - ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded
Dan Handley4def07d2018-03-01 18:44:00 +00001166 in the Arm platform port. The private/public RSA key pair may be
Douglas Raillard6f625742017-06-28 15:23:03 +01001167 found in ``plat/arm/board/common/rotpk``.
1168
Qixiang Xu9db9c652017-08-24 15:12:20 +08001169 - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded
Dan Handley4def07d2018-03-01 18:44:00 +00001170 in the Arm platform port. The private/public ECDSA key pair may be
Qixiang Xu9db9c652017-08-24 15:12:20 +08001171 found in ``plat/arm/board/common/rotpk``.
1172
Douglas Raillard6f625742017-06-28 15:23:03 +01001173 Example of command line using RSA development keys:
1174
Paul Beesley29c02522019-03-13 15:11:04 +00001175 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001176
1177 MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
1178 make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
1179 ARM_ROTPK_LOCATION=devel_rsa \
1180 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
1181 BL33=<path-to>/<bl33_image> \
1182 all fip
1183
1184 The result of this build will be the bl1.bin and the fip.bin binaries. This
1185 FIP will include the certificates corresponding to the Chain of Trust
1186 described in the TBBR-client document. These certificates can also be found
1187 in the output build directory.
1188
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01001189#. The optional FWU_FIP contains any additional images to be loaded from
Douglas Raillard6f625742017-06-28 15:23:03 +01001190 Non-Volatile storage during the `Firmware Update`_ process. To build the
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01001191 FWU_FIP, any FWU images required by the platform must be specified on the
Dan Handley4def07d2018-03-01 18:44:00 +00001192 command line. On Arm development platforms like Juno, these are:
Douglas Raillard6f625742017-06-28 15:23:03 +01001193
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01001194 - NS_BL2U. The AP non-secure Firmware Updater image.
1195 - SCP_BL2U. The SCP Firmware Update Configuration image.
Douglas Raillard6f625742017-06-28 15:23:03 +01001196
1197 Example of Juno command line for generating both ``fwu`` and ``fwu_fip``
1198 targets using RSA development:
1199
1200 ::
1201
1202 MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
1203 make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
1204 ARM_ROTPK_LOCATION=devel_rsa \
1205 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
1206 BL33=<path-to>/<bl33_image> \
1207 SCP_BL2=<path-to>/<scp_bl2_image> \
1208 SCP_BL2U=<path-to>/<scp_bl2u_image> \
1209 NS_BL2U=<path-to>/<ns_bl2u_image> \
1210 all fip fwu_fip
1211
Paul Beesleye1c50262019-03-13 16:20:44 +00001212 .. note::
1213 The BL2U image will be built by default and added to the FWU_FIP.
1214 The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
1215 to the command line above.
Douglas Raillard6f625742017-06-28 15:23:03 +01001216
Paul Beesleye1c50262019-03-13 16:20:44 +00001217 .. note::
1218 Building and installing the non-secure and SCP FWU images (NS_BL1U,
1219 NS_BL2U and SCP_BL2U) is outside the scope of this document.
Douglas Raillard6f625742017-06-28 15:23:03 +01001220
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01001221 The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries.
1222 Both the FIP and FWU_FIP will include the certificates corresponding to the
Douglas Raillard6f625742017-06-28 15:23:03 +01001223 Chain of Trust described in the TBBR-client document. These certificates
1224 can also be found in the output build directory.
1225
1226Building the Certificate Generation Tool
1227~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1228
Dan Handley4def07d2018-03-01 18:44:00 +00001229The ``cert_create`` tool is built as part of the TF-A build process when the
1230``fip`` make target is specified and TBB is enabled (as described in the
1231previous section), but it can also be built separately with the following
1232command:
Douglas Raillard6f625742017-06-28 15:23:03 +01001233
Paul Beesley29c02522019-03-13 15:11:04 +00001234.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001235
1236 make PLAT=<platform> [DEBUG=1] [V=1] certtool
1237
Antonio Nino Diaze23e0572018-09-25 09:41:08 +01001238For platforms that require their own IDs in certificate files, the generic
Paul Beesley573b4cd2019-04-11 13:35:26 +01001239'cert_create' tool can be built with the following command. Note that the target
1240platform must define its IDs within a ``platform_oid.h`` header file for the
1241build to succeed.
Douglas Raillard6f625742017-06-28 15:23:03 +01001242
Paul Beesley29c02522019-03-13 15:11:04 +00001243.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001244
Paul Beesley573b4cd2019-04-11 13:35:26 +01001245 make PLAT=<platform> USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool
Douglas Raillard6f625742017-06-28 15:23:03 +01001246
1247``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
1248verbose. The following command should be used to obtain help about the tool:
1249
Paul Beesley29c02522019-03-13 15:11:04 +00001250.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001251
1252 ./tools/cert_create/cert_create -h
1253
1254Building a FIP for Juno and FVP
1255-------------------------------
1256
1257This section provides Juno and FVP specific instructions to build Trusted
1258Firmware, obtain the additional required firmware, and pack it all together in
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01001259a single FIP binary. It assumes that a `Linaro Release`_ has been installed.
Douglas Raillard6f625742017-06-28 15:23:03 +01001260
Paul Beesleye1c50262019-03-13 16:20:44 +00001261.. note::
1262 Pre-built binaries for AArch32 are available from Linaro Release 16.12
1263 onwards. Before that release, pre-built binaries are only available for
1264 AArch64.
Douglas Raillard6f625742017-06-28 15:23:03 +01001265
Paul Beesleye1c50262019-03-13 16:20:44 +00001266.. warning::
1267 Follow the full instructions for one platform before switching to a
1268 different one. Mixing instructions for different platforms may result in
1269 corrupted binaries.
Douglas Raillard6f625742017-06-28 15:23:03 +01001270
Paul Beesleye1c50262019-03-13 16:20:44 +00001271.. warning::
1272 The uboot image downloaded by the Linaro workspace script does not always
1273 match the uboot image packaged as BL33 in the corresponding fip file. It is
1274 recommended to use the version that is packaged in the fip file using the
1275 instructions below.
Joel Huttonbf7008a2018-03-19 11:59:57 +00001276
Paul Beesleye1c50262019-03-13 16:20:44 +00001277.. note::
1278 For the FVP, the kernel FDT is packaged in FIP during build and loaded
1279 by the firmware at runtime. See `Obtaining the Flattened Device Trees`_
1280 section for more info on selecting the right FDT to use.
Soby Mathew7e8686d2018-05-09 13:59:29 +01001281
Douglas Raillard6f625742017-06-28 15:23:03 +01001282#. Clean the working directory
1283
Paul Beesley29c02522019-03-13 15:11:04 +00001284 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001285
1286 make realclean
1287
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01001288#. Obtain SCP_BL2 (Juno) and BL33 (all platforms)
Douglas Raillard6f625742017-06-28 15:23:03 +01001289
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01001290 Use the fiptool to extract the SCP_BL2 and BL33 images from the FIP
Douglas Raillard6f625742017-06-28 15:23:03 +01001291 package included in the Linaro release:
1292
Paul Beesley29c02522019-03-13 15:11:04 +00001293 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001294
1295 # Build the fiptool
1296 make [DEBUG=1] [V=1] fiptool
1297
1298 # Unpack firmware images from Linaro FIP
Ambroise Vincent68126052019-03-14 10:53:16 +00001299 ./tools/fiptool/fiptool unpack <path-to-linaro-release>/fip.bin
Douglas Raillard6f625742017-06-28 15:23:03 +01001300
1301 The unpack operation will result in a set of binary images extracted to the
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01001302 current working directory. The SCP_BL2 image corresponds to
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01001303 ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``.
Douglas Raillard6f625742017-06-28 15:23:03 +01001304
Paul Beesleye1c50262019-03-13 16:20:44 +00001305 .. note::
1306 The fiptool will complain if the images to be unpacked already
1307 exist in the current directory. If that is the case, either delete those
1308 files or use the ``--force`` option to overwrite.
Douglas Raillard6f625742017-06-28 15:23:03 +01001309
Paul Beesleye1c50262019-03-13 16:20:44 +00001310 .. note::
1311 For AArch32, the instructions below assume that nt-fw.bin is a
1312 normal world boot loader that supports AArch32.
Douglas Raillard6f625742017-06-28 15:23:03 +01001313
Dan Handley4def07d2018-03-01 18:44:00 +00001314#. Build TF-A images and create a new FIP for FVP
Douglas Raillard6f625742017-06-28 15:23:03 +01001315
Paul Beesley29c02522019-03-13 15:11:04 +00001316 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001317
1318 # AArch64
1319 make PLAT=fvp BL33=nt-fw.bin all fip
1320
1321 # AArch32
1322 make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip
1323
Dan Handley4def07d2018-03-01 18:44:00 +00001324#. Build TF-A images and create a new FIP for Juno
Douglas Raillard6f625742017-06-28 15:23:03 +01001325
1326 For AArch64:
1327
1328 Building for AArch64 on Juno simply requires the addition of ``SCP_BL2``
1329 as a build parameter.
1330
Paul Beesley29c02522019-03-13 15:11:04 +00001331 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001332
Ambroise Vincent68126052019-03-14 10:53:16 +00001333 make PLAT=juno BL33=nt-fw.bin SCP_BL2=scp-fw.bin all fip
Douglas Raillard6f625742017-06-28 15:23:03 +01001334
1335 For AArch32:
1336
1337 Hardware restrictions on Juno prevent cold reset into AArch32 execution mode,
1338 therefore BL1 and BL2 must be compiled for AArch64, and BL32 is compiled
1339 separately for AArch32.
1340
1341 - Before building BL32, the environment variable ``CROSS_COMPILE`` must point
1342 to the AArch32 Linaro cross compiler.
1343
Paul Beesley29c02522019-03-13 15:11:04 +00001344 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001345
1346 export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
1347
1348 - Build BL32 in AArch32.
1349
Paul Beesley29c02522019-03-13 15:11:04 +00001350 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001351
1352 make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \
1353 RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32
1354
Ambroise Vincent68126052019-03-14 10:53:16 +00001355 - Save ``bl32.bin`` to a temporary location and clean the build products.
1356
1357 ::
1358
1359 cp <path-to-build>/bl32.bin <path-to-temporary>
1360 make realclean
1361
Douglas Raillard6f625742017-06-28 15:23:03 +01001362 - Before building BL1 and BL2, the environment variable ``CROSS_COMPILE``
1363 must point to the AArch64 Linaro cross compiler.
1364
Paul Beesley29c02522019-03-13 15:11:04 +00001365 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001366
1367 export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
1368
1369 - The following parameters should be used to build BL1 and BL2 in AArch64
1370 and point to the BL32 file.
1371
Paul Beesley29c02522019-03-13 15:11:04 +00001372 .. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001373
Soby Mathew509af922018-09-27 16:46:41 +01001374 make ARCH=aarch64 PLAT=juno JUNO_AARCH32_EL3_RUNTIME=1 \
Ambroise Vincent68126052019-03-14 10:53:16 +00001375 BL33=nt-fw.bin SCP_BL2=scp-fw.bin \
1376 BL32=<path-to-temporary>/bl32.bin all fip
Douglas Raillard6f625742017-06-28 15:23:03 +01001377
1378The resulting BL1 and FIP images may be found in:
1379
1380::
1381
1382 # Juno
1383 ./build/juno/release/bl1.bin
1384 ./build/juno/release/fip.bin
1385
1386 # FVP
1387 ./build/fvp/release/bl1.bin
1388 ./build/fvp/release/fip.bin
1389
Roberto Vargase29ee462017-10-17 10:19:00 +01001390
1391Booting Firmware Update images
1392-------------------------------------
1393
1394When Firmware Update (FWU) is enabled there are at least 2 new images
1395that have to be loaded, the Non-Secure FWU ROM (NS-BL1U), and the
1396FWU FIP.
1397
1398Juno
1399~~~~
1400
1401The new images must be programmed in flash memory by adding
1402an entry in the ``SITE1/HBI0262x/images.txt`` configuration file
1403on the Juno SD card (where ``x`` depends on the revision of the Juno board).
1404Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory
1405programming" for more information. User should ensure these do not
1406overlap with any other entries in the file.
1407
1408::
1409
1410 NOR10UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
1411 NOR10ADDRESS: 0x00400000 ;Image Flash Address [ns_bl2u_base_address]
1412 NOR10FILE: \SOFTWARE\fwu_fip.bin ;Image File Name
1413 NOR10LOAD: 00000000 ;Image Load Address
1414 NOR10ENTRY: 00000000 ;Image Entry Point
1415
1416 NOR11UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
1417 NOR11ADDRESS: 0x03EB8000 ;Image Flash Address [ns_bl1u_base_address]
1418 NOR11FILE: \SOFTWARE\ns_bl1u.bin ;Image File Name
1419 NOR11LOAD: 00000000 ;Image Load Address
1420
1421The address ns_bl1u_base_address is the value of NS_BL1U_BASE - 0x8000000.
1422In the same way, the address ns_bl2u_base_address is the value of
1423NS_BL2U_BASE - 0x8000000.
1424
1425FVP
1426~~~
1427
1428The additional fip images must be loaded with:
1429
1430::
1431
1432 --data cluster0.cpu0="<path_to>/ns_bl1u.bin"@0x0beb8000 [ns_bl1u_base_address]
1433 --data cluster0.cpu0="<path_to>/fwu_fip.bin"@0x08400000 [ns_bl2u_base_address]
1434
1435The address ns_bl1u_base_address is the value of NS_BL1U_BASE.
1436In the same way, the address ns_bl2u_base_address is the value of
1437NS_BL2U_BASE.
1438
1439
Douglas Raillard6f625742017-06-28 15:23:03 +01001440EL3 payloads alternative boot flow
1441----------------------------------
1442
1443On a pre-production system, the ability to execute arbitrary, bare-metal code at
1444the highest exception level is required. It allows full, direct access to the
1445hardware, for example to run silicon soak tests.
1446
1447Although it is possible to implement some baremetal secure firmware from
1448scratch, this is a complex task on some platforms, depending on the level of
1449configuration required to put the system in the expected state.
1450
1451Rather than booting a baremetal application, a possible compromise is to boot
Dan Handley4def07d2018-03-01 18:44:00 +00001452``EL3 payloads`` through TF-A instead. This is implemented as an alternative
1453boot flow, where a modified BL2 boots an EL3 payload, instead of loading the
1454other BL images and passing control to BL31. It reduces the complexity of
1455developing EL3 baremetal code by:
Douglas Raillard6f625742017-06-28 15:23:03 +01001456
1457- putting the system into a known architectural state;
1458- taking care of platform secure world initialization;
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01001459- loading the SCP_BL2 image if required by the platform.
Douglas Raillard6f625742017-06-28 15:23:03 +01001460
Dan Handley4def07d2018-03-01 18:44:00 +00001461When booting an EL3 payload on Arm standard platforms, the configuration of the
Douglas Raillard6f625742017-06-28 15:23:03 +01001462TrustZone controller is simplified such that only region 0 is enabled and is
1463configured to permit secure access only. This gives full access to the whole
1464DRAM to the EL3 payload.
1465
1466The system is left in the same state as when entering BL31 in the default boot
1467flow. In particular:
1468
1469- Running in EL3;
1470- Current state is AArch64;
1471- Little-endian data access;
1472- All exceptions disabled;
1473- MMU disabled;
1474- Caches disabled.
1475
1476Booting an EL3 payload
1477~~~~~~~~~~~~~~~~~~~~~~
1478
1479The EL3 payload image is a standalone image and is not part of the FIP. It is
Dan Handley4def07d2018-03-01 18:44:00 +00001480not loaded by TF-A. Therefore, there are 2 possible scenarios:
Douglas Raillard6f625742017-06-28 15:23:03 +01001481
1482- The EL3 payload may reside in non-volatile memory (NVM) and execute in
1483 place. In this case, booting it is just a matter of specifying the right
Dan Handley4def07d2018-03-01 18:44:00 +00001484 address in NVM through ``EL3_PAYLOAD_BASE`` when building TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01001485
1486- The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at
1487 run-time.
1488
1489To help in the latter scenario, the ``SPIN_ON_BL1_EXIT=1`` build option can be
1490used. The infinite loop that it introduces in BL1 stops execution at the right
1491moment for a debugger to take control of the target and load the payload (for
1492example, over JTAG).
1493
1494It is expected that this loading method will work in most cases, as a debugger
1495connection is usually available in a pre-production system. The user is free to
1496use any other platform-specific mechanism to load the EL3 payload, though.
1497
1498Booting an EL3 payload on FVP
1499^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1500
1501The EL3 payloads boot flow requires the CPU's mailbox to be cleared at reset for
1502the secondary CPUs holding pen to work properly. Unfortunately, its reset value
1503is undefined on the FVP platform and the FVP platform code doesn't clear it.
1504Therefore, one must modify the way the model is normally invoked in order to
1505clear the mailbox at start-up.
1506
1507One way to do that is to create an 8-byte file containing all zero bytes using
1508the following command:
1509
Paul Beesley29c02522019-03-13 15:11:04 +00001510.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001511
1512 dd if=/dev/zero of=mailbox.dat bs=1 count=8
1513
1514and pre-load it into the FVP memory at the mailbox address (i.e. ``0x04000000``)
1515using the following model parameters:
1516
1517::
1518
1519 --data cluster0.cpu0=mailbox.dat@0x04000000 [Base FVPs]
1520 --data=mailbox.dat@0x04000000 [Foundation FVP]
1521
1522To provide the model with the EL3 payload image, the following methods may be
1523used:
1524
1525#. If the EL3 payload is able to execute in place, it may be programmed into
1526 flash memory. On Base Cortex and AEM FVPs, the following model parameter
1527 loads it at the base address of the NOR FLASH1 (the NOR FLASH0 is already
1528 used for the FIP):
1529
1530 ::
1531
Ambroise Vincent68126052019-03-14 10:53:16 +00001532 -C bp.flashloader1.fname="<path-to>/<el3-payload>"
Douglas Raillard6f625742017-06-28 15:23:03 +01001533
1534 On Foundation FVP, there is no flash loader component and the EL3 payload
1535 may be programmed anywhere in flash using method 3 below.
1536
1537#. When using the ``SPIN_ON_BL1_EXIT=1`` loading method, the following DS-5
1538 command may be used to load the EL3 payload ELF image over JTAG:
1539
1540 ::
1541
Ambroise Vincent68126052019-03-14 10:53:16 +00001542 load <path-to>/el3-payload.elf
Douglas Raillard6f625742017-06-28 15:23:03 +01001543
1544#. The EL3 payload may be pre-loaded in volatile memory using the following
1545 model parameters:
1546
1547 ::
1548
Ambroise Vincent68126052019-03-14 10:53:16 +00001549 --data cluster0.cpu0="<path-to>/el3-payload>"@address [Base FVPs]
1550 --data="<path-to>/<el3-payload>"@address [Foundation FVP]
Douglas Raillard6f625742017-06-28 15:23:03 +01001551
1552 The address provided to the FVP must match the ``EL3_PAYLOAD_BASE`` address
Dan Handley4def07d2018-03-01 18:44:00 +00001553 used when building TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01001554
1555Booting an EL3 payload on Juno
1556^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1557
1558If the EL3 payload is able to execute in place, it may be programmed in flash
1559memory by adding an entry in the ``SITE1/HBI0262x/images.txt`` configuration file
1560on the Juno SD card (where ``x`` depends on the revision of the Juno board).
1561Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory
1562programming" for more information.
1563
1564Alternatively, the same DS-5 command mentioned in the FVP section above can
1565be used to load the EL3 payload's ELF file over JTAG on Juno.
1566
1567Preloaded BL33 alternative boot flow
1568------------------------------------
1569
1570Some platforms have the ability to preload BL33 into memory instead of relying
Dan Handley4def07d2018-03-01 18:44:00 +00001571on TF-A to load it. This may simplify packaging of the normal world code and
1572improve performance in a development environment. When secure world cold boot
1573is complete, TF-A simply jumps to a BL33 base address provided at build time.
Douglas Raillard6f625742017-06-28 15:23:03 +01001574
1575For this option to be used, the ``PRELOADED_BL33_BASE`` build option has to be
Dan Handley4def07d2018-03-01 18:44:00 +00001576used when compiling TF-A. For example, the following command will create a FIP
1577without a BL33 and prepare to jump to a BL33 image loaded at address
15780x80000000:
Douglas Raillard6f625742017-06-28 15:23:03 +01001579
Paul Beesley29c02522019-03-13 15:11:04 +00001580.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001581
1582 make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip
1583
Antonio Nino Diaz32412a82018-05-14 09:12:34 +01001584Boot of a preloaded kernel image on Base FVP
1585~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillard6f625742017-06-28 15:23:03 +01001586
Antonio Nino Diaz32412a82018-05-14 09:12:34 +01001587The following example uses a simplified boot flow by directly jumping from the
1588TF-A to the Linux kernel, which will use a ramdisk as filesystem. This can be
1589useful if both the kernel and the device tree blob (DTB) are already present in
1590memory (like in FVP).
1591
1592For example, if the kernel is loaded at ``0x80080000`` and the DTB is loaded at
1593address ``0x82000000``, the firmware can be built like this:
Douglas Raillard6f625742017-06-28 15:23:03 +01001594
Paul Beesley29c02522019-03-13 15:11:04 +00001595.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001596
Antonio Nino Diaz32412a82018-05-14 09:12:34 +01001597 CROSS_COMPILE=aarch64-linux-gnu- \
1598 make PLAT=fvp DEBUG=1 \
1599 RESET_TO_BL31=1 \
1600 ARM_LINUX_KERNEL_AS_BL33=1 \
1601 PRELOADED_BL33_BASE=0x80080000 \
1602 ARM_PRELOADED_DTB_BASE=0x82000000 \
1603 all fip
Douglas Raillard6f625742017-06-28 15:23:03 +01001604
Antonio Nino Diaz32412a82018-05-14 09:12:34 +01001605Now, it is needed to modify the DTB so that the kernel knows the address of the
1606ramdisk. The following script generates a patched DTB from the provided one,
1607assuming that the ramdisk is loaded at address ``0x84000000``. Note that this
1608script assumes that the user is using a ramdisk image prepared for U-Boot, like
1609the ones provided by Linaro. If using a ramdisk without this header,the ``0x40``
1610offset in ``INITRD_START`` has to be removed.
1611
1612.. code:: bash
1613
1614 #!/bin/bash
1615
1616 # Path to the input DTB
1617 KERNEL_DTB=<path-to>/<fdt>
1618 # Path to the output DTB
1619 PATCHED_KERNEL_DTB=<path-to>/<patched-fdt>
1620 # Base address of the ramdisk
1621 INITRD_BASE=0x84000000
1622 # Path to the ramdisk
1623 INITRD=<path-to>/<ramdisk.img>
1624
1625 # Skip uboot header (64 bytes)
1626 INITRD_START=$(printf "0x%x" $((${INITRD_BASE} + 0x40)) )
1627 INITRD_SIZE=$(stat -Lc %s ${INITRD})
1628 INITRD_END=$(printf "0x%x" $((${INITRD_BASE} + ${INITRD_SIZE})) )
1629
1630 CHOSEN_NODE=$(echo \
1631 "/ { \
1632 chosen { \
1633 linux,initrd-start = <${INITRD_START}>; \
1634 linux,initrd-end = <${INITRD_END}>; \
1635 }; \
1636 };")
1637
1638 echo $(dtc -O dts -I dtb ${KERNEL_DTB}) ${CHOSEN_NODE} | \
1639 dtc -O dtb -o ${PATCHED_KERNEL_DTB} -
1640
1641And the FVP binary can be run with the following command:
Douglas Raillard6f625742017-06-28 15:23:03 +01001642
Paul Beesley29c02522019-03-13 15:11:04 +00001643.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001644
Antonio Nino Diaz32412a82018-05-14 09:12:34 +01001645 <path-to>/FVP_Base_AEMv8A-AEMv8A \
1646 -C pctl.startup=0.0.0.0 \
1647 -C bp.secure_memory=1 \
1648 -C cluster0.NUM_CORES=4 \
1649 -C cluster1.NUM_CORES=4 \
1650 -C cache_state_modelled=1 \
1651 -C cluster0.cpu0.RVBAR=0x04020000 \
1652 -C cluster0.cpu1.RVBAR=0x04020000 \
1653 -C cluster0.cpu2.RVBAR=0x04020000 \
1654 -C cluster0.cpu3.RVBAR=0x04020000 \
1655 -C cluster1.cpu0.RVBAR=0x04020000 \
1656 -C cluster1.cpu1.RVBAR=0x04020000 \
1657 -C cluster1.cpu2.RVBAR=0x04020000 \
1658 -C cluster1.cpu3.RVBAR=0x04020000 \
1659 --data cluster0.cpu0="<path-to>/bl31.bin"@0x04020000 \
1660 --data cluster0.cpu0="<path-to>/<patched-fdt>"@0x82000000 \
1661 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
1662 --data cluster0.cpu0="<path-to>/<ramdisk.img>"@0x84000000
Douglas Raillard6f625742017-06-28 15:23:03 +01001663
Antonio Nino Diaz32412a82018-05-14 09:12:34 +01001664Boot of a preloaded kernel image on Juno
1665~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillard6f625742017-06-28 15:23:03 +01001666
Antonio Nino Diaz32412a82018-05-14 09:12:34 +01001667The Trusted Firmware must be compiled in a similar way as for FVP explained
1668above. The process to load binaries to memory is the one explained in
1669`Booting an EL3 payload on Juno`_.
Douglas Raillard6f625742017-06-28 15:23:03 +01001670
1671Running the software on FVP
1672---------------------------
1673
David Cunado855ac022018-03-12 18:47:05 +00001674The latest version of the AArch64 build of TF-A has been tested on the following
1675Arm FVPs without shifted affinities, and that do not support threaded CPU cores
1676(64-bit host machine only).
Douglas Raillard6f625742017-06-28 15:23:03 +01001677
Paul Beesleye1c50262019-03-13 16:20:44 +00001678.. note::
1679 The FVP models used are Version 11.6 Build 45, unless otherwise stated.
David Cunado64d50c72017-06-27 17:31:12 +01001680
David Cunadoeb19da92017-12-19 16:33:25 +00001681- ``FVP_Base_AEMv8A-AEMv8A``
1682- ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502``
David Cunadoeb19da92017-12-19 16:33:25 +00001683- ``FVP_Base_RevC-2xAEMv8A``
1684- ``FVP_Base_Cortex-A32x4``
David Cunado64d50c72017-06-27 17:31:12 +01001685- ``FVP_Base_Cortex-A35x4``
1686- ``FVP_Base_Cortex-A53x4``
David Cunadoeb19da92017-12-19 16:33:25 +00001687- ``FVP_Base_Cortex-A55x4+Cortex-A75x4``
1688- ``FVP_Base_Cortex-A55x4``
Ambroise Vincent61924482019-03-28 12:51:48 +00001689- ``FVP_Base_Cortex-A57x1-A53x1``
1690- ``FVP_Base_Cortex-A57x2-A53x4``
David Cunado64d50c72017-06-27 17:31:12 +01001691- ``FVP_Base_Cortex-A57x4-A53x4``
1692- ``FVP_Base_Cortex-A57x4``
1693- ``FVP_Base_Cortex-A72x4-A53x4``
1694- ``FVP_Base_Cortex-A72x4``
1695- ``FVP_Base_Cortex-A73x4-A53x4``
1696- ``FVP_Base_Cortex-A73x4``
David Cunadoeb19da92017-12-19 16:33:25 +00001697- ``FVP_Base_Cortex-A75x4``
1698- ``FVP_Base_Cortex-A76x4``
John Tsichritzis532a67d2019-05-20 13:09:34 +01001699- ``FVP_Base_Cortex-A76AEx4``
1700- ``FVP_Base_Cortex-A76AEx8``
1701- ``FVP_Base_Neoverse-N1x4``
Ambroise Vincent61924482019-03-28 12:51:48 +00001702- ``FVP_Base_Deimos``
Ambroise Vincent68126052019-03-14 10:53:16 +00001703- ``FVP_CSS_SGI-575`` (Version 11.3 build 42)
Ambroise Vincent61924482019-03-28 12:51:48 +00001704- ``FVP_CSS_SGM-775`` (Version 11.3 build 42)
1705- ``FVP_RD_E1Edge`` (Version 11.3 build 42)
John Tsichritzis532a67d2019-05-20 13:09:34 +01001706- ``FVP_RD_N1Edge``
David Cunadoeb19da92017-12-19 16:33:25 +00001707- ``Foundation_Platform``
David Cunado855ac022018-03-12 18:47:05 +00001708
1709The latest version of the AArch32 build of TF-A has been tested on the following
1710Arm FVPs without shifted affinities, and that do not support threaded CPU cores
1711(64-bit host machine only).
1712
1713- ``FVP_Base_AEMv8A-AEMv8A``
David Cunado64d50c72017-06-27 17:31:12 +01001714- ``FVP_Base_Cortex-A32x4``
Douglas Raillard6f625742017-06-28 15:23:03 +01001715
Paul Beesleye1c50262019-03-13 16:20:44 +00001716.. note::
1717 The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which
1718 is not compatible with legacy GIC configurations. Therefore this FVP does not
1719 support these legacy GIC configurations.
David Cunado855ac022018-03-12 18:47:05 +00001720
Paul Beesleye1c50262019-03-13 16:20:44 +00001721.. note::
1722 The build numbers quoted above are those reported by launching the FVP
1723 with the ``--version`` parameter.
Douglas Raillard6f625742017-06-28 15:23:03 +01001724
Paul Beesleye1c50262019-03-13 16:20:44 +00001725.. note::
1726 Linaro provides a ramdisk image in prebuilt FVP configurations and full
1727 file systems that can be downloaded separately. To run an FVP with a virtio
1728 file system image an additional FVP configuration option
1729 ``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
1730 used.
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01001731
Paul Beesleye1c50262019-03-13 16:20:44 +00001732.. note::
1733 The software will not work on Version 1.0 of the Foundation FVP.
1734 The commands below would report an ``unhandled argument`` error in this case.
Douglas Raillard6f625742017-06-28 15:23:03 +01001735
Paul Beesleye1c50262019-03-13 16:20:44 +00001736.. note::
1737 FVPs can be launched with ``--cadi-server`` option such that a
1738 CADI-compliant debugger (for example, Arm DS-5) can connect to and control
1739 its execution.
Douglas Raillard6f625742017-06-28 15:23:03 +01001740
Paul Beesleye1c50262019-03-13 16:20:44 +00001741.. warning::
1742 Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202
1743 the internal synchronisation timings changed compared to older versions of
1744 the models. The models can be launched with ``-Q 100`` option if they are
1745 required to match the run time characteristics of the older versions.
David Cunado279fedc2017-07-31 12:24:51 +01001746
Douglas Raillard6f625742017-06-28 15:23:03 +01001747The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
Dan Handley4def07d2018-03-01 18:44:00 +00001748downloaded for free from `Arm's website`_.
Douglas Raillard6f625742017-06-28 15:23:03 +01001749
David Cunado64d50c72017-06-27 17:31:12 +01001750The Cortex-A models listed above are also available to download from
Dan Handley4def07d2018-03-01 18:44:00 +00001751`Arm's website`_.
David Cunado64d50c72017-06-27 17:31:12 +01001752
Douglas Raillard6f625742017-06-28 15:23:03 +01001753Please refer to the FVP documentation for a detailed description of the model
Dan Handley4def07d2018-03-01 18:44:00 +00001754parameter options. A brief description of the important ones that affect TF-A
1755and normal world software behavior is provided below.
Douglas Raillard6f625742017-06-28 15:23:03 +01001756
Douglas Raillard6f625742017-06-28 15:23:03 +01001757Obtaining the Flattened Device Trees
1758~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1759
1760Depending on the FVP configuration and Linux configuration used, different
Soby Mathew7e8686d2018-05-09 13:59:29 +01001761FDT files are required. FDT source files for the Foundation and Base FVPs can
1762be found in the TF-A source directory under ``fdts/``. The Foundation FVP has
1763a subset of the Base FVP components. For example, the Foundation FVP lacks
1764CLCD and MMC support, and has only one CPU cluster.
Douglas Raillard6f625742017-06-28 15:23:03 +01001765
Paul Beesleye1c50262019-03-13 16:20:44 +00001766.. note::
1767 It is not recommended to use the FDTs built along the kernel because not
1768 all FDTs are available from there.
Douglas Raillard6f625742017-06-28 15:23:03 +01001769
Soby Mathew7e8686d2018-05-09 13:59:29 +01001770The dynamic configuration capability is enabled in the firmware for FVPs.
1771This means that the firmware can authenticate and load the FDT if present in
1772FIP. A default FDT is packaged into FIP during the build based on
1773the build configuration. This can be overridden by using the ``FVP_HW_CONFIG``
1774or ``FVP_HW_CONFIG_DTS`` build options (refer to the
1775`Arm FVP platform specific build options`_ section for detail on the options).
1776
1777- ``fvp-base-gicv2-psci.dts``
Douglas Raillard6f625742017-06-28 15:23:03 +01001778
David Cunado855ac022018-03-12 18:47:05 +00001779 For use with models such as the Cortex-A57-A53 Base FVPs without shifted
1780 affinities and with Base memory map configuration.
Douglas Raillard6f625742017-06-28 15:23:03 +01001781
Soby Mathew7e8686d2018-05-09 13:59:29 +01001782- ``fvp-base-gicv2-psci-aarch32.dts``
Douglas Raillard6f625742017-06-28 15:23:03 +01001783
David Cunado855ac022018-03-12 18:47:05 +00001784 For use with models such as the Cortex-A32 Base FVPs without shifted
1785 affinities and running Linux in AArch32 state with Base memory map
1786 configuration.
Douglas Raillard6f625742017-06-28 15:23:03 +01001787
Soby Mathew7e8686d2018-05-09 13:59:29 +01001788- ``fvp-base-gicv3-psci.dts``
Douglas Raillard6f625742017-06-28 15:23:03 +01001789
David Cunado855ac022018-03-12 18:47:05 +00001790 For use with models such as the Cortex-A57-A53 Base FVPs without shifted
1791 affinities and with Base memory map configuration and Linux GICv3 support.
1792
Soby Mathew7e8686d2018-05-09 13:59:29 +01001793- ``fvp-base-gicv3-psci-1t.dts``
David Cunado855ac022018-03-12 18:47:05 +00001794
1795 For use with models such as the AEMv8-RevC Base FVP with shifted affinities,
1796 single threaded CPUs, Base memory map configuration and Linux GICv3 support.
1797
Soby Mathew7e8686d2018-05-09 13:59:29 +01001798- ``fvp-base-gicv3-psci-dynamiq.dts``
David Cunado855ac022018-03-12 18:47:05 +00001799
1800 For use with models as the Cortex-A55-A75 Base FVPs with shifted affinities,
1801 single cluster, single threaded CPUs, Base memory map configuration and Linux
1802 GICv3 support.
Douglas Raillard6f625742017-06-28 15:23:03 +01001803
Soby Mathew7e8686d2018-05-09 13:59:29 +01001804- ``fvp-base-gicv3-psci-aarch32.dts``
Douglas Raillard6f625742017-06-28 15:23:03 +01001805
David Cunado855ac022018-03-12 18:47:05 +00001806 For use with models such as the Cortex-A32 Base FVPs without shifted
1807 affinities and running Linux in AArch32 state with Base memory map
1808 configuration and Linux GICv3 support.
Douglas Raillard6f625742017-06-28 15:23:03 +01001809
Soby Mathew7e8686d2018-05-09 13:59:29 +01001810- ``fvp-foundation-gicv2-psci.dts``
Douglas Raillard6f625742017-06-28 15:23:03 +01001811
1812 For use with Foundation FVP with Base memory map configuration.
1813
Soby Mathew7e8686d2018-05-09 13:59:29 +01001814- ``fvp-foundation-gicv3-psci.dts``
Douglas Raillard6f625742017-06-28 15:23:03 +01001815
1816 (Default) For use with Foundation FVP with Base memory map configuration
1817 and Linux GICv3 support.
1818
1819Running on the Foundation FVP with reset to BL1 entrypoint
1820~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1821
1822The following ``Foundation_Platform`` parameters should be used to boot Linux with
Dan Handley4def07d2018-03-01 18:44:00 +000018234 CPUs using the AArch64 build of TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01001824
Paul Beesley29c02522019-03-13 15:11:04 +00001825.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001826
1827 <path-to>/Foundation_Platform \
1828 --cores=4 \
Antonio Nino Diaz38d96de2018-02-23 11:01:31 +00001829 --arm-v8.0 \
Douglas Raillard6f625742017-06-28 15:23:03 +01001830 --secure-memory \
1831 --visualization \
1832 --gicv3 \
1833 --data="<path-to>/<bl1-binary>"@0x0 \
1834 --data="<path-to>/<FIP-binary>"@0x08000000 \
Douglas Raillard6f625742017-06-28 15:23:03 +01001835 --data="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01001836 --data="<path-to>/<ramdisk-binary>"@0x84000000
Douglas Raillard6f625742017-06-28 15:23:03 +01001837
1838Notes:
1839
1840- BL1 is loaded at the start of the Trusted ROM.
1841- The Firmware Image Package is loaded at the start of NOR FLASH0.
Soby Mathew7e8686d2018-05-09 13:59:29 +01001842- The firmware loads the FDT packaged in FIP to the DRAM. The FDT load address
1843 is specified via the ``hw_config_addr`` property in `TB_FW_CONFIG for FVP`_.
Douglas Raillard6f625742017-06-28 15:23:03 +01001844- The default use-case for the Foundation FVP is to use the ``--gicv3`` option
1845 and enable the GICv3 device in the model. Note that without this option,
1846 the Foundation FVP defaults to legacy (Versatile Express) memory map which
Dan Handley4def07d2018-03-01 18:44:00 +00001847 is not supported by TF-A.
1848- In order for TF-A to run correctly on the Foundation FVP, the architecture
1849 versions must match. The Foundation FVP defaults to the highest v8.x
1850 version it supports but the default build for TF-A is for v8.0. To avoid
1851 issues either start the Foundation FVP to use v8.0 architecture using the
1852 ``--arm-v8.0`` option, or build TF-A with an appropriate value for
1853 ``ARM_ARCH_MINOR``.
Douglas Raillard6f625742017-06-28 15:23:03 +01001854
1855Running on the AEMv8 Base FVP with reset to BL1 entrypoint
1856~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1857
David Cunado855ac022018-03-12 18:47:05 +00001858The following ``FVP_Base_RevC-2xAEMv8A`` parameters should be used to boot Linux
Dan Handley4def07d2018-03-01 18:44:00 +00001859with 8 CPUs using the AArch64 build of TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01001860
Paul Beesley29c02522019-03-13 15:11:04 +00001861.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001862
David Cunado855ac022018-03-12 18:47:05 +00001863 <path-to>/FVP_Base_RevC-2xAEMv8A \
Douglas Raillard6f625742017-06-28 15:23:03 +01001864 -C pctl.startup=0.0.0.0 \
1865 -C bp.secure_memory=1 \
1866 -C bp.tzc_400.diagnostics=1 \
1867 -C cluster0.NUM_CORES=4 \
1868 -C cluster1.NUM_CORES=4 \
1869 -C cache_state_modelled=1 \
1870 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
1871 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
Douglas Raillard6f625742017-06-28 15:23:03 +01001872 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01001873 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillard6f625742017-06-28 15:23:03 +01001874
Paul Beesleye1c50262019-03-13 16:20:44 +00001875.. note::
1876 The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires
1877 a specific DTS for all the CPUs to be loaded.
Ambroise Vincent68126052019-03-14 10:53:16 +00001878
Douglas Raillard6f625742017-06-28 15:23:03 +01001879Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint
1880~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1881
1882The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
Dan Handley4def07d2018-03-01 18:44:00 +00001883with 8 CPUs using the AArch32 build of TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01001884
Paul Beesley29c02522019-03-13 15:11:04 +00001885.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001886
1887 <path-to>/FVP_Base_AEMv8A-AEMv8A \
1888 -C pctl.startup=0.0.0.0 \
1889 -C bp.secure_memory=1 \
1890 -C bp.tzc_400.diagnostics=1 \
1891 -C cluster0.NUM_CORES=4 \
1892 -C cluster1.NUM_CORES=4 \
1893 -C cache_state_modelled=1 \
1894 -C cluster0.cpu0.CONFIG64=0 \
1895 -C cluster0.cpu1.CONFIG64=0 \
1896 -C cluster0.cpu2.CONFIG64=0 \
1897 -C cluster0.cpu3.CONFIG64=0 \
1898 -C cluster1.cpu0.CONFIG64=0 \
1899 -C cluster1.cpu1.CONFIG64=0 \
1900 -C cluster1.cpu2.CONFIG64=0 \
1901 -C cluster1.cpu3.CONFIG64=0 \
1902 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
1903 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
Douglas Raillard6f625742017-06-28 15:23:03 +01001904 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01001905 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillard6f625742017-06-28 15:23:03 +01001906
1907Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint
1908~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1909
1910The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
Dan Handley4def07d2018-03-01 18:44:00 +00001911boot Linux with 8 CPUs using the AArch64 build of TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01001912
Paul Beesley29c02522019-03-13 15:11:04 +00001913.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001914
1915 <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
1916 -C pctl.startup=0.0.0.0 \
1917 -C bp.secure_memory=1 \
1918 -C bp.tzc_400.diagnostics=1 \
1919 -C cache_state_modelled=1 \
1920 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
1921 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
Douglas Raillard6f625742017-06-28 15:23:03 +01001922 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01001923 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillard6f625742017-06-28 15:23:03 +01001924
1925Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint
1926~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1927
1928The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
Dan Handley4def07d2018-03-01 18:44:00 +00001929boot Linux with 4 CPUs using the AArch32 build of TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01001930
Paul Beesley29c02522019-03-13 15:11:04 +00001931.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001932
1933 <path-to>/FVP_Base_Cortex-A32x4 \
1934 -C pctl.startup=0.0.0.0 \
1935 -C bp.secure_memory=1 \
1936 -C bp.tzc_400.diagnostics=1 \
1937 -C cache_state_modelled=1 \
1938 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
1939 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
Douglas Raillard6f625742017-06-28 15:23:03 +01001940 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01001941 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillard6f625742017-06-28 15:23:03 +01001942
1943Running on the AEMv8 Base FVP with reset to BL31 entrypoint
1944~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1945
David Cunado855ac022018-03-12 18:47:05 +00001946The following ``FVP_Base_RevC-2xAEMv8A`` parameters should be used to boot Linux
Dan Handley4def07d2018-03-01 18:44:00 +00001947with 8 CPUs using the AArch64 build of TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01001948
Paul Beesley29c02522019-03-13 15:11:04 +00001949.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01001950
David Cunado855ac022018-03-12 18:47:05 +00001951 <path-to>/FVP_Base_RevC-2xAEMv8A \
Douglas Raillard6f625742017-06-28 15:23:03 +01001952 -C pctl.startup=0.0.0.0 \
1953 -C bp.secure_memory=1 \
1954 -C bp.tzc_400.diagnostics=1 \
1955 -C cluster0.NUM_CORES=4 \
1956 -C cluster1.NUM_CORES=4 \
1957 -C cache_state_modelled=1 \
Soby Mathew8aa4e5f2018-12-12 14:54:23 +00001958 -C cluster0.cpu0.RVBAR=0x04010000 \
1959 -C cluster0.cpu1.RVBAR=0x04010000 \
1960 -C cluster0.cpu2.RVBAR=0x04010000 \
1961 -C cluster0.cpu3.RVBAR=0x04010000 \
1962 -C cluster1.cpu0.RVBAR=0x04010000 \
1963 -C cluster1.cpu1.RVBAR=0x04010000 \
1964 -C cluster1.cpu2.RVBAR=0x04010000 \
1965 -C cluster1.cpu3.RVBAR=0x04010000 \
1966 --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04010000 \
1967 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0xff000000 \
Douglas Raillard6f625742017-06-28 15:23:03 +01001968 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01001969 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillard6f625742017-06-28 15:23:03 +01001970 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01001971 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillard6f625742017-06-28 15:23:03 +01001972
1973Notes:
1974
Ambroise Vincent68126052019-03-14 10:53:16 +00001975- If Position Independent Executable (PIE) support is enabled for BL31
Soby Mathew8aa4e5f2018-12-12 14:54:23 +00001976 in this config, it can be loaded at any valid address for execution.
1977
Douglas Raillard6f625742017-06-28 15:23:03 +01001978- Since a FIP is not loaded when using BL31 as reset entrypoint, the
1979 ``--data="<path-to><bl31|bl32|bl33-binary>"@<base-address-of-binary>``
1980 parameter is needed to load the individual bootloader images in memory.
1981 BL32 image is only needed if BL31 has been built to expect a Secure-EL1
Soby Mathew7e8686d2018-05-09 13:59:29 +01001982 Payload. For the same reason, the FDT needs to be compiled from the DT source
1983 and loaded via the ``--data cluster0.cpu0="<path-to>/<fdt>"@0x82000000``
1984 parameter.
Douglas Raillard6f625742017-06-28 15:23:03 +01001985
Ambroise Vincent68126052019-03-14 10:53:16 +00001986- The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a
1987 specific DTS for all the CPUs to be loaded.
1988
Douglas Raillard6f625742017-06-28 15:23:03 +01001989- The ``-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>`` parameter, where
1990 X and Y are the cluster and CPU numbers respectively, is used to set the
1991 reset vector for each core.
1992
1993- Changing the default value of ``ARM_TSP_RAM_LOCATION`` will also require
1994 changing the value of
1995 ``--data="<path-to><bl32-binary>"@<base-address-of-bl32>`` to the new value of
1996 ``BL32_BASE``.
1997
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01001998Running on the AEMv8 Base FVP (AArch32) with reset to SP_MIN entrypoint
1999~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillard6f625742017-06-28 15:23:03 +01002000
2001The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
Dan Handley4def07d2018-03-01 18:44:00 +00002002with 8 CPUs using the AArch32 build of TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01002003
Paul Beesley29c02522019-03-13 15:11:04 +00002004.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01002005
2006 <path-to>/FVP_Base_AEMv8A-AEMv8A \
2007 -C pctl.startup=0.0.0.0 \
2008 -C bp.secure_memory=1 \
2009 -C bp.tzc_400.diagnostics=1 \
2010 -C cluster0.NUM_CORES=4 \
2011 -C cluster1.NUM_CORES=4 \
2012 -C cache_state_modelled=1 \
2013 -C cluster0.cpu0.CONFIG64=0 \
2014 -C cluster0.cpu1.CONFIG64=0 \
2015 -C cluster0.cpu2.CONFIG64=0 \
2016 -C cluster0.cpu3.CONFIG64=0 \
2017 -C cluster1.cpu0.CONFIG64=0 \
2018 -C cluster1.cpu1.CONFIG64=0 \
2019 -C cluster1.cpu2.CONFIG64=0 \
2020 -C cluster1.cpu3.CONFIG64=0 \
Soby Mathew8aa4e5f2018-12-12 14:54:23 +00002021 -C cluster0.cpu0.RVBAR=0x04002000 \
2022 -C cluster0.cpu1.RVBAR=0x04002000 \
2023 -C cluster0.cpu2.RVBAR=0x04002000 \
2024 -C cluster0.cpu3.RVBAR=0x04002000 \
2025 -C cluster1.cpu0.RVBAR=0x04002000 \
2026 -C cluster1.cpu1.RVBAR=0x04002000 \
2027 -C cluster1.cpu2.RVBAR=0x04002000 \
2028 -C cluster1.cpu3.RVBAR=0x04002000 \
Soby Mathewc099cd32018-06-01 16:53:38 +01002029 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04002000 \
Douglas Raillard6f625742017-06-28 15:23:03 +01002030 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01002031 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillard6f625742017-06-28 15:23:03 +01002032 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01002033 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillard6f625742017-06-28 15:23:03 +01002034
Paul Beesleye1c50262019-03-13 16:20:44 +00002035.. note::
2036 The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``.
2037 It should match the address programmed into the RVBAR register as well.
Douglas Raillard6f625742017-06-28 15:23:03 +01002038
2039Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
2040~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2041
2042The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
Dan Handley4def07d2018-03-01 18:44:00 +00002043boot Linux with 8 CPUs using the AArch64 build of TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01002044
Paul Beesley29c02522019-03-13 15:11:04 +00002045.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01002046
2047 <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
2048 -C pctl.startup=0.0.0.0 \
2049 -C bp.secure_memory=1 \
2050 -C bp.tzc_400.diagnostics=1 \
2051 -C cache_state_modelled=1 \
Soby Mathew8aa4e5f2018-12-12 14:54:23 +00002052 -C cluster0.cpu0.RVBARADDR=0x04010000 \
2053 -C cluster0.cpu1.RVBARADDR=0x04010000 \
2054 -C cluster0.cpu2.RVBARADDR=0x04010000 \
2055 -C cluster0.cpu3.RVBARADDR=0x04010000 \
2056 -C cluster1.cpu0.RVBARADDR=0x04010000 \
2057 -C cluster1.cpu1.RVBARADDR=0x04010000 \
2058 -C cluster1.cpu2.RVBARADDR=0x04010000 \
2059 -C cluster1.cpu3.RVBARADDR=0x04010000 \
2060 --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04010000 \
2061 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0xff000000 \
Douglas Raillard6f625742017-06-28 15:23:03 +01002062 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01002063 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillard6f625742017-06-28 15:23:03 +01002064 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01002065 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillard6f625742017-06-28 15:23:03 +01002066
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +01002067Running on the Cortex-A32 Base FVP (AArch32) with reset to SP_MIN entrypoint
2068~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillard6f625742017-06-28 15:23:03 +01002069
2070The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
Dan Handley4def07d2018-03-01 18:44:00 +00002071boot Linux with 4 CPUs using the AArch32 build of TF-A.
Douglas Raillard6f625742017-06-28 15:23:03 +01002072
Paul Beesley29c02522019-03-13 15:11:04 +00002073.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01002074
2075 <path-to>/FVP_Base_Cortex-A32x4 \
2076 -C pctl.startup=0.0.0.0 \
2077 -C bp.secure_memory=1 \
2078 -C bp.tzc_400.diagnostics=1 \
2079 -C cache_state_modelled=1 \
Soby Mathew8aa4e5f2018-12-12 14:54:23 +00002080 -C cluster0.cpu0.RVBARADDR=0x04002000 \
2081 -C cluster0.cpu1.RVBARADDR=0x04002000 \
2082 -C cluster0.cpu2.RVBARADDR=0x04002000 \
2083 -C cluster0.cpu3.RVBARADDR=0x04002000 \
Soby Mathewc099cd32018-06-01 16:53:38 +01002084 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04002000 \
Douglas Raillard6f625742017-06-28 15:23:03 +01002085 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01002086 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillard6f625742017-06-28 15:23:03 +01002087 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01002088 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillard6f625742017-06-28 15:23:03 +01002089
2090Running the software on Juno
2091----------------------------
2092
Dan Handley4def07d2018-03-01 18:44:00 +00002093This version of TF-A has been tested on variants r0, r1 and r2 of Juno.
Douglas Raillard6f625742017-06-28 15:23:03 +01002094
2095To execute the software stack on Juno, the version of the Juno board recovery
2096image indicated in the `Linaro Release Notes`_ must be installed. If you have an
2097earlier version installed or are unsure which version is installed, please
2098re-install the recovery image by following the
2099`Instructions for using Linaro's deliverables on Juno`_.
2100
Dan Handley4def07d2018-03-01 18:44:00 +00002101Preparing TF-A images
2102~~~~~~~~~~~~~~~~~~~~~
Douglas Raillard6f625742017-06-28 15:23:03 +01002103
Dan Handley4def07d2018-03-01 18:44:00 +00002104After building TF-A, the files ``bl1.bin`` and ``fip.bin`` need copying to the
2105``SOFTWARE/`` directory of the Juno SD card.
Douglas Raillard6f625742017-06-28 15:23:03 +01002106
2107Other Juno software information
2108~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2109
Dan Handley4def07d2018-03-01 18:44:00 +00002110Please visit the `Arm Platforms Portal`_ to get support and obtain any other Juno
Douglas Raillard6f625742017-06-28 15:23:03 +01002111software information. Please also refer to the `Juno Getting Started Guide`_ to
Dan Handley4def07d2018-03-01 18:44:00 +00002112get more detailed information about the Juno Arm development platform and how to
Douglas Raillard6f625742017-06-28 15:23:03 +01002113configure it.
2114
2115Testing SYSTEM SUSPEND on Juno
2116~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2117
2118The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend
2119to RAM. For more details refer to section 5.16 of `PSCI`_. To test system suspend
2120on Juno, at the linux shell prompt, issue the following command:
2121
Paul Beesley29c02522019-03-13 15:11:04 +00002122.. code:: shell
Douglas Raillard6f625742017-06-28 15:23:03 +01002123
2124 echo +10 > /sys/class/rtc/rtc0/wakealarm
2125 echo -n mem > /sys/power/state
2126
2127The Juno board should suspend to RAM and then wakeup after 10 seconds due to
2128wakeup interrupt from RTC.
2129
2130--------------
2131
Antonio Nino Diaz07090552019-01-30 16:01:49 +00002132*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
Douglas Raillard6f625742017-06-28 15:23:03 +01002133
Louis Mayencourt0042f572019-03-08 15:35:40 +00002134.. _arm Developer page: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
David Cunado31f2f792017-06-29 12:01:33 +01002135.. _Linaro: `Linaro Release Notes`_
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01002136.. _Linaro Release: `Linaro Release Notes`_
Paul Beesleydd4e9a72019-02-08 16:43:05 +00002137.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
2138.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables
David Cunadofa05efb2017-12-19 16:33:25 +00002139.. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/w/docs/303/juno
Dan Handley4def07d2018-03-01 18:44:00 +00002140.. _Arm Platforms Portal: https://community.arm.com/dev-platforms/
Paul Beesleydd4e9a72019-02-08 16:43:05 +00002141.. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio
Louis Mayencourt63fdda22019-03-22 11:47:22 +00002142.. _arm-trusted-firmware-a project page: https://review.trustedfirmware.org/admin/projects/TF-A/trusted-firmware-a
Paul Beesley93fbc712019-01-21 12:06:24 +00002143.. _`Linux Coding Style`: https://www.kernel.org/doc/html/latest/process/coding-style.html
Sandrine Bailleux52f6db9e2018-09-20 10:27:13 +02002144.. _Linux master tree: https://github.com/torvalds/linux/tree/master/
Antonio Nino Diaz6feb9e82017-05-23 11:49:22 +01002145.. _Dia: https://wiki.gnome.org/Apps/Dia/Download
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01002146.. _here: psci-lib-integration-guide.rst
Douglas Raillard6f625742017-06-28 15:23:03 +01002147.. _Trusted Board Boot: trusted-board-boot.rst
Soby Mathew7e8686d2018-05-09 13:59:29 +01002148.. _TB_FW_CONFIG for FVP: ../plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts
Douglas Raillard6f625742017-06-28 15:23:03 +01002149.. _Secure-EL1 Payloads and Dispatchers: firmware-design.rst#user-content-secure-el1-payloads-and-dispatchers
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01002150.. _Firmware Update: firmware-update.rst
2151.. _Firmware Design: firmware-design.rst
Douglas Raillard6f625742017-06-28 15:23:03 +01002152.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
2153.. _mbed TLS Security Center: https://tls.mbed.org/security
Dan Handley4def07d2018-03-01 18:44:00 +00002154.. _Arm's website: `FVP models`_
Eleanor Bonniciec4a2bb2017-07-07 14:33:24 +01002155.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
Douglas Raillard6f625742017-06-28 15:23:03 +01002156.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
David Cunado31f2f792017-06-29 12:01:33 +01002157.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
Sandrine Bailleux1843a192018-09-20 12:44:39 +02002158.. _Secure Partition Manager Design guide: secure-partition-manager-design.rst
Paul Beesley93fbc712019-01-21 12:06:24 +00002159.. _`Trusted Firmware-A Coding Guidelines`: coding-guidelines.rst
Louis Mayencourt63fdda22019-03-22 11:47:22 +00002160.. _`Library at ROM`: romlib-design.rst