Merge changes from topic "pb/sphinx-doc" into integration

* changes: doc: Use proper note and warning annotations doc: Refactor contributor acknowledgements doc: Reorganise images and update links doc: Set correct syntax highlighting style doc: Add minimal glossary doc: Remove per-page contents lists doc: Make checkpatch ignore rst files doc: Format security advisory titles and headings doc: Reformat platform port documents doc: Normalise section numbering and headings doc: Reword document titles

Merge changes from topic "pb/sphinx-doc" into integration
* changes: doc: Use proper note and warning annotations doc: Refactor contributor acknowledgements doc: Reorganise images and update links doc: Set correct syntax highlighting style doc: Add minimal glossary doc: Remove per-page contents lists doc: Make checkpatch ignore rst files doc: Format security advisory titles and headings doc: Reformat platform port documents doc: Normalise section numbering and headings doc: Reword document titles
ced17112 · Sandrine Bailleux · TrustedFirmware Code Review · 1665bcd0 · e1c5026a · ced17112
Commit ced17112 authored May 23, 2019 by Sandrine Bailleux Committed by TrustedFirmware Code Review May 23, 2019
--- a/docs/design/psci-pd-tree.rst
+++ b/docs/design/psci-pd-tree.rst
-PSCI Power Domain Tree design
+PSCI Power Domain Tree Structure
-=============================
+================================
-.. contents::
--------------
 Requirements
 ------------
@@ -116,7 +109,7 @@ separately.
 This tree is defined by the platform as the array described above as follows:
-::
+.. code:: c
        #define PLAT_NUM_POWER_DOMAINS       20
        #define PLATFORM_CORE_COUNT          13
@@ -226,7 +219,7 @@ to represent leaf and non-leaf power domain nodes in the tree.
 The power domain tree is implemented as a combination of the following data
 structures.
-::
+.. code:: c
    non_cpu_pd_node_t psci_non_cpu_pd_nodes[PSCI_NUM_NON_CPU_PWR_DOMAINS];
    cpu_pd_node_t psci_cpu_pd_nodes[PLATFORM_CORE_COUNT];

--- a/docs/design/reset-design.rst
+++ b/docs/design/reset-design.rst
-Trusted Firmware-A reset design
+CPU Reset
-===============================
+=========
-.. contents::
 This document describes the high-level design of the framework to handle CPU
 resets in Trusted Firmware-A (TF-A). It also describes how the platform
@@ -28,10 +23,11 @@ configuration, some of these steps might be unnecessary. The following sections
 guide the platform integrator by indicating which build options exclude which
 steps, depending on the capability of the platform.
-Note: If BL31 is used as the TF-A entry point instead of BL1, the diagram
+.. note::
-above is still relevant, as all these operations will occur in BL31 in
+   If BL31 is used as the TF-A entry point instead of BL1, the diagram
-this case. Please refer to section 6 "Using BL31 entrypoint as the reset
+   above is still relevant, as all these operations will occur in BL31 in
-address" for more information.
+   this case. Please refer to section 6 "Using BL31 entrypoint as the reset
+   address" for more information.
 Programmable CPU reset address
 ------------------------------
@@ -159,7 +155,7 @@ This might be done by the Trusted Boot Firmware or by platform code in BL31.
 .. _Firmware Design: firmware-design.rst
 .. _User Guide: ../getting_started/user-guide.rst
-.. |Default reset code flow| image:: ../diagrams/default_reset_code.png?raw=true
+.. |Default reset code flow| image:: ../resources/diagrams/default_reset_code.png
-.. |Reset code flow with programmable reset address| image:: ../diagrams/reset_code_no_boot_type_check.png?raw=true
+.. |Reset code flow with programmable reset address| image:: ../resources/diagrams/reset_code_no_boot_type_check.png
-.. |Reset code flow with single CPU released out of reset| image:: ../diagrams/reset_code_no_cpu_check.png?raw=true
+.. |Reset code flow with single CPU released out of reset| image:: ../resources/diagrams/reset_code_no_cpu_check.png
-.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: ../diagrams/reset_code_no_checks.png?raw=true
+.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: ../resources/diagrams/reset_code_no_checks.png
--- a/docs/design/trusted-board-boot.rst
+++ b/docs/design/trusted-board-boot.rst
-Trusted Board Boot Design Guide
+Trusted Board Boot
-===============================
+==================
-.. contents::
 The Trusted Board Boot (TBB) feature prevents malicious firmware from running on
 the platform by authenticating all firmware images up to and including the
@@ -146,8 +141,9 @@ if any of the steps fail.
   compared with the hash of the ROTPK read from the trusted root-key storage
   registers. If they match, the BL2 hash is read from the certificate.
-   Note: the matching operation is platform specific and is currently
+   .. note::
-   unimplemented on the Arm development platforms.
+      The matching operation is platform specific and is currently
+      unimplemented on the Arm development platforms.
 -  BL1 loads the BL2 image. Its hash is calculated and compared with the hash
   read from the certificate. Control is transferred to the BL2 image if all

--- a/docs/getting_started/image-terminology.rst
+++ b/docs/getting_started/image-terminology.rst
 Image Terminology
 =================
-.. section-numbering::
-    :suffix: .
-.. contents::
 This page contains the current name, abbreviated name and purpose of the various
 images referred to in the Trusted Firmware project.

--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
-Trusted Firmware-A Porting Guide
+Porting Guide
-================================
+=============
-.. contents::
 Introduction
 ------------
@@ -335,7 +331,9 @@ must also be defined:
   SCP_BL2U image identifier, used by BL1 to fetch an image descriptor
   corresponding to SCP_BL2U.
-   NOTE: TF-A does not provide source code for this image.
+   .. note::
+      TF-A does not provide source code for this image.
 If the Non-Secure Firmware Updater ROM, NS_BL1U is used, the following must
 also be defined:
@@ -344,7 +342,9 @@ also be defined:
   Defines the base address in non-secure ROM where NS_BL1U executes.
   Must be aligned on a page-size boundary.
-   NOTE: TF-A does not provide source code for this image.
+   .. note::
+      TF-A does not provide source code for this image.
 -  **#define : NS_BL1U_IMAGE_ID**
@@ -358,7 +358,9 @@ be defined:
   Defines the base address in non-secure memory where NS_BL2U executes.
   Must be aligned on a page-size boundary.
-   NOTE: TF-A does not provide source code for this image.
+   .. note::
+      TF-A does not provide source code for this image.
 -  **#define : NS_BL2U_IMAGE_ID**
@@ -1004,8 +1006,9 @@ situation from which it cannot recover. This function must not return,
 and must be implemented in assembly because it may be called before the C
 environment is initialized.
-Note: The address from where it was called is stored in x30 (Link Register).
+.. note::
-The default implementation simply spins.
+   The address from where it was called is stored in x30 (Link Register).
+   The default implementation simply spins.
 Function : plat_get_bl_image_load_info()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1046,9 +1049,10 @@ value will weaken the protection as the attacker could easily write the right
 value as part of the attack most of the time. Therefore, it should return a
 true random number.
-Note: For the protection to be effective, the global data need to be placed at
+.. warning::
-a lower address than the stack bases. Failure to do so would allow an attacker
+   For the protection to be effective, the global data need to be placed at
-to overwrite the canary as part of the stack buffer overflow attack.
+   a lower address than the stack bases. Failure to do so would allow an
+   attacker to overwrite the canary as part of the stack buffer overflow attack.
 Function : plat_flush_next_bl_params()
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1844,7 +1848,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
@@ -1854,19 +1858,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
+Normal |SDEI| events on the platform. This must have a higher value
-lower priority) than ``PLAT_SDEI_CRITICAL_PRI``.
+(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
+Critical |SDEI| events on the platform. This must have a lower value
-higher priority) than ``PLAT_SDEI_NORMAL_PRI``.
+(therefore of higher priority) than ``PLAT_SDEI_NORMAL_PRI``.
-**Note**: SDEI exception priorities must be the lowest among Secure priorities.
+**Note**: |SDEI| exception priorities must be the lowest among Secure
-Among the SDEI exceptions, Critical SDEI priority must be higher than Normal
+priorities. Among the |SDEI| exceptions, Critical |SDEI| priority must
-SDEI priority.
+be higher than Normal |SDEI| priority.
 Functions
 .........
@@ -1880,10 +1884,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
+event registration and *Complete and Resume* |SDEI| calls. The function
-argument, which is the address of the handler the SDEI client requested to
+takes one argument, which is the address of the handler the |SDEI| client
-register. The function must return ``0`` for successful validation, or ``-1``
+requested to register. The function must return ``0`` for successful validation,
-upon failure.
+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
@@ -1898,11 +1902,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.
+|SDEI| specification requires that a PE comes out of reset with the events
-The client therefore is expected to call ``PE_UNMASK`` to unmask SDEI events on
+masked. The client therefore is expected to call ``PE_UNMASK`` to unmask
-the PE. No SDEI events can be dispatched until such time.
+|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.
@@ -2567,10 +2572,12 @@ makefiles in order to benefit from them. By default, they will cause the crash
 output to be routed over the normal console infrastructure and get printed on
 consoles configured to output in crash state. ``console_set_scope()`` can be
 used to control whether a console is used for crash output.
-NOTE: Platforms are responsible for making sure that they only mark consoles for
-use in the crash scope that are able to support this, i.e. that are written in
+.. note::
-assembly and conform with the register clobber rules for putc() (x0-x2, x16-x17)
+   Platforms are responsible for making sure that they only mark consoles for
-and flush() (x0-x3, x16-x17) crash callbacks.
+   use in the crash scope that are able to support this, i.e. that are written
+   in assembly and conform with the register clobber rules for putc()
+   (x0-x2, x16-x17) and flush() (x0-x3, x16-x17) crash callbacks.
 In some cases (such as debugging very early crashes that happen before the
 normal boot console can be set up), platforms may want to control crash output

--- a/docs/getting_started/psci-lib-integration-guide.rst
+++ b/docs/getting_started/psci-lib-integration-guide.rst
 PSCI Library Integration guide for Armv8-A AArch32 systems
 ==========================================================
-.. contents::
 This document describes the PSCI library interface with a focus on how to
 integrate with a suitable Trusted OS for an Armv8-A AArch32 system. The PSCI
 Library implements the PSCI Standard as described in `PSCI spec`_ and is meant

--- a/docs/getting_started/rt-svc-writers-guide.rst
+++ b/docs/getting_started/rt-svc-writers-guide.rst
-Trusted Firmware-A EL3 runtime service writer's guide
+EL3 Runtime Service Writer's Guide
 =====================================================
-.. contents::
 Introduction
 ------------
@@ -96,7 +92,7 @@ A runtime service is registered using the ``DECLARE_RT_SVC()`` macro, specifying
 the name of the service, the range of OENs covered, the type of service and
 initialization and call handler functions.
-::
+.. code:: c
    #define DECLARE_RT_SVC(_name, _start, _end, _type, _setup, _smch)
@@ -264,8 +260,9 @@ The ``cookie`` parameter to the handler is reserved for future use and can be
 ignored. The ``handle`` is returned by the SMC handler - completion of the
 handler function must always be via one of the ``SMC_RETn()`` macros.
-NOTE: The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow
+.. note::
-all of the above requirements yet.
+   The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow
+   all of the above requirements yet.
 Services that contain multiple sub-services
 -------------------------------------------

--- a/docs/getting_started/user-guide.rst
+++ b/docs/getting_started/user-guide.rst
-Trusted Firmware-A User Guide
+User Guide
-=============================
+==========
-.. contents::
 This document describes how to build Trusted Firmware-A (TF-A) and run it with a
 tested set of other software components using defined configurations on the Juno
@@ -49,7 +44,7 @@ Tools
 Install the required packages to build TF-A with the following command:
-::
+.. code:: shell
    sudo apt-get install device-tree-compiler build-essential gcc make git libssl-dev
@@ -101,9 +96,10 @@ targets which both utilise the `checkpatch.pl` script that ships with the Linux
 source tree. The project also defines certain *checkpatch* options in the
 ``.checkpatch.conf`` file in the top-level directory.
-**Note:** Checkpatch errors will gate upstream merging of pull requests.
+.. note::
-Checkpatch warnings will not gate merging but should be reviewed and fixed if
+   Checkpatch errors will gate upstream merging of pull requests.
-possible.
+   Checkpatch warnings will not gate merging but should be reviewed and fixed if
+   possible.
 To check the entire source tree, you must first download copies of
 ``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available
@@ -111,14 +107,14 @@ in the `Linux master tree`_ *scripts* directory, then set the ``CHECKPATCH``
 environment variable to point to ``checkpatch.pl`` (with the other 2 files in
 the same directory) and build the `checkcodebase` target:
-::
+.. code:: shell
    make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase
 To just check the style on the files that differ between your local branch and
 the remote master, use:
-::
+.. code:: shell
    make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch
@@ -134,13 +130,13 @@ Building TF-A
   For AArch64:
-   ::
+   .. code:: shell
       export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
   For AArch32:
-   ::
+   .. code:: shell
       export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
@@ -158,7 +154,7 @@ Building TF-A
   For AArch64 using Arm Compiler 6:
-   ::
+   .. code:: shell
       export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
       make CC=<path-to-armclang>/bin/armclang PLAT=<platform> all
@@ -169,7 +165,7 @@ Building TF-A
   For AArch64 using clang:
-   ::
+   .. code:: shell
       export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
       make CC=<path-to-clang>/bin/clang PLAT=<platform> all
@@ -178,13 +174,13 @@ Building TF-A
   For AArch64:
-   ::
+   .. code:: shell
       make PLAT=<platform> all
   For AArch32:
-   ::
+   .. code:: shell
       make PLAT=<platform> ARCH=aarch32 AARCH32_SP=sp_min all
@@ -227,7 +223,7 @@ Building TF-A
 -  Build products for a specific build variant can be removed using:
-   ::
+   .. code:: shell
       make DEBUG=<D> PLAT=<platform> clean
@@ -235,7 +231,7 @@ Building TF-A
   The build tree can be removed completely using:
-   ::
+   .. code:: shell
       make realclean
@@ -723,8 +719,9 @@ Common build options
   of certificates in the FIP and FWU_FIP depends upon the value of the
   ``GENERATE_COT`` option.
-   Note: This option depends on ``CREATE_KEYS`` to be enabled. If the keys
+   .. warning::
-   already exist in disk, they will be overwritten without further notice.
+      This option depends on ``CREATE_KEYS`` to be enabled. If the keys
+      already exist in disk, they will be overwritten without further notice.
 -  ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It
   specifies the file that contains the Trusted World private key in PEM
@@ -744,8 +741,9 @@ Common build options
   interrupts to TSP allowing it to save its context and hand over
   synchronously to EL3 via an SMC.
-   Note: when ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT``
+   .. note::
-   must also be set to ``1``.
+      When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT``
+      must also be set to ``1``.
 -  ``USE_ARM_LINK``: This flag determines whether to enable support for ARM
   linker. When the ``LINKER`` build variable points to the armlink linker,
@@ -940,7 +938,7 @@ Debugging options
 To compile a debug version and make the build more verbose use
-::
+.. code:: shell
    make PLAT=<platform> DEBUG=1 V=1 all
@@ -953,14 +951,15 @@ version to 2 is recommended for DS-5 versions older than 5.16.
 When debugging logic problems it might also be useful to disable all compiler
 optimizations by using ``-O0``.
-NOTE: Using ``-O0`` could cause output images to be larger and base addresses
+.. warning::
-might need to be recalculated (see the **Memory layout on Arm development
+   Using ``-O0`` could cause output images to be larger and base addresses
-platforms** section in the `Firmware Design`_).
+   might need to be recalculated (see the **Memory layout on Arm development
+   platforms** section in the `Firmware Design`_).
 Extra debug options can be passed to the build system by setting ``CFLAGS`` or
 ``LDFLAGS``:
-.. code:: makefile
+.. code:: shell
    CFLAGS='-O0 -gdwarf-2'                                     \
    make PLAT=<platform> DEBUG=1 V=1 all
@@ -1001,7 +1000,7 @@ must be recompiled as well. For more information on SPs and SPDs, see the
 First clean the TF-A build directory to get rid of any previous BL31 binary.
 Then to build the TSP image use:
-::
+.. code:: shell
    make PLAT=<platform> SPD=tspd all
@@ -1029,13 +1028,13 @@ and BL33 images.
 For AArch64:
-::
+.. code:: shell
    make PLAT=fvp BL33=<path-to>/bl33.bin fip
 For AArch32:
-::
+.. code:: shell
    make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip
@@ -1051,13 +1050,13 @@ steps:
 It is recommended to remove old artifacts before building the tool:
-::
+.. code:: shell
    make -C tools/fiptool clean
 Build the tool:
-::
+.. code:: shell
    make [DEBUG=1] [V=1] fiptool
@@ -1072,7 +1071,7 @@ options.
 Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31:
-::
+.. code:: shell
    ./tools/fiptool/fiptool create \
        --tb-fw build/<platform>/<build-type>/bl2.bin \
@@ -1081,13 +1080,13 @@ Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31:
 Example 2: view the contents of an existing Firmware package:
-::
+.. code:: shell
    ./tools/fiptool/fiptool info <path-to>/fip.bin
 Example 3: update the entries of an existing Firmware package:
-::
+.. code:: shell
    # Change the BL2 from Debug to Release version
    ./tools/fiptool/fiptool update \
@@ -1096,14 +1095,14 @@ Example 3: update the entries of an existing Firmware package:
 Example 4: unpack all entries from an existing Firmware package:
-::
+.. code:: shell
    # Images will be unpacked to the working directory
    ./tools/fiptool/fiptool unpack <path-to>/fip.bin
 Example 5: remove an entry from an existing Firmware package:
-::
+.. code:: shell
    ./tools/fiptool/fiptool remove \
        --tb-fw build/<platform>/debug/fip.bin
@@ -1173,7 +1172,7 @@ images with support for these features:
   Example of command line using RSA development keys:
-   ::
+   .. code:: shell
       MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
       make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1        \
@@ -1210,12 +1209,14 @@ images with support for these features:
       NS_BL2U=<path-to>/<ns_bl2u_image>                               \
       all fip fwu_fip
-   Note: The BL2U image will be built by default and added to the FWU_FIP.
+   .. note::
-   The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
+      The BL2U image will be built by default and added to the FWU_FIP.
-   to the command line above.
+      The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
+      to the command line above.
-   Note: Building and installing the non-secure and SCP FWU images (NS_BL1U,
+   .. note::
-   NS_BL2U and SCP_BL2U) is outside the scope of this document.
+      Building and installing the non-secure and SCP FWU images (NS_BL1U,
+      NS_BL2U and SCP_BL2U) is outside the scope of this document.
   The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries.
   Both the FIP and FWU_FIP will include the certificates corresponding to the
@@ -1230,7 +1231,7 @@ The ``cert_create`` tool is built as part of the TF-A build process when the
 previous section), but it can also be built separately with the following
 command:
-::
+.. code:: shell
    make PLAT=<platform> [DEBUG=1] [V=1] certtool
@@ -1239,14 +1240,14 @@ For platforms that require their own IDs in certificate files, the generic
 platform must define its IDs within a ``platform_oid.h`` header file for the
 build to succeed.
-::
+.. code:: shell
    make PLAT=<platform> USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool
 ``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
 verbose. The following command should be used to obtain help about the tool:
-::
+.. code:: shell
    ./tools/cert_create/cert_create -h
@@ -1257,25 +1258,30 @@ This section provides Juno and FVP specific instructions to build Trusted
 Firmware, obtain the additional required firmware, and pack it all together in
 a single FIP binary. It assumes that a `Linaro Release`_ has been installed.
-Note: Pre-built binaries for AArch32 are available from Linaro Release 16.12
+.. note::
-onwards. Before that release, pre-built binaries are only available for AArch64.
+   Pre-built binaries for AArch32 are available from Linaro Release 16.12
+   onwards. Before that release, pre-built binaries are only available for
+   AArch64.
-Note: Follow the full instructions for one platform before switching to a
+.. warning::
-different one. Mixing instructions for different platforms may result in
+   Follow the full instructions for one platform before switching to a
-corrupted binaries.
+   different one. Mixing instructions for different platforms may result in
+   corrupted binaries.
-Note: The uboot image downloaded by the Linaro workspace script does not always
+.. warning::
-match the uboot image packaged as BL33 in the corresponding fip file. It is
+   The uboot image downloaded by the Linaro workspace script does not always
-recommended to use the version that is packaged in the fip file using the
+   match the uboot image packaged as BL33 in the corresponding fip file. It is
-instructions below.
+   recommended to use the version that is packaged in the fip file using the
+   instructions below.
-Note: For the FVP, the kernel FDT is packaged in FIP during build and loaded
+.. note::
-by the firmware at runtime. See `Obtaining the Flattened Device Trees`_
+   For the FVP, the kernel FDT is packaged in FIP during build and loaded
-section for more info on selecting the right FDT to use.
+   by the firmware at runtime. See `Obtaining the Flattened Device Trees`_
+   section for more info on selecting the right FDT to use.
 #. Clean the working directory
-   ::
+   .. code:: shell
       make realclean
@@ -1284,7 +1290,7 @@ section for more info on selecting the right FDT to use.
   Use the fiptool to extract the SCP_BL2 and BL33 images from the FIP
   package included in the Linaro release:
-   ::
+   .. code:: shell
       # Build the fiptool
       make [DEBUG=1] [V=1] fiptool
@@ -1296,16 +1302,18 @@ section for more info on selecting the right FDT to use.
   current working directory. The SCP_BL2 image corresponds to
   ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``.
-   Note: The fiptool will complain if the images to be unpacked already
+   .. note::
-   exist in the current directory. If that is the case, either delete those
+      The fiptool will complain if the images to be unpacked already
-   files or use the ``--force`` option to overwrite.
+      exist in the current directory. If that is the case, either delete those
+      files or use the ``--force`` option to overwrite.
-   Note: For AArch32, the instructions below assume that nt-fw.bin is a normal
+   .. note::
-   world boot loader that supports AArch32.
+      For AArch32, the instructions below assume that nt-fw.bin is a
+      normal world boot loader that supports AArch32.
 #. Build TF-A images and create a new FIP for FVP
-   ::
+   .. code:: shell
       # AArch64
       make PLAT=fvp BL33=nt-fw.bin all fip
@@ -1320,7 +1328,7 @@ section for more info on selecting the right FDT to use.
   Building for AArch64 on Juno simply requires the addition of ``SCP_BL2``
   as a build parameter.
-   ::
+   .. code:: shell
       make PLAT=juno BL33=nt-fw.bin SCP_BL2=scp-fw.bin all fip
@@ -1333,13 +1341,13 @@ section for more info on selecting the right FDT to use.
   -  Before building BL32, the environment variable ``CROSS_COMPILE`` must point
      to the AArch32 Linaro cross compiler.
-      ::
+      .. code:: shell
          export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf-
   -  Build BL32 in AArch32.
-      ::
+      .. code:: shell
          make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \
          RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32
@@ -1354,14 +1362,14 @@ section for more info on selecting the right FDT to use.
   -  Before building BL1 and BL2, the environment variable ``CROSS_COMPILE``
      must point to the AArch64 Linaro cross compiler.
-      ::
+      .. code:: shell
          export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu-
   -  The following parameters should be used to build BL1 and BL2 in AArch64
      and point to the BL32 file.
-      ::
+      .. code:: shell
          make ARCH=aarch64 PLAT=juno JUNO_AARCH32_EL3_RUNTIME=1 \
          BL33=nt-fw.bin SCP_BL2=scp-fw.bin \
@@ -1499,7 +1507,7 @@ clear the mailbox at start-up.
 One way to do that is to create an 8-byte file containing all zero bytes using
 the following command:
-::
+.. code:: shell
    dd if=/dev/zero of=mailbox.dat bs=1 count=8
@@ -1569,7 +1577,7 @@ used when compiling TF-A. For example, the following command will create a FIP
 without a BL33 and prepare to jump to a BL33 image loaded at address
 0x80000000:
-::
+.. code:: shell
    make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip
@@ -1584,7 +1592,7 @@ memory (like in FVP).
 For example, if the kernel is loaded at ``0x80080000`` and the DTB is loaded at
 address ``0x82000000``, the firmware can be built like this:
-::
+.. code:: shell
    CROSS_COMPILE=aarch64-linux-gnu-  \
    make PLAT=fvp DEBUG=1             \
@@ -1632,7 +1640,7 @@ offset in ``INITRD_START`` has to be removed.
 And the FVP binary can be run with the following command:
-::
+.. code:: shell
    <path-to>/FVP_Base_AEMv8A-AEMv8A                            \
    -C pctl.startup=0.0.0.0                                     \
@@ -1667,7 +1675,8 @@ The latest version of the AArch64 build of TF-A has been tested on the following
 Arm FVPs without shifted affinities, and that do not support threaded CPU cores
 (64-bit host machine only).
-The FVP models used are Version 11.6 Build 45, unless otherwise stated.
+.. note::
+   The FVP models used are Version 11.6 Build 45, unless otherwise stated.
 -  ``FVP_Base_AEMv8A-AEMv8A``
 -  ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502``
@@ -1704,30 +1713,36 @@ Arm FVPs without shifted affinities, and that do not support threaded CPU cores
 -  ``FVP_Base_AEMv8A-AEMv8A``
 -  ``FVP_Base_Cortex-A32x4``
-NOTE: The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which
+.. note::
-is not compatible with legacy GIC configurations. Therefore this FVP does not
+   The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which
-support these legacy GIC configurations.
+   is not compatible with legacy GIC configurations. Therefore this FVP does not
+   support these legacy GIC configurations.
-NOTE: The build numbers quoted above are those reported by launching the FVP
-with the ``--version`` parameter.
+.. note::
+   The build numbers quoted above are those reported by launching the FVP
-NOTE: Linaro provides a ramdisk image in prebuilt FVP configurations and full
+   with the ``--version`` parameter.
-file systems that can be downloaded separately. To run an FVP with a virtio
-file system image an additional FVP configuration option
+.. note::
-``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
+   Linaro provides a ramdisk image in prebuilt FVP configurations and full
-used.
+   file systems that can be downloaded separately. To run an FVP with a virtio
+   file system image an additional FVP configuration option
-NOTE: The software will not work on Version 1.0 of the Foundation FVP.
+   ``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
-The commands below would report an ``unhandled argument`` error in this case.
+   used.
-NOTE: FVPs can be launched with ``--cadi-server`` option such that a
+.. note::
-CADI-compliant debugger (for example, Arm DS-5) can connect to and control its
+   The software will not work on Version 1.0 of the Foundation FVP.
-execution.
+   The commands below would report an ``unhandled argument`` error in this case.
-NOTE: Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202
+.. note::
-the internal synchronisation timings changed compared to older versions of the
+   FVPs can be launched with ``--cadi-server`` option such that a
-models. The models can be launched with ``-Q 100`` option if they are required
+   CADI-compliant debugger (for example, Arm DS-5) can connect to and control
-to match the run time characteristics of the older versions.
+   its execution.
+.. warning::
+   Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202
+   the internal synchronisation timings changed compared to older versions of
+   the models. The models can be launched with ``-Q 100`` option if they are
+   required to match the run time characteristics of the older versions.
 The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be
 downloaded for free from `Arm's website`_.
@@ -1748,8 +1763,9 @@ be found in the TF-A source directory under ``fdts/``. The Foundation FVP has
 a subset of the Base FVP components. For example, the Foundation FVP lacks
 CLCD and MMC support, and has only one CPU cluster.
-Note: It is not recommended to use the FDTs built along the kernel because not
+.. note::
-all FDTs are available from there.
+   It is not recommended to use the FDTs built along the kernel because not
+   all FDTs are available from there.
 The dynamic configuration capability is enabled in the firmware for FVPs.
 This means that the firmware can authenticate and load the FDT if present in
@@ -1806,7 +1822,7 @@ Running on the Foundation FVP with reset to BL1 entrypoint
 The following ``Foundation_Platform`` parameters should be used to boot Linux with
 4 CPUs using the AArch64 build of TF-A.
-::
+.. code:: shell
    <path-to>/Foundation_Platform                   \
    --cores=4                                       \
@@ -1842,7 +1858,7 @@ Running on the AEMv8 Base FVP with reset to BL1 entrypoint
 The following ``FVP_Base_RevC-2xAEMv8A`` parameters should be used to boot Linux
 with 8 CPUs using the AArch64 build of TF-A.
-::
+.. code:: shell
    <path-to>/FVP_Base_RevC-2xAEMv8A                            \
    -C pctl.startup=0.0.0.0                                     \
@@ -1856,8 +1872,9 @@ with 8 CPUs using the AArch64 build of TF-A.
    --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
    --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-Note: The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a
+.. note::
-specific DTS for all the CPUs to be loaded.
+   The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires
+   a specific DTS for all the CPUs to be loaded.
 Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1865,7 +1882,7 @@ Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint
 The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
 with 8 CPUs using the AArch32 build of TF-A.
-::
+.. code:: shell
    <path-to>/FVP_Base_AEMv8A-AEMv8A                            \
    -C pctl.startup=0.0.0.0                                     \
@@ -1893,7 +1910,7 @@ Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint
 The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
 boot Linux with 8 CPUs using the AArch64 build of TF-A.
-::
+.. code:: shell
    <path-to>/FVP_Base_Cortex-A57x4-A53x4                       \
    -C pctl.startup=0.0.0.0                                     \
@@ -1911,7 +1928,7 @@ Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint
 The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
 boot Linux with 4 CPUs using the AArch32 build of TF-A.
-::
+.. code:: shell
    <path-to>/FVP_Base_Cortex-A32x4                             \
    -C pctl.startup=0.0.0.0                                     \
@@ -1929,7 +1946,7 @@ Running on the AEMv8 Base FVP with reset to BL31 entrypoint
 The following ``FVP_Base_RevC-2xAEMv8A`` parameters should be used to boot Linux
 with 8 CPUs using the AArch64 build of TF-A.
-::
+.. code:: shell
    <path-to>/FVP_Base_RevC-2xAEMv8A                             \
    -C pctl.startup=0.0.0.0                                      \
@@ -1984,7 +2001,7 @@ Running on the AEMv8 Base FVP (AArch32) with reset to SP_MIN entrypoint
 The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux
 with 8 CPUs using the AArch32 build of TF-A.
-::
+.. code:: shell
    <path-to>/FVP_Base_AEMv8A-AEMv8A                             \
    -C pctl.startup=0.0.0.0                                      \
@@ -2015,8 +2032,9 @@ with 8 CPUs using the AArch32 build of TF-A.
    --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000  \
    --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
-Note: The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``.
+.. note::
-It should match the address programmed into the RVBAR register as well.
+   The load address of ``<bl32-binary>`` depends on the value ``BL32_BASE``.
+   It should match the address programmed into the RVBAR register as well.
 Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2024,7 +2042,7 @@ Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint
 The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to
 boot Linux with 8 CPUs using the AArch64 build of TF-A.
-::
+.. code:: shell
    <path-to>/FVP_Base_Cortex-A57x4-A53x4                        \
    -C pctl.startup=0.0.0.0                                      \
@@ -2052,7 +2070,7 @@ Running on the Cortex-A32 Base FVP (AArch32) with reset to SP_MIN entrypoint
 The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to
 boot Linux with 4 CPUs using the AArch32 build of TF-A.
-::
+.. code:: shell
    <path-to>/FVP_Base_Cortex-A32x4                             \
    -C pctl.startup=0.0.0.0                                     \
@@ -2101,7 +2119,7 @@ The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend
 to RAM. For more details refer to section 5.16 of `PSCI`_. To test system suspend
 on Juno, at the linux shell prompt, issue the following command:
-::
+.. code:: shell
    echo +10 > /sys/class/rtc/rtc0/wakealarm
    echo -n mem > /sys/power/state

--- a/docs/global_substitutions.txt
+++ b/docs/global_substitutions.txt
+.. |AArch32| replace:: :term:`AArch32`
+.. |AArch64| replace:: :term:`AArch64`
+.. |API| replace:: :term:`API`
+.. |CoT| replace:: :term:`CoT`
+.. |COT| replace:: :term:`COT`
+.. |CSS| replace:: :term:`CSS`
+.. |CVE| replace:: :term:`CVE`
+.. |DS-5| replace:: :term:`DS-5`
+.. |DT| replace:: :term:`DT`
+.. |EL| replace:: :term:`EL`
+.. |EHF| replace:: :term:`EHF`
+.. |FDT| replace:: :term:`FDT`
+.. |FIP| replace:: :term:`FIP`
+.. |FVP| replace:: :term:`FVP`
+.. |FWU| replace:: :term:`FWU`
+.. |GIC| replace:: :term:`GIC`
+.. |ISA| replace:: :term:`ISA`
+.. |Linaro| replace:: :term:`Linaro`
+.. |MMU| replace:: :term:`MMU`
+.. |MPAM| replace:: :term:`MPAM`
+.. |MPIDR| replace:: :term:`MPIDR`
+.. |OEN| replace:: :term:`OEN`
+.. |OP-TEE| replace:: :term:`OP-TEE`
+.. |OTE| replace:: :term:`OTE`
+.. |PDD| replace:: :term:`PDD`
+.. |PMF| replace:: :term:`PMF`
+.. |PSCI| replace:: :term:`PSCI`
+.. |RAS| replace:: :term:`RAS`
+.. |ROT| replace:: :term:`ROT`
+.. |SCMI| replace:: :term:`SCMI`
+.. |SCP| replace:: :term:`SCP`
+.. |SDEI| replace:: :term:`SDEI`
+.. |SDS| replace:: :term:`SDS`
+.. |SEA| replace:: :term:`SEA`
+.. |SiP| replace:: :term:`SiP`
+.. |SIP| replace:: :term:`SIP`
+.. |SMC| replace:: :term:`SMC`
+.. |SMCCC| replace:: :term:`SMCCC`
+.. |SoC| replace:: :term:`SoC`
+.. |SP| replace:: :term:`SP`
+.. |SPD| replace:: :term:`SPD`
+.. |SPM| replace:: :term:`SPM`
+.. |SVE| replace:: :term:`SVE`
+.. |TBB| replace:: :term:`TBB`
+.. |TBBR| replace:: :term:`TBBR`
+.. |TEE| replace:: :term:`TEE`
+.. |TF-A| replace:: :term:`TF-A`
+.. |TF-M| replace:: :term:`TF-M`
+.. |TLB| replace:: :term:`TLB`
+.. |TLK| replace:: :term:`TLK`
+.. |TSP| replace:: :term:`TSP`
+.. |TZC| replace:: :term:`TZC`
+.. |UEFI| replace:: :term:`UEFI`
+.. |WDOG| replace:: :term:`WDOG`
+.. |XLAT| replace:: :term:`XLAT`
\ No newline at end of file
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
+Glossary
+========
+This glossary provides definitions for terms and abbreviations used in the TF-A
+documentation.
+You can find additional definitions in the `Arm Glossary`_.
+.. glossary::
+   :sorted:
+   AArch32
+      32-bit execution state of the ARMv8 ISA
+   AArch64
+      64-bit execution state of the ARMv8 ISA
+   API
+      Application Programming Interface
+   CoT
+   COT
+      Chain of Trust
+   CSS
+      Compute Sub-System
+   CVE
+      Common Vulnerabilities and Exposures. A CVE document is commonly used to
+      describe a publicly-known security vulnerability.
+   DS-5
+      Arm Development Studio 5
+   DT
+      Device Tree
+   EL
+      Exception Level
+   EHF
+      Exception Handling Framework
+   FDT
+      Flattened Device Tree
+   FIP
+      Firmware Image Package
+   FVP
+      Fixed Virtual Platform
+   FWU
+      FirmWare Update
+   GIC
+      Generic Interrupt Controller
+   ISA
+      Instruction Set Architecture
+   Linaro
+      A collaborative engineering organization consolidating
+      and optimizing open source software and tools for the Arm architecture.
+   MMU
+      Memory Management Unit
+   MPAM
+      Memory Partitioning And Monitoring. An optional Armv8.4 extension.
+   MPIDR
+      Multiprocessor Affinity Register
+   OEN
+      Owning Entity Number
+   OP-TEE
+      Open Portable Trusted Execution Environment. An example of a :term:`TEE`
+   OTE
+      Open-source Trusted Execution Environment
+   PDD
+      Platform Design Document
+   PMF
+      Performance Measurement Framework
+   PSCI
+      Power State Coordination Interface
+   RAS
+      Reliability, Availability, and Serviceability extensions. A mandatory
+      extension for the Armv8.2 architecture and later. An optional extension to
+      the base Armv8 architecture.
+   ROT
+      Root of Trust
+   SCMI
+      System Control and Management Interface
+   SCP
+      System Control Processor
+   SDEI
+      Software Delegated Exception Interface
+   SDS
+      Shared Data Storage
+   SEA
+      Synchronous External Abort
+   SiP
+   SIP
+      Silicon Provider
+   SMC
+      Secure Monitor Call
+   SMCCC
+      :term:`SMC` Calling Convention
+   SoC
+      System on Chip
+   SP
+      Secure Partition
+   SPD
+      Secure Payload Dispatcher
+   SPM
+      Secure Partition Manager
+   SVE
+      Scalable Vector Extension
+   TBB
+      Trusted Board Boot
+   TBBR
+      Trusted Board Boot Requirements
+   TEE
+      Trusted Execution Environment
+   TF-A
+      Trusted Firmware-A
+   TF-M
+      Trusted Firmware-M
+   TLB
+      Translation Lookaside Buffer
+   TLK
+      Trusted Little Kernel. A Trusted OS from NVIDIA.
+   TSP
+      Test Secure Payload
+   TZC
+      TrustZone Controller
+   UEFI
+      Unified Extensible Firmware Interface
+   WDOG
+      Watchdog
+   XLAT
+      Translation (abbr.). For example, "XLAT table".
+.. _`Arm Glossary`: https://developer.arm.com/support/arm-glossary
\ No newline at end of file
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,7 +3,7 @@ Trusted Firmware-A Documentation
 .. toctree::
   :maxdepth: 1
-   :caption: Contents
+   :hidden:
   Home<self>
   getting_started/index
@@ -14,10 +14,14 @@ Trusted Firmware-A Documentation
   perf/index
   security_advisories/index
   change-log
-   maintainers
   acknowledgements
+   glossary
+   maintainers
   license
+.. contents:: On This Page
+    :depth: 3
 Trusted Firmware-A (TF-A) provides a reference implementation of secure world
 software for `Armv7-A and Armv8-A`_, including a `Secure Monitor`_ executing
 at Exception Level 3 (EL3). It implements various Arm interface standards,
@@ -99,7 +103,7 @@ Functionality
      Secure-EL0, which can be used to implement simple management and
      security services.
-   -  An SDEI dispatcher to route interrupt-based SDEI events.
+   -  An |SDEI| dispatcher to route interrupt-based |SDEI| events.
   -  An Exception Handling Framework (EHF) that allows dispatching of EL3
      interrupts to their registered handlers, to facilitate firmware-first
@@ -149,7 +153,8 @@ The latest version of the AArch64 build of TF-A has been tested on the following
 Arm FVPs without shifted affinities, and that do not support threaded CPU cores
 (64-bit host machine only).
-The FVP models used are Version 11.5 Build 33, unless otherwise stated.
+.. note::
+   The FVP models used are Version 11.5 Build 33, unless otherwise stated.
 -  ``FVP_Base_AEMv8A-AEMv8A``
 -  ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502``
@@ -186,7 +191,8 @@ Arm FVPs without shifted affinities, and that do not support threaded CPU cores
 -  ``FVP_Base_AEMv8A-AEMv8A``
 -  ``FVP_Base_Cortex-A32x4``
-NOTE: The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities.
+.. note::
+   The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities.
 The Foundation FVP can be downloaded free of charge. The Base FVPs can be
 licensed from Arm. See the `Arm FVP website`_.

--- a/docs/maintainers.rst
+++ b/docs/maintainers.rst
-Trusted Firmware-A maintainers
+Maintainers
-==============================
+===========
 Trusted Firmware-A (TF-A) is an Arm maintained project. All contributions are
 ultimately merged by the maintainers listed below. Technical ownership of some

--- a/docs/perf/psci-performance-juno.rst
+++ b/docs/perf/psci-performance-juno.rst
@@ -28,7 +28,7 @@ levels 0, 1 and 2 respectively. It does not support any retention states.
 We used the upstream `TF master as of 31/01/2017`_, building the platform using
 the ``ENABLE_RUNTIME_INSTRUMENTATION`` option:
-::
+.. code:: shell
    make PLAT=juno ENABLE_RUNTIME_INSTRUMENTATION=1 \
        SCP_BL2=<path/to/scp-fw.bin>                \

--- a/docs/plat/allwinner.rst
+++ b/docs/plat/allwinner.rst
-Trusted Firmware-A for Allwinner ARMv8 SoCs
+Allwinner ARMv8 SoCs
-===========================================
+====================
 Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Allwinner
 SoCs with ARMv8 cores. Only BL31 is used to provide proper EL3 setup and
@@ -24,24 +24,23 @@ See the respective `U-Boot documentation`_ for more details.
 To build for machines with an A64 or H5 SoC:
-::
+.. code:: shell
    make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sun50i_a64 DEBUG=1 bl31
 To build for machines with an H6 SoC:
-::
+.. code:: shell
    make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sun50i_h6 DEBUG=1 bl31
 .. _U-Boot documentation: http://git.denx.de/?p=u-boot.git;f=board/sunxi/README.sunxi64;hb=HEAD
 Trusted OS dispatcher
-=====================
+---------------------
 One can boot Trusted OS(OP-TEE OS, bl32 image) along side bl31 image on Allwinner A64.
 In order to include the 'opteed' dispatcher in the image, pass 'SPD=opteed' on the command line
 while compiling the bl31 image and make sure the loader (SPL) loads the Trusted OS binary to
 the beginning of DRAM (0x40000000).
--- a/docs/plat/fvp_ve.rst
+++ b/docs/plat/fvp_ve.rst
-Description
+Arm Versatile Express
-===========
+=====================
 Versatile Express (VE) family development platform provides an
 ultra fast environment for prototyping arm-v7 System-on-Chip designs.
@@ -9,21 +9,21 @@ and Cortex-A7 VE FVP's. This platform is tested on and only expected to work
 with single core models.
 Boot Sequence
-=============
+-------------
 BL1 --> BL2 --> BL32(sp_min) --> BL33(u-boot) --> Linux kernel
 How to build
-============
+------------
 Code Locations
---------------
+~~~~~~~~~~~~~~
 -  `U-boot <https://git.linaro.org/landing-teams/working/arm/u-boot.git>`__
 -  `arm-trusted-firmware <https://github.com/ARM-software/arm-trusted-firmware>`__
 Build Procedure
---------------
+~~~~~~~~~~~~~~~
 -  Obtain arm toolchain. The software stack has been verified with linaro 6.2
   `arm-linux-gnueabihf <https://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/arm-linux-gnueabihf/>`__.
@@ -68,7 +68,7 @@ Build Procedure
      BL33=<path_to_u-boot.bin> all fip
 Run Procedure
-------------
+~~~~~~~~~~~~~
 The following model parameters should be used to boot Linux using the build of
 arm-trusted-firmware-a made using the above make commands:

--- a/docs/plat/imx8.rst
+++ b/docs/plat/imx8.rst
-Description
+NXP i.MX 8 Series
-===========
+=================
 The i.MX 8 series of applications processors is a feature- and
 performance-scalable multi-core platform that includes single-,
@@ -20,15 +20,15 @@ control for system-level resources on i.MX8. The heart of the system
 controller is a Cortex-M4 that executes system controller firmware.
 Boot Sequence
-=============
+-------------
 Bootrom --> BL31 --> BL33(u-boot) --> Linux kernel
 How to build
-============
+------------
 Build Procedure
---------------
+~~~~~~~~~~~~~~~
 -  Prepare AARCH64 toolchain.
@@ -46,7 +46,7 @@ Build Procedure
   Target_SoC should be "imx8qx" for i.MX8QX SoC.
 Deploy TF-A Images
-----------------
+~~~~~~~~~~~~~~~~~~
 TF-A binary(bl31.bin), scfw_tcm.bin and u-boot.bin are combined together
 to generate a binary file called flash.bin, the imx-mkimage tool is used

--- a/docs/plat/imx8m.rst
+++ b/docs/plat/imx8m.rst
-Description
+NXP i.MX 8M Series
-===========
+==================
 The i.MX 8M family of applications processors based on Arm Corte-A53 and Cortex-M4
 cores provide high-performance computing, power efficiency, enhanced system
@@ -7,15 +7,15 @@ reliability and embedded security needed to drive the growth of fast-growing
 edge node computing, streaming multimedia, and machine learning applications.
 Boot Sequence
-=============
+-------------
 Bootrom --> SPL --> BL31 --> BL33(u-boot) --> Linux kernel
 How to build
-============
+------------
 Build Procedure
---------------
+~~~~~~~~~~~~~~~
 -  Prepare AARCH64 toolchain.
@@ -34,7 +34,7 @@ Build Procedure
   Target_SoC should be "imx8mm" for i.MX8MM SoC.
 Deploy TF-A Images
-----------------
+~~~~~~~~~~~~~~~~~~
 TF-A binary(bl31.bin), u-boot-spl.bin u-boot-nodtb.bin and dtb are combined
 together to generate a binary file called flash.bin, the imx-mkimage tool is

--- a/docs/plat/index.rst
+++ b/docs/plat/index.rst
@@ -16,7 +16,6 @@ Platform Ports
   meson-gxl
   mt8183
   nvidia-tegra
-   poplar
   qemu
   rcar-gen3
   rockchip
@@ -26,4 +25,5 @@ Platform Ports
   synquacer
   ti-k3
   warp7
+   xilinx-versal
   xilinx-zynqmp
--- a/docs/plat/intel-stratix10.rst
+++ b/docs/plat/intel-stratix10.rst
-Description
+Intel Stratix 10 SoCFPGA
-===========
+========================
 Stratix 10 SoCFPGA is a FPGA with integrated quad-core 64-bit Arm Cortex A53 processor.
@@ -11,10 +11,10 @@ the hardware, then loads bl31 and bl33 (UEFI) into DDR and boots to bl33.
    Boot ROM --> Trusted Firmware-A --> UEFI
 How to build
-============
+------------
 Code Locations
--------------
+~~~~~~~~~~~~~~
 -  Trusted Firmware-A:
   `link <https://github.com/ARM-software/arm-trusted-firmware>`__
@@ -23,7 +23,7 @@ Code Locations
   `link <https://github.com/altera-opensource/uefi-socfpga>`__
 Build Procedure
---------------
+~~~~~~~~~~~~~~~
 -  Fetch all the above 2 repositories into local host.
   Make all the repositories in the same ${BUILD\_PATH}.
@@ -45,7 +45,7 @@ Build Procedure
       BL33=PEI.ROM
 Install Procedure
-----------------
+~~~~~~~~~~~~~~~~~
 - dd fip.bin to a A2 partition on the MMC drive to be booted in Stratix 10
  board.
@@ -53,16 +53,18 @@ Install Procedure
 - Generate a SOF containing bl2
 .. code:: bash
        aarch64-linux-gnu-objcopy -I binary -O ihex --change-addresses 0xffe00000 bl2.bin bl2.hex
        quartus_cpf --bootloader bl2.hex <quartus_generated_sof> <output_sof_with_bl2>
 - Configure SOF to board
 .. code:: bash
        nios2-configure-sof <output_sof_with_bl2>
 Boot trace
-==========
+----------
 ::
         INFO:    DDR: DRAM calibration success.

--- a/docs/plat/ls1043a.rst
+++ b/docs/plat/ls1043a.rst
-Description
+NXP QorIQ® LS1043A
-===========
+==================
 The QorIQ® LS1043A processor is NXP's first quad-core, 64-bit Arm®-based
 processor for embedded networking. The LS1023A (two core version) and the
@@ -36,7 +36,7 @@ UART: supports two UARTs up to 115200 bps for console
 More information are listed in `ls1043`_.
 Boot Sequence
-=============
+-------------
 Bootrom --> TF-A BL1 --> TF-A BL2 --> TF-A BL1 --> TF-A BL31
@@ -44,10 +44,10 @@ Bootrom --> TF-A BL1 --> TF-A BL2 --> TF-A BL1 --> TF-A BL31
 How to build
-============
+------------
 Build Procedure
---------------
+~~~~~~~~~~~~~~~
 -  Prepare AARCH64 toolchain.
@@ -69,7 +69,7 @@ Build Procedure
       BL33=u-boot.bin NEED_BL32=yes BL32=tee.bin SPD=opteed
 Deploy TF-A Images
-----------------
+~~~~~~~~~~~~~~~~~~
 -  Deploy TF-A images on Nor flash Alt Bank.