Fix broken links to various sections across docs
These broken links were found with the help of this command:
$> sphinx-build -M linkcheck . build
A sample broken link is reported as follows:
(line 80) -local- firmware-design.rst#secure-el1-payloads-and-dispatchers
Change-Id: I5dcefdd4b8040908658115647e957f6c2c5da7c2
Signed-off-by: Madhukar Pappireddy <madhukar.pappireddy@arm.com>
diff --git a/docs/components/debugfs-design.rst b/docs/components/debugfs-design.rst
index 2096bdb..2536515 100644
--- a/docs/components/debugfs-design.rst
+++ b/docs/components/debugfs-design.rst
@@ -80,8 +80,8 @@
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 4c63a8b..86ed87c 100644
--- a/docs/components/exception-handling.rst
+++ b/docs/components/exception-handling.rst
@@ -10,13 +10,9 @@
- 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 @@
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 @@
the case; for non-interrupts, the |EHF| monitors and asserts this. See
`Transition of priority levels`_.
+.. _interrupt-handling:
+
Interrupt handling
------------------
@@ -151,15 +148,12 @@
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.
@@ -283,15 +277,13 @@
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 +366,9 @@
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 +447,8 @@
If these are violated, a panic will result.
+.. _Effect on SMC calls:
+
Effect on SMC calls
-------------------
@@ -542,10 +534,8 @@
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 9d02f45..069c87b 100644
--- a/docs/components/platform-interrupt-controller-API.rst
+++ b/docs/components/platform-interrupt-controller-API.rst
@@ -286,6 +286,8 @@
*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 c5275a0..60259c8 100644
--- a/docs/components/sdei.rst
+++ b/docs/components/sdei.rst
@@ -205,6 +205,8 @@
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 87fc91d..d532901 100644
--- a/docs/components/secure-partition-manager-mm.rst
+++ b/docs/components/secure-partition-manager-mm.rst
@@ -6,11 +6,9 @@
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 2169f30..e09da53 100644
--- a/docs/components/secure-partition-manager.rst
+++ b/docs/components/secure-partition-manager.rst
@@ -833,9 +833,7 @@
.. _[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 ae6dd46..a357d58 100644
--- a/docs/design/firmware-design.rst
+++ b/docs/design/firmware-design.rst
@@ -957,6 +957,8 @@
|Image 1|
+.. _handling-an-smc:
+
Handling an SMC
~~~~~~~~~~~~~~~
@@ -1300,6 +1302,8 @@
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 2e200aa..dfb2eac 100644
--- a/docs/design/interrupt-framework-design.rst
+++ b/docs/design/interrupt-framework-design.rst
@@ -150,10 +150,8 @@
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 @@
`Software components`_) during the registration of a handler for an interrupt
type.
+.. _el3-runtime-firmware:
+
EL3 runtime firmware
~~~~~~~~~~~~~~~~~~~~
@@ -901,14 +901,14 @@
|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 630d861..b15ea1b 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -346,16 +346,14 @@
- ``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
diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 7aaeae2..6b8bbc6 100644
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -2482,9 +2482,7 @@
``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 @@
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/fvp/index.rst b/docs/plat/arm/fvp/index.rst
index fd658bb..745e31f 100644
--- a/docs/plat/arm/fvp/index.rst
+++ b/docs/plat/arm/fvp/index.rst
@@ -635,7 +635,7 @@
*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