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/plat/meson-gxbb.rst

-Trusted Firmware-A for Amlogic Meson S905 (GXBB)
-================================================
+Amlogic Meson S905 (GXBB)
+=========================
 
 The Amlogic Meson S905 is a SoC with a quad core Arm Cortex-A53 running at
 1.5Ghz. It also contains a Cortex-M3 used as SCP.
@@ -15,7 +15,7 @@ and Linux:
 
 In order to build it:
 
-::
+.. code:: shell
 
     CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=gxbb bl31
 

docs/plat/meson-gxl.rst

-Trusted Firmware-A for Amlogic Meson S905x (GXL)
-================================================
+Amlogic Meson S905x (GXL)
+=========================
 
 The Amlogic Meson S905x is a SoC with a quad core Arm Cortex-A53 running at
 1.5Ghz. It also contains a Cortex-M3 used as SCP.
@@ -15,7 +15,7 @@ and Linux:
 
 In order to build it:
 
-::
+.. code:: shell
 
     CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=gxl
 

docs/plat/mt8183.rst

-Description
-===========
+MediaTek 8183
+=============
 
 MediaTek 8183 (MT8183) is a 64-bit ARM SoC introduced by MediaTek in early 2018.
 The chip incorporates eight cores - four Cortex-A53 little cores and Cortex-A73.
 Both clusters can operate at up to 2 GHz.
 
 Boot Sequence
-=============
+-------------
 
 ::
 
     Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel
 
 How to Build
-============
+------------
 
 .. code:: shell
 

docs/plat/nvidia-tegra.rst

-Tegra SoCs - Overview
-=====================
+NVIDIA Tegra
+============
 
 -  .. rubric:: T186
       :name: t186
@@ -58,13 +58,13 @@ to extensive power-gating and dynamic voltage and clock scaling based on
 workloads.
 
 Directory structure
-===================
+-------------------
 
 -  plat/nvidia/tegra/common - Common code for all Tegra SoCs
 -  plat/nvidia/tegra/soc/txxx - Chip specific code
 
 Trusted OS dispatcher
-=====================
+---------------------
 
 Tegra supports multiple Trusted OS'.
 
@@ -83,7 +83,7 @@ Tegra210: TLK and Trusty
 Tegra186: Trusty
 
 Scatter files
-=============
+-------------
 
 Tegra platforms currently support scatter files and ld.S scripts. The scatter
 files help support ARMLINK linker to generate BL31 binaries. For now, there
@@ -93,7 +93,7 @@ the scatter file to be used. Tegra platforms have verified BL31 image generation
 with ARMCLANG (compilation) and ARMLINK (linking) for the Tegra186 platforms.
 
 Preparing the BL31 image to run on Tegra SoCs
-=============================================
+---------------------------------------------
 
 .. code:: shell
 
@@ -125,7 +125,7 @@ uint64\_t boot\_profiler\_shmem\_base;
 } plat\_params\_from\_bl2\_t;
 
 Power Management
-================
+----------------
 
 The PSCI implementation expects each platform to expose the 'power state'
 parameter to be used during the 'SYSTEM SUSPEND' call. The state-id field
@@ -133,7 +133,7 @@ is implementation defined on Tegra SoCs and is preferably defined by
 tegra\_def.h.
 
 Tegra configs
-=============
+-------------
 
 -  'tegra\_enable\_l2\_ecc\_parity\_prot': This flag enables the L2 ECC and Parity
    Protection bit, for Arm Cortex-A57 CPUs, during CPU boot. This flag will

docs/plat/qemu.rst

-Trusted Firmware-A for QEMU virt Armv8-A
-========================================
+QEMU virt Armv8-A
+=================
 
 Trusted Firmware-A (TF-A) implements the EL3 firmware layer for QEMU virt
 Armv8-A. BL1 is used as the BootROM, supplied with the -bios argument.
@@ -33,13 +33,13 @@ is conveniently achieved with symlinks the local names as:
 
 To build:
 
-::
+.. code:: shell
 
-    make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu 
+    make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu
 
 To start (QEMU v2.6.0):
 
-::
+.. code:: shell
 
     qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57  \
         -kernel Image                           \

docs/plat/rcar-gen3.rst

-Description
-===========
+Renesas R-Car
+=============
 
 "R-Car" is the nickname for Renesas' system-on-chip (SoC) family for
 car information systems designed for the next-generation of automotive
@@ -97,14 +97,14 @@ program counters.
 
 
 How to build
-============
+------------
 
 The TF-A build options depend on the target board so you will have to
 refer to those specific instructions. What follows is customized to
 the H3 SiP Salvator-X development system used in this port.
 
 Build Tested:
--------------
+~~~~~~~~~~~~~
 RCAR_OPT="LSI=H3 RCAR_DRAM_SPLIT=1 RCAR_LOSSY_ENABLE=1"
 MBEDTLS_DIR=$mbedtls_src
 
@@ -112,7 +112,7 @@ $ MBEDTLS_DIR=$mbedtls_src_tree make clean bl2 bl31 rcar_layout_tool \
 PLAT=rcar ${RCAR_OPT} SPD=opteed
 
 System Tested:
---------------------
+~~~~~~~~~~~~~~
 * mbed_tls:
   git@github.com:ARMmbed/mbedtls.git [devel]
 
@@ -150,7 +150,7 @@ System Tested:
   Linux 4.19-rc4
 
 TF-A Build Procedure
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 -  Fetch all the above 4 repositories.
 
@@ -184,7 +184,7 @@ TF-A Build Procedure
        make -j8 PLATFORM="rcar" CFG_ARM64_core=y
 
 Install Procedure
------------------
+~~~~~~~~~~~~~~~~~
 
 - Boot the board in Mini-monitor mode and enable access to the
   Hyperflash.
@@ -195,7 +195,7 @@ Install Procedure
 
 
 Boot trace
-==========
+----------
 
 Notice that BL31 traces are not accessible via the console and that in
 order to verbose the BL2 output you will have to compile TF-A with
@@ -266,4 +266,3 @@ LOG_LEVEL=50 and DEBUG=1
    Net:   eth0: ethernet@e6800000
    Hit any key to stop autoboot:  0
    =>
-

docs/plat/rockchip.rst

-Trusted Firmware-A for Rockchip SoCs
-====================================
+Rockchip SoCs
+=============
 
 Trusted Firmware-A supports a number of Rockchip ARM SoCs from both
 AARCH32 and AARCH64 fields.
@@ -12,7 +12,7 @@ This includes right now:
 
 
 Boot Sequence
-=============
+-------------
 
 For AARCH32:
     Bootrom --> BL1/BL2 --> BL32 --> BL33 --> Linux kernel
@@ -26,7 +26,7 @@ BL1/2 and BL33 can currently be supplied from either:
 
 
 How to build
-============
+------------
 
 Rockchip SoCs expect TF-A's BL31 (AARCH64) or BL32 (AARCH32) to get
 integrated with other boot software like U-Boot or Coreboot, so only
@@ -46,7 +46,7 @@ compilation toolchain.
 
 
 How to deploy
-=============
+-------------
 
 Both upstream U-Boot and Coreboot projects contain instructions on where
 to put the built images during their respective build process.

docs/plat/rpi3.rst

-Trusted Firmware-A for Raspberry Pi 3
-=====================================
-
-
-
-.. contents::
+Raspberry Pi 3
+==============
 
 The `Raspberry Pi 3`_ is an inexpensive single-board computer that contains four
 Arm Cortex-A53 cores.
@@ -167,7 +163,7 @@ Secondary cores
 ~~~~~~~~~~~~~~~
 
 This port of the Trusted Firmware-A supports ``PSCI_CPU_ON``,
