Doc: Fix internal links in interrupt framework design guide

Some of the sections numbers have been incorrect since the document
structure has changed. Using references to sections rather than
hard-coded section numbers fixes the issue while making it more
future-proof to updates.

Change-Id: I80f5ab6a55a0073b1562a02ce2c9ec7d67cddfff
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

docs/interrupt-framework-design.rst

@@ -89,8 +89,9 @@ incorrect as they conflict with the requirements mentioned in Section 1. The
 following sub-sections describe all the possible routing models and specify
 which ones are valid or invalid. EL3 interrupts are currently supported only
 for GIC version 3.0 (Arm GICv3) and only the Secure-EL1 and Non-secure interrupt
-types are supported for GIC version 2.0 (Arm GICv2) (See 1.2). The terminology
+types are supported for GIC version 2.0 (Arm GICv2) (see `Assumptions in
-used in the following sub-sections is explained below.
+Interrupt Management Framework`_). The terminology used in the following
+sub-sections is explained below.
 
 #. **CSS**. Current Security State. ``0`` when secure and ``1`` when non-secure
 
@@ -230,8 +231,8 @@ The framework makes the following assumptions to simplify its implementation.
 
 Both aspects of interrupt management involve various components in the secure
 software stack spanning from EL3 to Secure-EL1. These components are described
-in the section 2.1. The framework stores information associated with each type
+in the section `Software components`_. The framework stores information
-of interrupt in the following data structure.
+associated with each type of interrupt in the following data structure.
 
 .. code:: c
 
@@ -244,11 +245,11 @@ of interrupt in the following data structure.
 The ``flags`` field stores the routing model for the interrupt type in
 bits[1:0]. Bit[0] stores the routing model when execution is in the secure
 state. Bit[1] stores the routing model when execution is in the non-secure
-state. As mentioned in Section 1.2.2, a value of ``0`` implies that the interrupt
+state. As mentioned in Section `Routing model`_, a value of ``0`` implies that
-should be targeted to the FEL. A value of ``1`` implies that it should be targeted
+the interrupt should be targeted to the FEL. A value of ``1`` implies that it
-to EL3. The remaining bits are reserved and SBZ. The helper macro
+should be targeted to EL3. The remaining bits are reserved and SBZ. The helper
-``set_interrupt_rm_flag()`` should be used to set the bits in the ``flags``
+macro ``set_interrupt_rm_flag()`` should be used to set the bits in the
-parameter.
+``flags`` parameter.
 
 The ``scr_el3[2]`` field also stores the routing model but as a mapping of the
 model in the ``flags`` field to the corresponding bit in the ``SCR_EL3`` for each
@@ -302,8 +303,9 @@ briefly described below.
 Interrupt registration
 ----------------------
 
-This section describes in detail the role of each software component (see 2.1)
+This section describes in detail the role of each software component (see
-during the registration of a handler for an interrupt type.
+`Software components`_) during the registration of a handler for an interrupt
+type.
 
 EL3 runtime firmware
 ~~~~~~~~~~~~~~~~~~~~
@@ -395,6 +397,8 @@ runtime firmware is responsible for programming the routing model. The SPD is
 responsible for ensuring that the routing model has been adhered to upon
 receiving an interrupt.
 
+.. _spd-int-registration:
+
 Secure payload dispatcher
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -487,6 +491,8 @@ requirements mentioned earlier.
        if (rc)
            panic();
 
+.. _sp-int-registration:
+
 Secure payload
 ~~~~~~~~~~~~~~
 
@@ -512,10 +518,10 @@ The interrupt handling framework implemented by the SP should support one or
 both these interrupt handling models depending upon the chosen routing model.
 
 The following list briefly describes how the choice of a valid routing model
-(See 1.2.3) effects the implementation of the Secure-EL1 IHF. If the choice of
+(see `Valid routing models`_) effects the implementation of the Secure-EL1
-the interrupt routing model is not known to the SPD service at compile time,
+IHF. If the choice of the interrupt routing model is not known to the SPD
-then the SP should pass this information to the SPD service at runtime during
+service at compile time, then the SP should pass this information to the SPD
-its initialisation phase.
+service at runtime during its initialisation phase.
 
 As mentioned earlier, an Arm GICv2 system is considered and it is assumed that
 the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal
@@ -584,7 +590,10 @@ Test secure payload behavior
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The routing model for Secure-EL1 and non-secure interrupts chosen by the TSP is
-described in Section 2.2.2. It is known to the TSPD service at build time.
+described in Section `Secure Payload Dispatcher`__. It is known to the TSPD
+service at build time.
+
+.. __: #spd-int-registration
 
 The TSP implements an entrypoint (``tsp_sel1_intr_entry()``) for handling Secure-EL1
 interrupts taken in non-secure state and routed through the TSPD service
@@ -599,13 +608,14 @@ VBAR_EL1. It caters for the asynchronous handling model.
 
 The TSP also programs the Secure Physical Timer in the Arm Generic Timer block
 to raise a periodic interrupt (every half a second) for the purpose of testing
-interrupt management across all the software components listed in 2.1
+interrupt management across all the software components listed in `Software
+components`_.
 
 Interrupt handling
 ------------------
 
 This section describes in detail the role of each software component (see
-Section 2.1) in handling an interrupt of a particular type.
+Section `Software components`_) in handling an interrupt of a particular type.
 
 EL3 runtime firmware
 ~~~~~~~~~~~~~~~~~~~~
@@ -769,7 +779,7 @@ invoked.
    will be trashed, which is the ``ELR_EL3`` and ``SPSR_EL3``, in order to be able
    to re-enter TSP for Secure-EL1 interrupt processing. It does not need to
    save any other secure context since the TSP is expected to preserve it
-   (see Section 2.2.2.1).
+   (see section `Test secure payload dispatcher behavior`_).
 
 #. It restores the system register context for the secure state by calling
    ``cm_el1_sysregs_context_restore(SECURE);``.
@@ -823,21 +833,21 @@ interrupt may preempt Secure execution.
 It should be noted that while TSP is preempted, the TSPD only allows entry into
 the TSP either for Secure-EL1 interrupt handling or for resuming the preempted
 ``yielding`` SMC in response to the ``TSP_FID_RESUME`` SMC from the normal world.
-(See Section 3).
+(See Section `Implication of preempted SMC on Non-Secure Software`_).
 
-The non-secure interrupt triggered in Secure-EL1 during ``yielding`` SMC processing
+The non-secure interrupt triggered in Secure-EL1 during ``yielding`` SMC
-can be routed to either EL3 or Secure-EL1 and is controlled by build option
+processing can be routed to either EL3 or Secure-EL1 and is controlled by build
-``TSP_NS_INTR_ASYNC_PREEMPT`` (see Section 2.2.2.1). If the build option is set,
+option ``TSP_NS_INTR_ASYNC_PREEMPT`` (see Section `Test secure payload
-the TSPD will set the routing model for the non-secure interrupt to be routed to
+dispatcher behavior`_). If the build option is set, the TSPD will set the
-EL3 from secure state i.e. **TEL3=1, CSS=0** and registers
+routing model for the non-secure interrupt to be routed to EL3 from secure state
-``tspd_ns_interrupt_handler()`` as the non-secure interrupt handler. The
+i.e. **TEL3=1, CSS=0** and registers ``tspd_ns_interrupt_handler()`` as the
-``tspd_ns_interrupt_handler()`` on being invoked ensures that the interrupt
+non-secure interrupt handler. The ``tspd_ns_interrupt_handler()`` on being
-originated from the secure state and disables routing of non-secure interrupts
+invoked ensures that the interrupt originated from the secure state and disables
-from secure state to EL3. This is to prevent further preemption (by a non-secure
+routing of non-secure interrupts from secure state to EL3. This is to prevent
-interrupt) when TSP is reentered for handling Secure-EL1 interrupts that
+further preemption (by a non-secure interrupt) when TSP is reentered for
-triggered while execution was in the normal world. The
+handling Secure-EL1 interrupts that triggered while execution was in the normal
-``tspd_ns_interrupt_handler()`` then invokes ``tspd_handle_sp_preemption()`` for
+world. The ``tspd_ns_interrupt_handler()`` then invokes
-further handling.
+``tspd_handle_sp_preemption()`` for further handling.
 
 If the ``TSP_NS_INTR_ASYNC_PREEMPT`` build option is zero (default), the default
 routing model for non-secure interrupt in secure state is in effect
