Snap for 6188643 from cabe6937f2c9d0a50e4631c0545bddd650233ae8 to rvc-releaseandroid-vts-11.0_r5android-vts-11.0_r4android-vts-11.0_r3android-vts-11.0_r2android-vts-11.0_r1android-security-11.0.0_r1android-platform-11.0.0_r9android-platform-11.0.0_r8android-platform-11.0.0_r7android-platform-11.0.0_r6android-platform-11.0.0_r5android-platform-11.0.0_r4android-platform-11.0.0_r3android-platform-11.0.0_r2android-platform-11.0.0_r10android-platform-11.0.0_r1android-cts-11.0_r5android-cts-11.0_r4android-cts-11.0_r3android-cts-11.0_r2android-cts-11.0_r1android-11.0.0_r5android-11.0.0_r4android-11.0.0_r3android-11.0.0_r25android-11.0.0_r2android-11.0.0_r17android-11.0.0_r1android11-tests-releaseandroid11-security-releaseandroid11-s1-releaseandroid11-releaseandroid11-platform-releaseandroid11-gsi

Change-Id: Id9d1eda28e2f504532858d4c602eeebec865f19e

9 files changed, 352 insertions, 114 deletions

diff --git a/docs/design/alt-boot-flows.rst b/docs/design/alt-boot-flows.rst
new file mode 100644
index 000000000..b44c061d4
--- /dev/null
+++ b/docs/design/alt-boot-flows.rst
@@ -0,0 +1,84 @@
+Alternative Boot Flows
+======================
+
+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.
+
+.. _alt_boot_flows_el3_payload:
+
+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.
+
+
+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
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst
index da958b7c2..93f691b7b 100644
--- a/docs/design/auth-framework.rst
+++ b/docs/design/auth-framework.rst
@@ -637,9 +637,9 @@ all CoTs must present:
 
 The TBBR specifies the additional certificates that must accompany these images
 for a proper authentication. Details about the TBBR CoT may be found in the
-`Trusted Board Boot`_ document.
+:ref:`Trusted Board Boot` document.
 
-Following the `Platform Porting Guide`_, a platform must provide unique
+Following the :ref:`Porting Guide`, a platform must provide unique
 identifiers for all the images and certificates that will be loaded during the
 boot process. If a platform is using the TBBR as a reference for trusted boot,
 these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``.
@@ -704,7 +704,7 @@ Each image descriptor must specify:
 
 In the ``tbbr_cot.c`` file, a set of buffers are allocated to store the parameters
 extracted from the certificates. In the case of the TBBR CoT, these parameters
-are hashes and public keys. In DER format, an RSA-2048 public key requires 294
+are hashes and public keys. In DER format, an RSA-4096 public key requires 550
 bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication
 process, some of the buffers may be reused at different stages during the boot.
 
@@ -946,12 +946,16 @@ three functions:
     int verify_hash(void *data_ptr, unsigned int data_len,
                     void *digest_info_ptr, unsigned int digest_info_len);
 
-The mbedTLS library algorithm support is configured by the
-``TF_MBEDTLS_KEY_ALG`` variable which can take in 3 values: `rsa`, `ecdsa` or
-`rsa+ecdsa`. This variable allows the Makefile to include the corresponding
-sources in the build for the various algorithms. Setting the variable to
-`rsa+ecdsa` enables support for both rsa and ecdsa algorithms in the mbedTLS
-library.
+The mbedTLS library algorithm support is configured by both the
+``TF_MBEDTLS_KEY_ALG`` and ``TF_MBEDTLS_KEY_SIZE`` variables.
+
+-  ``TF_MBEDTLS_KEY_ALG`` can take in 3 values: `rsa`, `ecdsa` or `rsa+ecdsa`.
+   This variable allows the Makefile to include the corresponding sources in
+   the build for the various algorithms. Setting the variable to `rsa+ecdsa`
+   enables support for both rsa and ecdsa algorithms in the mbedTLS library.
+
+-  ``TF_MBEDTLS_KEY_SIZE`` sets the supported RSA key size for TFA. Valid values
+   include 1024, 2048, 3072 and 4096.
 
 .. note::
    If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
@@ -963,6 +967,4 @@ library.
 
 *Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.*
 
-.. _Trusted Board Boot: ./trusted-board-boot.rst
-.. _Platform Porting Guide: ../getting_started/porting-guide.rst
 .. _TBBR-Client specification: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a
