doc: Add minimal glossary

One of the current issues with the documentation is that terms and
abbreviations are frequently redefined. For example, we might have
a sentence like "... the SCP (System Control Processor) will ...".

These definitions might be repeated several times across pages, or
even within the same document. Equally, some of these abbreviations
are missed and are never expanded.

Sphinx provides a :term: keyword that takes some text and,
if that text is defined in a glossary document, links to its glossary
entry. Using this functionality will prevent repeated definitions
and will make the docs more maintainable by using a single
definition source.

The glossary added in this patch was created from a quick scrub of
the source code - there may be missing entries. The SDEI abbreviation
was used as an example.

Note that a global_substitutions file was created. This file contains
the RST 'replace' statements that convert plain text terms into linked
terms (by adding the ':term:' keyword to them). An example is:

.. |TF-A| replace:: :term:`TF-A`

The 'rst_prolog' variable in conf.py is used to inject this list of
replacements into each page. Terms must be surrounded with the pipe
character to be turned into links - this means that we can still
prevent certain terms from being linked if we don't want them to be.

Change-Id: I87010ed9cfa4a60011a9b4a431b98cb4bb7baa28
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

1 files changed, 17 insertions, 16 deletions

diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 458615ec..5be8c152 100644
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -1840,7 +1840,7 @@ line boundary.
 SDEI porting requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The SDEI dispatcher requires the platform to provide the following macros
+The |SDEI| dispatcher requires the platform to provide the following macros
 and functions, of which some are optional, and some others mandatory.
 
 Macros
@@ -1850,19 +1850,19 @@ Macro: PLAT_SDEI_NORMAL_PRI [mandatory]
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This macro must be defined to the EL3 exception priority level associated with
-Normal SDEI events on the platform. This must have a higher value (therefore of
-lower priority) than ``PLAT_SDEI_CRITICAL_PRI``.
+Normal |SDEI| events on the platform. This must have a higher value
+(therefore of lower priority) than ``PLAT_SDEI_CRITICAL_PRI``.
 
 Macro: PLAT_SDEI_CRITICAL_PRI [mandatory]
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This macro must be defined to the EL3 exception priority level associated with
-Critical SDEI events on the platform. This must have a lower value (therefore of
-higher priority) than ``PLAT_SDEI_NORMAL_PRI``.
+Critical |SDEI| events on the platform. This must have a lower value
+(therefore of higher priority) than ``PLAT_SDEI_NORMAL_PRI``.
 
-**Note**: SDEI exception priorities must be the lowest among Secure priorities.
-Among the SDEI exceptions, Critical SDEI priority must be higher than Normal
-SDEI priority.
+**Note**: |SDEI| exception priorities must be the lowest among Secure
+priorities. Among the |SDEI| exceptions, Critical |SDEI| priority must
+be higher than Normal |SDEI| priority.
 
 Functions
 .........
@@ -1876,10 +1876,10 @@ Function: int plat_sdei_validate_entry_point(uintptr_t ep) [optional]
   Return: int
 
 This function validates the address of client entry points provided for both
-event registration and *Complete and Resume* SDEI calls. The function takes one
-argument, which is the address of the handler the SDEI client requested to
-register. The function must return ``0`` for successful validation, or ``-1``
-upon failure.
+event registration and *Complete and Resume* |SDEI| calls. The function
+takes one argument, which is the address of the handler the |SDEI| client
+requested to register. The function must return ``0`` for successful validation,
+or ``-1`` upon failure.
 
 The default implementation always returns ``0``. On Arm platforms, this function
 is implemented to translate the entry point to physical address, and further to
@@ -1894,11 +1894,12 @@ Function: void plat_sdei_handle_masked_trigger(uint64_t mpidr, unsigned int intr
   Argument: unsigned int
   Return: void
 
-SDEI specification requires that a PE comes out of reset with the events masked.
-The client therefore is expected to call ``PE_UNMASK`` to unmask SDEI events on
-the PE. No SDEI events can be dispatched until such time.
+|SDEI| specification requires that a PE comes out of reset with the events
+masked. The client therefore is expected to call ``PE_UNMASK`` to unmask
+|SDEI| events on the PE. No |SDEI| events can be dispatched until such
+time.
 
-Should a PE receive an interrupt that was bound to an SDEI event while the
+Should a PE receive an interrupt that was bound to an |SDEI| event while the
 events are masked on the PE, the dispatcher implementation invokes the function
 ``plat_sdei_handle_masked_trigger``. The MPIDR of the PE that received the
 interrupt and the interrupt ID are passed as parameters.