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>
diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst
index 2a777b3..c5275a0 100644
--- a/docs/components/sdei.rst
+++ b/docs/components/sdei.rst
@@ -7,7 +7,7 @@
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 @@
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 @@
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 @@
- 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 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 @@
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 @@
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 @@
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 @@
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`_