15 files changed, 130 insertions, 77 deletions
diff --git a/docs/components/debugfs-design.rst b/docs/components/debugfs-design.rst
index 2096bdbb7..253651513 100644
--- a/docs/components/debugfs-design.rst
+++ b/docs/components/debugfs-design.rst
@@ -80,8 +80,8 @@ SMC interface
 The communication with the 9p layer in BL31 is made through an SMC conduit
 (`SMC Calling Convention`_), using a specific SiP Function Id. An NS
 shared buffer is used to pass path string parameters, or e.g. to exchange
-data on a read operation. Refer to `ARM SiP Services`_ for a description
-of the SMC interface.
+data on a read operation. Refer to :ref:`ARM SiP Services <arm sip services>`
+for a description of the SMC interface.
 
 Security considerations
 -----------------------
diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst
index 4c63a8b47..6f223c675 100644
--- a/docs/components/exception-handling.rst
+++ b/docs/components/exception-handling.rst
@@ -10,13 +10,9 @@ of the following exceptions when targeted at EL3:
 -  Asynchronous External Aborts
 
 |TF-A|'s handling of synchronous ``SMC`` exceptions raised from lower ELs is
-described in the `Firmware Design document`__. However, the |EHF| changes the
-semantics of `interrupt handling`__ and `synchronous exceptions`__ other than
-SMCs.
-
-.. __: firmware-design.rst#handling-an-smc
-.. __: `Interrupt handling`_
-.. __: `Effect on SMC calls`_
+described in the :ref:`Firmware Design document <handling-an-smc>`. However, the
+|EHF| changes the semantics of `Interrupt handling`_ and :ref:`synchronous
+exceptions <Effect on SMC calls>` other than SMCs.
 
 The |EHF| is selected by setting the build option ``EL3_EXCEPTION_HANDLING`` to
 ``1``, and is only available for AArch64 systems.
@@ -77,10 +73,9 @@ On any given system, all of the above handling models may be employed
 independently depending on platform choice and the nature of the exception
 received.
 
-.. [#spd] Not to be confused with `Secure Payload Dispatcher`__, which is an
-   EL3 component that operates in EL3 on behalf of Secure OS.
-
-.. __: firmware-design.rst#secure-el1-payloads-and-dispatchers
+.. [#spd] Not to be confused with :ref:`Secure Payload Dispatcher
+   <firmware_design_sel1_spd>`, which is an EL3 component that operates in EL3
+   on behalf of Secure OS.
 
 The role of Exception Handling Framework
 ----------------------------------------
@@ -139,6 +134,8 @@ unstacked in strictly the reverse order. For interrupts, the GIC ensures this is
 the case; for non-interrupts, the |EHF| monitors and asserts this. See
 `Transition of priority levels`_.
 
+.. _interrupt-handling:
+
 Interrupt handling
 ------------------
 
@@ -151,15 +148,12 @@ implications:
    sufficient priority are signalled as FIQs, and therefore will be routed to
    EL3. As a result, S-EL1 software cannot expect to handle Non-secure
    interrupts at S-EL1. Essentially, this deprecates the routing mode described
-   as `CSS=0, TEL3=0`__.
-
-   .. __: interrupt-framework-design.rst#el3-interrupts
+   as :ref:`CSS=0, TEL3=0 <EL3 interrupts>`.
 
    In order for S-EL1 software to handle Non-secure interrupts while having
    |EHF| enabled, the dispatcher must adopt a model where Non-secure interrupts
-   are received at EL3, but are then `synchronously`__ handled over to S-EL1.
-
-   .. __: interrupt-framework-design.rst#secure-payload
+   are received at EL3, but are then :ref:`synchronously <sp-synchronous-int>`
+   handled over to S-EL1.
 
 -  On GICv2 systems, it's required that the build option ``GICV2_G0_FOR_EL3`` is
    set to ``1`` so that *Group 0* interrupts target EL3.
@@ -239,12 +233,11 @@ The text in `Partitioning priority levels`_ only describes how the platform
 expresses the required levels of priority. It however doesn't choose interrupts
 nor program the required priority in GIC.
 
-The `Firmware Design guide`__ explains methods for configuring secure
-interrupts. |EHF| requires the platform to enumerate interrupt properties (as
-opposed to just numbers) of Secure interrupts. The priority of secure interrupts
-must match that as determined in the `Partitioning priority levels`_ section above.
-
-.. __: firmware-design.rst#configuring-secure-interrupts
+The :ref:`Firmware Design guide<configuring-secure-interrupts>` explains methods
+for configuring secure interrupts. |EHF| requires the platform to enumerate
+interrupt properties (as opposed to just numbers) of Secure interrupts. The
+priority of secure interrupts must match that as determined in the
+`Partitioning priority levels`_ section above.
 
 See `Limitations`_, and also refer to `Interrupt handling example`_ for
 illustration.
@@ -283,15 +276,13 @@ The interrupt handler should have the following signature:
    typedef int (*ehf_handler_t)(uint32_t intr_raw, uint32_t flags, void *handle,
                    void *cookie);
 
-The parameters are as obtained from the top-level `EL3 interrupt handler`__.
+The parameters are as obtained from the top-level :ref:`EL3 interrupt handler
+<el3-runtime-firmware>`.
 
-.. __: interrupt-framework-design.rst#el3-runtime-firmware
-
-The `SDEI dispatcher`__, for example, expects the platform to allocate two
-different priority levels—``PLAT_SDEI_CRITICAL_PRI``, and
-``PLAT_SDEI_NORMAL_PRI``—and registers the same handler to handle both levels.
-
-.. __: sdei.rst
+The :ref:`SDEI dispatcher<SDEI: Software Delegated Exception Interface>`, for
+example, expects the platform to allocate two different priority levels—
+``PLAT_SDEI_CRITICAL_PRI``, and ``PLAT_SDEI_NORMAL_PRI`` —and registers the
+same handler to handle both levels.
 
 Interrupt handling example
 --------------------------
@@ -374,11 +365,9 @@ Activating and Deactivating priorities
 
 A priority level is said to be *active* when an exception of that priority is
 being handled: for interrupts, this is implied when the interrupt is
-acknowledged; for non-interrupt exceptions, such as SErrors or `SDEI explicit
-dispatches`__, this has to be done via calling ``ehf_activate_priority()``. See
-`Run-time flow`_.
-
-.. __: sdei.rst#explicit-dispatch-of-events
+acknowledged; for non-interrupt exceptions, such as SErrors or :ref:`SDEI
+explicit dispatches <explicit-dispatch-of-events>`, this has to be done via
+calling ``ehf_activate_priority()``. See `Run-time flow`_.
 
 Conversely, when the dispatcher has reached a logical resolution for the cause
 of the exception, the corresponding priority level ought to be deactivated. As
@@ -457,6 +446,8 @@ calls to these APIs are subject to the following conditions:
 
 If these are violated, a panic will result.
 
+.. _Effect on SMC calls:
+
 Effect on SMC calls
 -------------------
 
@@ -542,10 +533,8 @@ The following is an example flow for interrupts:
    interrupts belonging to different dispatchers.
 
 #. The |EHF|, during its initialisation, registers a top-level interrupt handler
-   with the `Interrupt Management Framework`__ for EL3 interrupts. This also
-   results in setting the routing bits in ``SCR_EL3``.
-
-   .. __: interrupt-framework-design.rst#el3-runtime-firmware
+   with the :ref:`Interrupt Management Framework<el3-runtime-firmware>` for EL3
+   interrupts. This also results in setting the routing bits in ``SCR_EL3``.
 
 #. When an interrupt belonging to a dispatcher fires, GIC raises an EL3/Group 0
    interrupt, and is taken to EL3.
diff --git a/docs/components/platform-interrupt-controller-API.rst b/docs/components/platform-interrupt-controller-API.rst
index 9d02f45c0..069c87b84 100644
--- a/docs/components/platform-interrupt-controller-API.rst
+++ b/docs/components/platform-interrupt-controller-API.rst
@@ -286,6 +286,8 @@ inserts to order memory updates before updating mask, then writes to the GIC
 *Priority Mask Register*, and make sure memory updates are visible before
 potential trigger due to mask update.
 
+.. _plat_ic_get_interrupt_id:
+
 Function: unsigned int plat_ic_get_interrupt_id(unsigned int raw); [optional]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst
index c5275a0b7..60259c830 100644
--- a/docs/components/sdei.rst
+++ b/docs/components/sdei.rst
@@ -205,6 +205,8 @@ will only allow SDEI calls to be made from:
 
 See the function ``sdei_client_el()`` in ``sdei_private.h``.
 
+.. _explicit-dispatch-of-events:
+
 Explicit dispatch of events
 ---------------------------
 
diff --git a/docs/components/secure-partition-manager-mm.rst b/docs/components/secure-partition-manager-mm.rst
index 87fc91df3..d53290102 100644
--- a/docs/components/secure-partition-manager-mm.rst
+++ b/docs/components/secure-partition-manager-mm.rst
@@ -6,11 +6,9 @@ Foreword
 
 Two implementations of a Secure Partition Manager co-exist in the TF-A codebase:
 
--  SPM based on the PSA FF-A specification (`Secure Partition Manager`__).
+-  SPM based on the PSA FF-A specification (:ref:`Secure Partition Manager`).
 -  SPM based on the MM interface.
 
-.. __: secure-partition-manager.html
-
 Both implementations differ in their architectures and only one can be selected
 at build time.
 
diff --git a/docs/components/secure-partition-manager.rst b/docs/components/secure-partition-manager.rst
index 2169f30a0..c58cd0801 100644
--- a/docs/components/secure-partition-manager.rst
+++ b/docs/components/secure-partition-manager.rst
@@ -126,7 +126,7 @@ The following TF-A build options are provisioned:
    restoring) the EL2 system register context before entering (resp.
    after leaving) the SPMC. It is mandatory when ``SPMD_SPM_AT_SEL2`` is
    enabled. The context save/restore routine and exhaustive list of
-   registers is visible at `[4] <#References>`__.
+   registers is visible at `[4]`_.
 -  **SP_LAYOUT_FILE**: this option provides a text description file
    providing paths to SP binary images and DTS format manifests
    (see `Specifying partition binary image and DT`_). It
@@ -833,9 +833,7 @@ References
 
 .. _[2]:
 
-[2] `Secure Partition Manager using MM interface`__
-
-.. __: secure-partition-manager-mm.html
+[2] :ref:`Secure Partition Manager using MM interface<Secure Partition Manager (MM)>`
 
 .. _[3]:
 
diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst
index ae6dd469d..a357d5858 100644
--- a/docs/design/firmware-design.rst
+++ b/docs/design/firmware-design.rst
@@ -957,6 +957,8 @@ Function ID call type and OEN onto a specific service handler in the
 
 |Image 1|
 
+.. _handling-an-smc:
+
 Handling an SMC
 ~~~~~~~~~~~~~~~
 
@@ -1300,6 +1302,8 @@ In other words, the reset handler should be able to detect whether an action has
 already been performed and act as appropriate. Possible courses of actions are,
 e.g. skip the action the second time, or undo/redo it.
 
+.. _configuring-secure-interrupts:
+
 Configuring secure interrupts
 -----------------------------
 
diff --git a/docs/design/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst
index 2e200aa3f..dfb2eac8e 100644
--- a/docs/design/interrupt-framework-design.rst
+++ b/docs/design/interrupt-framework-design.rst
@@ -150,10 +150,8 @@ EL3 interrupts
 
    However, when ``EL3_EXCEPTION_HANDLING`` is ``1``, this routing model is
    invalid as EL3 interrupts are unconditionally routed to EL3, and EL3
-   interrupts will always preempt Secure EL1/EL0 execution. See `exception
-   handling`__ documentation.
-
-   .. __: exception-handling.rst#interrupt-handling
+   interrupts will always preempt Secure EL1/EL0 execution. See :ref:`exception
+   handling<interrupt-handling>` documentation.
 
 #. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in
    Secure-EL1/Secure-EL0. This is a valid routing model as secure software
@@ -303,6 +301,8 @@ This section describes in detail the role of each software component (see
 `Software components`_) during the registration of a handler for an interrupt
 type.
 
+.. _el3-runtime-firmware:
+
 EL3 runtime firmware
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -901,14 +901,14 @@ it is generated during execution in the TSP with ``PSTATE.I`` = 0 when the
 
 |Image 2|
 
-Secure payload
-~~~~~~~~~~~~~~
+.. _sp-synchronous-int:
+
+Secure payload interrupt handling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The SP should implement one or both of the synchronous and asynchronous
 interrupt handling models depending upon the interrupt routing model it has
-chosen (as described in section `Secure Payload`__).
-
-.. __: #sp-int-registration
+chosen (as described in section :ref:`Secure Payload <sp-int-registration>`).
 
 In the synchronous model, it should begin handling a Secure-EL1 interrupt after
 receiving control from the SPD service at an entrypoint agreed upon during build
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index bfc50dfe7..0acc8867b 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -119,6 +119,8 @@ Common build options
 -  ``BUILD_STRING``: Input string for VERSION_STRING, which allows the TF-A
    build to be uniquely identified. Defaults to the current git commit id.
 
+-  ``BUILD_BASE``: Output directory for the build. Defaults to ``./build``
+
 -  ``CFLAGS``: Extra user options appended on the compiler's command line in
    addition to the options set by the build system.
 
@@ -346,16 +348,14 @@ Common build options
 -  ``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`__.
+   by :ref:`platform abstraction layer<platform Interrupt Controller API>` and
+   :ref:`Interrupt Management Framework<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
@@ -721,6 +721,10 @@ Common build options
   bit, to trap access to the RAS ERR and RAS ERX registers from lower ELs.
   This flag is disabled by default.
 
+- ``OPENSSL_DIR``: This flag is used to provide the installed openssl directory
+  path on the host machine which is used to build certificate generation and
+  firmware encryption tool.
+
 GICv3 driver options
 --------------------
 
diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 7aaeae2f4..6b8bbc634 100644
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -2482,9 +2482,7 @@ FVP can be configured to use either GICv2 or GICv3 depending on the build flag
 ``FVP_USE_GIC_DRIVER`` (See :ref:`build_options_arm_fvp_platform` for more
 details).
 
-See also: `Interrupt Controller Abstraction APIs`__.
-
-.. __: ../design/platform-interrupt-controller-API.rst
+See also: :ref:`Interrupt Controller Abstraction APIs<Platform Interrupt Controller API>`.
 
 Function : plat_interrupt_type_to_line() [mandatory]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2609,9 +2607,7 @@ This API is used by the CPU to indicate to the platform IC that processing of
 the highest pending interrupt has begun. It should return the raw, unmodified
 value obtained from the interrupt controller when acknowledging an interrupt.
 The actual interrupt number shall be extracted from this raw value using the API
-`plat_ic_get_interrupt_id()`__.
-
-.. __: ../design/platform-interrupt-controller-API.rst#function-unsigned-int-plat-ic-get-interrupt-id-unsigned-int-raw-optional
+`plat_ic_get_interrupt_id()<plat_ic_get_interrupt_id>`.
 
 This function in Arm standard platforms using GICv2, reads the *Interrupt
 Acknowledge Register* (``GICC_IAR``). This changes the state of the highest
diff --git a/docs/plat/arm/arm-build-options.rst b/docs/plat/arm/arm-build-options.rst
index 9622de65d..2e50068f6 100644
--- a/docs/plat/arm/arm-build-options.rst
+++ b/docs/plat/arm/arm-build-options.rst
@@ -91,6 +91,9 @@ Arm Platform Build Options
    platforms. If this option is specified, then the path to the CryptoCell
    SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag.
 
+-  ``ARM_SPMC_MANIFEST_DTS`` : path to an alternate manifest file used as the
+   SPMC Core manifest. Valid when ``SPD=spmd`` is selected.
+
 For a better understanding of these options, the Arm development platform memory
 map is explained in the :ref:`Firmware Design`.
 
diff --git a/docs/plat/arm/fvp/index.rst b/docs/plat/arm/fvp/index.rst
index fd658bbff..745e31f9e 100644
--- a/docs/plat/arm/fvp/index.rst
+++ b/docs/plat/arm/fvp/index.rst
@@ -635,7 +635,7 @@ boot Linux with 4 CPUs using the AArch32 build of TF-A.
 
 *Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
 
-.. _TB_FW_CONFIG for FVP: ../plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts
+.. _TB_FW_CONFIG for FVP: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts
 .. _Arm's website: `FVP models`_
 .. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
 .. _Linaro Release 19.06: http://releases.linaro.org/members/arm/platforms/19.06
diff --git a/docs/plat/index.rst b/docs/plat/index.rst
index 7969003c9..6a38113fc 100644
--- a/docs/plat/index.rst
+++ b/docs/plat/index.rst
@@ -19,6 +19,7 @@ Platform Ports
    intel-stratix10
    marvell/index
    mt8183
+   mt8192
    nvidia-tegra
    warp7
    imx8
diff --git a/docs/plat/mt8192.rst b/docs/plat/mt8192.rst
new file mode 100644
index 000000000..369afcfb7
--- /dev/null
+++ b/docs/plat/mt8192.rst
@@ -0,0 +1,21 @@
+MediaTek 8192
+=============
+
+MediaTek 8192 (MT8192) is a 64-bit ARM SoC introduced by MediaTek in 2020.
+The chip incorporates eight cores - four Cortex-A55 little cores and Cortex-A76.
+Cortex-A76 can operate at up to 2.2 GHz.
+Cortex-A55 can operate at up to 2 GHz.
+
+Boot Sequence
+-------------
+
+::
+
+    Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel
+
+How to Build
+------------
+
+.. code:: shell
+
+    make CROSS_COMPILE=aarch64-linux-gnu- PLAT=mt8192 DEBUG=1 COREBOOT=1
diff --git a/docs/plat/qemu.rst b/docs/plat/qemu.rst
index afa32c11b..66b82473c 100644
--- a/docs/plat/qemu.rst
+++ b/docs/plat/qemu.rst
@@ -20,11 +20,46 @@ provided as it's generated by QEMU.
 Current limitations:
 
 -  Only cold boot is supported
--  No build instructions for QEMU\_EFI.fd and rootfs-arm64.cpio.gz
 
-``QEMU_EFI.fd`` can be dowloaded from
+Getting non-TF images
+---------------------
+
+``QEMU_EFI.fd`` can be downloaded from
 http://snapshots.linaro.org/components/kernel/leg-virt-tianocore-edk2-upstream/latest/QEMU-KERNEL-AARCH64/RELEASE_GCC5/QEMU_EFI.fd
 
+or, can be built as follows:
+
+.. code:: shell
+
+    git clone https://github.com/tianocore/edk2.git
+    cd edk2
+    git submodule update --init
+    make -C BaseTools
+    source edksetup.sh
+    export GCC5_AARCH64_PREFIX=aarch64-linux-gnu-
+    build -a AARCH64 -t GCC5 -p ArmVirtPkg/ArmVirtQemuKernel.dsc
+
+````
+
+Then, you will get ``Build/ArmVirtQemuKernel-AARCH64/DEBUG_GCC5/FV/QEMU_EFI.fd``
+
+Please note you do not need to use GCC 5 in spite of the environment variable
+``GCC5_AARCH64_PREFIX``
+
+The rootfs can be built by using Buildroot as follows:
+
+.. code:: shell
+
+    git clone git://git.buildroot.net/buildroot.git
+    cd buildroot
+    make qemu_aarch64_virt_defconfig
+    utils/config -e BR2_TARGET_ROOTFS_CPIO
+    utils/config -e BR2_TARGET_ROOTFS_CPIO_GZIP
+    make olddefconfig
+    make
+
+Then, you will get ``output/images/rootfs.cpio.gz``.
+
 Booting via semi-hosting option
 -------------------------------
 
@@ -43,14 +78,14 @@ To build:
 
     make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu
 
-To start (QEMU v4.1.0):
+To start (QEMU v5.0.0):
 
 .. code:: shell
 
     qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57  \
         -kernel Image                           \
-        -append "console=ttyAMA0,38400 keep_bootcon root=/dev/vda2"   \
-        -initrd rootfs-arm64.cpio.gz -smp 2 -m 1024 -bios bl1.bin   \
+        -append "console=ttyAMA0,38400 keep_bootcon"   \
+        -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios bl1.bin   \
         -d unimp -semihosting-config enable,target=native
 
 Booting via flash based firmwares
@@ -92,12 +127,12 @@ To build flash.bin:
     dd if=build/qemu/release/bl1.bin of=flash.bin bs=4096 conv=notrunc
     dd if=build/qemu/release/fip.bin of=flash.bin seek=64 bs=4096 conv=notrunc
 
-To start (QEMU v2.6.0):
+To start (QEMU v5.0.0):
 
 .. code:: shell
 
     qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57  \
         -kernel Image -no-acpi                     \
-        -append 'console=ttyAMA0,38400 keep_bootcon root=/dev/vda2'  \
-        -initrd rootfs-arm64.cpio.gz -smp 2 -m 1024 -bios flash.bin   \
+        -append 'console=ttyAMA0,38400 keep_bootcon'  \
+        -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios flash.bin   \
         -d unimp