diff --git a/docs/design/cpu-specific-build-macros.rst b/docs/design/cpu-specific-build-macros.rst
index d3fe89d62..f3096b418 100644
--- a/docs/design/cpu-specific-build-macros.rst
+++ b/docs/design/cpu-specific-build-macros.rst
@@ -29,6 +29,8 @@ vulnerability workarounds should be applied at runtime.
    platform contains at least 1 CPU that requires dynamic mitigation.
    Defaults to 0.
 
+.. _arm_cpu_macros_errata_workarounds:
+
 CPU Errata Workarounds
 ----------------------
 
@@ -47,9 +49,8 @@ errata notice document. The format of the define used to enable/disable the
 errata workaround is ``ERRATA_<Processor name>_<ID>``, where the ``Processor name``
 is for example ``A57`` for the ``Cortex_A57`` CPU.
 
-Refer to the section *CPU errata status reporting* in
-`Firmware Design guide`_ for information on how to write errata workaround
-functions.
+Refer to :ref:`firmware_design_cpu_errata_reporting` for information on how to
+write errata workaround functions.
 
 All workarounds are disabled by default. The platform is responsible for
 enabling these workarounds according to its requirement by defining the
@@ -226,6 +227,12 @@ For Cortex-A76, the following errata build flags are defined :
 -  ``ERRATA_A76_1275112``: This applies errata 1275112 workaround to Cortex-A76
    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 
+For Hercules, the following errata build flags are defined :
+
+-  ``ERRATA_HERCULES_1688305``: This applies errata 1688305 workaround to
+   Hercules CPU. This needs to be enabled only for revision r0p0 - r1p0 of
+   the CPU.
+
 For Neoverse N1, the following errata build flags are defined :
 
 -  ``ERRATA_N1_1073348``: This applies errata 1073348 workaround to Neoverse-N1
@@ -258,6 +265,9 @@ For Neoverse N1, the following errata build flags are defined :
 -  ``ERRATA_N1_1315703``: This applies errata 1315703 workaround to Neoverse-N1
    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 
+-  ``ERRATA_N1_1542419``: This applies errata 1542419 workaround to Neoverse-N1
+   CPU. This needs to be enabled only for revisions r3p0 - r4p0 of the CPU.
+
 DSU Errata Workarounds
 ----------------------
 
@@ -314,6 +324,11 @@ architecture that can be enabled by the platform as desired.
    as recommended in section "4.7 Non-Temporal Loads/Stores" of the
    `Cortex-A57 Software Optimization Guide`_.
 
+-  ``NEOVERSE_N1_EXTERNAL_LLC``: This flag indicates that an external last
+   level cache(LLC) is present in the system, and that the DataSource field
+   on the master CHI interface indicates when data is returned from the LLC.
+   This is used to control how the LL_CACHE* PMU events count.
+
 --------------
 
 *Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.*
@@ -323,6 +338,5 @@ architecture that can be enabled by the platform as desired.
 .. _Cortex-A53 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/index.html
 .. _Cortex-A57 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm049219/index.html
 .. _Cortex-A72 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm012079/index.html
-.. _Firmware Design guide: firmware-design.rst
 .. _Cortex-A57 Software Optimization Guide: http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf
 .. _Arm DSU Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm138168/index.html
diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst
index 00e199a20..5fc1335b3 100644
--- a/docs/design/firmware-design.rst
+++ b/docs/design/firmware-design.rst
@@ -2,24 +2,27 @@ Firmware Design
 ===============
 
 Trusted Firmware-A (TF-A) implements a subset of the Trusted Board Boot
-Requirements (TBBR) Platform Design Document (PDD) [1]_ for Arm reference
-platforms. The TBB sequence starts when the platform is powered on and runs up
+Requirements (TBBR) Platform Design Document (PDD) for Arm reference
+platforms.
+
+The TBB sequence starts when the platform is powered on and runs up
 to the stage where it hands-off control to firmware running in the normal
 world in DRAM. This is the cold boot path.
 
-TF-A also implements the Power State Coordination Interface PDD [2]_ as a
+TF-A also implements the `Power State Coordination Interface PDD`_ as a
 runtime service. PSCI is the interface from normal world software to firmware
 implementing power management use-cases (for example, secondary CPU boot,
 hotplug and idle). Normal world software can access TF-A runtime services via
 the Arm SMC (Secure Monitor Call) instruction. The SMC instruction must be
-used as mandated by the SMC Calling Convention [3]_.
+used as mandated by the SMC Calling Convention (`SMCCC`_).
 
 TF-A implements a framework for configuring and managing interrupts generated
 in either security state. The details of the interrupt management framework
-and its design can be found in TF-A Interrupt Management Design guide [4]_.
+and its design can be found in :ref:`Interrupt Management Framework`.
 
 TF-A also implements a library for setting up and managing the translation
-tables. The details of this library can be found in `Translation tables design`_.
+tables. The details of this library can be found in
+:ref:`Translation (XLAT) Tables Library`.
 
 TF-A can be built to support either AArch64 or AArch32 execution state.
 
@@ -34,7 +37,7 @@ executed by the primary CPU, other than essential CPU initialization executed by
 all CPUs. The secondary CPUs are kept in a safe platform-specific state until
 the primary CPU has performed enough initialization to boot them.
 
-Refer to the `Reset Design`_ for more information on the effect of the
+Refer to the :ref:`CPU Reset` for more information on the effect of the
 ``COLD_BOOT_SINGLE_CPU`` platform build option.
 
 The cold boot path in this implementation of TF-A depends on the execution
@@ -136,15 +139,15 @@ Determination of boot path
 
 Whenever a CPU is released from reset, BL1 needs to distinguish between a warm
 boot and a cold boot. This is done using platform-specific mechanisms (see the
-``plat_get_my_entrypoint()`` function in the `Porting Guide`_). In the case of a
-warm boot, a CPU is expected to continue execution from a separate
+``plat_get_my_entrypoint()`` function in the :ref:`Porting Guide`). In the case
+of a warm boot, a CPU is expected to continue execution from a separate
 entrypoint. In the case of a cold boot, the secondary CPUs are placed in a safe
 platform-specific state (see the ``plat_secondary_cold_boot_setup()`` function in
-the `Porting Guide`_) while the primary CPU executes the remaining cold boot path
-as described in the following sections.
+the :ref:`Porting Guide`) while the primary CPU executes the remaining cold boot
+path as described in the following sections.
 
 This step only applies when ``PROGRAMMABLE_RESET_ADDRESS=0``. Refer to the
-`Reset Design`_ for more information on the effect of the
+:ref:`CPU Reset` for more information on the effect of the
 ``PROGRAMMABLE_RESET_ADDRESS`` platform build option.
 
 Architectural initialization
@@ -157,8 +160,8 @@ BL1 performs minimal architectural initialization as follows.
    BL1 sets up simple exception vectors for both synchronous and asynchronous
    exceptions. The default behavior upon receiving an exception is to populate
    a status code in the general purpose register ``X0/R0`` and call the
-   ``plat_report_exception()`` function (see the `Porting Guide`_). The status
-   code is one of:
+   ``plat_report_exception()`` function (see the :ref:`Porting Guide`). The
+   status code is one of:
 
    For AArch64:
 
@@ -217,7 +220,7 @@ BL1 performs minimal architectural initialization as follows.
 
    -  ``BL1_SMC_RUN_IMAGE``: This SMC is raised by BL2 to make BL1 pass control
       to EL3 Runtime Software.
-   -  All SMCs listed in section "BL1 SMC Interface" in the `Firmware Update`_
+   -  All SMCs listed in section "BL1 SMC Interface" in the :ref:`Firmware Update (FWU)`
       Design Guide are supported for AArch64 only. These SMCs are currently
       not supported when BL1 is built for AArch32.
 
