1 ARM Trusted Firmware User Guide 2 =============================== 3 4 5 .. section-numbering:: 6 :suffix: . 7 8 .. contents:: 9 10 This document describes how to build ARM Trusted Firmware (TF) and run it with a 11 tested set of other software components using defined configurations on the Juno 12 ARM development platform and ARM Fixed Virtual Platform (FVP) models. It is 13 possible to use other software components, configurations and platforms but that 14 is outside the scope of this document. 15 16 This document assumes that the reader has previous experience running a fully 17 bootable Linux software stack on Juno or FVP using the prebuilt binaries and 18 filesystems provided by `Linaro`_. Further information may be found in the 19 `Linaro instructions`_. It also assumes that the user understands the role of 20 the different software components required to boot a Linux system: 21 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 28 This document also assumes that the user is familiar with the `FVP models`_ and 29 the different command line options available to launch the model. 30 31 This document should be used in conjunction with the `Firmware Design`_. 32 33 Host machine requirements 34 ------------------------- 35 36 The minimum recommended machine specification for building the software and 37 running the FVP models is a dual-core processor running at 2GHz with 12GB of 38 RAM. For best performance, use a machine with a quad-core processor running at 39 2.6GHz with 16GB of RAM. 40 41 The software has been tested on Ubuntu 14.04 LTS (64-bit). Packages used for 42 building the software were installed from that distribution unless otherwise 43 specified. 44 45 The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE, 46 Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain. 47 48 Tools 49 ----- 50 51 Install the required packages to build Trusted Firmware with the following 52 command: 53 54 :: 55 56 sudo apt-get install build-essential gcc make git libssl-dev 57 58 ARM TF has been tested with `Linaro Release 17.04`_. 59 60 Download and install the AArch32 or AArch64 little-endian GCC cross compiler. 61 The `Linaro Release Notes`_ documents which version of the compiler to use for a 62 given Linaro Release. Also, these `Linaro instructions`_ provide further 63 guidance and a script, which can be used to download Linaro deliverables 64 automatically. 65 66 Optionally, Trusted Firmware can be built using clang or ARM Compiler 6. 67 See instructions below on how to switch the default compiler. 68 69 In 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 76 - 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 80 Getting the Trusted Firmware source code 81 ---------------------------------------- 82 83 Download the Trusted Firmware source code from Github: 84 85 :: 86 87 git clone https://github.com/ARM-software/arm-trusted-firmware.git 88 89 Building 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 198 Summary of build options 199 ~~~~~~~~~~~~~~~~~~~~~~~~ 200 201 ARM Trusted Firmware build system supports the following build options. Unless 202 mentioned otherwise, these options are expected to be specified at the build 203 command line and are not to be modified in any component makefiles. Note that 204 the build system doesn't track dependency for build options. Therefore, if any 205 of the build options are changed from a previous build, a clean build must be 206 performed. 207 208 Common 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 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 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. 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_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 265 - ``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 346 - ``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 351 - ``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 389 - ``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 402 - ``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 421 - ``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. 423 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. 427 428 - ``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 473 contain a platform makefile named ``platform.mk``. For example to build ARM 474 Trusted Firmware for ARM Juno board select PLAT=juno. 475 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 550 - ``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 557 - ``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 604 ARM 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. 659 - ``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. 664 665 - ``ARM_TSP_RAM_LOCATION``: location of the TSP binary. Options: 666 667 - ``tsram`` : Trusted SRAM (default option when TBB is not enabled) 668 - ``tdram`` : Trusted DRAM (if available) 669 - ``dram`` : Secure region in DRAM (default option when TBB is enabled, 670 configured by the TrustZone controller) 671 672 - ``ARM_XLAT_TABLES_LIB_V1``: boolean option to compile the Trusted Firmware 673 with version 1 of the translation tables library instead of version 2. It is 674 set to 0 by default, which selects version 2. 675 676 - ``ARM_CRYPTOCELL_INTEG`` : bool option to enable Trusted Firmware to invoke 677 ARM TrustZone CryptoCell functionality for Trusted Board Boot on capable 678 ARM platforms. If this option is specified, then the path to the CryptoCell 679 SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag. 680 681 For a better understanding of these options, the ARM development platform memory 682 map is explained in the `Firmware Design`_. 683 684 ARM CSS platform specific build options 685 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 686 687 - ``CSS_DETECT_PRE_1_7_0_SCP``: Boolean flag to detect SCP version 688 incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards 689 compatible change to the MTL protocol, used for AP/SCP communication. 690 Trusted Firmware no longer supports earlier SCP versions. If this option is 691 set to 1 then Trusted Firmware will detect if an earlier version is in use. 692 Default is 1. 693 694 - ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP\_BL2 and 695 SCP\_BL2U to the FIP and FWU\_FIP respectively, and enables them to be loaded 696 during boot. Default is 1. 697 698 - ``CSS_USE_SCMI_SDS_DRIVER``: Boolean flag which selects SCMI/SDS drivers 699 instead of SCPI/BOM driver for communicating with the SCP during power 700 management operations and for SCP RAM Firmware transfer. If this option 701 is set to 1, then SCMI/SDS drivers will be used. Default is 0. 702 703 ARM FVP platform specific build options 704 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 705 706 - ``FVP_CLUSTER_COUNT`` : Configures the cluster count to be used to 707 build the topology tree within Trusted Firmware. By default the 708 Trusted Firmware is configured for dual cluster topology and this option 709 can be used to override the default value. 710 711 - ``FVP_INTERCONNECT_DRIVER``: Selects the interconnect driver to be built. The 712 default interconnect driver depends on the value of ``FVP_CLUSTER_COUNT`` as 713 explained in the options below: 714 715 - ``FVP_CCI`` : The CCI driver is selected. This is the default 716 if 0 < ``FVP_CLUSTER_COUNT`` <= 2. 717 - ``FVP_CCN`` : The CCN driver is selected. This is the default 718 if ``FVP_CLUSTER_COUNT`` > 2. 719 720 - ``FVP_MAX_PE_PER_CPU``: Sets the maximum number of PEs implemented on any CPU 721 in the system. This option defaults to 1. Note that the build option 722 ``ARM_PLAT_MT`` doesn't have any effect on FVP platforms. 723 724 - ``FVP_USE_GIC_DRIVER`` : Selects the GIC driver to be built. Options: 725 726 - ``FVP_GIC600`` : The GIC600 implementation of GICv3 is selected 727 - ``FVP_GICV2`` : The GICv2 only driver is selected 728 - ``FVP_GICV3`` : The GICv3 only driver is selected (default option) 729 - ``FVP_GICV3_LEGACY``: The Legacy GICv3 driver is selected (deprecated) 730 Note: If Trusted Firmware is compiled with this option on FVPs with 731 GICv3 hardware, then it configures the hardware to run in GICv2 732 emulation mode 733 734 - ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer 735 for functions that wait for an arbitrary time length (udelay and mdelay). 736 The default value is 0. 737 738 Debugging options 739 ~~~~~~~~~~~~~~~~~ 740 741 To compile a debug version and make the build more verbose use 742 743 :: 744 745 make PLAT=<platform> DEBUG=1 V=1 all 746 747 AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for 748 example DS-5) might not support this and may need an older version of DWARF 749 symbols to be emitted by GCC. This can be achieved by using the 750 ``-gdwarf-<version>`` flag, with the version being set to 2 or 3. Setting the 751 version to 2 is recommended for DS-5 versions older than 5.16. 752 753 When debugging logic problems it might also be useful to disable all compiler 754 optimizations by using ``-O0``. 755 756 NOTE: Using ``-O0`` could cause output images to be larger and base addresses 757 might need to be recalculated (see the **Memory layout on ARM development 758 platforms** section in the `Firmware Design`_). 759 760 Extra debug options can be passed to the build system by setting ``CFLAGS`` or 761 ``LDFLAGS``: 762 763 .. code:: makefile 764 765 CFLAGS='-O0 -gdwarf-2' \ 766 make PLAT=<platform> DEBUG=1 V=1 all 767 768 Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be 769 ignored as the linker is called directly. 770 771 It is also possible to introduce an infinite loop to help in debugging the 772 post-BL2 phase of the Trusted Firmware. This can be done by rebuilding BL1 with 773 the ``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the `Summary of build options`_ 774 section. In this case, the developer may take control of the target using a 775 debugger when indicated by the console output. When using DS-5, the following 776 commands can be used: 777 778 :: 779 780 # Stop target execution 781 interrupt 782 783 # 784 # Prepare your debugging environment, e.g. set breakpoints 785 # 786 787 # Jump over the debug loop 788 set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4 789 790 # Resume execution 791 continue 792 793 Building the Test Secure Payload 794 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 795 796 The TSP is coupled with a companion runtime service in the BL31 firmware, 797 called the TSPD. Therefore, if you intend to use the TSP, the BL31 image 798 must be recompiled as well. For more information on SPs and SPDs, see the 799 `Secure-EL1 Payloads and Dispatchers`_ section in the `Firmware Design`_. 800 801 First clean the Trusted Firmware build directory to get rid of any previous 802 BL31 binary. Then to build the TSP image use: 803 804 :: 805 806 make PLAT=<platform> SPD=tspd all 807 808 An additional boot loader binary file is created in the ``build`` directory: 809 810 :: 811 812 build/<platform>/<build-type>/bl32.bin 813 814 Checking source code style 815 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 816 817 When making changes to the source for submission to the project, the source 818 must be in compliance with the Linux style guide, and to assist with this check 819 the project Makefile contains two targets, which both utilise the 820 ``checkpatch.pl`` script that ships with the Linux source tree. 821 822 To check the entire source tree, you must first download a copy of 823 ``checkpatch.pl`` (or the full Linux source), set the ``CHECKPATCH`` environment 824 variable to point to the script and build the target checkcodebase: 825 826 :: 827 828 make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase 829 830 To just check the style on the files that differ between your local branch and 831 the remote master, use: 832 833 :: 834 835 make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch 836 837 If you wish to check your patch against something other than the remote master, 838 set the ``BASE_COMMIT`` variable to your desired branch. By default, ``BASE_COMMIT`` 839 is set to ``origin/master``. 840 841 Building and using the FIP tool 842 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 843 844 Firmware Image Package (FIP) is a packaging format used by the Trusted Firmware 845 project to package firmware images in a single binary. The number and type of 846 images that should be packed in a FIP is platform specific and may include TF 847 images and other firmware images required by the platform. For example, most 848 platforms require a BL33 image which corresponds to the normal world bootloader 849 (e.g. UEFI or U-Boot). 850 851 The TF build system provides the make target ``fip`` to create a FIP file for the 852 specified platform using the FIP creation tool included in the TF project. 853 Examples below show how to build a FIP file for FVP, packaging TF images and a 854 BL33 image. 855 856 For AArch64: 857 858 :: 859 860 make PLAT=fvp BL33=<path/to/bl33.bin> fip 861 862 For AArch32: 863 864 :: 865 866 make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path/to/bl33.bin> fip 867 868 Note that AArch32 support for Normal world boot loader (BL33), like U-boot or 869 UEFI, on FVP is not available upstream. Hence custom solutions are required to 870 allow Linux boot on FVP. These instructions assume such a custom boot loader 871 (BL33) is available. 872 873 The resulting FIP may be found in: 874 875 :: 876 877 build/fvp/<build-type>/fip.bin 878 879 For advanced operations on FIP files, it is also possible to independently build 880 the tool and create or modify FIPs using this tool. To do this, follow these 881 steps: 882 883 It is recommended to remove old artifacts before building the tool: 884 885 :: 886 887 make -C tools/fiptool clean 888 889 Build the tool: 890 891 :: 892 893 make [DEBUG=1] [V=1] fiptool 894 895 The tool binary can be located in: 896 897 :: 898 899 ./tools/fiptool/fiptool 900 901 Invoking the tool with ``--help`` will print a help message with all available 902 options. 903 904 Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31: 905 906 :: 907 908 ./tools/fiptool/fiptool create \ 909 --tb-fw build/<platform>/<build-type>/bl2.bin \ 910 --soc-fw build/<platform>/<build-type>/bl31.bin \ 911 fip.bin 912 913 Example 2: view the contents of an existing Firmware package: 914 915 :: 916 917 ./tools/fiptool/fiptool info <path-to>/fip.bin 918 919 Example 3: update the entries of an existing Firmware package: 920 921 :: 922 923 # Change the BL2 from Debug to Release version 924 ./tools/fiptool/fiptool update \ 925 --tb-fw build/<platform>/release/bl2.bin \ 926 build/<platform>/debug/fip.bin 927 928 Example 4: unpack all entries from an existing Firmware package: 929 930 :: 931 932 # Images will be unpacked to the working directory 933 ./tools/fiptool/fiptool unpack <path-to>/fip.bin 934 935 Example 5: remove an entry from an existing Firmware package: 936 937 :: 938 939 ./tools/fiptool/fiptool remove \ 940 --tb-fw build/<platform>/debug/fip.bin 941 942 Note that if the destination FIP file exists, the create, update and 943 remove operations will automatically overwrite it. 944 945 The unpack operation will fail if the images already exist at the 946 destination. In that case, use -f or --force to continue. 947 948 More information about FIP can be found in the `Firmware Design`_ document. 949 950 Migrating from fip\_create to fiptool 951 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 952 953 The previous version of fiptool was called fip\_create. A compatibility script 954 that emulates the basic functionality of the previous fip\_create is provided. 955 However, users are strongly encouraged to migrate to fiptool. 956 957 - To create a new FIP file, replace "fip\_create" with "fiptool create". 958 - To update a FIP file, replace "fip\_create" with "fiptool update". 959 - To dump the contents of a FIP file, replace "fip\_create --dump" 960 with "fiptool info". 961 962 Building FIP images with support for Trusted Board Boot 963 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 964 965 Trusted Board Boot primarily consists of the following two features: 966 967 - Image Authentication, described in `Trusted Board Boot`_, and 968 - Firmware Update, described in `Firmware Update`_ 969 970 The following steps should be followed to build FIP and (optionally) FWU\_FIP 971 images with support for these features: 972 973 #. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser 974 modules by checking out a recent version of the `mbed TLS Repository`_. It 975 is important to use a version that is compatible with TF and fixes any 976 known security vulnerabilities. See `mbed TLS Security Center`_ for more 977 information. The latest version of TF is tested with tag ``mbedtls-2.4.2``. 978 979 The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS 980 source files the modules depend upon. 981 ``include/drivers/auth/mbedtls/mbedtls_config.h`` contains the configuration 982 options required to build the mbed TLS sources. 983 984 Note that the mbed TLS library is licensed under the Apache version 2.0 985 license. Using mbed TLS source code will affect the licensing of 986 Trusted Firmware binaries that are built using this library. 987 988 #. To build the FIP image, ensure the following command line variables are set 989 while invoking ``make`` to build Trusted Firmware: 990 991 - ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>`` 992 - ``TRUSTED_BOARD_BOOT=1`` 993 - ``GENERATE_COT=1`` 994 995 In the case of ARM platforms, the location of the ROTPK hash must also be 996 specified at build time. Two locations are currently supported (see 997 ``ARM_ROTPK_LOCATION`` build option): 998 999 - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted 1000 root-key storage registers present in the platform. On Juno, this 1001 registers are read-only. On FVP Base and Cortex models, the registers 1002 are read-only, but the value can be specified using the command line 1003 option ``bp.trusted_key_storage.public_key`` when launching the model. 1004 On both Juno and FVP models, the default value corresponds to an 1005 ECDSA-SECP256R1 public key hash, whose private part is not currently 1006 available. 1007 1008 - ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded 1009 in the ARM platform port. The private/public RSA key pair may be 1010 found in ``plat/arm/board/common/rotpk``. 1011 1012 - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded 1013 in the ARM platform port. The private/public ECDSA key pair may be 1014 found in ``plat/arm/board/common/rotpk``. 1015 1016 Example of command line using RSA development keys: 1017 1018 :: 1019 1020 MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \ 1021 make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ 1022 ARM_ROTPK_LOCATION=devel_rsa \ 1023 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ 1024 BL33=<path-to>/<bl33_image> \ 1025 all fip 1026 1027 The result of this build will be the bl1.bin and the fip.bin binaries. This 1028 FIP will include the certificates corresponding to the Chain of Trust 1029 described in the TBBR-client document. These certificates can also be found 1030 in the output build directory. 1031 1032 #. The optional FWU\_FIP contains any additional images to be loaded from 1033 Non-Volatile storage during the `Firmware Update`_ process. To build the 1034 FWU\_FIP, any FWU images required by the platform must be specified on the 1035 command line. On ARM development platforms like Juno, these are: 1036 1037 - NS\_BL2U. The AP non-secure Firmware Updater image. 1038 - SCP\_BL2U. The SCP Firmware Update Configuration image. 1039 1040 Example of Juno command line for generating both ``fwu`` and ``fwu_fip`` 1041 targets using RSA development: 1042 1043 :: 1044 1045 MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \ 1046 make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ 1047 ARM_ROTPK_LOCATION=devel_rsa \ 1048 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ 1049 BL33=<path-to>/<bl33_image> \ 1050 SCP_BL2=<path-to>/<scp_bl2_image> \ 1051 SCP_BL2U=<path-to>/<scp_bl2u_image> \ 1052 NS_BL2U=<path-to>/<ns_bl2u_image> \ 1053 all fip fwu_fip 1054 1055 Note: The BL2U image will be built by default and added to the FWU\_FIP. 1056 The user may override this by adding ``BL2U=<path-to>/<bl2u_image>`` 1057 to the command line above. 1058 1059 Note: Building and installing the non-secure and SCP FWU images (NS\_BL1U, 1060 NS\_BL2U and SCP\_BL2U) is outside the scope of this document. 1061 1062 The result of this build will be bl1.bin, fip.bin and fwu\_fip.bin binaries. 1063 Both the FIP and FWU\_FIP will include the certificates corresponding to the 1064 Chain of Trust described in the TBBR-client document. These certificates 1065 can also be found in the output build directory. 1066 1067 Building the Certificate Generation Tool 1068 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1069 1070 The ``cert_create`` tool is built as part of the TF build process when the ``fip`` 1071 make target is specified and TBB is enabled (as described in the previous 1072 section), but it can also be built separately with the following command: 1073 1074 :: 1075 1076 make PLAT=<platform> [DEBUG=1] [V=1] certtool 1077 1078 For platforms that do not require their own IDs in certificate files, 1079 the generic 'cert\_create' tool can be built with the following command: 1080 1081 :: 1082 1083 make USE_TBBR_DEFS=1 [DEBUG=1] [V=1] certtool 1084 1085 ``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more 1086 verbose. The following command should be used to obtain help about the tool: 1087 1088 :: 1089 1090 ./tools/cert_create/cert_create -h 1091 1092 Building a FIP for Juno and FVP 1093 ------------------------------- 1094 1095 This section provides Juno and FVP specific instructions to build Trusted 1096 Firmware, obtain the additional required firmware, and pack it all together in 1097 a single FIP binary. It assumes that a `Linaro Release`_ has been installed. 1098 1099 Note: Pre-built binaries for AArch32 are available from Linaro Release 16.12 1100 onwards. Before that release, pre-built binaries are only available for AArch64. 1101 1102 Note: follow the full instructions for one platform before switching to a 1103 different one. Mixing instructions for different platforms may result in 1104 corrupted binaries. 1105 1106 #. Clean the working directory 1107 1108 :: 1109 1110 make realclean 1111 1112 #. Obtain SCP\_BL2 (Juno) and BL33 (all platforms) 1113 1114 Use the fiptool to extract the SCP\_BL2 and BL33 images from the FIP 1115 package included in the Linaro release: 1116 1117 :: 1118 1119 # Build the fiptool 1120 make [DEBUG=1] [V=1] fiptool 1121 1122 # Unpack firmware images from Linaro FIP 1123 ./tools/fiptool/fiptool unpack \ 1124 <path/to/linaro/release>/fip.bin 1125 1126 The unpack operation will result in a set of binary images extracted to the 1127 current working directory. The SCP\_BL2 image corresponds to 1128 ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``. 1129 1130 Note: the fiptool will complain if the images to be unpacked already 1131 exist in the current directory. If that is the case, either delete those 1132 files or use the ``--force`` option to overwrite. 1133 1134 Note for AArch32, the instructions below assume that nt-fw.bin is a custom 1135 Normal world boot loader that supports AArch32. 1136 1137 #. Build TF images and create a new FIP for FVP 1138 1139 :: 1140 1141 # AArch64 1142 make PLAT=fvp BL33=nt-fw.bin all fip 1143 1144 # AArch32 1145 make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip 1146 1147 #. Build TF images and create a new FIP for Juno 1148 1149 For AArch64: 1150 1151 Building for AArch64 on Juno simply requires the addition of ``SCP_BL2`` 1152 as a build parameter. 1153 1154 :: 1155 1156 make PLAT=juno all fip \ 1157 BL33=<path-to-juno-oe-uboot>/SOFTWARE/bl33-uboot.bin \ 1158 SCP_BL2=<path-to-juno-busybox-uboot>/SOFTWARE/scp_bl2.bin 1159 1160 For AArch32: 1161 1162 Hardware restrictions on Juno prevent cold reset into AArch32 execution mode, 1163 therefore BL1 and BL2 must be compiled for AArch64, and BL32 is compiled 1164 separately for AArch32. 1165 1166 - Before building BL32, the environment variable ``CROSS_COMPILE`` must point 1167 to the AArch32 Linaro cross compiler. 1168 1169 :: 1170 1171 export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf- 1172 1173 - Build BL32 in AArch32. 1174 1175 :: 1176 1177 make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \ 1178 RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32 1179 1180 - Before building BL1 and BL2, the environment variable ``CROSS_COMPILE`` 1181 must point to the AArch64 Linaro cross compiler. 1182 1183 :: 1184 1185 export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- 1186 1187 - The following parameters should be used to build BL1 and BL2 in AArch64 1188 and point to the BL32 file. 1189 1190 :: 1191 1192 make ARCH=aarch64 PLAT=juno LOAD_IMAGE_V2=1 JUNO_AARCH32_EL3_RUNTIME=1 \ 1193 BL33=<path-to-juno32-oe-uboot>/SOFTWARE/bl33-uboot.bin \ 1194 SCP_BL2=<path-to-juno32-oe-uboot>/SOFTWARE/scp_bl2.bin SPD=tspd \ 1195 BL32=<path-to-bl32>/bl32.bin all fip 1196 1197 The resulting BL1 and FIP images may be found in: 1198 1199 :: 1200 1201 # Juno 1202 ./build/juno/release/bl1.bin 1203 ./build/juno/release/fip.bin 1204 1205 # FVP 1206 ./build/fvp/release/bl1.bin 1207 ./build/fvp/release/fip.bin 1208 1209 1210 Booting Firmware Update images 1211 ------------------------------------- 1212 1213 When Firmware Update (FWU) is enabled there are at least 2 new images 1214 that have to be loaded, the Non-Secure FWU ROM (NS-BL1U), and the 1215 FWU FIP. 1216 1217 Juno 1218 ~~~~ 1219 1220 The new images must be programmed in flash memory by adding 1221 an entry in the ``SITE1/HBI0262x/images.txt`` configuration file 1222 on the Juno SD card (where ``x`` depends on the revision of the Juno board). 1223 Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory 1224 programming" for more information. User should ensure these do not 1225 overlap with any other entries in the file. 1226 1227 :: 1228 1229 NOR10UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE 1230 NOR10ADDRESS: 0x00400000 ;Image Flash Address [ns_bl2u_base_address] 1231 NOR10FILE: \SOFTWARE\fwu_fip.bin ;Image File Name 1232 NOR10LOAD: 00000000 ;Image Load Address 1233 NOR10ENTRY: 00000000 ;Image Entry Point 1234 1235 NOR11UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE 1236 NOR11ADDRESS: 0x03EB8000 ;Image Flash Address [ns_bl1u_base_address] 1237 NOR11FILE: \SOFTWARE\ns_bl1u.bin ;Image File Name 1238 NOR11LOAD: 00000000 ;Image Load Address 1239 1240 The address ns_bl1u_base_address is the value of NS_BL1U_BASE - 0x8000000. 1241 In the same way, the address ns_bl2u_base_address is the value of 1242 NS_BL2U_BASE - 0x8000000. 1243 1244 FVP 1245 ~~~ 1246 1247 The additional fip images must be loaded with: 1248 1249 :: 1250 1251 --data cluster0.cpu0="<path_to>/ns_bl1u.bin"@0x0beb8000 [ns_bl1u_base_address] 1252 --data cluster0.cpu0="<path_to>/fwu_fip.bin"@0x08400000 [ns_bl2u_base_address] 1253 1254 The address ns_bl1u_base_address is the value of NS_BL1U_BASE. 1255 In the same way, the address ns_bl2u_base_address is the value of 1256 NS_BL2U_BASE. 1257 1258 1259 EL3 payloads alternative boot flow 1260 ---------------------------------- 1261 1262 On a pre-production system, the ability to execute arbitrary, bare-metal code at 1263 the highest exception level is required. It allows full, direct access to the 1264 hardware, for example to run silicon soak tests. 1265 1266 Although it is possible to implement some baremetal secure firmware from 1267 scratch, this is a complex task on some platforms, depending on the level of 1268 configuration required to put the system in the expected state. 1269 1270 Rather than booting a baremetal application, a possible compromise is to boot 1271 ``EL3 payloads`` through the Trusted Firmware instead. This is implemented as an 1272 alternative boot flow, where a modified BL2 boots an EL3 payload, instead of 1273 loading the other BL images and passing control to BL31. It reduces the 1274 complexity of developing EL3 baremetal code by: 1275 1276 - putting the system into a known architectural state; 1277 - taking care of platform secure world initialization; 1278 - loading the SCP\_BL2 image if required by the platform. 1279 1280 When booting an EL3 payload on ARM standard platforms, the configuration of the 1281 TrustZone controller is simplified such that only region 0 is enabled and is 1282 configured to permit secure access only. This gives full access to the whole 1283 DRAM to the EL3 payload. 1284 1285 The system is left in the same state as when entering BL31 in the default boot 1286 flow. In particular: 1287 1288 - Running in EL3; 1289 - Current state is AArch64; 1290 - Little-endian data access; 1291 - All exceptions disabled; 1292 - MMU disabled; 1293 - Caches disabled. 1294 1295 Booting an EL3 payload 1296 ~~~~~~~~~~~~~~~~~~~~~~ 1297 1298 The EL3 payload image is a standalone image and is not part of the FIP. It is 1299 not loaded by the Trusted Firmware. Therefore, there are 2 possible scenarios: 1300 1301 - The EL3 payload may reside in non-volatile memory (NVM) and execute in 1302 place. In this case, booting it is just a matter of specifying the right 1303 address in NVM through ``EL3_PAYLOAD_BASE`` when building the TF. 1304 1305 - The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at 1306 run-time. 1307 1308 To help in the latter scenario, the ``SPIN_ON_BL1_EXIT=1`` build option can be 1309 used. The infinite loop that it introduces in BL1 stops execution at the right 1310 moment for a debugger to take control of the target and load the payload (for 1311 example, over JTAG). 1312 1313 It is expected that this loading method will work in most cases, as a debugger 1314 connection is usually available in a pre-production system. The user is free to 1315 use any other platform-specific mechanism to load the EL3 payload, though. 1316 1317 Booting an EL3 payload on FVP 1318 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1319 1320 The EL3 payloads boot flow requires the CPU's mailbox to be cleared at reset for 1321 the secondary CPUs holding pen to work properly. Unfortunately, its reset value 1322 is undefined on the FVP platform and the FVP platform code doesn't clear it. 1323 Therefore, one must modify the way the model is normally invoked in order to 1324 clear the mailbox at start-up. 1325 1326 One way to do that is to create an 8-byte file containing all zero bytes using 1327 the following command: 1328 1329 :: 1330 1331 dd if=/dev/zero of=mailbox.dat bs=1 count=8 1332 1333 and pre-load it into the FVP memory at the mailbox address (i.e. ``0x04000000``) 1334 using the following model parameters: 1335 1336 :: 1337 1338 --data cluster0.cpu0=mailbox.dat@0x04000000 [Base FVPs] 1339 --data=mailbox.dat@0x04000000 [Foundation FVP] 1340 1341 To provide the model with the EL3 payload image, the following methods may be 1342 used: 1343 1344 #. If the EL3 payload is able to execute in place, it may be programmed into 1345 flash memory. On Base Cortex and AEM FVPs, the following model parameter 1346 loads it at the base address of the NOR FLASH1 (the NOR FLASH0 is already 1347 used for the FIP): 1348 1349 :: 1350 1351 -C bp.flashloader1.fname="/path/to/el3-payload" 1352 1353 On Foundation FVP, there is no flash loader component and the EL3 payload 1354 may be programmed anywhere in flash using method 3 below. 1355 1356 #. When using the ``SPIN_ON_BL1_EXIT=1`` loading method, the following DS-5 1357 command may be used to load the EL3 payload ELF image over JTAG: 1358 1359 :: 1360 1361 load /path/to/el3-payload.elf 1362 1363 #. The EL3 payload may be pre-loaded in volatile memory using the following 1364 model parameters: 1365 1366 :: 1367 1368 --data cluster0.cpu0="/path/to/el3-payload"@address [Base FVPs] 1369 --data="/path/to/el3-payload"@address [Foundation FVP] 1370 1371 The address provided to the FVP must match the ``EL3_PAYLOAD_BASE`` address 1372 used when building the Trusted Firmware. 1373 1374 Booting an EL3 payload on Juno 1375 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1376 1377 If the EL3 payload is able to execute in place, it may be programmed in flash 1378 memory by adding an entry in the ``SITE1/HBI0262x/images.txt`` configuration file 1379 on the Juno SD card (where ``x`` depends on the revision of the Juno board). 1380 Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory 1381 programming" for more information. 1382 1383 Alternatively, the same DS-5 command mentioned in the FVP section above can 1384 be used to load the EL3 payload's ELF file over JTAG on Juno. 1385 1386 Preloaded BL33 alternative boot flow 1387 ------------------------------------ 1388 1389 Some platforms have the ability to preload BL33 into memory instead of relying 1390 on Trusted Firmware to load it. This may simplify packaging of the normal world 1391 code and improve performance in a development environment. When secure world 1392 cold boot is complete, Trusted Firmware simply jumps to a BL33 base address 1393 provided at build time. 1394 1395 For this option to be used, the ``PRELOADED_BL33_BASE`` build option has to be 1396 used when compiling the Trusted Firmware. For example, the following command 1397 will create a FIP without a BL33 and prepare to jump to a BL33 image loaded at 1398 address 0x80000000: 1399 1400 :: 1401 1402 make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip 1403 1404 Boot of a preloaded bootwrapped kernel image on Base FVP 1405 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1406 1407 The following example uses the AArch64 boot wrapper. This simplifies normal 1408 world booting while also making use of TF features. It can be obtained from its 1409 repository with: 1410 1411 :: 1412 1413 git clone git://git.kernel.org/pub/scm/linux/kernel/git/mark/boot-wrapper-aarch64.git 1414 1415 After compiling it, an ELF file is generated. It can be loaded with the 1416 following command: 1417 1418 :: 1419 1420 <path-to>/FVP_Base_AEMv8A-AEMv8A \ 1421 -C bp.secureflashloader.fname=bl1.bin \ 1422 -C bp.flashloader0.fname=fip.bin \ 1423 -a cluster0.cpu0=<bootwrapped-kernel.elf> \ 1424 --start cluster0.cpu0=0x0 1425 1426 The ``-a cluster0.cpu0=<bootwrapped-kernel.elf>`` option loads the ELF file. It 1427 also sets the PC register to the ELF entry point address, which is not the 1428 desired behaviour, so the ``--start cluster0.cpu0=0x0`` option forces the PC back 1429 to 0x0 (the BL1 entry point address) on CPU #0. The ``PRELOADED_BL33_BASE`` define 1430 used when compiling the FIP must match the ELF entry point. 1431 1432 Boot of a preloaded bootwrapped kernel image on Juno 1433 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1434 1435 The procedure to obtain and compile the boot wrapper is very similar to the case 1436 of the FVP. The execution must be stopped at the end of bl2\_main(), and the 1437 loading method explained above in the EL3 payload boot flow section may be used 1438 to load the ELF file over JTAG on Juno. 1439 1440 Running the software on FVP 1441 --------------------------- 1442 1443 The latest version of the AArch64 build of ARM Trusted Firmware has been tested 1444 on the following ARM FVPs (64-bit host machine only). 1445 1446 NOTE: Unless otherwise stated, the model version is Version 11.1 Build 11.1.22. 1447 1448 - ``Foundation_Platform`` 1449 - ``FVP_Base_AEMv8A-AEMv8A`` (Version 8.7, Build 0.8.8702) 1450 - ``FVP_Base_Cortex-A35x4`` 1451 - ``FVP_Base_Cortex-A53x4`` 1452 - ``FVP_Base_Cortex-A57x4-A53x4`` 1453 - ``FVP_Base_Cortex-A57x4`` 1454 - ``FVP_Base_Cortex-A72x4-A53x4`` 1455 - ``FVP_Base_Cortex-A72x4`` 1456 - ``FVP_Base_Cortex-A73x4-A53x4`` 1457 - ``FVP_Base_Cortex-A73x4`` 1458 1459 The latest version of the AArch32 build of ARM Trusted Firmware has been tested 1460 on the following ARM FVPs (64-bit host machine only). 1461 1462 - ``FVP_Base_AEMv8A-AEMv8A`` (Version 8.7, Build 0.8.8702) 1463 - ``FVP_Base_Cortex-A32x4`` 1464 1465 NOTE: The build numbers quoted above are those reported by launching the FVP 1466 with the ``--version`` parameter. 1467 1468 NOTE: Linaro provides a ramdisk image in prebuilt FVP configurations and full 1469 file systems that can be downloaded separately. To run an FVP with a virtio 1470 file system image an additional FVP configuration option 1471 ``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be 1472 used. 1473 1474 NOTE: The software will not work on Version 1.0 of the Foundation FVP. 1475 The commands below would report an ``unhandled argument`` error in this case. 1476 1477 NOTE: FVPs can be launched with ``--cadi-server`` option such that a 1478 CADI-compliant debugger (for example, ARM DS-5) can connect to and control its 1479 execution. 1480 1481 NOTE: Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202 1482 the internal synchronisation timings changed compared to older versions of the 1483 models. The models can be launched with ``-Q 100`` option if they are required 1484 to match the run time characteristics of the older versions. 1485 1486 The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be 1487 downloaded for free from `ARM's website`_. 1488 1489 The Cortex-A models listed above are also available to download from 1490 `ARM's website`_. 1491 1492 Please refer to the FVP documentation for a detailed description of the model 1493 parameter options. A brief description of the important ones that affect the ARM 1494 Trusted Firmware and normal world software behavior is provided below. 1495 1496 Obtaining the Flattened Device Trees 1497 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1498 1499 Depending on the FVP configuration and Linux configuration used, different 1500 FDT files are required. FDTs for the Foundation and Base FVPs can be found in 1501 the Trusted Firmware source directory under ``fdts/``. The Foundation FVP has a 1502 subset of the Base FVP components. For example, the Foundation FVP lacks CLCD 1503 and MMC support, and has only one CPU cluster. 1504 1505 Note: It is not recommended to use the FDTs built along the kernel because not 1506 all FDTs are available from there. 1507 1508 - ``fvp-base-gicv2-psci.dtb`` 1509 1510 For use with both AEMv8 and Cortex-A57-A53 Base FVPs with 1511 Base memory map configuration. 1512 1513 - ``fvp-base-gicv2-psci-aarch32.dtb`` 1514 1515 For use with AEMv8 and Cortex-A32 Base FVPs running Linux in AArch32 state 1516 with Base memory map configuration. 1517 1518 - ``fvp-base-gicv3-psci.dtb`` 1519 1520 (Default) For use with both AEMv8 and Cortex-A57-A53 Base FVPs with Base 1521 memory map configuration and Linux GICv3 support. 1522 1523 - ``fvp-base-gicv3-psci-aarch32.dtb`` 1524 1525 For use with AEMv8 and Cortex-A32 Base FVPs running Linux in AArch32 state 1526 with Base memory map configuration and Linux GICv3 support. 1527 1528 - ``fvp-foundation-gicv2-psci.dtb`` 1529 1530 For use with Foundation FVP with Base memory map configuration. 1531 1532 - ``fvp-foundation-gicv3-psci.dtb`` 1533 1534 (Default) For use with Foundation FVP with Base memory map configuration 1535 and Linux GICv3 support. 1536 1537 Running on the Foundation FVP with reset to BL1 entrypoint 1538 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1539 1540 The following ``Foundation_Platform`` parameters should be used to boot Linux with 1541 4 CPUs using the AArch64 build of ARM Trusted Firmware. 1542 1543 :: 1544 1545 <path-to>/Foundation_Platform \ 1546 --cores=4 \ 1547 --secure-memory \ 1548 --visualization \ 1549 --gicv3 \ 1550 --data="<path-to>/<bl1-binary>"@0x0 \ 1551 --data="<path-to>/<FIP-binary>"@0x08000000 \ 1552 --data="<path-to>/<fdt>"@0x82000000 \ 1553 --data="<path-to>/<kernel-binary>"@0x80080000 \ 1554 --data="<path-to>/<ramdisk-binary>"@0x84000000 1555 1556 Notes: 1557 1558 - BL1 is loaded at the start of the Trusted ROM. 1559 - The Firmware Image Package is loaded at the start of NOR FLASH0. 1560 - The Linux kernel image and device tree are loaded in DRAM. 1561 - The default use-case for the Foundation FVP is to use the ``--gicv3`` option 1562 and enable the GICv3 device in the model. Note that without this option, 1563 the Foundation FVP defaults to legacy (Versatile Express) memory map which 1564 is not supported by ARM Trusted Firmware. 1565 1566 Running on the AEMv8 Base FVP with reset to BL1 entrypoint 1567 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1568 1569 The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux 1570 with 8 CPUs using the AArch64 build of ARM Trusted Firmware. 1571 1572 :: 1573 1574 <path-to>/FVP_Base_AEMv8A-AEMv8A \ 1575 -C pctl.startup=0.0.0.0 \ 1576 -C bp.secure_memory=1 \ 1577 -C bp.tzc_400.diagnostics=1 \ 1578 -C cluster0.NUM_CORES=4 \ 1579 -C cluster1.NUM_CORES=4 \ 1580 -C cache_state_modelled=1 \ 1581 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ 1582 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ 1583 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ 1584 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ 1585 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 1586 1587 Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint 1588 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1589 1590 The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux 1591 with 8 CPUs using the AArch32 build of ARM Trusted Firmware. 1592 1593 :: 1594 1595 <path-to>/FVP_Base_AEMv8A-AEMv8A \ 1596 -C pctl.startup=0.0.0.0 \ 1597 -C bp.secure_memory=1 \ 1598 -C bp.tzc_400.diagnostics=1 \ 1599 -C cluster0.NUM_CORES=4 \ 1600 -C cluster1.NUM_CORES=4 \ 1601 -C cache_state_modelled=1 \ 1602 -C cluster0.cpu0.CONFIG64=0 \ 1603 -C cluster0.cpu1.CONFIG64=0 \ 1604 -C cluster0.cpu2.CONFIG64=0 \ 1605 -C cluster0.cpu3.CONFIG64=0 \ 1606 -C cluster1.cpu0.CONFIG64=0 \ 1607 -C cluster1.cpu1.CONFIG64=0 \ 1608 -C cluster1.cpu2.CONFIG64=0 \ 1609 -C cluster1.cpu3.CONFIG64=0 \ 1610 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ 1611 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ 1612 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ 1613 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ 1614 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 1615 1616 Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint 1617 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1618 1619 The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to 1620 boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware. 1621 1622 :: 1623 1624 <path-to>/FVP_Base_Cortex-A57x4-A53x4 \ 1625 -C pctl.startup=0.0.0.0 \ 1626 -C bp.secure_memory=1 \ 1627 -C bp.tzc_400.diagnostics=1 \ 1628 -C cache_state_modelled=1 \ 1629 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ 1630 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ 1631 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ 1632 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ 1633 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 1634 1635 Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint 1636 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1637 1638 The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to 1639 boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware. 1640 1641 :: 1642 1643 <path-to>/FVP_Base_Cortex-A32x4 \ 1644 -C pctl.startup=0.0.0.0 \ 1645 -C bp.secure_memory=1 \ 1646 -C bp.tzc_400.diagnostics=1 \ 1647 -C cache_state_modelled=1 \ 1648 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ 1649 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ 1650 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ 1651 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ 1652 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 1653 1654 Running on the AEMv8 Base FVP with reset to BL31 entrypoint 1655 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1656 1657 The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux 1658 with 8 CPUs using the AArch64 build of ARM Trusted Firmware. 1659 1660 :: 1661 1662 <path-to>/FVP_Base_AEMv8A-AEMv8A \ 1663 -C pctl.startup=0.0.0.0 \ 1664 -C bp.secure_memory=1 \ 1665 -C bp.tzc_400.diagnostics=1 \ 1666 -C cluster0.NUM_CORES=4 \ 1667 -C cluster1.NUM_CORES=4 \ 1668 -C cache_state_modelled=1 \ 1669 -C cluster0.cpu0.RVBAR=0x04020000 \ 1670 -C cluster0.cpu1.RVBAR=0x04020000 \ 1671 -C cluster0.cpu2.RVBAR=0x04020000 \ 1672 -C cluster0.cpu3.RVBAR=0x04020000 \ 1673 -C cluster1.cpu0.RVBAR=0x04020000 \ 1674 -C cluster1.cpu1.RVBAR=0x04020000 \ 1675 -C cluster1.cpu2.RVBAR=0x04020000 \ 1676 -C cluster1.cpu3.RVBAR=0x04020000 \ 1677 --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04020000 \ 1678 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \ 1679 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ 1680 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ 1681 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ 1682 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 1683 1684 Notes: 1685 1686 - Since a FIP is not loaded when using BL31 as reset entrypoint, the 1687 ``--data="<path-to><bl31|bl32|bl33-binary>"@<base-address-of-binary>`` 1688 parameter is needed to load the individual bootloader images in memory. 1689 BL32 image is only needed if BL31 has been built to expect a Secure-EL1 1690 Payload. 1691 1692 - The ``-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>`` parameter, where 1693 X and Y are the cluster and CPU numbers respectively, is used to set the 1694 reset vector for each core. 1695 1696 - Changing the default value of ``ARM_TSP_RAM_LOCATION`` will also require 1697 changing the value of 1698 ``--data="<path-to><bl32-binary>"@<base-address-of-bl32>`` to the new value of 1699 ``BL32_BASE``. 1700 1701 Running on the AEMv8 Base FVP (AArch32) with reset to SP\_MIN entrypoint 1702 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1703 1704 The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux 1705 with 8 CPUs using the AArch32 build of ARM Trusted Firmware. 1706 1707 :: 1708 1709 <path-to>/FVP_Base_AEMv8A-AEMv8A \ 1710 -C pctl.startup=0.0.0.0 \ 1711 -C bp.secure_memory=1 \ 1712 -C bp.tzc_400.diagnostics=1 \ 1713 -C cluster0.NUM_CORES=4 \ 1714 -C cluster1.NUM_CORES=4 \ 1715 -C cache_state_modelled=1 \ 1716 -C cluster0.cpu0.CONFIG64=0 \ 1717 -C cluster0.cpu1.CONFIG64=0 \ 1718 -C cluster0.cpu2.CONFIG64=0 \ 1719 -C cluster0.cpu3.CONFIG64=0 \ 1720 -C cluster1.cpu0.CONFIG64=0 \ 1721 -C cluster1.cpu1.CONFIG64=0 \ 1722 -C cluster1.cpu2.CONFIG64=0 \ 1723 -C cluster1.cpu3.CONFIG64=0 \ 1724 -C cluster0.cpu0.RVBAR=0x04001000 \ 1725 -C cluster0.cpu1.RVBAR=0x04001000 \ 1726 -C cluster0.cpu2.RVBAR=0x04001000 \ 1727 -C cluster0.cpu3.RVBAR=0x04001000 \ 1728 -C cluster1.cpu0.RVBAR=0x04001000 \ 1729 -C cluster1.cpu1.RVBAR=0x04001000 \ 1730 -C cluster1.cpu2.RVBAR=0x04001000 \ 1731 -C cluster1.cpu3.RVBAR=0x04001000 \ 1732 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \ 1733 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ 1734 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ 1735 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ 1736 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 1737 1738 Note: The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``. 1739 It should match the address programmed into the RVBAR register as well. 1740 1741 Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint 1742 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1743 1744 The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to 1745 boot Linux with 8 CPUs using the AArch64 build of ARM Trusted Firmware. 1746 1747 :: 1748 1749 <path-to>/FVP_Base_Cortex-A57x4-A53x4 \ 1750 -C pctl.startup=0.0.0.0 \ 1751 -C bp.secure_memory=1 \ 1752 -C bp.tzc_400.diagnostics=1 \ 1753 -C cache_state_modelled=1 \ 1754 -C cluster0.cpu0.RVBARADDR=0x04020000 \ 1755 -C cluster0.cpu1.RVBARADDR=0x04020000 \ 1756 -C cluster0.cpu2.RVBARADDR=0x04020000 \ 1757 -C cluster0.cpu3.RVBARADDR=0x04020000 \ 1758 -C cluster1.cpu0.RVBARADDR=0x04020000 \ 1759 -C cluster1.cpu1.RVBARADDR=0x04020000 \ 1760 -C cluster1.cpu2.RVBARADDR=0x04020000 \ 1761 -C cluster1.cpu3.RVBARADDR=0x04020000 \ 1762 --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04020000 \ 1763 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \ 1764 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ 1765 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ 1766 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ 1767 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 1768 1769 Running on the Cortex-A32 Base FVP (AArch32) with reset to SP\_MIN entrypoint 1770 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1771 1772 The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to 1773 boot Linux with 4 CPUs using the AArch32 build of ARM Trusted Firmware. 1774 1775 :: 1776 1777 <path-to>/FVP_Base_Cortex-A32x4 \ 1778 -C pctl.startup=0.0.0.0 \ 1779 -C bp.secure_memory=1 \ 1780 -C bp.tzc_400.diagnostics=1 \ 1781 -C cache_state_modelled=1 \ 1782 -C cluster0.cpu0.RVBARADDR=0x04001000 \ 1783 -C cluster0.cpu1.RVBARADDR=0x04001000 \ 1784 -C cluster0.cpu2.RVBARADDR=0x04001000 \ 1785 -C cluster0.cpu3.RVBARADDR=0x04001000 \ 1786 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \ 1787 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ 1788 --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \ 1789 --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ 1790 --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 1791 1792 Running the software on Juno 1793 ---------------------------- 1794 1795 This version of the ARM Trusted Firmware has been tested on variants r0, r1 and 1796 r2 of Juno. 1797 1798 To execute the software stack on Juno, the version of the Juno board recovery 1799 image indicated in the `Linaro Release Notes`_ must be installed. If you have an 1800 earlier version installed or are unsure which version is installed, please 1801 re-install the recovery image by following the 1802 `Instructions for using Linaro's deliverables on Juno`_. 1803 1804 Preparing Trusted Firmware images 1805 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1806 1807 After building Trusted Firmware, the files ``bl1.bin`` and ``fip.bin`` need copying 1808 to the ``SOFTWARE/`` directory of the Juno SD card. 1809 1810 Other Juno software information 1811 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1812 1813 Please visit the `ARM Platforms Portal`_ to get support and obtain any other Juno 1814 software information. Please also refer to the `Juno Getting Started Guide`_ to 1815 get more detailed information about the Juno ARM development platform and how to 1816 configure it. 1817 1818 Testing SYSTEM SUSPEND on Juno 1819 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1820 1821 The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend 1822 to RAM. For more details refer to section 5.16 of `PSCI`_. To test system suspend 1823 on Juno, at the linux shell prompt, issue the following command: 1824 1825 :: 1826 1827 echo +10 > /sys/class/rtc/rtc0/wakealarm 1828 echo -n mem > /sys/power/state 1829 1830 The Juno board should suspend to RAM and then wakeup after 10 seconds due to 1831 wakeup interrupt from RTC. 1832 1833 -------------- 1834 1835 *Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.* 1836 1837 .. _Linaro: `Linaro Release Notes`_ 1838 .. _Linaro Release: `Linaro Release Notes`_ 1839 .. _Linaro Release Notes: https://community.arm.com/tools/dev-platforms/b/documents/posts/linaro-release-notes-deprecated 1840 .. _Linaro Release 17.04: https://community.arm.com/tools/dev-platforms/b/documents/posts/linaro-release-notes-deprecated#LinaroRelease17.04 1841 .. _Linaro instructions: https://community.arm.com/dev-platforms/b/documents/posts/instructions-for-using-the-linaro-software-deliverables 1842 .. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/b/documents/posts/using-linaros-deliverables-on-juno 1843 .. _ARM Platforms Portal: https://community.arm.com/dev-platforms/ 1844 .. _Development Studio 5 (DS-5): http://www.arm.com/products/tools/software-tools/ds-5/index.php 1845 .. _Dia: https://wiki.gnome.org/Apps/Dia/Download 1846 .. _here: psci-lib-integration-guide.rst 1847 .. _Trusted Board Boot: trusted-board-boot.rst 1848 .. _Secure-EL1 Payloads and Dispatchers: firmware-design.rst#user-content-secure-el1-payloads-and-dispatchers 1849 .. _Firmware Update: firmware-update.rst 1850 .. _Firmware Design: firmware-design.rst 1851 .. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git 1852 .. _mbed TLS Security Center: https://tls.mbed.org/security 1853 .. _ARM's website: `FVP models`_ 1854 .. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms 1855 .. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf 1856 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf 1857
