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>

6 files changed, 92 insertions, 93 deletions

diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst
index 7de8ee1e..93f691b7 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``.
@@ -967,6 +967,4 @@ The mbedTLS library algorithm support is configured by both the
 
 *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 a392eea2..891703bf 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
@@ -326,6 +327,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 2cbd9c94..1deacb7f 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
@@ -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
 ------------------------------
@@ -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.
@@ -1866,7 +1878,7 @@ BL image during boot.
 Library at ROM
 ---------------
 
-Please refer to the `ROMLIB Design`_ document.
+Please refer to the :ref:`Library at ROM` document.
 
 Firmware Image Package (FIP)
 ----------------------------
@@ -1978,11 +1990,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 +2200,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 +2393,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 +2543,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`_.
+See also the *Summary of build options* in :ref:`User Guide`.
 
 For details on the Architecture Extension and available features, please refer
 to the respective Architecture Extension Supplement.
@@ -2668,37 +2682,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)`_
-.. [#] `Power State Coordination Interface PDD`_
-.. [#] `SMC Calling Convention PDD`_
-.. [#] `TF-A Interrupt Management Design guide`_.
+-  `Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D)`_
+
+-  `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/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst
index 4a864f9c..d155cb35 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 ccd717a0..a92ceeba 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:`User Guide` 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.rst b/docs/design/trusted-board-boot.rst
index 82be272b..f3b1c364 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 the
+:ref:`User Guide`.
 
 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
 ---------------------------
@@ -221,15 +224,11 @@ 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`_.
+for building and using the tool can be found in the :ref:`User Guide`.
 
 --------------
 
 *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