doc: Split the User Guide into multiple files
The User Guide document has grown organically over time and
now covers a wide range of topics, making it difficult to
skim read and extract information from. Currently, it covers
these topics and maybe a couple more:
- Requirements (hardware, tools, libs)
- Checking out the repo
- Basic build instructions
- A comprehensive list of build flags
- FIP packaging
- Building specifically for Juno
- Firmware update images
- EL3 payloads
- Preloaded BL33 boot flow
- Running on FVPs
- Running on Juno
I have separated these out into a few groups that become new
documents. Broadly speaking, build instructions for the tools,
for TF-A generally, and for specific scenarios are separated.
Content relating to specific platforms (Juno and the FVPs are
Arm-specific platforms, essentially) has been moved into the
documentation that is specific to those platforms, under
docs/plat/arm.
Change-Id: Ica87c52d8cd4f577332be0b0738998ea3ba3bbec
Signed-off-by: Paul Beesley <paul.beesley@arm.com>
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
new file mode 100644
index 0000000..fded1e0
--- /dev/null
+++ b/docs/getting_started/build-options.rst
@@ -0,0 +1,623 @@
+Build Options
+=============
+
+The TF-A build system supports the following build options. Unless mentioned
+otherwise, these options are expected to be specified at the build command
+line and are not to be modified in any component makefiles. Note that the
+build system doesn't track dependency for build options. Therefore, if any of
+the build options are changed from a previous build, a clean build must be
+performed.
+
+.. _build_options_common:
+
+Common build options
+--------------------
+
+- ``AARCH32_INSTRUCTION_SET``: Choose the AArch32 instruction set that the
+ compiler should use. Valid values are T32 and A32. It defaults to T32 due to
+ code having a smaller resulting size.
+
+- ``AARCH32_SP`` : Choose the AArch32 Secure Payload component to be built as
+ as the BL32 image when ``ARCH=aarch32``. The value should be the path to the
+ directory containing the SP source, relative to the ``bl32/``; the directory
+ is expected to contain a makefile called ``<aarch32_sp-value>.mk``.
+
+- ``ARCH`` : Choose the target build architecture for TF-A. It can take either
+ ``aarch64`` or ``aarch32`` as values. By default, it is defined to
+ ``aarch64``.
+
+- ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when
+ compiling TF-A. Its value must be numeric, and defaults to 8 . See also,
+ *Armv8 Architecture Extensions* and *Armv7 Architecture Extensions* in
+ :ref:`Firmware Design`.
+
+- ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when
+ compiling TF-A. Its value must be a numeric, and defaults to 0. See also,
+ *Armv8 Architecture Extensions* in :ref:`Firmware Design`.
+
+- ``BL2``: This is an optional build option which specifies the path to BL2
+ image for the ``fip`` target. In this case, the BL2 in the TF-A will not be
+ built.
+
+- ``BL2U``: This is an optional build option which specifies the path to
+ BL2U image. In this case, the BL2U in TF-A will not be built.
+
+- ``BL2_AT_EL3``: This is an optional build option that enables the use of
+ BL2 at EL3 execution level.
+
+- ``BL2_IN_XIP_MEM``: In some use-cases BL2 will be stored in eXecute In Place
+ (XIP) memory, like BL1. In these use-cases, it is necessary to initialize
+ the RW sections in RAM, while leaving the RO sections in place. This option
+ enable this use-case. For now, this option is only supported when BL2_AT_EL3
+ is set to '1'.
+
+- ``BL31``: This is an optional build option which specifies the path to
+ BL31 image for the ``fip`` target. In this case, the BL31 in TF-A will not
+ be built.
+
+- ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
+ file that contains the BL31 private key in PEM format. If ``SAVE_KEYS=1``,
+ this file name will be used to save the key.
+
+- ``BL32``: This is an optional build option which specifies the path to
+ BL32 image for the ``fip`` target. In this case, the BL32 in TF-A will not
+ be built.
+
+- ``BL32_EXTRA1``: This is an optional build option which specifies the path to
+ Trusted OS Extra1 image for the ``fip`` target.
+
+- ``BL32_EXTRA2``: This is an optional build option which specifies the path to
+ Trusted OS Extra2 image for the ``fip`` target.
+
+- ``BL32_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
+ file that contains the BL32 private key in PEM format. If ``SAVE_KEYS=1``,
+ this file name will be used to save the key.
+
+- ``BL33``: Path to BL33 image in the host file system. This is mandatory for
+ ``fip`` target in case TF-A BL2 is used.
+
+- ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
+ file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``,
+ this file name will be used to save the key.
+
+- ``BRANCH_PROTECTION``: Numeric value to enable ARMv8.3 Pointer Authentication
+ and ARMv8.5 Branch Target Identification support for TF-A BL images themselves.
+ If enabled, it is needed to use a compiler that supports the option
+ ``-mbranch-protection``. Selects the branch protection features to use:
+- 0: Default value turns off all types of branch protection
+- 1: Enables all types of branch protection features
+- 2: Return address signing to its standard level
+- 3: Extend the signing to include leaf functions
+
+ The table below summarizes ``BRANCH_PROTECTION`` values, GCC compilation options
+ and resulting PAuth/BTI features.
+
+ +-------+--------------+-------+-----+
+ | Value | GCC option | PAuth | BTI |
+ +=======+==============+=======+=====+
+ | 0 | none | N | N |
+ +-------+--------------+-------+-----+
+ | 1 | standard | Y | Y |
+ +-------+--------------+-------+-----+
+ | 2 | pac-ret | Y | N |
+ +-------+--------------+-------+-----+
+ | 3 | pac-ret+leaf | Y | N |
+ +-------+--------------+-------+-----+
+
+ This option defaults to 0 and this is an experimental feature.
+ Note that Pointer Authentication is enabled for Non-secure world
+ irrespective of the value of this option if the CPU supports it.
+
+- ``BUILD_MESSAGE_TIMESTAMP``: String used to identify the time and date of the
+ compilation of each build. It must be set to a C string (including quotes
+ where applicable). Defaults to a string that contains the time and date of
+ the compilation.
+
+- ``BUILD_STRING``: Input string for VERSION_STRING, which allows the TF-A
+ build to be uniquely identified. Defaults to the current git commit id.
+
+- ``CFLAGS``: Extra user options appended on the compiler's command line in
+ addition to the options set by the build system.
+
+- ``COLD_BOOT_SINGLE_CPU``: This option indicates whether the platform may
+ release several CPUs out of reset. It can take either 0 (several CPUs may be
+ brought up) or 1 (only one CPU will ever be brought up during cold reset).
+ Default is 0. If the platform always brings up a single CPU, there is no
+ need to distinguish between primary and secondary CPUs and the boot path can
+ be optimised. The ``plat_is_my_cpu_primary()`` and
+ ``plat_secondary_cold_boot_setup()`` platform porting interfaces do not need
+ to be implemented in this case.
+
+- ``CRASH_REPORTING``: A non-zero value enables a console dump of processor
+ register state when an unexpected exception occurs during execution of
+ BL31. This option defaults to the value of ``DEBUG`` - i.e. by default
+ this is only enabled for a debug build of the firmware.
+
+- ``CREATE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
+ certificate generation tool to create new keys in case no valid keys are
+ present or specified. Allowed options are '0' or '1'. Default is '1'.
+
+- ``CTX_INCLUDE_AARCH32_REGS`` : Boolean option that, when set to 1, will cause
+ the AArch32 system registers to be included when saving and restoring the
+ CPU context. The option must be set to 0 for AArch64-only platforms (that
+ is on hardware that does not implement AArch32, or at least not at EL1 and
+ higher ELs). Default value is 1.
+
+- ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP
+ registers to be included when saving and restoring the CPU context. Default
+ is 0.
+
+- ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, enables
+ Pointer Authentication for Secure world. This will cause the ARMv8.3-PAuth
+ registers to be included when saving and restoring the CPU context as
+ part of world switch. Default value is 0 and this is an experimental feature.
+ Note that Pointer Authentication is enabled for Non-secure world irrespective
+ of the value of this flag if the CPU supports it.
+
+- ``DEBUG``: Chooses between a debug and release build. It can take either 0
+ (release) or 1 (debug) as values. 0 is the default.
+
+- ``DISABLE_BIN_GENERATION``: Boolean option to disable the generation
+ of the binary image. If set to 1, then only the ELF image is built.
+ 0 is the default.
+
+- ``DYN_DISABLE_AUTH``: Provides the capability to dynamically disable Trusted
+ Board Boot authentication at runtime. This option is meant to be enabled only
+ for development platforms. ``TRUSTED_BOARD_BOOT`` flag must be set if this
+ flag has to be enabled. 0 is the default.
+
+- ``E``: Boolean option to make warnings into errors. Default is 1.
+
+- ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of
+ the normal boot flow. It must specify the entry point address of the EL3
+ payload. Please refer to the "Booting an EL3 payload" section for more
+ details.
+
+- ``ENABLE_AMU``: Boolean option to enable Activity Monitor Unit extensions.
+ This is an optional architectural feature available on v8.4 onwards. Some
+ v8.2 implementations also implement an AMU and this option can be used to
+ enable this feature on those systems as well. Default is 0.
+
+- ``ENABLE_ASSERTIONS``: This option controls whether or not calls to ``assert()``
+ are compiled out. For debug builds, this option defaults to 1, and calls to
+ ``assert()`` are left in place. For release builds, this option defaults to 0
+ and calls to ``assert()`` function are compiled out. This option can be set
+ independently of ``DEBUG``. It can also be used to hide any auxiliary code
+ that is only required for the assertion and does not fit in the assertion
+ itself.
+
+- ``ENABLE_BACKTRACE``: This option controls whether to enables backtrace
+ dumps or not. It is supported in both AArch64 and AArch32. However, in
+ AArch32 the format of the frame records are not defined in the AAPCS and they
+ are defined by the implementation. This implementation of backtrace only
+ supports the format used by GCC when T32 interworking is disabled. For this
+ reason enabling this option in AArch32 will force the compiler to only
+ generate A32 code. This option is enabled by default only in AArch64 debug
+ builds, but this behaviour can be overridden in each platform's Makefile or
+ in the build command line.
+
+- ``ENABLE_MPAM_FOR_LOWER_ELS``: Boolean option to enable lower ELs to use MPAM
+ feature. MPAM is an optional Armv8.4 extension that enables various memory
+ system components and resources to define partitions; software running at
+ various ELs can assign themselves to desired partition to control their
+ performance aspects.
+
+ When this option is set to ``1``, EL3 allows lower ELs to access their own
+ MPAM registers without trapping into EL3. This option doesn't make use of
+ partitioning in EL3, however. Platform initialisation code should configure
+ and use partitions in EL3 as required. This option defaults to ``0``.
+
+- ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE)
+ support within generic code in TF-A. This option is currently only supported
+ in BL31. Default is 0.
+
+- ``ENABLE_PMF``: Boolean option to enable support for optional Performance
+ Measurement Framework(PMF). Default is 0.
+
+- ``ENABLE_PSCI_STAT``: Boolean option to enable support for optional PSCI
+ functions ``PSCI_STAT_RESIDENCY`` and ``PSCI_STAT_COUNT``. Default is 0.
+ In the absence of an alternate stat collection backend, ``ENABLE_PMF`` must
+ be enabled. If ``ENABLE_PMF`` is set, the residency statistics are tracked in
+ software.
+
+- ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime
+ instrumentation which injects timestamp collection points into TF-A to
+ allow runtime performance to be measured. Currently, only PSCI is
+ instrumented. Enabling this option enables the ``ENABLE_PMF`` build option
+ as well. Default is 0.
+
+- ``ENABLE_SPE_FOR_LOWER_ELS`` : Boolean option to enable Statistical Profiling
+ extensions. This is an optional architectural feature for AArch64.
+ The default is 1 but is automatically disabled when the target architecture
+ is AArch32.
+
+- ``ENABLE_SPM`` : Boolean option to enable the Secure Partition Manager (SPM).
+ Refer to :ref:`Secure Partition Manager` for more details about
+ this feature. Default is 0.
+
+- ``ENABLE_SVE_FOR_NS``: Boolean option to enable Scalable Vector Extension
+ (SVE) for the Non-secure world only. SVE is an optional architectural feature
+ for AArch64. Note that when SVE is enabled for the Non-secure world, access
+ to SIMD and floating-point functionality from the Secure world is disabled.
+ This is to avoid corruption of the Non-secure world data in the Z-registers
+ which are aliased by the SIMD and FP registers. The build option is not
+ compatible with the ``CTX_INCLUDE_FPREGS`` build option, and will raise an
+ assert on platforms where SVE is implemented and ``ENABLE_SVE_FOR_NS`` set to
+ 1. The default is 1 but is automatically disabled when the target
+ architecture is AArch32.
+
+- ``ENABLE_STACK_PROTECTOR``: String option to enable the stack protection
+ checks in GCC. Allowed values are "all", "strong", "default" and "none". The
+ default value is set to "none". "strong" is the recommended stack protection
+ level if this feature is desired. "none" disables the stack protection. For
+ all values other than "none", the ``plat_get_stack_protector_canary()``
+ platform hook needs to be implemented. The value is passed as the last
+ component of the option ``-fstack-protector-$ENABLE_STACK_PROTECTOR``.
+
+- ``ERROR_DEPRECATED``: This option decides whether to treat the usage of
+ deprecated platform APIs, helper functions or drivers within Trusted
+ Firmware as error. It can take the value 1 (flag the use of deprecated
+ APIs as error) or 0. The default is 0.
+
+- ``EL3_EXCEPTION_HANDLING``: When set to ``1``, enable handling of exceptions
+ targeted at EL3. When set ``0`` (default), no exceptions are expected or
+ handled at EL3, and a panic will result. This is supported only for AArch64
+ builds.
+
+- ``FAULT_INJECTION_SUPPORT``: ARMv8.4 extensions introduced support for fault
+ injection from lower ELs, and this build option enables lower ELs to use
+ Error Records accessed via System Registers to inject faults. This is
+ applicable only to AArch64 builds.
+
+ This feature is intended for testing purposes only, and is advisable to keep
+ disabled for production images.
+
+- ``FIP_NAME``: This is an optional build option which specifies the FIP
+ filename for the ``fip`` target. Default is ``fip.bin``.
+
+- ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU
+ FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``.
+
+- ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create``
+ tool to create certificates as per the Chain of Trust described in
+ :ref:`Trusted Board Boot`. The build system then calls ``fiptool`` to
+ include the certificates in the FIP and FWU_FIP. Default value is '0'.
+
+ Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support
+ for the Trusted Board Boot feature in the BL1 and BL2 images, to generate
+ the corresponding certificates, and to include those certificates in the
+ FIP and FWU_FIP.
+
+ Note that if ``TRUSTED_BOARD_BOOT=0`` and ``GENERATE_COT=1``, the BL1 and BL2
+ images will not include support for Trusted Board Boot. The FIP will still
+ include the corresponding certificates. This FIP can be used to verify the
+ Chain of Trust on the host machine through other mechanisms.
+
+ Note that if ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=0``, the BL1 and BL2
+ images will include support for Trusted Board Boot, but the FIP and FWU_FIP
+ will not include the corresponding certificates, causing a boot failure.
+
+- ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have
+ inherent support for specific EL3 type interrupts. Setting this build option
+ to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both
+ by `platform abstraction layer`__ and `Interrupt Management Framework`__.
+ This allows GICv2 platforms to enable features requiring EL3 interrupt type.
+ This also means that all GICv2 Group 0 interrupts are delivered to EL3, and
+ the Secure Payload interrupts needs to be synchronously handed over to Secure
+ EL1 for handling. The default value of this option is ``0``, which means the
+ Group 0 interrupts are assumed to be handled by Secure EL1.
+
+ .. __: `platform-interrupt-controller-API.rst`
+ .. __: `interrupt-framework-design.rst`
+
+- ``HANDLE_EA_EL3_FIRST``: When set to ``1``, External Aborts and SError
+ Interrupts will be always trapped in EL3 i.e. in BL31 at runtime. When set to
+ ``0`` (default), these exceptions will be trapped in the current exception
+ level (or in EL1 if the current exception level is EL0).
+
+- ``HW_ASSISTED_COHERENCY``: On most Arm systems to-date, platform-specific
+ software operations are required for CPUs to enter and exit coherency.
+ However, newer systems exist where CPUs' entry to and exit from coherency
+ is managed in hardware. Such systems require software to only initiate these
+ operations, and the rest is managed in hardware, minimizing active software
+ management. In such systems, this boolean option enables TF-A to carry out
+ build and run-time optimizations during boot and power management operations.
+ This option defaults to 0 and if it is enabled, then it implies
+ ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled.
+
+ If this flag is disabled while the platform which TF-A is compiled for
+ includes cores that manage coherency in hardware, then a compilation error is
+ generated. This is based on the fact that a system cannot have, at the same
+ time, cores that manage coherency in hardware and cores that don't. In other
+ words, a platform cannot have, at the same time, cores that require
+ ``HW_ASSISTED_COHERENCY=1`` and cores that require
+ ``HW_ASSISTED_COHERENCY=0``.
+
+ Note that, when ``HW_ASSISTED_COHERENCY`` is enabled, version 2 of
+ translation library (xlat tables v2) must be used; version 1 of translation
+ library is not supported.
+
+- ``JUNO_AARCH32_EL3_RUNTIME``: This build flag enables you to execute EL3
+ runtime software in AArch32 mode, which is required to run AArch32 on Juno.
+ By default this flag is set to '0'. Enabling this flag builds BL1 and BL2 in
+ AArch64 and facilitates the loading of ``SP_MIN`` and BL33 as AArch32 executable
+ images.
+
+- ``KEY_ALG``: This build flag enables the user to select the algorithm to be
+ used for generating the PKCS keys and subsequent signing of the certificate.
+ It accepts 3 values: ``rsa``, ``rsa_1_5`` and ``ecdsa``. The option
+ ``rsa_1_5`` is the legacy PKCS#1 RSA 1.5 algorithm which is not TBBR
+ compliant and is retained only for compatibility. The default value of this
+ flag is ``rsa`` which is the TBBR compliant PKCS#1 RSA 2.1 scheme.
+
+- ``HASH_ALG``: This build flag enables the user to select the secure hash
+ algorithm. It accepts 3 values: ``sha256``, ``sha384`` and ``sha512``.
+ The default value of this flag is ``sha256``.
+
+- ``LDFLAGS``: Extra user options appended to the linkers' command line in
+ addition to the one set by the build system.
+
+- ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log
+ output compiled into the build. This should be one of the following:
+
+ ::
+
+ 0 (LOG_LEVEL_NONE)
+ 10 (LOG_LEVEL_ERROR)
+ 20 (LOG_LEVEL_NOTICE)
+ 30 (LOG_LEVEL_WARNING)
+ 40 (LOG_LEVEL_INFO)
+ 50 (LOG_LEVEL_VERBOSE)
+
+ All log output up to and including the selected log level is compiled into
+ the build. The default value is 40 in debug builds and 20 in release builds.
+
+- ``NON_TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
+ specifies the file that contains the Non-Trusted World private key in PEM
+ format. If ``SAVE_KEYS=1``, this file name will be used to save the key.
+
+- ``NS_BL2U``: Path to NS_BL2U image in the host file system. This image is
+ optional. It is only needed if the platform makefile specifies that it
+ is required in order to build the ``fwu_fip`` target.
+
+- ``NS_TIMER_SWITCH``: Enable save and restore for non-secure timer register
+ contents upon world switch. It can take either 0 (don't save and restore) or
+ 1 (do save and restore). 0 is the default. An SPD may set this to 1 if it
+ wants the timer registers to be saved and restored.
+
+- ``OVERRIDE_LIBC``: This option allows platforms to override the default libc
+ for the BL image. It can be either 0 (include) or 1 (remove). The default
+ value is 0.
+
+- ``PL011_GENERIC_UART``: Boolean option to indicate the PL011 driver that
+ the underlying hardware is not a full PL011 UART but a minimally compliant
+ generic UART, which is a subset of the PL011. The driver will not access
+ any register that is not part of the SBSA generic UART specification.
+ Default value is 0 (a full PL011 compliant UART is present).
+
+- ``PLAT``: Choose a platform to build TF-A for. The chosen platform name
+ must be subdirectory of any depth under ``plat/``, and must contain a
+ platform makefile named ``platform.mk``. For example, to build TF-A for the
+ Arm Juno board, select PLAT=juno.
+
+- ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image
+ instead of the normal boot flow. When defined, it must specify the entry
+ point address for the preloaded BL33 image. This option is incompatible with
+ ``EL3_PAYLOAD_BASE``. If both are defined, ``EL3_PAYLOAD_BASE`` has priority
+ over ``PRELOADED_BL33_BASE``.
+
+- ``PROGRAMMABLE_RESET_ADDRESS``: This option indicates whether the reset
+ vector address can be programmed or is fixed on the platform. It can take
+ either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a
+ programmable reset address, it is expected that a CPU will start executing
+ code directly at the right address, both on a cold and warm reset. In this
+ case, there is no need to identify the entrypoint on boot and the boot path
+ can be optimised. The ``plat_get_my_entrypoint()`` platform porting interface
+ does not need to be implemented in this case.
+
+- ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats
+ possible for the PSCI power-state parameter: original and extended State-ID
+ formats. This flag if set to 1, configures the generic PSCI layer to use the
+ extended format. The default value of this flag is 0, which means by default
+ the original power-state format is used by the PSCI implementation. This flag
+ should be specified by the platform makefile and it governs the return value
+ of PSCI_FEATURES API for CPU_SUSPEND smc function id. When this option is
+ enabled on Arm platforms, the option ``ARM_RECOM_STATE_ID_ENC`` needs to be
+ set to 1 as well.
+
+- ``RAS_EXTENSION``: When set to ``1``, enable Armv8.2 RAS features. RAS features
+ are an optional extension for pre-Armv8.2 CPUs, but are mandatory for Armv8.2
+ or later CPUs.
+
+ When ``RAS_EXTENSION`` is set to ``1``, ``HANDLE_EA_EL3_FIRST`` must also be
+ set to ``1``.
+
+ This option is disabled by default.
+
+- ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead
+ of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
+ entrypoint) or 1 (CPU reset to BL31 entrypoint).
+ The default value is 0.
+
+- ``RESET_TO_SP_MIN``: SP_MIN is the minimal AArch32 Secure Payload provided
+ in TF-A. This flag configures SP_MIN entrypoint as the CPU reset vector
+ instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
+ entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default value is 0.
+
+- ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
+ file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this
+ file name will be used to save the key.
+
+- ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
+ certificate generation tool to save the keys used to establish the Chain of
+ Trust. Allowed options are '0' or '1'. Default is '0' (do not save).
+
+- ``SCP_BL2``: Path to SCP_BL2 image in the host file system. This image is optional.
+ If a SCP_BL2 image is present then this option must be passed for the ``fip``
+ target.
+
+- ``SCP_BL2_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
+ file that contains the SCP_BL2 private key in PEM format. If ``SAVE_KEYS=1``,
+ this file name will be used to save the key.
+
+- ``SCP_BL2U``: Path to SCP_BL2U image in the host file system. This image is
+ optional. It is only needed if the platform makefile specifies that it
+ is required in order to build the ``fwu_fip`` target.
+
+- ``SDEI_SUPPORT``: Setting this to ``1`` enables support for Software
+ Delegated Exception Interface to BL31 image. This defaults to ``0``.
+
+ When set to ``1``, the build option ``EL3_EXCEPTION_HANDLING`` must also be
+ set to ``1``.
+
+- ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be
+ isolated on separate memory pages. This is a trade-off between security and
+ memory usage. See "Isolating code and read-only data on separate memory
+ pages" section in :ref:`Firmware Design`. This flag is disabled by default and
+ affects all BL images.
+
+- ``SPD``: Choose a Secure Payload Dispatcher component to be built into TF-A.
+ This build option is only valid if ``ARCH=aarch64``. The value should be
+ the path to the directory containing the SPD source, relative to
+ ``services/spd/``; the directory is expected to contain a makefile called
+ ``<spd-value>.mk``.
+
+- ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can
+ take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops
+ execution in BL1 just before handing over to BL31. At this point, all
+ firmware images have been loaded in memory, and the MMU and caches are
+ turned off. Refer to the "Debugging options" section for more details.
+
+- ``SP_MIN_WITH_SECURE_FIQ``: Boolean flag to indicate the SP_MIN handles
+ secure interrupts (caught through the FIQ line). Platforms can enable
+ this directive if they need to handle such interruption. When enabled,
+ the FIQ are handled in monitor mode and non secure world is not allowed
+ to mask these events. Platforms that enable FIQ handling in SP_MIN shall
+ implement the api ``sp_min_plat_fiq_handler()``. The default value is 0.
+
+- ``TRUSTED_BOARD_BOOT``: Boolean flag to include support for the Trusted Board
+ Boot feature. When set to '1', BL1 and BL2 images include support to load
+ and verify the certificates and images in a FIP, and BL1 includes support
+ for the Firmware Update. The default value is '0'. Generation and inclusion
+ of certificates in the FIP and FWU_FIP depends upon the value of the
+ ``GENERATE_COT`` option.
+
+ .. warning::
+ This option depends on ``CREATE_KEYS`` to be enabled. If the keys
+ already exist in disk, they will be overwritten without further notice.
+
+- ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
+ specifies the file that contains the Trusted World private key in PEM
+ format. If ``SAVE_KEYS=1``, this file name will be used to save the key.
+
+- ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or
+ synchronous, (see "Initializing a BL32 Image" section in
+ :ref:`Firmware Design`). It can take the value 0 (BL32 is initialized using
+ synchronous method) or 1 (BL32 is initialized using asynchronous method).
+ Default is 0.
+
+- ``TSP_NS_INTR_ASYNC_PREEMPT``: A non zero value enables the interrupt
+ routing model which routes non-secure interrupts asynchronously from TSP
+ to EL3 causing immediate preemption of TSP. The EL3 is responsible
+ for saving and restoring the TSP context in this routing model. The
+ default routing model (when the value is 0) is to route non-secure
+ interrupts to TSP allowing it to save its context and hand over
+ synchronously to EL3 via an SMC.
+
+ .. note::
+ When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT``
+ must also be set to ``1``.
+
+- ``USE_ARM_LINK``: This flag determines whether to enable support for ARM
+ linker. When the ``LINKER`` build variable points to the armlink linker,
+ this flag is enabled automatically. To enable support for armlink, platforms
+ will have to provide a scatter file for the BL image. Currently, Tegra
+ platforms use the armlink support to compile BL3-1 images.
+
+- ``USE_COHERENT_MEM``: This flag determines whether to include the coherent
+ memory region in the BL memory map or not (see "Use of Coherent memory in
+ TF-A" section in :ref:`Firmware Design`). It can take the value 1
+ (Coherent memory region is included) or 0 (Coherent memory region is
+ excluded). Default is 1.
+
+- ``USE_ROMLIB``: This flag determines whether library at ROM will be used.
+ This feature creates a library of functions to be placed in ROM and thus
+ reduces SRAM usage. Refer to :ref:`Library at ROM` for further details. Default
+ is 0.
+
+- ``V``: Verbose build. If assigned anything other than 0, the build commands
+ are printed. Default is 0.
+
+- ``VERSION_STRING``: String used in the log output for each TF-A image.
+ Defaults to a string formed by concatenating the version number, build type
+ and build string.
+
+- ``W``: Warning level. Some compiler warning options of interest have been
+ regrouped and put in the root Makefile. This flag can take the values 0 to 3,
+ each level enabling more warning options. Default is 0.
+
+- ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on
+ the CPU after warm boot. This is applicable for platforms which do not
+ require interconnect programming to enable cache coherency (eg: single
+ cluster platforms). If this option is enabled, then warm boot path
+ enables D-caches immediately after enabling MMU. This option defaults to 0.
+
+Debugging options
+-----------------
+
+To compile a debug version and make the build more verbose use
+
+.. code:: shell
+
+ make PLAT=<platform> DEBUG=1 V=1 all
+
+AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for
+example DS-5) might not support this and may need an older version of DWARF
+symbols to be emitted by GCC. This can be achieved by using the
+``-gdwarf-<version>`` flag, with the version being set to 2 or 3. Setting the
+version to 2 is recommended for DS-5 versions older than 5.16.
+
+When debugging logic problems it might also be useful to disable all compiler
+optimizations by using ``-O0``.
+
+.. warning::
+ Using ``-O0`` could cause output images to be larger and base addresses
+ might need to be recalculated (see the **Memory layout on Arm development
+ platforms** section in the :ref:`Firmware Design`).
+
+Extra debug options can be passed to the build system by setting ``CFLAGS`` or
+``LDFLAGS``:
+
+.. code:: shell
+
+ CFLAGS='-O0 -gdwarf-2' \
+ make PLAT=<platform> DEBUG=1 V=1 all
+
+Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be
+ignored as the linker is called directly.
+
+It is also possible to introduce an infinite loop to help in debugging the
+post-BL2 phase of TF-A. This can be done by rebuilding BL1 with the
+``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the :ref:`build_options_common`
+section. In this case, the developer may take control of the target using a
+debugger when indicated by the console output. When using DS-5, the following
+commands can be used:
+
+::
+
+ # Stop target execution
+ interrupt
+
+ #
+ # Prepare your debugging environment, e.g. set breakpoints
+ #
+
+ # Jump over the debug loop
+ set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4
+
+ # Resume execution
+ continue
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst
index fa07642..c5625e9 100644
--- a/docs/getting_started/docs-build.rst
+++ b/docs/getting_started/docs-build.rst
@@ -22,6 +22,9 @@
- Python 3 (3.5 or later)
- PlantUML (1.2017.15 or later)
+Optionally, the `Dia`_ application can be installed if you need to edit
+existing ``.dia`` diagram files, or create new ones.
+
You must also install the Python modules that are specified in the
``requirements.txt`` file in the root of the ``docs`` directory. These modules
can be installed using ``pip3`` (the Python Package Installer). Passing this
@@ -33,7 +36,7 @@
.. code:: shell
- sudo apt install python3 python3-pip plantuml
+ sudo apt install python3 python3-pip plantuml [dia]
pip3 install [--user] -r requirements.txt
.. note::
@@ -75,3 +78,4 @@
.. _Sphinx: http://www.sphinx-doc.org/en/master/
.. _pip homepage: https://pip.pypa.io/en/stable/
+.. _Dia: https://wiki.gnome.org/Apps/Dia
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index 07e3753..817beaf 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -6,9 +6,16 @@
:caption: Contents
:numbered:
- user-guide
+ prerequisites
docs-build
+ tools-build
+ initial-build
+ build-options
image-terminology
porting-guide
psci-lib-integration-guide
rt-svc-writers-guide
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/initial-build.rst b/docs/getting_started/initial-build.rst
new file mode 100644
index 0000000..41cd4d1
--- /dev/null
+++ b/docs/getting_started/initial-build.rst
@@ -0,0 +1,117 @@
+Performing an Initial Build
+===========================
+
+- Before building TF-A, the environment variable ``CROSS_COMPILE`` must point
+ to the Linaro cross compiler.
+
+ For AArch64:
+
+ .. code:: shell
+
+ export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
+
+ For AArch32:
+
+ .. code:: shell
+
+ export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-eabi-
+
+ It is possible to build TF-A using Clang or Arm Compiler 6. To do so
+ ``CC`` needs to point to the clang or armclang binary, which will
+ also select the clang or armclang assembler. Be aware that the
+ GNU linker is used by default. In case of being needed the linker
+ can be overridden using the ``LD`` variable. Clang linker version 6 is
+ known to work with TF-A.
+
+ In both cases ``CROSS_COMPILE`` should be set as described above.
+
+ Arm Compiler 6 will be selected when the base name of the path assigned
+ to ``CC`` matches the string 'armclang'.
+
+ For AArch64 using Arm Compiler 6:
+
+ .. code:: shell
+
+ export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
+ make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all
+
+ Clang will be selected when the base name of the path assigned to ``CC``
+ contains the string 'clang'. This is to allow both clang and clang-X.Y
+ to work.
+
+ For AArch64 using clang:
+
+ .. code:: shell
+
+ export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
+ make CC=<path-to-clang>/bin/clang PLAT=<platform> all
+
+- Change to the root directory of the TF-A source tree and build.
+
+ For AArch64:
+
+ .. code:: shell
+
+ make PLAT=<platform> all
+
+ For AArch32:
+
+ .. code:: shell
+
+ make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all
+
+ Notes:
+
+ - If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the
+ :ref:`Build Options` document for more information on available build
+ options.
+
+ - (AArch32 only) Currently only ``PLAT=fvp`` is supported.
+
+ - (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it
+ corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp_min, is
+ provided by TF-A to demonstrate how PSCI Library can be integrated with
+ an AArch32 EL3 Runtime Software. Some AArch32 EL3 Runtime Software may
+ include other runtime services, for example Trusted OS services. A guide
+ to integrate PSCI library with AArch32 EL3 Runtime Software can be found
+ at :ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`.
+
+ - (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
+ image, is not compiled in by default. Refer to the
+ :ref:`Test Secure Payload (TSP) and Dispatcher (TSPD)` document for
+ details on building the TSP.
+
+ - By default this produces a release version of the build. To produce a
+ debug version instead, refer to the "Debugging options" section below.
+
+ - The build process creates products in a ``build`` directory tree, building
+ the objects and binaries for each boot loader stage in separate
+ sub-directories. The following boot loader binary files are created
+ from the corresponding ELF files:
+
+ - ``build/<platform>/<build-type>/bl1.bin``
+ - ``build/<platform>/<build-type>/bl2.bin``
+ - ``build/<platform>/<build-type>/bl31.bin`` (AArch64 only)
+ - ``build/<platform>/<build-type>/bl32.bin`` (mandatory for AArch32)
+
+ where ``<platform>`` is the name of the chosen platform and ``<build-type>``
+ is either ``debug`` or ``release``. The actual number of images might differ
+ depending on the platform.
+
+- Build products for a specific build variant can be removed using:
+
+ .. code:: shell
+
+ make DEBUG=<D> PLAT=<platform> clean
+
+ ... where ``<D>`` is ``0`` or ``1``, as specified when building.
+
+ The build tree can be removed completely using:
+
+ .. code:: shell
+
+ make realclean
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 9cca75e..17fd546 100644
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -23,8 +23,6 @@
discusses these in detail. The subsequent sections discuss the remaining
modifications for each BL stage in detail.
-This document should be read in conjunction with the TF-A :ref:`User Guide`.
-
Please refer to the :ref:`Platform Compatibility Policy` for the policy
regarding compatibility and deprecation of these porting interfaces.
@@ -2387,8 +2385,8 @@
`Arm Generic Interrupt Controller version 2.0 (GICv2)`_
and `3.0 (GICv3)`_. Juno builds the Arm platform layer to use GICv2 and the
FVP can be configured to use either GICv2 or GICv3 depending on the build flag
-``FVP_USE_GIC_DRIVER`` (See FVP platform specific build options in
-:ref:`User Guide` for more details).
+``FVP_USE_GIC_DRIVER`` (See :ref:`build_options_arm_fvp_platform` for more
+details).
See also: `Interrupt Controller Abstraction APIs`__.
@@ -2796,10 +2794,10 @@
It is mandatory to implement at least one storage driver. For the Arm
development platforms the Firmware Image Package (FIP) driver is provided as
-the default means to load data from storage (see the "Firmware Image Package"
-section in the :ref:`User Guide`). The storage layer is described in the header file
-``include/drivers/io/io_storage.h``. The implementation of the common library
-is in ``drivers/io/io_storage.c`` and the driver files are located in
+the default means to load data from storage (see :ref:`firmware_design_fip`).
+The storage layer is described in the header file
+``include/drivers/io/io_storage.h``. The implementation of the common library is
+in ``drivers/io/io_storage.c`` and the driver files are located in
``drivers/io/``.
.. uml:: ../resources/diagrams/plantuml/io_arm_class_diagram.puml
diff --git a/docs/getting_started/prerequisites.rst b/docs/getting_started/prerequisites.rst
new file mode 100644
index 0000000..27ad0ed
--- /dev/null
+++ b/docs/getting_started/prerequisites.rst
@@ -0,0 +1,136 @@
+Prerequisites
+=============
+
+This document describes the software requirements for building |TF-A| for
+AArch32 and AArch64 target platforms.
+
+It may possible to build |TF-A| with combinations of software packages that are
+different from those listed below, however only the software described in this
+document can be officially supported.
+
+Build Host
+----------
+
+|TF-A| can be built using either a Linux or a Windows machine as the build host.
+
+A relatively recent Linux distribution is recommended for building |TF-A|. We
+have performed tests using Ubuntu 16.04 LTS (64-bit) but other distributions
+should also work fine as a base, provided that the necessary tools and libraries
+can be installed.
+
+.. _prerequisites_toolchain:
+
+Toolchain
+---------
+
+|TF-A| can be built with any of the following *cross-compiler* toolchains that
+target the Armv7-A or Armv8-A architectures:
+
+- GCC >= 8.3-2019.03 (from the `Arm Developer website`_)
+- Clang >= 4.0
+- Arm Compiler >= 6.0
+
+In addition, a native compiler is required to build the supporting tools.
+
+.. note::
+ The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE,
+ Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain.
+
+.. note::
+ For instructions on how to select the cross compiler refer to
+ :ref:`Performing an Initial Build`.
+
+.. _prerequisites_software_and_libraries:
+
+Software and Libraries
+----------------------
+
+The following tools are required to obtain and build |TF-A|:
+
+- An appropriate toolchain (see :ref:`prerequisites_toolchain`)
+- GNU Make
+- Git
+
+The following libraries must be available to build one or more components or
+supporting tools:
+
+- OpenSSL >= 1.0.1
+
+ Required to build the cert_create tool.
+
+The following libraries are required for Trusted Board Boot support:
+
+- mbed TLS == 2.16.2 (tag: ``mbedtls-2.16.2``)
+
+These tools are optional:
+
+- Device Tree Compiler (DTC) >= 1.4.6
+
+ Needed if you want to rebuild the provided Flattened Device Tree (FDT)
+ source files (``.dts`` files). DTC is available for Linux through the package
+ repositories of most distributions.
+
+- Arm `Development Studio 5 (DS-5)`_
+
+ The standard software package used for debugging software on Arm development
+ platforms and |FVP| models.
+
+Package Installation (Linux)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are using the recommended Ubuntu distribution then you can install the
+required packages with the following command:
+
+.. code:: shell
+
+ sudo apt install build-essential git libssl-dev
+
+The optional packages can be installed using:
+
+.. code:: shell
+
+ sudo apt install device-tree-compiler
+
+Supporting Files
+----------------
+
+TF-A has been tested with pre-built binaries and file systems from `Linaro
+Release 19.06`_. Alternatively, you can build the binaries from source using
+instructions in :ref:`Performing an Initial Build`.
+
+.. _prerequisites_get_source:
+
+Getting the TF-A Source
+-----------------------
+
+Source code for |TF-A| is maintained in a Git repository hosted on
+TrustedFirmware.org. To clone this repository from the server, run the following
+in your shell:
+
+.. code:: shell
+
+ git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a" && (cd "trusted-firmware-a" && mkdir -p .git/hooks && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg; chmod +x `git rev-parse --git-dir`/hooks/commit-msg)
+
+This will clone the Git repository also install a *commit hook* that
+automatically inserts appropriate *Change-Id:* lines at the end of your
+commit messages. These change IDs are required when committing changes that you
+intend to push for review via our Gerrit system.
+
+You can read more about Git hooks in the *githooks* page of the Git documentation,
+available at: https://git-scm.com/docs/githooks
+
+Alternatively, you can clone without the commit hook using:
+
+.. code:: shell
+
+ git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a"
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _Arm Developer website: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
+.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
+.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables
+.. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio
+.. _Linaro Release 19.06: http://releases.linaro.org/members/arm/platforms/19.06
diff --git a/docs/getting_started/tools-build.rst b/docs/getting_started/tools-build.rst
new file mode 100644
index 0000000..bb707cb
--- /dev/null
+++ b/docs/getting_started/tools-build.rst
@@ -0,0 +1,140 @@
+Building Supporting Tools
+=========================
+
+Building and using the FIP tool
+-------------------------------
+
+Firmware Image Package (FIP) is a packaging format used by TF-A to package
+firmware images in a single binary. The number and type of images that should
+be packed in a FIP is platform specific and may include TF-A images and other
+firmware images required by the platform. For example, most platforms require
+a BL33 image which corresponds to the normal world bootloader (e.g. UEFI or
+U-Boot).
+
+The TF-A build system provides the make target ``fip`` to create a FIP file
+for the specified platform using the FIP creation tool included in the TF-A
+project. Examples below show how to build a FIP file for FVP, packaging TF-A
+and BL33 images.
+
+For AArch64:
+
+.. code:: shell
+
+ make PLAT=fvp BL33=<path-to>/bl33.bin fip
+
+For AArch32:
+
+.. code:: shell
+
+ make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip
+
+The resulting FIP may be found in:
+
+::
+
+ build/fvp/<build-type>/fip.bin
+
+For advanced operations on FIP files, it is also possible to independently build
+the tool and create or modify FIPs using this tool. To do this, follow these
+steps:
+
+It is recommended to remove old artifacts before building the tool:
+
+.. code:: shell
+
+ make -C tools/fiptool clean
+
+Build the tool:
+
+.. code:: shell
+
+ make [DEBUG=1] [V=1] fiptool
+
+The tool binary can be located in:
+
+::
+
+ ./tools/fiptool/fiptool
+
+Invoking the tool with ``help`` will print a help message with all available
+options.
+
+Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31:
+
+.. code:: shell
+
+ ./tools/fiptool/fiptool create \
+ --tb-fw build/<platform>/<build-type>/bl2.bin \
+ --soc-fw build/<platform>/<build-type>/bl31.bin \
+ fip.bin
+
+Example 2: view the contents of an existing Firmware package:
+
+.. code:: shell
+
+ ./tools/fiptool/fiptool info <path-to>/fip.bin
+
+Example 3: update the entries of an existing Firmware package:
+
+.. code:: shell
+
+ # Change the BL2 from Debug to Release version
+ ./tools/fiptool/fiptool update \
+ --tb-fw build/<platform>/release/bl2.bin \
+ build/<platform>/debug/fip.bin
+
+Example 4: unpack all entries from an existing Firmware package:
+
+.. code:: shell
+
+ # Images will be unpacked to the working directory
+ ./tools/fiptool/fiptool unpack <path-to>/fip.bin
+
+Example 5: remove an entry from an existing Firmware package:
+
+.. code:: shell
+
+ ./tools/fiptool/fiptool remove \
+ --tb-fw build/<platform>/debug/fip.bin
+
+Note that if the destination FIP file exists, the create, update and
+remove operations will automatically overwrite it.
+
+The unpack operation will fail if the images already exist at the
+destination. In that case, use -f or --force to continue.
+
+More information about FIP can be found in the :ref:`Firmware Design` document.
+
+.. _tools_build_cert_create:
+
+Building the Certificate Generation Tool
+----------------------------------------
+
+The ``cert_create`` tool is built as part of the TF-A build process when the
+``fip`` make target is specified and TBB is enabled (as described in the
+previous section), but it can also be built separately with the following
+command:
+
+.. code:: shell
+
+ make PLAT=<platform> [DEBUG=1] [V=1] certtool
+
+For platforms that require their own IDs in certificate files, the generic
+'cert_create' tool can be built with the following command. Note that the target
+platform must define its IDs within a ``platform_oid.h`` header file for the
+build to succeed.
+
+.. code:: shell
+
+ make PLAT=<platform> USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool
+
+``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
+verbose. The following command should be used to obtain help about the tool:
+
+.. code:: shell
+
+ ./tools/cert_create/cert_create -h
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst
deleted file mode 100644
index 9876531..0000000
--- a/docs/getting_started/user-guide.rst
+++ /dev/null
@@ -1,2214 +0,0 @@
-User Guide
-==========
-
-This document describes how to build Trusted Firmware-A (TF-A) and run it with a
-tested set of other software components using defined configurations on the Juno
-Arm development platform and Arm Fixed Virtual Platform (FVP) models. It is
-possible to use other software components, configurations and platforms but that
-is outside the scope of this document.
-
-This document assumes that the reader has previous experience running a fully
-bootable Linux software stack on Juno or FVP using the prebuilt binaries and
-filesystems provided by Linaro. Further information may be found in the
-`Linaro instructions`_. It also assumes that the user understands the role of
-the different software components required to boot a Linux system:
-
-- Specific firmware images required by the platform (e.g. SCP firmware on Juno)
-- Normal world bootloader (e.g. UEFI or U-Boot)
-- Device tree
-- Linux kernel image
-- Root filesystem
-
-This document also assumes that the user is familiar with the `FVP models`_ and
-the different command line options available to launch the model.
-
-This document should be used in conjunction with the :ref:`Firmware Design`.
-
-Host machine requirements
--------------------------
-
-The minimum recommended machine specification for building the software and
-running the FVP models is a dual-core processor running at 2GHz with 12GB of
-RAM. For best performance, use a machine with a quad-core processor running at
-2.6GHz with 16GB of RAM.
-
-The software has been tested on Ubuntu 16.04 LTS (64-bit). Packages used for
-building the software were installed from that distribution unless otherwise
-specified.
-
-The software has also been built on Windows 7 Enterprise SP1, using CMD.EXE,
-Cygwin, and Msys (MinGW) shells, using version 5.3.1 of the GNU toolchain.
-
-Tools
------
-
-Install the required packages to build TF-A with the following command:
-
-.. code:: shell
-
- sudo apt-get install device-tree-compiler build-essential gcc make git libssl-dev
-
-Download and install the AArch32 (arm-eabi) or AArch64 little-endian
-(aarch64-linux-gnu) GCC 8.3-2019.03 cross compiler from `Arm Developer page`_.
-
-Optionally, TF-A can be built using clang version 4.0 or newer or Arm
-Compiler 6. See instructions below on how to switch the default compiler.
-
-In addition, the following optional packages and tools may be needed:
-
-- ``device-tree-compiler`` (dtc) package if you need to rebuild the Flattened Device
- Tree (FDT) source files (``.dts`` files) provided with this software. The
- version of dtc must be 1.4.6 or above.
-
-- For debugging, Arm `Development Studio 5 (DS-5)`_.
-
-- To create and modify the diagram files included in the documentation, `Dia`_.
- This tool can be found in most Linux distributions. Inkscape is needed to
- generate the actual \*.png files.
-
-TF-A has been tested with pre-built binaries and file systems from
-`Linaro Release 19.06`_. Alternatively, you can build the binaries from
-source using instructions provided at the `Arm Platforms User guide`_.
-
-Getting the TF-A source code
-----------------------------
-
-Clone the repository from the Gerrit server. The project details may be found
-on the `arm-trusted-firmware-a project page`_. We recommend the "`Clone with
-commit-msg hook`" clone method, which will setup the git commit hook that
-automatically generates and inserts appropriate `Change-Id:` lines in your
-commit messages.
-
-Checking source code style
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Trusted Firmware follows the `Linux Coding Style`_ . When making changes to the
-source, for submission to the project, the source must be in compliance with
-this style guide.
-
-Additional, project-specific guidelines are defined in the
-:ref:`Coding Style & Guidelines` document.
-
-To assist with coding style compliance, the project Makefile contains two
-targets which both utilise the `checkpatch.pl` script that ships with the Linux
-source tree. The project also defines certain *checkpatch* options in the
-``.checkpatch.conf`` file in the top-level directory.
-
-.. note::
- Checkpatch errors will gate upstream merging of pull requests.
- Checkpatch warnings will not gate merging but should be reviewed and fixed if
- possible.
-
-To check the entire source tree, you must first download copies of
-``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available
-in the `Linux master tree`_ *scripts* directory, then set the ``CHECKPATCH``
-environment variable to point to ``checkpatch.pl`` (with the other 2 files in
-the same directory) and build the `checkcodebase` target:
-
-.. code:: shell
-
- make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase
-
-To just check the style on the files that differ between your local branch and
-the remote master, use:
-
-.. code:: shell
-
- make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch
-
-If you wish to check your patch against something other than the remote master,
-set the ``BASE_COMMIT`` variable to your desired branch. By default, ``BASE_COMMIT``
-is set to ``origin/master``.
-
-Building TF-A
--------------
-
-- Before building TF-A, the environment variable ``CROSS_COMPILE`` must point
- to the cross compiler.
-
- For AArch64:
-
- .. code:: shell
-
- export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
-
- For AArch32:
-
- .. code:: shell
-
- export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-eabi-
-
- It is possible to build TF-A using Clang or Arm Compiler 6. To do so
- ``CC`` needs to point to the clang or armclang binary, which will
- also select the clang or armclang assembler. Be aware that the
- GNU linker is used by default. In case of being needed the linker
- can be overridden using the ``LD`` variable. Clang linker version 6 is
- known to work with TF-A.
-
- In both cases ``CROSS_COMPILE`` should be set as described above.
-
- Arm Compiler 6 will be selected when the base name of the path assigned
- to ``CC`` matches the string 'armclang'.
-
- For AArch64 using Arm Compiler 6:
-
- .. code:: shell
-
- export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
- make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all
-
- Clang will be selected when the base name of the path assigned to ``CC``
- contains the string 'clang'. This is to allow both clang and clang-X.Y
- to work.
-
- For AArch64 using clang:
-
- .. code:: shell
-
- export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
- make CC=<path-to-clang>/bin/clang PLAT=<platform> all
-
-- Change to the root directory of the TF-A source tree and build.
-
- For AArch64:
-
- .. code:: shell
-
- make PLAT=<platform> all
-
- For AArch32:
-
- .. code:: shell
-
- make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all
-
- Notes:
-
- - If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the
- `Summary of build options`_ for more information on available build
- options.
-
- - (AArch32 only) ``AARCH32_SP`` is the AArch32 EL3 Runtime Software and it
- corresponds to the BL32 image. A minimal ``AARCH32_SP``, sp_min, is
- provided by TF-A to demonstrate how PSCI Library can be integrated with
- an AArch32 EL3 Runtime Software. Some AArch32 EL3 Runtime Software may
- include other runtime services, for example Trusted OS services. A guide
- to integrate PSCI library with AArch32 EL3 Runtime Software can be found
- at :ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`.
-
- - (AArch64 only) The TSP (Test Secure Payload), corresponding to the BL32
- image, is not compiled in by default. Refer to the
- `Building the Test Secure Payload`_ section below.
-
- - By default this produces a release version of the build. To produce a
- debug version instead, refer to the "Debugging options" section below.
-
- - The build process creates products in a ``build`` directory tree, building
- the objects and binaries for each boot loader stage in separate
- sub-directories. The following boot loader binary files are created
- from the corresponding ELF files:
-
- - ``build/<platform>/<build-type>/bl1.bin``
- - ``build/<platform>/<build-type>/bl2.bin``
- - ``build/<platform>/<build-type>/bl31.bin`` (AArch64 only)
- - ``build/<platform>/<build-type>/bl32.bin`` (mandatory for AArch32)
-
- where ``<platform>`` is the name of the chosen platform and ``<build-type>``
- is either ``debug`` or ``release``. The actual number of images might differ
- depending on the platform.
-
-- Build products for a specific build variant can be removed using:
-
- .. code:: shell
-
- make DEBUG=<D> PLAT=<platform> clean
-
- ... where ``<D>`` is ``0`` or ``1``, as specified when building.
-
- The build tree can be removed completely using:
-
- .. code:: shell
-
- make realclean
-
-Summary of build options
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The TF-A build system supports the following build options. Unless mentioned
-otherwise, these options are expected to be specified at the build command
-line and are not to be modified in any component makefiles. Note that the
-build system doesn't track dependency for build options. Therefore, if any of
-the build options are changed from a previous build, a clean build must be
-performed.
-
-Common build options
-^^^^^^^^^^^^^^^^^^^^
-
-- ``AARCH32_INSTRUCTION_SET``: Choose the AArch32 instruction set that the
- compiler should use. Valid values are T32 and A32. It defaults to T32 due to
- code having a smaller resulting size.
-
-- ``AARCH32_SP`` : Choose the AArch32 Secure Payload component to be built as
- as the BL32 image when ``ARCH=aarch32``. The value should be the path to the
- directory containing the SP source, relative to the ``bl32/``; the directory
- is expected to contain a makefile called ``<aarch32_sp-value>.mk``.
-
-- ``ARCH`` : Choose the target build architecture for TF-A. It can take either
- ``aarch64`` or ``aarch32`` as values. By default, it is defined to
- ``aarch64``.
-
-- ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when
- compiling TF-A. Its value must be numeric, and defaults to 8 . See also,
- *Armv8 Architecture Extensions* and *Armv7 Architecture Extensions* in
- :ref:`Firmware Design`.
-
-- ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when
- compiling TF-A. Its value must be a numeric, and defaults to 0. See also,
- *Armv8 Architecture Extensions* in :ref:`Firmware Design`.
-
-- ``BL2``: This is an optional build option which specifies the path to BL2
- image for the ``fip`` target. In this case, the BL2 in the TF-A will not be
- built.
-
-- ``BL2U``: This is an optional build option which specifies the path to
- BL2U image. In this case, the BL2U in TF-A will not be built.
-
-- ``BL2_AT_EL3``: This is an optional build option that enables the use of
- BL2 at EL3 execution level.
-
-- ``BL2_IN_XIP_MEM``: In some use-cases BL2 will be stored in eXecute In Place
- (XIP) memory, like BL1. In these use-cases, it is necessary to initialize
- the RW sections in RAM, while leaving the RO sections in place. This option
- enable this use-case. For now, this option is only supported when BL2_AT_EL3
- is set to '1'.
-
-- ``BL2_INV_DCACHE``: This is an optional build option which control dcache
- invalidation upon BL2 entry. Some platform cannot handle cache operations
- during entry as the coherency unit is not yet initialized. This may cause
- crashing. Leaving this option to '1' (default) will allow the operation.
- This option is only relevant when BL2_AT_EL3 is set to '1'.
-
-- ``BL31``: This is an optional build option which specifies the path to
- BL31 image for the ``fip`` target. In this case, the BL31 in TF-A will not
- be built.
-
-- ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
- file that contains the BL31 private key in PEM format. If ``SAVE_KEYS=1``,
- this file name will be used to save the key.
-
-- ``BL32``: This is an optional build option which specifies the path to
- BL32 image for the ``fip`` target. In this case, the BL32 in TF-A will not
- be built.
-
-- ``BL32_EXTRA1``: This is an optional build option which specifies the path to
- Trusted OS Extra1 image for the ``fip`` target.
-
-- ``BL32_EXTRA2``: This is an optional build option which specifies the path to
- Trusted OS Extra2 image for the ``fip`` target.
-
-- ``BL32_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
- file that contains the BL32 private key in PEM format. If ``SAVE_KEYS=1``,
- this file name will be used to save the key.
-
-- ``BL33``: Path to BL33 image in the host file system. This is mandatory for
- ``fip`` target in case TF-A BL2 is used.
-
-- ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
- file that contains the BL33 private key in PEM format. If ``SAVE_KEYS=1``,
- this file name will be used to save the key.
-
-- ``BRANCH_PROTECTION``: Numeric value to enable ARMv8.3 Pointer Authentication
- and ARMv8.5 Branch Target Identification support for TF-A BL images themselves.
- If enabled, it is needed to use a compiler (e.g GCC 9.1 and later versions) that
- supports the option ``-mbranch-protection``.
- Selects the branch protection features to use:
-- 0: Default value turns off all types of branch protection
-- 1: Enables all types of branch protection features
-- 2: Return address signing to its standard level
-- 3: Extend the signing to include leaf functions
-
- The table below summarizes ``BRANCH_PROTECTION`` values, GCC compilation options
- and resulting PAuth/BTI features.
-
- +-------+--------------+-------+-----+
- | Value | GCC option | PAuth | BTI |
- +=======+==============+=======+=====+
- | 0 | none | N | N |
- +-------+--------------+-------+-----+
- | 1 | standard | Y | Y |
- +-------+--------------+-------+-----+
- | 2 | pac-ret | Y | N |
- +-------+--------------+-------+-----+
- | 3 | pac-ret+leaf | Y | N |
- +-------+--------------+-------+-----+
-
- This option defaults to 0 and this is an experimental feature.
- Note that Pointer Authentication is enabled for Non-secure world
- irrespective of the value of this option if the CPU supports it.
-
-- ``BUILD_MESSAGE_TIMESTAMP``: String used to identify the time and date of the
- compilation of each build. It must be set to a C string (including quotes
- where applicable). Defaults to a string that contains the time and date of
- the compilation.
-
-- ``BUILD_STRING``: Input string for VERSION_STRING, which allows the TF-A
- build to be uniquely identified. Defaults to the current git commit id.
-
-- ``CFLAGS``: Extra user options appended on the compiler's command line in
- addition to the options set by the build system.
-
-- ``COLD_BOOT_SINGLE_CPU``: This option indicates whether the platform may
- release several CPUs out of reset. It can take either 0 (several CPUs may be
- brought up) or 1 (only one CPU will ever be brought up during cold reset).
- Default is 0. If the platform always brings up a single CPU, there is no
- need to distinguish between primary and secondary CPUs and the boot path can
- be optimised. The ``plat_is_my_cpu_primary()`` and
- ``plat_secondary_cold_boot_setup()`` platform porting interfaces do not need
- to be implemented in this case.
-
-- ``CRASH_REPORTING``: A non-zero value enables a console dump of processor
- register state when an unexpected exception occurs during execution of
- BL31. This option defaults to the value of ``DEBUG`` - i.e. by default
- this is only enabled for a debug build of the firmware.
-
-- ``CREATE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
- certificate generation tool to create new keys in case no valid keys are
- present or specified. Allowed options are '0' or '1'. Default is '1'.
-
-- ``CTX_INCLUDE_AARCH32_REGS`` : Boolean option that, when set to 1, will cause
- the AArch32 system registers to be included when saving and restoring the
- CPU context. The option must be set to 0 for AArch64-only platforms (that
- is on hardware that does not implement AArch32, or at least not at EL1 and
- higher ELs). Default value is 1.
-
-- ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP
- registers to be included when saving and restoring the CPU context. Default
- is 0.
-
-- ``CTX_INCLUDE_MTE_REGS``: Enables register saving/reloading support for
- ARMv8.5 Memory Tagging Extension. A value of 0 will disable
- saving/reloading and restrict the use of MTE to the normal world if the
- CPU has support, while a value of 1 enables the saving/reloading, allowing
- the use of MTE in both the secure and non-secure worlds. Default is 0
- (disabled) and this feature is experimental.
-
-- ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, enables
- Pointer Authentication for Secure world. This will cause the ARMv8.3-PAuth
- registers to be included when saving and restoring the CPU context as
- part of world switch. Default value is 0 and this is an experimental feature.
- Note that Pointer Authentication is enabled for Non-secure world irrespective
- of the value of this flag if the CPU supports it.
-
-- ``DEBUG``: Chooses between a debug and release build. It can take either 0
- (release) or 1 (debug) as values. 0 is the default.
-
-- ``DISABLE_BIN_GENERATION``: Boolean option to disable the generation
- of the binary image. If set to 1, then only the ELF image is built.
- 0 is the default.
-
-- ``DYN_DISABLE_AUTH``: Provides the capability to dynamically disable Trusted
- Board Boot authentication at runtime. This option is meant to be enabled only
- for development platforms. ``TRUSTED_BOARD_BOOT`` flag must be set if this
- flag has to be enabled. 0 is the default.
-
-- ``E``: Boolean option to make warnings into errors. Default is 1.
-
-- ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of
- the normal boot flow. It must specify the entry point address of the EL3
- payload. Please refer to the "Booting an EL3 payload" section for more
- details.
-
-- ``ENABLE_AMU``: Boolean option to enable Activity Monitor Unit extensions.
- This is an optional architectural feature available on v8.4 onwards. Some
- v8.2 implementations also implement an AMU and this option can be used to
- enable this feature on those systems as well. Default is 0.
-
-- ``ENABLE_ASSERTIONS``: This option controls whether or not calls to ``assert()``
- are compiled out. For debug builds, this option defaults to 1, and calls to
- ``assert()`` are left in place. For release builds, this option defaults to 0
- and calls to ``assert()`` function are compiled out. This option can be set
- independently of ``DEBUG``. It can also be used to hide any auxiliary code
- that is only required for the assertion and does not fit in the assertion
- itself.
-
-- ``ENABLE_BACKTRACE``: This option controls whether to enables backtrace
- dumps or not. It is supported in both AArch64 and AArch32. However, in
- AArch32 the format of the frame records are not defined in the AAPCS and they
- are defined by the implementation. This implementation of backtrace only
- supports the format used by GCC when T32 interworking is disabled. For this
- reason enabling this option in AArch32 will force the compiler to only
- generate A32 code. This option is enabled by default only in AArch64 debug
- builds, but this behaviour can be overridden in each platform's Makefile or
- in the build command line.
-
-- ``ENABLE_MPAM_FOR_LOWER_ELS``: Boolean option to enable lower ELs to use MPAM
- feature. MPAM is an optional Armv8.4 extension that enables various memory
- system components and resources to define partitions; software running at
- various ELs can assign themselves to desired partition to control their
- performance aspects.
-
- When this option is set to ``1``, EL3 allows lower ELs to access their own
- MPAM registers without trapping into EL3. This option doesn't make use of
- partitioning in EL3, however. Platform initialisation code should configure
- and use partitions in EL3 as required. This option defaults to ``0``.
-
-- ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE)
- support within generic code in TF-A. This option is currently only supported
- in BL31. Default is 0.
-
-- ``ENABLE_PMF``: Boolean option to enable support for optional Performance
- Measurement Framework(PMF). Default is 0.
-
-- ``ENABLE_PSCI_STAT``: Boolean option to enable support for optional PSCI
- functions ``PSCI_STAT_RESIDENCY`` and ``PSCI_STAT_COUNT``. Default is 0.
- In the absence of an alternate stat collection backend, ``ENABLE_PMF`` must
- be enabled. If ``ENABLE_PMF`` is set, the residency statistics are tracked in
- software.
-
-- ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime
- instrumentation which injects timestamp collection points into TF-A to
- allow runtime performance to be measured. Currently, only PSCI is
- instrumented. Enabling this option enables the ``ENABLE_PMF`` build option
- as well. Default is 0.
-
-- ``ENABLE_SPE_FOR_LOWER_ELS`` : Boolean option to enable Statistical Profiling
- extensions. This is an optional architectural feature for AArch64.
- The default is 1 but is automatically disabled when the target architecture
- is AArch32.
-
-- ``ENABLE_SPM`` : Boolean option to enable the Secure Partition Manager (SPM).
- Refer to :ref:`Secure Partition Manager` for more details about
- this feature. Default is 0.
-
-- ``ENABLE_SVE_FOR_NS``: Boolean option to enable Scalable Vector Extension
- (SVE) for the Non-secure world only. SVE is an optional architectural feature
- for AArch64. Note that when SVE is enabled for the Non-secure world, access
- to SIMD and floating-point functionality from the Secure world is disabled.
- This is to avoid corruption of the Non-secure world data in the Z-registers
- which are aliased by the SIMD and FP registers. The build option is not
- compatible with the ``CTX_INCLUDE_FPREGS`` build option, and will raise an
- assert on platforms where SVE is implemented and ``ENABLE_SVE_FOR_NS`` set to
- 1. The default is 1 but is automatically disabled when the target
- architecture is AArch32.
-
-- ``ENABLE_STACK_PROTECTOR``: String option to enable the stack protection
- checks in GCC. Allowed values are "all", "strong", "default" and "none". The
- default value is set to "none". "strong" is the recommended stack protection
- level if this feature is desired. "none" disables the stack protection. For
- all values other than "none", the ``plat_get_stack_protector_canary()``
- platform hook needs to be implemented. The value is passed as the last
- component of the option ``-fstack-protector-$ENABLE_STACK_PROTECTOR``.
-
-- ``ERROR_DEPRECATED``: This option decides whether to treat the usage of
- deprecated platform APIs, helper functions or drivers within Trusted
- Firmware as error. It can take the value 1 (flag the use of deprecated
- APIs as error) or 0. The default is 0.
-
-- ``EL3_EXCEPTION_HANDLING``: When set to ``1``, enable handling of exceptions
- targeted at EL3. When set ``0`` (default), no exceptions are expected or
- handled at EL3, and a panic will result. This is supported only for AArch64
- builds.
-
-- ``FAULT_INJECTION_SUPPORT``: ARMv8.4 extensions introduced support for fault
- injection from lower ELs, and this build option enables lower ELs to use
- Error Records accessed via System Registers to inject faults. This is
- applicable only to AArch64 builds.
-
- This feature is intended for testing purposes only, and is advisable to keep
- disabled for production images.
-
-- ``FIP_NAME``: This is an optional build option which specifies the FIP
- filename for the ``fip`` target. Default is ``fip.bin``.
-
-- ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU
- FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``.
-
-- ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create``
- tool to create certificates as per the Chain of Trust described in
- :ref:`Trusted Board Boot`. The build system then calls ``fiptool`` to
- include the certificates in the FIP and FWU_FIP. Default value is '0'.
-
- Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support
- for the Trusted Board Boot feature in the BL1 and BL2 images, to generate
- the corresponding certificates, and to include those certificates in the
- FIP and FWU_FIP.
-
- Note that if ``TRUSTED_BOARD_BOOT=0`` and ``GENERATE_COT=1``, the BL1 and BL2
- images will not include support for Trusted Board Boot. The FIP will still
- include the corresponding certificates. This FIP can be used to verify the
- Chain of Trust on the host machine through other mechanisms.
-
- Note that if ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=0``, the BL1 and BL2
- images will include support for Trusted Board Boot, but the FIP and FWU_FIP
- will not include the corresponding certificates, causing a boot failure.
-
-- ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have
- inherent support for specific EL3 type interrupts. Setting this build option
- to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both
- by `platform abstraction layer`__ and `Interrupt Management Framework`__.
- This allows GICv2 platforms to enable features requiring EL3 interrupt type.
- This also means that all GICv2 Group 0 interrupts are delivered to EL3, and
- the Secure Payload interrupts needs to be synchronously handed over to Secure
- EL1 for handling. The default value of this option is ``0``, which means the
- Group 0 interrupts are assumed to be handled by Secure EL1.
-
- .. __: `platform-interrupt-controller-API.rst`
- .. __: `interrupt-framework-design.rst`
-
-- ``HANDLE_EA_EL3_FIRST``: When set to ``1``, External Aborts and SError
- Interrupts will be always trapped in EL3 i.e. in BL31 at runtime. When set to
- ``0`` (default), these exceptions will be trapped in the current exception
- level (or in EL1 if the current exception level is EL0).
-
-- ``HW_ASSISTED_COHERENCY``: On most Arm systems to-date, platform-specific
- software operations are required for CPUs to enter and exit coherency.
- However, newer systems exist where CPUs' entry to and exit from coherency
- is managed in hardware. Such systems require software to only initiate these
- operations, and the rest is managed in hardware, minimizing active software
- management. In such systems, this boolean option enables TF-A to carry out
- build and run-time optimizations during boot and power management operations.
- This option defaults to 0 and if it is enabled, then it implies
- ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled.
-
- If this flag is disabled while the platform which TF-A is compiled for
- includes cores that manage coherency in hardware, then a compilation error is
- generated. This is based on the fact that a system cannot have, at the same
- time, cores that manage coherency in hardware and cores that don't. In other
- words, a platform cannot have, at the same time, cores that require
- ``HW_ASSISTED_COHERENCY=1`` and cores that require
- ``HW_ASSISTED_COHERENCY=0``.
-
- Note that, when ``HW_ASSISTED_COHERENCY`` is enabled, version 2 of
- translation library (xlat tables v2) must be used; version 1 of translation
- library is not supported.
-
-- ``JUNO_AARCH32_EL3_RUNTIME``: This build flag enables you to execute EL3
- runtime software in AArch32 mode, which is required to run AArch32 on Juno.
- By default this flag is set to '0'. Enabling this flag builds BL1 and BL2 in
- AArch64 and facilitates the loading of ``SP_MIN`` and BL33 as AArch32 executable
- images.
-
-- ``KEY_ALG``: This build flag enables the user to select the algorithm to be
- used for generating the PKCS keys and subsequent signing of the certificate.
- It accepts 2 values: ``rsa`` and ``ecdsa``. The default value of this flag
- is ``rsa`` which is the TBBR compliant PKCS#1 RSA 2.1 scheme.
-
-- ``KEY_SIZE``: This build flag enables the user to select the key size for
- the algorithm specified by ``KEY_ALG``. The valid values for ``KEY_SIZE``
- depend on the chosen algorithm.
-
- +-----------+------------------------------------+
- | KEY_ALG | Possible key sizes |
- +===========+====================================+
- | rsa | 1024, 2048 (default), 3072, 4096 |
- +-----------+------------------------------------+
- | ecdsa | unavailable |
- +-----------+------------------------------------+
-
-- ``HASH_ALG``: This build flag enables the user to select the secure hash
- algorithm. It accepts 3 values: ``sha256``, ``sha384`` and ``sha512``.
- The default value of this flag is ``sha256``.
-
-- ``LDFLAGS``: Extra user options appended to the linkers' command line in
- addition to the one set by the build system.
-
-- ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log
- output compiled into the build. This should be one of the following:
-
- ::
-
- 0 (LOG_LEVEL_NONE)
- 10 (LOG_LEVEL_ERROR)
- 20 (LOG_LEVEL_NOTICE)
- 30 (LOG_LEVEL_WARNING)
- 40 (LOG_LEVEL_INFO)
- 50 (LOG_LEVEL_VERBOSE)
-
- All log output up to and including the selected log level is compiled into
- the build. The default value is 40 in debug builds and 20 in release builds.
-
-- ``NON_TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
- specifies the file that contains the Non-Trusted World private key in PEM
- format. If ``SAVE_KEYS=1``, this file name will be used to save the key.
-
-- ``NS_BL2U``: Path to NS_BL2U image in the host file system. This image is
- optional. It is only needed if the platform makefile specifies that it
- is required in order to build the ``fwu_fip`` target.
-
-- ``NS_TIMER_SWITCH``: Enable save and restore for non-secure timer register
- contents upon world switch. It can take either 0 (don't save and restore) or
- 1 (do save and restore). 0 is the default. An SPD may set this to 1 if it
- wants the timer registers to be saved and restored.
-
-- ``OVERRIDE_LIBC``: This option allows platforms to override the default libc
- for the BL image. It can be either 0 (include) or 1 (remove). The default
- value is 0.
-
-- ``PL011_GENERIC_UART``: Boolean option to indicate the PL011 driver that
- the underlying hardware is not a full PL011 UART but a minimally compliant
- generic UART, which is a subset of the PL011. The driver will not access
- any register that is not part of the SBSA generic UART specification.
- Default value is 0 (a full PL011 compliant UART is present).
-
-- ``PLAT``: Choose a platform to build TF-A for. The chosen platform name
- must be subdirectory of any depth under ``plat/``, and must contain a
- platform makefile named ``platform.mk``. For example, to build TF-A for the
- Arm Juno board, select PLAT=juno.
-
-- ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image
- instead of the normal boot flow. When defined, it must specify the entry
- point address for the preloaded BL33 image. This option is incompatible with
- ``EL3_PAYLOAD_BASE``. If both are defined, ``EL3_PAYLOAD_BASE`` has priority
- over ``PRELOADED_BL33_BASE``.
-
-- ``PROGRAMMABLE_RESET_ADDRESS``: This option indicates whether the reset
- vector address can be programmed or is fixed on the platform. It can take
- either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a
- programmable reset address, it is expected that a CPU will start executing
- code directly at the right address, both on a cold and warm reset. In this
- case, there is no need to identify the entrypoint on boot and the boot path
- can be optimised. The ``plat_get_my_entrypoint()`` platform porting interface
- does not need to be implemented in this case.
-
-- ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats
- possible for the PSCI power-state parameter: original and extended State-ID
- formats. This flag if set to 1, configures the generic PSCI layer to use the
- extended format. The default value of this flag is 0, which means by default
- the original power-state format is used by the PSCI implementation. This flag
- should be specified by the platform makefile and it governs the return value
- of PSCI_FEATURES API for CPU_SUSPEND smc function id. When this option is
- enabled on Arm platforms, the option ``ARM_RECOM_STATE_ID_ENC`` needs to be
- set to 1 as well.
-
-- ``RAS_EXTENSION``: When set to ``1``, enable Armv8.2 RAS features. RAS features
- are an optional extension for pre-Armv8.2 CPUs, but are mandatory for Armv8.2
- or later CPUs.
-
- When ``RAS_EXTENSION`` is set to ``1``, ``HANDLE_EA_EL3_FIRST`` must also be
- set to ``1``.
-
- This option is disabled by default.
-
-- ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead
- of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
- entrypoint) or 1 (CPU reset to BL31 entrypoint).
- The default value is 0.
-
-- ``RESET_TO_SP_MIN``: SP_MIN is the minimal AArch32 Secure Payload provided
- in TF-A. This flag configures SP_MIN entrypoint as the CPU reset vector
- instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1
- entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default value is 0.
-
-- ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
- file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this
- file name will be used to save the key.
-
-- ``SANITIZE_UB``: This option enables the Undefined Behaviour sanitizer. It
- can take 3 values: 'off' (default), 'on' and 'trap'. When using 'trap',
- gcc and clang will insert calls to ``__builtin_trap`` on detected
- undefined behaviour, which defaults to a ``brk`` instruction. When using
- 'on', undefined behaviour is translated to a call to special handlers which
- prints the exact location of the problem and its cause and then panics.
-
- .. note::
- Because of the space penalty of the Undefined Behaviour sanitizer,
- this option will increase the size of the binary. Depending on the
- memory constraints of the target platform, it may not be possible to
- enable the sanitizer for all images (BL1 and BL2 are especially
- likely to be memory constrained). We recommend that the
- sanitizer is enabled only in debug builds.
-
-- ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the
- certificate generation tool to save the keys used to establish the Chain of
- Trust. Allowed options are '0' or '1'. Default is '0' (do not save).
-
-- ``SCP_BL2``: Path to SCP_BL2 image in the host file system. This image is optional.
- If a SCP_BL2 image is present then this option must be passed for the ``fip``
- target.
-
-- ``SCP_BL2_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the
- file that contains the SCP_BL2 private key in PEM format. If ``SAVE_KEYS=1``,
- this file name will be used to save the key.
-
-- ``SCP_BL2U``: Path to SCP_BL2U image in the host file system. This image is
- optional. It is only needed if the platform makefile specifies that it
- is required in order to build the ``fwu_fip`` target.
-
-- ``SDEI_SUPPORT``: Setting this to ``1`` enables support for Software
- Delegated Exception Interface to BL31 image. This defaults to ``0``.
-
- When set to ``1``, the build option ``EL3_EXCEPTION_HANDLING`` must also be
- set to ``1``.
-
-- ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be
- isolated on separate memory pages. This is a trade-off between security and
- memory usage. See "Isolating code and read-only data on separate memory
- pages" section in :ref:`Firmware Design`. This flag is disabled by default
- and affects all BL images.
-
-- ``SPD``: Choose a Secure Payload Dispatcher component to be built into TF-A.
- This build option is only valid if ``ARCH=aarch64``. The value should be
- the path to the directory containing the SPD source, relative to
- ``services/spd/``; the directory is expected to contain a makefile called
- ``<spd-value>.mk``.
-
-- ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can
- take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops
- execution in BL1 just before handing over to BL31. At this point, all
- firmware images have been loaded in memory, and the MMU and caches are
- turned off. Refer to the "Debugging options" section for more details.
-
-- ``SP_MIN_WITH_SECURE_FIQ``: Boolean flag to indicate the SP_MIN handles
- secure interrupts (caught through the FIQ line). Platforms can enable
- this directive if they need to handle such interruption. When enabled,
- the FIQ are handled in monitor mode and non secure world is not allowed
- to mask these events. Platforms that enable FIQ handling in SP_MIN shall
- implement the api ``sp_min_plat_fiq_handler()``. The default value is 0.
-
-- ``TRUSTED_BOARD_BOOT``: Boolean flag to include support for the Trusted Board
- Boot feature. When set to '1', BL1 and BL2 images include support to load
- and verify the certificates and images in a FIP, and BL1 includes support
- for the Firmware Update. The default value is '0'. Generation and inclusion
- of certificates in the FIP and FWU_FIP depends upon the value of the
- ``GENERATE_COT`` option.
-
- .. warning::
- This option depends on ``CREATE_KEYS`` to be enabled. If the keys
- already exist in disk, they will be overwritten without further notice.
-
-- ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
- specifies the file that contains the Trusted World private key in PEM
- format. If ``SAVE_KEYS=1``, this file name will be used to save the key.
-
-- ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or
- synchronous, (see "Initializing a BL32 Image" section in
- :ref:`Firmware Design`). It can take the value 0 (BL32 is initialized using
- synchronous method) or 1 (BL32 is initialized using asynchronous method).
- Default is 0.
-
-- ``TSP_NS_INTR_ASYNC_PREEMPT``: A non zero value enables the interrupt
- routing model which routes non-secure interrupts asynchronously from TSP
- to EL3 causing immediate preemption of TSP. The EL3 is responsible
- for saving and restoring the TSP context in this routing model. The
- default routing model (when the value is 0) is to route non-secure
- interrupts to TSP allowing it to save its context and hand over
- synchronously to EL3 via an SMC.
-
- .. note::
- When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT``
- must also be set to ``1``.
-
-- ``USE_ARM_LINK``: This flag determines whether to enable support for ARM
- linker. When the ``LINKER`` build variable points to the armlink linker,
- this flag is enabled automatically. To enable support for armlink, platforms
- will have to provide a scatter file for the BL image. Currently, Tegra
- platforms use the armlink support to compile BL3-1 images.
-
-- ``USE_COHERENT_MEM``: This flag determines whether to include the coherent
- memory region in the BL memory map or not (see "Use of Coherent memory in
- TF-A" section in :ref:`Firmware Design`). It can take the value 1
- (Coherent memory region is included) or 0 (Coherent memory region is
- excluded). Default is 1.
-
-- ``USE_ROMLIB``: This flag determines whether library at ROM will be used.
- This feature creates a library of functions to be placed in ROM and thus
- reduces SRAM usage. Refer to :ref:`Library at ROM` for further details.
- Default is 0.
-
-- ``USE_SPINLOCK_CAS``: Setting this build flag to 1 selects the spinlock
- implementation variant using the ARMv8.1-LSE compare-and-swap instruction.
- Notice this option is experimental and only available to AArch64 builds.
-
-- ``V``: Verbose build. If assigned anything other than 0, the build commands
- are printed. Default is 0.
-
-- ``VERSION_STRING``: String used in the log output for each TF-A image.
- Defaults to a string formed by concatenating the version number, build type
- and build string.
-
-- ``W``: Warning level. Some compiler warning options of interest have been
- regrouped and put in the root Makefile. This flag can take the values 0 to 3,
- each level enabling more warning options. Default is 0.
-
-- ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on
- the CPU after warm boot. This is applicable for platforms which do not
- require interconnect programming to enable cache coherency (eg: single
- cluster platforms). If this option is enabled, then warm boot path
- enables D-caches immediately after enabling MMU. This option defaults to 0.
-
-Arm development platform specific build options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- ``ARM_BL31_IN_DRAM``: Boolean option to select loading of BL31 in TZC secured
- DRAM. By default, BL31 is in the secure SRAM. Set this flag to 1 to load
- BL31 in TZC secured DRAM. If TSP is present, then setting this option also
- sets the TSP location to DRAM and ignores the ``ARM_TSP_RAM_LOCATION`` build
- flag.
-
-- ``ARM_CONFIG_CNTACR``: boolean option to unlock access to the ``CNTBase<N>``
- frame registers by setting the ``CNTCTLBase.CNTACR<N>`` register bits. The
- frame number ``<N>`` is defined by ``PLAT_ARM_NSTIMER_FRAME_ID``, which should
- match the frame used by the Non-Secure image (normally the Linux kernel).
- Default is true (access to the frame is allowed).
-
-- ``ARM_DISABLE_TRUSTED_WDOG``: boolean option to disable the Trusted Watchdog.
- By default, Arm platforms use a watchdog to trigger a system reset in case
- an error is encountered during the boot process (for example, when an image
- could not be loaded or authenticated). The watchdog is enabled in the early
- platform setup hook at BL1 and disabled in the BL1 prepare exit hook. The
- Trusted Watchdog may be disabled at build time for testing or development
- purposes.
-
-- ``ARM_LINUX_KERNEL_AS_BL33``: The Linux kernel expects registers x0-x3 to
- have specific values at boot. This boolean option allows the Trusted Firmware
- to have a Linux kernel image as BL33 by preparing the registers to these
- values before jumping to BL33. This option defaults to 0 (disabled). For
- AArch64 ``RESET_TO_BL31`` and for AArch32 ``RESET_TO_SP_MIN`` must be 1 when
- using it. If this option is set to 1, ``ARM_PRELOADED_DTB_BASE`` must be set
- to the location of a device tree blob (DTB) already loaded in memory. The
- Linux Image address must be specified using the ``PRELOADED_BL33_BASE``
- option.
-
-- ``ARM_PLAT_MT``: This flag determines whether the Arm platform layer has to
- cater for the multi-threading ``MT`` bit when accessing MPIDR. When this flag
- is set, the functions which deal with MPIDR assume that the ``MT`` bit in
- MPIDR is set and access the bit-fields in MPIDR accordingly. Default value of
- this flag is 0. Note that this option is not used on FVP platforms.
-
-- ``ARM_RECOM_STATE_ID_ENC``: The PSCI1.0 specification recommends an encoding
- for the construction of composite state-ID in the power-state parameter.
- The existing PSCI clients currently do not support this encoding of
- State-ID yet. Hence this flag is used to configure whether to use the
- recommended State-ID encoding or not. The default value of this flag is 0,
- in which case the platform is configured to expect NULL in the State-ID
- field of power-state parameter.
-
-- ``ARM_ROTPK_LOCATION``: used when ``TRUSTED_BOARD_BOOT=1``. It specifies the
- location of the ROTPK hash returned by the function ``plat_get_rotpk_info()``
- for Arm platforms. Depending on the selected option, the proper private key
- must be specified using the ``ROT_KEY`` option when building the Trusted
- Firmware. This private key will be used by the certificate generation tool
- to sign the BL2 and Trusted Key certificates. Available options for
- ``ARM_ROTPK_LOCATION`` are:
-
- - ``regs`` : return the ROTPK hash stored in the Trusted root-key storage
- registers. The private key corresponding to this ROTPK hash is not
- currently available.
- - ``devel_rsa`` : return a development public key hash embedded in the BL1
- and BL2 binaries. This hash has been obtained from the RSA public key
- ``arm_rotpk_rsa.der``, located in ``plat/arm/board/common/rotpk``. To use
- this option, ``arm_rotprivk_rsa.pem`` must be specified as ``ROT_KEY`` when
- creating the certificates.
- - ``devel_ecdsa`` : return a development public key hash embedded in the BL1
- and BL2 binaries. This hash has been obtained from the ECDSA public key
- ``arm_rotpk_ecdsa.der``, located in ``plat/arm/board/common/rotpk``. To use
- this option, ``arm_rotprivk_ecdsa.pem`` must be specified as ``ROT_KEY``
- when creating the certificates.
-
-- ``ARM_TSP_RAM_LOCATION``: location of the TSP binary. Options:
-
- - ``tsram`` : Trusted SRAM (default option when TBB is not enabled)
- - ``tdram`` : Trusted DRAM (if available)
- - ``dram`` : Secure region in DRAM (default option when TBB is enabled,
- configured by the TrustZone controller)
-
-- ``ARM_XLAT_TABLES_LIB_V1``: boolean option to compile TF-A with version 1
- of the translation tables library instead of version 2. It is set to 0 by
- default, which selects version 2.
-
-- ``ARM_CRYPTOCELL_INTEG`` : bool option to enable TF-A to invoke Arm®
- TrustZone® CryptoCell functionality for Trusted Board Boot on capable Arm
- platforms. If this option is specified, then the path to the CryptoCell
- SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag.
-
-For a better understanding of these options, the Arm development platform memory
-map is explained in the :ref:`Firmware Design`.
-
-Arm CSS platform specific build options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- ``CSS_DETECT_PRE_1_7_0_SCP``: Boolean flag to detect SCP version
- incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards
- compatible change to the MTL protocol, used for AP/SCP communication.
- TF-A no longer supports earlier SCP versions. If this option is set to 1
- then TF-A will detect if an earlier version is in use. Default is 1.
-
-- ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP_BL2 and
- SCP_BL2U to the FIP and FWU_FIP respectively, and enables them to be loaded
- during boot. Default is 1.
-
-- ``CSS_USE_SCMI_SDS_DRIVER``: Boolean flag which selects SCMI/SDS drivers
- instead of SCPI/BOM driver for communicating with the SCP during power
- management operations and for SCP RAM Firmware transfer. If this option
- is set to 1, then SCMI/SDS drivers will be used. Default is 0.
-
-Arm FVP platform specific build options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- ``FVP_CLUSTER_COUNT`` : Configures the cluster count to be used to
- build the topology tree within TF-A. By default TF-A is configured for dual
- cluster topology and this option can be used to override the default value.
-
-- ``FVP_INTERCONNECT_DRIVER``: Selects the interconnect driver to be built. The
- default interconnect driver depends on the value of ``FVP_CLUSTER_COUNT`` as
- explained in the options below:
-
- - ``FVP_CCI`` : The CCI driver is selected. This is the default
- if 0 < ``FVP_CLUSTER_COUNT`` <= 2.
- - ``FVP_CCN`` : The CCN driver is selected. This is the default
- if ``FVP_CLUSTER_COUNT`` > 2.
-
-- ``FVP_MAX_CPUS_PER_CLUSTER``: Sets the maximum number of CPUs implemented in
- a single cluster. This option defaults to 4.
-
-- ``FVP_MAX_PE_PER_CPU``: Sets the maximum number of PEs implemented on any CPU
- in the system. This option defaults to 1. Note that the build option
- ``ARM_PLAT_MT`` doesn't have any effect on FVP platforms.
-
-- ``FVP_USE_GIC_DRIVER`` : Selects the GIC driver to be built. Options:
-
- - ``FVP_GIC600`` : The GIC600 implementation of GICv3 is selected
- - ``FVP_GICV2`` : The GICv2 only driver is selected
- - ``FVP_GICV3`` : The GICv3 only driver is selected (default option)
-
-- ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer
- for functions that wait for an arbitrary time length (udelay and mdelay).
- The default value is 0.
-
-- ``FVP_HW_CONFIG_DTS`` : Specify the path to the DTS file to be compiled
- to DTB and packaged in FIP as the HW_CONFIG. See :ref:`Firmware Design` for
- details on HW_CONFIG. By default, this is initialized to a sensible DTS
- file in ``fdts/`` folder depending on other build options. But some cases,
- like shifted affinity format for MPIDR, cannot be detected at build time
- and this option is needed to specify the appropriate DTS file.
-
-- ``FVP_HW_CONFIG`` : Specify the path to the HW_CONFIG blob to be packaged in
- FIP. See :ref:`Firmware Design` for details on HW_CONFIG. This option is
- similar to the ``FVP_HW_CONFIG_DTS`` option, but it directly specifies the
- HW_CONFIG blob instead of the DTS file. This option is useful to override
- the default HW_CONFIG selected by the build system.
-
-ARM JUNO platform specific build options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- ``JUNO_TZMP1`` : Boolean option to configure Juno to be used for TrustZone
- Media Protection (TZ-MP1). Default value of this flag is 0.
-
-Debugging options
-~~~~~~~~~~~~~~~~~
-
-To compile a debug version and make the build more verbose use
-
-.. code:: shell
-
- make PLAT=<platform> DEBUG=1 V=1 all
-
-AArch64 GCC uses DWARF version 4 debugging symbols by default. Some tools (for
-example DS-5) might not support this and may need an older version of DWARF
-symbols to be emitted by GCC. This can be achieved by using the
-``-gdwarf-<version>`` flag, with the version being set to 2 or 3. Setting the
-version to 2 is recommended for DS-5 versions older than 5.16.
-
-When debugging logic problems it might also be useful to disable all compiler
-optimizations by using ``-O0``.
-
-.. warning::
- Using ``-O0`` could cause output images to be larger and base addresses
- might need to be recalculated (see the **Memory layout on Arm development
- platforms** section in the :ref:`Firmware Design`).
-
-Extra debug options can be passed to the build system by setting ``CFLAGS`` or
-``LDFLAGS``:
-
-.. code:: shell
-
- CFLAGS='-O0 -gdwarf-2' \
- make PLAT=<platform> DEBUG=1 V=1 all
-
-Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be
-ignored as the linker is called directly.
-
-It is also possible to introduce an infinite loop to help in debugging the
-post-BL2 phase of TF-A. This can be done by rebuilding BL1 with the
-``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the `Summary of build options`_
-section. In this case, the developer may take control of the target using a
-debugger when indicated by the console output. When using DS-5, the following
-commands can be used:
-
-::
-
- # Stop target execution
- interrupt
-
- #
- # Prepare your debugging environment, e.g. set breakpoints
- #
-
- # Jump over the debug loop
- set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4
-
- # Resume execution
- continue
-
-Building the Test Secure Payload
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The TSP is coupled with a companion runtime service in the BL31 firmware,
-called the TSPD. Therefore, if you intend to use the TSP, the BL31 image
-must be recompiled as well. For more information on SPs and SPDs, see the
-:ref:`Secure-EL1 Payloads and Dispatchers <firmware_design_sel1_spd>` section
-in the :ref:`Firmware Design` document.
-
-First clean the TF-A build directory to get rid of any previous BL31 binary.
-Then to build the TSP image use:
-
-.. code:: shell
-
- make PLAT=<platform> SPD=tspd all
-
-An additional boot loader binary file is created in the ``build`` directory:
-
-::
-
- build/<platform>/<build-type>/bl32.bin
-
-
-Building and using the FIP tool
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Firmware Image Package (FIP) is a packaging format used by TF-A to package
-firmware images in a single binary. The number and type of images that should
-be packed in a FIP is platform specific and may include TF-A images and other
-firmware images required by the platform. For example, most platforms require
-a BL33 image which corresponds to the normal world bootloader (e.g. UEFI or
-U-Boot).
-
-The TF-A build system provides the make target ``fip`` to create a FIP file
-for the specified platform using the FIP creation tool included in the TF-A
-project. Examples below show how to build a FIP file for FVP, packaging TF-A
-and BL33 images.
-
-For AArch64:
-
-.. code:: shell
-
- make PLAT=fvp BL33=<path-to>/bl33.bin fip
-
-For AArch32:
-
-.. code:: shell
-
- make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip
-
-The resulting FIP may be found in:
-
-::
-
- build/fvp/<build-type>/fip.bin
-
-For advanced operations on FIP files, it is also possible to independently build
-the tool and create or modify FIPs using this tool. To do this, follow these
-steps:
-
-It is recommended to remove old artifacts before building the tool:
-
-.. code:: shell
-
- make -C tools/fiptool clean
-
-Build the tool:
-
-.. code:: shell
-
- make [DEBUG=1] [V=1] fiptool
-
-The tool binary can be located in:
-
-::
-
- ./tools/fiptool/fiptool
-
-Invoking the tool with ``help`` will print a help message with all available
-options.
-
-Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31:
-
-.. code:: shell
-
- ./tools/fiptool/fiptool create \
- --tb-fw build/<platform>/<build-type>/bl2.bin \
- --soc-fw build/<platform>/<build-type>/bl31.bin \
- fip.bin
-
-Example 2: view the contents of an existing Firmware package:
-
-.. code:: shell
-
- ./tools/fiptool/fiptool info <path-to>/fip.bin
-
-Example 3: update the entries of an existing Firmware package:
-
-.. code:: shell
-
- # Change the BL2 from Debug to Release version
- ./tools/fiptool/fiptool update \
- --tb-fw build/<platform>/release/bl2.bin \
- build/<platform>/debug/fip.bin
-
-Example 4: unpack all entries from an existing Firmware package:
-
-.. code:: shell
-
- # Images will be unpacked to the working directory
- ./tools/fiptool/fiptool unpack <path-to>/fip.bin
-
-Example 5: remove an entry from an existing Firmware package:
-
-.. code:: shell
-
- ./tools/fiptool/fiptool remove \
- --tb-fw build/<platform>/debug/fip.bin
-
-Note that if the destination FIP file exists, the create, update and
-remove operations will automatically overwrite it.
-
-The unpack operation will fail if the images already exist at the
-destination. In that case, use -f or --force to continue.
-
-More information about FIP can be found in the :ref:`Firmware Design` document.
-
-Building FIP images with support for Trusted Board Boot
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Trusted Board Boot primarily consists of the following two features:
-
-- Image Authentication, described in :ref:`Trusted Board Boot`, and
-- Firmware Update, described in :ref:`Firmware Update (FWU)`
-
-The following steps should be followed to build FIP and (optionally) FWU_FIP
-images with support for these features:
-
-#. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser
- modules by checking out a recent version of the `mbed TLS Repository`_. It
- is important to use a version that is compatible with TF-A and fixes any
- known security vulnerabilities. See `mbed TLS Security Center`_ for more
- information. The latest version of TF-A is tested with tag
- ``mbedtls-2.16.2``.
-
- The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS
- source files the modules depend upon.
- ``include/drivers/auth/mbedtls/mbedtls_config.h`` contains the configuration
- options required to build the mbed TLS sources.
-
- Note that the mbed TLS library is licensed under the Apache version 2.0
- license. Using mbed TLS source code will affect the licensing of TF-A
- binaries that are built using this library.
-
-#. To build the FIP image, ensure the following command line variables are set
- while invoking ``make`` to build TF-A:
-
- - ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>``
- - ``TRUSTED_BOARD_BOOT=1``
- - ``GENERATE_COT=1``
-
- In the case of Arm platforms, the location of the ROTPK hash must also be
- specified at build time. Two locations are currently supported (see
- ``ARM_ROTPK_LOCATION`` build option):
-
- - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted
- root-key storage registers present in the platform. On Juno, this
- registers are read-only. On FVP Base and Cortex models, the registers
- are read-only, but the value can be specified using the command line
- option ``bp.trusted_key_storage.public_key`` when launching the model.
- On both Juno and FVP models, the default value corresponds to an
- ECDSA-SECP256R1 public key hash, whose private part is not currently
- available.
-
- - ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded
- in the Arm platform port. The private/public RSA key pair may be
- found in ``plat/arm/board/common/rotpk``.
-
- - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded
- in the Arm platform port. The private/public ECDSA key pair may be
- found in ``plat/arm/board/common/rotpk``.
-
- Example of command line using RSA development keys:
-
- .. code:: shell
-
- MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
- make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
- ARM_ROTPK_LOCATION=devel_rsa \
- ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
- BL33=<path-to>/<bl33_image> \
- all fip
-
- The result of this build will be the bl1.bin and the fip.bin binaries. This
- FIP will include the certificates corresponding to the Chain of Trust
- described in the TBBR-client document. These certificates can also be found
- in the output build directory.
-
-#. The optional FWU_FIP contains any additional images to be loaded from
- Non-Volatile storage during the :ref:`Firmware Update (FWU)` process. To
- build the FWU_FIP, any FWU images required by the platform must be specified
- on the command line. On Arm development platforms like Juno, these are:
-
- - NS_BL2U. The AP non-secure Firmware Updater image.
- - SCP_BL2U. The SCP Firmware Update Configuration image.
-
- Example of Juno command line for generating both ``fwu`` and ``fwu_fip``
- targets using RSA development:
-
- ::
-
- MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
- make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \
- ARM_ROTPK_LOCATION=devel_rsa \
- ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
- BL33=<path-to>/<bl33_image> \
- SCP_BL2=<path-to>/<scp_bl2_image> \
- SCP_BL2U=<path-to>/<scp_bl2u_image> \
- NS_BL2U=<path-to>/<ns_bl2u_image> \
- all fip fwu_fip
-
- .. note::
- The BL2U image will be built by default and added to the FWU_FIP.
- The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
- to the command line above.
-
- .. note::
- Building and installing the non-secure and SCP FWU images (NS_BL1U,
- NS_BL2U and SCP_BL2U) is outside the scope of this document.
-
- The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries.
- Both the FIP and FWU_FIP will include the certificates corresponding to the
- Chain of Trust described in the TBBR-client document. These certificates
- can also be found in the output build directory.
-
-Building the Certificate Generation Tool
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``cert_create`` tool is built as part of the TF-A build process when the
-``fip`` make target is specified and TBB is enabled (as described in the
-previous section), but it can also be built separately with the following
-command:
-
-.. code:: shell
-
- make PLAT=<platform> [DEBUG=1] [V=1] certtool
-
-For platforms that require their own IDs in certificate files, the generic
-'cert_create' tool can be built with the following command. Note that the target
-platform must define its IDs within a ``platform_oid.h`` header file for the
-build to succeed.
-
-.. code:: shell
-
- make PLAT=<platform> USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool
-
-``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
-verbose. The following command should be used to obtain help about the tool:
-
-.. code:: shell
-
- ./tools/cert_create/cert_create -h
-
-Building a FIP for Juno and FVP
--------------------------------
-
-This section provides Juno and FVP specific instructions to build Trusted
-Firmware, obtain the additional required firmware, and pack it all together in
-a single FIP binary. It assumes that a `Linaro Release`_ has been installed.
-
-.. note::
- Pre-built binaries for AArch32 are available from Linaro Release 16.12
- onwards. Before that release, pre-built binaries are only available for
- AArch64.
-
-.. warning::
- Follow the full instructions for one platform before switching to a
- different one. Mixing instructions for different platforms may result in
- corrupted binaries.
-
-.. warning::
- The uboot image downloaded by the Linaro workspace script does not always
- match the uboot image packaged as BL33 in the corresponding fip file. It is
- recommended to use the version that is packaged in the fip file using the
- instructions below.
-
-.. note::
- For the FVP, the kernel FDT is packaged in FIP during build and loaded
- by the firmware at runtime. See `Obtaining the Flattened Device Trees`_
- section for more info on selecting the right FDT to use.
-
-#. Clean the working directory
-
- .. code:: shell
-
- make realclean
-
-#. Obtain SCP_BL2 (Juno) and BL33 (all platforms)
-
- Use the fiptool to extract the SCP_BL2 and BL33 images from the FIP
- package included in the Linaro release:
-
- .. code:: shell
-
- # Build the fiptool
- make [DEBUG=1] [V=1] fiptool
-
- # Unpack firmware images from Linaro FIP
- ./tools/fiptool/fiptool unpack <path-to-linaro-release>/[SOFTWARE]/fip.bin
-
- The unpack operation will result in a set of binary images extracted to the
- current working directory. The SCP_BL2 image corresponds to
- ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``.
-
- .. note::
- The fiptool will complain if the images to be unpacked already
- exist in the current directory. If that is the case, either delete those
- files or use the ``--force`` option to overwrite.
-
- .. note::
- For AArch32, the instructions below assume that nt-fw.bin is a
- normal world boot loader that supports AArch32.
-
-#. Build TF-A images and create a new FIP for FVP
-
- .. code:: shell
-
- # AArch64
- make PLAT=fvp BL33=nt-fw.bin all fip
-
- # AArch32
- make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip
-
-#. Build TF-A images and create a new FIP for Juno
-
- For AArch64:
-
- Building for AArch64 on Juno simply requires the addition of ``SCP_BL2``
- as a build parameter.
-
- .. code:: shell
-
- make PLAT=juno BL33=nt-fw.bin SCP_BL2=scp-fw.bin all fip
-
- For AArch32:
-
- Hardware restrictions on Juno prevent cold reset into AArch32 execution mode,
- therefore BL1 and BL2 must be compiled for AArch64, and BL32 is compiled
- separately for AArch32.
-
- - Before building BL32, the environment variable ``CROSS_COMPILE`` must point
- to the AArch32 cross compiler.
-
- .. code:: shell
-
- export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-eabi-
-
- - Build BL32 in AArch32.
-
- .. code:: shell
-
- make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \
- RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32
-
- - Save ``bl32.bin`` to a temporary location and clean the build products.
-
- ::
-
- cp <path-to-build>/bl32.bin <path-to-temporary>
- make realclean
-
- - Before building BL1 and BL2, the environment variable ``CROSS_COMPILE``
- must point to the AArch64 cross compiler.
-
- .. code:: shell
-
- export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
-
- - The following parameters should be used to build BL1 and BL2 in AArch64
- and point to the BL32 file.
-
- .. code:: shell
-
- make ARCH=aarch64 PLAT=juno JUNO_AARCH32_EL3_RUNTIME=1 \
- BL33=nt-fw.bin SCP_BL2=scp-fw.bin \
- BL32=<path-to-temporary>/bl32.bin all fip
-
-The resulting BL1 and FIP images may be found in:
-
-::
-
- # Juno
- ./build/juno/release/bl1.bin
- ./build/juno/release/fip.bin
-
- # FVP
- ./build/fvp/release/bl1.bin
- ./build/fvp/release/fip.bin
-
-
-Booting Firmware Update images
--------------------------------------
-
-When Firmware Update (FWU) is enabled there are at least 2 new images
-that have to be loaded, the Non-Secure FWU ROM (NS-BL1U), and the
-FWU FIP.
-
-Juno
-~~~~
-
-The new images must be programmed in flash memory by adding
-an entry in the ``SITE1/HBI0262x/images.txt`` configuration file
-on the Juno SD card (where ``x`` depends on the revision of the Juno board).
-Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory
-programming" for more information. User should ensure these do not
-overlap with any other entries in the file.
-
-::
-
- NOR10UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
- NOR10ADDRESS: 0x00400000 ;Image Flash Address [ns_bl2u_base_address]
- NOR10FILE: \SOFTWARE\fwu_fip.bin ;Image File Name
- NOR10LOAD: 00000000 ;Image Load Address
- NOR10ENTRY: 00000000 ;Image Entry Point
-
- NOR11UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
- NOR11ADDRESS: 0x03EB8000 ;Image Flash Address [ns_bl1u_base_address]
- NOR11FILE: \SOFTWARE\ns_bl1u.bin ;Image File Name
- NOR11LOAD: 00000000 ;Image Load Address
-
-The address ns_bl1u_base_address is the value of NS_BL1U_BASE - 0x8000000.
-In the same way, the address ns_bl2u_base_address is the value of
-NS_BL2U_BASE - 0x8000000.
-
-FVP
-~~~
-
-The additional fip images must be loaded with:
-
-::
-
- --data cluster0.cpu0="<path_to>/ns_bl1u.bin"@0x0beb8000 [ns_bl1u_base_address]
- --data cluster0.cpu0="<path_to>/fwu_fip.bin"@0x08400000 [ns_bl2u_base_address]
-
-The address ns_bl1u_base_address is the value of NS_BL1U_BASE.
-In the same way, the address ns_bl2u_base_address is the value of
-NS_BL2U_BASE.
-
-
-EL3 payloads alternative boot flow
-----------------------------------
-
-On a pre-production system, the ability to execute arbitrary, bare-metal code at
-the highest exception level is required. It allows full, direct access to the
-hardware, for example to run silicon soak tests.
-
-Although it is possible to implement some baremetal secure firmware from
-scratch, this is a complex task on some platforms, depending on the level of
-configuration required to put the system in the expected state.
-
-Rather than booting a baremetal application, a possible compromise is to boot
-``EL3 payloads`` through TF-A instead. This is implemented as an alternative
-boot flow, where a modified BL2 boots an EL3 payload, instead of loading the
-other BL images and passing control to BL31. It reduces the complexity of
-developing EL3 baremetal code by:
-
-- putting the system into a known architectural state;
-- taking care of platform secure world initialization;
-- loading the SCP_BL2 image if required by the platform.
-
-When booting an EL3 payload on Arm standard platforms, the configuration of the
-TrustZone controller is simplified such that only region 0 is enabled and is
-configured to permit secure access only. This gives full access to the whole
-DRAM to the EL3 payload.
-
-The system is left in the same state as when entering BL31 in the default boot
-flow. In particular:
-
-- Running in EL3;
-- Current state is AArch64;
-- Little-endian data access;
-- All exceptions disabled;
-- MMU disabled;
-- Caches disabled.
-
-Booting an EL3 payload
-~~~~~~~~~~~~~~~~~~~~~~
-
-The EL3 payload image is a standalone image and is not part of the FIP. It is
-not loaded by TF-A. Therefore, there are 2 possible scenarios:
-
-- The EL3 payload may reside in non-volatile memory (NVM) and execute in
- place. In this case, booting it is just a matter of specifying the right
- address in NVM through ``EL3_PAYLOAD_BASE`` when building TF-A.
-
-- The EL3 payload needs to be loaded in volatile memory (e.g. DRAM) at
- run-time.
-
-To help in the latter scenario, the ``SPIN_ON_BL1_EXIT=1`` build option can be
-used. The infinite loop that it introduces in BL1 stops execution at the right
-moment for a debugger to take control of the target and load the payload (for
-example, over JTAG).
-
-It is expected that this loading method will work in most cases, as a debugger
-connection is usually available in a pre-production system. The user is free to
-use any other platform-specific mechanism to load the EL3 payload, though.
-
-Booting an EL3 payload on FVP
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The EL3 payloads boot flow requires the CPU's mailbox to be cleared at reset for
-the secondary CPUs holding pen to work properly. Unfortunately, its reset value
-is undefined on the FVP platform and the FVP platform code doesn't clear it.
-Therefore, one must modify the way the model is normally invoked in order to
-clear the mailbox at start-up.
-
-One way to do that is to create an 8-byte file containing all zero bytes using
-the following command:
-
-.. code:: shell
-
- dd if=/dev/zero of=mailbox.dat bs=1 count=8
-
-and pre-load it into the FVP memory at the mailbox address (i.e. ``0x04000000``)
-using the following model parameters:
-
-::
-
- --data cluster0.cpu0=mailbox.dat@0x04000000 [Base FVPs]
- --data=mailbox.dat@0x04000000 [Foundation FVP]
-
-To provide the model with the EL3 payload image, the following methods may be
-used:
-
-#. If the EL3 payload is able to execute in place, it may be programmed into
- flash memory. On Base Cortex and AEM FVPs, the following model parameter
- loads it at the base address of the NOR FLASH1 (the NOR FLASH0 is already
- used for the FIP):
-
- ::
-
- -C bp.flashloader1.fname="<path-to>/<el3-payload>"
-
- On Foundation FVP, there is no flash loader component and the EL3 payload
- may be programmed anywhere in flash using method 3 below.
-
-#. When using the ``SPIN_ON_BL1_EXIT=1`` loading method, the following DS-5
- command may be used to load the EL3 payload ELF image over JTAG:
-
- ::
-
- load <path-to>/el3-payload.elf
-
-#. The EL3 payload may be pre-loaded in volatile memory using the following
- model parameters:
-
- ::
-
- --data cluster0.cpu0="<path-to>/el3-payload>"@address [Base FVPs]
- --data="<path-to>/<el3-payload>"@address [Foundation FVP]
-
- The address provided to the FVP must match the ``EL3_PAYLOAD_BASE`` address
- used when building TF-A.
-
-Booting an EL3 payload on Juno
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If the EL3 payload is able to execute in place, it may be programmed in flash
-memory by adding an entry in the ``SITE1/HBI0262x/images.txt`` configuration file
-on the Juno SD card (where ``x`` depends on the revision of the Juno board).
-Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory
-programming" for more information.
-
-Alternatively, the same DS-5 command mentioned in the FVP section above can
-be used to load the EL3 payload's ELF file over JTAG on Juno.
-
-Preloaded BL33 alternative boot flow
-------------------------------------
-
-Some platforms have the ability to preload BL33 into memory instead of relying
-on TF-A to load it. This may simplify packaging of the normal world code and
-improve performance in a development environment. When secure world cold boot
-is complete, TF-A simply jumps to a BL33 base address provided at build time.
-
-For this option to be used, the ``PRELOADED_BL33_BASE`` build option has to be
-used when compiling TF-A. For example, the following command will create a FIP
-without a BL33 and prepare to jump to a BL33 image loaded at address
-0x80000000:
-
-.. code:: shell
-
- make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip
-
-Boot of a preloaded kernel image on Base FVP
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following example uses a simplified boot flow by directly jumping from the
-TF-A to the Linux kernel, which will use a ramdisk as filesystem. This can be
-useful if both the kernel and the device tree blob (DTB) are already present in
-memory (like in FVP).
-
-For example, if the kernel is loaded at ``0x80080000`` and the DTB is loaded at
-address ``0x82000000``, the firmware can be built like this:
-
-.. code:: shell
-
- CROSS_COMPILE=aarch64-linux-gnu- \
- make PLAT=fvp DEBUG=1 \
- RESET_TO_BL31=1 \
- ARM_LINUX_KERNEL_AS_BL33=1 \
- PRELOADED_BL33_BASE=0x80080000 \
- ARM_PRELOADED_DTB_BASE=0x82000000 \
- all fip
-
-Now, it is needed to modify the DTB so that the kernel knows the address of the
-ramdisk. The following script generates a patched DTB from the provided one,
-assuming that the ramdisk is loaded at address ``0x84000000``. Note that this
-script assumes that the user is using a ramdisk image prepared for U-Boot, like
-the ones provided by Linaro. If using a ramdisk without this header,the ``0x40``
-offset in ``INITRD_START`` has to be removed.
-
-.. code:: bash
-
- #!/bin/bash
-
- # Path to the input DTB
- KERNEL_DTB=<path-to>/<fdt>
- # Path to the output DTB
- PATCHED_KERNEL_DTB=<path-to>/<patched-fdt>
- # Base address of the ramdisk
- INITRD_BASE=0x84000000
- # Path to the ramdisk
- INITRD=<path-to>/<ramdisk.img>
-
- # Skip uboot header (64 bytes)
- INITRD_START=$(printf "0x%x" $((${INITRD_BASE} + 0x40)) )
- INITRD_SIZE=$(stat -Lc %s ${INITRD})
- INITRD_END=$(printf "0x%x" $((${INITRD_BASE} + ${INITRD_SIZE})) )
-
- CHOSEN_NODE=$(echo \
- "/ { \
- chosen { \
- linux,initrd-start = <${INITRD_START}>; \
- linux,initrd-end = <${INITRD_END}>; \
- }; \
- };")
-
- echo $(dtc -O dts -I dtb ${KERNEL_DTB}) ${CHOSEN_NODE} | \
- dtc -O dtb -o ${PATCHED_KERNEL_DTB} -
-
-And the FVP binary can be run with the following command:
-
-.. code:: shell
-
- <path-to>/FVP_Base_AEMv8A-AEMv8A \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C cluster0.NUM_CORES=4 \
- -C cluster1.NUM_CORES=4 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.RVBAR=0x04020000 \
- -C cluster0.cpu1.RVBAR=0x04020000 \
- -C cluster0.cpu2.RVBAR=0x04020000 \
- -C cluster0.cpu3.RVBAR=0x04020000 \
- -C cluster1.cpu0.RVBAR=0x04020000 \
- -C cluster1.cpu1.RVBAR=0x04020000 \
- -C cluster1.cpu2.RVBAR=0x04020000 \
- -C cluster1.cpu3.RVBAR=0x04020000 \
- --data cluster0.cpu0="<path-to>/bl31.bin"@0x04020000 \
- --data cluster0.cpu0="<path-to>/<patched-fdt>"@0x82000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- --data cluster0.cpu0="<path-to>/<ramdisk.img>"@0x84000000
-
-Boot of a preloaded kernel image on Juno
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The Trusted Firmware must be compiled in a similar way as for FVP explained
-above. The process to load binaries to memory is the one explained in
-`Booting an EL3 payload on Juno`_.
-
-.. _user_guide_run_fvp:
-
-Running the software on FVP
----------------------------
-
-The latest version of the AArch64 build of TF-A has been tested on the following
-Arm FVPs without shifted affinities, and that do not support threaded CPU cores
-(64-bit host machine only).
-
-.. note::
- The FVP models used are Version 11.6 Build 45, unless otherwise stated.
-
-- ``FVP_Base_AEMv8A-AEMv8A``
-- ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502``
-- ``FVP_Base_RevC-2xAEMv8A``
-- ``FVP_Base_Cortex-A32x4``
-- ``FVP_Base_Cortex-A35x4``
-- ``FVP_Base_Cortex-A53x4``
-- ``FVP_Base_Cortex-A55x4+Cortex-A75x4``
-- ``FVP_Base_Cortex-A55x4``
-- ``FVP_Base_Cortex-A57x1-A53x1``
-- ``FVP_Base_Cortex-A57x2-A53x4``
-- ``FVP_Base_Cortex-A57x4-A53x4``
-- ``FVP_Base_Cortex-A57x4``
-- ``FVP_Base_Cortex-A72x4-A53x4``
-- ``FVP_Base_Cortex-A72x4``
-- ``FVP_Base_Cortex-A73x4-A53x4``
-- ``FVP_Base_Cortex-A73x4``
-- ``FVP_Base_Cortex-A75x4``
-- ``FVP_Base_Cortex-A76x4``
-- ``FVP_Base_Cortex-A76AEx4``
-- ``FVP_Base_Cortex-A76AEx8``
-- ``FVP_Base_Cortex-A77x4`` (Version 11.7 build 36)
-- ``FVP_Base_Neoverse-N1x4``
-- ``FVP_Base_Zeusx4``
-- ``FVP_CSS_SGI-575`` (Version 11.3 build 42)
-- ``FVP_CSS_SGM-775`` (Version 11.3 build 42)
-- ``FVP_RD_E1Edge`` (Version 11.3 build 42)
-- ``FVP_RD_N1Edge``
-- ``Foundation_Platform``
-
-The latest version of the AArch32 build of TF-A has been tested on the following
-Arm FVPs without shifted affinities, and that do not support threaded CPU cores
-(64-bit host machine only).
-
-- ``FVP_Base_AEMv8A-AEMv8A``
-- ``FVP_Base_Cortex-A32x4``
-
-.. note::
- The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which
- is not compatible with legacy GIC configurations. Therefore this FVP does not
- support these legacy GIC configurations.
-
-.. note::
- The build numbers quoted above are those reported by launching the FVP
- with the ``--version`` parameter.
-
-.. note::
- Linaro provides a ramdisk image in prebuilt FVP configurations and full
- file systems that can be downloaded separately. To run an FVP with a virtio
- file system image an additional FVP configuration option
- ``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
- used.
-
-.. note::
- The software will not work on Version 1.0 of the Foundation FVP.
- The commands below would report an ``unhandled argument`` error in this case.
-
-.. note::
- FVPs can be launched with ``--cadi-server`` option such that a
- CADI-compliant debugger (for example, Arm DS-5) can connect to and control
- its execution.
-
-.. warning::
- Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202
- the internal synchronisation timings changed compared to older versions of
- the models. The models can be launched with ``-Q 100`` option if they are
- required to match the run time characteristics of the older versions.
-
-The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
-downloaded for free from `Arm's website`_.
-
-The Cortex-A models listed above are also available to download from
-`Arm's website`_.
-
-Please refer to the FVP documentation for a detailed description of the model
-parameter options. A brief description of the important ones that affect TF-A
-and normal world software behavior is provided below.
-
-Obtaining the Flattened Device Trees
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Depending on the FVP configuration and Linux configuration used, different
-FDT files are required. FDT source files for the Foundation and Base FVPs can
-be found in the TF-A source directory under ``fdts/``. The Foundation FVP has
-a subset of the Base FVP components. For example, the Foundation FVP lacks
-CLCD and MMC support, and has only one CPU cluster.
-
-.. note::
- It is not recommended to use the FDTs built along the kernel because not
- all FDTs are available from there.
-
-The dynamic configuration capability is enabled in the firmware for FVPs.
-This means that the firmware can authenticate and load the FDT if present in
-FIP. A default FDT is packaged into FIP during the build based on
-the build configuration. This can be overridden by using the ``FVP_HW_CONFIG``
-or ``FVP_HW_CONFIG_DTS`` build options (refer to the
-`Arm FVP platform specific build options`_ section for detail on the options).
-
-- ``fvp-base-gicv2-psci.dts``
-
- For use with models such as the Cortex-A57-A53 Base FVPs without shifted
- affinities and with Base memory map configuration.
-
-- ``fvp-base-gicv2-psci-aarch32.dts``
-
- For use with models such as the Cortex-A32 Base FVPs without shifted
- affinities and running Linux in AArch32 state with Base memory map
- configuration.
-
-- ``fvp-base-gicv3-psci.dts``
-
- For use with models such as the Cortex-A57-A53 Base FVPs without shifted
- affinities and with Base memory map configuration and Linux GICv3 support.
-
-- ``fvp-base-gicv3-psci-1t.dts``
-
- For use with models such as the AEMv8-RevC Base FVP with shifted affinities,
- single threaded CPUs, Base memory map configuration and Linux GICv3 support.
-
-- ``fvp-base-gicv3-psci-dynamiq.dts``
-
- For use with models as the Cortex-A55-A75 Base FVPs with shifted affinities,
- single cluster, single threaded CPUs, Base memory map configuration and Linux
- GICv3 support.
-
-- ``fvp-base-gicv3-psci-aarch32.dts``
-
- For use with models such as the Cortex-A32 Base FVPs without shifted
- affinities and running Linux in AArch32 state with Base memory map
- configuration and Linux GICv3 support.
-
-- ``fvp-foundation-gicv2-psci.dts``
-
- For use with Foundation FVP with Base memory map configuration.
-
-- ``fvp-foundation-gicv3-psci.dts``
-
- (Default) For use with Foundation FVP with Base memory map configuration
- and Linux GICv3 support.
-
-Running on the Foundation FVP with reset to BL1 entrypoint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following ``Foundation_Platform`` parameters should be used to boot Linux with
-4 CPUs using the AArch64 build of TF-A.
-
-.. code:: shell
-
- <path-to>/Foundation_Platform \
- --cores=4 \
- --arm-v8.0 \
- --secure-memory \
- --visualization \
- --gicv3 \
- --data="<path-to>/<bl1-binary>"@0x0 \
- --data="<path-to>/<FIP-binary>"@0x08000000 \
- --data="<path-to>/<kernel-binary>"@0x80080000 \
- --data="<path-to>/<ramdisk-binary>"@0x84000000
-
-Notes:
-
-- BL1 is loaded at the start of the Trusted ROM.
-- The Firmware Image Package is loaded at the start of NOR FLASH0.
-- The firmware loads the FDT packaged in FIP to the DRAM. The FDT load address
- is specified via the ``hw_config_addr`` property in ``TB_FW_CONFIG`` for FVP.
-- The default use-case for the Foundation FVP is to use the ``--gicv3`` option
- and enable the GICv3 device in the model. Note that without this option,
- the Foundation FVP defaults to legacy (Versatile Express) memory map which
- is not supported by TF-A.
-- In order for TF-A to run correctly on the Foundation FVP, the architecture
- versions must match. The Foundation FVP defaults to the highest v8.x
- version it supports but the default build for TF-A is for v8.0. To avoid
- issues either start the Foundation FVP to use v8.0 architecture using the
- ``--arm-v8.0`` option, or build TF-A with an appropriate value for
- ``ARM_ARCH_MINOR``.
-
-Running on the AEMv8 Base FVP with reset to BL1 entrypoint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following ``FVP_Base_RevC-2xAEMv8A`` parameters should be used to boot Linux
-with 8 CPUs using the AArch64 build of TF-A.
-
-.. code:: shell
-
- <path-to>/FVP_Base_RevC-2xAEMv8A \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cluster0.NUM_CORES=4 \
- -C cluster1.NUM_CORES=4 \
- -C cache_state_modelled=1 \
- -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
- -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-
-.. note::
- The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires
- a specific DTS for all the CPUs to be loaded.
-
-Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
-with 8 CPUs using the AArch32 build of TF-A.
-
-.. code:: shell
-
- <path-to>/FVP_Base_AEMv8A-AEMv8A \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cluster0.NUM_CORES=4 \
- -C cluster1.NUM_CORES=4 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.CONFIG64=0 \
- -C cluster0.cpu1.CONFIG64=0 \
- -C cluster0.cpu2.CONFIG64=0 \
- -C cluster0.cpu3.CONFIG64=0 \
- -C cluster1.cpu0.CONFIG64=0 \
- -C cluster1.cpu1.CONFIG64=0 \
- -C cluster1.cpu2.CONFIG64=0 \
- -C cluster1.cpu3.CONFIG64=0 \
- -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
- -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-
-Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
-boot Linux with 8 CPUs using the AArch64 build of TF-A.
-
-.. code:: shell
-
- <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cache_state_modelled=1 \
- -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
- -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-
-Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
-boot Linux with 4 CPUs using the AArch32 build of TF-A.
-
-.. code:: shell
-
- <path-to>/FVP_Base_Cortex-A32x4 \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cache_state_modelled=1 \
- -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
- -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-
-Running on the AEMv8 Base FVP with reset to BL31 entrypoint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following ``FVP_Base_RevC-2xAEMv8A`` parameters should be used to boot Linux
-with 8 CPUs using the AArch64 build of TF-A.
-
-.. code:: shell
-
- <path-to>/FVP_Base_RevC-2xAEMv8A \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cluster0.NUM_CORES=4 \
- -C cluster1.NUM_CORES=4 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.RVBAR=0x04010000 \
- -C cluster0.cpu1.RVBAR=0x04010000 \
- -C cluster0.cpu2.RVBAR=0x04010000 \
- -C cluster0.cpu3.RVBAR=0x04010000 \
- -C cluster1.cpu0.RVBAR=0x04010000 \
- -C cluster1.cpu1.RVBAR=0x04010000 \
- -C cluster1.cpu2.RVBAR=0x04010000 \
- -C cluster1.cpu3.RVBAR=0x04010000 \
- --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04010000 \
- --data cluster0.cpu0="<path-to>/<bl32-binary>"@0xff000000 \
- --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-
-Notes:
-
-- If Position Independent Executable (PIE) support is enabled for BL31
- in this config, it can be loaded at any valid address for execution.
-
-- Since a FIP is not loaded when using BL31 as reset entrypoint, the
- ``--data="<path-to><bl31|bl32|bl33-binary>"@<base-address-of-binary>``
- parameter is needed to load the individual bootloader images in memory.
- BL32 image is only needed if BL31 has been built to expect a Secure-EL1
- Payload. For the same reason, the FDT needs to be compiled from the DT source
- and loaded via the ``--data cluster0.cpu0="<path-to>/<fdt>"@0x82000000``
- parameter.
-
-- The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a
- specific DTS for all the CPUs to be loaded.
-
-- The ``-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>`` parameter, where
- X and Y are the cluster and CPU numbers respectively, is used to set the
- reset vector for each core.
-
-- Changing the default value of ``ARM_TSP_RAM_LOCATION`` will also require
- changing the value of
- ``--data="<path-to><bl32-binary>"@<base-address-of-bl32>`` to the new value of
- ``BL32_BASE``.
-
-Running on the AEMv8 Base FVP (AArch32) with reset to SP_MIN entrypoint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
-with 8 CPUs using the AArch32 build of TF-A.
-
-.. code:: shell
-
- <path-to>/FVP_Base_AEMv8A-AEMv8A \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cluster0.NUM_CORES=4 \
- -C cluster1.NUM_CORES=4 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.CONFIG64=0 \
- -C cluster0.cpu1.CONFIG64=0 \
- -C cluster0.cpu2.CONFIG64=0 \
- -C cluster0.cpu3.CONFIG64=0 \
- -C cluster1.cpu0.CONFIG64=0 \
- -C cluster1.cpu1.CONFIG64=0 \
- -C cluster1.cpu2.CONFIG64=0 \
- -C cluster1.cpu3.CONFIG64=0 \
- -C cluster0.cpu0.RVBAR=0x04002000 \
- -C cluster0.cpu1.RVBAR=0x04002000 \
- -C cluster0.cpu2.RVBAR=0x04002000 \
- -C cluster0.cpu3.RVBAR=0x04002000 \
- -C cluster1.cpu0.RVBAR=0x04002000 \
- -C cluster1.cpu1.RVBAR=0x04002000 \
- -C cluster1.cpu2.RVBAR=0x04002000 \
- -C cluster1.cpu3.RVBAR=0x04002000 \
- --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04002000 \
- --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-
-.. note::
- The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``.
- It should match the address programmed into the RVBAR register as well.
-
-Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
-boot Linux with 8 CPUs using the AArch64 build of TF-A.
-
-.. code:: shell
-
- <path-to>/FVP_Base_Cortex-A57x4-A53x4 \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.RVBARADDR=0x04010000 \
- -C cluster0.cpu1.RVBARADDR=0x04010000 \
- -C cluster0.cpu2.RVBARADDR=0x04010000 \
- -C cluster0.cpu3.RVBARADDR=0x04010000 \
- -C cluster1.cpu0.RVBARADDR=0x04010000 \
- -C cluster1.cpu1.RVBARADDR=0x04010000 \
- -C cluster1.cpu2.RVBARADDR=0x04010000 \
- -C cluster1.cpu3.RVBARADDR=0x04010000 \
- --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04010000 \
- --data cluster0.cpu0="<path-to>/<bl32-binary>"@0xff000000 \
- --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-
-Running on the Cortex-A32 Base FVP (AArch32) with reset to SP_MIN entrypoint
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
-boot Linux with 4 CPUs using the AArch32 build of TF-A.
-
-.. code:: shell
-
- <path-to>/FVP_Base_Cortex-A32x4 \
- -C pctl.startup=0.0.0.0 \
- -C bp.secure_memory=1 \
- -C bp.tzc_400.diagnostics=1 \
- -C cache_state_modelled=1 \
- -C cluster0.cpu0.RVBARADDR=0x04002000 \
- -C cluster0.cpu1.RVBARADDR=0x04002000 \
- -C cluster0.cpu2.RVBARADDR=0x04002000 \
- -C cluster0.cpu3.RVBARADDR=0x04002000 \
- --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04002000 \
- --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
- --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
- --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
- --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-
-Running the software on Juno
-----------------------------
-
-This version of TF-A has been tested on variants r0, r1 and r2 of Juno.
-
-To execute the software stack on Juno, installing the latest Arm Platforms
-software deliverables is recommended. Please install the deliverables by
-following the `Instructions for using Linaro's deliverables on Juno`_.
-
-Preparing TF-A images
-~~~~~~~~~~~~~~~~~~~~~
-
-After building TF-A, the files ``bl1.bin`` and ``fip.bin`` need copying to the
-``SOFTWARE/`` directory of the Juno SD card.
-
-Other Juno software information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Please visit the `Arm Platforms Portal`_ to get support and obtain any other Juno
-software information. Please also refer to the `Juno Getting Started Guide`_ to
-get more detailed information about the Juno Arm development platform and how to
-configure it.
-
-Testing SYSTEM SUSPEND on Juno
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend
-to RAM. For more details refer to section 5.16 of `PSCI`_. To test system suspend
-on Juno, at the linux shell prompt, issue the following command:
-
-.. code:: shell
-
- echo +10 > /sys/class/rtc/rtc0/wakealarm
- echo -n mem > /sys/power/state
-
-The Juno board should suspend to RAM and then wakeup after 10 seconds due to
-wakeup interrupt from RTC.
-
---------------
-
-*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
-
-.. _Arm Developer page: https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads
-.. _Linaro Release: http://releases.linaro.org/members/arm/platforms
-.. _Linaro Release 19.06: http://releases.linaro.org/members/arm/platforms/19.06
-.. _Linaro instructions: https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about
-.. _Arm Platforms User guide: https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about/docs/user-guide.rst
-.. _Instructions for using Linaro's deliverables on Juno: https://community.arm.com/dev-platforms/w/docs/303/juno
-.. _Arm Platforms Portal: https://community.arm.com/dev-platforms/
-.. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio
-.. _arm-trusted-firmware-a project page: https://review.trustedfirmware.org/admin/projects/TF-A/trusted-firmware-a
-.. _`Linux Coding Style`: https://www.kernel.org/doc/html/latest/process/coding-style.html
-.. _Linux master tree: https://github.com/torvalds/linux/tree/master/
-.. _Dia: https://wiki.gnome.org/Apps/Dia/Download
-.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
-.. _mbed TLS Security Center: https://tls.mbed.org/security
-.. _Arm's website: `FVP models`_
-.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
-.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf
-.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf