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