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>

7 files changed, 65 insertions, 85 deletions

diff --git a/docs/components/arm-sip-service.rst b/docs/components/arm-sip-service.rst
index e450d375..2d58586b 100644
--- a/docs/components/arm-sip-service.rst
+++ b/docs/components/arm-sip-service.rst
@@ -24,9 +24,9 @@ file.
 Performance Measurement Framework (PMF)
 ---------------------------------------
 
-The `Performance Measurement Framework`_
+The :ref:`Performance Measurement Framework <firmware_design_pmf>`
 allows callers to retrieve timestamps captured at various paths in TF-A
-execution. It's described in detail in `Firmware Design document`_.
+execution.
 
 Execution State Switching service
 ---------------------------------
@@ -89,8 +89,6 @@ respectively.
 
 --------------
 
-*Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.*
 
 .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
-.. _Performance Measurement Framework: ../design/firmware-design.rst#user-content-performance-measurement-framework
-.. _Firmware Design document: ../design/firmware-design.rst
diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst
index 0d017331..3f386854 100644
--- a/docs/components/exception-handling.rst
+++ b/docs/components/exception-handling.rst
@@ -26,8 +26,8 @@ Introduction
 
 Through various control bits in the ``SCR_EL3`` register, the Arm architecture
 allows for asynchronous exceptions to be routed to EL3. As described in the
-`Interrupt Framework Design`_ document, depending on the chosen interrupt
-routing model, TF-A appropriately sets the ``FIQ`` and ``IRQ`` bits of
+:ref:`Interrupt Management Framework` document, depending on the chosen
+interrupt routing model, TF-A appropriately sets the ``FIQ`` and ``IRQ`` bits of
 ``SCR_EL3`` register to effect this routing. For most use cases, other than for
 the purpose of facilitating context switch between Normal and Secure worlds,
 FIQs and IRQs routed to EL3 are not required to be handled in EL3.
@@ -143,8 +143,9 @@ Interrupt handling
 ------------------
 
 The |EHF| is a client of *Interrupt Management Framework*, and registers the
-top-level handler for interrupts that target EL3, as described in the `Interrupt
-Framework Design`_ document. This has the following implications.
+top-level handler for interrupts that target EL3, as described in the
+:ref:`Interrupt Management Framework` document. This has the following
+implications:
 
 -  On GICv3 systems, when executing in S-EL1, pending Non-secure interrupts of
    sufficient priority are signalled as FIQs, and therefore will be routed to
@@ -618,9 +619,8 @@ The |EHF| has the following limitations:
    exception descriptor and the programmed priority of interrupts handled by the
    dispatcher match. The |EHF| cannot verify that this has been followed.
 
-----
+--------------
 
-*Copyright (c) 2018, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.*
 
-.. _Interrupt Framework Design: ../design/interrupt-framework-design.rst
 .. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst
index 30bdc24b..2bff00f5 100644
--- a/docs/components/firmware-update.rst
+++ b/docs/components/firmware-update.rst
@@ -14,8 +14,8 @@ be complemented by other, higher level firmware update software.
 
 FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
 specification, Arm DEN0006C-1. It should be used in conjunction with the
-`Trusted Board Boot`_ design document, which describes the image authentication
-parts of the Trusted Firmware-A (TF-A) TBBR implementation.
+:ref:`Trusted Board Boot` design document, which describes the image
+authentication parts of the Trusted Firmware-A (TF-A) TBBR implementation.
 
 Scope
 ~~~~~
@@ -53,10 +53,11 @@ The primary requirements of the FWU feature are:
    at other Exception Levels.
 #. Export a platform interface to provide FWU common code with the information
    it needs, and to enable platform specific FWU functionality. See the
-   `Porting Guide`_ for details of this interface.
+   :ref:`Porting Guide` for details of this interface.
 
 TF-A uses abbreviated image terminology for FWU images like for other TF-A
-images. An overview of this terminology can be found `here`_.
+images. See the :ref:`Image Terminology` document for an explanation of these
+terms.
 
 The following diagram shows the FWU boot flow for Arm development platforms.
 Arm CSS platforms like Juno have a System Control Processor (SCP), and these
@@ -70,8 +71,8 @@ Image Identification
 Each FWU image and certificate is identified by a unique ID, defined by the
 platform, which BL1 uses to fetch an image descriptor (``image_desc_t``) via a
 call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the
-Chain of Trust (Refer to the `Authentication Framework Design`_
-for more information).
+Chain of Trust (Refer to the :ref:`Authentication Framework & Chain of Trust`
+document for more information).
 
 The image descriptor includes the following information:
 
@@ -394,11 +395,6 @@ This is only allowed if the image is not being executed.
 
 *Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.*
 
-.. _Trusted Board Boot: ../design/trusted-board-boot.rst
-.. _Porting Guide: ../getting_started/porting-guide.rst
-.. _here: ../getting_started/image-terminology.rst
-.. _Authentication Framework Design: ../design/auth-framework.rst
 .. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
-
 .. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png
 .. |FWU state machine| image:: ../resources/diagrams/fwu_states.png
diff --git a/docs/components/platform-interrupt-controller-API.rst b/docs/components/platform-interrupt-controller-API.rst
index 7890cd38..9d02f45c 100644
--- a/docs/components/platform-interrupt-controller-API.rst
+++ b/docs/components/platform-interrupt-controller-API.rst
@@ -3,9 +3,8 @@ Platform Interrupt Controller API
 
 This document lists the optional platform interrupt controller API that
 abstracts the runtime configuration and control of interrupt controller from the
-generic code. The mandatory APIs are described in the `porting guide`__.
-
-.. __: ../getting_started/porting-guide.rst#interrupt-management-framework-in-bl31
+generic code. The mandatory APIs are described in the
+:ref:`Porting Guide <porting_guide_imf_in_bl31>`.
 
 Function: unsigned int plat_ic_get_running_priority(void); [optional]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -303,6 +302,6 @@ should return ``INTR_ID_UNAVAILABLE``.
 In case of Arm standard platforms using GIC, the implementation of the API
 masks out the interrupt ID field from the acknowledged value from GIC.
 
-----
+--------------
 
-*Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/components/ras.rst b/docs/components/ras.rst
index 137c0c30..3d81f17e 100644
--- a/docs/components/ras.rst
+++ b/docs/components/ras.rst
@@ -1,9 +1,6 @@
 Reliability, Availability, and Serviceability (RAS) Extensions
 ==============================================================
 
-.. |EHF| replace:: Exception Handling Framework
-.. |TF-A| replace:: Trusted Firmware-A
-
 This document describes |TF-A| support for Arm Reliability, Availability, and
 Serviceability (RAS) extensions. RAS is a mandatory extension for Armv8.2 and
 later CPUs, and also an optional extension to the base Armv8.0 architecture.
@@ -247,6 +244,6 @@ explicit using `EHF APIs`__.
 .. __: exception-handling.rst#non-interrupt-flow
 .. __: exception-handling.rst#activating-and-deactivating-priorities
 
-----
+--------------
 
-*Copyright (c) 2018, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst
index 2a777b38..c5275a0b 100644
--- a/docs/components/sdei.rst
+++ b/docs/components/sdei.rst
@@ -7,7 +7,7 @@ Trusted Firmware-A (TF-A).
 Introduction
 ------------
 
-`Software Delegated Exception Interface`_ (SDEI) is an Arm specification for
+Software Delegated Exception Interface (|SDEI|) is an Arm specification for
 Non-secure world to register handlers with firmware to receive notifications
 about system events. Firmware will first receive the system events by way of
 asynchronous exceptions and, in response, arranges for the registered handler to
@@ -50,9 +50,6 @@ The remainder of this document only discusses the design and implementation of
 SDEI dispatcher in TF-A, and assumes that the reader is familiar with the SDEI
 specification, the interfaces, and their requirements.
 
-.. [#std-event] Except event 0, which is defined by the SDEI specification as a
-                standard event.
-
 Defining events
 ---------------
 
@@ -78,12 +75,10 @@ event descriptors. Both macros take 3 arguments:
 To define event 0, the macro ``SDEI_DEFINE_EVENT_0()`` should be used. This
 macro takes only one parameter: an SGI number to signal other PEs.
 
-To define an event that's meant to be `explicitly dispatched`__ (i.e., not as a
+To define an event that's meant to be explicitly dispatched (i.e., not as a
 result of receiving an SDEI interrupt), the macro ``SDEI_EXPLICIT_EVENT()``
 should be used. It accepts two parameters:
 
-.. __: `Explicit dispatch of events`_
-
 -  The event number (as above);
 
 -  Event priority: ``SDEI_MAPF_CRITICAL`` or ``SDEI_MAPF_NORMAL``, as described
@@ -110,9 +105,7 @@ Regarding event descriptors:
 
 -  Statically bound shared and private interrupts must be bound to shared and
    private interrupts on the platform, respectively. See the section on
-   `interrupt configuration`__.
-
-   .. __: `Configuration within Exception Handling Framework`_
+   `Configuration within Exception Handling Framework`_.
 
 -  Both arrays should be one-dimensional. The ``REGISTER_SDEI_MAP()`` macro
    takes care of replicating private events for each PE on the platform.