-`PSCI_SYSTEM_RESET`` and ``PSCI_SYSTEM_OFF``. The last one doesn't really turn
+``PSCI_SYSTEM_RESET`` and ``PSCI_SYSTEM_OFF``. The last one doesn't really turn
 the system off, it simply reboots it and asks the VideoCore firmware to keep it
 in a low power mode permanently.
 
@@ -274,11 +270,12 @@ The following build options are supported:
   BL32_EXTRA1=tee-pager_v2.bin  BL32_EXTRA2=tee-pageable_v2.bin``
   to put the binaries into the FIP.
 
-  Note: If OP-TEE is used it may be needed to add the following options to the
-  Linux command line so that the USB driver doesn't use FIQs:
-  ``dwc_otg.fiq_enable=0 dwc_otg.fiq_fsm_enable=0 dwc_otg.nak_holdoff=0``.
-  This will unfortunately reduce the performance of the USB driver. It is needed
-  when using Raspbian, for example.
+  .. warning::
+     If OP-TEE is used it may be needed to add the following options to the
+     Linux command line so that the USB driver doesn't use FIQs:
+     ``dwc_otg.fiq_enable=0 dwc_otg.fiq_fsm_enable=0 dwc_otg.nak_holdoff=0``.
+     This will unfortunately reduce the performance of the USB driver. It is
+     needed when using Raspbian, for example.
 
 - ``TRUSTED_BOARD_BOOT``: This port supports TBB. Set this option to 1 to enable
   it. In order to use TBB, you might want to set ``GENERATE_COT=1`` to let the

docs/plat/socionext-uniphier.rst

-Trusted Firmware-A for Socionext UniPhier SoCs
-==============================================
-
+Socionext UniPhier
+==================
 
 Socionext UniPhier Armv8-A SoCs use Trusted Firmware-A (TF-A) as the secure
 world firmware, supporting BL2 and BL31.

docs/plat/stm32mp1.rst

-Trusted Firmware-A for STM32MP1
-===============================
+STMicroelectronics STM32MP1
+===========================
 
 STM32MP1 is a microprocessor designed by STMicroelectronics
 based on a dual Arm Cortex-A7.

docs/plat/synquacer.rst

-Trusted Firmware-A for Socionext Synquacer SoCs
-===============================================
+Socionext Synquacer
+===================
 
 Socionext's Synquacer SC2A11 is a multi-core processor with 24 cores of Arm
 Cortex-A53. The Developerbox, of 96boards, is a platform that contains this
@@ -9,10 +9,10 @@ the moment.
 More information are listed in `link`_.
 
 How to build
-============
+------------
 
 Code Locations
---------------
+~~~~~~~~~~~~~~
 
 -  Trusted Firmware-A:
    `link <https://github.com/ARM-software/arm-trusted-firmware>`__
@@ -27,12 +27,12 @@ Code Locations
    `link <https://github.com/tianocore/edk2-non-osi>`__
 
 Boot Flow
----------
+~~~~~~~~~
 
 SCP firmware --> TF-A BL31 --> UEFI(edk2)
 
 Build Procedure
----------------
+~~~~~~~~~~~~~~~
 
 -  Firstly, in addition to the “normal” build tools you will also need a
    few specialist tools. On a Debian or Ubuntu operating system try:
@@ -98,7 +98,7 @@ Build Procedure
    Note #2: Replace -b RELEASE with -b DEBUG to build a debug.
 
 Install the System Firmware
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -  Providing your Developerbox is fully working and has on operating system
    installed then you can adopt your the newly compiled system firmware using

docs/plat/ti-k3.rst

-Trusted Firmware-A for Texas Instruments K3 SoCs
-================================================
+Texas Instruments K3
+====================
 
 Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Texas Instruments K3 SoCs.
 
 Boot Flow
 ---------
 
-R5(U-Boot) --> TF-A BL31 --> BL32(OP-TEE) --> TF-A BL31 --> BL33(U-Boot) --> Linux
+::
+
+   R5(U-Boot) --> TF-A BL31 --> BL32(OP-TEE) --> TF-A BL31 --> BL33(U-Boot) --> Linux
                                                        \
-                                                Optional direct to Linux boot
-                                                         \
+                                                   Optional direct to Linux boot
+                                                           \
                                                            --> BL33(Linux)
 
 Texas Instruments K3 SoCs contain an R5 processor used as the boot master, it

docs/plat/warp7.rst

-Trusted Firmware-A for i.MX7 WaRP7
-==================================
+NXP i.MX7 WaRP7
+===============
 
 The Trusted Firmware-A port for the i.MX7Solo WaRP7 implements BL2 at EL3.
 The i.MX7S contains a BootROM with a High Assurance Boot (HAB) functionality.
@@ -7,21 +7,23 @@ This functionality provides a mechanism for establishing a root-of-trust from
 the reset vector to the command-line in user-space.
 
 Boot Flow
-=========
+---------
 
 BootROM --> TF-A BL2 --> BL32(OP-TEE) --> BL33(U-Boot) --> Linux
 
 In the WaRP7 port we encapsulate OP-TEE, DTB and U-Boot into a FIP. This FIP is
 expected and required
 
-# Build Instructions
+Build Instructions
+------------------
 
 We need to use a file generated by u-boot in order to generate a .imx image the
 BootROM will boot. It is therefore _required_ to build u-boot before TF-A and
 furthermore it is _recommended_ to use the mkimage in the u-boot/tools directory
 to generate the TF-A .imx image.
 
-## U-Boot:
+U-Boot
+~~~~~~
 
 https://git.linaro.org/landing-teams/working/mbl/u-boot.git
 
@@ -31,7 +33,8 @@ https://git.linaro.org/landing-teams/working/mbl/u-boot.git
     make warp7_bl33_defconfig;
     make u-boot.imx arch=ARM CROSS_COMPILE=arm-linux-gnueabihf-
 
-## OP-TEE:
+OP-TEE
+~~~~~~
 
 https://github.com/OP-TEE/optee_os.git
 
@@ -39,7 +42,8 @@ https://github.com/OP-TEE/optee_os.git
 
     make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- PLATFORM=imx PLATFORM_FLAVOR=mx7swarp7 ARCH=arm CFG_PAGEABLE_ADDR=0 CFG_DT_ADDR=0x83000000 CFG_NS_ENTRY_ADDR=0x87800000
 
-## TF-A:
+TF-A
+~~~~
 
 https://github.com/ARM-software/arm-trusted-firmware.git
 
@@ -75,7 +79,8 @@ It is also assumed copy of mbedtls is available on the path path ../mbedtls
 
     /path/to/u-boot/tools/mkimage -n /path/to/u-boot/u-boot.cfgout -T imximage -e 0x9df00000 -d ./build/warp7/debug/bl2.bin ./build/warp7/debug/bl2.bin.imx
 
-## FIP:
+FIP
+~~~
 
 .. code:: shell
 
@@ -110,8 +115,8 @@ It is also assumed copy of mbedtls is available on the path path ../mbedtls
               --trusted-key-cert fiptool_images/trusted-key-cert.key-crt \
               --tb-fw-cert fiptool_images/trusted-boot-fw.key-crt warp7.fip
 
-# Deploy Images
-
+Deploy Images
+-------------
 
 First place the WaRP7 into UMS mode in u-boot this should produce an entry in
 /dev like /dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0
@@ -138,7 +143,8 @@ Remember to umount the USB device pefore proceeding
     sudo umount /dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0*
 
 
-# Signing BL2
+Signing BL2
+-----------
 
 A further step is to sign BL2.
 

docs/plat/xilinx-versal.md → docs/plat/xilinx-versal.rst

-Trusted Firmware-A for Xilinx Versal
-================================
+Xilinx Versal
+=============
 
 Trusted Firmware-A implements the EL3 firmware layer for Xilinx Versal.
 The platform only uses the runtime part of TF-A as Xilinx Versal already has a
