doc: Reformat platform port documents

The platform port documents are not very standardised right now and
they don't integrate properly into the document tree so:

1) Make sure each port has a proper name and title (incl. owner)
2) Correct use of headings, subheadings, etc in each port
3) Resolve any naming conflicts between documents

Change-Id: I4c2da6f57172b7f2af3512e766ae9ce3b840b50f
Signed-off-by: Paul Beesley <paul.beesley@arm.com>

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
@@ -37,11 +37,10 @@ To build for machines with an H6 SoC:
 .. _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.
 

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.

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.

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.
@@ -35,7 +35,7 @@ To build:
 
 ::
 
-    make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu 
+    make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu
 
 To start (QEMU v2.6.0):
 

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
-=====================================
-
-
+Raspberry Pi 3
+==============
 
 .. contents::
 
@@ -167,7 +165,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.
 

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.