@@ -866,10 +876,11 @@ invoked:
 #. ``SMC_PREEMPTED`` is set in x0 and return to non secure state after
    restoring non secure context.
 
-The Normal World is expected to resume the TSP after the ``yielding`` SMC preemption
+The Normal World is expected to resume the TSP after the ``yielding`` SMC
-by issuing an SMC with ``TSP_FID_RESUME`` as the function identifier (see section 3).
+preemption by issuing an SMC with ``TSP_FID_RESUME`` as the function identifier
-The TSPD service takes the following actions in ``tspd_smc_handler()`` function
+(see section `Implication of preempted SMC on Non-Secure Software`_).  The TSPD
-upon receiving this SMC:
+service takes the following actions in ``tspd_smc_handler()`` function upon
+receiving this SMC:
 
 #. It ensures that the call originated from the non secure state. An
    assertion is raised otherwise.
@@ -898,16 +909,18 @@ Secure payload
 
 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 2.2.3).
+chosen (as described in section `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
 time or during the registration phase. Before handling the interrupt, the SP
 should save any Secure-EL1 system register context which is needed for resuming
-normal execution in the SP later e.g. ``SPSR_EL1,``\ ELR_EL1\`. After handling the
+normal execution in the SP later e.g. ``SPSR_EL1``, ``ELR_EL1``. After handling
-interrupt, the SP could return control back to the exception level and security
+the interrupt, the SP could return control back to the exception level and
-state where the interrupt was originally taken from. The SP should use an SMC32
+security state where the interrupt was originally taken from. The SP should use
-or SMC64 to ask the SPD service to do this.
+an SMC32 or SMC64 to ask the SPD service to do this.
 
 In the asynchronous model, the Secure Payload is responsible for handling
 non-secure and Secure-EL1 interrupts at the IRQ and FIQ vectors in its exception
@@ -922,8 +935,9 @@ Test secure payload behavior
 
 The TSPD hands control of a Secure-EL1 interrupt to the TSP at the
 ``tsp_sel1_intr_entry()``. The TSP handles the interrupt while ensuring that the
-handover agreement described in Section 2.2.2.1 is maintained. It updates some
+handover agreement described in Section `Test secure payload dispatcher
-statistics by calling ``tsp_update_sync_sel1_intr_stats()``. It then calls
+behavior`_ is maintained. It updates some statistics by calling
+``tsp_update_sync_sel1_intr_stats()``. It then calls
 ``tsp_common_int_handler()`` which.
 
 #. Checks whether the interrupt is the secure physical timer interrupt. It
@@ -947,12 +961,13 @@ The TSP handles interrupts under the asynchronous model as follows.
 #. Secure-EL1 interrupts are handled by calling the ``tsp_common_int_handler()``
    function. The function has been described above.
 
-#. Non-secure interrupts are handled by by calling the ``tsp_common_int_handler()``
+#. Non-secure interrupts are handled by calling the ``tsp_common_int_handler()``
    function which ends up invoking ``tsp_handle_preemption()`` and issuing an
    SMC64 with ``TSP_PREEMPTED`` as the function identifier. Execution resumes at
-   the instruction that follows this SMC instruction when the TSPD hands
+   the instruction that follows this SMC instruction when the TSPD hands control
-   control to the TSP in response to an SMC with ``TSP_FID_RESUME`` as the
+   to the TSP in response to an SMC with ``TSP_FID_RESUME`` as the function
-   function identifier from the non-secure state (see section 2.3.2.4).
+   identifier from the non-secure state (see section `Test secure payload
+   dispatcher non-secure interrupt handling`_).
 
 Other considerations
 --------------------