From 8aa050554b996406231a66a048b56fa03ba220c8 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Thu, 7 Mar 2019 15:47:15 +0000 Subject: doc: Reword document titles This patch attempts to standardise the document titles as well as adding titles to documents that were missing one. The aim is to remove needless references to "TF-A" or "Trusted Firmware" in the title of every document and to make sure that the title matches with the document content. Change-Id: I9b93ccf43b5d57e8dc793a5311b8ed7c4dd245cc Signed-off-by: Paul Beesley --- docs/components/exception-handling.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) (limited to 'docs/components/exception-handling.rst') diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index e3684f13..b370c02f 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -1,8 +1,5 @@ -Exception Handling Framework in Trusted Firmware-A -================================================== - - - +Exception Handling Framework +============================ .. contents:: :depth: 2 -- cgit v1.2.3 From 57354abb2032b4598ce513d5d1ca788fe3bcf356 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Thu, 7 Mar 2019 17:03:22 +0000 Subject: doc: Remove per-page contents lists These are no longer needed as there will always be a table of contents rendered to the left of every page. Some of these lists can be quite long and, when opening a page, the reader sees nothing but a huge list of contents! After this patch, the document contents are front-and-centre and the contents are nicely rendered in the sidebar without duplication. Change-Id: I444754d548ec91d00f2b04e861de8dde8856aa62 Signed-off-by: Paul Beesley --- docs/components/exception-handling.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/components/exception-handling.rst') diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index b370c02f..2452e06a 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -1,9 +1,6 @@ Exception Handling Framework ============================ -.. contents:: - :depth: 2 - .. |EHF| replace:: Exception Handling Framework .. |TF-A| replace:: Trusted Firmware-A -- cgit v1.2.3 From 8f62ca7b3060b87ede0a55c1972e5d2146a23890 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Wed, 13 Mar 2019 13:58:02 +0000 Subject: 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 --- docs/components/exception-handling.rst | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) (limited to 'docs/components/exception-handling.rst') diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index 2452e06a..a89a05c9 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -1,9 +1,6 @@ Exception Handling Framework ============================ -.. |EHF| replace:: Exception Handling Framework -.. |TF-A| replace:: Trusted Firmware-A - This document describes various aspects of handling exceptions by Runtime Firmware (BL31) that are targeted at EL3, other than SMCs. The |EHF| takes care of the following exceptions when targeted at EL3: @@ -48,11 +45,11 @@ exceptions are targeted at and handled in EL3. For instance: - The Arm `SDEI specification`_ defines interfaces through which Normal world interacts with the Runtime Firmware in order to request notification of - system events. The SDEI specification requires that these events are notified - even when the Normal world executes with the exceptions masked. This too - implies that firmware-first handling is required, where the events are first - received by the EL3 firmware, and then dispatched to Normal world through - purely software mechanism. + system events. The |SDEI| specification requires that these events are + notified even when the Normal world executes with the exceptions masked. This + too implies that firmware-first handling is required, where the events are + first received by the EL3 firmware, and then dispatched to Normal world + through purely software mechanism. For |TF-A|, firmware-first handling means that asynchronous exceptions are suitably routed to EL3, and the Runtime Firmware (BL31) is extended to include @@ -73,8 +70,8 @@ choose to: processing of the error to dedicated software stack running at lower secure ELs (as above); additionally, the Normal world may also be required to participate in the handling, or be notified of such events (for example, as - an SDEI event). In this scheme, exception handling potentially and maximally - spans all ELs in both Secure and Normal worlds. + an |SDEI| event). In this scheme, exception handling potentially and + maximally spans all ELs in both Secure and Normal worlds. On any given system, all of the above handling models may be employed independently depending on platform choice and the nature of the exception @@ -603,8 +600,8 @@ should carefully consider the assignment of priorities to dispatchers integrated into runtime firmware. The platform should sensibly delineate priority to various dispatchers according to their nature. In particular, dispatchers of critical nature (RAS, for example) should be assigned higher priority than -others (SDEI, for example); and within SDEI, Critical priority SDEI should be -assigned higher priority than Normal ones. +others (|SDEI|, for example); and within |SDEI|, Critical priority +|SDEI| should be assigned higher priority than Normal ones. Limitations ----------- -- cgit v1.2.3 From a2c320a83ef3966b30929636fb8345a7eabee2ae Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Wed, 13 Mar 2019 15:49:27 +0000 Subject: doc: Reorganise images and update links Change-Id: I679d1499376a524bef1cfc33df995b0a719b5ac8 Signed-off-by: Paul Beesley --- docs/components/exception-handling.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/components/exception-handling.rst') diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index a89a05c9..30600f95 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -107,7 +107,7 @@ for more than one priority level. .. _ehf-figure: -.. image:: ../draw.io/ehf.svg +.. image:: ../resources/diagrams/draw.io/ehf.svg A priority level is *active* when a handler at that priority level is currently executing in EL3, or has delegated the execution to a lower EL. For interrupts, -- cgit v1.2.3 From e1c5026ac7e9da1b74047bf8cb9be2a5c9564532 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Wed, 13 Mar 2019 16:20:44 +0000 Subject: doc: Use proper note and warning annotations The documentation contains plenty of notes and warnings. Enable special rendering of these blocks by converting the note prefix into a .. note:: annotation. Change-Id: I34e26ca6bf313d335672ab6c2645741900338822 Signed-off-by: Paul Beesley --- docs/components/exception-handling.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/components/exception-handling.rst') diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index 30600f95..8f74eb65 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -193,7 +193,7 @@ priority assignment: 6 and 5), the platform can partition into 4 secure priority ranges: ``0x0``, ``0x20``, ``0x40``, and ``0x60``. See `Interrupt handling example`_. -Note: +.. note:: The Arm GIC architecture requires that a GIC implementation that supports two security states must implement at least 32 priority levels; i.e., at least 5 @@ -215,7 +215,7 @@ priority level descriptors. Each entry in the array is of type ``ehf_pri_desc_t``, and declares a priority level, and shall be populated by the ``EHF_PRI_DESC()`` macro. -Note: +.. warning:: The macro ``EHF_PRI_DESC()`` installs the descriptors in the array at a computed index, and not necessarily where the macro is placed in the array. -- cgit v1.2.3