@@ -307,14 +310,15 @@ Firmware Update detection and execution
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 After performing platform setup, BL1 common code calls
-``bl1_plat_get_next_image_id()`` to determine if `Firmware Update`_ is required or
-to proceed with the normal boot process. If the platform code returns
-``BL2_IMAGE_ID`` then the normal boot sequence is executed as described in the
-next section, else BL1 assumes that `Firmware Update`_ is required and execution
-passes to the first image in the `Firmware Update`_ process. In either case, BL1
-retrieves a descriptor of the next image by calling ``bl1_plat_get_image_desc()``.
-The image descriptor contains an ``entry_point_info_t`` structure, which BL1
-uses to initialize the execution state of the next image.
+``bl1_plat_get_next_image_id()`` to determine if :ref:`Firmware Update (FWU)` is
+required or to proceed with the normal boot process. If the platform code
+returns ``BL2_IMAGE_ID`` then the normal boot sequence is executed as described
+in the next section, else BL1 assumes that :ref:`Firmware Update (FWU)` is
+required and execution passes to the first image in the
+:ref:`Firmware Update (FWU)` process. In either case, BL1 retrieves a descriptor
+of the next image by calling ``bl1_plat_get_image_desc()``. The image descriptor
+contains an ``entry_point_info_t`` structure, which BL1 uses to initialize the
+execution state of the next image.
 
 BL2 image load and execution
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -440,7 +444,8 @@ initialization is complete. Hence, BL2 populates a platform-specific area of
 memory with the entrypoint and Saved Program Status Register (``SPSR``) of the
 normal world software image. The entrypoint is the load address of the BL33
 image. The ``SPSR`` is determined as specified in Section 5.13 of the
-`PSCI PDD`_. This information is passed to the EL3 Runtime Software.
+`Power State Coordination Interface PDD`_. This information is passed to the
+EL3 Runtime Software.
 
 AArch64 BL31 (EL3 Runtime Software) execution
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -539,7 +544,7 @@ It then replaces the exception vectors populated by BL1 with its own. BL31
 exception vectors implement more elaborate support for handling SMCs since this
 is the only mechanism to access the runtime services implemented by BL31 (PSCI
 for example). BL31 checks each SMC for validity as specified by the
-`SMC calling convention PDD`_ before passing control to the required SMC
+`SMC Calling Convention PDD`_ before passing control to the required SMC
 handler routine.
 
 BL31 programs the ``CNTFRQ_EL0`` register with the clock frequency of the system
@@ -592,7 +597,7 @@ registered function to initialize BL32 before running BL33. This initialization
 is not necessary for AArch32 SPs.
 
 Details on BL32 initialization and the SPD's role are described in the
-"Secure-EL1 Payloads and Dispatchers" section below.
+:ref:`firmware_design_sel1_spd` section below.
 
 BL33 (Non-trusted Firmware) execution
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -812,7 +817,8 @@ data access and all interrupt sources masked:
 
 The warm boot entrypoint may be implemented by using TF-A
 ``psci_warmboot_entrypoint()`` function. In that case, the platform must fulfil
