docs/user-guide.rst

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