blob: 28483f2b1f8a0bbbe3192e47a9dc4c0cbca9eab9 [file] [log] [blame]
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001ARM Trusted Firmware User Guide
2===============================
3
4
5.. section-numbering::
6 :suffix: .
7
8.. contents::
9
10This document describes how to build ARM Trusted Firmware (TF) and run it with a
11tested set of other software components using defined configurations on the Juno
12ARM development platform and ARM Fixed Virtual Platform (FVP) models. It is
13possible to use other software components, configurations and platforms but that
14is outside the scope of this document.
15
16This document assumes that the reader has previous experience running a fully
17bootable Linux software stack on Juno or FVP using the prebuilt binaries and
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +010018filesystems provided by `Linaro`_. Further information may be found in the
19`Linaro instructions`_. It also assumes that the user understands the role of
20the different software components required to boot a Linux system:
Douglas Raillardd7c21b72017-06-28 15:23:03 +010021
22- Specific firmware images required by the platform (e.g. SCP firmware on Juno)
23- Normal world bootloader (e.g. UEFI or U-Boot)
24- Device tree
25- Linux kernel image
26- Root filesystem
27
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +010028This document also assumes that the user is familiar with the `FVP models`_ and
Douglas Raillardd7c21b72017-06-28 15:23:03 +010029the different command line options available to launch the model.
30
31This document should be used in conjunction with the `Firmware Design`_.
32
33Host machine requirements
34-------------------------
35
36The minimum recommended machine specification for building the software and
37running the FVP models is a dual-core processor running at 2GHz with 12GB of
38RAM. For best performance, use a machine with a quad-core processor running at
392.6GHz with 16GB of RAM.
40
41The software has been tested on Ubuntu 14.04 LTS (64-bit). Packages used for
42building the software were installed from that distribution unless otherwise
43specified.
44
45The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE,
David Cunadob2de0992017-06-29 12:01:33 +010046Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010047
48Tools
49-----
50
51Install the required packages to build Trusted Firmware with the following
52command:
53
54::
55
56 sudo apt-get install build-essential gcc make git libssl-dev
57
David Cunadob2de0992017-06-29 12:01:33 +010058ARM TF has been tested with `Linaro Release 17.04`_.
59
Douglas Raillardd7c21b72017-06-28 15:23:03 +010060Download and install the AArch32 or AArch64 little-endian GCC cross compiler.
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +010061The `Linaro Release Notes`_ documents which version of the compiler to use for a
62given Linaro Release. Also, these `Linaro instructions`_ provide further
63guidance and a script, which can be used to download Linaro deliverables
64automatically.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010065
66Optionally, Trusted Firmware can be built using clang or ARM Compiler 6.
67See instructions below on how to switch the default compiler.
68
69In addition, the following optional packages and tools may be needed:
70
71- ``device-tree-compiler`` package if you need to rebuild the Flattened Device
72 Tree (FDT) source files (``.dts`` files) provided with this software.
73
74- For debugging, ARM `Development Studio 5 (DS-5)`_.
75
Antonio Nino Diazb5d68092017-05-23 11:49:22 +010076- To create and modify the diagram files included in the documentation, `Dia`_.
77 This tool can be found in most Linux distributions. Inkscape is needed to
78 generate the actual *.png files.
79
Douglas Raillardd7c21b72017-06-28 15:23:03 +010080Getting the Trusted Firmware source code
81----------------------------------------
82
83Download the Trusted Firmware source code from Github:
84
85::
86
87 git clone https://github.com/ARM-software/arm-trusted-firmware.git
88
89Building the Trusted Firmware
90-----------------------------
91
92- Before building Trusted Firmware, the environment variable ``CROSS_COMPILE``
93 must point to the Linaro cross compiler.
94
95 For AArch64:
96
97 ::
98
99 export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
100
101 For AArch32:
102
103 ::
104
105 export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
106
107 It is possible to build Trusted Firmware using clang or ARM Compiler 6.
108 To do so ``CC`` needs to point to the clang or armclang binary. Only the
109 compiler is switched; the assembler and linker need to be provided by
110 the GNU toolchain, thus ``CROSS_COMPILE`` should be set as described above.
111
112 ARM Compiler 6 will be selected when the base name of the path assigned
113 to ``CC`` matches the string 'armclang'.
114
115 For AArch64 using ARM Compiler 6:
116
117 ::
118
119 export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
120 make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all
121
122 Clang will be selected when the base name of the path assigned to ``CC``
123 contains the string 'clang'. This is to allow both clang and clang-X.Y
124 to work.
125
126 For AArch64 using clang:
127
128 ::
129
130 export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
131 make CC=<path-to-clang>/bin/clang PLAT=<platform> all
132
133- Change to the root directory of the Trusted Firmware source tree and build.
134
135 For AArch64:
136
137 ::
138
139 make PLAT=<platform> all
140
141 For AArch32:
142
143 ::
144
145 make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all
146
147 Notes:
148
149 - If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the
150 `Summary of build options`_ for more information on available build
151 options.
152
153 - (AArch32 only) Currently only ``PLAT=fvp`` is supported.
154
155 - (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it
156 corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp\_min, is
157 provided by ARM Trusted Firmware to demonstrate how PSCI Library can
158 be integrated with an AArch32 EL3 Runtime Software. Some AArch32 EL3
159 Runtime Software may include other runtime services, for example
160 Trusted OS services. A guide to integrate PSCI library with AArch32
161 EL3 Runtime Software can be found `here`_.
162
163 - (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
164 image, is not compiled in by default. Refer to the
165 `Building the Test Secure Payload`_ section below.
166
167 - By default this produces a release version of the build. To produce a
168 debug version instead, refer to the "Debugging options" section below.
169
170 - The build process creates products in a ``build`` directory tree, building
171 the objects and binaries for each boot loader stage in separate
172 sub-directories. The following boot loader binary files are created
173 from the corresponding ELF files:
174
175 - ``build/<platform>/<build-type>/bl1.bin``
176 - ``build/<platform>/<build-type>/bl2.bin``
177 - ``build/<platform>/<build-type>/bl31.bin`` (AArch64 only)
178 - ``build/<platform>/<build-type>/bl32.bin`` (mandatory for AArch32)
179
180 where ``<platform>`` is the name of the chosen platform and ``<build-type>``
181 is either ``debug`` or ``release``. The actual number of images might differ
182 depending on the platform.
183
184- Build products for a specific build variant can be removed using:
185
186 ::
187
188 make DEBUG=<D> PLAT=<platform> clean
189
190 ... where ``<D>`` is ``0`` or ``1``, as specified when building.
191
192 The build tree can be removed completely using:
193
194 ::
195
196 make realclean
197
198Summary of build options
199~~~~~~~~~~~~~~~~~~~~~~~~
200
201ARM Trusted Firmware build system supports the following build options. Unless
202mentioned otherwise, these options are expected to be specified at the build
203command line and are not to be modified in any component makefiles. Note that
204the build system doesn't track dependency for build options. Therefore, if any
205of the build options are changed from a previous build, a clean build must be
206performed.
207
208Common build options
209^^^^^^^^^^^^^^^^^^^^
210
211- ``AARCH32_SP`` : Choose the AArch32 Secure Payload component to be built as
212 as the BL32 image when ``ARCH=aarch32``. The value should be the path to the
213 directory containing the SP source, relative to the ``bl32/``; the directory
214 is expected to contain a makefile called ``<aarch32_sp-value>.mk``.
215
216- ``ARCH`` : Choose the target build architecture for ARM Trusted Firmware.
217 It can take either ``aarch64`` or ``aarch32`` as values. By default, it is
218 defined to ``aarch64``.
219
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100220- ``ARM_ARCH_MAJOR``: The major version of ARM Architecture to target when
221 compiling ARM Trusted Firmware. Its value must be numeric, and defaults to
222 8 . See also, *ARMv8 Architecture Extensions* in `Firmware Design`_.
223
224- ``ARM_ARCH_MINOR``: The minor version of ARM Architecture to target when
225 compiling ARM Trusted Firmware. Its value must be a numeric, and defaults
226 to 0. See also, *ARMv8 Architecture Extensions* in `Firmware Design`_.
227
228- ``ARM_GIC_ARCH``: Choice of ARM GIC architecture version used by the ARM
229 Legacy GIC driver for implementing the platform GIC API. This API is used
230 by the interrupt management framework. Default is 2 (that is, version 2.0).
231 This build option is deprecated.
232
233- ``ARM_PLAT_MT``: This flag determines whether the ARM platform layer has to
Jeenu Viswambharan528d21b2016-11-15 13:53:57 +0000234 cater for the multi-threading ``MT`` bit when accessing MPIDR. When this flag
235 is set, the functions which deal with MPIDR assume that the ``MT`` bit in
236 MPIDR is set and access the bit-fields in MPIDR accordingly. Default value of
237 this flag is 0. Note that this option is not used on FVP platforms.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100238
239- ``BL2``: This is an optional build option which specifies the path to BL2
240 image for the ``fip`` target. In this case, the BL2 in the ARM Trusted
241 Firmware will not be built.
242
243- ``BL2U``: This is an optional build option which specifies the path to
244 BL2U image. In this case, the BL2U in the ARM Trusted Firmware will not
245 be built.
246
247- ``BL31``: This is an optional build option which specifies the path to
248 BL31 image for the ``fip`` target. In this case, the BL31 in the ARM
249 Trusted Firmware will not be built.
250
251- ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
252 file that contains the BL31 private key in PEM format. If ``SAVE_KEYS=1``,
253 this file name will be used to save the key.
254
255- ``BL32``: This is an optional build option which specifies the path to
256 BL32 image for the ``fip`` target. In this case, the BL32 in the ARM
257 Trusted Firmware will not be built.
258
Summer Qin80726782017-04-20 16:28:39 +0100259- ``BL32_EXTRA1``: This is an optional build option which specifies the path to
260 Trusted OS Extra1 image for the ``fip`` target.
261
262- ``BL32_EXTRA2``: This is an optional build option which specifies the path to
263 Trusted OS Extra2 image for the ``fip`` target.
264
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100265- ``BL32_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
266 file that contains the BL32 private key in PEM format. If ``SAVE_KEYS=1``,
267 this file name will be used to save the key.
268
269- ``BL33``: Path to BL33 image in the host file system. This is mandatory for
270 ``fip`` target in case the BL2 from ARM Trusted Firmware is used.
271
272- ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
273 file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``,
274 this file name will be used to save the key.
275
276- ``BUILD_MESSAGE_TIMESTAMP``: String used to identify the time and date of the
277 compilation of each build. It must be set to a C string (including quotes
278 where applicable). Defaults to a string that contains the time and date of
279 the compilation.
280
281- ``BUILD_STRING``: Input string for VERSION\_STRING, which allows the TF build
282 to be uniquely identified. Defaults to the current git commit id.
283
284- ``CFLAGS``: Extra user options appended on the compiler's command line in
285 addition to the options set by the build system.
286
287- ``COLD_BOOT_SINGLE_CPU``: This option indicates whether the platform may
288 release several CPUs out of reset. It can take either 0 (several CPUs may be
289 brought up) or 1 (only one CPU will ever be brought up during cold reset).
290 Default is 0. If the platform always brings up a single CPU, there is no
291 need to distinguish between primary and secondary CPUs and the boot path can
292 be optimised. The ``plat_is_my_cpu_primary()`` and
293 ``plat_secondary_cold_boot_setup()`` platform porting interfaces do not need
294 to be implemented in this case.
295
296- ``CRASH_REPORTING``: A non-zero value enables a console dump of processor
297 register state when an unexpected exception occurs during execution of
298 BL31. This option defaults to the value of ``DEBUG`` - i.e. by default
299 this is only enabled for a debug build of the firmware.
300
301- ``CREATE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
302 certificate generation tool to create new keys in case no valid keys are
303 present or specified. Allowed options are '0' or '1'. Default is '1'.
304
305- ``CTX_INCLUDE_AARCH32_REGS`` : Boolean option that, when set to 1, will cause
306 the AArch32 system registers to be included when saving and restoring the
307 CPU context. The option must be set to 0 for AArch64-only platforms (that
308 is on hardware that does not implement AArch32, or at least not at EL1 and
309 higher ELs). Default value is 1.
310
311- ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP
312 registers to be included when saving and restoring the CPU context. Default
313 is 0.
314
315- ``DEBUG``: Chooses between a debug and release build. It can take either 0
316 (release) or 1 (debug) as values. 0 is the default.
317
318- ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of
319 the normal boot flow. It must specify the entry point address of the EL3
320 payload. Please refer to the "Booting an EL3 payload" section for more
321 details.
322
323- ``ENABLE_ASSERTIONS``: This option controls whether or not calls to ``assert()``
324 are compiled out. For debug builds, this option defaults to 1, and calls to
325 ``assert()`` are left in place. For release builds, this option defaults to 0
326 and calls to ``assert()`` function are compiled out. This option can be set
327 independently of ``DEBUG``. It can also be used to hide any auxiliary code
328 that is only required for the assertion and does not fit in the assertion
329 itself.
330
331- ``ENABLE_PMF``: Boolean option to enable support for optional Performance
332 Measurement Framework(PMF). Default is 0.
333
334- ``ENABLE_PSCI_STAT``: Boolean option to enable support for optional PSCI
335 functions ``PSCI_STAT_RESIDENCY`` and ``PSCI_STAT_COUNT``. Default is 0.
336 In the absence of an alternate stat collection backend, ``ENABLE_PMF`` must
337 be enabled. If ``ENABLE_PMF`` is set, the residency statistics are tracked in
338 software.
339
340- ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime
341 instrumentation which injects timestamp collection points into
342 Trusted Firmware to allow runtime performance to be measured.
343 Currently, only PSCI is instrumented. Enabling this option enables
344 the ``ENABLE_PMF`` build option as well. Default is 0.
345
Jeenu Viswambharand73dcf32017-07-19 13:52:12 +0100346- ``ENABLE_SPE_FOR_LOWER_ELS`` : Boolean option to enable Statistical Profiling
347 extensions. This is an optional architectural feature available only for
348 AArch64 8.2 onwards. This option defaults to 1 but is automatically
349 disabled when the target architecture is AArch32 or AArch64 8.0/8.1.
350
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100351- ``ENABLE_STACK_PROTECTOR``: String option to enable the stack protection
352 checks in GCC. Allowed values are "all", "strong" and "0" (default).
353 "strong" is the recommended stack protection level if this feature is
354 desired. 0 disables the stack protection. For all values other than 0, the
355 ``plat_get_stack_protector_canary()`` platform hook needs to be implemented.
356 The value is passed as the last component of the option
357 ``-fstack-protector-$ENABLE_STACK_PROTECTOR``.
358
359- ``ERROR_DEPRECATED``: This option decides whether to treat the usage of
360 deprecated platform APIs, helper functions or drivers within Trusted
361 Firmware as error. It can take the value 1 (flag the use of deprecated
362 APIs as error) or 0. The default is 0.
363
364- ``FIP_NAME``: This is an optional build option which specifies the FIP
365 filename for the ``fip`` target. Default is ``fip.bin``.
366
367- ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU
368 FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``.
369
370- ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create``
371 tool to create certificates as per the Chain of Trust described in
372 `Trusted Board Boot`_. The build system then calls ``fiptool`` to
373 include the certificates in the FIP and FWU\_FIP. Default value is '0'.
374
375 Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support
376 for the Trusted Board Boot feature in the BL1 and BL2 images, to generate
377 the corresponding certificates, and to include those certificates in the
378 FIP and FWU\_FIP.
379
380 Note that if ``TRUSTED_BOARD_BOOT=0`` and ``GENERATE_COT=1``, the BL1 and BL2
381 images will not include support for Trusted Board Boot. The FIP will still
382 include the corresponding certificates. This FIP can be used to verify the
383 Chain of Trust on the host machine through other mechanisms.
384
385 Note that if ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=0``, the BL1 and BL2
386 images will include support for Trusted Board Boot, but the FIP and FWU\_FIP
387 will not include the corresponding certificates, causing a boot failure.
388
Jeenu Viswambharanc06f05c2017-09-22 08:32:09 +0100389- ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have
390 inherent support for specific EL3 type interrupts. Setting this build option
391 to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both
392 by `platform abstraction layer`__ and `Interrupt Management Framework`__.
393 This allows GICv2 platforms to enable features requiring EL3 interrupt type.
394 This also means that all GICv2 Group 0 interrupts are delivered to EL3, and
395 the Secure Payload interrupts needs to be synchronously handed over to Secure
396 EL1 for handling. The default value of this option is ``0``, which means the
397 Group 0 interrupts are assumed to be handled by Secure EL1.
398
399 .. __: `platform-interrupt-controller-API.rst`
400 .. __: `interrupt-framework-design.rst`
401
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100402- ``HANDLE_EA_EL3_FIRST``: When defined External Aborts and SError Interrupts
403 will be always trapped in EL3 i.e. in BL31 at runtime.
404
405- ``HW_ASSISTED_COHERENCY``: On most ARM systems to-date, platform-specific
406 software operations are required for CPUs to enter and exit coherency.
407 However, there exists newer systems where CPUs' entry to and exit from
408 coherency is managed in hardware. Such systems require software to only
409 initiate the operations, and the rest is managed in hardware, minimizing
410 active software management. In such systems, this boolean option enables ARM
411 Trusted Firmware to carry out build and run-time optimizations during boot
412 and power management operations. This option defaults to 0 and if it is
413 enabled, then it implies ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled.
414
415- ``JUNO_AARCH32_EL3_RUNTIME``: This build flag enables you to execute EL3
416 runtime software in AArch32 mode, which is required to run AArch32 on Juno.
417 By default this flag is set to '0'. Enabling this flag builds BL1 and BL2 in
418 AArch64 and facilitates the loading of ``SP_MIN`` and BL33 as AArch32 executable
419 images.
420
Soby Mathew13b16052017-08-31 11:49:32 +0100421- ``KEY_ALG``: This build flag enables the user to select the algorithm to be
422 used for generating the PKCS keys and subsequent signing of the certificate.
Soby Mathew2fd70f62017-08-31 11:50:29 +0100423 It accepts 3 values viz ``rsa``, ``rsa_1_5``, ``ecdsa``. The ``rsa_1_5`` is
424 the legacy PKCS#1 RSA 1.5 algorithm which is not TBBR compliant and is
425 retained only for compatibility. The default value of this flag is ``rsa``
426 which is the TBBR compliant PKCS#1 RSA 2.1 scheme.
Soby Mathew13b16052017-08-31 11:49:32 +0100427
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100428- ``LDFLAGS``: Extra user options appended to the linkers' command line in
429 addition to the one set by the build system.
430
431- ``LOAD_IMAGE_V2``: Boolean option to enable support for new version (v2) of
432 image loading, which provides more flexibility and scalability around what
433 images are loaded and executed during boot. Default is 0.
434 Note: ``TRUSTED_BOARD_BOOT`` is currently only supported for AArch64 when
435 ``LOAD_IMAGE_V2`` is enabled.
436
437- ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log
438 output compiled into the build. This should be one of the following:
439
440 ::
441
442 0 (LOG_LEVEL_NONE)
443 10 (LOG_LEVEL_NOTICE)
444 20 (LOG_LEVEL_ERROR)
445 30 (LOG_LEVEL_WARNING)
446 40 (LOG_LEVEL_INFO)
447 50 (LOG_LEVEL_VERBOSE)
448
449 All log output up to and including the log level is compiled into the build.
450 The default value is 40 in debug builds and 20 in release builds.
451
452- ``NON_TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
453 specifies the file that contains the Non-Trusted World private key in PEM
454 format. If ``SAVE_KEYS=1``, this file name will be used to save the key.
455
456- ``NS_BL2U``: Path to NS\_BL2U image in the host file system. This image is
457 optional. It is only needed if the platform makefile specifies that it
458 is required in order to build the ``fwu_fip`` target.
459
460- ``NS_TIMER_SWITCH``: Enable save and restore for non-secure timer register
461 contents upon world switch. It can take either 0 (don't save and restore) or
462 1 (do save and restore). 0 is the default. An SPD may set this to 1 if it
463 wants the timer registers to be saved and restored.
464
465- ``PL011_GENERIC_UART``: Boolean option to indicate the PL011 driver that
466 the underlying hardware is not a full PL011 UART but a minimally compliant
467 generic UART, which is a subset of the PL011. The driver will not access
468 any register that is not part of the SBSA generic UART specification.
469 Default value is 0 (a full PL011 compliant UART is present).
470
471- ``PLAT``: Choose a platform to build ARM Trusted Firmware for. The chosen
472 platform name must be subdirectory of any depth under ``plat/``, and must
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +0100473 contain a platform makefile named ``platform.mk``. For example to build ARM
474 Trusted Firmware for ARM Juno board select PLAT=juno.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100475
476- ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image
477 instead of the normal boot flow. When defined, it must specify the entry
478 point address for the preloaded BL33 image. This option is incompatible with
479 ``EL3_PAYLOAD_BASE``. If both are defined, ``EL3_PAYLOAD_BASE`` has priority
480 over ``PRELOADED_BL33_BASE``.
481
482- ``PROGRAMMABLE_RESET_ADDRESS``: This option indicates whether the reset
483 vector address can be programmed or is fixed on the platform. It can take
484 either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a
485 programmable reset address, it is expected that a CPU will start executing
486 code directly at the right address, both on a cold and warm reset. In this
487 case, there is no need to identify the entrypoint on boot and the boot path
488 can be optimised. The ``plat_get_my_entrypoint()`` platform porting interface
489 does not need to be implemented in this case.
490
491- ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats
492 possible for the PSCI power-state parameter viz original and extended
493 State-ID formats. This flag if set to 1, configures the generic PSCI layer
494 to use the extended format. The default value of this flag is 0, which
495 means by default the original power-state format is used by the PSCI
496 implementation. This flag should be specified by the platform makefile
497 and it governs the return value of PSCI\_FEATURES API for CPU\_SUSPEND
498 smc function id. When this option is enabled on ARM platforms, the
499 option ``ARM_RECOM_STATE_ID_ENC`` needs to be set to 1 as well.
500
501- ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead
502 of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
503 entrypoint) or 1 (CPU reset to BL31 entrypoint).
504 The default value is 0.
505
506- ``RESET_TO_SP_MIN``: SP\_MIN is the minimal AArch32 Secure Payload provided in
507 ARM Trusted Firmware. This flag configures SP\_MIN entrypoint as the CPU
508 reset vector instead of the BL1 entrypoint. It can take the value 0 (CPU
509 reset to BL1 entrypoint) or 1 (CPU reset to SP\_MIN entrypoint). The default
510 value is 0.
511
512- ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
513 file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this
514 file name will be used to save the key.
515
516- ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
517 certificate generation tool to save the keys used to establish the Chain of
518 Trust. Allowed options are '0' or '1'. Default is '0' (do not save).
519
520- ``SCP_BL2``: Path to SCP\_BL2 image in the host file system. This image is optional.
521 If a SCP\_BL2 image is present then this option must be passed for the ``fip``
522 target.
523
524- ``SCP_BL2_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
525 file that contains the SCP\_BL2 private key in PEM format. If ``SAVE_KEYS=1``,
526 this file name will be used to save the key.
527
528- ``SCP_BL2U``: Path to SCP\_BL2U image in the host file system. This image is
529 optional. It is only needed if the platform makefile specifies that it
530 is required in order to build the ``fwu_fip`` target.
531
532- ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be
533 isolated on separate memory pages. This is a trade-off between security and
534 memory usage. See "Isolating code and read-only data on separate memory
535 pages" section in `Firmware Design`_. This flag is disabled by default and
536 affects all BL images.
537
538- ``SPD``: Choose a Secure Payload Dispatcher component to be built into the
539 Trusted Firmware. This build option is only valid if ``ARCH=aarch64``. The
540 value should be the path to the directory containing the SPD source,
541 relative to ``services/spd/``; the directory is expected to
542 contain a makefile called ``<spd-value>.mk``.
543
544- ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can
545 take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops
546 execution in BL1 just before handing over to BL31. At this point, all
547 firmware images have been loaded in memory, and the MMU and caches are
548 turned off. Refer to the "Debugging options" section for more details.
549
Etienne Carrieredc0fea72017-08-09 15:48:53 +0200550- ``SP_MIN_WITH_SECURE_FIQ``: Boolean flag to indicate the SP_MIN handles
551 secure interrupts (caught through the FIQ line). Platforms can enable
552 this directive if they need to handle such interruption. When enabled,
553 the FIQ are handled in monitor mode and non secure world is not allowed
554 to mask these events. Platforms that enable FIQ handling in SP_MIN shall
555 implement the api ``sp_min_plat_fiq_handler()``. The default value is 0.
556
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100557- ``TRUSTED_BOARD_BOOT``: Boolean flag to include support for the Trusted Board
558 Boot feature. When set to '1', BL1 and BL2 images include support to load
559 and verify the certificates and images in a FIP, and BL1 includes support
560 for the Firmware Update. The default value is '0'. Generation and inclusion
561 of certificates in the FIP and FWU\_FIP depends upon the value of the
562 ``GENERATE_COT`` option.
563
564 Note: This option depends on ``CREATE_KEYS`` to be enabled. If the keys
565 already exist in disk, they will be overwritten without further notice.
566
567- ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
568 specifies the file that contains the Trusted World private key in PEM
569 format. If ``SAVE_KEYS=1``, this file name will be used to save the key.
570
571- ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or
572 synchronous, (see "Initializing a BL32 Image" section in
573 `Firmware Design`_). It can take the value 0 (BL32 is initialized using
574 synchronous method) or 1 (BL32 is initialized using asynchronous method).
575 Default is 0.
576
577- ``TSP_NS_INTR_ASYNC_PREEMPT``: A non zero value enables the interrupt
578 routing model which routes non-secure interrupts asynchronously from TSP
579 to EL3 causing immediate preemption of TSP. The EL3 is responsible
580 for saving and restoring the TSP context in this routing model. The
581 default routing model (when the value is 0) is to route non-secure
582 interrupts to TSP allowing it to save its context and hand over
583 synchronously to EL3 via an SMC.
584
585- ``USE_COHERENT_MEM``: This flag determines whether to include the coherent
586 memory region in the BL memory map or not (see "Use of Coherent memory in
587 Trusted Firmware" section in `Firmware Design`_). It can take the value 1
588 (Coherent memory region is included) or 0 (Coherent memory region is
589 excluded). Default is 1.
590
591- ``V``: Verbose build. If assigned anything other than 0, the build commands
592 are printed. Default is 0.
593
594- ``VERSION_STRING``: String used in the log output for each TF image. Defaults
595 to a string formed by concatenating the version number, build type and build
596 string.
597
598- ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on
599 the CPU after warm boot. This is applicable for platforms which do not
600 require interconnect programming to enable cache coherency (eg: single
601 cluster platforms). If this option is enabled, then warm boot path
602 enables D-caches immediately after enabling MMU. This option defaults to 0.
603
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100604ARM development platform specific build options
605^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
606
607- ``ARM_BL31_IN_DRAM``: Boolean option to select loading of BL31 in TZC secured
608 DRAM. By default, BL31 is in the secure SRAM. Set this flag to 1 to load
609 BL31 in TZC secured DRAM. If TSP is present, then setting this option also
610 sets the TSP location to DRAM and ignores the ``ARM_TSP_RAM_LOCATION`` build
611 flag.
612
613- ``ARM_BOARD_OPTIMISE_MEM``: Boolean option to enable or disable optimisation
614 of the memory reserved for each image. This affects the maximum size of each
615 BL image as well as the number of allocated memory regions and translation
616 tables. By default this flag is 0, which means it uses the default
617 unoptimised values for these macros. ARM development platforms that wish to
618 optimise memory usage need to set this flag to 1 and must override the
619 related macros.
620
621- ``ARM_CONFIG_CNTACR``: boolean option to unlock access to the ``CNTBase<N>``
622 frame registers by setting the ``CNTCTLBase.CNTACR<N>`` register bits. The
623 frame number ``<N>`` is defined by ``PLAT_ARM_NSTIMER_FRAME_ID``, which should
624 match the frame used by the Non-Secure image (normally the Linux kernel).
625 Default is true (access to the frame is allowed).
626
627- ``ARM_DISABLE_TRUSTED_WDOG``: boolean option to disable the Trusted Watchdog.
628 By default, ARM platforms use a watchdog to trigger a system reset in case
629 an error is encountered during the boot process (for example, when an image
630 could not be loaded or authenticated). The watchdog is enabled in the early
631 platform setup hook at BL1 and disabled in the BL1 prepare exit hook. The
632 Trusted Watchdog may be disabled at build time for testing or development
633 purposes.
634
635- ``ARM_RECOM_STATE_ID_ENC``: The PSCI1.0 specification recommends an encoding
636 for the construction of composite state-ID in the power-state parameter.
637 The existing PSCI clients currently do not support this encoding of
638 State-ID yet. Hence this flag is used to configure whether to use the
639 recommended State-ID encoding or not. The default value of this flag is 0,
640 in which case the platform is configured to expect NULL in the State-ID
641 field of power-state parameter.
642
643- ``ARM_ROTPK_LOCATION``: used when ``TRUSTED_BOARD_BOOT=1``. It specifies the
644 location of the ROTPK hash returned by the function ``plat_get_rotpk_info()``
645 for ARM platforms. Depending on the selected option, the proper private key
646 must be specified using the ``ROT_KEY`` option when building the Trusted
647 Firmware. This private key will be used by the certificate generation tool
648 to sign the BL2 and Trusted Key certificates. Available options for
649 ``ARM_ROTPK_LOCATION`` are:
650
651 - ``regs`` : return the ROTPK hash stored in the Trusted root-key storage
652 registers. The private key corresponding to this ROTPK hash is not
653 currently available.
654 - ``devel_rsa`` : return a development public key hash embedded in the BL1
655 and BL2 binaries. This hash has been obtained from the RSA public key
656 ``arm_rotpk_rsa.der``, located in ``plat/arm/board/common/rotpk``. To use
657 this option, ``arm_rotprivk_rsa.pem`` must be specified as ``ROT_KEY`` when
658 creating the certificates.
Qixiang Xu1c2aef12017-08-24 15:12:20 +0800659 - ``devel_ecdsa`` : return a development public key hash embedded in the BL1
660 and BL2 binaries. This hash has been obtained from the ECDSA public key
661 ``arm_rotpk_ecdsa.der``, located in ``plat/arm/board/common/rotpk``. To use
662 this option, ``arm_rotprivk_ecdsa.pem`` must be specified as ``ROT_KEY``
663 when creating the certificates.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100664
665- ``ARM_TSP_RAM_LOCATION``: location of the TSP binary. Options:
666
667 - ``tsram`` : Trusted SRAM (default option)
668 - ``tdram`` : Trusted DRAM (if available)
669 - ``dram`` : Secure region in DRAM (configured by the TrustZone controller)
670
671- ``ARM_XLAT_TABLES_LIB_V1``: boolean option to compile the Trusted Firmware
672 with version 1 of the translation tables library instead of version 2. It is
673 set to 0 by default, which selects version 2.
674
675- ``ARM_CRYPTOCELL_INTEG`` : bool option to enable Trusted Firmware to invoke
676 ARM® TrustZone® CryptoCell functionality for Trusted Board Boot on capable
677 ARM platforms. If this option is specified, then the path to the CryptoCell
678 SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag.
679
680For a better understanding of these options, the ARM development platform memory
681map is explained in the `Firmware Design`_.
682
683ARM CSS platform specific build options
684^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
685
686- ``CSS_DETECT_PRE_1_7_0_SCP``: Boolean flag to detect SCP version
687 incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards
688 compatible change to the MTL protocol, used for AP/SCP communication.
689 Trusted Firmware no longer supports earlier SCP versions. If this option is
690 set to 1 then Trusted Firmware will detect if an earlier version is in use.
691 Default is 1.
692
693- ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP\_BL2 and
694 SCP\_BL2U to the FIP and FWU\_FIP respectively, and enables them to be loaded
695 during boot. Default is 1.
696
Soby Mathew1ced6b82017-06-12 12:37:10 +0100697- ``CSS_USE_SCMI_SDS_DRIVER``: Boolean flag which selects SCMI/SDS drivers
698 instead of SCPI/BOM driver for communicating with the SCP during power
699 management operations and for SCP RAM Firmware transfer. If this option
700 is set to 1, then SCMI/SDS drivers will be used. Default is 0.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100701
702ARM FVP platform specific build options
703^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
704
705- ``FVP_CLUSTER_COUNT`` : Configures the cluster count to be used to
706 build the topology tree within Trusted Firmware. By default the
707 Trusted Firmware is configured for dual cluster topology and this option
708 can be used to override the default value.
709
710- ``FVP_INTERCONNECT_DRIVER``: Selects the interconnect driver to be built. The
711 default interconnect driver depends on the value of ``FVP_CLUSTER_COUNT`` as
712 explained in the options below:
713
714 - ``FVP_CCI`` : The CCI driver is selected. This is the default
715 if 0 < ``FVP_CLUSTER_COUNT`` <= 2.
716 - ``FVP_CCN`` : The CCN driver is selected. This is the default
717 if ``FVP_CLUSTER_COUNT`` > 2.
718
Jeenu Viswambharan528d21b2016-11-15 13:53:57 +0000719- ``FVP_MAX_PE_PER_CPU``: Sets the maximum number of PEs implemented on any CPU
720 in the system. This option defaults to 1. Note that the build option
721 ``ARM_PLAT_MT`` doesn't have any effect on FVP platforms.
722
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100723- ``FVP_USE_GIC_DRIVER`` : Selects the GIC driver to be built. Options:
724
725 - ``FVP_GIC600`` : The GIC600 implementation of GICv3 is selected
726 - ``FVP_GICV2`` : The GICv2 only driver is selected
727 - ``FVP_GICV3`` : The GICv3 only driver is selected (default option)
728 - ``FVP_GICV3_LEGACY``: The Legacy GICv3 driver is selected (deprecated)
729 Note: If Trusted Firmware is compiled with this option on FVPs with
730 GICv3 hardware, then it configures the hardware to run in GICv2
731 emulation mode
732
733- ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer
734 for functions that wait for an arbitrary time length (udelay and mdelay).
735 The default value is 0.
736
737Debugging options
738~~~~~~~~~~~~~~~~~
739
740To compile a debug version and make the build more verbose use
741
742::
743
744 make PLAT=<platform> DEBUG=1 V=1 all
745
746AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for
747example DS-5) might not support this and may need an older version of DWARF
748symbols to be emitted by GCC. This can be achieved by using the
749``-gdwarf-<version>`` flag, with the version being set to 2 or 3. Setting the
750version to 2 is recommended for DS-5 versions older than 5.16.
751
752When debugging logic problems it might also be useful to disable all compiler
753optimizations by using ``-O0``.
754
755NOTE: Using ``-O0`` could cause output images to be larger and base addresses
756might need to be recalculated (see the **Memory layout on ARM development
757platforms** section in the `Firmware Design`_).
758
759Extra debug options can be passed to the build system by setting ``CFLAGS`` or
760``LDFLAGS``:
761
762.. code:: makefile
763
764 CFLAGS='-O0 -gdwarf-2' \
765 make PLAT=<platform> DEBUG=1 V=1 all
766
767Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be
768ignored as the linker is called directly.
769
770It is also possible to introduce an infinite loop to help in debugging the
771post-BL2 phase of the Trusted Firmware. This can be done by rebuilding BL1 with
Douglas Raillard30d7b362017-06-28 16:14:55 +0100772the ``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the `Summary of build options`_
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100773section. In this case, the developer may take control of the target using a
774debugger when indicated by the console output. When using DS-5, the following
775commands can be used:
776
777::
778
779 # Stop target execution
780 interrupt
781
782 #
783 # Prepare your debugging environment, e.g. set breakpoints
784 #
785
786 # Jump over the debug loop
787 set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4
788
789 # Resume execution
790 continue
791
792Building the Test Secure Payload
793~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
794
795The TSP is coupled with a companion runtime service in the BL31 firmware,
796called the TSPD. Therefore, if you intend to use the TSP, the BL31 image
797must be recompiled as well. For more information on SPs and SPDs, see the
798`Secure-EL1 Payloads and Dispatchers`_ section in the `Firmware Design`_.
799
800First clean the Trusted Firmware build directory to get rid of any previous
801BL31 binary. Then to build the TSP image use:
802
803::
804
805 make PLAT=<platform> SPD=tspd all
806
807An additional boot loader binary file is created in the ``build`` directory:
808
809::
810
811 build/<platform>/<build-type>/bl32.bin
812
813Checking source code style
814~~~~~~~~~~~~~~~~~~~~~~~~~~
815
816When making changes to the source for submission to the project, the source
817must be in compliance with the Linux style guide, and to assist with this check
818the project Makefile contains two targets, which both utilise the
819``checkpatch.pl`` script that ships with the Linux source tree.
820
821To check the entire source tree, you must first download a copy of
822``checkpatch.pl`` (or the full Linux source), set the ``CHECKPATCH`` environment
823variable to point to the script and build the target checkcodebase:
824
825::
826
827 make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase
828
829To just check the style on the files that differ between your local branch and
830the remote master, use:
831
832::
833
834 make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch
835
836If you wish to check your patch against something other than the remote master,
837set the ``BASE_COMMIT`` variable to your desired branch. By default, ``BASE_COMMIT``
838is set to ``origin/master``.
839
840Building and using the FIP tool
841~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
842
843Firmware Image Package (FIP) is a packaging format used by the Trusted Firmware
844project to package firmware images in a single binary. The number and type of
845images that should be packed in a FIP is platform specific and may include TF
846images and other firmware images required by the platform. For example, most
847platforms require a BL33 image which corresponds to the normal world bootloader
848(e.g. UEFI or U-Boot).
849
850The TF build system provides the make target ``fip`` to create a FIP file for the
851specified platform using the FIP creation tool included in the TF project.
852Examples below show how to build a FIP file for FVP, packaging TF images and a
853BL33 image.
854
855For AArch64:
856
857::
858
859 make PLAT=fvp BL33=<path/to/bl33.bin> fip
860
861For AArch32:
862
863::
864
865 make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path/to/bl33.bin> fip
866
867Note that AArch32 support for Normal world boot loader (BL33), like U-boot or
868UEFI, on FVP is not available upstream. Hence custom solutions are required to
869allow Linux boot on FVP. These instructions assume such a custom boot loader
870(BL33) is available.
871
872The resulting FIP may be found in:
873
874::
875
876 build/fvp/<build-type>/fip.bin
877
878For advanced operations on FIP files, it is also possible to independently build
879the tool and create or modify FIPs using this tool. To do this, follow these
880steps:
881
882It is recommended to remove old artifacts before building the tool:
883
884::
885
886 make -C tools/fiptool clean
887
888Build the tool:
889
890::
891
892 make [DEBUG=1] [V=1] fiptool
893
894The tool binary can be located in:
895
896::
897
898 ./tools/fiptool/fiptool
899
900Invoking the tool with ``--help`` will print a help message with all available
901options.
902
903Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31:
904
905::
906
907 ./tools/fiptool/fiptool create \
908 --tb-fw build/<platform>/<build-type>/bl2.bin \
909 --soc-fw build/<platform>/<build-type>/bl31.bin \
910 fip.bin
911
912Example 2: view the contents of an existing Firmware package:
913
914::
915
916 ./tools/fiptool/fiptool info <path-to>/fip.bin
917
918Example 3: update the entries of an existing Firmware package:
919
920::
921
922 # Change the BL2 from Debug to Release version
923 ./tools/fiptool/fiptool update \
924 --tb-fw build/<platform>/release/bl2.bin \
925 build/<platform>/debug/fip.bin
926
927Example 4: unpack all entries from an existing Firmware package:
928
929::
930
931 # Images will be unpacked to the working directory
932 ./tools/fiptool/fiptool unpack <path-to>/fip.bin
933
934Example 5: remove an entry from an existing Firmware package:
935
936::
937
938 ./tools/fiptool/fiptool remove \
939 --tb-fw build/<platform>/debug/fip.bin
940
941Note that if the destination FIP file exists, the create, update and
942remove operations will automatically overwrite it.
943
944The unpack operation will fail if the images already exist at the
945destination. In that case, use -f or --force to continue.
946
947More information about FIP can be found in the `Firmware Design`_ document.
948
949Migrating from fip\_create to fiptool
950^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
951
952The previous version of fiptool was called fip\_create. A compatibility script
953that emulates the basic functionality of the previous fip\_create is provided.
954However, users are strongly encouraged to migrate to fiptool.
955
956- To create a new FIP file, replace "fip\_create" with "fiptool create".
957- To update a FIP file, replace "fip\_create" with "fiptool update".
958- To dump the contents of a FIP file, replace "fip\_create --dump"
959 with "fiptool info".
960
961Building FIP images with support for Trusted Board Boot
962~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
963
964Trusted Board Boot primarily consists of the following two features:
965
966- Image Authentication, described in `Trusted Board Boot`_, and
967- Firmware Update, described in `Firmware Update`_
968
969The following steps should be followed to build FIP and (optionally) FWU\_FIP
970images with support for these features:
971
972#. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser
973 modules by checking out a recent version of the `mbed TLS Repository`_. It
974 is important to use a version that is compatible with TF and fixes any
975 known security vulnerabilities. See `mbed TLS Security Center`_ for more
976 information. The latest version of TF is tested with tag ``mbedtls-2.4.2``.
977
978 The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS
979 source files the modules depend upon.
980 ``include/drivers/auth/mbedtls/mbedtls_config.h`` contains the configuration
981 options required to build the mbed TLS sources.
982
983 Note that the mbed TLS library is licensed under the Apache version 2.0
984 license. Using mbed TLS source code will affect the licensing of
985 Trusted Firmware binaries that are built using this library.
986
987#. To build the FIP image, ensure the following command line variables are set
988 while invoking ``make`` to build Trusted Firmware:
989
990 - ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>``
991 - ``TRUSTED_BOARD_BOOT=1``
992 - ``GENERATE_COT=1``
993
994 In the case of ARM platforms, the location of the ROTPK hash must also be
995 specified at build time. Two locations are currently supported (see
996 ``ARM_ROTPK_LOCATION`` build option):
997
998 - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted
999 root-key storage registers present in the platform. On Juno, this
1000 registers are read-only. On FVP Base and Cortex models, the registers
1001 are read-only, but the value can be specified using the command line
1002 option ``bp.trusted_key_storage.public_key`` when launching the model.
1003 On both Juno and FVP models, the default value corresponds to an
1004 ECDSA-SECP256R1 public key hash, whose private part is not currently
1005 available.
1006
1007 - ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded
1008 in the ARM platform port. The private/public RSA key pair may be
1009 found in ``plat/arm/board/common/rotpk``.
1010
Qixiang Xu1c2aef12017-08-24 15:12:20 +08001011 - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded
1012 in the ARM platform port. The private/public ECDSA key pair may be
1013 found in ``plat/arm/board/common/rotpk``.
1014
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001015 Example of command line using RSA development keys:
1016
1017 ::
1018
1019 MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
1020 make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
1021 ARM_ROTPK_LOCATION=devel_rsa \
1022 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
1023 BL33=<path-to>/<bl33_image> \
1024 all fip
1025
1026 The result of this build will be the bl1.bin and the fip.bin binaries. This
1027 FIP will include the certificates corresponding to the Chain of Trust
1028 described in the TBBR-client document. These certificates can also be found
1029 in the output build directory.
1030
1031#. The optional FWU\_FIP contains any additional images to be loaded from
1032 Non-Volatile storage during the `Firmware Update`_ process. To build the
1033 FWU\_FIP, any FWU images required by the platform must be specified on the
1034 command line. On ARM development platforms like Juno, these are:
1035
1036 - NS\_BL2U. The AP non-secure Firmware Updater image.
1037 - SCP\_BL2U. The SCP Firmware Update Configuration image.
1038
1039 Example of Juno command line for generating both ``fwu`` and ``fwu_fip``
1040 targets using RSA development:
1041
1042 ::
1043
1044 MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
1045 make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
1046 ARM_ROTPK_LOCATION=devel_rsa \
1047 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
1048 BL33=<path-to>/<bl33_image> \
1049 SCP_BL2=<path-to>/<scp_bl2_image> \
1050 SCP_BL2U=<path-to>/<scp_bl2u_image> \
1051 NS_BL2U=<path-to>/<ns_bl2u_image> \
1052 all fip fwu_fip
1053
1054 Note: The BL2U image will be built by default and added to the FWU\_FIP.
1055 The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
1056 to the command line above.
1057
1058 Note: Building and installing the non-secure and SCP FWU images (NS\_BL1U,
1059 NS\_BL2U and SCP\_BL2U) is outside the scope of this document.
1060
1061 The result of this build will be bl1.bin, fip.bin and fwu\_fip.bin binaries.
1062 Both the FIP and FWU\_FIP will include the certificates corresponding to the
1063 Chain of Trust described in the TBBR-client document. These certificates
1064 can also be found in the output build directory.
1065
1066Building the Certificate Generation Tool
1067~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1068
1069The ``cert_create`` tool is built as part of the TF build process when the ``fip``
1070make target is specified and TBB is enabled (as described in the previous
1071section), but it can also be built separately with the following command:
1072
1073::
1074
1075 make PLAT=<platform> [DEBUG=1] [V=1] certtool
1076
1077For platforms that do not require their own IDs in certificate files,
1078the generic 'cert\_create' tool can be built with the following command:
1079
1080::
1081
1082 make USE_TBBR_DEFS=1 [DEBUG=1] [V=1] certtool
1083
1084``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
1085verbose. The following command should be used to obtain help about the tool:
1086
1087::
1088
1089 ./tools/cert_create/cert_create -h
1090
1091Building a FIP for Juno and FVP
1092-------------------------------
1093
1094This section provides Juno and FVP specific instructions to build Trusted
1095Firmware, obtain the additional required firmware, and pack it all together in
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001096a single FIP binary. It assumes that a `Linaro Release`_ has been installed.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001097
David Cunadob2de0992017-06-29 12:01:33 +01001098Note: Pre-built binaries for AArch32 are available from Linaro Release 16.12
1099onwards. Before that release, pre-built binaries are only available for AArch64.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001100
1101Note: follow the full instructions for one platform before switching to a
1102different one. Mixing instructions for different platforms may result in
1103corrupted binaries.
1104
1105#. Clean the working directory
1106
1107 ::
1108
1109 make realclean
1110
1111#. Obtain SCP\_BL2 (Juno) and BL33 (all platforms)
1112
1113 Use the fiptool to extract the SCP\_BL2 and BL33 images from the FIP
1114 package included in the Linaro release:
1115
1116 ::
1117
1118 # Build the fiptool
1119 make [DEBUG=1] [V=1] fiptool
1120
1121 # Unpack firmware images from Linaro FIP
1122 ./tools/fiptool/fiptool unpack \
1123 <path/to/linaro/release>/fip.bin
1124
1125 The unpack operation will result in a set of binary images extracted to the
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001126 current working directory. The SCP\_BL2 image corresponds to
1127 ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001128
1129 Note: the fiptool will complain if the images to be unpacked already
1130 exist in the current directory. If that is the case, either delete those
1131 files or use the ``--force`` option to overwrite.
1132
1133 Note for AArch32, the instructions below assume that nt-fw.bin is a custom
1134 Normal world boot loader that supports AArch32.
1135
1136#. Build TF images and create a new FIP for FVP
1137
1138 ::
1139
1140 # AArch64
1141 make PLAT=fvp BL33=nt-fw.bin all fip
1142
1143 # AArch32
1144 make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip
1145
1146#. Build TF images and create a new FIP for Juno
1147
1148 For AArch64:
1149
1150 Building for AArch64 on Juno simply requires the addition of ``SCP_BL2``
1151 as a build parameter.
1152
1153 ::
1154
1155 make PLAT=juno all fip \
1156 BL33=<path-to-juno-oe-uboot>/SOFTWARE/bl33-uboot.bin \
1157 SCP_BL2=<path-to-juno-busybox-uboot>/SOFTWARE/scp_bl2.bin
1158
1159 For AArch32:
1160
1161 Hardware restrictions on Juno prevent cold reset into AArch32 execution mode,
1162 therefore BL1 and BL2 must be compiled for AArch64, and BL32 is compiled
1163 separately for AArch32.
1164
1165 - Before building BL32, the environment variable ``CROSS_COMPILE`` must point
1166 to the AArch32 Linaro cross compiler.
1167
1168 ::
1169
1170 export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
1171
1172 - Build BL32 in AArch32.
1173
1174 ::
1175
1176 make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \
1177 RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32
1178
1179 - Before building BL1 and BL2, the environment variable ``CROSS_COMPILE``
1180 must point to the AArch64 Linaro cross compiler.
1181
1182 ::
1183
1184 export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
1185
1186 - The following parameters should be used to build BL1 and BL2 in AArch64
1187 and point to the BL32 file.
1188
1189 ::
1190
1191 make ARCH=aarch64 PLAT=juno LOAD_IMAGE_V2=1 JUNO_AARCH32_EL3_RUNTIME=1 \
1192 BL33=<path-to-juno32-oe-uboot>/SOFTWARE/bl33-uboot.bin \
1193 SCP_BL2=<path-to-juno32-oe-uboot>/SOFTWARE/scp_bl2.bin SPD=tspd \
1194 BL32=<path-to-bl32>/bl32.bin all fip
1195
1196The resulting BL1 and FIP images may be found in:
1197
1198::
1199
1200 # Juno
1201 ./build/juno/release/bl1.bin
1202 ./build/juno/release/fip.bin
1203
1204 # FVP
1205 ./build/fvp/release/bl1.bin
1206 ./build/fvp/release/fip.bin
1207
1208EL3 payloads alternative boot flow
1209----------------------------------
1210
1211On a pre-production system, the ability to execute arbitrary, bare-metal code at
1212the highest exception level is required. It allows full, direct access to the
1213hardware, for example to run silicon soak tests.
1214
1215Although it is possible to implement some baremetal secure firmware from
1216scratch, this is a complex task on some platforms, depending on the level of
1217configuration required to put the system in the expected state.
1218
1219Rather than booting a baremetal application, a possible compromise is to boot
1220``EL3 payloads`` through the Trusted Firmware instead. This is implemented as an
1221alternative boot flow, where a modified BL2 boots an EL3 payload, instead of
1222loading the other BL images and passing control to BL31. It reduces the
1223complexity of developing EL3 baremetal code by:
1224
1225- putting the system into a known architectural state;
1226- taking care of platform secure world initialization;
1227- loading the SCP\_BL2 image if required by the platform.
1228
1229When booting an EL3 payload on ARM standard platforms, the configuration of the
1230TrustZone controller is simplified such that only region 0 is enabled and is
1231configured to permit secure access only. This gives full access to the whole
1232DRAM to the EL3 payload.
1233
1234The system is left in the same state as when entering BL31 in the default boot
1235flow. In particular:
1236
1237- Running in EL3;
1238- Current state is AArch64;
1239- Little-endian data access;
1240- All exceptions disabled;
1241- MMU disabled;
1242- Caches disabled.
1243
1244Booting an EL3 payload
1245~~~~~~~~~~~~~~~~~~~~~~
1246
1247The EL3 payload image is a standalone image and is not part of the FIP. It is
1248not loaded by the Trusted Firmware. Therefore, there are 2 possible scenarios:
1249
1250- The EL3 payload may reside in non-volatile memory (NVM) and execute in
1251 place. In this case, booting it is just a matter of specifying the right
1252 address in NVM through ``EL3_PAYLOAD_BASE`` when building the TF.
1253
1254- The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at
1255 run-time.
1256
1257To help in the latter scenario, the ``SPIN_ON_BL1_EXIT=1`` build option can be
1258used. The infinite loop that it introduces in BL1 stops execution at the right
1259moment for a debugger to take control of the target and load the payload (for
1260example, over JTAG).
1261
1262It is expected that this loading method will work in most cases, as a debugger
1263connection is usually available in a pre-production system. The user is free to
1264use any other platform-specific mechanism to load the EL3 payload, though.
1265
1266Booting an EL3 payload on FVP
1267^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1268
1269The EL3 payloads boot flow requires the CPU's mailbox to be cleared at reset for
1270the secondary CPUs holding pen to work properly. Unfortunately, its reset value
1271is undefined on the FVP platform and the FVP platform code doesn't clear it.
1272Therefore, one must modify the way the model is normally invoked in order to
1273clear the mailbox at start-up.
1274
1275One way to do that is to create an 8-byte file containing all zero bytes using
1276the following command:
1277
1278::
1279
1280 dd if=/dev/zero of=mailbox.dat bs=1 count=8
1281
1282and pre-load it into the FVP memory at the mailbox address (i.e. ``0x04000000``)
1283using the following model parameters:
1284
1285::
1286
1287 --data cluster0.cpu0=mailbox.dat@0x04000000 [Base FVPs]
1288 --data=mailbox.dat@0x04000000 [Foundation FVP]
1289
1290To provide the model with the EL3 payload image, the following methods may be
1291used:
1292
1293#. If the EL3 payload is able to execute in place, it may be programmed into
1294 flash memory. On Base Cortex and AEM FVPs, the following model parameter
1295 loads it at the base address of the NOR FLASH1 (the NOR FLASH0 is already
1296 used for the FIP):
1297
1298 ::
1299
1300 -C bp.flashloader1.fname="/path/to/el3-payload"
1301
1302 On Foundation FVP, there is no flash loader component and the EL3 payload
1303 may be programmed anywhere in flash using method 3 below.
1304
1305#. When using the ``SPIN_ON_BL1_EXIT=1`` loading method, the following DS-5
1306 command may be used to load the EL3 payload ELF image over JTAG:
1307
1308 ::
1309
1310 load /path/to/el3-payload.elf
1311
1312#. The EL3 payload may be pre-loaded in volatile memory using the following
1313 model parameters:
1314
1315 ::
1316
1317 --data cluster0.cpu0="/path/to/el3-payload"@address [Base FVPs]
1318 --data="/path/to/el3-payload"@address [Foundation FVP]
1319
1320 The address provided to the FVP must match the ``EL3_PAYLOAD_BASE`` address
1321 used when building the Trusted Firmware.
1322
1323Booting an EL3 payload on Juno
1324^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1325
1326If the EL3 payload is able to execute in place, it may be programmed in flash
1327memory by adding an entry in the ``SITE1/HBI0262x/images.txt`` configuration file
1328on the Juno SD card (where ``x`` depends on the revision of the Juno board).
1329Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory
1330programming" for more information.
1331
1332Alternatively, the same DS-5 command mentioned in the FVP section above can
1333be used to load the EL3 payload's ELF file over JTAG on Juno.
1334
1335Preloaded BL33 alternative boot flow
1336------------------------------------
1337
1338Some platforms have the ability to preload BL33 into memory instead of relying
1339on Trusted Firmware to load it. This may simplify packaging of the normal world
1340code and improve performance in a development environment. When secure world
1341cold boot is complete, Trusted Firmware simply jumps to a BL33 base address
1342provided at build time.
1343
1344For this option to be used, the ``PRELOADED_BL33_BASE`` build option has to be
1345used when compiling the Trusted Firmware. For example, the following command
1346will create a FIP without a BL33 and prepare to jump to a BL33 image loaded at
1347address 0x80000000:
1348
1349::
1350
1351 make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip
1352
1353Boot of a preloaded bootwrapped kernel image on Base FVP
1354~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1355
1356The following example uses the AArch64 boot wrapper. This simplifies normal
1357world booting while also making use of TF features. It can be obtained from its
1358repository with:
1359
1360::
1361
1362 git clone git://git.kernel.org/pub/scm/linux/kernel/git/mark/boot-wrapper-aarch64.git
1363
1364After compiling it, an ELF file is generated. It can be loaded with the
1365following command:
1366
1367::
1368
1369 <path-to>/FVP_Base_AEMv8A-AEMv8A \
1370 -C bp.secureflashloader.fname=bl1.bin \
1371 -C bp.flashloader0.fname=fip.bin \
1372 -a cluster0.cpu0=<bootwrapped-kernel.elf> \
1373 --start cluster0.cpu0=0x0
1374
1375The ``-a cluster0.cpu0=<bootwrapped-kernel.elf>`` option loads the ELF file. It
1376also sets the PC register to the ELF entry point address, which is not the
1377desired behaviour, so the ``--start cluster0.cpu0=0x0`` option forces the PC back
1378to 0x0 (the BL1 entry point address) on CPU #0. The ``PRELOADED_BL33_BASE`` define
1379used when compiling the FIP must match the ELF entry point.
1380
1381Boot of a preloaded bootwrapped kernel image on Juno
1382~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1383
1384The procedure to obtain and compile the boot wrapper is very similar to the case
1385of the FVP. The execution must be stopped at the end of bl2\_main(), and the
1386loading method explained above in the EL3 payload boot flow section may be used
1387to load the ELF file over JTAG on Juno.
1388
1389Running the software on FVP
1390---------------------------
1391
1392The latest version of the AArch64 build of ARM Trusted Firmware has been tested
1393on the following ARM FVPs (64-bit host machine only).
1394
Eleanor Bonnicie124dc42017-10-04 15:03:33 +01001395NOTE: Unless otherwise stated, the model version is Version 11.1 Build 11.1.22.
David Cunado124415e2017-06-27 17:31:12 +01001396
1397- ``Foundation_Platform``
Eleanor Bonnicie124dc42017-10-04 15:03:33 +01001398- ``FVP_Base_AEMv8A-AEMv8A`` (Version 8.7, Build 0.8.8702)
David Cunado124415e2017-06-27 17:31:12 +01001399- ``FVP_Base_Cortex-A35x4``
1400- ``FVP_Base_Cortex-A53x4``
1401- ``FVP_Base_Cortex-A57x4-A53x4``
1402- ``FVP_Base_Cortex-A57x4``
1403- ``FVP_Base_Cortex-A72x4-A53x4``
1404- ``FVP_Base_Cortex-A72x4``
1405- ``FVP_Base_Cortex-A73x4-A53x4``
1406- ``FVP_Base_Cortex-A73x4``
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001407
1408The latest version of the AArch32 build of ARM Trusted Firmware has been tested
1409on the following ARM FVPs (64-bit host machine only).
1410
Eleanor Bonnicie124dc42017-10-04 15:03:33 +01001411- ``FVP_Base_AEMv8A-AEMv8A`` (Version 8.7, Build 0.8.8702)
David Cunado124415e2017-06-27 17:31:12 +01001412- ``FVP_Base_Cortex-A32x4``
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001413
1414NOTE: The build numbers quoted above are those reported by launching the FVP
1415with the ``--version`` parameter.
1416
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001417NOTE: Linaro provides a ramdisk image in prebuilt FVP configurations and full
1418file systems that can be downloaded separately. To run an FVP with a virtio
1419file system image an additional FVP configuration option
1420``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
1421used.
1422
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001423NOTE: The software will not work on Version 1.0 of the Foundation FVP.
1424The commands below would report an ``unhandled argument`` error in this case.
1425
1426NOTE: FVPs can be launched with ``--cadi-server`` option such that a
1427CADI-compliant debugger (for example, ARM DS-5) can connect to and control its
1428execution.
1429
Eleanor Bonnicie124dc42017-10-04 15:03:33 +01001430NOTE: Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202
David Cunado97309462017-07-31 12:24:51 +01001431the internal synchronisation timings changed compared to older versions of the
1432models. The models can be launched with ``-Q 100`` option if they are required
1433to match the run time characteristics of the older versions.
1434
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001435The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
1436downloaded for free from `ARM's website`_.
1437
David Cunado124415e2017-06-27 17:31:12 +01001438The Cortex-A models listed above are also available to download from
1439`ARM's website`_.
1440
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001441Please refer to the FVP documentation for a detailed description of the model
1442parameter options. A brief description of the important ones that affect the ARM
1443Trusted Firmware and normal world software behavior is provided below.
1444
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001445Obtaining the Flattened Device Trees
1446~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1447
1448Depending on the FVP configuration and Linux configuration used, different
1449FDT files are required. FDTs for the Foundation and Base FVPs can be found in
1450the Trusted Firmware source directory under ``fdts/``. The Foundation FVP has a
1451subset of the Base FVP components. For example, the Foundation FVP lacks CLCD
1452and MMC support, and has only one CPU cluster.
1453
1454Note: It is not recommended to use the FDTs built along the kernel because not
1455all FDTs are available from there.
1456
1457- ``fvp-base-gicv2-psci.dtb``
1458
1459 For use with both AEMv8 and Cortex-A57-A53 Base FVPs with
1460 Base memory map configuration.
1461
1462- ``fvp-base-gicv2-psci-aarch32.dtb``
1463
1464 For use with AEMv8 and Cortex-A32 Base FVPs running Linux in AArch32 state
1465 with Base memory map configuration.
1466
1467- ``fvp-base-gicv3-psci.dtb``
1468
1469 (Default) For use with both AEMv8 and Cortex-A57-A53 Base FVPs with Base
1470 memory map configuration and Linux GICv3 support.
1471
1472- ``fvp-base-gicv3-psci-aarch32.dtb``
1473
1474 For use with AEMv8 and Cortex-A32 Base FVPs running Linux in AArch32 state
1475 with Base memory map configuration and Linux GICv3 support.
1476
1477- ``fvp-foundation-gicv2-psci.dtb``
1478
1479 For use with Foundation FVP with Base memory map configuration.
1480
1481- ``fvp-foundation-gicv3-psci.dtb``
1482
1483 (Default) For use with Foundation FVP with Base memory map configuration
1484 and Linux GICv3 support.
1485
1486Running on the Foundation FVP with reset to BL1 entrypoint
1487~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1488
1489The following ``Foundation_Platform`` parameters should be used to boot Linux with
14904 CPUs using the AArch64 build of ARM Trusted Firmware.
1491
1492::
1493
1494 <path-to>/Foundation_Platform \
1495 --cores=4 \
1496 --secure-memory \
1497 --visualization \
1498 --gicv3 \
1499 --data="<path-to>/<bl1-binary>"@0x0 \
1500 --data="<path-to>/<FIP-binary>"@0x08000000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001501 --data="<path-to>/<fdt>"@0x82000000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001502 --data="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001503 --data="<path-to>/<ramdisk-binary>"@0x84000000
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001504
1505Notes:
1506
1507- BL1 is loaded at the start of the Trusted ROM.
1508- The Firmware Image Package is loaded at the start of NOR FLASH0.
1509- The Linux kernel image and device tree are loaded in DRAM.
1510- The default use-case for the Foundation FVP is to use the ``--gicv3`` option
1511 and enable the GICv3 device in the model. Note that without this option,
1512 the Foundation FVP defaults to legacy (Versatile Express) memory map which
1513 is not supported by ARM Trusted Firmware.
1514
1515Running on the AEMv8 Base FVP with reset to BL1 entrypoint
1516~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1517
1518The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
1519with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
1520
1521::
1522
1523 <path-to>/FVP_Base_AEMv8A-AEMv8A \
1524 -C pctl.startup=0.0.0.0 \
1525 -C bp.secure_memory=1 \
1526 -C bp.tzc_400.diagnostics=1 \
1527 -C cluster0.NUM_CORES=4 \
1528 -C cluster1.NUM_CORES=4 \
1529 -C cache_state_modelled=1 \
1530 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
1531 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001532 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001533 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001534 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001535
1536Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint
1537~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1538
1539The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
1540with 8 CPUs using the AArch32 build of ARM Trusted Firmware.
1541
1542::
1543
1544 <path-to>/FVP_Base_AEMv8A-AEMv8A \
1545 -C pctl.startup=0.0.0.0 \
1546 -C bp.secure_memory=1 \
1547 -C bp.tzc_400.diagnostics=1 \
1548 -C cluster0.NUM_CORES=4 \
1549 -C cluster1.NUM_CORES=4 \
1550 -C cache_state_modelled=1 \
1551 -C cluster0.cpu0.CONFIG64=0 \
1552 -C cluster0.cpu1.CONFIG64=0 \
1553 -C cluster0.cpu2.CONFIG64=0 \
1554 -C cluster0.cpu3.CONFIG64=0 \
1555 -C cluster1.cpu0.CONFIG64=0 \
1556 -C cluster1.cpu1.CONFIG64=0 \
1557 -C cluster1.cpu2.CONFIG64=0 \
1558 -C cluster1.cpu3.CONFIG64=0 \
1559 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
1560 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001561 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001562 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001563 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001564
1565Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint
1566~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1567
1568The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
1569boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
1570
1571::
1572
1573 <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
1574 -C pctl.startup=0.0.0.0 \
1575 -C bp.secure_memory=1 \
1576 -C bp.tzc_400.diagnostics=1 \
1577 -C cache_state_modelled=1 \
1578 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
1579 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001580 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001581 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001582 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001583
1584Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint
1585~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1586
1587The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
1588boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware.
1589
1590::
1591
1592 <path-to>/FVP_Base_Cortex-A32x4 \
1593 -C pctl.startup=0.0.0.0 \
1594 -C bp.secure_memory=1 \
1595 -C bp.tzc_400.diagnostics=1 \
1596 -C cache_state_modelled=1 \
1597 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
1598 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001599 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001600 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001601 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001602
1603Running on the AEMv8 Base FVP with reset to BL31 entrypoint
1604~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1605
1606The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
1607with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
1608
1609::
1610
1611 <path-to>/FVP_Base_AEMv8A-AEMv8A \
1612 -C pctl.startup=0.0.0.0 \
1613 -C bp.secure_memory=1 \
1614 -C bp.tzc_400.diagnostics=1 \
1615 -C cluster0.NUM_CORES=4 \
1616 -C cluster1.NUM_CORES=4 \
1617 -C cache_state_modelled=1 \
Qixiang Xua5f72812017-08-31 11:45:32 +08001618 -C cluster0.cpu0.RVBAR=0x04020000 \
1619 -C cluster0.cpu1.RVBAR=0x04020000 \
1620 -C cluster0.cpu2.RVBAR=0x04020000 \
1621 -C cluster0.cpu3.RVBAR=0x04020000 \
1622 -C cluster1.cpu0.RVBAR=0x04020000 \
1623 -C cluster1.cpu1.RVBAR=0x04020000 \
1624 -C cluster1.cpu2.RVBAR=0x04020000 \
1625 -C cluster1.cpu3.RVBAR=0x04020000 \
1626 --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04020000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001627 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
1628 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001629 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001630 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001631 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001632
1633Notes:
1634
1635- Since a FIP is not loaded when using BL31 as reset entrypoint, the
1636 ``--data="<path-to><bl31|bl32|bl33-binary>"@<base-address-of-binary>``
1637 parameter is needed to load the individual bootloader images in memory.
1638 BL32 image is only needed if BL31 has been built to expect a Secure-EL1
1639 Payload.
1640
1641- The ``-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>`` parameter, where
1642 X and Y are the cluster and CPU numbers respectively, is used to set the
1643 reset vector for each core.
1644
1645- Changing the default value of ``ARM_TSP_RAM_LOCATION`` will also require
1646 changing the value of
1647 ``--data="<path-to><bl32-binary>"@<base-address-of-bl32>`` to the new value of
1648 ``BL32_BASE``.
1649
1650Running on the AEMv8 Base FVP (AArch32) with reset to SP\_MIN entrypoint
1651~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1652
1653The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
1654with 8 CPUs using the AArch32 build of ARM Trusted Firmware.
1655
1656::
1657
1658 <path-to>/FVP_Base_AEMv8A-AEMv8A \
1659 -C pctl.startup=0.0.0.0 \
1660 -C bp.secure_memory=1 \
1661 -C bp.tzc_400.diagnostics=1 \
1662 -C cluster0.NUM_CORES=4 \
1663 -C cluster1.NUM_CORES=4 \
1664 -C cache_state_modelled=1 \
1665 -C cluster0.cpu0.CONFIG64=0 \
1666 -C cluster0.cpu1.CONFIG64=0 \
1667 -C cluster0.cpu2.CONFIG64=0 \
1668 -C cluster0.cpu3.CONFIG64=0 \
1669 -C cluster1.cpu0.CONFIG64=0 \
1670 -C cluster1.cpu1.CONFIG64=0 \
1671 -C cluster1.cpu2.CONFIG64=0 \
1672 -C cluster1.cpu3.CONFIG64=0 \
1673 -C cluster0.cpu0.RVBAR=0x04001000 \
1674 -C cluster0.cpu1.RVBAR=0x04001000 \
1675 -C cluster0.cpu2.RVBAR=0x04001000 \
1676 -C cluster0.cpu3.RVBAR=0x04001000 \
1677 -C cluster1.cpu0.RVBAR=0x04001000 \
1678 -C cluster1.cpu1.RVBAR=0x04001000 \
1679 -C cluster1.cpu2.RVBAR=0x04001000 \
1680 -C cluster1.cpu3.RVBAR=0x04001000 \
1681 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
1682 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001683 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001684 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001685 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001686
1687Note: The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``.
1688It should match the address programmed into the RVBAR register as well.
1689
1690Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
1691~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1692
1693The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
1694boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware.
1695
1696::
1697
1698 <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
1699 -C pctl.startup=0.0.0.0 \
1700 -C bp.secure_memory=1 \
1701 -C bp.tzc_400.diagnostics=1 \
1702 -C cache_state_modelled=1 \
Qixiang Xua5f72812017-08-31 11:45:32 +08001703 -C cluster0.cpu0.RVBARADDR=0x04020000 \
1704 -C cluster0.cpu1.RVBARADDR=0x04020000 \
1705 -C cluster0.cpu2.RVBARADDR=0x04020000 \
1706 -C cluster0.cpu3.RVBARADDR=0x04020000 \
1707 -C cluster1.cpu0.RVBARADDR=0x04020000 \
1708 -C cluster1.cpu1.RVBARADDR=0x04020000 \
1709 -C cluster1.cpu2.RVBARADDR=0x04020000 \
1710 -C cluster1.cpu3.RVBARADDR=0x04020000 \
1711 --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04020000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001712 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
1713 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001714 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001715 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001716 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001717
1718Running on the Cortex-A32 Base FVP (AArch32) with reset to SP\_MIN entrypoint
1719~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1720
1721The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
1722boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware.
1723
1724::
1725
1726 <path-to>/FVP_Base_Cortex-A32x4 \
1727 -C pctl.startup=0.0.0.0 \
1728 -C bp.secure_memory=1 \
1729 -C bp.tzc_400.diagnostics=1 \
1730 -C cache_state_modelled=1 \
1731 -C cluster0.cpu0.RVBARADDR=0x04001000 \
1732 -C cluster0.cpu1.RVBARADDR=0x04001000 \
1733 -C cluster0.cpu2.RVBARADDR=0x04001000 \
1734 -C cluster0.cpu3.RVBARADDR=0x04001000 \
1735 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \
1736 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001737 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001738 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001739 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001740
1741Running the software on Juno
1742----------------------------
1743
David Cunadob2de0992017-06-29 12:01:33 +01001744This version of the ARM Trusted Firmware has been tested on variants r0, r1 and
1745r2 of Juno.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001746
1747To execute the software stack on Juno, the version of the Juno board recovery
1748image indicated in the `Linaro Release Notes`_ must be installed. If you have an
1749earlier version installed or are unsure which version is installed, please
1750re-install the recovery image by following the
1751`Instructions for using Linaro's deliverables on Juno`_.
1752
1753Preparing Trusted Firmware images
1754~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1755
1756After building Trusted Firmware, the files ``bl1.bin`` and ``fip.bin`` need copying
1757to the ``SOFTWARE/`` directory of the Juno SD card.
1758
1759Other Juno software information
1760~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1761
1762Please visit the `ARM Platforms Portal`_ to get support and obtain any other Juno
1763software information. Please also refer to the `Juno Getting Started Guide`_ to
1764get more detailed information about the Juno ARM development platform and how to
1765configure it.
1766
1767Testing SYSTEM SUSPEND on Juno
1768~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1769
1770The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend
1771to RAM. For more details refer to section 5.16 of `PSCI`_. To test system suspend
1772on Juno, at the linux shell prompt, issue the following command:
1773
1774::
1775
1776 echo +10 > /sys/class/rtc/rtc0/wakealarm
1777 echo -n mem > /sys/power/state
1778
1779The Juno board should suspend to RAM and then wakeup after 10 seconds due to
1780wakeup interrupt from RTC.
1781
1782--------------
1783
1784*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.*
1785
David Cunadob2de0992017-06-29 12:01:33 +01001786.. _Linaro: `Linaro Release Notes`_
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001787.. _Linaro Release: `Linaro Release Notes`_
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001788.. _Linaro Release Notes: https://community.arm.com/tools/dev-platforms/b/documents/posts/linaro-release-notes-deprecated
David Cunadob2de0992017-06-29 12:01:33 +01001789.. _Linaro Release 17.04: https://community.arm.com/tools/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease17.04
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001790.. _Linaro instructions: https://community.arm.com/dev-platforms/b/documents/posts/instructions-for-using-the-linaro-software-deliverables
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001791.. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/b/documents/posts/using-linaros-deliverables-on-juno
1792.. _ARM Platforms Portal: https://community.arm.com/dev-platforms/
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001793.. _Development Studio 5 (DS-5): http://www.arm.com/products/tools/software-tools/ds-5/index.php
Antonio Nino Diazb5d68092017-05-23 11:49:22 +01001794.. _Dia: https://wiki.gnome.org/Apps/Dia/Download
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001795.. _here: psci-lib-integration-guide.rst
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001796.. _Trusted Board Boot: trusted-board-boot.rst
1797.. _Secure-EL1 Payloads and Dispatchers: firmware-design.rst#user-content-secure-el1-payloads-and-dispatchers
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001798.. _Firmware Update: firmware-update.rst
1799.. _Firmware Design: firmware-design.rst
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001800.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
1801.. _mbed TLS Security Center: https://tls.mbed.org/security
Eleanor Bonnicic61b22e2017-07-07 14:33:24 +01001802.. _ARM's website: `FVP models`_
1803.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001804.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
David Cunadob2de0992017-06-29 12:01:33 +01001805.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf