doc: Convert internal links to RST format

Currently links between documents are using the format:

<path/to/><filename>.rst

This was required for services like GitHub because they render each
document in isolation - linking to another document is like linking
to any other file, just provide the full path.

However, with the new approach, the .rst files are only the raw
source for the documents. Once the documents have been rendered
the output is now in another format (HTML in our case) and so,
when linking to another document, the link must point to the
rendered version and not the .rst file.

The RST spec provides a few methods for linking between content.
The parent of this patch enabled the automatic creation of anchors
for document titles - we will use these anchors as the targets for
our links. Additional anchors can be added by hand if needed, on
section and sub-section titles, for example.

An example of this new format, for a document with the title
"Firmware Design" is :ref:`Firmware Design`.

One big advantage of this is that anchors are not dependent on
paths. We can then move documents around, even between directories,
without breaking any links between documents. Links will need to be
updated only if the title of a document changes.

Change-Id: I9e2340a61dd424cbd8fd1ecc2dc166f460d81703
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

4 files changed, 91 insertions, 115 deletions

diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 9eb7c17e..d7157690 100644
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -13,20 +13,20 @@ Modifications consist of:
 -  Defining certain constants (for example #defines).
 
 The platform-specific functions and variables are declared in
-`include/plat/common/platform.h`_. The firmware provides a default implementation
-of variables and functions to fulfill the optional requirements. These
-implementations are all weakly defined; they are provided to ease the porting
-effort. Each platform port can override them with its own implementation if the
-default implementation is inadequate.
+``include/plat/common/platform.h``. The firmware provides a default
+implementation of variables and functions to fulfill the optional requirements.
+These implementations are all weakly defined; they are provided to ease the
+porting effort. Each platform port can override them with its own implementation
+if the default implementation is inadequate.
 
 Some modifications are common to all Boot Loader (BL) stages. Section 2
 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 `User Guide`_.
+This document should be read in conjunction with the TF-A :ref:`User Guide`.
 
-Please refer to the `Platform compatibility policy`_ for the policy regarding
-compatibility and deprecation of these porting interfaces.
+Please refer to the :ref:`Platform Compatibility Policy` for the policy
+regarding compatibility and deprecation of these porting interfaces.
 
 Only Arm development platforms (such as FVP and Juno) may use the
 functions/definitions in ``include/plat/arm/common/`` and the corresponding
@@ -98,7 +98,7 @@ Each platform must ensure that a header file of this name is in the system
 include path with the following constants defined. This will require updating
 the list of ``PLAT_INCLUDES`` in the ``platform.mk`` file.
 
-Platform ports may optionally use the file `include/plat/common/common_def.h`_,
+Platform ports may optionally use the file ``include/plat/common/common_def.h``,
 which provides typical values for some of the constants below. These values are
 likely to be suitable for all platform ports.
 
@@ -115,8 +115,8 @@ likely to be suitable for all platform ports.
 -  **#define : PLATFORM_STACK_SIZE**
 
    Defines the normal stack memory available to each CPU. This constant is used
-   by `plat/common/aarch64/platform_mp_stack.S`_ and
-   `plat/common/aarch64/platform_up_stack.S`_.
+   by ``plat/common/aarch64/platform_mp_stack.S`` and
+   ``plat/common/aarch64/platform_up_stack.S``.
 
 -  **define : CACHE_WRITEBACK_GRANULE**
 
@@ -542,7 +542,7 @@ optionally be defined:
    Maximum number of partition entries required by the platform. This allows
    control how much memory is allocated for partition entries. The default
    value is 128.
-   `For example, define the build flag in platform.mk`_:
+   For example, define the build flag in ``platform.mk``:
    PLAT_PARTITION_MAX_ENTRIES := 12
    $(eval $(call add_define,PLAT_PARTITION_MAX_ENTRIES))
 
@@ -828,7 +828,8 @@ runtime environment. This function can clobber x0 - x8 and must preserve
 x9 - x29.
 
 This function plays a crucial role in the power domain topology framework in
-PSCI and details of this can be found in `Power Domain Topology Design`_.
+PSCI and details of this can be found in
+:ref:`PSCI Power Domain Tree Structure`.
 
 Function : plat_core_pos_by_mpidr()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -844,7 +845,7 @@ case the ``MPIDR`` is invalid, this function returns -1. This function will only
 be invoked by BL31 after the power domain topology is initialized and can
 utilize the C runtime environment. For further details about how TF-A
 represents the power domain topology and how this relates to the linear CPU
-index, please refer `Power Domain Topology Design`_.
+index, please refer :ref:`PSCI Power Domain Tree Structure`.
 
 Function : plat_get_mbedtls_heap() [when TRUSTED_BOARD_BOOT == 1]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -895,8 +896,8 @@ of the stack allocated to each CPU is specified by the platform defined
 constant ``PLATFORM_STACK_SIZE``.
 
 Common implementations of this function for the UP and MP BL images are
-provided in `plat/common/aarch64/platform_up_stack.S`_ and
-`plat/common/aarch64/platform_mp_stack.S`_
+provided in ``plat/common/aarch64/platform_up_stack.S`` and
+``plat/common/aarch64/platform_mp_stack.S``
 
 Function : plat_get_my_stack()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -913,8 +914,8 @@ of the stack allocated to each CPU is specified by the platform defined
 constant ``PLATFORM_STACK_SIZE``.
 
 Common implementations of this function for the UP and MP BL images are
-provided in `plat/common/aarch64/platform_up_stack.S`_ and
-`plat/common/aarch64/platform_mp_stack.S`_
+provided in ``plat/common/aarch64/platform_up_stack.S`` and
+``plat/common/aarch64/platform_mp_stack.S``
 
 Function : plat_report_exception()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -937,12 +938,12 @@ about the way the platform displays its status information.
 
 For AArch64, this function receives the exception type as its argument.
 Possible values for exceptions types are listed in the
-`include/common/bl_common.h`_ header file. Note that these constants are not
+``include/common/bl_common.h`` header file. Note that these constants are not
 related to any architectural exception code; they are just a TF-A convention.
 
 For AArch32, this function receives the exception mode as its argument.
 Possible values for exception modes are listed in the
-`include/lib/aarch32/arch.h`_ header file.
+``include/lib/aarch32/arch.h`` header file.
 
 Function : plat_reset_handler()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -958,7 +959,7 @@ specific errata workarounds could also be implemented here. The API should
 preserve the values of callee saved registers x19 to x29.
 
 The default implementation doesn't do anything. If a platform needs to override
-the default implementation, refer to the `Firmware Design`_ for general
+the default implementation, refer to the :ref:`Firmware Design` for general
 guidelines.
 
 Function : plat_disable_acp()
@@ -1475,8 +1476,8 @@ Boot Loader Stage 2 (BL2) at EL3
 
 When the platform has a non-TF-A Boot ROM it is desirable to jump
 directly to BL2 instead of TF-A BL1. In this case BL2 is expected to
-execute at EL3 instead of executing at EL1. Refer to the `Firmware
-Design`_ for more information.
+execute at EL3 instead of executing at EL1. Refer to the :ref:`Firmware Design`
+document for more information.
 
 All mandatory functions of BL2 must be implemented, except the functions
 bl2_early_platform_setup and bl2_el3_plat_arch_setup, because
@@ -1852,6 +1853,8 @@ calculated by the linker then a link time assertion is raised. A compile time
 assertion is raised if the value of the constant is not aligned to the cache
 line boundary.
 
+.. _porting_guide_sdei_requirements:
+
 SDEI porting requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1936,7 +1939,7 @@ example, a CPU) is at level 0. If the *power domain* node above a CPU is a
 logical grouping of CPUs that share some state, then level 1 is that group of
 CPUs (for example, a cluster), and level 2 is a group of clusters (for
 example, the system). More details on the power domain topology and its
-organization can be found in `Power Domain Topology Design`_.
+organization can be found in :ref:`PSCI Power Domain Tree Structure`.
 
 BL31's platform initialization code exports a pointer to the platform-specific
 power management operations required for the PSCI implementation to function
@@ -2048,13 +2051,13 @@ Function : plat_get_power_domain_tree_desc() [mandatory]
 
 This function returns a pointer to the byte array containing the power domain
 topology tree description. The format and method to construct this array are
-described in `Power Domain Topology Design`_. The BL31 PSCI initialization code
-requires this array to be described by the platform, either statically or
-dynamically, to initialize the power domain topology tree. In case the array
-is populated dynamically, then plat_core_pos_by_mpidr() and
-plat_my_core_pos() should also be implemented suitably so that the topology
-tree description matches the CPU indices returned by these APIs. These APIs
-together form the platform interface for the PSCI topology framework.
+described in :ref:`PSCI Power Domain Tree Structure`. The BL31 PSCI
+initialization code requires this array to be described by the platform, either
+statically or dynamically, to initialize the power domain topology tree. In case
+the array is populated dynamically, then plat_core_pos_by_mpidr() and
+plat_my_core_pos() should also be implemented suitably so that the topology tree
+description matches the CPU indices returned by these APIs. These APIs together
+form the platform interface for the PSCI topology framework.
 
 Function : plat_setup_psci_ops() [mandatory]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2076,10 +2079,10 @@ pointer with a pointer to BL31's private ``plat_psci_ops`` structure.
 
 A description of each member of this structure is given below. Please refer to
 the Arm FVP specific implementation of these handlers in
-`plat/arm/board/fvp/fvp_pm.c`_ as an example. For each PSCI function that the
+``plat/arm/board/fvp/fvp_pm.c`` as an example. For each PSCI function that the
 platform wants to support, the associated operation or operations in this
 structure must be provided and implemented (Refer section 4 of
-`Firmware Design`_ for the PSCI API supported in TF-A). To disable a PSCI
+:ref:`Firmware Design` for the PSCI API supported in TF-A). To disable a PSCI
 function in a platform port, the operation should be removed from this
 structure instead of providing an empty implementation.
 
@@ -2367,13 +2370,15 @@ region defined by a base address ``base`` and with a size of ``length``
 bytes is protected by ``MEM_PROTECT``.  If the region is protected
 then it must return 0, otherwise it must return a negative number.
 
+.. _porting_guide_imf_in_bl31:
+
 Interrupt Management framework (in BL31)
 ----------------------------------------
 
 BL31 implements an Interrupt Management Framework (IMF) to manage interrupts
 generated in either security state and targeted to EL1 or EL2 in the non-secure
 state or EL3/S-EL1 in the secure state. The design of this framework is
-described in the `IMF Design Guide`_
+described in the :ref:`Interrupt Management Framework`
 
 A platform should export the following APIs to support the IMF. The following
 text briefly describes each API and its implementation in Arm standard
@@ -2383,7 +2388,7 @@ present in the platform. Arm standard platform layer supports both
 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
-`User Guide`_ for more details).
+:ref:`User Guide` for more details).
 
 See also: `Interrupt Controller Abstraction APIs`__.
 
@@ -2405,10 +2410,10 @@ the platform IC uses to signal each type of interrupt supported by the framework
 from a given security state. This API must be invoked at EL3.
 
 The first parameter will be one of the ``INTR_TYPE_*`` values (see
-`IMF Design Guide`_) indicating the target type of the interrupt, the second parameter is the
-security state of the originating execution context. The return result is the
-bit position in the ``SCR_EL3`` register of the respective interrupt trap: IRQ=1,
-FIQ=2.
+:ref:`Interrupt Management Framework`) indicating the target type of the
+interrupt, the second parameter is the security state of the originating
+execution context. The return result is the bit position in the ``SCR_EL3``
+register of the respective interrupt trap: IRQ=1, FIQ=2.
 
 In the case of Arm standard platforms using GICv2, S-EL1 interrupts are
 configured as FIQs and Non-secure interrupts as IRQs from either security
@@ -2792,7 +2797,7 @@ storage access is only required by BL1 and BL2 phases and performed inside the
 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 `User Guide`_). The storage layer is described in the header file
+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
 ``drivers/io/``.
@@ -2843,22 +2848,7 @@ amount of open resources per driver.
 
 *Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.*
 
-.. _include/plat/common/platform.h: ../include/plat/common/platform.h
-.. _include/plat/arm/common/plat_arm.h: ../include/plat/arm/common/plat_arm.h%5D
-.. _User Guide: user-guide.rst
-.. _include/plat/common/common_def.h: ../include/plat/common/common_def.h
-.. _include/plat/arm/common/arm_def.h: ../include/plat/arm/common/arm_def.h
-.. _plat/common/aarch64/platform_mp_stack.S: ../plat/common/aarch64/platform_mp_stack.S
-.. _plat/common/aarch64/platform_up_stack.S: ../plat/common/aarch64/platform_up_stack.S
-.. _For example, define the build flag in platform.mk: PLAT_PL061_MAX_GPIOS%20:=%20160
-.. _Power Domain Topology Design: ../design/psci-pd-tree.rst
-.. _include/common/bl_common.h: ../include/common/bl_common.h
-.. _include/lib/aarch32/arch.h: ../include/lib/aarch32/arch.h
-.. _Firmware Design: ../design/firmware-design.rst
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _plat/arm/board/fvp/fvp_pm.c: ../plat/arm/board/fvp/fvp_pm.c
-.. _Platform compatibility policy: ../process/platform-compatibility-policy.rst
-.. _IMF Design Guide: ../design/interrupt-framework-design.rst
 .. _Arm Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html
 .. _3.0 (GICv3): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html
 .. _FreeBSD: https://www.freebsd.org
diff --git a/docs/getting_started/psci-lib-integration-guide.rst b/docs/getting_started/psci-lib-integration-guide.rst
index 25936d90..1351fff0 100644
--- a/docs/getting_started/psci-lib-integration-guide.rst
+++ b/docs/getting_started/psci-lib-integration-guide.rst
@@ -437,13 +437,13 @@ The mandatory platform macros are:
 -  PLAT_MAX_PWR_LVL_STATES (optional)
 -  PLAT_PCPU_DATA_SIZE (optional)
 
-The details of these APIs/macros can be found in `Porting Guide`_.
+The details of these APIs/macros can be found in the :ref:`Porting Guide`.
 
 All platform specific operations for power management are done via
 ``plat_psci_ops_t`` callbacks registered by the platform when
 ``plat_setup_psci_ops()`` API is called. The description of each of
 the callbacks in ``plat_psci_ops_t`` can be found in PSCI section of the
-`Porting Guide`_. If any these callbacks are not registered, then the
+:ref:`Porting Guide`. If any these callbacks are not registered, then the
 PSCI API associated with that callback will not be supported by PSCI
 library.
 
@@ -524,12 +524,12 @@ CPU operations
 ~~~~~~~~~~~~~~
 
 The CPU operations (cpu_ops) framework implement power down sequence specific
-to the CPU and the details of which can be found in the
-``CPU specific operations framework`` section of `Firmware Design`_. The TF-A
-tree implements the ``cpu_ops`` for various supported CPUs and the EL3 Runtime
-Software needs to include the required ``cpu_ops`` in its build. The start and
-end of the ``cpu_ops`` descriptors must be exported by the EL3 Runtime Software
-via the ``__CPU_OPS_START__`` and ``__CPU_OPS_END__`` linker symbols.
+to the CPU and the details of which can be found at
+:ref:`firmware_design_cpu_ops_fwk`. The TF-A tree implements the ``cpu_ops``
+for various supported CPUs and the EL3 Runtime Software needs to include the
+required ``cpu_ops`` in its build. The start and end of the ``cpu_ops``
+descriptors must be exported by the EL3 Runtime Software via the
+``__CPU_OPS_START__`` and ``__CPU_OPS_END__`` linker symbols.
 
 The ``cpu_ops`` descriptors also include reset sequences and may include errata
 workarounds for the CPU. The EL3 Runtime Software can choose to call this
@@ -538,11 +538,9 @@ workarounds.
 
 --------------
 
-*Copyright (c) 2016-2018, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2016-2019, Arm Limited and Contributors. All rights reserved.*
 
 .. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
 .. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf
 .. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
 .. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _Porting Guide: ./porting-guide.rst
-.. _Firmware Design: ../design/firmware-design.rst
diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst
index 6c17a1fb..6a06025e 100644
--- a/docs/getting_started/rt-svc-writers-guide.rst
+++ b/docs/getting_started/rt-svc-writers-guide.rst
@@ -21,8 +21,8 @@ independent implementation of services for each group, which are then compiled
 into the BL31 image. This simplifies the integration of common software from
 Arm to support `PSCI`_, Secure Monitor for a Trusted OS and SoC specific
 software. The common runtime services framework ensures that SMC Functions are
-dispatched to their respective service implementation - the `Firmware Design`_
-provides details of how this is achieved.
+dispatched to their respective service implementation - the
+:ref:`Firmware Design` document provides details of how this is achieved.
 
 The interface and operation of the runtime services depends heavily on the
 concepts and definitions described in the `SMCCC`_, in particular SMC Function
@@ -79,11 +79,11 @@ handler will be responsible for all SMC Functions within a given service type.
 Getting started
 ---------------
 
-TF-A has a `services`_ directory in the source tree under which
+TF-A has a ``services`` directory in the source tree under which
 each owning entity can place the implementation of its runtime service. The
-`PSCI`_ implementation is located here in the `lib/psci`_ directory.
+`PSCI`_ implementation is located here in the ``lib/psci`` directory.
 
-Runtime service sources will need to include the `runtime_svc.h`_ header file.
+Runtime service sources will need to include the ``runtime_svc.h`` header file.
 
 Registering a runtime service
 -----------------------------
@@ -100,7 +100,7 @@ initialization and call handler functions.
    is also used for diagnostic purposes
 
 -  ``_start`` and ``_end`` values must be based on the ``OEN_*`` values defined in
-   `smccc.h`_
+   ``smccc.h``
 
 -  ``_type`` must be one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD``
 
@@ -132,7 +132,7 @@ to ensure that the following conditions are met:
 #. The ``_type`` is one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD``
 #. ``_setup`` and ``_smch`` routines have been specified
 
-`std_svc_setup.c`_ provides an example of registering a runtime service:
+``std_svc_setup.c`` provides an example of registering a runtime service:
 
 .. code:: c
 
@@ -296,13 +296,7 @@ provide this information....
 
 --------------
 
-*Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.*
 
 .. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
-.. _Firmware Design: ../design/firmware-design.rst
-.. _services: ../../services
-.. _lib/psci: ../../lib/psci
-.. _runtime_svc.h: ../../include/common/runtime_svc.h
-.. _smccc.h: ../../include/lib/smccc.h
-.. _std_svc_setup.c: ../../services/std_svc/std_svc_setup.c
diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst
index e540fd06..c7359ada 100644
--- a/docs/getting_started/user-guide.rst
+++ b/docs/getting_started/user-guide.rst
@@ -22,7 +22,7 @@ the different software components required to boot a Linux system:
 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 `Firmware Design`_.
+This document should be used in conjunction with the :ref:`Firmware Design`.
 
 Host machine requirements
 -------------------------
@@ -86,8 +86,8 @@ 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 `Trusted Firmware-A
-Coding Guidelines`_ document.
+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
@@ -196,7 +196,7 @@ Building TF-A
       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
-      `here`_.
+      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
@@ -262,11 +262,11 @@ Common build options
 -  ``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
-   `Firmware Design`_.
+   :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 `Firmware Design`_.
+   *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
@@ -479,7 +479,7 @@ Common build options
    is AArch32.
 
 -  ``ENABLE_SPM`` : Boolean option to enable the Secure Partition Manager (SPM).
-   Refer to the `Secure Partition Manager Design guide`_ for more details about
+   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
@@ -527,7 +527,7 @@ Common build options
 
 -  ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create``
    tool to create certificates as per the Chain of Trust described in
-   `Trusted Board Boot`_. The build system then calls ``fiptool`` to
+   :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
@@ -745,8 +745,8 @@ Common build options
 -  ``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 `Firmware Design`_. This flag is disabled by default and
-   affects all BL images.
+   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
@@ -784,7 +784,7 @@ Common build options
 
 -  ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or
    synchronous, (see "Initializing a BL32 Image" section in
-   `Firmware Design`_). It can take the value 0 (BL32 is initialized using
+   :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.
 
@@ -808,14 +808,14 @@ Common build options
 
 -  ``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 `Firmware Design`_). It can take the value 1
+   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 `Library at ROM`_ for further details. Default
-   is 0.
+   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.
@@ -924,7 +924,7 @@ Arm development platform specific build options
    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 `Firmware Design`_.
+map is explained in the :ref:`Firmware Design`.
 
 Arm CSS platform specific build options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -978,14 +978,14 @@ Arm FVP platform specific build options
    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 `Firmware Design`_ for
+   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 `Firmware Design`_ for details on HW_CONFIG. This option is
+   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.
@@ -1017,7 +1017,7 @@ 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 `Firmware Design`_).
+   platforms** section in the :ref:`Firmware Design`).
 
 Extra debug options can be passed to the build system by setting ``CFLAGS`` or
 ``LDFLAGS``:
@@ -1058,7 +1058,8 @@ 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
-`Secure-EL1 Payloads and Dispatchers`_ section in the `Firmware Design`_.
+: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:
@@ -1176,15 +1177,15 @@ 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 `Firmware Design`_ document.
+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 `Trusted Board Boot`_, and
--  Firmware Update, described in `Firmware Update`_
+-  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:
@@ -1250,9 +1251,9 @@ images with support for these features:
    in the output build directory.
 
 #. The optional FWU_FIP contains any additional images to be loaded from
-   Non-Volatile storage during the `Firmware Update`_ 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:
+   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.
@@ -1731,6 +1732,8 @@ 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
 ---------------------------
 
@@ -1903,7 +1906,7 @@ 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`_.
+   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
@@ -2204,18 +2207,9 @@ wakeup interrupt from RTC.
 .. _`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
-.. _here: psci-lib-integration-guide.rst
-.. _Trusted Board Boot: ../design/trusted-board-boot.rst
-.. _TB_FW_CONFIG for FVP: ../../plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts
-.. _Secure-EL1 Payloads and Dispatchers: ../design/firmware-design.rst#user-content-secure-el1-payloads-and-dispatchers
-.. _Firmware Update: ../components/firmware-update.rst
-.. _Firmware Design: ../design/firmware-design.rst
 .. _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
-.. _Secure Partition Manager Design guide: ../components/secure-partition-manager-design.rst
-.. _`Trusted Firmware-A Coding Guidelines`: ../process/coding-guidelines.rst
-.. _Library at ROM: ../components/romlib-design.rst