-the pre-requisites mentioned in the `PSCI Library integration guide`_.
+the pre-requisites mentioned in the
+:ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`.
 
 EL3 runtime services framework
 ------------------------------
@@ -862,7 +868,7 @@ not all been instantiated in the current implementation.
 
    TF-A provides a Test Secure-EL1 Payload (TSP) and its associated Dispatcher
    (TSPD). Details of SPD design and TSP/TSPD operation are described in the
-   "Secure-EL1 Payloads and Dispatchers" section below.
+   :ref:`firmware_design_sel1_spd` section below.
 
 #. CPU implementation service
 
@@ -972,8 +978,8 @@ manipulation; and with ``flags`` indicating the security state of the caller. Th
 framework finally sets up the execution stack for the handler, and invokes the
 services ``handle()`` function.
 
-On return from the handler the result registers are populated in X0-X3 before
-restoring the stack and CPU state and returning from the original SMC.
+On return from the handler the result registers are populated in X0-X7 as needed
+before restoring the stack and CPU state and returning from the original SMC.
 
 Exception Handling Framework
 ----------------------------
@@ -1051,7 +1057,9 @@ hooks to be registered with the generic PSCI code to be supported.
 The PSCI implementation in TF-A is a library which can be integrated with
 AArch64 or AArch32 EL3 Runtime Software for Armv8-A systems. A guide to
 integrating PSCI library with AArch32 EL3 Runtime Software can be found
-`here`_.
+at :ref:`PSCI Library Integration guide for Armv8-A AArch32 systems`.
+
+.. _firmware_design_sel1_spd:
 
 Secure-EL1 Payloads and Dispatchers
 -----------------------------------
@@ -1258,7 +1266,7 @@ handling functions.
 
 Details for implementing a CPU specific reset handler can be found in
 Section 8. Details for implementing a platform specific reset handler can be
-found in the `Porting Guide`_ (see the ``plat_reset_handler()`` function).
+found in the :ref:`Porting Guide` (see the ``plat_reset_handler()`` function).
 
 When adding functionality to a reset handler, keep in mind that if a different
 reset handling behavior is required between the first and the subsequent
@@ -1292,6 +1300,8 @@ by the macro ``INTR_PROP_DESC()``. The macro takes the following arguments:
 - Interrupt configuration (either ``GIC_INTR_CFG_LEVEL`` or
   ``GIC_INTR_CFG_EDGE``).
 
+.. _firmware_design_cpu_ops_fwk:
+
 CPU specific operations framework
 ---------------------------------
 
@@ -1333,7 +1343,7 @@ different CPUs during power down and reset handling. The platform can specify
 any CPU optimization it wants to enable for each CPU. It can also specify
 the CPU errata workarounds to be applied for each CPU type during reset
 handling by defining CPU errata compile time macros. Details on these macros
-can be found in `CPU specific build macros`_.
+can be found in the :ref:`Arm CPU Specific Build Macros` document.
 
 The CPU specific operations framework depends on the ``cpu_ops`` structure which
 needs to be exported for each type of CPU in the platform. It is defined in
@@ -1399,6 +1409,8 @@ reporting framework calls ``do_cpu_reg_dump`` which retrieves the matching
 be reported and a pointer to the ASCII list of register names in a format
 expected by the crash reporting framework.
 
+.. _firmware_design_cpu_errata_reporting:
+
 CPU errata status reporting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1408,8 +1420,8 @@ build options. Some errata workarounds have potential run-time implications;
 therefore some are enabled by default, others not. Platform ports shall
 override build options to enable or disable errata as appropriate. The CPU
 drivers take care of applying errata workarounds that are enabled and applicable
-to a given CPU. Refer to the section titled *CPU Errata Workarounds* in `CPUBM`_
-for more information.
+to a given CPU. Refer to :ref:`arm_cpu_macros_errata_workarounds` for more
+information.
 
 Functions in CPU drivers that apply errata workaround must follow the
 conventions listed below.
@@ -1488,6 +1500,11 @@ sections then the resulting binary file would contain zero bytes in place of
 this NOBITS section, making the image unnecessarily bigger. Smaller images
 allow faster loading from the FIP to the main memory.
 
+For BL31, a platform can specify an alternate location for NOBITS sections
+(other than immediately following PROGBITS sections) by setting
+``SEPARATE_NOBITS_REGION`` to 1 and defining ``BL31_NOBITS_BASE`` and
+``BL31_NOBITS_LIMIT``.
+
 Linker scripts and symbols
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1660,7 +1677,7 @@ The following list describes the memory layout on the Arm development platforms:
    point during a cold boot.
 
 -  On Juno, SCP_BL2 is loaded temporarily into the EL3 Runtime Software memory
-   region and transfered to the SCP before being overwritten by EL3 Runtime
+   region and transferred to the SCP before being overwritten by EL3 Runtime
    Software.
 
 -  BL32 (for AArch64) can be loaded in one of the following locations:
@@ -1863,10 +1880,7 @@ BL image during boot.
                |   MHU    |
     0x04000000 +----------+
 
-Library at ROM
----------------
-
-Please refer to the `ROMLIB Design`_ document.
+.. _firmware_design_fip:
 
 Firmware Image Package (FIP)
 ----------------------------
@@ -1978,11 +1992,11 @@ is the smallest possible size of the coherent memory region.
 
 By default, all data structures which are susceptible to accesses with
 mismatched attributes from various CPUs are allocated in a coherent memory
-region (refer to section 2.1 of `Porting Guide`_). The coherent memory region
-accesses are Outer Shareable, non-cacheable and they can be accessed
-with the Device nGnRE attributes when the MMU is turned on. Hence, at the
-expense of at least an extra page of memory, TF-A is able to work around
-coherency issues due to mismatched memory attributes.
+region (refer to section 2.1 of :ref:`Porting Guide`). The coherent memory
+region accesses are Outer Shareable, non-cacheable and they can be accessed with
+the Device nGnRE attributes when the MMU is turned on. Hence, at the expense of
+at least an extra page of memory, TF-A is able to work around coherency issues
+due to mismatched memory attributes.
 
 The alternative to the above approach is to allocate the susceptible data
 structures in Normal WriteBack WriteAllocate Inner shareable memory. This
@@ -2188,7 +2202,7 @@ As mentioned earlier, almost a page of memory can be saved by disabling
 whether coherent memory should be used. If a platform disables
 ``USE_COHERENT_MEM`` and needs to use bakery locks in the porting layer, it can
 optionally define macro ``PLAT_PERCPU_BAKERY_LOCK_SIZE`` (see the
-`Porting Guide`_). Refer to the reference platform code for examples.
+:ref:`Porting Guide`). Refer to the reference platform code for examples.
 
 Isolating code and read-only data on separate memory pages
 ----------------------------------------------------------
@@ -2381,6 +2395,8 @@ are changed within the ``bl31_plat_runtime_setup`` platform hook. The init
 section section can be reclaimed for any data which is accessed after cold
 boot initialization and it is upto the platform to make the decision.
 
+.. _firmware_design_pmf:
+
 Performance Measurement Framework
 ---------------------------------
 
@@ -2529,7 +2545,7 @@ Architecture Extension-specific code is included in the build. Otherwise, TF-A
 targets the base Armv8.0-A architecture; i.e. as if ``ARM_ARCH_MAJOR`` == 8
 and ``ARM_ARCH_MINOR`` == 0, which are also their respective default values.
 
-See also the *Summary of build options* in `User Guide`_.
+.. seealso:: :ref:`Build Options`
 
 For details on the Architecture Extension and available features, please refer
 to the respective Architecture Extension Supplement.
@@ -2540,8 +2556,11 @@ Armv8.1-A
 This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when
 ``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` >= 1.
 