@@ -130,9 +123,8 @@ Event flags
 ~~~~~~~~~~~
 
 Event flags describe the properties of the event. They are bit maps that can be
-``OR``\ ed to form parameters to macros that `define events`__.
-
-.. __: `Defining events`_
+``OR``\ ed to form parameters to macros that define events (see
+`Defining events`_).
 
 -  ``SDEI_MAPF_DYNAMIC``: Marks the event as dynamic. Dynamic events can be
    bound to (or released from) any Non-secure interrupt at runtime via the
@@ -196,7 +188,7 @@ interrupts for the platform:
    be configured as *Group 0*.  Additionally, on GICv2 systems, the build option
    ``GICV2_G0_FOR_EL3`` must be set to ``1``.
 
-See also `SDEI porting requirements`_.
+See also :ref:`porting_guide_sdei_requirements`.
 
 Determining client EL
 ---------------------
@@ -250,10 +242,6 @@ rest of the sequence is similar to that in the `general SDEI dispatch`_: the
 requested event is dispatched to the client (assuming all the conditions are
 met), and when the handler completes, the preempted execution resumes.
 
-.. [#critical-event] Examples of critical event are *SError*, *Synchronous
-                     External Abort*, *Fault Handling interrupt*, or *Error
-                     Recovery interrupt* from one of RAS nodes in the system.
-
 Conditions for event dispatch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -307,10 +295,8 @@ dispatcher:
 Porting requirements
 --------------------
 
-The porting requirements of the SDEI dispatcher are outlined in the `porting
-guide`__.
-
-.. __: `SDEI porting requirements`_
+The porting requirements of the SDEI dispatcher are outlined in the
+:ref:`Porting Guide <porting_guide_sdei_requirements>`.
 
 Note on writing SDEI event handlers
 -----------------------------------
@@ -364,10 +350,18 @@ implemented in assembly, following a similar pattern as below:
                 smc     #0
                 b       .
 
-----
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.*
 
-*Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
+.. rubric:: Footnotes
+
+.. [#std-event] Except event 0, which is defined by the SDEI specification as a
+                standard event.
+
+.. [#critical-event] Examples of critical events are *SError*, *Synchronous
+                     External Abort*, *Fault Handling interrupt* or *Error
+                     Recovery interrupt* from one of RAS nodes in the system.
 
 .. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
-.. _SDEI porting requirements: ../getting_started/porting-guide.rst#sdei-porting-requirements
 .. _Software Delegated Exception Interface: `SDEI specification`_
diff --git a/docs/components/xlat-tables-lib-v2-design.rst b/docs/components/xlat-tables-lib-v2-design.rst
index 786dd3bc..af5151f7 100644
--- a/docs/components/xlat-tables-lib-v2-design.rst
+++ b/docs/components/xlat-tables-lib-v2-design.rst
@@ -30,8 +30,8 @@ About version 1 and version 2
 -----------------------------
 
 This document focuses on version 2 of the library, whose sources are available
-in the `lib/xlat_tables_v2`_ directory. Version 1 of the library can still be
-found in `lib/xlat_tables`_ directory but it is less flexible and doesn't
+in the ``lib/xlat_tables_v2`` directory. Version 1 of the library can still be
+found in ``lib/xlat_tables`` directory but it is less flexible and doesn't
 support dynamic mapping. Although potential bug fixes will be applied to both
 versions, future features enhancements will focus on version 2 and might not be
 back-ported to version 1. Therefore, it is recommended to use version 2,
@@ -62,7 +62,7 @@ map. It is one of the key interfaces to the library. It is identified by:
 - its attributes;
 - its mapping granularity (optional).
 
-See the ``struct mmap_region`` type in `xlat_tables_v2.h`_.
+See the ``struct mmap_region`` type in ``xlat_tables_v2.h``.
 
 The user usually provides a list of such mmap regions to map and lets the
 library transpose that in a set of translation tables. As a result, the library
@@ -73,7 +73,7 @@ normal memory) as well as the memory access permissions (read-only or
 read-write, executable or not, secure or non-secure, and so on). In the case of
 the EL1&0 translation regime, the attributes also specify whether the region is
 a User region (EL0) or Privileged region (EL1). See the ``MT_xxx`` definitions
-in `xlat_tables_v2.h`_. Note that for the EL1&0 translation regime the Execute
+in ``xlat_tables_v2.h``. Note that for the EL1&0 translation regime the Execute
 Never attribute is set simultaneously for both EL1 and EL0.
 
 The granularity controls the translation table level to go down to when mapping
@@ -162,7 +162,7 @@ coming (for the most part) from platform-specific defines:
 - size of the virtual address space: ``PLAT_VIRT_ADDR_SPACE_SIZE``;
 - size of the physical address space: ``PLAT_PHY_ADDR_SPACE_SIZE``.
 
-Please refer to the `Porting Guide`_ for more details about these macros.
+Please refer to the :ref:`Porting Guide` for more details about these macros.
 
 
 Static and dynamic memory regions
@@ -201,7 +201,7 @@ Library APIs
 ------------
 
 The external APIs exposed by this library are declared and documented in the
-`xlat_tables_v2.h`_ header file. This should be the reference point for
+``xlat_tables_v2.h`` header file. This should be the reference point for
 getting information about the usage of the different APIs this library
 provides. This section just provides some extra details and clarifications.
 
@@ -284,7 +284,7 @@ The library is divided into 4 modules:
   provides functions such as ``mmap_add_region_ctx`` that let the caller specify
   the translation tables context affected by them.
 
-  See `xlat_tables_core.c`_.
+  See ``xlat_tables_core.c``.
 
 - **Active context module**
 
@@ -293,14 +293,14 @@ The library is divided into 4 modules:
   This module provides functions such as ``mmap_add_region``, that directly
   affect the BL image using them.
 
-  See `xlat_tables_context.c`_.
+  See ``xlat_tables_context.c``.
 
 - **Utilities module**
 
   Provides additional functionality like debug print of the current state of the
   translation tables and helpers to query memory attributes and to modify them.
 
-  See `xlat_tables_utils.c`_.
+  See ``xlat_tables_utils.c``.
 
 - **Architectural module**
 
@@ -309,7 +309,7 @@ The library is divided into 4 modules:
   MMU, or calculate the Physical Address Space size. They do not need a
   translation context to work on.
 
-  See `aarch32/xlat_tables_arch.c`_ and `aarch64/xlat_tables_arch.c`_.
+  See ``aarch32/xlat_tables_arch.c`` and ``aarch64/xlat_tables_arch.c``.
 
 From mmap regions to translation tables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -343,7 +343,7 @@ The mapping function is implemented as a recursive algorithm. It is however
 bound by the level of depth of the translation tables (the Armv8-A architecture
 allows up to 4 lookup levels).
 
-By default [#granularity-ref]_, the algorithm will attempt to minimize the
+By default [#granularity]_, the algorithm will attempt to minimize the
 number of translation tables created to satisfy the user's request. It will
 favour mapping a region using the biggest possible blocks, only creating a
 sub-table if it is strictly necessary. This is to reduce the memory footprint of
@@ -374,9 +374,6 @@ entries in the translation tables are checked to ensure consistency. Please
 refer to the comments in the source code of the core module for more details
 about the sorting algorithm in use.
 
-.. [#granularity-ref] That is, when mmap regions do not enforce their mapping
-                      granularity.
-
 TLB maintenance operations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -402,20 +399,19 @@ descriptor. Given that the TLBs are not architecturally permitted to hold any
 invalid translation table entry [#tlb-no-invalid-entry]_, this means that this
 mapping cannot be cached in the TLBs.
 
-.. [#tlb-reset-ref] See section D4.9 `Translation Lookaside Buffers (TLBs)`, subsection `TLB behavior at reset` in Armv8-A, rev C.a.
-.. [#tlb-no-invalid-entry] See section D4.10.1 `General TLB maintenance requirements` in Armv8-A, rev C.a.
+.. rubric:: Footnotes
+
+.. [#granularity] That is, when mmap regions do not enforce their mapping
+                  granularity.
+
+.. [#tlb-reset-ref] See section D4.9 ``Translation Lookaside Buffers (TLBs)``,
+                    subsection ``TLB behavior at reset`` in Armv8-A, rev C.a.
+
+.. [#tlb-no-invalid-entry] See section D4.10.1 ``General TLB maintenance
+                           requirements`` in Armv8-A, rev C.a.
 
 --------------
 
-*Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
-
-.. _lib/xlat_tables_v2: ../../lib/xlat_tables_v2
-.. _lib/xlat_tables: ../../lib/xlat_tables
-.. _xlat_tables_v2.h: ../../include/lib/xlat_tables/xlat_tables_v2.h
-.. _xlat_tables_context.c: ../../lib/xlat_tables_v2/xlat_tables_context.c
-.. _xlat_tables_core.c: ../../lib/xlat_tables_v2/xlat_tables_core.c
-.. _xlat_tables_utils.c: ../../lib/xlat_tables_v2/xlat_tables_utils.c
-.. _aarch32/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c
-.. _aarch64/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c
-.. _Porting Guide: ../getting_started/porting-guide.rst
+*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.*
+
 .. |Alignment Example| image:: ../resources/diagrams/xlat_align.png