12 files changed, 47 insertions, 91 deletions
diff --git a/docs/components/arm-sip-service.rst b/docs/components/arm-sip-service.rst
index 6cdac835..9cbf1994 100644
--- a/docs/components/arm-sip-service.rst
+++ b/docs/components/arm-sip-service.rst
@@ -1,5 +1,5 @@
-Arm SiP Service
-===============
+Arm SiP Services
+================
 
 This document enumerates and describes the Arm SiP (Silicon Provider) services.
 
diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst
index e3684f13..8f74eb65 100644
--- a/docs/components/exception-handling.rst
+++ b/docs/components/exception-handling.rst
@@ -1,14 +1,5 @@
-Exception Handling Framework in Trusted Firmware-A
-==================================================
-
-
-
-
-.. contents::
-    :depth: 2
-
-.. |EHF| replace:: Exception Handling Framework
-.. |TF-A| replace:: Trusted Firmware-A
+Exception Handling Framework
+============================
 
 This document describes various aspects of handling exceptions by Runtime
 Firmware (BL31) that are targeted at EL3, other than SMCs. The |EHF| takes care
@@ -54,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
@@ -79,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
@@ -116,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,
@@ -202,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
@@ -224,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.
@@ -609,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
 -----------
diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst
index f3ad6af1..31f5917e 100644
--- a/docs/components/firmware-update.rst
+++ b/docs/components/firmware-update.rst
@@ -1,12 +1,5 @@
-Trusted Firmware-A - Firmware Update design guide
-=================================================
-
-
-
-
-.. contents::
-
---------------
+Firmware Update (FWU)
+=====================
 
 Introduction
 ------------
@@ -407,5 +400,5 @@ This is only allowed if the image is not being executed.
 .. _Authentication Framework Design: ./auth-framework.rst
 .. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
 
-.. |Flow Diagram| image:: diagrams/fwu_flow.png?raw=true
-.. |FWU state machine| image:: diagrams/fwu_states.png?raw=true
+.. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png
+.. |FWU state machine| image:: ../resources/diagrams/fwu_states.png
diff --git a/docs/components/platform-interrupt-controller-API.rst b/docs/components/platform-interrupt-controller-API.rst
index 42d92be2..7890cd38 100644
--- a/docs/components/platform-interrupt-controller-API.rst
+++ b/docs/components/platform-interrupt-controller-API.rst
@@ -1,9 +1,5 @@
-Platform Interrupt Controller API documentation
-===============================================
-
-
-
-.. contents::
+Platform Interrupt Controller API
+=================================
 
 This document lists the optional platform interrupt controller API that
 abstracts the runtime configuration and control of interrupt controller from the
diff --git a/docs/components/ras.rst b/docs/components/ras.rst
index f329fb0b..137c0c30 100644
--- a/docs/components/ras.rst
+++ b/docs/components/ras.rst
@@ -1,10 +1,5 @@
-RAS support in Trusted Firmware-A
-=================================
-
-
-
-.. contents::
-    :depth: 2
+Reliability, Availability, and Serviceability (RAS) Extensions
+==============================================================
 
 .. |EHF| replace:: Exception Handling Framework
 .. |TF-A| replace:: Trusted Firmware-A
@@ -44,7 +39,7 @@ be set ``1``.
 
 .. _ras-figure:
 
-.. image:: ../draw.io/ras.svg
+.. image:: ../resources/diagrams/draw.io/ras.svg
 
 See more on `Engaging the RAS framework`_.
 
diff --git a/docs/components/romlib-design.rst b/docs/components/romlib-design.rst
index 41957214..a70ed17f 100644
--- a/docs/components/romlib-design.rst
+++ b/docs/components/romlib-design.rst
@@ -1,11 +1,6 @@
 Library at ROM
 ==============
 
-.. section-numbering::
-    :suffix: .
-
-.. contents::
-
 This document provides an overview of the "library at ROM" implementation in
 Trusted Firmware-A (TF-A).
 
@@ -28,7 +23,7 @@ are placed in ROM. The capabilities of the "library at ROM" are:
 Index file
 ~~~~~~~~~~
 
-.. image:: diagrams/romlib_design.png
+.. image:: ../resources/diagrams/romlib_design.png
     :width: 600
 
 Library at ROM is described by an index file with the list of functions to be
@@ -59,7 +54,7 @@ For an index file example, refer to ``lib/romlib/jmptbl.i``.
 Wrapper functions
 ~~~~~~~~~~~~~~~~~
 
-.. image:: diagrams/romlib_wrapper.png
+.. image:: ../resources/diagrams/romlib_wrapper.png
     :width: 600
 
 When invoking a function of the "library at ROM", the calling sequence is as
@@ -111,7 +106,7 @@ The environment variable ``CROSS_COMPILE`` must be set as per the user guide.
 In the below example the usage of ROMLIB together with mbed TLS is demonstrated
 to showcase the benefits of library at ROM - it's not mandatory.
 
-::
+.. code:: shell
 
     make PLAT=fvp                                                   \
     MBEDTLS_DIR=</path/to/mbedtls/>                                 \
diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst
index aca1ccb0..6d0e1563 100644
--- a/docs/components/sdei.rst
+++ b/docs/components/sdei.rst
@@ -1,9 +1,6 @@
 SDEI: Software Delegated Exception Interface
 ============================================
 
-.. contents::
-    :depth: 2
-
 This document provides an overview of the SDEI dispatcher implementation in
 Trusted Firmware-A (TF-A).
 
@@ -29,7 +26,7 @@ The following figure depicts a general sequence involving SDEI client executing
 at EL2 and an event dispatch resulting from the triggering of a bound interrupt.
 A commentary is provided below:
 
-.. image:: ../plantuml/sdei_general.svg
+.. image:: ../resources/diagrams/plantuml/sdei_general.svg
 
 As part of initialisation, the SDEI client binds a Non-secure interrupt [1], and
 the SDEI dispatcher returns a platform dynamic event number [2]. The client then
@@ -44,7 +41,7 @@ execute the registered handler [10]. The client terminates its execution with
 original EL2 execution [13]. Note that the SDEI interrupt remains active until
 the client handler completes, at which point EL3 does EOI [12].
 