--  The Compare and Swap instruction is used to implement spinlocks. Otherwise,
-   the load-/store-exclusive instruction pair is used.
+-  By default, a load-/store-exclusive instruction pair is used to implement
+   spinlocks. The ``USE_SPINLOCK_CAS`` build option when set to 1 selects the
+   spinlock implementation using the ARMv8.1-LSE Compare and Swap instruction.
+   Notice this instruction is only available in AArch64 execution state, so
+   the option is only available to AArch64 builds.
 
 Armv8.2-A
 ~~~~~~~~~
@@ -2581,7 +2600,16 @@ Armv8.5-A
 ~~~~~~~~~
 
 -  Branch Target Identification feature is selected by ``BRANCH_PROTECTION``
-   option set to 1. This option defaults to 0 and this is an experimental feature.
+   option set to 1. This option defaults to 0 and this is an experimental
+   feature.
+
+-  Memory Tagging Extension feature is unconditionally enabled for both worlds
+   (at EL0 and S-EL0) if it is only supported at EL0. If instead it is
+   implemented at all ELs, it is unconditionally enabled for only the normal
+   world. To enable it for the secure world as well, the build option
+   ``CTX_INCLUDE_MTE_REGS`` is required. If the hardware does not implement
+   MTE support at all, it is always disabled, no matter what build options
+   are used.
 
 Armv7-A
 ~~~~~~~
@@ -2597,7 +2625,7 @@ Cortex-A architecture through ``ARM_CORTEX_A<X> = yes`` in their
 Cortex-A15 target.
 
 Platform can also set ``ARM_WITH_NEON=yes`` to enable neon support.
-Note that using neon at runtime has constraints on non secure wolrd context.
+Note that using neon at runtime has constraints on non secure world context.
 TF-A does not yet provide VFP context management.
 
 Directive ``ARM_CORTEX_A<x>`` and ``ARM_WITH_NEON`` are used to set
@@ -2656,37 +2684,26 @@ linker scripts which have the extension ``.ld``.
 FDTs provide a description of the hardware platform and are used by the Linux
 kernel at boot time. These can be found in the ``fdts`` directory.
 
-References
-----------
+.. rubric:: References
+
+-  `Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D)`_
 