@@ -19,7 +19,9 @@ To build ATF for different platform (for now its just versal virtual "versal_vir
 make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal VERSAL_PLATFORM=versal_virt bl31
 ```
 
-# Xilinx Versal platform specific build options
+Xilinx Versal platform specific build options
+---------------------------------------------
+
 *   `VERSAL_ATF_MEM_BASE`: Specifies the base address of the bl31 binary.
 *   `VERSAL_ATF_MEM_SIZE`: Specifies the size of the memory region of the bl31 binary.
 *   `VERSAL_BL32_MEM_BASE`: Specifies the base address of the bl32 binary.

docs/plat/xilinx-zynqmp.rst

-Trusted Firmware-A for Xilinx Zynq UltraScale+ MPSoC
-====================================================
+Xilinx Zynq UltraScale+ MPSoC
+=============================
 
 Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Xilinx Zynq
 UltraScale + MPSoC.
@@ -23,7 +23,7 @@ To build bl32 TSP you have to rebuild bl31 too:
     make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd bl31 bl32
 
 ZynqMP platform specific build options
-======================================
+--------------------------------------
 
 -  ``ZYNQMP_ATF_MEM_BASE``: Specifies the base address of the bl31 binary.
 -  ``ZYNQMP_ATF_MEM_SIZE``: Specifies the size of the memory region of the bl31 binary.
@@ -36,7 +36,7 @@ ZynqMP platform specific build options
    -  ``cadence1`` : Cadence UART 1
 
 FSBL->TF-A Parameter Passing
-===========================
+----------------------------
 
 The FSBL populates a data structure with image information for TF-A. TF-A uses
 that data to hand off to the loaded images. The address of the handoff data
@@ -45,7 +45,7 @@ register is free to be used by other software once TF-A has brought up
 further firmware images.
 
 Power Domain Tree
-=================
+-----------------
 
 The following power domain tree represents the power domain model used by TF-A
 for ZynqMP:

docs/process/coding-guidelines.rst

-Trusted Firmware-A Coding Guidelines
-====================================
-
-
-
-.. contents::
+Coding Style & Guidelines
+=========================
 
 The following sections contain TF coding guidelines. They are continually
 evolving and should not be considered "set in stone". Feel free to question them
@@ -11,8 +7,9 @@ and provide feedback.
 
 Some of the guidelines may also apply to other codebases.
 
-**Note:** the existing TF codebase does not necessarily comply with all the
-below guidelines but the intent is for it to do so eventually.
+.. note::
+   The existing TF codebase does not necessarily comply with all the
+   below guidelines but the intent is for it to do so eventually.
 
 Checkpatch overrides
 --------------------
@@ -296,7 +293,7 @@ of the size of an array is the same.
 If ``MY_STRUCT_SIZE`` in the above example were wrong then the compiler would
 emit an error like this:
 
-.. code:: c
+::
 
   my_struct.h:10:1: error: size of array ‘assert_my_struct_size_mismatch’ is negative
 

docs/process/contributing.rst

-Contributing to Trusted Firmware-A
-==================================
+Contributor's Guide
+===================
 
 Getting Started
 ---------------

docs/process/index.rst

@@ -7,7 +7,7 @@ Processes & Policies
    :numbered:
 
    release-information
-   security-center
+   security
    platform-compatibility-policy
    coding-guidelines
    contributing

docs/process/platform-compatibility-policy.rst

-TF-A Platform Compatibility Policy
-==================================
-
-
-
-
-.. contents::
-
---------------
+Platform Compatibility Policy
+=============================
 
 Introduction
 ------------

docs/process/release-information.rst

-TF-A Release Information
-========================
-
-.. section-numbering::
-    :suffix: .
-
-.. contents::
-
---------------
+Release Processes
+=================
 
 Project Release Cadence
 -----------------------