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

docs/design/psci-pd-tree.rst

-PSCI Power Domain Tree design
-=============================
-
-
-
-
-.. contents::
-
---------------
+PSCI Power Domain Tree Structure
+================================
 
 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];

docs/design/reset-design.rst

-Trusted Firmware-A reset design
-===============================
-
-
-
-
-.. contents::
+CPU Reset
+=========
 
 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
-above is still relevant, as all these operations will occur in BL31 in
-this case. Please refer to section 6 "Using BL31 entrypoint as the reset
-address" for more information.
+.. note::
+   If BL31 is used as the TF-A entry point instead of BL1, the diagram
+   above is still relevant, as all these operations will occur in BL31 in
+   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
-.. |Reset code flow with programmable reset address| image:: ../diagrams/reset_code_no_boot_type_check.png?raw=true
-.. |Reset code flow with single CPU released out of reset| image:: ../diagrams/reset_code_no_cpu_check.png?raw=true
-.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: ../diagrams/reset_code_no_checks.png?raw=true
+.. |Default reset code flow| image:: ../resources/diagrams/default_reset_code.png
+.. |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:: ../resources/diagrams/reset_code_no_cpu_check.png
+.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: ../resources/diagrams/reset_code_no_checks.png

docs/design/trusted-board-boot.rst

-Trusted Board Boot Design Guide
-===============================
-
-
-
-
-.. contents::
+Trusted Board Boot
+==================
 
 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,7 +141,8 @@ 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::
+      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

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.
 

docs/getting_started/porting-guide.rst

-Trusted Firmware-A Porting Guide
-================================
-
-
-
-.. contents::
+Porting Guide
+=============
 
 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).
-The default implementation simply spins.
+.. note::
+   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
-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.
+.. warning::
+   For the protection to be effective, the global data need to be placed at
+   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
-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
 .........
@@ -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
-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
@@ -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.
-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.
@@ -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
-assembly and conform with the register clobber rules for putc() (x0-x2, x16-x17)
-and flush() (x0-x3, x16-x17) crash callbacks.
+
+.. 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 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

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

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
-all of the above requirements yet.
+.. note::
+   The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow
+   all of the above requirements yet.
 
 Services that contain multiple sub-services
 -------------------------------------------

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

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

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`_.

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

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>                \

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).
-

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:

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

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

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

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.

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.