-.. [#] `Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D)`_
-.. [#] `Power State Coordination Interface PDD`_
-.. [#] `SMC Calling Convention PDD`_
-.. [#] `TF-A Interrupt Management Design guide`_.
+-  `Power State Coordination Interface PDD`_
+
+-  `SMC Calling Convention PDD`_
+
+-  :ref:`Interrupt Management Framework`
 
 --------------
 
 *Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
 
-.. _Reset Design: ./reset-design.rst
-.. _Porting Guide: ../getting_started/porting-guide.rst
-.. _Firmware Update: ../components/firmware-update.rst
-.. _PSCI PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
-.. _SMC calling convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
-.. _PSCI Library integration guide: ../getting_started/psci-lib-integration-guide.rst
+.. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
 .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
 .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
-.. _here: ../getting_started/psci-lib-integration-guide.rst
-.. _CPU specific build macros: ./cpu-specific-build-macros.rst
-.. _CPUBM: ./cpu-specific-build-macros.rst
 .. _Arm ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html
-.. _User Guide: ../getting_started/user-guide.rst
 .. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
-.. _TF-A Interrupt Management Design guide: ./interrupt-framework-design.rst
-.. _Translation tables design: ../components/xlat-tables-lib-v2-design.rst
-.. _Exception Handling Framework: ../components/exception-handling.rst
-.. _ROMLIB Design: ../components/romlib-design.rst
 .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a
 
 .. |Image 1| image:: ../resources/diagrams/rt-svc-descs-layout.png
diff --git a/docs/design/index.rst b/docs/design/index.rst
index a51a4eb47..e3b8f7429 100644
--- a/docs/design/index.rst
+++ b/docs/design/index.rst
@@ -6,6 +6,7 @@ System Design
    :caption: Contents
    :numbered:
 
+   alt-boot-flows
    auth-framework
    cpu-specific-build-macros
    firmware-design
@@ -13,3 +14,8 @@ System Design
    psci-pd-tree
    reset-design
    trusted-board-boot
+   trusted-board-boot-build
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/design/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst
index 4a864f9c8..d155cb356 100644
--- a/docs/design/interrupt-framework-design.rst
+++ b/docs/design/interrupt-framework-design.rst
@@ -177,10 +177,10 @@ uses this information to determine whether the IRQ or the FIQ bit should be
 programmed in ``SCR_EL3`` while applying the routing model for a type of
 interrupt. The platform provides this information through the
 ``plat_interrupt_type_to_line()`` API (described in the
-`Porting Guide`_). For example, on the FVP port when the platform uses an Arm GICv2
-interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal
-while Non-secure interrupts are signaled through the IRQ signal. This applies
-when execution is in either security state.
+:ref:`Porting Guide`). For example, on the FVP port when the platform uses an
+Arm GICv2 interrupt controller, Secure-EL1 interrupts are signaled through the
+FIQ signal while Non-secure interrupts are signaled through the IRQ signal.
+This applies when execution is in either security state.
 
 Effect of mapping of several interrupt types to one signal
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -255,7 +255,7 @@ is expected to be aware of the secure devices present in the system and their
 associated interrupt numbers. It should configure the interrupt controller to
 enable the secure interrupts, ensure that their priority is always higher than
 the non-secure interrupts and target them to the primary CPU. It should also
-export the interface described in the `Porting Guide`_ to enable
+export the interface described in the :ref:`Porting Guide` to enable
 handling of interrupts.
 
 In the remainder of this document, for the sake of simplicity a Arm GICv2 system
@@ -1013,7 +1013,6 @@ TSP by returning ``SMC_UNK`` error.
 
 *Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.*
 
-.. _Porting Guide: ../getting_started/porting-guide.rst
 .. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
 
 .. |Image 1| image:: ../resources/diagrams/sec-int-handling.png
diff --git a/docs/design/reset-design.rst b/docs/design/reset-design.rst
index ccd717a06..7b10c956c 100644
--- a/docs/design/reset-design.rst
+++ b/docs/design/reset-design.rst
@@ -6,9 +6,9 @@ resets in Trusted Firmware-A (TF-A). It also describes how the platform
 integrator can tailor this code to the system configuration to some extent,
 resulting in a simplified and more optimised boot flow.
 
-This document should be used in conjunction with the `Firmware Design`_, which
-provides greater implementation details around the reset code, specifically
-for the cold boot path.
+This document should be used in conjunction with the :ref:`Firmware Design`
+document which provides greater implementation details around the reset code,
+specifically for the cold boot path.
 
 General reset code flow
 -----------------------
@@ -109,11 +109,14 @@ images might be done by the Trusted Boot Firmware or by platform code in BL31.
 
 Although the Arm FVP platform does not support programming the reset base
 address dynamically at run-time, it is possible to set the initial value of the
-``RVBAR_EL3`` register at start-up. This feature is provided on the Base FVP only.
+``RVBAR_EL3`` register at start-up. This feature is provided on the Base FVP
+only.
+
 It allows the Arm FVP port to support the ``RESET_TO_BL31`` configuration, in
 which case the ``bl31.bin`` image must be loaded to its run address in Trusted
 SRAM and all CPU reset vectors be changed from the default ``0x0`` to this run
-address. See the `User Guide`_ for details of running the FVP models in this way.
+address. See the :ref:`Arm Fixed Virtual Platforms (FVP)` for details of running
+the FVP models in this way.
 
 Although technically it would be possible to program the reset base address with
 the right support in the SCP firmware, this is currently not implemented so the
@@ -150,10 +153,7 @@ This might be done by the Trusted Boot Firmware or by platform code in BL31.
 
 --------------
 
-*Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
-
-.. _Firmware Design: firmware-design.rst
-.. _User Guide: ../getting_started/user-guide.rst
+*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.*
 
 .. |Default reset code flow| image:: ../resources/diagrams/default_reset_code.png
 .. |Reset code flow with programmable reset address| image:: ../resources/diagrams/reset_code_no_boot_type_check.png
diff --git a/docs/design/trusted-board-boot-build.rst b/docs/design/trusted-board-boot-build.rst
new file mode 100644
index 000000000..202524316
--- /dev/null
+++ b/docs/design/trusted-board-boot-build.rst
@@ -0,0 +1,114 @@
+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. See the :ref:`Prerequisites` document for the appropriate
+   version of mbed TLS to use.
+
+   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.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
+.. _mbed TLS Security Center: https://tls.mbed.org/security
diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst
index 82be272bf..49e8adb98 100644
--- a/docs/design/trusted-board-boot.rst
+++ b/docs/design/trusted-board-boot.rst
@@ -8,8 +8,9 @@ Public-Key-Cryptography Standards (PKCS).
 
 This document describes the design of Trusted Firmware-A (TF-A) TBB, which is an
 implementation of the `Trusted Board Boot Requirements (TBBR)`_ specification,
-Arm DEN0006D. It should be used in conjunction with the `Firmware Update`_
-design document, which implements a specific aspect of the TBBR.
+Arm DEN0006D. It should be used in conjunction with the
+:ref:`Firmware Update (FWU)` design document, which implements a specific aspect
+of the TBBR.
 
 Chain of Trust
 --------------
@@ -186,7 +187,8 @@ The next step is executed for all the boot loader images.
 
 The Trusted Board Boot implementation spans both generic and platform-specific
 BL1 and BL2 code, and in tool code on the host build machine. The feature is
-enabled through use of specific build flags as described in the `User Guide`_.
+enabled through use of specific build flags as described in
+:ref:`Build Options`.
 
 On the host machine, a tool generates the certificates, which are included in
 the FIP along with the boot loader images. These certificates are loaded in
@@ -201,10 +203,11 @@ Authentication Framework
 
 The authentication framework included in TF-A provides support to implement
 the desired trusted boot sequence. Arm platforms use this framework to
-implement the boot requirements specified in the `TBBR-client`_ document.
+implement the boot requirements specified in the
+`Trusted Board Boot Requirements (TBBR)`_ document.
 
 More information about the authentication framework can be found in the
-`Auth Framework`_ document.
+:ref:`Authentication Framework & Chain of Trust` document.
 
 Certificate Generation Tool
 ---------------------------
@@ -219,17 +222,16 @@ passed as inputs to the ``fiptool`` utility for creating the FIP.
 The certificates are also stored individually in the in the output build
 directory.
 
-The tool resides in the ``tools/cert_create`` directory. It uses OpenSSL SSL
-library version 1.0.1 or later to generate the X.509 certificates. Instructions
-for building and using the tool can be found in the `User Guide`_.
+The tool resides in the ``tools/cert_create`` directory. It uses the OpenSSL SSL
+library version to generate the X.509 certificates. The specific version of the
+library that is required is given in the :ref:`Prerequisites` document.
+
+Instructions for building and using the tool can be found at
+:ref:`tools_build_cert_create`.
 
 --------------
 
 *Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.*
 
-.. _Firmware Update: ../components/firmware-update.rst
 .. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt
-.. _User Guide: ../getting_started/user-guide.rst
-.. _Auth Framework: auth-framework.rst
-.. _TBBR-client: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a
-.. _Trusted Board Boot Requirements (TBBR): `TBBR-client`_
+.. _Trusted Board Boot Requirements (TBBR): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a