-Other than events bound to interrupts (as depicted in the sequence above, SDEI
+Other than events bound to interrupts, as depicted in the sequence above, SDEI
 events can be explicitly dispatched in response to other exceptions, for
 example, upon receiving an *SError* or *Synchronous External Abort*. See
 `Explicit dispatch of events`_.
@@ -227,7 +224,7 @@ activity, such as receiving a Secure interrupt or an exception.
 The SDEI dispatcher implementation provides ``sdei_dispatch_event()`` API for
 this purpose. The API has the following signature:
 
-::
+.. code:: c
 
         int sdei_dispatch_event(int ev_num);
 
@@ -237,7 +234,7 @@ on success, or ``-1`` on failure.
 The following figure depicts a scenario involving explicit dispatch of SDEI
 event. A commentary is provided below:
 
-.. image:: ../plantuml/sdei_explicit_dispatch.svg
+.. image:: ../resources/diagrams/plantuml/sdei_explicit_dispatch.svg
 
 As part of initialisation, the SDEI client registers a handler for a platform
 event [1], enables the event [3], and unmasks the current PE [5]. Note that,
@@ -373,3 +370,4 @@ implemented in assembly, following a similar pattern as below:
 
 .. _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`_
diff --git a/docs/components/secure-partition-manager-design.rst b/docs/components/secure-partition-manager-design.rst
index 2c32eba1..ac1172c8 100644
--- a/docs/components/secure-partition-manager-design.rst
+++ b/docs/components/secure-partition-manager-design.rst
@@ -1,10 +1,5 @@
-*******************************
-Secure Partition Manager Design
-*******************************
-
-
-
-.. contents::
+Secure Partition Manager
+************************
 
 Background
 ==========
@@ -135,7 +130,7 @@ First, build the Standalone MM Secure Partition. To build it, refer to the
 Then build TF-A with SPM support and include the Standalone MM Secure Partition
 image in the FIP:
 
-::
+.. code:: shell
 
     BL32=path/to/standalone/mm/sp BL33=path/to/bl33.bin \
     make PLAT=fvp ENABLE_SPM=1 ARM_BL31_IN_DRAM=1 fip all
@@ -819,5 +814,5 @@ Error Codes
 .. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf
 .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
 
-.. |Image 1| image:: ../diagrams/secure_sw_stack_tos.png
-.. |Image 2| image:: ../diagrams/secure_sw_stack_sp.png
+.. |Image 1| image:: ../resources/diagrams/secure_sw_stack_tos.png
+.. |Image 2| image:: ../resources/diagrams/secure_sw_stack_sp.png
diff --git a/docs/components/spd/index.rst b/docs/components/spd/index.rst
index e03bfe33..25d0124b 100644
--- a/docs/components/spd/index.rst
+++ b/docs/components/spd/index.rst
@@ -4,7 +4,6 @@ Secure Payload Dispatcher (SPD)
 .. toctree::
    :maxdepth: 1
    :caption: Contents
-   :numbered:
 
    optee-dispatcher
    tlk-dispatcher
diff --git a/docs/components/spd/tlk-dispatcher.rst b/docs/components/spd/tlk-dispatcher.rst
index 90af5faf..a6c658cc 100644
--- a/docs/components/spd/tlk-dispatcher.rst
+++ b/docs/components/spd/tlk-dispatcher.rst
@@ -15,7 +15,7 @@ Once a BL32 is ready, TLKD can be included in the image by adding "SPD=tlkd"
 to the build command.
 
 Trusted Little Kernel (TLK)
-===========================
+---------------------------
 
 TLK is a Trusted OS running as Secure EL1. It is a Free Open Source Software
 (FOSS) release of the NVIDIA® Trusted Little Kernel (TLK) technology, which
@@ -54,20 +54,20 @@ TLK and OTE can be found in the Tegra\_BSP\_for\_Android\_TLK\_FOSS\_Reference.p
 manual located under the "documentation" directory\_.
 
 Build TLK
-=========
+---------
 
 To build and execute TLK, follow the instructions from "Building a TLK Device"
 section from Tegra\_BSP\_for\_Android\_TLK\_FOSS\_Reference.pdf manual.
 
 Input parameters to TLK
-=======================
+-----------------------
 
 TLK expects the TZDRAM size and a structure containing the boot arguments. BL2
 passes this information to the EL3 software as members of the bl32\_ep\_info
 struct, where bl32\_ep\_info is part of bl31\_params\_t (passed by BL2 in X0)
 
-Example:
---------
+Example
+~~~~~~~
 
 ::
 
diff --git a/docs/components/spd/trusty-dispatcher.rst b/docs/components/spd/trusty-dispatcher.rst
index be085705..a3cb8295 100644
--- a/docs/components/spd/trusty-dispatcher.rst
+++ b/docs/components/spd/trusty-dispatcher.rst
@@ -9,7 +9,7 @@ Open Source Project (AOSP) webpage for Trusty hosted at
 https://source.android.com/security/trusty
 
 Boot parameters
-===============
+---------------
 
 Custom boot parameters can be passed to Trusty by providing a platform
 specific function:
@@ -26,7 +26,7 @@ can be set to a platform specific parameter block, and ``args->arg2``
 should then be set to the size of that block.
 
 Supported platforms
-===================
+-------------------
 
 Out of all the platforms supported by Trusted Firmware-A, Trusty is only
 verified and supported by NVIDIA's Tegra SoCs.
diff --git a/docs/components/xlat-tables-lib-v2-design.rst b/docs/components/xlat-tables-lib-v2-design.rst
index d55f010a..786dd3bc 100644
--- a/docs/components/xlat-tables-lib-v2-design.rst
+++ b/docs/components/xlat-tables-lib-v2-design.rst
@@ -1,12 +1,6 @@
-Translation Tables Library Design
+Translation (XLAT) Tables Library
 =================================
 
-
-
-
-.. contents::
-
-
 This document describes the design of the translation tables library (version 2)
 used by Trusted Firmware-A (TF-A). This library provides APIs to create page
 tables based on a description of the memory layout, as well as setting up system
@@ -424,4 +418,4 @@ mapping cannot be cached in the TLBs.
 .. _aarch32/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c
 .. _aarch64/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c
 .. _Porting Guide: ../getting_started/porting-guide.rst
-.. |Alignment Example| image:: ../diagrams/xlat_align.png?raw=true
+.. |Alignment Example| image:: ../resources/diagrams/xlat_align.png