1 ARM Trusted Firmware User Guide 2 =============================== 3 4 Contents : 5 6 1. [Introduction](#1--introduction) 7 2. [Host machine requirements](#2--host-machine-requirements) 8 3. [Tools](#3--tools) 9 4. [Building the Trusted Firmware](#4--building-the-trusted-firmware) 10 5. [Obtaining the normal world software](#5--obtaining-the-normal-world-software) 11 6. [Preparing the images to run on FVP](#6--preparing-the-images-to-run-on-fvp) 12 7. [Running the software on FVP](#7--running-the-software-on-fvp) 13 8. [Running the software on Juno](#8--running-the-software-on-juno) 14 15 16 1. Introduction 17 ---------------- 18 This document describes how to build ARM Trusted Firmware and run it with a 19 tested set of other software components using defined configurations on the Juno 20 ARM development platform and ARM Fixed Virtual Platform (FVP) models. It is 21 possible to use other software components, configurations and platforms but that 22 is outside the scope of this document. 23 24 This document should be used in conjunction with the [Firmware Design]. 25 26 27 2. Host machine requirements 28 ----------------------------- 29 30 The minimum recommended machine specification for building the software and 31 running the FVP models is a dual-core processor running at 2GHz with 12GB of 32 RAM. For best performance, use a machine with a quad-core processor running at 33 2.6GHz with 16GB of RAM. 34 35 The software has been tested on Ubuntu 12.04.04 (64-bit). Packages used 36 for building the software were installed from that distribution unless 37 otherwise specified. 38 39 40 3. Tools 41 --------- 42 43 The following tools are required to use the ARM Trusted Firmware: 44 45 * `git` package to obtain source code. 46 47 * `build-essential`, `uuid-dev` and `iasl` packages for building UEFI and the 48 Firmware Image Package (FIP) tool. 49 50 * `bc` and `ncurses-dev` packages for building Linux. 51 52 * `device-tree-compiler` package for building the Flattened Device Tree (FDT) 53 source files (`.dts` files) provided with this software. 54 55 * Baremetal GNU GCC tools. Verified packages can be downloaded from [Linaro] 56 [Linaro Toolchain]. The rest of this document assumes that the 57 `gcc-linaro-aarch64-none-elf-4.9-2014.07_linux.tar.xz` tools are used. 58 59 wget http://releases.linaro.org/14.07/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.9-2014.07_linux.tar.xz 60 tar -xf gcc-linaro-aarch64-none-elf-4.9-2014.07_linux.tar.xz 61 62 * (Optional) For debugging, ARM [Development Studio 5 (DS-5)][DS-5] v5.20. 63 64 65 4. Building the Trusted Firmware 66 --------------------------------- 67 68 To build the Trusted Firmware images, follow these steps: 69 70 1. Clone the ARM Trusted Firmware repository from GitHub: 71 72 git clone https://github.com/ARM-software/arm-trusted-firmware.git 73 74 2. Change to the trusted firmware directory: 75 76 cd arm-trusted-firmware 77 78 3. Set the compiler path, specify a Non-trusted Firmware image (BL3-3) and 79 a valid platform, and then build: 80 81 CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \ 82 BL33=<path-to>/<bl33_image> \ 83 make PLAT=<platform> all fip 84 85 If `PLAT` is not specified, `fvp` is assumed by default. See the "Summary of 86 build options" for more information on available build options. 87 88 The BL3-3 image corresponds to the software that is executed after switching 89 to the non-secure world. UEFI can be used as the BL3-3 image. Refer to the 90 "Obtaining the normal world software" section below. 91 92 The TSP (Test Secure Payload), corresponding to the BL3-2 image, is not 93 compiled in by default. Refer to the "Building the Test Secure Payload" 94 section below. 95 96 By default this produces a release version of the build. To produce a debug 97 version instead, refer to the "Debugging options" section below. 98 99 The build process creates products in a `build` directory tree, building 100 the objects and binaries for each boot loader stage in separate 101 sub-directories. The following boot loader binary files are created from 102 the corresponding ELF files: 103 104 * `build/<platform>/<build-type>/bl1.bin` 105 * `build/<platform>/<build-type>/bl2.bin` 106 * `build/<platform>/<build-type>/bl31.bin` 107 108 where `<platform>` is the name of the chosen platform and `<build-type>` is 109 either `debug` or `release`. A Firmare Image Package (FIP) will be created 110 as part of the build. It contains all boot loader images except for 111 `bl1.bin`. 112 113 * `build/<platform>/<build-type>/fip.bin` 114 115 For more information on FIPs, see the "Firmware Image Package" section in 116 the [Firmware Design]. 117 118 4. (Optional) Some platforms may require a BL3-0 image to boot. This image can 119 be included in the FIP when building the Trusted Firmware by specifying the 120 `BL30` build option: 121 122 BL30=<path-to>/<bl30_image> 123 124 5. Output binary files `bl1.bin` and `fip.bin` are both required to boot the 125 system. How these files are used is platform specific. Refer to the 126 platform documentation on how to use the firmware images. 127 128 6. (Optional) Build products for a specific build variant can be removed using: 129 130 make DEBUG=<D> PLAT=<platform> clean 131 132 ... where `<D>` is `0` or `1`, as specified when building. 133 134 The build tree can be removed completely using: 135 136 make realclean 137 138 7. (Optional) Path to binary for certain BL stages (BL2, BL3-1 and BL3-2) can be 139 provided by specifying the BLx=<path-to>/<blx_image> where BLx is the BL stage. 140 This will bypass the build of the BL component from source, but will include 141 the specified binary in the final FIP image. Please note that BL3-2 will be 142 included in the build, only if the `SPD` build option is specified. 143 144 For example, specifying BL2=<path-to>/<bl2_image> in the build option, will 145 skip compilation of BL2 source in trusted firmware, but include the BL2 146 binary specified in the final FIP image. 147 148 ### Summary of build options 149 150 ARM Trusted Firmware build system supports the following build options. Unless 151 mentioned otherwise, these options are expected to be specified at the build 152 command line and are not to be modified in any component makefiles. Note that 153 the build system doesn't track dependency for build options. Therefore, if any 154 of the build options are changed from a previous build, a clean build must be 155 performed. 156 157 #### Common build options 158 159 * `BL30`: Path to BL3-0 image in the host file system. This image is optional. 160 If a BL3-0 image is present then this option must be passed for the `fip` 161 target. 162 163 * `BL33`: Path to BL3-3 image in the host file system. This is mandatory for 164 `fip` target in case the BL2 from ARM Trusted Firmware is used. 165 166 * `BL2`: This is an optional build option which specifies the path to BL2 167 image for the `fip` target. In this case, the BL2 in the ARM Trusted 168 Firmware will not be built. 169 170 * `BL31`: This is an optional build option which specifies the path to 171 BL3-1 image for the `fip` target. In this case, the BL3-1 in the ARM 172 Trusted Firmware will not be built. 173 174 * `BL32`: This is an optional build option which specifies the path to 175 BL3-2 image for the `fip` target. In this case, the BL3-2 in the ARM 176 Trusted Firmware will not be built. 177 178 * `FIP_NAME`: This is an optional build option which specifies the FIP 179 filename for the `fip` target. Default is `fip.bin`. 180 181 * `CROSS_COMPILE`: Prefix to toolchain binaries. Please refer to examples in 182 this document for usage. 183 184 * `DEBUG`: Chooses between a debug and release build. It can take either 0 185 (release) or 1 (debug) as values. 0 is the default. 186 187 * `LOG_LEVEL`: Chooses the log level, which controls the amount of console log 188 output compiled into the build. This should be one of the following: 189 190 0 (LOG_LEVEL_NONE) 191 10 (LOG_LEVEL_NOTICE) 192 20 (LOG_LEVEL_ERROR) 193 30 (LOG_LEVEL_WARNING) 194 40 (LOG_LEVEL_INFO) 195 50 (LOG_LEVEL_VERBOSE) 196 197 All log output up to and including the log level is compiled into the build. 198 The default value is 40 in debug builds and 20 in release builds. 199 200 * `NS_TIMER_SWITCH`: Enable save and restore for non-secure timer register 201 contents upon world switch. It can take either 0 (don't save and restore) or 202 1 (do save and restore). 0 is the default. An SPD may set this to 1 if it 203 wants the timer registers to be saved and restored. 204 205 * `PLAT`: Choose a platform to build ARM Trusted Firmware for. The chosen 206 platform name must be the name of one of the directories under the `plat/` 207 directory other than `common`. 208 209 * `SPD`: Choose a Secure Payload Dispatcher component to be built into the 210 Trusted Firmware. The value should be the path to the directory containing 211 the SPD source, relative to `services/spd/`; the directory is expected to 212 contain a makefile called `<spd-value>.mk`. 213 214 * `V`: Verbose build. If assigned anything other than 0, the build commands 215 are printed. Default is 0. 216 217 * `ARM_GIC_ARCH`: Choice of ARM GIC architecture version used by the ARM GIC 218 driver for implementing the platform GIC API. This API is used 219 by the interrupt management framework. Default is 2 (that is, version 2.0). 220 221 * `IMF_READ_INTERRUPT_ID`: Boolean flag used by the interrupt management 222 framework to enable passing of the interrupt id to its handler. The id is 223 read using a platform GIC API. `INTR_ID_UNAVAILABLE` is passed instead if 224 this option set to 0. Default is 0. 225 226 * `RESET_TO_BL31`: Enable BL3-1 entrypoint as the CPU reset vector instead 227 of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 228 entrypoint) or 1 (CPU reset to BL3-1 entrypoint). 229 The default value is 0. 230 231 * `CRASH_REPORTING`: A non-zero value enables a console dump of processor 232 register state when an unexpected exception occurs during execution of 233 BL3-1. This option defaults to the value of `DEBUG` - i.e. by default 234 this is only enabled for a debug build of the firmware. 235 236 * `ASM_ASSERTION`: This flag determines whether the assertion checks within 237 assembly source files are enabled or not. This option defaults to the 238 value of `DEBUG` - that is, by default this is only enabled for a debug 239 build of the firmware. 240 241 * `TSP_INIT_ASYNC`: Choose BL3-2 initialization method as asynchronous or 242 synchronous, (see "Initializing a BL3-2 Image" section in [Firmware 243 Design]). It can take the value 0 (BL3-2 is initialized using 244 synchronous method) or 1 (BL3-2 is initialized using asynchronous method). 245 Default is 0. 246 247 * `USE_COHERENT_MEM`: This flag determines whether to include the coherent 248 memory region in the BL memory map or not (see "Use of Coherent memory in 249 Trusted Firmware" section in [Firmware Design]). It can take the value 1 250 (Coherent memory region is included) or 0 (Coherent memory region is 251 excluded). Default is 1. 252 253 * `TSPD_ROUTE_IRQ_TO_EL3`: A non zero value enables the routing model 254 for non-secure interrupts in which they are routed to EL3 (TSPD). The 255 default model (when the value is 0) is to route non-secure interrupts 256 to S-EL1 (TSP). 257 258 * `TRUSTED_BOARD_BOOT`: Boolean flag to include support for the Trusted Board 259 Boot feature. When set to '1', BL1 and BL2 images include support to load 260 and verify the certificates and images in a FIP. The default value is '0'. 261 A successful build, when `TRUSTED_BOARD_BOOT=1`, depends upon the correct 262 initialization of the `AUTH_MOD` option. Generation and inclusion of 263 certificates in the FIP depends upon the value of the `GENERATE_COT` option. 264 265 * `AUTH_MOD`: This option is used when `TRUSTED_BOARD_BOOT=1`. It specifies 266 the name of the authentication module that will be used in the Trusted Board 267 Boot sequence. The module must be located in `common/auth/<module name>` 268 directory. The directory must contain a makefile `<module name>.mk` which 269 will be used to build the module. More information can be found in 270 [Trusted Board Boot]. The default module name is 'none'. 271 272 * `GENERATE_COT`: Boolean flag used to build and execute the `cert_create` 273 tool to create certificates as per the Chain of Trust described in 274 [Trusted Board Boot]. The build system then calls the `fip_create` tool to 275 include the certificates in the FIP. Default value is '0'. 276 277 Specify `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=1` to include support for 278 the Trusted Board Boot Sequence in the BL1 and BL2 images and the FIP. 279 280 Note that if `TRUSTED_BOARD_BOOT=0` and `GENERATE_COT=1`, the BL1 and BL2 281 images will not include support for Trusted Board Boot. The FIP will still 282 include the key and content certificates. This FIP can be used to verify the 283 Chain of Trust on the host machine through other mechanisms. 284 285 Note that if `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=0`, the BL1 and BL2 286 images will include support for Trusted Board Boot, but the FIP will not 287 include the key and content certificates, causing a boot failure. 288 289 * `CREATE_KEYS`: This option is used when `GENERATE_COT=1`. It tells the 290 certificate generation tool to create new keys in case no valid keys are 291 present or specified. Allowed options are '0' or '1'. Default is '1'. 292 293 * `ROT_KEY`: This option is used when `GENERATE_COT=1`. It specifies the 294 file that contains the ROT private key in PEM format. 295 296 * `TRUSTED_WORLD_KEY`: This option is used when `GENERATE_COT=1`. It 297 specifies the file that contains the Trusted World private key in PEM 298 format. 299 300 * `NON_TRUSTED_WORLD_KEY`: This option is used when `GENERATE_COT=1`. It 301 specifies the file that contains the Non-Trusted World private key in PEM 302 format. 303 304 * `BL30_KEY`: This option is used when `GENERATE_COT=1`. It specifies the 305 file that contains the BL3-0 private key in PEM format. 306 307 * `BL31_KEY`: This option is used when `GENERATE_COT=1`. It specifies the 308 file that contains the BL3-1 private key in PEM format. 309 310 * `BL32_KEY`: This option is used when `GENERATE_COT=1`. It specifies the 311 file that contains the BL3-2 private key in PEM format. 312 313 * `BL33_KEY`: This option is used when `GENERATE_COT=1`. It specifies the 314 file that contains the BL3-3 private key in PEM format. 315 316 #### FVP specific build options 317 318 * `FVP_TSP_RAM_LOCATION`: location of the TSP binary. Options: 319 - `tsram` : Trusted SRAM (default option) 320 - `tdram` : Trusted DRAM 321 - `dram` : Secure region in DRAM (configured by the TrustZone controller) 322 323 For a better understanding of FVP options, the FVP memory map is explained in 324 the [Firmware Design]. 325 326 #### Juno specific build options 327 328 * `PLAT_TSP_LOCATION`: location of the TSP binary. Options: 329 - `tsram` : Trusted SRAM (default option) 330 - `dram` : Secure region in DRAM (set by the TrustZone controller) 331 332 ### Creating a Firmware Image Package 333 334 FIPs are automatically created as part of the build instructions described in 335 the previous section. It is also possible to independently build the FIP 336 creation tool and FIPs if required. To do this, follow these steps: 337 338 Build the tool: 339 340 make -C tools/fip_create 341 342 It is recommended to remove the build artifacts before rebuilding: 343 344 make -C tools/fip_create clean 345 346 Create a Firmware package that contains existing BL2 and BL3-1 images: 347 348 # fip_create --help to print usage information 349 # fip_create <fip_name> <images to add> [--dump to show result] 350 ./tools/fip_create/fip_create fip.bin --dump \ 351 --bl2 build/<platform>/debug/bl2.bin --bl31 build/<platform>/debug/bl31.bin 352 353 Firmware Image Package ToC: 354 --------------------------- 355 - Trusted Boot Firmware BL2: offset=0x88, size=0x81E8 356 file: 'build/<platform>/debug/bl2.bin' 357 - EL3 Runtime Firmware BL3-1: offset=0x8270, size=0xC218 358 file: 'build/<platform>/debug/bl31.bin' 359 --------------------------- 360 Creating "fip.bin" 361 362 View the contents of an existing Firmware package: 363 364 ./tools/fip_create/fip_create fip.bin --dump 365 366 Firmware Image Package ToC: 367 --------------------------- 368 - Trusted Boot Firmware BL2: offset=0x88, size=0x81E8 369 - EL3 Runtime Firmware BL3-1: offset=0x8270, size=0xC218 370 --------------------------- 371 372 Existing package entries can be individially updated: 373 374 # Change the BL2 from Debug to Release version 375 ./tools/fip_create/fip_create fip.bin --dump \ 376 --bl2 build/<platform>/release/bl2.bin 377 378 Firmware Image Package ToC: 379 --------------------------- 380 - Trusted Boot Firmware BL2: offset=0x88, size=0x7240 381 file: 'build/<platform>/release/bl2.bin' 382 - EL3 Runtime Firmware BL3-1: offset=0x72C8, size=0xC218 383 --------------------------- 384 Updating "fip.bin" 385 386 387 ### Debugging options 388 389 To compile a debug version and make the build more verbose use 390 391 CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \ 392 BL33=<path-to>/<bl33_image> \ 393 make PLAT=<platform> DEBUG=1 V=1 all fip 394 395 AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for 396 example DS-5) might not support this and may need an older version of DWARF 397 symbols to be emitted by GCC. This can be achieved by using the 398 `-gdwarf-<version>` flag, with the version being set to 2 or 3. Setting the 399 version to 2 is recommended for DS-5 versions older than 5.16. 400 401 When debugging logic problems it might also be useful to disable all compiler 402 optimizations by using `-O0`. 403 404 NOTE: Using `-O0` could cause output images to be larger and base addresses 405 might need to be recalculated (see the "Memory layout of BL images" section in 406 the [Firmware Design]). 407 408 Extra debug options can be passed to the build system by setting `CFLAGS`: 409 410 CFLAGS='-O0 -gdwarf-2' \ 411 CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \ 412 BL33=<path-to>/<bl33_image> \ 413 make PLAT=<platform> DEBUG=1 V=1 all fip 414 415 416 ### Building the Test Secure Payload 417 418 The TSP is coupled with a companion runtime service in the BL3-1 firmware, 419 called the TSPD. Therefore, if you intend to use the TSP, the BL3-1 image 420 must be recompiled as well. For more information on SPs and SPDs, see the 421 "Secure-EL1 Payloads and Dispatchers" section in the [Firmware Design]. 422 423 First clean the Trusted Firmware build directory to get rid of any previous 424 BL3-1 binary. Then to build the TSP image and include it into the FIP use: 425 426 CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \ 427 BL33=<path-to>/<bl33_image> \ 428 make PLAT=<platform> SPD=tspd all fip 429 430 An additional boot loader binary file is created in the `build` directory: 431 432 * `build/<platform>/<build-type>/bl32.bin` 433 434 The FIP will now contain the additional BL3-2 image. Here is an example 435 output from an FVP build in release mode including BL3-2 and using 436 FVP_AARCH64_EFI.fd as BL3-3 image: 437 438 Firmware Image Package ToC: 439 --------------------------- 440 - Trusted Boot Firmware BL2: offset=0xD8, size=0x6000 441 file: './build/fvp/release/bl2.bin' 442 - EL3 Runtime Firmware BL3-1: offset=0x60D8, size=0x9000 443 file: './build/fvp/release/bl31.bin' 444 - Secure Payload BL3-2 (Trusted OS): offset=0xF0D8, size=0x3000 445 file: './build/fvp/release/bl32.bin' 446 - Non-Trusted Firmware BL3-3: offset=0x120D8, size=0x280000 447 file: '../FVP_AARCH64_EFI.fd' 448 --------------------------- 449 Creating "build/fvp/release/fip.bin" 450 451 452 ### Building the Certificate Generation Tool 453 454 The `cert_create` tool can be built separately through the following commands: 455 456 $ cd tools/cert_create 457 $ make [DEBUG=1] [V=1] 458 459 `DEBUG=1` builds the tool in debug mode. `V=1` makes the build process more 460 verbose. The following command should be used to obtain help about the tool: 461 462 $ ./cert_create -h 463 464 The `cert_create` tool is automatically built with the `fip` target when 465 `GENERATE_COT=1`. 466 467 468 ### Building a FIP image with support for Trusted Board Boot 469 470 The Trusted Board Boot feature is described in [Trusted Board Boot]. The 471 following steps should be followed to build a FIP image with support for this 472 feature. 473 474 1. Fulfill the dependencies of the `polarssl` authentication module by checking 475 out the tag `polarssl-1.3.9` from the [PolarSSL Repository]. 476 477 The `common/auth/polarssl/polarssl.mk` contains the list of PolarSSL source 478 files the module depends upon. `common/auth/polarssl/polarssl_config.h` 479 contains the configuration options required to build the PolarSSL sources. 480 481 Note that the PolarSSL SSL library is licensed under the GNU GPL version 2 482 or later license. Using PolarSSL source code will affect the licensing of 483 Trusted Firmware binaries that are built using this library. 484 485 2. Ensure that the following command line variables are set while invoking 486 `make` to build Trusted Firmware: 487 488 * `POLARSSL_DIR=<path of the directory containing PolarSSL sources>` 489 * `AUTH_MOD=polarssl` 490 * `TRUSTED_BOARD_BOOT=1` 491 * `GENERATE_COT=1` 492 493 494 ### Checking source code style 495 496 When making changes to the source for submission to the project, the source 497 must be in compliance with the Linux style guide, and to assist with this check 498 the project Makefile contains two targets, which both utilise the 499 `checkpatch.pl` script that ships with the Linux source tree. 500 501 To check the entire source tree, you must first download a copy of 502 `checkpatch.pl` (or the full Linux source), set the `CHECKPATCH` environment 503 variable to point to the script and build the target checkcodebase: 504 505 make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase 506 507 To just check the style on the files that differ between your local branch and 508 the remote master, use: 509 510 make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch 511 512 If you wish to check your patch against something other than the remote master, 513 set the `BASE_COMMIT` variable to your desired branch. By default, `BASE_COMMIT` 514 is set to `origin/master`. 515 516 517 5. Obtaining the normal world software 518 --------------------------------------- 519 520 ### Obtaining EDK2 521 522 Potentially any kind of non-trusted firmware may be used with the ARM Trusted 523 Firmware but the software has only been tested with the EFI Development Kit 2 524 (EDK2) open source implementation of the UEFI specification. 525 526 To build the software to be compatible with the Foundation and Base FVPs, or the 527 Juno platform, follow these steps: 528 529 1. Clone the [EDK2 source code][EDK2] from GitHub: 530 531 git clone -n https://github.com/tianocore/edk2.git 532 533 Not all required features are available in the EDK2 mainline yet. These can 534 be obtained from the ARM-software EDK2 repository instead: 535 536 cd edk2 537 git remote add -f --tags arm-software https://github.com/ARM-software/edk2.git 538 git checkout --detach v2.1-rc0 539 540 2. Copy build config templates to local workspace 541 542 # in edk2/ 543 . edksetup.sh 544 545 3. Build the EDK2 host tools 546 547 make -C BaseTools clean 548 make -C BaseTools 549 550 4. Build the EDK2 software 551 552 1. Build for FVP 553 554 GCC49_AARCH64_PREFIX=<absolute-path-to-aarch64-gcc>/bin/aarch64-none-elf- \ 555 make -f ArmPlatformPkg/Scripts/Makefile EDK2_ARCH=AARCH64 \ 556 EDK2_DSC=ArmPlatformPkg/ArmVExpressPkg/ArmVExpress-FVP-AArch64.dsc \ 557 EDK2_TOOLCHAIN=GCC49 EDK2_BUILD=RELEASE \ 558 EDK2_MACROS="-n 6 -D ARM_FOUNDATION_FVP=1" 559 560 The EDK2 binary for use with the ARM Trusted Firmware can then be found 561 here: 562 563 Build/ArmVExpress-FVP-AArch64/RELEASE_GCC49/FV/FVP_AARCH64_EFI.fd 564 565 2. Build for Juno 566 567 GCC49_AARCH64_PREFIX=<absolute-path-to-aarch64-gcc>/bin/aarch64-none-elf- \ 568 make -f ArmPlatformPkg/ArmJunoPkg/Makefile EDK2_ARCH=AARCH64 \ 569 EDK2_TOOLCHAIN=GCC49 EDK2_BUILD=RELEASE 570 571 The EDK2 binary for use with the ARM Trusted Firmware can then be found 572 here: 573 574 Build/ArmJuno/RELEASE_GCC49/FV/BL33_AP_UEFI.fd 575 576 The EDK2 binary should be specified as `BL33` in in the `make` command line 577 when building the Trusted Firmware. See the "Building the Trusted Firmware" 578 section above. 579 580 5. (Optional) To build EDK2 in debug mode, remove `EDK2_BUILD=RELEASE` from the 581 command line. 582 583 6. (Optional) To boot Linux using a VirtioBlock file-system, the command line 584 passed from EDK2 to the Linux kernel must be modified as described in the 585 "Obtaining a root file-system" section below. 586 587 7. (Optional) If legacy GICv2 locations are used, the EDK2 platform description 588 must be updated. This is required as EDK2 does not support probing for the 589 GIC location. To do this, first clean the EDK2 build directory. 590 591 make -f ArmPlatformPkg/Scripts/Makefile EDK2_ARCH=AARCH64 \ 592 EDK2_DSC=ArmPlatformPkg/ArmVExpressPkg/ArmVExpress-FVP-AArch64.dsc \ 593 EDK2_TOOLCHAIN=ARMGCC clean 594 595 Then rebuild EDK2 as described in step 3, using the following flag: 596 597 -D ARM_FVP_LEGACY_GICV2_LOCATION=1 598 599 Finally rebuild the Trusted Firmware to generate a new FIP using the 600 instructions in the "Building the Trusted Firmware" section. 601 602 603 ### Obtaining a Linux kernel 604 605 Preparing a Linux kernel for use on the FVPs can be done as follows 606 (GICv2 support only): 607 608 1. Clone Linux: 609 610 git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 611 612 Not all required features are available in the kernel mainline yet. These 613 can be obtained from the ARM-software Linux repository instead: 614 615 cd linux 616 git remote add -f --tags arm-software https://github.com/ARM-software/linux.git 617 git checkout --detach 1.3-Juno 618 619 2. Build with the Linaro GCC tools. 620 621 # in linux/ 622 make mrproper 623 make ARCH=arm64 defconfig 624 625 CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- \ 626 make -j6 ARCH=arm64 627 628 The compiled Linux image will now be found at `arch/arm64/boot/Image`. 629 630 631 6. Preparing the images to run on FVP 632 -------------------------------------- 633 634 ### Obtaining the Flattened Device Trees 635 636 Depending on the FVP configuration and Linux configuration used, different 637 FDT files are required. FDTs for the Foundation and Base FVPs can be found in 638 the Trusted Firmware source directory under `fdts/`. The Foundation FVP has a 639 subset of the Base FVP components. For example, the Foundation FVP lacks CLCD 640 and MMC support, and has only one CPU cluster. 641 642 * `fvp-base-gicv2-psci.dtb` 643 644 (Default) For use with both AEMv8 and Cortex-A57-A53 Base FVPs with 645 Base memory map configuration. 646 647 * `fvp-base-gicv2legacy-psci.dtb` 648 649 For use with AEMv8 Base FVP with legacy VE GIC memory map configuration. 650 651 * `fvp-base-gicv3-psci.dtb` 652 653 For use with both AEMv8 and Cortex-A57-A53 Base FVPs with Base memory map 654 configuration and Linux GICv3 support. 655 656 * `fvp-foundation-gicv2-psci.dtb` 657 658 (Default) For use with Foundation FVP with Base memory map configuration. 659 660 * `fvp-foundation-gicv2legacy-psci.dtb` 661 662 For use with Foundation FVP with legacy VE GIC memory map configuration. 663 664 * `fvp-foundation-gicv3-psci.dtb` 665 666 For use with Foundation FVP with Base memory map configuration and Linux 667 GICv3 support. 668 669 670 Copy the chosen FDT blob as `fdt.dtb` to the directory from which the FVP 671 is launched. Alternatively a symbolic link may be used. 672 673 ### Preparing the kernel image 674 675 Copy the kernel image file `arch/arm64/boot/Image` to the directory from which 676 the FVP is launched. Alternatively a symbolic link may be used. 677 678 ### Obtaining a root file-system 679 680 To prepare a Linaro LAMP based Open Embedded file-system, the following 681 instructions can be used as a guide. The file-system can be provided to Linux 682 via VirtioBlock or as a RAM-disk. Both methods are described below. 683 684 #### Prepare VirtioBlock 685 686 To prepare a VirtioBlock file-system, do the following: 687 688 1. Download and unpack the disk image. 689 690 NOTE: The unpacked disk image grows to 3 GiB in size. 691 692 wget http://releases.linaro.org/14.12/openembedded/aarch64/vexpress64-openembedded_lamp-armv8-gcc-4.9_20141211-701.img.gz 693 gunzip vexpress64-openembedded_lamp-armv8-gcc-4.9_20141211-701.img.gz 694 695 2. Make sure the Linux kernel has Virtio support enabled using 696 `make ARCH=arm64 menuconfig`. 697 698 Device Drivers ---> Virtio drivers ---> <*> Platform bus driver for memory mapped virtio devices 699 Device Drivers ---> [*] Block devices ---> <*> Virtio block driver 700 File systems ---> <*> The Extended 4 (ext4) filesystem 701 702 If some of these configurations are missing, enable them, save the kernel 703 configuration, then rebuild the kernel image using the instructions 704 provided in the section "Obtaining a Linux kernel". 705 706 3. Change the Kernel command line to include `root=/dev/vda2`. This can either 707 be done in the EDK2 boot menu or in the platform file. Editing the platform 708 file and rebuilding EDK2 will make the change persist. To do this: 709 710 1. In EDK2, edit the following file: 711 712 ArmPlatformPkg/ArmVExpressPkg/ArmVExpress-FVP-AArch64.dsc 713 714 2. Add `root=/dev/vda2` to: 715 716 gArmPlatformTokenSpaceGuid.PcdDefaultBootArgument|"<Other default options>" 717 718 3. Remove the entry: 719 720 gArmPlatformTokenSpaceGuid.PcdDefaultBootInitrdPath|"" 721 722 4. Rebuild EDK2 (see "Obtaining UEFI" section above). 723 724 4. The file-system image file should be provided to the model environment by 725 passing it the correct command line option. In the FVPs the following 726 option should be provided in addition to the ones described in the 727 "Running the software on FVP" section below. 728 729 NOTE: A symbolic link to this file cannot be used with the FVP; the path 730 to the real file must be provided. 731 732 On the Base FVPs: 733 734 -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" 735 736 On the Foundation FVP: 737 738 --block-device="<path-to>/<file-system-image>" 739 740 5. Ensure that the FVP doesn't output any error messages. If the following 741 error message is displayed: 742 743 ERROR: BlockDevice: Failed to open "<path-to>/<file-system-image>"! 744 745 then make sure the path to the file-system image in the model parameter is 746 correct and that read permission is correctly set on the file-system image 747 file. 748 749 #### Prepare RAM-disk 750 751 To prepare a RAM-disk root file-system, do the following: 752 753 1. Download the file-system image: 754 755 wget http://releases.linaro.org/14.12/openembedded/aarch64/linaro-image-lamp-genericarmv8-20141212-729.rootfs.tar.gz 756 757 2. Modify the Linaro image: 758 759 # Prepare for use as RAM-disk. Normally use MMC, NFS or VirtioBlock. 760 # Be careful, otherwise you could damage your host file-system. 761 mkdir tmp; cd tmp 762 sudo sh -c "zcat ../linaro-image-lamp-genericarmv8-20141212-729.rootfs.tar.gz | cpio -id" 763 sudo ln -s sbin/init . 764 sudo sh -c "echo 'devtmpfs /dev devtmpfs mode=0755,nosuid 0 0' >> etc/fstab" 765 sudo sh -c "find . | cpio --quiet -H newc -o | gzip -3 -n > ../filesystem.cpio.gz" 766 cd .. 767 768 3. Copy the resultant `filesystem.cpio.gz` to the directory where the FVP is 769 launched from. Alternatively a symbolic link may be used. 770 771 772 7. Running the software on FVP 773 ------------------------------- 774 775 This version of the ARM Trusted Firmware has been tested on the following ARM 776 FVPs (64-bit versions only). 777 778 * `Foundation_Platform` (Version 9.1, Build 9.1.33) 779 * `FVP_Base_AEMv8A-AEMv8A` (Version 6.2, Build 0.8.6202) 780 * `FVP_Base_Cortex-A57x4-A53x4` (Version 6.2, Build 0.8.6202) 781 * `FVP_Base_Cortex-A57x1-A53x1` (Version 6.2, Build 0.8.6202) 782 * `FVP_Base_Cortex-A57x2-A53x4` (Version 6.2, Build 0.8.6202) 783 784 NOTE: The build numbers quoted above are those reported by launching the FVP 785 with the `--version` parameter. 786 787 NOTE: The software will not work on Version 1.0 of the Foundation FVP. 788 The commands below would report an `unhandled argument` error in this case. 789 790 NOTE: The Foundation FVP does not provide a debugger interface. 791 792 Please refer to the FVP documentation for a detailed description of the model 793 parameter options. A brief description of the important ones that affect the 794 ARM Trusted Firmware and normal world software behavior is provided below. 795 796 The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be 797 downloaded for free from [ARM's website][ARM FVP website]. 798 799 800 ### Running on the Foundation FVP with reset to BL1 entrypoint 801 802 The following `Foundation_Platform` parameters should be used to boot Linux with 803 4 CPUs using the ARM Trusted Firmware. 804 805 NOTE: Using the `--block-device` parameter is not necessary if a Linux RAM-disk 806 file-system is used (see the "Obtaining a File-system" section above). 807 808 NOTE: The `--data="<path to FIP binary>"@0x8000000` parameter is used to load a 809 Firmware Image Package at the start of NOR FLASH0 (see the "Building the 810 Trusted Firmware" section above). 811 812 <path-to>/Foundation_Platform \ 813 --cores=4 \ 814 --secure-memory \ 815 --visualization \ 816 --gicv3 \ 817 --data="<path-to>/<bl1-binary>"@0x0 \ 818 --data="<path-to>/<FIP-binary>"@0x8000000 \ 819 --block-device="<path-to>/<file-system-image>" 820 821 The default use-case for the Foundation FVP is to enable the GICv3 device in 822 the model but use the GICv2 FDT, in order for Linux to drive the GIC in GICv2 823 emulation mode. 824 825 The memory mapped addresses `0x0` and `0x8000000` correspond to the start of 826 trusted ROM and NOR FLASH0 respectively. 827 828 ### Notes regarding Base FVP configuration options 829 830 Please refer to these notes in the subsequent "Running on the Base FVP" 831 sections. 832 833 1. The `-C bp.flashloader0.fname` parameter is used to load a Firmware Image 834 Package at the start of NOR FLASH0 (see the "Building the Trusted Firmware" 835 section above). 836 837 2. Using `cache_state_modelled=1` makes booting very slow. The software will 838 still work (and run much faster) without this option but this will hide any 839 cache maintenance defects in the software. 840 841 3. Using the `-C bp.virtioblockdevice.image_path` parameter is not necessary 842 if a Linux RAM-disk file-system is used (see the "Obtaining a root 843 file-system" section above). 844 845 4. Setting the `-C bp.secure_memory` parameter to `1` is only supported on 846 Base FVP versions 5.4 and newer. Setting this parameter to `0` is also 847 supported. The `-C bp.tzc_400.diagnostics=1` parameter is optional. It 848 instructs the FVP to provide some helpful information if a secure memory 849 violation occurs. 850 851 5. This and the following notes only apply when the firmware is built with 852 the `RESET_TO_BL31` option. 853 854 The `--data="<path-to><bl31|bl32|bl33-binary>"@<base-address-of-binary>` 855 parameter is used to load bootloader images into Base FVP memory (see the 856 "Building the Trusted Firmware" section above). The base addresses used 857 should match the image base addresses in `platform_def.h` used while linking 858 the images. The BL3-2 image is only needed if BL3-1 has been built to expect 859 a Secure-EL1 Payload. 860 861 6. The `-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>` parameter, where 862 X and Y are the cluster and CPU numbers respectively, is used to set the 863 reset vector for each core. 864 865 7. Changing the default value of `FVP_SHARED_DATA_LOCATION` will also require 866 changing the value of 867 `--data="<path-to><bl31-binary>"@<base-address-of-bl31>` and 868 `-C cluster<X>.cpu<X>.RVBAR=@<base-address-of-bl31>`, to the new value of 869 `BL31_BASE` in `platform_def.h`. 870 871 8. Changing the default value of `FVP_TSP_RAM_LOCATION` will also require 872 changing the value of 873 `--data="<path-to><bl32-binary>"@<base-address-of-bl32>` to the new value of 874 `BL32_BASE` in `platform_def.h`. 875 876 877 ### Running on the AEMv8 Base FVP with reset to BL1 entrypoint 878 879 Please read "Notes regarding Base FVP configuration options" section above for 880 information about some of the options to run the software. 881 882 The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux 883 with 8 CPUs using the ARM Trusted Firmware. 884 885 <path-to>/FVP_Base_AEMv8A-AEMv8A \ 886 -C pctl.startup=0.0.0.0 \ 887 -C bp.secure_memory=1 \ 888 -C bp.tzc_400.diagnostics=1 \ 889 -C cluster0.NUM_CORES=4 \ 890 -C cluster1.NUM_CORES=4 \ 891 -C cache_state_modelled=1 \ 892 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ 893 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ 894 -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" 895 896 ### Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint 897 898 Please read "Notes regarding Base FVP configuration options" section above for 899 information about some of the options to run the software. 900 901 The following `FVP_Base_Cortex-A57x4-A53x4` model parameters should be used to 902 boot Linux with 8 CPUs using the ARM Trusted Firmware. 903 904 <path-to>/FVP_Base_Cortex-A57x4-A53x4 \ 905 -C pctl.startup=0.0.0.0 \ 906 -C bp.secure_memory=1 \ 907 -C bp.tzc_400.diagnostics=1 \ 908 -C cache_state_modelled=1 \ 909 -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \ 910 -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \ 911 -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" 912 913 ### Running on the AEMv8 Base FVP with reset to BL3-1 entrypoint 914 915 Please read "Notes regarding Base FVP configuration options" section above for 916 information about some of the options to run the software. 917 918 The following `FVP_Base_AEMv8A-AEMv8A` parameters should be used to boot Linux 919 with 8 CPUs using the ARM Trusted Firmware. 920 921 <path-to>/FVP_Base_AEMv8A-AEMv8A \ 922 -C pctl.startup=0.0.0.0 \ 923 -C bp.secure_memory=1 \ 924 -C bp.tzc_400.diagnostics=1 \ 925 -C cluster0.NUM_CORES=4 \ 926 -C cluster1.NUM_CORES=4 \ 927 -C cache_state_modelled=1 \ 928 -C cluster0.cpu0.RVBAR=0x04023000 \ 929 -C cluster0.cpu1.RVBAR=0x04023000 \ 930 -C cluster0.cpu2.RVBAR=0x04023000 \ 931 -C cluster0.cpu3.RVBAR=0x04023000 \ 932 -C cluster1.cpu0.RVBAR=0x04023000 \ 933 -C cluster1.cpu1.RVBAR=0x04023000 \ 934 -C cluster1.cpu2.RVBAR=0x04023000 \ 935 -C cluster1.cpu3.RVBAR=0x04023000 \ 936 --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04023000 \ 937 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \ 938 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ 939 -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" 940 941 ### Running on the Cortex-A57-A53 Base FVP with reset to BL3-1 entrypoint 942 943 Please read "Notes regarding Base FVP configuration options" section above for 944 information about some of the options to run the software. 945 946 The following `FVP_Base_Cortex-A57x4-A53x4` model parameters should be used to 947 boot Linux with 8 CPUs using the ARM Trusted Firmware. 948 949 <path-to>/FVP_Base_Cortex-A57x4-A53x4 \ 950 -C pctl.startup=0.0.0.0 \ 951 -C bp.secure_memory=1 \ 952 -C bp.tzc_400.diagnostics=1 \ 953 -C cache_state_modelled=1 \ 954 -C cluster0.cpu0.RVBARADDR=0x04023000 \ 955 -C cluster0.cpu1.RVBARADDR=0x04023000 \ 956 -C cluster0.cpu2.RVBARADDR=0x04023000 \ 957 -C cluster0.cpu3.RVBARADDR=0x04023000 \ 958 -C cluster1.cpu0.RVBARADDR=0x04023000 \ 959 -C cluster1.cpu1.RVBARADDR=0x04023000 \ 960 -C cluster1.cpu2.RVBARADDR=0x04023000 \ 961 -C cluster1.cpu3.RVBARADDR=0x04023000 \ 962 --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04023000 \ 963 --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04001000 \ 964 --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \ 965 -C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>" 966 967 ### Configuring the GICv2 memory map 968 969 The Base FVP models support GICv2 with the default model parameters at the 970 following addresses. The Foundation FVP also supports these addresses when 971 configured for GICv3 in GICv2 emulation mode. 972 973 GICv2 Distributor Interface 0x2f000000 974 GICv2 CPU Interface 0x2c000000 975 GICv2 Virtual CPU Interface 0x2c010000 976 GICv2 Hypervisor Interface 0x2c02f000 977 978 The AEMv8 Base FVP can be configured to support GICv2 at addresses 979 corresponding to the legacy (Versatile Express) memory map as follows. These are 980 the default addresses when using the Foundation FVP in GICv2 mode. 981 982 GICv2 Distributor Interface 0x2c001000 983 GICv2 CPU Interface 0x2c002000 984 GICv2 Virtual CPU Interface 0x2c004000 985 GICv2 Hypervisor Interface 0x2c006000 986 987 The choice of memory map is reflected in the build variant field (bits[15:12]) 988 in the `SYS_ID` register (Offset `0x0`) in the Versatile Express System 989 registers memory map (`0x1c010000`). 990 991 * `SYS_ID.Build[15:12]` 992 993 `0x1` corresponds to the presence of the Base GIC memory map. This is the 994 default value on the Base FVPs. 995 996 * `SYS_ID.Build[15:12]` 997 998 `0x0` corresponds to the presence of the Legacy VE GIC memory map. This is 999 the default value on the Foundation FVP. 1000 1001 This register can be configured as described in the following sections. 1002 1003 NOTE: If the legacy VE GIC memory map is used, then the corresponding FDT and 1004 BL3-3 images should be used. 1005 1006 #### Configuring AEMv8 Foundation FVP GIC for legacy VE memory map 1007 1008 The following parameters configure the Foundation FVP to use GICv2 with the 1009 legacy VE memory map: 1010 1011 <path-to>/Foundation_Platform \ 1012 --cores=4 \ 1013 --secure-memory \ 1014 --visualization \ 1015 --no-gicv3 \ 1016 --data="<path-to>/<bl1-binary>"@0x0 \ 1017 --data="<path-to>/<FIP-binary>"@0x8000000 \ 1018 --block-device="<path-to>/<file-system-image>" 1019 1020 Explicit configuration of the `SYS_ID` register is not required. 1021 1022 #### Configuring AEMv8 Base FVP GIC for legacy VE memory map 1023 1024 The following parameters configure the AEMv8 Base FVP to use GICv2 with the 1025 legacy VE memory map. They must added to the parameters described in the 1026 "Running on the AEMv8 Base FVP" section above: 1027 1028 -C cluster0.gic.GICD-offset=0x1000 \ 1029 -C cluster0.gic.GICC-offset=0x2000 \ 1030 -C cluster0.gic.GICH-offset=0x4000 \ 1031 -C cluster0.gic.GICH-other-CPU-offset=0x5000 \ 1032 -C cluster0.gic.GICV-offset=0x6000 \ 1033 -C cluster0.gic.PERIPH-size=0x8000 \ 1034 -C cluster1.gic.GICD-offset=0x1000 \ 1035 -C cluster1.gic.GICC-offset=0x2000 \ 1036 -C cluster1.gic.GICH-offset=0x4000 \ 1037 -C cluster1.gic.GICH-other-CPU-offset=0x5000 \ 1038 -C cluster1.gic.GICV-offset=0x6000 \ 1039 -C cluster1.gic.PERIPH-size=0x8000 \ 1040 -C gic_distributor.GICD-alias=0x2c001000 \ 1041 -C gicv3.gicv2-only=1 \ 1042 -C bp.variant=0x0 1043 1044 The `bp.variant` parameter corresponds to the build variant field of the 1045 `SYS_ID` register. Setting this to `0x0` allows the ARM Trusted Firmware to 1046 detect the legacy VE memory map while configuring the GIC. 1047 1048 1049 8. Running the software on Juno 1050 -------------------------------- 1051 1052 ### Preparing Trusted Firmware images 1053 1054 To execute the versions of software components on Juno referred to in this 1055 document, the latest [Juno Board Recovery Image] must be installed. If you 1056 have an earlier version installed or are unsure which version is installed, 1057 follow the recovery image update instructions in the [Juno Software Guide] 1058 on the [ARM Connected Community] website. 1059 1060 The Juno platform requires a BL3-0 image to boot up. This image contains the 1061 runtime firmware that runs on the SCP (System Control Processor). This image is 1062 embedded within the [Juno Board Recovery Image] but can also be 1063 [downloaded directly][Juno SCP Firmware]. 1064 1065 Rebuild the Trusted Firmware specifying the BL3-0 image. Refer to the section 1066 "Building the Trusted Firmware". Alternatively, the FIP image can be updated 1067 manually with the BL3-0 image: 1068 1069 fip_create --dump --bl30 <path-to>/<bl30-binary> <path-to>/<FIP-binary> 1070 1071 ### Obtaining the Flattened Device Tree 1072 1073 Juno's device tree blob is built along with the kernel. It is located in: 1074 1075 <path-to-linux>/arch/arm64/boot/dts/juno.dtb 1076 1077 ### Other Juno software information 1078 1079 Please refer to the [Juno Software Guide] to: 1080 1081 * Deploy a root filesystem 1082 * Install and run the Juno binaries on the board 1083 * Obtain any other Juno software information 1084 1085 1086 - - - - - - - - - - - - - - - - - - - - - - - - - - 1087 1088 _Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._ 1089 1090 1091 [Firmware Design]: ./firmware-design.md 1092 1093 [ARM FVP website]: http://www.arm.com/fvp 1094 [ARM Connected Community]: http://community.arm.com 1095 [Juno Software Guide]: http://community.arm.com/docs/DOC-8396 1096 [Juno Board Recovery Image]: http://community.arm.com/servlet/JiveServlet/download/9427-1-15432/board_recovery_image_0.10.1.zip 1097 [Juno SCP Firmware]: http://community.arm.com/servlet/JiveServlet/download/9427-1-15422/bl30.bin.zip 1098 [Linaro Toolchain]: http://releases.linaro.org/14.07/components/toolchain/binaries/ 1099 [EDK2]: http://github.com/tianocore/edk2 1100 [DS-5]: http://www.arm.com/products/tools/software-tools/ds-5/index.php 1101 [Polarssl Repository]: https://github.com/polarssl/polarssl.git 1102 [Trusted Board Boot]: trusted-board-boot.md 1103
