summaryrefslogtreecommitdiffstats
path: root/docs/plat
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 09:13:47 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 09:13:47 +0000
commit102b0d2daa97dae68d3eed54d8fe37a9cc38a892 (patch)
treebcf648efac40ca6139842707f0eba5a4496a6dd2 /docs/plat
parentInitial commit. (diff)
downloadarm-trusted-firmware-102b0d2daa97dae68d3eed54d8fe37a9cc38a892.tar.xz
arm-trusted-firmware-102b0d2daa97dae68d3eed54d8fe37a9cc38a892.zip
Adding upstream version 2.8.0+dfsg.upstream/2.8.0+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/plat')
-rw-r--r--docs/plat/allwinner.rst142
-rw-r--r--docs/plat/arm/arm-build-options.rst164
-rw-r--r--docs/plat/arm/arm_fpga/index.rst97
-rw-r--r--docs/plat/arm/corstone1000/index.rst61
-rw-r--r--docs/plat/arm/fvp-ve/index.rst84
-rw-r--r--docs/plat/arm/fvp/index.rst640
-rw-r--r--docs/plat/arm/fvp_r/index.rst46
-rw-r--r--docs/plat/arm/index.rst24
-rw-r--r--docs/plat/arm/juno/index.rst253
-rw-r--r--docs/plat/arm/morello/index.rst33
-rw-r--r--docs/plat/arm/tc/index.rst63
-rw-r--r--docs/plat/brcm-stingray.rst43
-rw-r--r--docs/plat/hikey.rst155
-rw-r--r--docs/plat/hikey960.rst180
-rw-r--r--docs/plat/imx8.rst58
-rw-r--r--docs/plat/imx8m.rst113
-rw-r--r--docs/plat/index.rst82
-rw-r--r--docs/plat/intel-agilex.rst86
-rw-r--r--docs/plat/intel-stratix10.rst94
-rw-r--r--docs/plat/marvell/armada/build.rst476
-rw-r--r--docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst49
-rw-r--r--docs/plat/marvell/armada/misc/mvebu-amb.rst58
-rw-r--r--docs/plat/marvell/armada/misc/mvebu-ccu.rst33
-rw-r--r--docs/plat/marvell/armada/misc/mvebu-io-win.rst46
-rw-r--r--docs/plat/marvell/armada/misc/mvebu-iob.rst52
-rw-r--r--docs/plat/marvell/armada/porting.rst158
-rw-r--r--docs/plat/marvell/armada/uart-booting.rst103
-rw-r--r--docs/plat/marvell/index.rst15
-rw-r--r--docs/plat/meson-axg.rst27
-rw-r--r--docs/plat/meson-g12a.rst27
-rw-r--r--docs/plat/meson-gxbb.rst26
-rw-r--r--docs/plat/meson-gxl.rst27
-rw-r--r--docs/plat/mt8183.rst20
-rw-r--r--docs/plat/mt8186.rst21
-rw-r--r--docs/plat/mt8188.rst21
-rw-r--r--docs/plat/mt8192.rst21
-rw-r--r--docs/plat/mt8195.rst21
-rw-r--r--docs/plat/nvidia-tegra.rst148
-rw-r--r--docs/plat/nxp/index.rst17
-rw-r--r--docs/plat/nxp/nxp-layerscape.rst473
-rw-r--r--docs/plat/nxp/nxp-ls-fuse-prov.rst271
-rw-r--r--docs/plat/nxp/nxp-ls-tbbr.rst210
-rw-r--r--docs/plat/poplar.rst176
-rw-r--r--docs/plat/qemu-sbsa.rst56
-rw-r--r--docs/plat/qemu.rst172
-rw-r--r--docs/plat/qti-msm8916.rst116
-rw-r--r--docs/plat/qti.rst43
-rw-r--r--docs/plat/rcar-gen3.rst268
-rw-r--r--docs/plat/rockchip.rst55
-rw-r--r--docs/plat/rpi3.rst466
-rw-r--r--docs/plat/rpi4.rst84
-rw-r--r--docs/plat/rz-g2.rst228
-rw-r--r--docs/plat/socionext-uniphier.rst116
-rw-r--r--docs/plat/stm32mp1.rst280
-rw-r--r--docs/plat/synquacer.rst117
-rw-r--r--docs/plat/ti-k3.rst57
-rw-r--r--docs/plat/warp7.rst210
-rw-r--r--docs/plat/xilinx-versal-net.rst31
-rw-r--r--docs/plat/xilinx-versal.rst55
-rw-r--r--docs/plat/xilinx-zynqmp.rst73
60 files changed, 7341 insertions, 0 deletions
diff --git a/docs/plat/allwinner.rst b/docs/plat/allwinner.rst
new file mode 100644
index 0000000..3e9ce51
--- /dev/null
+++ b/docs/plat/allwinner.rst
@@ -0,0 +1,142 @@
+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
+PSCI runtime services.
+
+Building TF-A
+-------------
+
+There is one build target per supported SoC:
+
++------+-------------------+
+| SoC | TF-A build target |
++======+===================+
+| A64 | sun50i_a64 |
++------+-------------------+
+| H5 | sun50i_a64 |
++------+-------------------+
+| H6 | sun50i_h6 |
++------+-------------------+
+| H616 | sun50i_h616 |
++------+-------------------+
+| H313 | sun50i_h616 |
++------+-------------------+
+| R329 | sun50i_r329 |
++------+-------------------+
+
+To build with the default settings for a particular SoC:
+
+.. code:: shell
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=<build target> DEBUG=1
+
+So for instance to build for a board with the Allwinner A64 SoC::
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sun50i_a64 DEBUG=1
+
+Platform-specific build options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The default build options should generate a working firmware image. There are
+some build options that allow to fine-tune the firmware, or to disable support
+for optional features.
+
+- ``SUNXI_PSCI_USE_NATIVE`` : Support direct control of the CPU cores powerdown
+ and powerup sequence by BL31. This requires either support for a code snippet
+ to be loaded into the ARISC SCP (A64, H5), or the power sequence control
+ registers to be programmed directly (H6, H616). This supports only basic
+ control, like core on/off and system off/reset.
+ This option defaults to 1. If an active SCP supporting the SCPI protocol
+ is detected at runtime, this control scheme will be ignored, and SCPI
+ will be used instead, unless support has been explicitly disabled.
+
+- ``SUNXI_PSCI_USE_SCPI`` : Support control of the CPU cores powerdown and
+ powerup sequence by talking to the SCP processor via the SCPI protocol.
+ This allows more advanced power saving techniques, like suspend to RAM.
+ This option defaults to 1 on SoCs that feature an SCP. If no SCP firmware
+ using the SCPI protocol is detected, the native sequence will be used
+ instead. If both native and SCPI methods are included, SCPI will be favoured
+ if SCP support is detected.
+
+- ``SUNXI_SETUP_REGULATORS`` : On SoCs that typically ship with a PMIC
+ power management controller, BL31 tries to set up all needed power rails,
+ programming them to their respective voltages. That allows bootloader
+ software like U-Boot to ignore power control via the PMIC.
+ This setting defaults to 1. In some situations that enables too many
+ regulators, or some regulators need to be enabled in a very specific
+ sequence. To avoid problems with those boards, ``SUNXI_SETUP_REGULATORS``
+ can bet set to ``0`` on the build command line, to skip the PMIC setup
+ entirely. Any bootloader or OS would need to setup the PMIC on its own then.
+
+Installation
+------------
+
+U-Boot's SPL acts as a loader, loading both BL31 and BL33 (typically U-Boot).
+Loading is done from SD card, eMMC or SPI flash, also via an USB debug
+interface (FEL).
+
+After building bl31.bin, the binary must be fed to the U-Boot build system
+to include it in the FIT image that the SPL loader will process.
+bl31.bin can be either copied (or sym-linked) into U-Boot's root directory,
+or the environment variable BL31 must contain the binary's path.
+See the respective `U-Boot documentation`_ for more details.
+
+.. _U-Boot documentation: https://gitlab.denx.de/u-boot/u-boot/-/blob/master/board/sunxi/README.sunxi64
+
+Memory layout
+-------------
+
+A64, H5 and H6 SoCs
+~~~~~~~~~~~~~~~~~~~
+
+BL31 lives in SRAM A2, which is documented to be accessible from secure
+world only. Since this SRAM region is very limited (48 KB), we take
+several measures to reduce memory consumption. One of them is to confine
+BL31 to only 28 bits of virtual address space, which reduces the number
+of required page tables (each occupying 4KB of memory).
+The mapping we use on those SoCs is as follows:
+
+::
+
+ 0 64K 16M 1GB 1G+160M physical address
+ +-+------+-+---+------+--...---+-------+----+------+----------
+ |B| |S|///| |//...///| |////| |
+ |R| SRAM |C|///| dev |//...///| (sec) |////| BL33 | DRAM ...
+ |O| |P|///| MMIO |//...///| DRAM |////| |
+ |M| | |///| |//...///| (32M) |////| |
+ +-+------+-+---+------+--...---+-------+----+------+----------
+ | | | | | | / / / /
+ | | | | | | / / / /
+ | | | | | | / / / /
+ | | | | | | / // /
+ | | | | | | / / /
+ +-+------+-+---+------+--+-------+------+
+ |B| |S|///| |//| | |
+ |R| SRAM |C|///| dev |//| sec | BL33 |
+ |O| |P|///| MMIO |//| DRAM | |
+ |M| | |///| |//| | |
+ +-+------+-+---+------+--+-------+------+
+ 0 64K 16M 160M 192M 256M virtual address
+
+
+H616 SoC
+~~~~~~~~
+
+The H616 lacks the secure SRAM region present on the other SoCs, also
+lacks the "ARISC" management processor (SCP) we use. BL31 thus needs to
+run from DRAM, which prevents our compressed virtual memory map described
+above. Since running in DRAM also lifts the restriction of the limited
+SRAM size, we use the normal 1:1 mapping with 32 bits worth of virtual
+address space. So the virtual addresses used in BL31 match the physical
+addresses as presented above.
+
+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).
diff --git a/docs/plat/arm/arm-build-options.rst b/docs/plat/arm/arm-build-options.rst
new file mode 100644
index 0000000..407c04b
--- /dev/null
+++ b/docs/plat/arm/arm-build-options.rst
@@ -0,0 +1,164 @@
+Arm Development Platform Build Options
+======================================
+
+Arm Platform Build Options
+--------------------------
+
+- ``ARM_BL31_IN_DRAM``: Boolean option to select loading of BL31 in TZC secured
+ DRAM. By default, BL31 is in the secure SRAM. Set this flag to 1 to load
+ BL31 in TZC secured DRAM. If TSP is present, then setting this option also
+ sets the TSP location to DRAM and ignores the ``ARM_TSP_RAM_LOCATION`` build
+ flag.
+
+- ``ARM_CONFIG_CNTACR``: boolean option to unlock access to the ``CNTBase<N>``
+ frame registers by setting the ``CNTCTLBase.CNTACR<N>`` register bits. The
+ frame number ``<N>`` is defined by ``PLAT_ARM_NSTIMER_FRAME_ID``, which
+ should match the frame used by the Non-Secure image (normally the Linux
+ kernel). Default is true (access to the frame is allowed).
+
+- ``ARM_DISABLE_TRUSTED_WDOG``: boolean option to disable the Trusted Watchdog.
+ By default, Arm platforms use a watchdog to trigger a system reset in case
+ an error is encountered during the boot process (for example, when an image
+ could not be loaded or authenticated). The watchdog is enabled in the early
+ platform setup hook at BL1 and disabled in the BL1 prepare exit hook. The
+ Trusted Watchdog may be disabled at build time for testing or development
+ purposes.
+
+- ``ARM_LINUX_KERNEL_AS_BL33``: The Linux kernel expects registers x0-x3 to
+ have specific values at boot. This boolean option allows the Trusted Firmware
+ to have a Linux kernel image as BL33 by preparing the registers to these
+ values before jumping to BL33. This option defaults to 0 (disabled). For
+ AArch64 ``RESET_TO_BL31`` and for AArch32 ``RESET_TO_SP_MIN`` must be 1 when
+ using it. If this option is set to 1, ``ARM_PRELOADED_DTB_BASE`` must be set
+ to the location of a device tree blob (DTB) already loaded in memory. The
+ Linux Image address must be specified using the ``PRELOADED_BL33_BASE``
+ option.
+
+- ``ARM_PLAT_MT``: This flag determines whether the Arm platform layer has to
+ cater for the multi-threading ``MT`` bit when accessing MPIDR. When this flag
+ is set, the functions which deal with MPIDR assume that the ``MT`` bit in
+ MPIDR is set and access the bit-fields in MPIDR accordingly. Default value of
+ this flag is 0. Note that this option is not used on FVP platforms.
+
+- ``ARM_RECOM_STATE_ID_ENC``: The PSCI1.0 specification recommends an encoding
+ for the construction of composite state-ID in the power-state parameter.
+ The existing PSCI clients currently do not support this encoding of
+ State-ID yet. Hence this flag is used to configure whether to use the
+ recommended State-ID encoding or not. The default value of this flag is 0,
+ in which case the platform is configured to expect NULL in the State-ID
+ field of power-state parameter.
+
+- ``ARM_ROTPK_LOCATION``: used when ``TRUSTED_BOARD_BOOT=1``. It specifies the
+ location of the ROTPK hash returned by the function ``plat_get_rotpk_info()``
+ for Arm platforms. Depending on the selected option, the proper private key
+ must be specified using the ``ROT_KEY`` option when building the Trusted
+ Firmware. This private key will be used by the certificate generation tool
+ to sign the BL2 and Trusted Key certificates. Available options for
+ ``ARM_ROTPK_LOCATION`` are:
+
+ - ``regs`` : return the ROTPK hash stored in the Trusted root-key storage
+ registers.
+ - ``devel_rsa`` : return a development public key hash embedded in the BL1
+ and BL2 binaries. This hash has been obtained from the RSA public key
+ ``arm_rotpk_rsa.der``, located in ``plat/arm/board/common/rotpk``. To use
+ this option, ``arm_rotprivk_rsa.pem`` must be specified as ``ROT_KEY``
+ when creating the certificates.
+ - ``devel_ecdsa`` : return a development public key hash embedded in the BL1
+ and BL2 binaries. This hash has been obtained from the ECDSA public key
+ ``arm_rotpk_ecdsa.der``, located in ``plat/arm/board/common/rotpk``. To
+ use this option, ``arm_rotprivk_ecdsa.pem`` must be specified as
+ ``ROT_KEY`` when creating the certificates.
+
+- ``ARM_ROTPK_HASH``: used when ``ARM_ROTPK_LOCATION=devel_*``. Specifies the
+ location of the ROTPK hash. Not expected to be a build option. This defaults to
+ ``plat/arm/board/common/rotpk/*_sha256.bin`` depending on the specified algorithm.
+ Providing ``ROT_KEY`` enforces generation of the hash from the ``ROT_KEY`` and
+ overwrites the default hash file.
+
+- ``ARM_TSP_RAM_LOCATION``: location of the TSP binary. Options:
+
+ - ``tsram`` : Trusted SRAM (default option when TBB is not enabled)
+ - ``tdram`` : Trusted DRAM (if available)
+ - ``dram`` : Secure region in DRAM (default option when TBB is enabled,
+ configured by the TrustZone controller)
+
+- ``ARM_XLAT_TABLES_LIB_V1``: boolean option to compile TF-A with version 1
+ of the translation tables library instead of version 2. It is set to 0 by
+ default, which selects version 2.
+
+- ``ARM_CRYPTOCELL_INTEG`` : bool option to enable TF-A to invoke Arm®
+ TrustZone® CryptoCell functionality for Trusted Board Boot on capable Arm
+ platforms. If this option is specified, then the path to the CryptoCell
+ SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag.
+
+- ``ARM_ETHOSN_NPU_DRIVER``: boolean option to enable a SiP service that can
+ configure an Arm® Ethos™-N NPU. To use this service the target platform's
+ ``HW_CONFIG`` must include the device tree nodes for the NPU. Currently, only
+ the Arm Juno platform has this included in its ``HW_CONFIG`` and the platform
+ only loads the ``HW_CONFIG`` in AArch64 builds. Default is 0.
+
+- ``ARM_SPMC_MANIFEST_DTS`` : path to an alternate manifest file used as the
+ SPMC Core manifest. Valid when ``SPD=spmd`` is selected.
+
+- ``ARM_BL2_SP_LIST_DTS``: Path to DTS file snippet to override the hardcoded
+ SP nodes in tb_fw_config.
+
+- ``OPTEE_SP_FW_CONFIG``: DTC build flag to include OP-TEE as SP in tb_fw_config
+ device tree. This flag is defined only when ``ARM_SPMC_MANIFEST_DTS`` manifest
+ file name contains pattern optee_sp.
+
+- ``TS_SP_FW_CONFIG``: DTC build flag to include Trusted Services (Crypto and
+ internal-trusted-storage) as SP in tb_fw_config device tree.
+
+- ``ARM_GPT_SUPPORT``: Enable GPT parser to get the entry address and length of
+ the various partitions present in the GPT image. This support is available
+ only for the BL2 component, and it is disabled by default.
+ The following diagram shows the view of the FIP partition inside the GPT
+ image:
+
+ |FIP in a GPT image|
+
+For a better understanding of these options, the Arm development platform memory
+map is explained in the :ref:`Firmware Design`.
+
+.. _build_options_arm_css_platform:
+
+Arm CSS Platform-Specific Build Options
+---------------------------------------
+
+- ``CSS_DETECT_PRE_1_7_0_SCP``: Boolean flag to detect SCP version
+ incompatibility. Version 1.7.0 of the SCP firmware made a non-backwards
+ compatible change to the MTL protocol, used for AP/SCP communication.
+ TF-A no longer supports earlier SCP versions. If this option is set to 1
+ then TF-A will detect if an earlier version is in use. Default is 1.
+
+- ``CSS_LOAD_SCP_IMAGES``: Boolean flag, which when set, adds SCP_BL2 and
+ SCP_BL2U to the FIP and FWU_FIP respectively, and enables them to be loaded
+ during boot. Default is 1.
+
+- ``CSS_USE_SCMI_SDS_DRIVER``: Boolean flag which selects SCMI/SDS drivers
+ instead of SCPI/BOM driver for communicating with the SCP during power
+ management operations and for SCP RAM Firmware transfer. If this option
+ is set to 1, then SCMI/SDS drivers will be used. Default is 0.
+
+ - ``CSS_SGI_CHIP_COUNT``: Configures the number of chips on a SGI/RD platform
+ which supports multi-chip operation. If ``CSS_SGI_CHIP_COUNT`` is set to any
+ valid value greater than 1, the platform code performs required configuration
+ to support multi-chip operation.
+
+- ``CSS_SGI_PLATFORM_VARIANT``: Selects the variant of a SGI/RD platform. A
+ particular SGI/RD platform may have multiple variants which may differ in
+ core count, cluster count or other peripherals. This build option is used
+ to select the appropriate platform variant for the build. The range of
+ valid values is platform specific.
+
+- ``CSS_SYSTEM_GRACEFUL_RESET``: Build option to enable graceful powerdown of
+ CPU core on reset. This build option can be used on CSS platforms that
+ require all the CPUs to execute the CPU specific power down sequence to
+ complete a warm reboot sequence in which only the CPUs are power cycled.
+
+--------------
+
+.. |FIP in a GPT image| image:: ../../resources/diagrams/FIP_in_a_GPT_image.png
+
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/plat/arm/arm_fpga/index.rst b/docs/plat/arm/arm_fpga/index.rst
new file mode 100644
index 0000000..5427c1d
--- /dev/null
+++ b/docs/plat/arm/arm_fpga/index.rst
@@ -0,0 +1,97 @@
+Arm FPGA Platform
+=================
+
+This platform supports FPGA images used internally in Arm Ltd., for
+testing and bringup of new cores. With that focus, peripheral support is
+minimal: there is no mass storage or display output, for instance. Also
+this port ignores any power management features of the platform.
+Some interconnect setup is done internally by the platform, so the TF-A code
+just needs to setup UART and GIC.
+
+The FPGA platform requires to pass on a DTB for the non-secure payload
+(mostly Linux), so we let TF-A use information from the DTB for dynamic
+configuration: the UART and GIC base addresses are read from there.
+
+As a result this port is a fairly generic BL31-only port, which can serve
+as a template for a minimal new (and possibly DT-based) platform port.
+
+The aim of this port is to support as many FPGA images as possible with
+a single build. Image specific data must be described in the DTB or should
+be auto-detected at runtime.
+
+As the number and topology layout of the CPU cores differs significantly
+across the various images, this is detected at runtime by BL31.
+The /cpus node in the DT will be added and filled accordingly, as long as
+it does not exist already.
+
+Platform-specific build options
+-------------------------------
+
+- ``SUPPORT_UNKNOWN_MPID`` : Boolean option to allow unknown MPIDR registers.
+ Normally TF-A panics if it encounters a MPID value not matched to its
+ internal list, but for new or experimental cores this creates a lot of
+ churn. With this option, the code will fall back to some basic CPU support
+ code (only architectural system registers, and no errata).
+ Default value of this flag is 1.
+
+- ``PRELOADED_BL33_BASE`` : Physical address of the BL33 non-secure payload.
+ It must have been loaded into DRAM already, typically this is done by
+ the script that also loads BL31 and the DTB.
+ It defaults to 0x80080000, which is the traditional load address for an
+ arm64 Linux kernel.
+
+- ``FPGA_PRELOADED_DTB_BASE`` : Physical address of the flattened device
+ tree blob (DTB). This DT will be used by TF-A for dynamic configuration,
+ so it must describe at least the UART and a GICv3 interrupt controller.
+ The DT gets amended by the code, to potentially add a command line and
+ fill the CPU topology nodes. It will also be passed on to BL33, by
+ putting its address into the x0 register before jumping to the entry
+ point (following the Linux kernel boot protocol).
+ It defaults to 0x80070000, which is 64KB before the BL33 load address.
+
+- ``FPGA_PRELOADED_CMD_LINE`` : Physical address of the command line to
+ put into the devicetree blob. Due to the lack of a proper bootloader,
+ a command line can be put somewhere into memory, so that BL31 will
+ detect it and copy it into the DTB passed on to BL33.
+ To avoid random garbage, there needs to be a "CMD:" signature before the
+ actual command line.
+ Defaults to 0x1000, which is normally in the "ROM" space of the typical
+ FPGA image (which can be written by the FPGA payload uploader, but is
+ read-only to the CPU). The FPGA payload tool should be given a text file
+ containing the desired command line, prefixed by the "CMD:" signature.
+
+Building the TF-A image
+-----------------------
+
+ .. code:: shell
+
+ make PLAT=arm_fgpa DEBUG=1
+
+ This will use the default load addresses as described above. When those
+ addresses need to differ for a certain setup, they can be passed on the
+ make command line:
+
+ .. code:: shell
+
+ make PLAT=arm_fgpa DEBUG=1 PRELOADED_BL33_BASE=0x80200000 FPGA_PRELOADED_DTB_BASE=0x80180000 bl31
+
+Running the TF-A image
+----------------------
+
+After building TF-A, the actual TF-A code will be located in ``bl31.bin`` in
+the build directory.
+Additionally there is a ``bl31.axf`` ELF file, which contains BL31, as well
+as some simple ROM trampoline code (required by the Arm FPGA boot flow) and
+a generic DTB to support most of the FPGA images. This can be simply handed
+over to the FPGA payload uploader, which will take care of loading the
+components at their respective load addresses. In addition to this file
+you need at least a BL33 payload (typically a Linux kernel image), optionally
+a Linux initrd image file and possibly a command line:
+
+ .. code:: shell
+
+ fpga-run ... -m bl31.axf -l auto -m Image -l 0x80080000 -m initrd.gz -l 0x84000000 -m cmdline.txt -l 0x1000
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/plat/arm/corstone1000/index.rst b/docs/plat/arm/corstone1000/index.rst
new file mode 100644
index 0000000..b889b7f
--- /dev/null
+++ b/docs/plat/arm/corstone1000/index.rst
@@ -0,0 +1,61 @@
+Corstone1000 Platform
+==========================
+
+Some of the features of the Corstone1000 platform referenced in TF-A include:
+
+- Cortex-A35 application processor (64-bit mode)
+- Secure Enclave
+- GIC-400
+- Trusted Board Boot
+
+Boot Sequence
+-------------
+
+The board boot relies on CoT (chain of trust). The trusted-firmware-a
+BL2 is extracted from the FIP and verified by the Secure Enclave
+processor. BL2 verification relies on the signature area at the
+beginning of the BL2 image. This area is needed by the SecureEnclave
+bootloader.
+
+Then, the application processor is released from reset and starts by
+executing BL2.
+
+BL2 performs the actions described in the trusted-firmware-a TBB design
+document.
+
+Build Procedure (TF-A only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Obtain AArch64 ELF bare-metal target `toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads>`_.
+ Set the CROSS_COMPILE environment variable to point to the toolchain folder.
+
+- Build TF-A:
+
+ .. code:: shell
+
+ make LD=aarch64-none-elf-ld \
+ CC=aarch64-none-elf-gcc \
+ V=1 \
+ BUILD_BASE=<path to the build folder> \
+ PLAT=corstone1000 \
+ SPD=spmd \
+ SPMD_SPM_AT_SEL2=0 \
+ DEBUG=1 \
+ MBEDTLS_DIR=mbedtls \
+ OPENSSL_DIR=<path to openssl usr folder> \
+ RUNTIME_SYSROOT=<path to the sysroot> \
+ ARCH=aarch64 \
+ TARGET_PLATFORM=<fpga or fvp> \
+ ENABLE_PIE=1 \
+ BL2_AT_EL3=1 \
+ CREATE_KEYS=1 \
+ GENERATE_COT=1 \
+ TRUSTED_BOARD_BOOT=1 \
+ COT=tbbr \
+ ARM_ROTPK_LOCATION=devel_rsa \
+ ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \
+ BL32=<path to optee binary> \
+ BL33=<path to u-boot binary> \
+ bl2
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/plat/arm/fvp-ve/index.rst b/docs/plat/arm/fvp-ve/index.rst
new file mode 100644
index 0000000..8ac0741
--- /dev/null
+++ b/docs/plat/arm/fvp-ve/index.rst
@@ -0,0 +1,84 @@
+Arm Versatile Express
+=====================
+
+Versatile Express (VE) family development platform provides an ultra fast
+environment for prototyping Armv7 System-on-Chip designs. VE Fixed Virtual
+Platforms (FVP) are simulations of Versatile Express boards. The platform in
+Trusted Firmware-A has been verified with Arm Cortex-A5 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>`__
+
+- `Trusted Firmware-A <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git>`__
+
+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/>`__.
+ Set the CROSS_COMPILE environment variable to point to the toolchain folder.
+
+- Fetch and build u-boot.
+ Make the .config file using the command:
+
+ .. code:: shell
+
+ make ARCH=arm vexpress_aemv8a_aarch32_config
+
+ Make the u-boot binary for Cortex-A5 using the command:
+
+ .. code:: shell
+
+ make ARCH=arm SUPPORT_ARCH_TIMER=no
+
+ Make the u-boot binary for Cortex-A7 using the command:
+
+ .. code:: shell
+
+ make ARCH=arm
+
+
+- Build TF-A:
+
+ The make command for Cortex-A5 is:
+
+ .. code:: shell
+
+ make PLAT=fvp_ve ARCH=aarch32 ARM_ARCH_MAJOR=7 ARM_CORTEX_A5=yes \
+ AARCH32_SP=sp_min FVP_HW_CONFIG_DTS=fdts/fvp-ve-Cortex-A5x1.dts \
+ ARM_XLAT_TABLES_LIB_V1=1 BL33=<path_to_u-boot.bin> all fip
+
+ The make command for Cortex-A7 is:
+
+ .. code:: shell
+
+ make PLAT=fvp_ve ARCH=aarch32 ARM_ARCH_MAJOR=7 ARM_CORTEX_A7=yes \
+ AARCH32_SP=sp_min FVP_HW_CONFIG_DTS=fdts/fvp-ve-Cortex-A7x1.dts \
+ BL33=<path_to_u-boot.bin> all fip
+
+Run Procedure
+~~~~~~~~~~~~~
+
+The following model parameters should be used to boot Linux using the build of
+Trusted Firmware-A made using the above make commands:
+
+ .. code:: shell
+
+ ./<path_to_model> <path_to_bl1.elf> \
+ -C motherboard.flashloader1.fname=<path_to_fip.bin> \
+ --data cluster.cpu0=<path_to_zImage>@0x80080000 \
+ --data cluster.cpu0=<path_to_ramdisk>@0x84000000
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/plat/arm/fvp/index.rst b/docs/plat/arm/fvp/index.rst
new file mode 100644
index 0000000..42c0eda
--- /dev/null
+++ b/docs/plat/arm/fvp/index.rst
@@ -0,0 +1,640 @@
+Arm Fixed Virtual Platforms (FVP)
+=================================
+
+Fixed Virtual Platform (FVP) Support
+------------------------------------
+
+This section lists the supported Arm |FVP| platforms. Please refer to the FVP
+documentation for a detailed description of the model parameter options.
+
+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).
+
+.. note::
+ The FVP models used are Version 11.19 Build 14, unless otherwise stated.
+
+- ``Foundation_Platform``
+- ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` (Version 11.17/21)
+- ``FVP_Base_AEMv8A-GIC600AE`` (Version 11.17/21)
+- ``FVP_Base_AEMvA``
+- ``FVP_Base_AEMvA-AEMvA``
+- ``FVP_Base_Cortex-A32x4`` (Version 11.12/38)
+- ``FVP_Base_Cortex-A35x4``
+- ``FVP_Base_Cortex-A53x4``
+- ``FVP_Base_Cortex-A55``
+- ``FVP_Base_Cortex-A55x4+Cortex-A75x4``
+- ``FVP_Base_Cortex-A55x4+Cortex-A76x2``
+- ``FVP_Base_Cortex-A57x1-A53x1``
+- ``FVP_Base_Cortex-A57x2-A53x4``
+- ``FVP_Base_Cortex-A57x4``
+- ``FVP_Base_Cortex-A57x4-A53x4``
+- ``FVP_Base_Cortex-A65``
+- ``FVP_Base_Cortex-A65AE``
+- ``FVP_Base_Cortex-A710x4`` (Version 11.17/21)
+- ``FVP_Base_Cortex-A72x4``
+- ``FVP_Base_Cortex-A72x4-A53x4``
+- ``FVP_Base_Cortex-A73x4``
+- ``FVP_Base_Cortex-A73x4-A53x4``
+- ``FVP_Base_Cortex-A75``
+- ``FVP_Base_Cortex-A76``
+- ``FVP_Base_Cortex-A76AE``
+- ``FVP_Base_Cortex-A77``
+- ``FVP_Base_Cortex-A78``
+- ``FVP_Base_Cortex-A78C``
+- ``FVP_Base_Cortex-X2x4`` (Version 11.17/21)
+- ``FVP_Base_Neoverse-E1``
+- ``FVP_Base_Neoverse-N1``
+- ``FVP_Base_Neoverse-N2x4`` (Version 11.16/16)
+- ``FVP_Base_Neoverse-V1``
+- ``FVP_Base_RevC-2xAEMvA``
+- ``FVP_Morello`` (Version 0.11/33)
+- ``FVP_RD_E1_edge`` (Version 11.17/29)
+- ``FVP_RD_V1`` (Version 11.17/29)
+- ``FVP_TC0`` (Version 11.17/18)
+- ``FVP_TC1`` (Version 11.17/33)
+- ``FVP_TC2`` (Version 11.18/28)
+
+The latest version of the AArch32 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).
+
+- ``FVP_Base_AEMvA``
+- ``FVP_Base_AEMvA-AEMvA``
+- ``FVP_Base_Cortex-A32x4``
+
+.. note::
+ The ``FVP_Base_RevC-2xAEMvA`` FVP only supports shifted affinities, which
+ is not compatible with legacy GIC configurations. Therefore this FVP does not
+ support these legacy GIC configurations.
+
+The *Foundation* and *Base* FVPs can be downloaded free of charge. See the `Arm
+FVP website`_. The Cortex-A models listed above are also available to download
+from `Arm's website`_.
+
+.. note::
+ The build numbers quoted above are those reported by launching the FVP
+ with the ``--version`` parameter.
+
+.. note::
+ Linaro provides a ramdisk image in prebuilt FVP configurations and full
+ file systems that can be downloaded separately. To run an FVP with a virtio
+ file system image an additional FVP configuration option
+ ``-C bp.virtioblockdevice.image_path="<path-to>/<file-system-image>`` can be
+ used.
+
+.. note::
+ The software will not work on Version 1.0 of the Foundation FVP.
+ The commands below would report an ``unhandled argument`` error in this case.
+
+.. note::
+ FVPs can be launched with ``--cadi-server`` option such that a
+ CADI-compliant debugger (for example, Arm DS-5) can connect to and control
+ 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.
+
+All the above platforms have been tested with `Linaro Release 20.01`_.
+
+.. _build_options_arm_fvp_platform:
+
+Arm FVP Platform Specific Build Options
+---------------------------------------
+
+- ``FVP_CLUSTER_COUNT`` : Configures the cluster count to be used to
+ build the topology tree within TF-A. By default TF-A is configured for dual
+ cluster topology and this option can be used to override the default value.
+
+- ``FVP_INTERCONNECT_DRIVER``: Selects the interconnect driver to be built. The
+ default interconnect driver depends on the value of ``FVP_CLUSTER_COUNT`` as
+ explained in the options below:
+
+ - ``FVP_CCI`` : The CCI driver is selected. This is the default
+ if 0 < ``FVP_CLUSTER_COUNT`` <= 2.
+ - ``FVP_CCN`` : The CCN driver is selected. This is the default
+ if ``FVP_CLUSTER_COUNT`` > 2.
+
+- ``FVP_MAX_CPUS_PER_CLUSTER``: Sets the maximum number of CPUs implemented in
+ a single cluster. This option defaults to 4.
+
+- ``FVP_MAX_PE_PER_CPU``: Sets the maximum number of PEs implemented on any CPU
+ in the system. This option defaults to 1. Note that the build option
+ ``ARM_PLAT_MT`` doesn't have any effect on FVP platforms.
+
+- ``FVP_USE_GIC_DRIVER`` : Selects the GIC driver to be built. Options:
+
+ - ``FVP_GICV2`` : The GICv2 only driver is selected
+ - ``FVP_GICV3`` : The GICv3 only driver is selected (default option)
+
+- ``FVP_HW_CONFIG_DTS`` : Specify the path to the DTS file to be compiled
+ to DTB and packaged in FIP as the HW_CONFIG. See :ref:`Firmware Design` for
+ details on HW_CONFIG. By default, this is initialized to a sensible DTS
+ file in ``fdts/`` folder depending on other build options. But some cases,
+ like shifted affinity format for MPIDR, cannot be detected at build time
+ and this option is needed to specify the appropriate DTS file.
+
+- ``FVP_HW_CONFIG`` : Specify the path to the HW_CONFIG blob to be packaged in
+ FIP. See :ref:`Firmware Design` for details on HW_CONFIG. This option is
+ similar to the ``FVP_HW_CONFIG_DTS`` option, but it directly specifies the
+ HW_CONFIG blob instead of the DTS file. This option is useful to override
+ the default HW_CONFIG selected by the build system.
+
+- ``FVP_GICR_REGION_PROTECTION``: Mark the redistributor pages of
+ inactive/fused CPU cores as read-only. The default value of this option
+ is ``0``, which means the redistributor pages of all CPU cores are marked
+ as read and write.
+
+Booting Firmware Update images
+------------------------------
+
+When Firmware Update (FWU) is enabled there are at least 2 new images
+that have to be loaded, the Non-Secure FWU ROM (NS-BL1U), and the
+FWU FIP.
+
+The additional fip images must be loaded with:
+
+::
+
+ --data cluster0.cpu0="<path_to>/ns_bl1u.bin"@0x0beb8000 [ns_bl1u_base_address]
+ --data cluster0.cpu0="<path_to>/fwu_fip.bin"@0x08400000 [ns_bl2u_base_address]
+
+The address ns_bl1u_base_address is the value of NS_BL1U_BASE.
+In the same way, the address ns_bl2u_base_address is the value of
+NS_BL2U_BASE.
+
+Booting an EL3 payload
+----------------------
+
+The EL3 payloads boot flow requires the CPU's mailbox to be cleared at reset for
+the secondary CPUs holding pen to work properly. Unfortunately, its reset value
+is undefined on the FVP platform and the FVP platform code doesn't clear it.
+Therefore, one must modify the way the model is normally invoked in order to
+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
+
+and pre-load it into the FVP memory at the mailbox address (i.e. ``0x04000000``)
+using the following model parameters:
+
+::
+
+ --data cluster0.cpu0=mailbox.dat@0x04000000 [Base FVPs]
+ --data=mailbox.dat@0x04000000 [Foundation FVP]
+
+To provide the model with the EL3 payload image, the following methods may be
+used:
+
+#. If the EL3 payload is able to execute in place, it may be programmed into
+ flash memory. On Base Cortex and AEM FVPs, the following model parameter
+ loads it at the base address of the NOR FLASH1 (the NOR FLASH0 is already
+ used for the FIP):
+
+ ::
+
+ -C bp.flashloader1.fname="<path-to>/<el3-payload>"
+
+ On Foundation FVP, there is no flash loader component and the EL3 payload
+ may be programmed anywhere in flash using method 3 below.
+
+#. When using the ``SPIN_ON_BL1_EXIT=1`` loading method, the following DS-5
+ command may be used to load the EL3 payload ELF image over JTAG:
+
+ ::
+
+ load <path-to>/el3-payload.elf
+
+#. The EL3 payload may be pre-loaded in volatile memory using the following
+ model parameters:
+
+ ::
+
+ --data cluster0.cpu0="<path-to>/el3-payload>"@address [Base FVPs]
+ --data="<path-to>/<el3-payload>"@address [Foundation FVP]
+
+ The address provided to the FVP must match the ``EL3_PAYLOAD_BASE`` address
+ used when building TF-A.
+
+Booting a preloaded kernel image (Base FVP)
+-------------------------------------------
+
+The following example uses a simplified boot flow by directly jumping from the
+TF-A to the Linux kernel, which will use a ramdisk as filesystem. This can be
+useful if both the kernel and the device tree blob (DTB) are already present in
+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-none-elf- \
+ make PLAT=fvp DEBUG=1 \
+ RESET_TO_BL31=1 \
+ ARM_LINUX_KERNEL_AS_BL33=1 \
+ PRELOADED_BL33_BASE=0x80080000 \
+ ARM_PRELOADED_DTB_BASE=0x82000000 \
+ all fip
+
+Now, it is needed to modify the DTB so that the kernel knows the address of the
+ramdisk. The following script generates a patched DTB from the provided one,
+assuming that the ramdisk is loaded at address ``0x84000000``. Note that this
+script assumes that the user is using a ramdisk image prepared for U-Boot, like
+the ones provided by Linaro. If using a ramdisk without this header,the ``0x40``
+offset in ``INITRD_START`` has to be removed.
+
+.. code:: bash
+
+ #!/bin/bash
+
+ # Path to the input DTB
+ KERNEL_DTB=<path-to>/<fdt>
+ # Path to the output DTB
+ PATCHED_KERNEL_DTB=<path-to>/<patched-fdt>
+ # Base address of the ramdisk
+ INITRD_BASE=0x84000000
+ # Path to the ramdisk
+ INITRD=<path-to>/<ramdisk.img>
+
+ # Skip uboot header (64 bytes)
+ INITRD_START=$(printf "0x%x" $((${INITRD_BASE} + 0x40)) )
+ INITRD_SIZE=$(stat -Lc %s ${INITRD})
+ INITRD_END=$(printf "0x%x" $((${INITRD_BASE} + ${INITRD_SIZE})) )
+
+ CHOSEN_NODE=$(echo \
+ "/ { \
+ chosen { \
+ linux,initrd-start = <${INITRD_START}>; \
+ linux,initrd-end = <${INITRD_END}>; \
+ }; \
+ };")
+
+ echo $(dtc -O dts -I dtb ${KERNEL_DTB}) ${CHOSEN_NODE} | \
+ dtc -O dtb -o ${PATCHED_KERNEL_DTB} -
+
+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 \
+ -C bp.secure_memory=1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster1.NUM_CORES=4 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.RVBAR=0x04001000 \
+ -C cluster0.cpu1.RVBAR=0x04001000 \
+ -C cluster0.cpu2.RVBAR=0x04001000 \
+ -C cluster0.cpu3.RVBAR=0x04001000 \
+ -C cluster1.cpu0.RVBAR=0x04001000 \
+ -C cluster1.cpu1.RVBAR=0x04001000 \
+ -C cluster1.cpu2.RVBAR=0x04001000 \
+ -C cluster1.cpu3.RVBAR=0x04001000 \
+ --data cluster0.cpu0="<path-to>/bl31.bin"@0x04001000 \
+ --data cluster0.cpu0="<path-to>/<patched-fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk.img>"@0x84000000
+
+Obtaining the Flattened Device Trees
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Depending on the FVP configuration and Linux configuration used, different
+FDT files are required. FDT source files for the Foundation and Base FVPs can
+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
+ 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
+FIP. A default FDT is packaged into FIP during the build based on
+the build configuration. This can be overridden by using the ``FVP_HW_CONFIG``
+or ``FVP_HW_CONFIG_DTS`` build options (refer to
+:ref:`build_options_arm_fvp_platform` for details on the options).
+
+- ``fvp-base-gicv2-psci.dts``
+
+ For use with models such as the Cortex-A57-A53 or Cortex-A32 Base FVPs
+ without shifted affinities and with Base memory map configuration.
+
+- ``fvp-base-gicv3-psci.dts``
+
+ For use with models such as the Cortex-A57-A53 or Cortex-A32 Base FVPs
+ without shifted affinities and with Base memory map configuration and
+ Linux GICv3 support.
+
+- ``fvp-base-gicv3-psci-1t.dts``
+
+ For use with models such as the AEMv8-RevC Base FVP with shifted affinities,
+ single threaded CPUs, Base memory map configuration and Linux GICv3 support.
+
+- ``fvp-base-gicv3-psci-dynamiq.dts``
+
+ For use with models as the Cortex-A55-A75 Base FVPs with shifted affinities,
+ single cluster, single threaded CPUs, Base memory map configuration and Linux
+ GICv3 support.
+
+- ``fvp-foundation-gicv2-psci.dts``
+
+ For use with Foundation FVP with Base memory map configuration.
+
+- ``fvp-foundation-gicv3-psci.dts``
+
+ (Default) For use with Foundation FVP with Base memory map configuration
+ and Linux GICv3 support.
+
+
+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 \
+ --arm-v8.0 \
+ --secure-memory \
+ --visualization \
+ --gicv3 \
+ --data="<path-to>/<bl1-binary>"@0x0 \
+ --data="<path-to>/<FIP-binary>"@0x08000000 \
+ --data="<path-to>/<kernel-binary>"@0x80080000 \
+ --data="<path-to>/<ramdisk-binary>"@0x84000000
+
+Notes:
+
+- BL1 is loaded at the start of the Trusted ROM.
+- The Firmware Image Package is loaded at the start of NOR FLASH0.
+- The firmware loads the FDT packaged in FIP to the DRAM. The FDT load address
+ is specified via the ``load-address`` property in the ``hw-config`` node of
+ `FW_CONFIG for FVP`_.
+- The default use-case for the Foundation FVP is to use the ``--gicv3`` option
+ and enable the GICv3 device in the model. Note that without this option,
+ the Foundation FVP defaults to legacy (Versatile Express) memory map which
+ is not supported by TF-A.
+- In order for TF-A to run correctly on the Foundation FVP, the architecture
+ versions must match. The Foundation FVP defaults to the highest v8.x
+ version it supports but the default build for TF-A is for v8.0. To avoid
+ issues either start the Foundation FVP to use v8.0 architecture using the
+ ``--arm-v8.0`` option, or build TF-A with an appropriate value for
+ ``ARM_ARCH_MINOR``.
+
+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 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster1.NUM_CORES=4 \
+ -C cache_state_modelled=1 \
+ -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
+ -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
+ --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 specific DTS for all the CPUs to be loaded.
+
+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 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster1.NUM_CORES=4 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.CONFIG64=0 \
+ -C cluster0.cpu1.CONFIG64=0 \
+ -C cluster0.cpu2.CONFIG64=0 \
+ -C cluster0.cpu3.CONFIG64=0 \
+ -C cluster1.cpu0.CONFIG64=0 \
+ -C cluster1.cpu1.CONFIG64=0 \
+ -C cluster1.cpu2.CONFIG64=0 \
+ -C cluster1.cpu3.CONFIG64=0 \
+ -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
+ -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+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 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cache_state_modelled=1 \
+ -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
+ -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+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 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cache_state_modelled=1 \
+ -C bp.secureflashloader.fname="<path-to>/<bl1-binary>" \
+ -C bp.flashloader0.fname="<path-to>/<FIP-binary>" \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+
+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 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster1.NUM_CORES=4 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.RVBAR=0x04010000 \
+ -C cluster0.cpu1.RVBAR=0x04010000 \
+ -C cluster0.cpu2.RVBAR=0x04010000 \
+ -C cluster0.cpu3.RVBAR=0x04010000 \
+ -C cluster1.cpu0.RVBAR=0x04010000 \
+ -C cluster1.cpu1.RVBAR=0x04010000 \
+ -C cluster1.cpu2.RVBAR=0x04010000 \
+ -C cluster1.cpu3.RVBAR=0x04010000 \
+ --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04010000 \
+ --data cluster0.cpu0="<path-to>/<bl32-binary>"@0xff000000 \
+ --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+Notes:
+
+- Position Independent Executable (PIE) support is enabled in this
+ config allowing BL31 to be loaded at any valid address for execution.
+
+- Since a FIP is not loaded when using BL31 as reset entrypoint, the
+ ``--data="<path-to><bl31|bl32|bl33-binary>"@<base-address-of-binary>``
+ parameter is needed to load the individual bootloader images in memory.
+ BL32 image is only needed if BL31 has been built to expect a Secure-EL1
+ Payload. For the same reason, the FDT needs to be compiled from the DT source
+ and loaded via the ``--data cluster0.cpu0="<path-to>/<fdt>"@0x82000000``
+ parameter.
+
+- The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a
+ specific DTS for all the CPUs to be loaded.
+
+- The ``-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>`` parameter, where
+ X and Y are the cluster and CPU numbers respectively, is used to set the
+ reset vector for each core.
+
+- Changing the default value of ``ARM_TSP_RAM_LOCATION`` will also require
+ changing the value of
+ ``--data="<path-to><bl32-binary>"@<base-address-of-bl32>`` to the new value of
+ ``BL32_BASE``.
+
+
+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 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cluster0.NUM_CORES=4 \
+ -C cluster1.NUM_CORES=4 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.CONFIG64=0 \
+ -C cluster0.cpu1.CONFIG64=0 \
+ -C cluster0.cpu2.CONFIG64=0 \
+ -C cluster0.cpu3.CONFIG64=0 \
+ -C cluster1.cpu0.CONFIG64=0 \
+ -C cluster1.cpu1.CONFIG64=0 \
+ -C cluster1.cpu2.CONFIG64=0 \
+ -C cluster1.cpu3.CONFIG64=0 \
+ -C cluster0.cpu0.RVBAR=0x04002000 \
+ -C cluster0.cpu1.RVBAR=0x04002000 \
+ -C cluster0.cpu2.RVBAR=0x04002000 \
+ -C cluster0.cpu3.RVBAR=0x04002000 \
+ -C cluster1.cpu0.RVBAR=0x04002000 \
+ -C cluster1.cpu1.RVBAR=0x04002000 \
+ -C cluster1.cpu2.RVBAR=0x04002000 \
+ -C cluster1.cpu3.RVBAR=0x04002000 \
+ --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04002000 \
+ --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+.. note::
+ Position Independent Executable (PIE) support is enabled in this
+ config allowing SP_MIN to be loaded at any valid address for execution.
+
+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 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.RVBARADDR=0x04010000 \
+ -C cluster0.cpu1.RVBARADDR=0x04010000 \
+ -C cluster0.cpu2.RVBARADDR=0x04010000 \
+ -C cluster0.cpu3.RVBARADDR=0x04010000 \
+ -C cluster1.cpu0.RVBARADDR=0x04010000 \
+ -C cluster1.cpu1.RVBARADDR=0x04010000 \
+ -C cluster1.cpu2.RVBARADDR=0x04010000 \
+ -C cluster1.cpu3.RVBARADDR=0x04010000 \
+ --data cluster0.cpu0="<path-to>/<bl31-binary>"@0x04010000 \
+ --data cluster0.cpu0="<path-to>/<bl32-binary>"@0xff000000 \
+ --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+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 \
+ -C bp.secure_memory=1 \
+ -C bp.tzc_400.diagnostics=1 \
+ -C cache_state_modelled=1 \
+ -C cluster0.cpu0.RVBARADDR=0x04002000 \
+ -C cluster0.cpu1.RVBARADDR=0x04002000 \
+ -C cluster0.cpu2.RVBARADDR=0x04002000 \
+ -C cluster0.cpu3.RVBARADDR=0x04002000 \
+ --data cluster0.cpu0="<path-to>/<bl32-binary>"@0x04002000 \
+ --data cluster0.cpu0="<path-to>/<bl33-binary>"@0x88000000 \
+ --data cluster0.cpu0="<path-to>/<fdt>"@0x82000000 \
+ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \
+ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000
+
+--------------
+
+*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*
+
+.. _FW_CONFIG for FVP: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_fw_config.dts
+.. _Arm's website: `FVP models`_
+.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms
+.. _Linaro Release 20.01: http://releases.linaro.org/members/arm/platforms/20.01
+.. _Arm FVP website: https://developer.arm.com/products/system-design/fixed-virtual-platforms
diff --git a/docs/plat/arm/fvp_r/index.rst b/docs/plat/arm/fvp_r/index.rst
new file mode 100644
index 0000000..8af16ba
--- /dev/null
+++ b/docs/plat/arm/fvp_r/index.rst
@@ -0,0 +1,46 @@
+ARM V8-R64 Fixed Virtual Platform (FVP)
+=======================================
+
+Some of the features of Armv8-R AArch64 FVP platform referenced in Trusted
+Boot R-class include:
+
+- Secure World Support Only
+- EL2 as Maximum EL support (No EL3)
+- MPU Support only at EL2
+- MPU or MMU Support at EL0/EL1
+- AArch64 Support Only
+- Trusted Board Boot
+
+Further information on v8-R64 FVP is available at `info <https://developer.arm.com/documentation/ddi0600/latest/>`_
+
+Boot Sequence
+-------------
+
+BL1 –> BL33
+
+The execution begins from BL1 which loads the BL33 image, a boot-wrapped (bootloader + Operating System)
+Operating System, from FIP to DRAM.
+
+Build Procedure
+~~~~~~~~~~~~~~~
+
+- Obtain arm `toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads>`_.
+ Set the CROSS_COMPILE environment variable to point to the toolchain folder.
+
+- Build TF-A:
+
+ .. code:: shell
+
+ make PLAT=fvp_r BL33=<path_to_os.bin> all fip
+
+ Enable TBBR by adding the following options to the make command:
+
+ .. code:: shell
+
+ MBEDTLS_DIR=<path_to_mbedtls_directory> \
+ TRUSTED_BOARD_BOOT=1 \
+ GENERATE_COT=1 \
+ ARM_ROTPK_LOCATION=devel_rsa \
+ ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/plat/arm/index.rst b/docs/plat/arm/index.rst
new file mode 100644
index 0000000..2f68522
--- /dev/null
+++ b/docs/plat/arm/index.rst
@@ -0,0 +1,24 @@
+Arm Development Platforms
+=========================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+
+ juno/index
+ fvp/index
+ fvp_r/index
+ fvp-ve/index
+ tc/index
+ arm_fpga/index
+ arm-build-options
+ morello/index
+ corstone1000/index
+
+This chapter holds documentation related to Arm's development platforms,
+including both software models (FVPs) and hardware development boards
+such as Juno.
+
+--------------
+
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/plat/arm/juno/index.rst b/docs/plat/arm/juno/index.rst
new file mode 100644
index 0000000..91e681f
--- /dev/null
+++ b/docs/plat/arm/juno/index.rst
@@ -0,0 +1,253 @@
+Arm Juno Development Platform
+=============================
+
+Platform-specific build options
+-------------------------------
+
+- ``JUNO_TZMP1`` : Boolean option to configure Juno to be used for TrustZone
+ Media Protection (TZ-MP1). Default value of this flag is 0.
+
+Running software on Juno
+------------------------
+
+This version of TF-A has been tested on variants r0, r1 and r2 of Juno.
+
+To run TF-A on Juno, you need to first prepare an SD card with Juno software
+stack that includes TF-A. This version of TF-A is tested with pre-built
+`Linaro release software stack`_ version 20.01. You can alternatively
+build the software stack yourself by following the
+`Juno platform software user guide`_. Once you prepare the software stack
+on an SD card, you can replace the ``bl1.bin`` and ``fip.bin``
+binaries in the ``SOFTWARE/`` directory with custom built TF-A binaries.
+
+Preparing TF-A images
+---------------------
+
+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 software stack has been
+installed.
+
+.. note::
+ Pre-built binaries for AArch32 are available from Linaro Release 16.12
+ onwards. Before that release, pre-built binaries are only available for
+ AArch64.
+
+.. warning::
+ Follow the full instructions for one platform before switching to a
+ different one. Mixing instructions for different platforms may result in
+ corrupted binaries.
+
+.. warning::
+ The uboot image downloaded by the Linaro workspace script does not always
+ match the uboot image packaged as BL33 in the corresponding fip file. It is
+ 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
+ by the firmware at runtime.
+
+#. Clean the working directory
+
+ .. code:: shell
+
+ make realclean
+
+#. Obtain SCP binaries (Juno)
+
+ This version of TF-A is tested with SCP version 2.8.0 on Juno. You can
+ download pre-built SCP binaries (``scp_bl1.bin`` and ``scp_bl2.bin``)
+ from `TF-A downloads page`_. Alternatively, you can `build
+ the binaries from source`_.
+
+#. Obtain BL33 (all platforms)
+
+ Use the fiptool to extract the BL33 image from the FIP
+ package included in the Linaro release:
+
+ .. code:: shell
+
+ # Build the fiptool
+ make [DEBUG=1] [V=1] fiptool
+
+ # Unpack firmware images from Linaro FIP
+ ./tools/fiptool/fiptool unpack <path-to-linaro-release>/[SOFTWARE]/fip.bin
+
+ The unpack operation will result in a set of binary images extracted to the
+ current working directory. BL33 corresponds to ``nt-fw.bin``.
+
+ .. note::
+ The fiptool will complain if the images to be unpacked already
+ 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 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
+
+ # AArch32
+ make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=nt-fw.bin all fip
+
+#. Build TF-A images and create a new FIP for Juno
+
+ For AArch64:
+
+ 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_bl2.bin all fip
+
+ For AArch32:
+
+ Hardware restrictions on Juno prevent cold reset into AArch32 execution mode,
+ therefore BL1 and BL2 must be compiled for AArch64, and BL32 is compiled
+ separately for AArch32.
+
+ - 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
+
+ - Save ``bl32.bin`` to a temporary location and clean the build products.
+
+ ::
+
+ cp <path-to-build>/bl32.bin <path-to-temporary>
+ make realclean
+
+ - 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-none-elf-
+
+ - 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_bl2.bin \
+ BL32=<path-to-temporary>/bl32.bin all fip
+
+The resulting BL1 and FIP images may be found in:
+
+::
+
+ # Juno
+ ./build/juno/release/bl1.bin
+ ./build/juno/release/fip.bin
+
+ # FVP
+ ./build/fvp/release/bl1.bin
+ ./build/fvp/release/fip.bin
+
+After building TF-A, the files ``bl1.bin``, ``fip.bin`` and ``scp_bl1.bin``
+need to be copied to the ``SOFTWARE/`` directory on the Juno SD card.
+
+Booting Firmware Update images
+------------------------------
+
+The new images must be programmed in flash memory by adding
+an entry in the ``SITE1/HBI0262x/images.txt`` configuration file
+on the Juno SD card (where ``x`` depends on the revision of the Juno board).
+Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory
+programming" for more information. User should ensure these do not
+overlap with any other entries in the file.
+
+::
+
+ NOR10UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ NOR10ADDRESS: 0x00400000 ;Image Flash Address [ns_bl2u_base_address]
+ NOR10FILE: \SOFTWARE\fwu_fip.bin ;Image File Name
+ NOR10LOAD: 00000000 ;Image Load Address
+ NOR10ENTRY: 00000000 ;Image Entry Point
+
+ NOR11UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE
+ NOR11ADDRESS: 0x03EB8000 ;Image Flash Address [ns_bl1u_base_address]
+ NOR11FILE: \SOFTWARE\ns_bl1u.bin ;Image File Name
+ NOR11LOAD: 00000000 ;Image Load Address
+
+The address ns_bl1u_base_address is the value of NS_BL1U_BASE - 0x8000000.
+In the same way, the address ns_bl2u_base_address is the value of
+NS_BL2U_BASE - 0x8000000.
+
+.. _plat_juno_booting_el3_payload:
+
+Booting an EL3 payload
+----------------------
+
+If the EL3 payload is able to execute in place, it may be programmed in flash
+memory by adding an entry in the ``SITE1/HBI0262x/images.txt`` configuration file
+on the Juno SD card (where ``x`` depends on the revision of the Juno board).
+Refer to the `Juno Getting Started Guide`_, section 2.3 "Flash memory
+programming" for more information.
+
+Alternatively, the same DS-5 command mentioned in the FVP section above can
+be used to load the EL3 payload's ELF file over JTAG on Juno.
+
+For more information on EL3 payloads in general, see
+:ref:`alt_boot_flows_el3_payload`.
+
+Booting a preloaded kernel image
+--------------------------------
+
+The Trusted Firmware must be compiled in a similar way as for FVP explained
+above. The process to load binaries to memory is the one explained in
+`plat_juno_booting_el3_payload`_.
+
+Testing System Suspend
+----------------------
+
+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
+
+The Juno board should suspend to RAM and then wakeup after 10 seconds due to
+wakeup interrupt from RTC.
+
+Additional Resources
+--------------------
+
+Please visit the `Arm Platforms Portal`_ to get support and obtain any other Juno
+software information. Please also refer to the `Juno Getting Started Guide`_ to
+get more detailed information about the Juno Arm development platform and how to
+configure it.
+
+--------------
+
+*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*
+
+.. _Linaro release software stack: http://releases.linaro.org/members/arm/platforms/
+.. _Juno platform software user guide: https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/about/docs/juno/user-guide.rst
+.. _TF-A downloads page: https://downloads.trustedfirmware.org/tf-a/css_scp_2.8.0/juno/
+.. _build the binaries from source: https://github.com/ARM-software/SCP-firmware/blob/master/user_guide.md#scp-firmware-user-guide
+.. _Arm Platforms Portal: https://community.arm.com/dev-platforms/
+.. _Juno Getting Started Guide: https://developer.arm.com/documentation/den0928/f/?lang=en
+.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
+.. _Juno Arm Development Platform: http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php
diff --git a/docs/plat/arm/morello/index.rst b/docs/plat/arm/morello/index.rst
new file mode 100644
index 0000000..b18001c
--- /dev/null
+++ b/docs/plat/arm/morello/index.rst
@@ -0,0 +1,33 @@
+Morello Platform
+================
+
+Morello is an ARMv8-A platform that implements the capability architecture extension.
+The platform port present at `site <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git>`_
+provides ARMv8-A architecture enablement.
+
+Capability architecture specific changes will be added `here <https://git.morello-project.org/morello>`_
+
+Further information on Morello Platform is available at `info <https://developer.arm.com/architectures/cpu-architecture/a-profile/morello>`_
+
+Boot Sequence
+-------------
+
+The execution begins from SCP_BL1 which loads the SCP_BL2 and starts its
+execution. SCP_BL2 powers up the AP which starts execution at AP_BL31. The AP
+then continues executing and hands off execution to Non-secure world (UEFI).
+
+Build Procedure (TF-A only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Obtain arm `toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads>`_.
+ Set the CROSS_COMPILE environment variable to point to the toolchain folder.
+
+- Build TF-A:
+
+ .. code:: shell
+
+ export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-
+
+ make PLAT=morello all
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/plat/arm/tc/index.rst b/docs/plat/arm/tc/index.rst
new file mode 100644
index 0000000..df1847d
--- /dev/null
+++ b/docs/plat/arm/tc/index.rst
@@ -0,0 +1,63 @@
+TC Total Compute Platform
+==========================
+
+Some of the features of TC platform referenced in TF-A include:
+
+- A `System Control Processor <https://github.com/ARM-software/SCP-firmware>`_
+ to abstract power and system management tasks away from application
+ processors. The RAM firmware for SCP is included in the TF-A FIP and is
+ loaded by AP BL2 from FIP in flash to SRAM for copying by SCP (SCP has access
+ to AP SRAM).
+- GICv4
+- Trusted Board Boot
+- SCMI
+- MHUv2
+
+Currently, the main difference between TC0 (TARGET_PLATFORM=0), TC1
+(TARGET_PLATFORM=1), TC2 (TARGET_PLATFORM=2) platforms w.r.t to TF-A
+is the CPUs supported as below:
+
+- TC0 has support for Cortex A510, Cortex A710 and Cortex X2.
+- TC1 has support for Cortex A510, Cortex Makalu and Cortex X3.
+- TC2 has support for Hayes and Hunter Arm CPUs.
+
+
+Boot Sequence
+-------------
+
+The execution begins from SCP_BL1. SCP_BL1 powers up the AP which starts
+executing AP_BL1 and then executes AP_BL2 which loads the SCP_BL2 from
+FIP to SRAM. The SCP has access to AP SRAM. The address and size of SCP_BL2
+is communicated to SCP using SDS. SCP copies SCP_BL2 from SRAM to its own
+RAM and starts executing it. The AP then continues executing the rest of TF-A
+stages including BL31 runtime stage and hands off executing to
+Non-secure world (u-boot).
+
+Build Procedure (TF-A only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Obtain `Arm toolchain`_ and set the CROSS_COMPILE environment variable to
+ point to the toolchain folder.
+
+- Build TF-A:
+
+ .. code:: shell
+
+ make PLAT=tc BL33=<path_to_uboot.bin> \
+ SCP_BL2=<path_to_scp_ramfw.bin> TARGET_PLATFORM={0,1,2} all fip
+
+ Enable TBBR by adding the following options to the make command:
+
+ .. code:: shell
+
+ MBEDTLS_DIR=<path_to_mbedtls_directory> \
+ TRUSTED_BOARD_BOOT=1 \
+ GENERATE_COT=1 \
+ ARM_ROTPK_LOCATION=devel_rsa \
+ ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem
+
+--------------
+
+*Copyright (c) 2020-2022, Arm Limited. All rights reserved.*
+
+.. _Arm Toolchain: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads
diff --git a/docs/plat/brcm-stingray.rst b/docs/plat/brcm-stingray.rst
new file mode 100644
index 0000000..95029cc
--- /dev/null
+++ b/docs/plat/brcm-stingray.rst
@@ -0,0 +1,43 @@
+Broadcom Stingray
+=================
+
+Description
+-----------
+Broadcom's Stingray(BCM958742t) is a multi-core processor with 8 Cortex-A72 cores.
+Trusted Firmware-A (TF-A) is used to implement secure world firmware, supporting
+BL2 and BL31 for Broadcom Stingray SoCs.
+
+On Poweron, Boot ROM will load bl2 image and Bl2 will initialize the hardware,
+then loads bl31 and bl33 into DDR and boots to bl33.
+
+Boot Sequence
+-------------
+
+Bootrom --> TF-A BL2 --> TF-A BL31 --> BL33(u-boot)
+
+Code Locations
+~~~~~~~~~~~~~~
+- Trusted Firmware-A:
+ `link <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/>`__
+
+How to build
+------------
+
+Build Procedure
+~~~~~~~~~~~~~~~
+
+- Prepare AARCH64 toolchain.
+
+- Build u-boot first, and get the binary image: u-boot.bin,
+
+- Build TF-A
+
+ Build fip:
+
+ .. code:: shell
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=stingray BOARD_CFG=bcm958742t all fip BL33=u-boot.bin
+
+Deploy TF-A Images
+~~~~~~~~~~~~~~~~~~
+The u-boot will be upstreamed soon, this doc will be updated once they are ready, and the link will be posted.
diff --git a/docs/plat/hikey.rst b/docs/plat/hikey.rst
new file mode 100644
index 0000000..6c488b8
--- /dev/null
+++ b/docs/plat/hikey.rst
@@ -0,0 +1,155 @@
+HiKey
+=====
+
+HiKey is one of 96boards. Hisilicon Kirin6220 processor is installed on HiKey.
+
+More information are listed in `link`_.
+
+How to build
+------------
+
+Code Locations
+~~~~~~~~~~~~~~
+
+- Trusted Firmware-A:
+ `link <https://github.com/ARM-software/arm-trusted-firmware>`__
+
+- OP-TEE
+ `link <https://github.com/OP-TEE/optee_os>`__
+
+- edk2:
+ `link <https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5>`__
+
+- OpenPlatformPkg:
+ `link <https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4>`__
+
+- l-loader:
+ `link <https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2>`__
+
+- atf-fastboot:
+ `link <https://github.com/96boards-hikey/atf-fastboot/tree/master>`__
+
+Build Procedure
+~~~~~~~~~~~~~~~
+
+- Fetch all the above repositories into local host.
+ Make all the repositories in the same ${BUILD\_PATH}.
+
+ .. code:: shell
+
+ git clone https://github.com/ARM-software/arm-trusted-firmware -b integration
+ git clone https://github.com/OP-TEE/optee_os
+ git clone https://github.com/96boards-hikey/edk2 -b testing/hikey960_v2.5
+ git clone https://github.com/96boards-hikey/OpenPlatformPkg -b testing/hikey960_v1.3.4
+ git clone https://github.com/96boards-hikey/l-loader -b testing/hikey960_v1.2
+ git clone https://github.com/96boards-hikey/atf-fastboot
+
+- Create the symbol link to OpenPlatformPkg in edk2.
+
+ .. code:: shell
+
+ $cd ${BUILD_PATH}/edk2
+ $ln -sf ../OpenPlatformPkg
+
+- Prepare AARCH64 && AARCH32 toolchain. Prepare python.
+
+- If your hikey hardware is built by CircuitCo, update *OpenPlatformPkg/Platforms/Hisilicon/HiKey/HiKey.dsc* first. *(optional)*
+ console on hikey.**
+
+ .. code:: shell
+
+ DEFINE SERIAL_BASE=0xF8015000
+
+ If your hikey hardware is built by LeMaker, nothing to do.
+
+- Build it as debug mode. Create your own build script file or you could refer to **build\_uefi.sh** in l-loader git repository.
+
+ .. code:: shell
+
+ cd {BUILD_PATH}/arm-trusted-firmware
+ sh ../l-loader/build_uefi.sh hikey
+
+- Generate l-loader.bin and partition table for aosp. The eMMC capacity is either 8GB or 4GB. Just change "aosp-8g" to "linux-8g" for debian.
+
+ .. code:: shell
+
+ cd ${BUILD_PATH}/l-loader
+ ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin
+ ln -sf ${EDK2_OUTPUT_DIR}/FV/bl2.bin
+ ln -sf ${BUILD_PATH}/atf-fastboot/build/hikey/${FASTBOOT_BUILD_OPTION}/bl1.bin fastboot.bin
+ make hikey PTABLE_LST=aosp-8g
+
+Setup Console
+-------------
+
+- Install ser2net. Use telnet as the console since UEFI fails to display Boot Manager GUI in minicom. **If you don't need Boot Manager GUI, just ignore this section.**
+
+ .. code:: shell
+
+ $sudo apt-get install ser2net
+
+- Configure ser2net.
+
+ .. code:: shell
+
+ $sudo vi /etc/ser2net.conf
+
+ Append one line for serial-over-USB in below.
+ *#ser2net.conf*
+
+ .. code:: shell
+
+ 2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner
+
+- Start ser2net
+
+ .. code:: shell
+
+ $sudo killall ser2net
+ $sudo ser2net -u
+
+- Open the console.
+
+ .. code:: shell
+
+ $telnet localhost 2004
+
+ And you could open the console remotely, too.
+
+Flash images in recovery mode
+-----------------------------
+
+- Make sure Pin3-Pin4 on J15 are connected for recovery mode. Then power on HiKey.
+
+- Remove the modemmanager package. This package may cause the idt tool failure.
+
+ .. code:: shell
+
+ $sudo apt-get purge modemmanager
+
+- Run the command to download recovery.bin into HiKey.
+
+ .. code:: shell
+
+ $sudo python hisi-idt.py -d /dev/ttyUSB1 --img1 recovery.bin
+
+- Update images. All aosp or debian images could be fetched from `link <http://releases.linaro.org/96boards/>`__.
+
+ .. code:: shell
+
+ $sudo fastboot flash ptable prm_ptable.img
+ $sudo fastboot flash loader l-loader.bin
+ $sudo fastboot flash fastboot fip.bin
+ $sudo fastboot flash boot boot.img
+ $sudo fastboot flash cache cache.img
+ $sudo fastboot flash system system.img
+ $sudo fastboot flash userdata userdata.img
+
+Boot UEFI in normal mode
+------------------------
+
+- Make sure Pin3-Pin4 on J15 are open for normal boot mode. Then power on HiKey.
+
+- Reference `link <https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md>`__
+
+.. _link: https://www.96boards.org/documentation/consumer/hikey/
diff --git a/docs/plat/hikey960.rst b/docs/plat/hikey960.rst
new file mode 100644
index 0000000..982c2c8
--- /dev/null
+++ b/docs/plat/hikey960.rst
@@ -0,0 +1,180 @@
+HiKey960
+========
+
+HiKey960 is one of 96boards. Hisilicon Hi3660 processor is installed on HiKey960.
+
+More information are listed in `link`_.
+
+How to build
+------------
+
+Code Locations
+~~~~~~~~~~~~~~
+
+- Trusted Firmware-A:
+ `link <https://github.com/ARM-software/arm-trusted-firmware>`__
+
+- OP-TEE:
+ `link <https://github.com/OP-TEE/optee_os>`__
+
+- edk2:
+ `link <https://github.com/96boards-hikey/edk2/tree/testing/hikey960_v2.5>`__
+
+- OpenPlatformPkg:
+ `link <https://github.com/96boards-hikey/OpenPlatformPkg/tree/testing/hikey960_v1.3.4>`__
+
+- l-loader:
+ `link <https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2>`__
+
+Build Procedure
+~~~~~~~~~~~~~~~
+
+- Fetch all the above 5 repositories into local host.
+ Make all the repositories in the same ${BUILD\_PATH}.
+
+ .. code:: shell
+
+ git clone https://github.com/ARM-software/arm-trusted-firmware -b integration
+ git clone https://github.com/OP-TEE/optee_os
+ git clone https://github.com/96boards-hikey/edk2 -b testing/hikey960_v2.5
+ git clone https://github.com/96boards-hikey/OpenPlatformPkg -b testing/hikey960_v1.3.4
+ git clone https://github.com/96boards-hikey/l-loader -b testing/hikey960_v1.2
+
+- Create the symbol link to OpenPlatformPkg in edk2.
+
+ .. code:: shell
+
+ $cd ${BUILD_PATH}/edk2
+ $ln -sf ../OpenPlatformPkg
+
+- Prepare AARCH64 toolchain.
+
+- If your hikey960 hardware is v1, update *OpenPlatformPkg/Platforms/Hisilicon/HiKey960/HiKey960.dsc* first. *(optional)*
+
+ .. code:: shell
+
+ DEFINE SERIAL_BASE=0xFDF05000
+
+ If your hikey960 hardware is v2 or newer, nothing to do.
+
+- Build it as debug mode. Create script file for build.
+
+ .. code:: shell
+
+ cd {BUILD_PATH}/arm-trusted-firmware
+ sh ../l-loader/build_uefi.sh hikey960
+
+- Generate l-loader.bin and partition table.
+ *Make sure that you're using the sgdisk in the l-loader directory.*
+
+ .. code:: shell
+
+ cd ${BUILD_PATH}/l-loader
+ ln -sf ${EDK2_OUTPUT_DIR}/FV/bl1.bin
+ ln -sf ${EDK2_OUTPUT_DIR}/FV/bl2.bin
+ ln -sf ${EDK2_OUTPUT_DIR}/FV/fip.bin
+ ln -sf ${EDK2_OUTPUT_DIR}/FV/BL33_AP_UEFI.fd
+ make hikey960
+
+Setup Console
+-------------
+
+- Install ser2net. Use telnet as the console since UEFI will output window
+ that fails to display in minicom.
+
+ .. code:: shell
+
+ $sudo apt-get install ser2net
+
+- Configure ser2net.
+
+ .. code:: shell
+
+ $sudo vi /etc/ser2net.conf
+
+ Append one line for serial-over-USB in *#ser2net.conf*
+
+ ::
+
+ 2004:telnet:0:/dev/ttyUSB0:115200 8DATABITS NONE 1STOPBIT banner
+
+- Start ser2net
+
+ .. code:: shell
+
+ $sudo killall ser2net
+ $sudo ser2net -u
+
+- Open the console.
+
+ .. code:: shell
+
+ $telnet localhost 2004
+
+ And you could open the console remotely, too.
+
+Boot UEFI in recovery mode
+--------------------------
+
+- Fetch that are used in recovery mode. The code location is in below.
+ `link <https://github.com/96boards-hikey/tools-images-hikey960>`__
+
+- Prepare recovery binary.
+
+ .. code:: shell
+
+ $cd tools-images-hikey960
+ $ln -sf ${BUILD_PATH}/l-loader/l-loader.bin
+ $ln -sf ${BUILD_PATH}/l-loader/fip.bin
+ $ln -sf ${BUILD_PATH}/l-loader/recovery.bin
+
+- Prepare config file.
+
+ .. code:: shell
+
+ $vi config
+ # The content of config file
+ ./sec_usb_xloader.img 0x00020000
+ ./sec_uce_boot.img 0x6A908000
+ ./recovery.bin 0x1AC00000
+
+- Remove the modemmanager package. This package may causes hikey\_idt tool failure.
+
+ .. code:: shell
+
+ $sudo apt-get purge modemmanager
+
+- Run the command to download recovery.bin into HiKey960.
+
+ .. code:: shell
+
+ $sudo ./hikey_idt -c config -p /dev/ttyUSB1
+
+- UEFI running in recovery mode.
+ When prompt '.' is displayed on console, press hotkey 'f' in keyboard. Then Android fastboot app is running.
+ The timeout of prompt '.' is 10 seconds.
+
+- Update images.
+
+ .. code:: shell
+
+ $sudo fastboot flash ptable prm_ptable.img
+ $sudo fastboot flash xloader sec_xloader.img
+ $sudo fastboot flash fastboot l-loader.bin
+ $sudo fastboot flash fip fip.bin
+ $sudo fastboot flash boot boot.img
+ $sudo fastboot flash cache cache.img
+ $sudo fastboot flash system system.img
+ $sudo fastboot flash userdata userdata.img
+
+- Notice: UEFI could also boot kernel in recovery mode, but BL31 isn't loaded in
+ recovery mode.
+
+Boot UEFI in normal mode
+------------------------
+
+- Make sure "Boot Mode" switch is OFF for normal boot mode. Then power on HiKey960.
+
+- Reference `link <https://github.com/96boards-hikey/tools-images-hikey960/blob/master/build-from-source/README-ATF-UEFI-build-from-source.md>`__
+
+.. _link: https://www.96boards.org/documentation/consumer/hikey/hikey960
diff --git a/docs/plat/imx8.rst b/docs/plat/imx8.rst
new file mode 100644
index 0000000..49ba374
--- /dev/null
+++ b/docs/plat/imx8.rst
@@ -0,0 +1,58 @@
+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-,
+dual-, and quad-core families based on the Arm® Cortex®
+architecture—including combined Cortex-A72 + Cortex-A53,
+Cortex-A35, and Cortex-M4 based solutions for advanced graphics,
+imaging, machine vision, audio, voice, video, and safety-critical
+applications.
+
+The i.MX8QM is with 2 Cortex-A72 ARM core, 4 Cortex-A53 ARM core
+and 1 Cortex-M4 system controller.
+
+The i.MX8QX is with 4 Cortex-A35 ARM core and 1 Cortex-M4 system
+controller.
+
+The System Controller (SC) represents the evolution of centralized
+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.
+
+- Build System Controller Firmware and u-boot firstly, and get binary images: scfw_tcm.bin and u-boot.bin
+
+- Build TF-A
+
+ Build bl31:
+
+ .. code:: shell
+
+ CROSS_COMPILE=aarch64-linux-gnu- make PLAT=<Target_SoC> bl31
+
+ Target_SoC should be "imx8qm" for i.MX8QM SoC.
+ 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
+to generate flash.bin, and flash.bin needs to be flashed into SD card
+with certain offset for BOOT ROM. The system controller firmware,
+u-boot and imx-mkimage will be upstreamed soon, this doc will be updated
+once they are ready, and the link will be posted.
+
+.. _i.MX8: https://www.nxp.com/products/processors-and-microcontrollers/applications-processors/i.mx-applications-processors/i.mx-8-processors/i.mx-8-family-arm-cortex-a53-cortex-a72-virtualization-vision-3d-graphics-4k-video:i.MX8
diff --git a/docs/plat/imx8m.rst b/docs/plat/imx8m.rst
new file mode 100644
index 0000000..f8071f7
--- /dev/null
+++ b/docs/plat/imx8m.rst
@@ -0,0 +1,113 @@
+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
+reliability and embedded security needed to drive the growth of fast-growing
+edge node computing, streaming multimedia, and machine learning applications.
+
+imx8mq is dropped in TF-A CI build due to the small OCRAM size, but still actively
+maintained in NXP official release.
+
+Boot Sequence
+-------------
+
+Bootrom --> SPL --> BL31 --> BL33(u-boot) --> Linux kernel
+
+How to build
+------------
+
+Build Procedure
+~~~~~~~~~~~~~~~
+
+- Prepare AARCH64 toolchain.
+
+- Build spl and u-boot firstly, and get binary images: u-boot-spl.bin,
+ u-boot-nodtb.bin and dtb for the target board.
+
+- Build TF-A
+
+ Build bl31:
+
+ .. code:: shell
+
+ CROSS_COMPILE=aarch64-linux-gnu- make PLAT=<Target_SoC> bl31
+
+ Target_SoC should be "imx8mq" for i.MX8MQ SoC.
+ Target_SoC should be "imx8mm" for i.MX8MM SoC.
+ Target_SoC should be "imx8mn" for i.MX8MN SoC.
+ Target_SoC should be "imx8mp" for i.MX8MP 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
+used to generate flash.bin, and flash.bin needs to be flashed into SD card
+with certain offset for BOOT ROM. the u-boot and imx-mkimage will be upstreamed
+soon, this doc will be updated once they are ready, and the link will be posted.
+
+TBBR Boot Sequence
+------------------
+
+When setting NEED_BL2=1 on imx8mm. We support an alternative way of
+boot sequence to support TBBR.
+
+Bootrom --> SPL --> BL2 --> BL31 --> BL33(u-boot with UEFI) --> grub
+
+This helps us to fulfill the SystemReady EBBR standard.
+BL2 will be in the FIT image and SPL will verify it.
+All of the BL3x will be put in the FIP image. BL2 will verify them.
+In U-boot we turn on the UEFI secure boot features so it can verify
+grub. And we use grub to verify linux kernel.
+
+Measured Boot
+-------------
+
+When setting MEASURED_BOOT=1 on imx8mm we can let TF-A generate event logs
+with a DTB overlay. The overlay will be put at PLAT_IMX8M_DTO_BASE with
+maximum size PLAT_IMX8M_DTO_MAX_SIZE. Then in U-boot we can apply the DTB
+overlay and let U-boot to parse the event log and update the PCRs.
+
+High Assurance Boot (HABv4)
+---------------------------
+
+All actively maintained platforms have a support for High Assurance
+Boot (HABv4), which is implemented via ROM Vector Table (RVT) API to
+extend the Root-of-Trust beyond the SPL. Those calls are done via SMC
+and are executed in EL3, with results returned back to original caller.
+
+Note on DRAM Memory Mapping
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is a special case of mapping the DRAM: entire DRAM available on the
+platform is mapped into the EL3 with MT_RW attributes.
+
+Mapping the entire DRAM allows the usage of 2MB block mapping in Level-2
+Translation Table entries, which use less Page Table Entries (PTEs). If
+Level-3 PTE mapping is used instead then additional PTEs would be required,
+which leads to the increase of translation table size.
+
+Due to the fact that the size of SRAM is limited on some platforms in the
+family it should rather be avoided creating additional Level-3 mapping and
+introduce more PTEs, hence the implementation uses Level-2 mapping which
+maps entire DRAM space.
+
+The reason for the MT_RW attribute mapping scheme is the fact that the SMC
+API to get the status and events is called from NS world passing destination
+pointers which are located in DRAM. Mapping DRAM without MT_RW permissions
+causes those locations not to be filled, which in turn causing EL1&0 software
+not to receive replies.
+
+Therefore, DRAM mapping is done with MT_RW attributes, as it is required for
+data exchange between EL3 and EL1&0 software.
+
+Reference Documentation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Details on HABv4 usage and implementation could be found in following documents:
+
+- AN4581: "i.MX Secure Boot on HABv4 Supported Devices", Rev. 4 - June 2020
+- AN12263: "HABv4 RVT Guidelines and Recommendations", Rev. 1 - 06/2020
+- "HABv4 API Reference Manual". This document in the part of NXP Code Signing Tool (CST) distribution.
+
diff --git a/docs/plat/index.rst b/docs/plat/index.rst
new file mode 100644
index 0000000..a4e2067
--- /dev/null
+++ b/docs/plat/index.rst
@@ -0,0 +1,82 @@
+Platform Ports
+==============
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+ :hidden:
+
+ allwinner
+ arm/index
+ meson-axg
+ meson-gxbb
+ meson-gxl
+ meson-g12a
+ hikey
+ hikey960
+ intel-agilex
+ intel-stratix10
+ marvell/index
+ mt8183
+ mt8186
+ mt8188
+ mt8192
+ mt8195
+ nvidia-tegra
+ warp7
+ imx8
+ imx8m
+ nxp/index
+ poplar
+ qemu
+ qemu-sbsa
+ qti
+ qti-msm8916
+ rpi3
+ rpi4
+ rcar-gen3
+ rz-g2
+ rockchip
+ socionext-uniphier
+ synquacer
+ stm32mp1
+ ti-k3
+ xilinx-versal-net
+ xilinx-versal
+ xilinx-zynqmp
+ brcm-stingray
+
+This section provides a list of supported upstream *platform ports* and the
+documentation associated with them.
+
+.. note::
+ In addition to the platforms ports listed within the table of contents, there
+ are several additional platforms that are supported upstream but which do not
+ currently have associated documentation:
+
+ - Arm Neoverse N1 System Development Platform (N1SDP)
+ - Arm Neoverse Reference Design N1 Edge (RD-N1-Edge) FVP
+ - Arm Neoverse Reference Design E1 Edge (RD-E1-Edge) FVP
+ - Arm SGI-575
+ - MediaTek MT8173 SoCs
+
+Deprecated platforms
+--------------------
+
++----------------+----------------+--------------------+--------------------+
+| Platform | Vendor | Deprecated version | Deleted version |
++================+================+====================+====================+
+| sgm775 | Arm | 2.5 | 2.7 |
++----------------+----------------+--------------------+--------------------+
+| mt6795 | MTK | 2.5 | 2.7 |
++----------------+----------------+--------------------+--------------------+
+| sgi575 | Arm | 2.8 | 3.0 |
++----------------+----------------+--------------------+--------------------+
+| rdn1edge | Arm | 2.8 | 3.0 |
++----------------+----------------+--------------------+--------------------+
+| tc0 | Arm | 2.8 | 3.0 |
++----------------+----------------+--------------------+--------------------+
+
+--------------
+
+*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*
diff --git a/docs/plat/intel-agilex.rst b/docs/plat/intel-agilex.rst
new file mode 100644
index 0000000..ff27b6b
--- /dev/null
+++ b/docs/plat/intel-agilex.rst
@@ -0,0 +1,86 @@
+Intel Agilex SoCFPGA
+========================
+
+Agilex SoCFPGA is a FPGA with integrated quad-core 64-bit Arm Cortex A53 processor.
+
+Upon boot, Boot ROM loads bl2 into OCRAM. Bl2 subsequently initializes
+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>`__
+
+- UEFI (to be updated with new upstreamed UEFI):
+ `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}.
+
+- Prepare the AARCH64 toolchain.
+
+- Build UEFI using Agilex platform as configuration
+ This will be updated to use an updated UEFI using the latest EDK2 source
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-linux-gnu- device=agx
+
+- Build atf providing the previously generated UEFI as the BL33 image
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-linux-gnu- bl2 fip PLAT=agilex
+ BL33=PEI.ROM
+
+Install Procedure
+~~~~~~~~~~~~~~~~~
+
+- dd fip.bin to a A2 partition on the MMC drive to be booted in Agilex
+ board.
+
+- 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.
+ INFO: ECC is disabled.
+ NOTICE: BL2: v2.1(debug)
+ NOTICE: BL2: Built
+ INFO: BL2: Doing platform setup
+ NOTICE: BL2: Booting BL31
+ INFO: Entry point address = 0xffe1c000
+ INFO: SPSR = 0x3cd
+ NOTICE: BL31: v2.1(debug)
+ NOTICE: BL31: Built
+ INFO: ARM GICv2 driver initialized
+ INFO: BL31: Initializing runtime services
+ WARNING: BL31: cortex_a53
+ INFO: BL31: Preparing for EL3 exit to normal world
+ INFO: Entry point address = 0x50000
+ INFO: SPSR = 0x3c9
diff --git a/docs/plat/intel-stratix10.rst b/docs/plat/intel-stratix10.rst
new file mode 100644
index 0000000..7f8d18e
--- /dev/null
+++ b/docs/plat/intel-stratix10.rst
@@ -0,0 +1,94 @@
+Intel Stratix 10 SoCFPGA
+========================
+
+Stratix 10 SoCFPGA is a FPGA with integrated quad-core 64-bit Arm Cortex A53 processor.
+
+Upon boot, Boot ROM loads bl2 into OCRAM. Bl2 subsequently initializes
+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>`__
+
+- UEFI (to be updated with new upstreamed UEFI):
+ `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}.
+
+- Prepare the AARCH64 toolchain.
+
+- Build UEFI using Stratix 10 platform as configuration
+ This will be updated to use an updated UEFI using the latest EDK2 source
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-linux-gnu- device=s10
+
+- Build atf providing the previously generated UEFI as the BL33 image
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-linux-gnu- bl2 fip PLAT=stratix10
+ BL33=PEI.ROM
+
+Install Procedure
+~~~~~~~~~~~~~~~~~
+
+- dd fip.bin to a A2 partition on the MMC drive to be booted in Stratix 10
+ board.
+
+- 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.
+ INFO: ECC is disabled.
+ INFO: Init HPS NOC's DDR Scheduler.
+ NOTICE: BL2: v2.0(debug):v2.0-809-g7f8474a-dirty
+ NOTICE: BL2: Built : 17:38:19, Feb 18 2019
+ INFO: BL2: Doing platform setup
+ INFO: BL2: Loading image id 3
+ INFO: Loading image id=3 at address 0xffe1c000
+ INFO: Image id=3 loaded: 0xffe1c000 - 0xffe24034
+ INFO: BL2: Loading image id 5
+ INFO: Loading image id=5 at address 0x50000
+ INFO: Image id=5 loaded: 0x50000 - 0x550000
+ NOTICE: BL2: Booting BL31
+ INFO: Entry point address = 0xffe1c000
+ INFO: SPSR = 0x3cd
+ NOTICE: BL31: v2.0(debug):v2.0-810-g788c436-dirty
+ NOTICE: BL31: Built : 15:17:16, Feb 20 2019
+ INFO: ARM GICv2 driver initialized
+ INFO: BL31: Initializing runtime services
+ WARNING: BL31: cortex_a53: CPU workaround for 855873 was missing!
+ INFO: BL31: Preparing for EL3 exit to normal world
+ INFO: Entry point address = 0x50000
+ INFO: SPSR = 0x3c9
+ UEFI firmware (version 1.0 built at 11:26:18 on Nov 7 2018)
diff --git a/docs/plat/marvell/armada/build.rst b/docs/plat/marvell/armada/build.rst
new file mode 100644
index 0000000..8cb3fdf
--- /dev/null
+++ b/docs/plat/marvell/armada/build.rst
@@ -0,0 +1,476 @@
+TF-A Build Instructions for Marvell Platforms
+=============================================
+
+This section describes how to compile the Trusted Firmware-A (TF-A) project for Marvell's platforms.
+
+Build Instructions
+------------------
+(1) Set the cross compiler
+
+ .. code:: shell
+
+ > export CROSS_COMPILE=/path/to/toolchain/aarch64-linux-gnu-
+
+(2) Set path for FIP images:
+
+Set U-Boot image path (relatively to TF-A root or absolute path)
+
+ .. code:: shell
+
+ > export BL33=path/to/u-boot.bin
+
+For example: if U-Boot project (and its images) is located at ``~/project/u-boot``,
+BL33 should be ``~/project/u-boot/u-boot.bin``
+
+ .. note::
+
+ *u-boot.bin* should be used and not *u-boot-spl.bin*
+
+Set MSS/SCP image path (mandatory only for A7K/A8K/CN913x when MSS_SUPPORT=1)
+
+ .. code:: shell
+
+ > export SCP_BL2=path/to/mrvl_scp_bl2*.img
+
+(3) Armada-37x0 build requires WTP tools installation.
+
+See below in the section "Tools and external components installation".
+Install ARM 32-bit cross compiler, which is required for building WTMI image for CM3
+
+ .. code:: shell
+
+ > sudo apt-get install gcc-arm-linux-gnueabi
+
+(4) Clean previous build residuals (if any)
+
+ .. code:: shell
+
+ > make distclean
+
+(5) Build TF-A
+
+There are several build options:
+
+- PLAT
+
+ Supported Marvell platforms are:
+
+ - a3700 - A3720 DB, EspressoBin and Turris MOX
+ - a70x0
+ - a70x0_amc - AMC board
+ - a70x0_mochabin - Globalscale MOCHAbin
+ - a80x0
+ - a80x0_mcbin - MacchiatoBin
+ - a80x0_puzzle - IEI Puzzle-M801
+ - t9130 - CN913x
+ - t9130_cex7_eval - CN913x CEx7 Evaluation Board
+
+- DEBUG
+
+ Default is without debug information (=0). in order to enable it use ``DEBUG=1``.
+ Can be enabled also when building UART recovery images, there is no issue with it.
+
+ Production TF-A images should be built without this debug option!
+
+- LOG_LEVEL
+
+ Defines the level of logging which will be purged to the default output port.
+
+ - 0 - LOG_LEVEL_NONE
+ - 10 - LOG_LEVEL_ERROR
+ - 20 - LOG_LEVEL_NOTICE (default for DEBUG=0)
+ - 30 - LOG_LEVEL_WARNING
+ - 40 - LOG_LEVEL_INFO (default for DEBUG=1)
+ - 50 - LOG_LEVEL_VERBOSE
+
+- USE_COHERENT_MEM
+
+ This flag determines whether to include the coherent memory region in the
+ BL memory map or not. Enabled by default.
+
+- LLC_ENABLE
+
+ Flag defining the LLC (L3) cache state. The cache is enabled by default (``LLC_ENABLE=1``).
+
+- LLC_SRAM
+
+ Flag enabling the LLC (L3) cache SRAM support. The LLC SRAM is activated and used
+ by Trusted OS (OP-TEE OS, BL32). The TF-A only prepares CCU address translation windows
+ for SRAM address range at BL31 execution stage with window target set to DRAM-0.
+ When Trusted OS activates LLC SRAM, the CCU window target is changed to SRAM.
+ There is no reason to enable this feature if OP-TEE OS built with CFG_WITH_PAGER=n.
+ Only set LLC_SRAM=1 if OP-TEE OS is built with CFG_WITH_PAGER=y.
+
+- MARVELL_SECURE_BOOT
+
+ Build trusted(=1)/non trusted(=0) image, default is non trusted.
+ This parameter is used only for ``mrvl_flash`` and ``mrvl_uart`` targets.
+
+- MV_DDR_PATH
+
+ This parameter is required for ``mrvl_flash`` and ``mrvl_uart`` targets.
+ For A7K/A8K/CN913x it is used for BLE build and for Armada37x0 it used
+ for ddr_tool build.
+
+ Specify path to the full checkout of Marvell mv-ddr-marvell git
+ repository. Checkout must contain also .git subdirectory because
+ mv-ddr build process calls git commands.
+
+ Do not remove any parts of git checkout becuase build process and other
+ applications need them for correct building and version determination.
+
+
+CN913x specific build options:
+
+- CP_NUM
+
+ Total amount of CPs (South Bridge) connected to AP. When the parameter is omitted,
+ the build uses the default number of CPs, which is a number of embedded CPs inside the
+ package: 1 or 2 depending on the SoC used. The parameter is valid for OcteonTX2 CN913x SoC
+ family (PLAT=t9130), which can have external CPs connected to the MCI ports. Valid
+ values with CP_NUM are in a range of 1 to 3.
+
+
+A7K/A8K/CN913x specific build options:
+
+- BLE_PATH
+
+ Points to BLE (Binary ROM extension) sources folder.
+ The parameter is optional, its default value is ``plat/marvell/armada/a8k/common/ble``
+ which uses TF-A in-tree BLE implementation.
+
+- MSS_SUPPORT
+
+ When ``MSS_SUPPORT=1``, then TF-A includes support for Management SubSystem (MSS).
+ When enabled it is required to specify path to the MSS firmware image via ``SCP_BL2``
+ option.
+
+ This option is by default enabled.
+
+- SCP_BL2
+
+ Specify path to the MSS fimware image binary which will run on Cortex-M3 coprocessor.
+ It is available in Marvell binaries-marvell git repository. Required when ``MSS_SUPPORT=1``.
+
+Globalscale MOCHAbin specific build options:
+
+- DDR_TOPOLOGY
+
+ The DDR topology map index/name, default is 0.
+
+ Supported Options:
+ - 0 - DDR4 1CS 2GB
+ - 1 - DDR4 1CS 4GB
+ - 2 - DDR4 2CS 8GB
+
+Armada37x0 specific build options:
+
+- HANDLE_EA_EL3_FIRST_NS
+
+ When ``HANDLE_EA_EL3_FIRST_NS=1``, External Aborts and SError Interrupts, resulting from errors
+ in NS world, will be always trapped in TF-A. TF-A in this case enables dirty hack / workaround for
+ a bug found in U-Boot and Linux kernel PCIe controller driver pci-aardvark.c, traps and then masks
+ SError interrupt caused by AXI SLVERR on external access (syndrome 0xbf000002).
+
+ Otherwise when ``HANDLE_EA_EL3_FIRST_NS=0``, these exceptions will be trapped in the current
+ exception level (or in EL1 if the current exception level is EL0). So exceptions caused by
+ U-Boot will be trapped in U-Boot, exceptions caused by Linux kernel (or user applications)
+ will be trapped in Linux kernel.
+
+ Mentioned bug in pci-aardvark.c driver is fixed in U-Boot version v2021.07 and Linux kernel
+ version v5.13 (workarounded since Linux kernel version 5.9) and also backported in Linux
+ kernel stable releases since versions v5.12.13, v5.10.46, v5.4.128, v4.19.198, v4.14.240.
+
+ If target system has already patched version of U-Boot and Linux kernel then it is strongly
+ recommended to not enable this workaround as it disallows propagating of all External Aborts
+ to running Linux kernel and makes correctable errors as fatal aborts.
+
+ This option is now disabled by default. In past this option has different name "HANDLE_EA_EL3_FIRST" and
+ was enabled by default in TF-A versions v2.2, v2.3, v2.4 and v2.5.
+
+- CM3_SYSTEM_RESET
+
+ When ``CM3_SYSTEM_RESET=1``, the Cortex-M3 secure coprocessor will be used for system reset.
+
+ TF-A will send command 0x0009 with a magic value via the rWTM mailbox interface to the
+ Cortex-M3 secure coprocessor.
+ The firmware running in the coprocessor must either implement this functionality or
+ ignore the 0x0009 command (which is true for the firmware from A3700-utils-marvell
+ repository). If this option is enabled but the firmware does not support this command,
+ an error message will be printed prior trying to reboot via the usual way.
+
+ This option is needed on Turris MOX as a workaround to a HW bug which causes reset to
+ sometime hang the board.
+
+- A3720_DB_PM_WAKEUP_SRC
+
+ For Armada 3720 Development Board only, when ``A3720_DB_PM_WAKEUP_SRC=1``,
+ TF-A will setup PM wake up src configuration. This option is disabled by default.
+
+
+Armada37x0 specific build options for ``mrvl_flash`` and ``mrvl_uart`` targets:
+
+- DDR_TOPOLOGY
+
+ The DDR topology map index/name, default is 0.
+
+ Supported Options:
+ - 0 - DDR3 1CS 512MB (DB-88F3720-DDR3-Modular, EspressoBin V3-V5)
+ - 1 - DDR4 1CS 512MB (DB-88F3720-DDR4-Modular)
+ - 2 - DDR3 2CS 1GB (EspressoBin V3-V5)
+ - 3 - DDR4 2CS 4GB (DB-88F3720-DDR4-Modular)
+ - 4 - DDR3 1CS 1GB (DB-88F3720-DDR3-Modular, EspressoBin V3-V5)
+ - 5 - DDR4 1CS 1GB (EspressoBin V7, EspressoBin-Ultra)
+ - 6 - DDR4 2CS 2GB (EspressoBin V7)
+ - 7 - DDR3 2CS 2GB (EspressoBin V3-V5)
+ - CUST - CUSTOMER BOARD (Customer board settings)
+
+- CLOCKSPRESET
+
+ The clock tree configuration preset including CPU and DDR frequency,
+ default is CPU_800_DDR_800.
+
+ - CPU_600_DDR_600 - CPU at 600 MHz, DDR at 600 MHz
+ - CPU_800_DDR_800 - CPU at 800 MHz, DDR at 800 MHz
+ - CPU_1000_DDR_800 - CPU at 1000 MHz, DDR at 800 MHz
+ - CPU_1200_DDR_750 - CPU at 1200 MHz, DDR at 750 MHz
+
+ Look at Armada37x0 chip package marking on board to identify correct CPU frequency.
+ The last line on package marking (next line after the 88F37x0 line) should contain:
+
+ - C080 or I080 - chip with 800 MHz CPU - use ``CLOCKSPRESET=CPU_800_DDR_800``
+ - C100 or I100 - chip with 1000 MHz CPU - use ``CLOCKSPRESET=CPU_1000_DDR_800``
+ - C120 - chip with 1200 MHz CPU - use ``CLOCKSPRESET=CPU_1200_DDR_750``
+
+- BOOTDEV
+
+ The flash boot device, default is ``SPINOR``.
+
+ Currently, Armada37x0 only supports ``SPINOR``, ``SPINAND``, ``EMMCNORM`` and ``SATA``:
+
+ - SPINOR - SPI NOR flash boot
+ - SPINAND - SPI NAND flash boot
+ - EMMCNORM - eMMC Download Mode
+
+ Download boot loader or program code from eMMC flash into CM3 or CA53
+ Requires full initialization and command sequence
+
+ - SATA - SATA device boot
+
+ Image needs to be stored at disk LBA 0 or at disk partition with
+ MBR type 0x4d (ASCII 'M' as in Marvell) or at disk partition with
+ GPT partition type GUID ``6828311A-BA55-42A4-BCDE-A89BB5EDECAE``.
+
+- PARTNUM
+
+ The boot partition number, default is 0.
+
+ To boot from eMMC, the value should be aligned with the parameter in
+ U-Boot with name of ``CONFIG_SYS_MMC_ENV_PART``, whose value by default is
+ 1. For details about CONFIG_SYS_MMC_ENV_PART, please refer to the U-Boot
+ build instructions.
+
+- WTMI_IMG
+
+ The path of the binary can point to an image which
+ does nothing, an image which supports EFUSE or a customized CM3 firmware
+ binary. The default image is ``fuse.bin`` that built from sources in WTP
+ folder, which is the next option. If the default image is OK, then this
+ option should be skipped.
+
+ Please note that this is not a full WTMI image, just a main loop without
+ hardware initialization code. Final WTMI image is built from this WTMI_IMG
+ binary and sys-init code from the WTP directory which sets DDR and CPU
+ clocks according to DDR_TOPOLOGY and CLOCKSPRESET options.
+
+ CZ.NIC as part of Turris project released free and open source WTMI
+ application firmware ``wtmi_app.bin`` for all Armada 3720 devices.
+ This firmware includes additional features like access to Hardware
+ Random Number Generator of Armada 3720 SoC which original Marvell's
+ ``fuse.bin`` image does not have.
+
+ CZ.NIC's Armada 3720 Secure Firmware is available at website:
+
+ https://gitlab.nic.cz/turris/mox-boot-builder/
+
+- WTP
+
+ Specify path to the full checkout of Marvell A3700-utils-marvell git
+ repository. Checkout must contain also .git subdirectory because WTP
+ build process calls git commands.
+
+ WTP build process uses also Marvell mv-ddr-marvell git repository
+ specified in MV_DDR_PATH option.
+
+ Do not remove any parts of git checkout becuase build process and other
+ applications need them for correct building and version determination.
+
+- CRYPTOPP_PATH
+
+ Use this parameter to point to Crypto++ source code
+ directory. If this option is specified then Crypto++ source code in
+ CRYPTOPP_PATH directory will be automatically compiled. Crypto++ library
+ is required for building WTP image tool. Either CRYPTOPP_PATH or
+ CRYPTOPP_LIBDIR with CRYPTOPP_INCDIR needs to be specified for Armada37x0.
+
+- CRYPTOPP_LIBDIR
+
+ Use this parameter to point to the directory with
+ compiled Crypto++ library. By default it points to the CRYPTOPP_PATH.
+
+ On Debian systems it is possible to install system-wide Crypto++ library
+ via command ``apt install libcrypto++-dev`` and specify CRYPTOPP_LIBDIR
+ to ``/usr/lib/``.
+
+- CRYPTOPP_INCDIR
+
+ Use this parameter to point to the directory with
+ header files of Crypto++ library. By default it points to the CRYPTOPP_PATH.
+
+ On Debian systems it is possible to install system-wide Crypto++ library
+ via command ``apt install libcrypto++-dev`` and specify CRYPTOPP_INCDIR
+ to ``/usr/include/crypto++/``.
+
+
+For example, in order to build the image in debug mode with log level up to 'notice' level run
+
+.. code:: shell
+
+ > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 PLAT=<MARVELL_PLATFORM> mrvl_flash
+
+And if we want to build a Armada37x0 image in debug mode with log level up to 'notice' level,
+the image has the preset CPU at 1000 MHz, preset DDR3 at 800 MHz, the DDR topology of DDR4 2CS,
+the image boot from SPI NOR flash partition 0, and the image is non trusted in WTP, the command
+line is as following
+
+.. code:: shell
+
+ > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 CLOCKSPRESET=CPU_1000_DDR_800 \
+ MARVELL_SECURE_BOOT=0 DDR_TOPOLOGY=3 BOOTDEV=SPINOR PARTNUM=0 PLAT=a3700 \
+ MV_DDR_PATH=/path/to/mv-ddr-marvell/ WTP=/path/to/A3700-utils-marvell/ \
+ CRYPTOPP_PATH=/path/to/cryptopp/ BL33=/path/to/u-boot.bin \
+ all fip mrvl_bootimage mrvl_flash mrvl_uart
+
+To build just TF-A without WTMI image (useful for A3720 Turris MOX board), run following command:
+
+.. code:: shell
+
+ > make USE_COHERENT_MEM=0 PLAT=a3700 CM3_SYSTEM_RESET=1 BL33=/path/to/u-boot.bin \
+ CROSS_COMPILE=aarch64-linux-gnu- mrvl_bootimage
+
+Here is full example how to build production release of Marvell firmware image (concatenated
+binary of Marvell's A3720 sys-init, CZ.NIC's Armada 3720 Secure Firmware, TF-A and U-Boot) for
+EspressoBin board (PLAT=a3700) with 1GHz CPU (CLOCKSPRESET=CPU_1000_DDR_800) and
+1GB DDR4 RAM (DDR_TOPOLOGY=5):
+
+.. code:: shell
+
+ > git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+ > git clone https://source.denx.de/u-boot/u-boot.git
+ > git clone https://github.com/weidai11/cryptopp.git
+ > git clone https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git
+ > git clone https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git
+ > git clone https://gitlab.nic.cz/turris/mox-boot-builder.git
+ > make -C u-boot CROSS_COMPILE=aarch64-linux-gnu- mvebu_espressobin-88f3720_defconfig u-boot.bin
+ > make -C mox-boot-builder CROSS_CM3=arm-linux-gnueabi- wtmi_app.bin
+ > make -C trusted-firmware-a CROSS_COMPILE=aarch64-linux-gnu- CROSS_CM3=arm-linux-gnueabi- \
+ USE_COHERENT_MEM=0 PLAT=a3700 CLOCKSPRESET=CPU_1000_DDR_800 DDR_TOPOLOGY=5 \
+ MV_DDR_PATH=$PWD/mv-ddr-marvell/ WTP=$PWD/A3700-utils-marvell/ \
+ CRYPTOPP_PATH=$PWD/cryptopp/ BL33=$PWD/u-boot/u-boot.bin \
+ WTMI_IMG=$PWD/mox-boot-builder/wtmi_app.bin FIP_ALIGN=0x100 mrvl_flash
+
+Produced Marvell firmware flash image: ``trusted-firmware-a/build/a3700/release/flash-image.bin``
+
+Special Build Flags
+--------------------
+
+- PLAT_RECOVERY_IMAGE_ENABLE
+ When set this option to enable secondary recovery function when build atf.
+ In order to build UART recovery image this operation should be disabled for
+ A7K/A8K/CN913x because of hardware limitation (boot from secondary image
+ can interrupt UART recovery process). This MACRO definition is set in
+ ``plat/marvell/armada/a8k/common/include/platform_def.h`` file.
+
+- DDR32
+ In order to work in 32bit DDR, instead of the default 64bit ECC DDR,
+ this flag should be set to 1.
+
+For more information about build options, please refer to the
+:ref:`Build Options` document.
+
+
+Build output
+------------
+Marvell's TF-A compilation generates 8 files:
+
+ - ble.bin - BLe image (not available for Armada37x0)
+ - bl1.bin - BL1 image
+ - bl2.bin - BL2 image
+ - bl31.bin - BL31 image
+ - fip.bin - FIP image (contains BL2, BL31 & BL33 (U-Boot) images)
+ - boot-image.bin - TF-A image (contains BL1 and FIP images)
+ - flash-image.bin - Flashable Marvell firmware image. For Armada37x0 it
+ contains TIM, WTMI and boot-image.bin images. For other platforms it contains
+ BLe and boot-image.bin images. Should be placed on the boot flash/device.
+ - uart-images.tgz.bin - GZIPed TAR archive which contains Armada37x0 images
+ for booting via UART. Could be loaded via Marvell's WtpDownload tool from
+ A3700-utils-marvell repository.
+
+Additional make target ``mrvl_bootimage`` produce ``boot-image.bin`` file. Target
+``mrvl_flash`` produce final ``flash-image.bin`` file and target ``mrvl_uart``
+produce ``uart-images.tgz.bin`` file.
+
+
+Tools and external components installation
+------------------------------------------
+
+Armada37x0 Builds require installation of additional components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(1) ARM cross compiler capable of building images for the service CPU (CM3).
+ This component is usually included in the Linux host packages.
+ On Debian/Ubuntu hosts the default GNU ARM tool chain can be installed
+ using the following command
+
+ .. code:: shell
+
+ > sudo apt-get install gcc-arm-linux-gnueabi
+
+ Only if required, the default tool chain prefix ``arm-linux-gnueabi-`` can be
+ overwritten using the environment variable ``CROSS_CM3``.
+ Example for BASH shell
+
+ .. code:: shell
+
+ > export CROSS_CM3=/opt/arm-cross/bin/arm-linux-gnueabi
+
+(2) DDR initialization library sources (mv_ddr) available at the following repository
+ (use the "master" branch):
+
+ https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git
+
+(3) Armada3700 tools available at the following repository
+ (use the "master" branch):
+
+ https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git
+
+(4) Crypto++ library available at the following repository:
+
+ https://github.com/weidai11/cryptopp.git
+
+(5) Optional CZ.NIC's Armada 3720 Secure Firmware:
+
+ https://gitlab.nic.cz/turris/mox-boot-builder.git
+
+Armada70x0, Armada80x0 and CN913x Builds require installation of additional components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(1) DDR initialization library sources (mv_ddr) available at the following repository
+ (use the "master" branch):
+
+ https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git
+
+(2) MSS Management SubSystem Firmware available at the following repository
+ (use the "binaries-marvell-armada-SDK10.0.1.0" branch):
+
+ https://github.com/MarvellEmbeddedProcessors/binaries-marvell.git
diff --git a/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst b/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst
new file mode 100644
index 0000000..e88a458
--- /dev/null
+++ b/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst
@@ -0,0 +1,49 @@
+Address decoding flow and address translation units of Marvell Armada 8K SoC family
+===================================================================================
+
+::
+
+ +--------------------------------------------------------------------------------------------------+
+ | +-------------+ +--------------+ |
+ | | Memory +----- DRAM CS | |
+ |+------------+ +-----------+ +-----------+ | Controller | +--------------+ |
+ || AP DMA | | | | | +-------------+ |
+ || SD/eMMC | | CA72 CPUs | | AP MSS | +-------------+ |
+ || MCI-0/1 | | | | | | Memory | |
+ |+------+-----+ +--+--------+ +--------+--+ +------------+ | Controller | +-------------+ |
+ | | | | | +----- Translaton | |AP | |
+ | | | | | | +-------------+ |Configuration| |
+ | | | +-----+ +-------------------------Space | |
+ | | | +-------------+ | CCU | +-------------+ |
+ | | | | MMU +---------+ Windows | +-----------+ +-------------+ |
+ | | +-| translation | | Lookup +---- +--------- AP SPI | |
+ | | +-------------+ | | | | +-------------+ |
+ | | +-------------+ | | | IO | +-------------+ |
+ | +------------| SMMU +---------+ | | Windows +--------- AP MCI0/1 | |
+ | | translation | +------------+ | Lookup | +-------------+ |
+ | +---------+---+ | | +-------------+ |
+ | - | | +--------- AP STM | |
+ | +----------------- | | +-------------+ |
+ | AP | | +-+---------+ |
+ +---------------------------------------------------------------|----------------------------------+
+ +-------------|-------------------------------------------------|----------------------------------+
+ | CP | +-------------+ +------+-----+ +-------------------+ |
+ | | | | | +------- SB CFG Space | |
+ | | | DIOB | | | +-------------------+ |
+ | | | Windows ----------------- IOB | +-------------------+ |
+ | | | Control | | Windows +------| SB PCIe-0 - PCIe2 | |
+ | | | | | Lookup | +-------------------+ |
+ | | +------+------+ | | +-------------------+ |
+ | | | | +------+ SB NAND | |
+ | | | +------+-----+ +-------------------+ |
+ | | | | |
+ | | | | |
+ | +------------------+ +------------+ +------+-----+ +-------------------+ |
+ | | Network Engine | | | | +------- SB SPI-0/SPI-1 | |
+ | | Security Engine | | PCIe, MSS | | RUNIT | +-------------------+ |
+ | | SATA, USB | | DMA | | Windows | +-------------------+ |
+ | | SD/eMMC | | | | Lookup +------- SB Device Bus | |
+ | | TDM, I2C | | | | | +-------------------+ |
+ | +------------------+ +------------+ +------------+ |
+ | |
+ +--------------------------------------------------------------------------------------------------+
diff --git a/docs/plat/marvell/armada/misc/mvebu-amb.rst b/docs/plat/marvell/armada/misc/mvebu-amb.rst
new file mode 100644
index 0000000..d734003
--- /dev/null
+++ b/docs/plat/marvell/armada/misc/mvebu-amb.rst
@@ -0,0 +1,58 @@
+AMB - AXI MBUS address decoding
+===============================
+
+AXI to M-bridge decoding unit driver for Marvell Armada 8K and 8K+ SoCs.
+
+The Runit offers a second level of address windows lookup. It is used to map
+transaction towards the CD BootROM, SPI0, SPI1 and Device bus (NOR).
+
+The Runit contains eight configurable windows. Each window defines a contiguous,
+address space and the properties associated with that address space.
+
+::
+
+ Unit Bank ATTR
+ Device-Bus DEV_BOOT_CS 0x2F
+ DEV_CS0 0x3E
+ DEV_CS1 0x3D
+ DEV_CS2 0x3B
+ DEV_CS3 0x37
+ SPI-0 SPI_A_CS0 0x1E
+ SPI_A_CS1 0x5E
+ SPI_A_CS2 0x9E
+ SPI_A_CS3 0xDE
+ SPI_A_CS4 0x1F
+ SPI_A_CS5 0x5F
+ SPI_A_CS6 0x9F
+ SPI_A_CS7 0xDF
+ SPI SPI_B_CS0 0x1A
+ SPI_B_CS1 0x5A
+ SPI_B_CS2 0x9A
+ SPI_B_CS3 0xDA
+ BOOT_ROM BOOT_ROM 0x1D
+ UART UART 0x01
+
+Mandatory functions
+-------------------
+
+- marvell_get_amb_memory_map
+ Returns the AMB windows configuration and the number of windows
+
+Mandatory structures
+--------------------
+
+- amb_memory_map
+ Array that include the configuration of the windows. Every window/entry is a
+ struct which has 2 parameters:
+
+ - Base address of the window
+ - Attribute of the window
+
+Examples
+--------
+
+.. code:: c
+
+ struct addr_map_win amb_memory_map[] = {
+ {0xf900, AMB_DEV_CS0_ID},
+ };
diff --git a/docs/plat/marvell/armada/misc/mvebu-ccu.rst b/docs/plat/marvell/armada/misc/mvebu-ccu.rst
new file mode 100644
index 0000000..12118e9
--- /dev/null
+++ b/docs/plat/marvell/armada/misc/mvebu-ccu.rst
@@ -0,0 +1,33 @@
+Marvell CCU address decoding bindings
+=====================================
+
+CCU configuration driver (1st stage address translation) for Marvell Armada 8K and 8K+ SoCs.
+
+The CCU node includes a description of the address decoding configuration.
+
+Mandatory functions
+-------------------
+
+- marvell_get_ccu_memory_map
+ Return the CCU windows configuration and the number of windows of the
+ specific AP.
+
+Mandatory structures
+--------------------
+
+- ccu_memory_map
+ Array that includes the configuration of the windows. Every window/entry is
+ a struct which has 3 parameters:
+
+ - Base address of the window
+ - Size of the window
+ - Target-ID of the window
+
+Example
+-------
+
+.. code:: c
+
+ struct addr_map_win ccu_memory_map[] = {
+ {0x00000000f2000000, 0x00000000e000000, IO_0_TID}, /* IO window */
+ };
diff --git a/docs/plat/marvell/armada/misc/mvebu-io-win.rst b/docs/plat/marvell/armada/misc/mvebu-io-win.rst
new file mode 100644
index 0000000..7498291
--- /dev/null
+++ b/docs/plat/marvell/armada/misc/mvebu-io-win.rst
@@ -0,0 +1,46 @@
+Marvell IO WIN address decoding bindings
+========================================
+
+IO Window configuration driver (2nd stage address translation) for Marvell Armada 8K and 8K+ SoCs.
+
+The IO WIN includes a description of the address decoding configuration.
+
+Transactions that are decoded by CCU windows as IO peripheral, have an additional
+layer of decoding. This additional address decoding layer defines one of the
+following targets:
+
+- **0x0** = BootRom
+- **0x1** = STM (Serial Trace Macro-cell, a programmer's port into trace stream)
+- **0x2** = SPI direct access
+- **0x3** = PCIe registers
+- **0x4** = MCI Port
+- **0x5** = PCIe port
+
+Mandatory functions
+-------------------
+
+- marvell_get_io_win_memory_map
+ Returns the IO windows configuration and the number of windows of the
+ specific AP.
+
+Mandatory structures
+--------------------
+
+- io_win_memory_map
+ Array that include the configuration of the windows. Every window/entry is
+ a struct which has 3 parameters:
+
+ - Base address of the window
+ - Size of the window
+ - Target-ID of the window
+
+Example
+-------
+
+.. code:: c
+
+ struct addr_map_win io_win_memory_map[] = {
+ {0x00000000fe000000, 0x000000001f00000, PCIE_PORT_TID}, /* PCIe window 31Mb for PCIe port*/
+ {0x00000000ffe00000, 0x000000000100000, PCIE_REGS_TID}, /* PCI-REG window 64Kb for PCIe-reg*/
+ {0x00000000f6000000, 0x000000000100000, MCIPHY_TID}, /* MCI window 1Mb for PHY-reg*/
+ };
diff --git a/docs/plat/marvell/armada/misc/mvebu-iob.rst b/docs/plat/marvell/armada/misc/mvebu-iob.rst
new file mode 100644
index 0000000..aa41822
--- /dev/null
+++ b/docs/plat/marvell/armada/misc/mvebu-iob.rst
@@ -0,0 +1,52 @@
+Marvell IOB address decoding bindings
+=====================================
+
+IO bridge configuration driver (3rd stage address translation) for Marvell Armada 8K and 8K+ SoCs.
+
+The IOB includes a description of the address decoding configuration.
+
+IOB supports up to n (in CP110 n=24) windows for external memory transaction.
+When a transaction passes through the IOB, its address is compared to each of
+the enabled windows. If there is a hit and it passes the security checks, it is
+advanced to the target port.
+
+Mandatory functions
+-------------------
+
+- marvell_get_iob_memory_map
+ Returns the IOB windows configuration and the number of windows
+
+Mandatory structures
+--------------------
+
+- iob_memory_map
+ Array that includes the configuration of the windows. Every window/entry is
+ a struct which has 3 parameters:
+
+ - Base address of the window
+ - Size of the window
+ - Target-ID of the window
+
+Target ID options
+-----------------
+
+- **0x0** = Internal configuration space
+- **0x1** = MCI0
+- **0x2** = PEX1_X1
+- **0x3** = PEX2_X1
+- **0x4** = PEX0_X4
+- **0x5** = NAND flash
+- **0x6** = RUNIT (NOR/SPI/BootRoom)
+- **0x7** = MCI1
+
+Example
+-------
+
+.. code:: c
+
+ struct addr_map_win iob_memory_map[] = {
+ {0x00000000f7000000, 0x0000000001000000, PEX1_TID}, /* PEX1_X1 window */
+ {0x00000000f8000000, 0x0000000001000000, PEX2_TID}, /* PEX2_X1 window */
+ {0x00000000f6000000, 0x0000000001000000, PEX0_TID}, /* PEX0_X4 window */
+ {0x00000000f9000000, 0x0000000001000000, NAND_TID} /* NAND window */
+ };
diff --git a/docs/plat/marvell/armada/porting.rst b/docs/plat/marvell/armada/porting.rst
new file mode 100644
index 0000000..ba8736d
--- /dev/null
+++ b/docs/plat/marvell/armada/porting.rst
@@ -0,0 +1,158 @@
+TF-A Porting Guide for Marvell Platforms
+========================================
+
+This section describes how to port TF-A to a customer board, assuming that the
+SoC being used is already supported in TF-A.
+
+
+Source Code Structure
+---------------------
+
+- The customer platform specific code shall reside under ``plat/marvell/armada/<soc family>/<soc>_cust``
+ (e.g. 'plat/marvell/armada/a8k/a7040_cust').
+- The platform name for build purposes is called ``<soc>_cust`` (e.g. ``a7040_cust``).
+- The build system will reuse all files from within the soc directory, and take only the porting
+ files from the customer platform directory.
+
+Files that require porting are located at ``plat/marvell/armada/<soc family>/<soc>_cust`` directory.
+
+
+Armada-70x0/Armada-80x0 Porting
+-------------------------------
+
+SoC Physical Address Map (marvell_plat_config.c)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This file describes the SoC physical memory mapping to be used for the CCU,
+IOWIN, AXI-MBUS and IOB address decode units (Refer to the functional spec for
+more details).
+
+In most cases, using the default address decode windows should work OK.
+
+In cases where a special physical address map is needed (e.g. Special size for
+PCIe MEM windows, large memory mapped SPI flash...), then porting of the SoC
+memory map is required.
+
+.. note::
+ For a detailed information on how CCU, IOWIN, AXI-MBUS & IOB work, please
+ refer to the SoC functional spec, and under
+ ``docs/plat/marvell/armada/misc/mvebu-[ccu/iob/amb/io-win].rst`` files.
+
+boot loader recovery (marvell_plat_config.c)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Background:
+
+ Boot rom can skip the current image and choose to boot from next position if a
+ specific value (``0xDEADB002``) is returned by the ble main function. This
+ feature is used for boot loader recovery by booting from a valid flash-image
+ saved in next position on flash (e.g. address 2M in SPI flash).
+
+ Supported options to implement the skip request are:
+ - GPIO
+ - I2C
+ - User defined
+
+- Porting:
+
+ Under marvell_plat_config.c, implement struct skip_image that includes
+ specific board parameters.
+
+ .. warning::
+ To disable this feature make sure the struct skip_image is not implemented.
+
+- Example:
+
+In A7040-DB specific implementation
+(``plat/marvell/armada/a8k/a70x0/board/marvell_plat_config.c``), the image skip is
+implemented using GPIO: mpp 33 (SW5).
+
+Before resetting the board make sure there is a valid image on the next flash
+address:
+
+ -tftp [valid address] flash-image.bin
+ -sf update [valid address] 0x2000000 [size]
+
+Press reset and keep pressing the button connected to the chosen GPIO pin. A
+skip image request message is printed on the screen and boot rom boots from the
+saved image at the next position.
+
+DDR Porting (dram_port.c)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This file defines the dram topology and parameters of the target board.
+
+The DDR code is part of the BLE component, which is an extension of ARM Trusted
+Firmware (TF-A).
+
+The DDR driver called mv_ddr is released separately apart from TF-A sources.
+
+The BLE and consequently, the DDR init code is executed at the early stage of
+the boot process.
+
+Each supported platform of the TF-A has its own DDR porting file called
+dram_port.c located at ``atf/plat/marvell/armada/a8k/<platform>/board`` directory.
+
+Please refer to '<path_to_mv_ddr_sources>/doc/porting_guide.txt' for detailed
+porting description.
+
+The build target directory is "build/<platform>/release/ble".
+
+Comphy Porting (phy-porting-layer.h or phy-default-porting-layer.h)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Background:
+ Some of the comphy's parameters value depend on the HW connection between
+ the SoC and the PHY. Every board type has specific HW characteristics like
+ wire length. Due to those differences some comphy parameters vary between
+ board types. Therefore each board type can have its own list of values for
+ all relevant comphy parameters. The PHY porting layer specifies which
+ parameters need to be suited and the board designer should provide relevant
+ values.
+
+ The PHY porting layer simplifies updating static values per board type,
+ which are now grouped in one place.
+
+ .. note::
+ The parameters for the same type of comphy may vary even for the same
+ board type, it is because the lanes from comphy-x to some PHY may have
+ different HW characteristic than lanes from comphy-y to the same
+ (multiplexed) or other PHY.
+
+- Porting:
+ The porting layer for PHY was introduced in TF-A. There is one file
+ ``drivers/marvell/comphy/phy-default-porting-layer.h`` which contains the
+ defaults. Those default parameters are used only if there is no appropriate
+ phy-porting-layer.h file under: ``plat/marvell/armada/<soc
+ family>/<platform>/board/phy-porting-layer.h``. If the phy-porting-layer.h
+ exists, the phy-default-porting-layer.h is not going to be included.
+
+ .. warning::
+ Not all comphy types are already reworked to support the PHY porting
+ layer, currently the porting layer is supported for XFI/SFI and SATA
+ comphy types.
+
+ The easiest way to prepare the PHY porting layer for custom board is to copy
+ existing example to a new platform:
+
+ - cp ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/armada/<soc family>/<platform>/board/phy-porting-layer.h"
+ - adjust relevant parameters or
+ - if different comphy index is used for specific feature, move it to proper table entry and then adjust.
+
+ .. note::
+ The final table size with comphy parameters can be different, depending
+ on the CP module count for given SoC type.
+
+- Example:
+ Example porting layer for armada-8040-db is under:
+ ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h``
+
+ .. note::
+ If there is no PHY porting layer for new platform (missing
+ phy-porting-layer.h), the default values are used
+ (drivers/marvell/comphy/phy-default-porting-layer.h) and the user is
+ warned:
+
+ .. warning::
+ "Using default comphy parameters - it may be required to suit them for
+ your board".
diff --git a/docs/plat/marvell/armada/uart-booting.rst b/docs/plat/marvell/armada/uart-booting.rst
new file mode 100644
index 0000000..04ce464
--- /dev/null
+++ b/docs/plat/marvell/armada/uart-booting.rst
@@ -0,0 +1,103 @@
+TF-A UART Booting Instructions for Marvell Platforms
+====================================================
+
+This section describes how to temporary boot the Trusted Firmware-A (TF-A) project over UART
+without flashing it to non-volatile storage for Marvell's platforms.
+
+See :ref:`TF-A Build Instructions for Marvell Platforms` how to build ``mrvl_uart`` and
+``mrvl_flash`` targets used in this section.
+
+Armada37x0 UART image downloading
+---------------------------------
+
+There are two options how to download UART image into any Armada37x0 board.
+
+Marvell Wtpdownloader
+~~~~~~~~~~~~~~~~~~~~~
+
+Marvell Wtpdownloader works only with UART images stored in separate files and supports only upload
+speed with 115200 bauds. Target ``mrvl_uart`` produces GZIPed TAR archive ``uart-images.tgz.bin``
+with either three files ``TIM_ATF.bin``, ``wtmi_h.bin`` and ``boot-image_h.bin`` for non-secure
+boot or with four files ``TIM_ATF_TRUSTED.bin``, ``TIMN_ATF_TRUSTED.bin``, ``wtmi_h.bin`` and
+``boot-image_h.bin`` when secure boot is enabled.
+
+Compilation:
+
+.. code:: shell
+
+ > git clone https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git
+ > make -C A3700-utils-marvell/wtptp/src/Wtpdownloader_Linux -f makefile.mk
+
+It produces executable binary ``A3700-utils-marvell/wtptp/src/Wtpdownloader_Linux/WtpDownload_linux``
+
+To download images from ``uart-images.tgz.bin`` archive unpack it and for non-secure boot variant run:
+
+.. code:: shell
+
+ > stty -F /dev/ttyUSB<port#> clocal
+ > WtpDownload_linux -P UART -C <port#> -E -B TIM_ATF.bin -I wtmi_h.bin -I boot-image_h.bin
+
+After that immediately start terminal on ``/dev/ttyUSB<port#>`` to see boot output.
+
+CZ.NIC mox-imager
+~~~~~~~~~~~~~~~~~
+
+CZ.NIC mox-imager supports all Armada37x0 boards (not only Turris MOX as name suggests). It works
+with either with separate files from ``uart-images.tgz.bin`` archive (like Marvell Wtpdownloader)
+produced by ``mrvl_uart`` target or also with ``flash-image.bin`` file produced by ``mrvl_flash``
+target, which is the exactly same file as used for flashing. So when using CZ.NIC mox-imager there
+is no need to build separate files for UART flashing like in case with Marvell Wtpdownloader.
+
+CZ.NIC mox-imager moreover supports higher upload speeds up to the 6000000 bauds (which seems to
+be limit of Armada37x0 SoC) which is much higher and faster than Marvell Wtpdownloader.
+
+Compilation:
+
+.. code:: shell
+
+ > git clone https://gitlab.nic.cz/turris/mox-imager.git
+ > make -C mox-imager
+
+It produces executable binary ``mox-imager/mox-imager``
+
+To download single file image built by ``mrvl_flash`` target at the highest speed, run:
+
+.. code:: shell
+
+ > mox-imager -D /dev/ttyUSB<port#> -E -b 6000000 -t flash-image.bin
+
+To download images from ``uart-images.tgz.bin`` archive built by ``mrvl_uart`` target for
+non-secure boot variant (like Wtpdownloader) but at the highest speed, first unpack
+``uart-images.tgz.bin`` archive and then run:
+
+.. code:: shell
+
+ > mox-imager -D /dev/ttyUSB<port#> -E -b 6000000 -t TIM_ATF.bin wtmi_h.bin boot-image_h.bin
+
+CZ.NIC mox-imager after successful download will start its own mini terminal (option ``-t``) to
+not loose any boot output. It also prints boot output which is sent either by image files or by
+bootrom during transferring of image files. This mini terminal can be quit by CTRL-\\ + C keypress.
+
+
+A7K/A8K/CN913x UART image downloading
+-------------------------------------
+
+A7K/A8K/CN913x uses same image ``flash-image.bin`` for both flashing and booting over UART.
+For downloading image over UART it is possible to use mvebu64boot tool.
+
+Compilation:
+
+.. code:: shell
+
+ > git clone https://github.com/pali/mvebu64boot.git
+ > make -C mvebu64boot
+
+It produces executable binary ``mvebu64boot/mvebu64boot``
+
+To download ``flash-image.bin`` image run:
+
+.. code:: shell
+
+ > mvebu64boot -t -b flash-image.bin /dev/ttyUSB0
+
+After successful download it will start own mini terminal (option ``-t``) like CZ.NIC mox-imager.
diff --git a/docs/plat/marvell/index.rst b/docs/plat/marvell/index.rst
new file mode 100644
index 0000000..2d5cdeb
--- /dev/null
+++ b/docs/plat/marvell/index.rst
@@ -0,0 +1,15 @@
+Marvell
+=======
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+
+ armada/build
+ armada/uart-booting
+ armada/porting
+ armada/misc/mvebu-a8k-addr-map
+ armada/misc/mvebu-amb
+ armada/misc/mvebu-ccu
+ armada/misc/mvebu-io-win
+ armada/misc/mvebu-iob
diff --git a/docs/plat/meson-axg.rst b/docs/plat/meson-axg.rst
new file mode 100644
index 0000000..6f6732e
--- /dev/null
+++ b/docs/plat/meson-axg.rst
@@ -0,0 +1,27 @@
+Amlogic Meson A113D (AXG)
+===========================
+
+The Amlogic Meson A113D is a SoC with a quad core Arm Cortex-A53 running at
+~1.2GHz. It also contains a Cortex-M3 used as SCP.
+
+This port is a minimal implementation of BL31 capable of booting mainline U-Boot
+and Linux:
+
+- SCPI support.
+- Basic PSCI support (CPU_ON, CPU_OFF, SYSTEM_RESET, SYSTEM_OFF). Note that CPU0
+ can't be turned off, so there is a workaround to hide this from the caller.
+- GICv2 driver set up.
+- Basic SIP services (read efuse data, enable/disable JTAG).
+
+In order to build it:
+
+.. code:: shell
+
+ CROSS_COMPILE=aarch64-none-elf- make DEBUG=1 PLAT=axg [SPD=opteed]
+ [AML_USE_ATOS=1 when using ATOS as BL32]
+
+This port has been tested on a A113D board. After building it, follow the
+instructions in the `U-Boot repository`_, replacing the mentioned **bl31.img**
+by the one built from this port.
+
+.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/doc/board/amlogic/s400.rst
diff --git a/docs/plat/meson-g12a.rst b/docs/plat/meson-g12a.rst
new file mode 100644
index 0000000..9588ec4
--- /dev/null
+++ b/docs/plat/meson-g12a.rst
@@ -0,0 +1,27 @@
+Amlogic Meson S905X2 (G12A)
+===========================
+
+The Amlogic Meson S905X2 is a SoC with a quad core Arm Cortex-A53 running at
+~1.8GHz. It also contains a Cortex-M3 used as SCP.
+
+This port is a minimal implementation of BL31 capable of booting mainline U-Boot
+and Linux:
+
+- SCPI support.
+- Basic PSCI support (CPU_ON, CPU_OFF, SYSTEM_RESET, SYSTEM_OFF). Note that CPU0
+ can't be turned off, so there is a workaround to hide this from the caller.
+- GICv2 driver set up.
+- Basic SIP services (read efuse data, enable/disable JTAG).
+
+In order to build it:
+
+.. code:: shell
+
+ CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=g12a
+
+This port has been tested on a SEI510 board. After building it, follow the
+instructions in the `gxlimg repository`_ or `U-Boot repository`_, replacing the
+mentioned **bl31.img** by the one built from this port.
+
+.. _gxlimg repository: https://github.com/repk/gxlimg/blob/master/README.g12a
+.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/doc/board/amlogic/sei510.rst
diff --git a/docs/plat/meson-gxbb.rst b/docs/plat/meson-gxbb.rst
new file mode 100644
index 0000000..dbd83e0
--- /dev/null
+++ b/docs/plat/meson-gxbb.rst
@@ -0,0 +1,26 @@
+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.
+
+This port is a minimal implementation of BL31 capable of booting mainline U-Boot
+and Linux:
+
+- SCPI support.
+- Basic PSCI support (CPU_ON, CPU_OFF, SYSTEM_RESET, SYSTEM_OFF). Note that CPU0
+ can't be turned off, so there is a workaround to hide this from the caller.
+- GICv2 driver set up.
+- Basic SIP services (read efuse data, enable/disable JTAG).
+
+In order to build it:
+
+.. code:: shell
+
+ CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=gxbb bl31
+
+This port has been tested in a ODROID-C2. After building it, follow the
+instructions in the `U-Boot repository`_, replacing the mentioned **bl31.bin**
+by the one built from this port.
+
+.. _U-Boot repository: https://gitlab.denx.de/u-boot/u-boot/-/blob/master/board/amlogic/p200/README.odroid-c2
diff --git a/docs/plat/meson-gxl.rst b/docs/plat/meson-gxl.rst
new file mode 100644
index 0000000..0751f1d
--- /dev/null
+++ b/docs/plat/meson-gxl.rst
@@ -0,0 +1,27 @@
+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.
+
+This port is a minimal implementation of BL31 capable of booting mainline U-Boot
+and Linux:
+
+- SCPI support.
+- Basic PSCI support (CPU_ON, CPU_OFF, SYSTEM_RESET, SYSTEM_OFF). Note that CPU0
+ can't be turned off, so there is a workaround to hide this from the caller.
+- GICv2 driver set up.
+- Basic SIP services (read efuse data, enable/disable JTAG).
+
+In order to build it:
+
+.. code:: shell
+
+ CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=gxl
+
+This port has been tested on a Lepotato. After building it, follow the
+instructions in the `gxlimg repository`_ or `U-Boot repository`_, replacing the
+mentioned **bl31.img** by the one built from this port.
+
+.. _gxlimg repository: https://github.com/repk/gxlimg/blob/master/README
+.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/doc/board/amlogic/p212.rst
diff --git a/docs/plat/mt8183.rst b/docs/plat/mt8183.rst
new file mode 100644
index 0000000..c639be1
--- /dev/null
+++ b/docs/plat/mt8183.rst
@@ -0,0 +1,20 @@
+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
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=mt8183 DEBUG=1
diff --git a/docs/plat/mt8186.rst b/docs/plat/mt8186.rst
new file mode 100644
index 0000000..16b833a
--- /dev/null
+++ b/docs/plat/mt8186.rst
@@ -0,0 +1,21 @@
+MediaTek 8186
+=============
+
+MediaTek 8186 (MT8186) is a 64-bit ARM SoC introduced by MediaTek in 2021.
+The chip incorporates eight cores - six Cortex-A55 little cores and two Cortex-A76.
+Cortex-A76 can operate at up to 2.05 GHz.
+Cortex-A55 can operate at up to 2.0 GHz.
+
+Boot Sequence
+-------------
+
+::
+
+ Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel
+
+How to Build
+------------
+
+.. code:: shell
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=mt8186 DEBUG=1 COREBOOT=1
diff --git a/docs/plat/mt8188.rst b/docs/plat/mt8188.rst
new file mode 100644
index 0000000..93abaa5
--- /dev/null
+++ b/docs/plat/mt8188.rst
@@ -0,0 +1,21 @@
+MediaTek 8188
+=============
+
+MediaTek 8188 (MT8188) is a 64-bit ARM SoC introduced by MediaTek in 2022.
+The chip incorporates eight cores - six Cortex-A55 little cores and two Cortex-A78.
+Cortex-A78 can operate at up to 2.6 GHz.
+Cortex-A55 can operate at up to 2.0 GHz.
+
+Boot Sequence
+-------------
+
+::
+
+ Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel
+
+ How to Build
+ ------------
+
+ .. code:: shell
+
+ make CROSS_COMPILE=aarch64-linux-gnu- LD=aarch64-linux-gnu-gcc PLAT=mt8188 DEBUG=1 COREBOOT=1
diff --git a/docs/plat/mt8192.rst b/docs/plat/mt8192.rst
new file mode 100644
index 0000000..369afcf
--- /dev/null
+++ b/docs/plat/mt8192.rst
@@ -0,0 +1,21 @@
+MediaTek 8192
+=============
+
+MediaTek 8192 (MT8192) is a 64-bit ARM SoC introduced by MediaTek in 2020.
+The chip incorporates eight cores - four Cortex-A55 little cores and Cortex-A76.
+Cortex-A76 can operate at up to 2.2 GHz.
+Cortex-A55 can operate at up to 2 GHz.
+
+Boot Sequence
+-------------
+
+::
+
+ Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel
+
+How to Build
+------------
+
+.. code:: shell
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=mt8192 DEBUG=1 COREBOOT=1
diff --git a/docs/plat/mt8195.rst b/docs/plat/mt8195.rst
new file mode 100644
index 0000000..b2aeea2
--- /dev/null
+++ b/docs/plat/mt8195.rst
@@ -0,0 +1,21 @@
+MediaTek 8195
+=============
+
+MediaTek 8195 (MT8195) is a 64-bit ARM SoC introduced by MediaTek in 2021.
+The chip incorporates eight cores - four Cortex-A55 little cores and Cortex-A76.
+Cortex-A76 can operate at up to 2.2 GHz.
+Cortex-A55 can operate at up to 2.0 GHz.
+
+Boot Sequence
+-------------
+
+::
+
+ Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel
+
+How to Build
+------------
+
+.. code:: shell
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=mt8195 DEBUG=1 COREBOOT=1
diff --git a/docs/plat/nvidia-tegra.rst b/docs/plat/nvidia-tegra.rst
new file mode 100644
index 0000000..391c7c8
--- /dev/null
+++ b/docs/plat/nvidia-tegra.rst
@@ -0,0 +1,148 @@
+NVIDIA Tegra
+============
+
+- .. rubric:: T194
+ :name: t194
+
+T194 has eight NVIDIA Carmel CPU cores in a coherent multi-processor
+configuration. The Carmel cores support the ARM Architecture version 8.2,
+executing both 64-bit AArch64 code, and 32-bit AArch32 code. The Carmel
+processors are organized as four dual-core clusters, where each cluster has
+a dedicated 2 MiB Level-2 unified cache. A high speed coherency fabric connects
+these processor complexes and allows heterogeneous multi-processing with all
+eight cores if required.
+
+- .. rubric:: T186
+ :name: t186
+
+The NVIDIA® Parker (T186) series system-on-chip (SoC) delivers a heterogeneous
+multi-processing (HMP) solution designed to optimize performance and
+efficiency.
+
+T186 has Dual NVIDIA Denver2 ARM® CPU cores, plus Quad ARM Cortex®-A57 cores,
+in a coherent multiprocessor configuration. The Denver 2 and Cortex-A57 cores
+support ARMv8, executing both 64-bit Aarch64 code, and 32-bit Aarch32 code
+including legacy ARMv7 applications. The Denver 2 processors each have 128 KB
+Instruction and 64 KB Data Level 1 caches; and have a 2MB shared Level 2
+unified cache. The Cortex-A57 processors each have 48 KB Instruction and 32 KB
+Data Level 1 caches; and also have a 2 MB shared Level 2 unified cache. A
+high speed coherency fabric connects these two processor complexes and allows
+heterogeneous multi-processing with all six cores if required.
+
+Denver is NVIDIA's own custom-designed, 64-bit, dual-core CPU which is
+fully Armv8-A architecture compatible. Each of the two Denver cores
+implements a 7-way superscalar microarchitecture (up to 7 concurrent
+micro-ops can be executed per clock), and includes a 128KB 4-way L1
+instruction cache, a 64KB 4-way L1 data cache, and a 2MB 16-way L2
+cache, which services both cores.
+
+Denver implements an innovative process called Dynamic Code Optimization,
+which optimizes frequently used software routines at runtime into dense,
+highly tuned microcode-equivalent routines. These are stored in a
+dedicated, 128MB main-memory-based optimization cache. After being read
+into the instruction cache, the optimized micro-ops are executed,
+re-fetched and executed from the instruction cache as long as needed and
+capacity allows.
+
+Effectively, this reduces the need to re-optimize the software routines.
+Instead of using hardware to extract the instruction-level parallelism
+(ILP) inherent in the code, Denver extracts the ILP once via software
+techniques, and then executes those routines repeatedly, thus amortizing
+the cost of ILP extraction over the many execution instances.
+
+Denver also features new low latency power-state transitions, in addition
+to extensive power-gating and dynamic voltage and clock scaling based on
+workloads.
+
+- .. rubric:: T210
+ :name: t210
+
+T210 has Quad Arm® Cortex®-A57 cores in a switched configuration with a
+companion set of quad Arm Cortex-A53 cores. The Cortex-A57 and A53 cores
+support Armv8-A, executing both 64-bit Aarch64 code, and 32-bit Aarch32 code
+including legacy Armv7-A applications. The Cortex-A57 processors each have
+48 KB Instruction and 32 KB Data Level 1 caches; and have a 2 MB shared
+Level 2 unified cache. The Cortex-A53 processors each have 32 KB Instruction
+and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache.
+
+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'.
+
+- Trusted Little Kernel (TLK): In order to include the 'tlkd' dispatcher in
+ the image, pass 'SPD=tlkd' on the command line while preparing a bl31 image.
+- Trusty: In order to include the 'trusty' dispatcher in the image, pass
+ 'SPD=trusty' on the command line while preparing a bl31 image.
+
+This allows other Trusted OS vendors to use the upstream code and include
+their dispatchers in the image without changing any makefiles.
+
+These are the supported Trusted OS' by Tegra platforms.
+
+- Tegra210: TLK and Trusty
+- Tegra186: Trusty
+- Tegra194: 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
+exists a common scatter file, plat/nvidia/tegra/scat/bl31.scat, for all Tegra
+SoCs. The `LINKER` build variable needs to point to the ARMLINK binary for
+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
+
+ CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- make PLAT=tegra \
+ TARGET_SOC=<target-soc e.g. t194|t186|t210> SPD=<dispatcher e.g. trusty|tlkd>
+ bl31
+
+Platforms wanting to use different TZDRAM\_BASE, can add ``TZDRAM_BASE=<value>``
+to the build command line.
+
+The Tegra platform code expects a pointer to the following platform specific
+structure via 'x1' register from the BL2 layer which is used by the
+bl31\_early\_platform\_setup() handler to extract the TZDRAM carveout base and
+size for loading the Trusted OS and the UART port ID to be used. The Tegra
+memory controller driver programs this base/size in order to restrict NS
+accesses.
+
+typedef struct plat\_params\_from\_bl2 {
+/\* TZ memory size */
+uint64\_t tzdram\_size;
+/* TZ memory base */
+uint64\_t tzdram\_base;
+/* UART port ID \*/
+int uart\_id;
+/* L2 ECC parity protection disable flag \*/
+int l2\_ecc\_parity\_prot\_dis;
+/* SHMEM base address for storing the boot logs \*/
+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
+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
+ be enabled by Tegrs SoCs during 'Cluster power up' or 'System Suspend' exit.
diff --git a/docs/plat/nxp/index.rst b/docs/plat/nxp/index.rst
new file mode 100644
index 0000000..8546887
--- /dev/null
+++ b/docs/plat/nxp/index.rst
@@ -0,0 +1,17 @@
+NXP Reference Development Platforms
+===================================
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+
+ nxp-layerscape
+ nxp-ls-fuse-prov
+ nxp-ls-tbbr
+
+This chapter holds documentation related to NXP reference development platforms.
+It includes details on image flashing, fuse provisioning and trusted board boot-up.
+
+--------------
+
+*Copyright (c) 2021, NXP Limited. All rights reserved.*
diff --git a/docs/plat/nxp/nxp-layerscape.rst b/docs/plat/nxp/nxp-layerscape.rst
new file mode 100644
index 0000000..cd5874b
--- /dev/null
+++ b/docs/plat/nxp/nxp-layerscape.rst
@@ -0,0 +1,473 @@
+NXP SoCs - Overview
+=====================
+.. section-numbering::
+ :suffix: .
+
+The QorIQ family of ARM based SoCs that are supported on TF-A are:
+
+1. LX2160A
+
+- SoC Overview:
+
+The LX2160A multicore processor, the highest-performance member of the
+Layerscape family, combines FinFET process technology's low power and
+sixteen Arm® Cortex®-A72 cores with datapath acceleration optimized for
+L2/3 packet processing, together with security offload, robust traffic
+management and quality of service.
+
+Details about LX2160A can be found at `lx2160a`_.
+
+- LX2160ARDB Board:
+
+The LX2160A reference design board provides a comprehensive platform
+that enables design and evaluation of the LX2160A or LX2162A processors. It
+comes preloaded with a board support package (BSP) based on a standard Linux
+kernel.
+
+Board details can be fetched from the link: `lx2160ardb`_.
+
+2. LS1028A
+
+- SoC Overview:
+
+The Layerscape LS1028A applications processor for industrial and
+automotive includes a time-sensitive networking (TSN) -enabled Ethernet
+switch and Ethernet controllers to support converged IT and OT networks.
+Two powerful 64-bit Arm®v8 cores support real-time processing for
+industrial control and virtual machines for edge computing in the IoT.
+The integrated GPU and LCD controller enable Human-Machine Interface
+(HMI) systems with next-generation interfaces.
+
+Details about LS1028A can be found at `ls1028a`_.
+
+- LS1028ARDB Board:
+
+The LS1028A reference design board (RDB) is a computing, evaluation,
+and development platform that supports industrial IoT applications, human
+machine interface solutions, and industrial networking.
+
+Details about LS1028A RDB board can be found at `ls1028ardb`_.
+
+3. LS1043A
+
+- SoC Overview:
+
+The Layerscape LS1043A processor is NXP's first quad-core, 64-bit Arm®-based
+processor for embedded networking. The LS1023A (two core version) and the
+LS1043A (four core version) deliver greater than 10 Gbps of performance
+in a flexible I/O package supporting fanless designs. This SoC is a
+purpose-built solution for small-form-factor networking and industrial
+applications with BOM optimizations for economic low layer PCB, lower cost
+power supply and single clock design. The new 0.9V versions of the LS1043A
+and LS1023A deliver addition power savings for applications such as Wireless
+LAN and to Power over Ethernet systems.
+
+Details about LS1043A can be found at `ls1043a`_.
+
+- LS1043ARDB Board:
+
+The LS1043A reference design board (RDB) is a computing, evaluation, and
+development platform that supports the Layerscape LS1043A architecture
+processor. The LS1043A-RDB can help shorten your time to market by providing
+the following features:
+
+Memory subsystem:
+ * 2GByte DDR4 SDRAM (32bit bus)
+ * 128 Mbyte NOR flash single-chip memory
+ * 512 Mbyte NAND flash
+ * 16 Mbyte high-speed SPI flash
+ * SD connector to interface with the SD memory card
+
+Ethernet:
+ * XFI 10G port
+ * QSGMII with 4x 1G ports
+ * Two RGMII ports
+
+PCIe:
+ * PCIe2 (Lanes C) to mini-PCIe slot
+ * PCIe3 (Lanes D) to PCIe slot
+
+USB 3.0: two super speed USB 3.0 type A ports
+
+UART: supports two UARTs up to 115200 bps for console
+
+Details about LS1043A RDB board can be found at `ls1043ardb`_.
+
+4. LS1046A
+
+- SoC Overview:
+
+The LS1046A is a cost-effective, power-efficient, and highly integrated
+system-on-chip (SoC) design that extends the reach of the NXP value-performance
+line of QorIQ communications processors. Featuring power-efficient 64-bit
+Arm Cortex-A72 cores with ECC-protected L1 and L2 cache memories for high
+reliability, running up to 1.8 GHz.
+
+Details about LS1046A can be found at `ls1046a`_.
+
+- LS1046ARDB Board:
+
+The LS1046A reference design board (RDB) is a high-performance computing,
+evaluation, and development platform that supports the Layerscape LS1046A
+architecture processor. The LS1046ARDB board supports the Layerscape LS1046A
+processor and is optimized to support the DDR4 memory and a full complement
+of high-speed SerDes ports.
+
+Details about LS1046A RDB board can be found at `ls1046ardb`_.
+
+- LS1046AFRWY Board:
+
+The LS1046A Freeway board (FRWY) is a high-performance computing, evaluation,
+and development platform that supports the LS1046A architecture processor
+capable of support more than 32,000 CoreMark performance. The FRWY-LS1046A
+board supports the LS1046A processor, onboard DDR4 memory, multiple Gigabit
+Ethernet, USB3.0 and M2_Type_E interfaces for Wi-Fi, FRWY-LS1046A-AC includes
+the Wi-Fi card.
+
+Details about LS1046A FRWY board can be found at `ls1046afrwy`_.
+
+5. LS1088A
+
+- SoC Overview:
+
+The LS1088A family of multicore communications processors combines up to and eight
+Arm Cortex-A53 cores with the advanced, high-performance data path and network
+peripheral interfaces required for wireless access points, networking infrastructure,
+intelligent edge access, including virtual customer premise equipment (vCPE) and
+high-performance industrial applications.
+
+Details about LS1088A can be found at `ls1088a`_.
+
+- LS1088ARDB Board:
+
+The LS1088A reference design board provides a comprehensive platform that
+enables design and evaluation of the product (LS1088A processor). This RDB
+comes pre-loaded with a board support package (BSP) based on a standard
+Linux kernel.
+
+Details about LS1088A RDB board can be found at `ls1088ardb`_.
+
+Table of supported boot-modes by each platform & platform that needs FIP-DDR:
+-----------------------------------------------------------------------------
+
++---------------------+---------------------------------------------------------------------+-----------------+
+| | BOOT_MODE | |
+| PLAT +-------+--------+-------+-------+-------+-------------+--------------+ fip_ddr_needed |
+| | sd | qspi | nor | nand | emmc | flexspi_nor | flexspi_nand | |
++=====================+=======+========+=======+=======+=======+=============+==============+=================+
+| lx2160ardb | yes | | | | yes | yes | | yes |
++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+
+| ls1028ardb | yes | | | | yes | yes | | no |
++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+
+| ls1043ardb | yes | | yes | yes | | | | no |
++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+
+| ls1046ardb | yes | yes | | | yes | | | no |
++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+
+| ls1046afrwy | yes | yes | | | | | | no |
++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+
+| ls1088ardb | yes | yes | | | | | | no |
++---------------------+-------+--------+-------+-------+-------+-------------+--------------+-----------------+
+
+
+Boot Sequence
+-------------
+::
+
++ Secure World | Normal World
++ EL0 |
++ |
++ EL1 BL32(Tee OS) | kernel
++ ^ | | ^
++ | | | |
++ EL2 | | | BL33(u-boot)
++ | | | ^
++ | v | /
++ EL3 BootROM --> BL2 --> BL31 ---------------/
++
+
+Boot Sequence with FIP-DDR
+--------------------------
+::
+
++ Secure World | Normal World
++ EL0 |
++ |
++ EL1 fip-ddr BL32(Tee OS) | kernel
++ ^ | ^ | | ^
++ | | | | | |
++ EL2 | | | | | BL33(u-boot)
++ | | | | | ^
++ | v | v | /
++ EL3 BootROM --> BL2 -----> BL31 ---------------/
++
+
+DDR Memory Layout
+--------------------------
+
+NXP Platforms divide DRAM into banks:
+
+- DRAM0 Bank: Maximum size of this bank is fixed to 2GB, DRAM0 size is defined in platform_def.h if it is less than 2GB.
+
+- DRAM1 ~ DRAMn Bank: Greater than 2GB belongs to DRAM1 and following banks, and size of DRAMn Bank varies for one platform to others.
+
+The following diagram is default DRAM0 memory layout in which secure memory is at top of DRAM0.
+
+::
+
+ high +---------------------------------------------+
+ | |
+ | Secure EL1 Payload Shared Memory (2 MB) |
+ | |
+ +---------------------------------------------+
+ | |
+ | Secure Memory (64 MB) |
+ | |
+ +---------------------------------------------+
+ | |
+ | Non Secure Memory |
+ | |
+ low +---------------------------------------------+
+
+How to build
+=============
+
+Code Locations
+--------------
+
+- OP-TEE:
+ `link <https://source.codeaurora.org/external/qoriq/qoriq-components/optee_os>`__
+
+- U-Boot:
+ `link <https://source.codeaurora.org/external/qoriq/qoriq-components/u-boot>`__
+
+- RCW:
+ `link <https://source.codeaurora.org/external/qoriq/qoriq-components/rcw>`__
+
+- ddr-phy-binary: Required by platforms that need fip-ddr.
+ `link <https:://github.com/NXP/ddr-phy-binary>`__
+
+- cst: Required for TBBR.
+ `link <https:://source.codeaurora.org/external/qoriq/qoriq-components/cst>`__
+
+Build Procedure
+---------------
+
+- Fetch all the above repositories into local host.
+
+- Prepare AARCH64 toolchain and set the environment variable "CROSS_COMPILE".
+
+ .. code:: shell
+
+ export CROSS_COMPILE=.../bin/aarch64-linux-gnu-
+
+- Build RCW. Refer README from the respective cloned folder for more details.
+
+- Build u-boot and OPTee firstly, and get binary images: u-boot.bin and tee.bin.
+ For u-boot you can use the <platform>_tfa_defconfig for build.
+
+- Copy/clone the repo "ddr-phy-binary" to the tfa directory for platform needing ddr-fip.
+
+- Below are the steps to build TF-A images for the supported platforms.
+
+Compilation steps without BL32
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+BUILD BL2:
+
+-To compile
+ .. code:: shell
+
+ make PLAT=$PLAT \
+ BOOT_MODE=<platform_supported_boot_mode> \
+ RCW=$RCW_BIN \
+ pbl
+
+BUILD FIP:
+
+ .. code:: shell
+
+ make PLAT=$PLAT \
+ BOOT_MODE=<platform_supported_boot_mode> \
+ RCW=$RCW_BIN \
+ BL33=$UBOOT_SECURE_BIN \
+ pbl \
+ fip
+
+Compilation steps with BL32
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+BUILD BL2:
+
+-To compile
+ .. code:: shell
+
+ make PLAT=$PLAT \
+ BOOT_MODE=<platform_supported_boot_mode> \
+ RCW=$RCW_BIN \
+ BL32=$TEE_BIN SPD=opteed\
+ pbl
+
+BUILD FIP:
+
+ .. code:: shell
+
+ make PLAT=$PLAT \
+ BOOT_MODE=<platform_supported_boot_mode> \
+ RCW=$RCW_BIN \
+ BL32=$TEE_BIN SPD=opteed\
+ BL33=$UBOOT_SECURE_BIN \
+ pbl \
+ fip
+
+
+BUILD fip-ddr (Mandatory for certain platforms, refer table above):
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-To compile additional fip-ddr for selected platforms(Refer above table if the platform needs fip-ddr).
+ .. code:: shell
+
+ make PLAT=<platform_name> fip-ddr
+
+
+Deploy ATF Images
+=================
+
+Note: The size in the standard uboot commands for copy to nor, qspi, nand or sd
+should be modified based on the binary size of the image to be copied.
+
+- Deploy ATF images on flexspi-Nor or QSPI flash Alt Bank from U-Boot prompt.
+
+ -- Commands to flash images for bl2_xxx.pbl and fip.bin
+
+ Notes: ls1028ardb has no flexspi-Nor Alt Bank, so use "sf probe 0:0" for current bank.
+
+ .. code:: shell
+
+ tftp 82000000 $path/bl2_xxx.pbl;
+
+ i2c mw 66 50 20;sf probe 0:1; sf erase 0 +$filesize; sf write 0x82000000 0x0 $filesize;
+
+ tftp 82000000 $path/fip.bin;
+ i2c mw 66 50 20;sf probe 0:1; sf erase 0x100000 +$filesize; sf write 0x82000000 0x100000 $filesize;
+
+ -- Next step is valid for platform where FIP-DDR is needed.
+
+ .. code:: shell
+
+ tftp 82000000 $path/ddr_fip.bin;
+ i2c mw 66 50 20;sf probe 0:1; sf erase 0x800000 +$filesize; sf write 0x82000000 0x800000 $filesize;
+
+ -- Then reset to alternate bank to boot up ATF.
+
+ Command for lx2160a, ls1088a and ls1028a platforms:
+
+ .. code:: shell
+
+ qixisreset altbank;
+
+ Command for ls1046a platforms:
+
+ .. code:: shell
+
+ cpld reset altbank;
+
+- Deploy ATF images on SD/eMMC from U-Boot prompt.
+ -- file_size_in_block_sizeof_512 = (Size_of_bytes_tftp / 512)
+
+ .. code:: shell
+
+ mmc dev <idx>; (idx = 1 for eMMC; idx = 0 for SD)
+
+ tftp 82000000 $path/bl2_<sd>_or_<emmc>.pbl;
+ mmc write 82000000 8 <file_size_in_block_sizeof_512>;
+
+ tftp 82000000 $path/fip.bin;
+ mmc write 82000000 0x800 <file_size_in_block_sizeof_512>;
+
+ -- Next step is valid for platform that needs FIP-DDR.
+
+ .. code:: shell
+
+ tftp 82000000 $path/ddr_fip.bin;
+ mmc write 82000000 0x4000 <file_size_in_block_sizeof_512>;
+
+ -- Then reset to sd/emmc to boot up ATF from sd/emmc as boot-source.
+
+ Command for lx2160A, ls1088a and ls1028a platforms:
+
+ .. code:: shell
+
+ qixisreset <sd or emmc>;
+
+ Command for ls1043a and ls1046a platform:
+
+ .. code:: shell
+
+ cpld reset <sd or emmc>;
+
+- Deploy ATF images on IFC nor flash from U-Boot prompt.
+
+ .. code:: shell
+
+ tftp 82000000 $path/bl2_nor.pbl;
+ protect off 64000000 +$filesize; erase 64000000 +$filesize; cp.b 82000000 64000000 $filesize;
+
+ tftp 82000000 $path/fip.bin;
+ protect off 64100000 +$filesize; erase 64100000 +$filesize; cp.b 82000000 64100000 $filesize;
+
+ -- Then reset to alternate bank to boot up ATF.
+
+ Command for ls1043a platform:
+
+ .. code:: shell
+
+ cpld reset altbank;
+
+- Deploy ATF images on IFC nand flash from U-Boot prompt.
+
+ .. code:: shell
+
+ tftp 82000000 $path/bl2_nand.pbl;
+ nand erase 0x0 $filesize; nand write 82000000 0x0 $filesize;
+
+ tftp 82000000 $path/fip.bin;
+ nand erase 0x100000 $filesize;nand write 82000000 0x100000 $filesize;
+
+ -- Then reset to nand flash to boot up ATF.
+
+ Command for ls1043a platform:
+
+ .. code:: shell
+
+ cpld reset nand;
+
+
+
+Trusted Board Boot:
+===================
+
+For TBBR, the binary name changes:
+
++-------------+--------------------------+---------+-------------------+
+| Boot Type | BL2 | FIP | FIP-DDR |
++=============+==========================+=========+===================+
+| Normal Boot | bl2_<boot_mode>.pbl | fip.bin | ddr_fip.bin |
++-------------+--------------------------+---------+-------------------+
+| TBBR Boot | bl2_<boot_mode>_sec.pbl | fip.bin | ddr_fip_sec.bin |
++-------------+--------------------------+---------+-------------------+
+
+Refer `nxp-ls-tbbr.rst`_ for detailed user steps.
+
+
+.. _lx2160a: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-lx2160a-lx2120a-lx2080a-processors:LX2160A
+.. _lx2160ardb: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-communication-process/layerscape-lx2160a-multicore-communications-processor:LX2160A
+.. _ls1028a: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-1028a-applications-processor:LS1028A
+.. _ls1028ardb: https://www.nxp.com/design/qoriq-developer-resources/layerscape-ls1028a-reference-design-board:LS1028ARDB
+.. _ls1043a: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-1043a-and-1023a-processors:LS1043A
+.. _ls1043ardb: https://www.nxp.com/design/qoriq-developer-resources/layerscape-ls1043a-reference-design-board:LS1043A-RDB
+.. _ls1046a: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-1046a-and-1026a-processors:LS1046A
+.. _ls1046ardb: https://www.nxp.com/design/qoriq-developer-resources/layerscape-ls1046a-reference-design-board:LS1046A-RDB
+.. _ls1046afrwy: https://www.nxp.com/design/qoriq-developer-resources/ls1046a-freeway-board:FRWY-LS1046A
+.. _ls1088a: https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/layerscape-processors/layerscape-1088a-and-1048a-processor:LS1088A
+.. _ls1088ardb: https://www.nxp.com/design/qoriq-developer-resources/layerscape-ls1088a-reference-design-board:LS1088A-RDB
+.. _nxp-ls-tbbr.rst: ./nxp-ls-tbbr.rst
diff --git a/docs/plat/nxp/nxp-ls-fuse-prov.rst b/docs/plat/nxp/nxp-ls-fuse-prov.rst
new file mode 100644
index 0000000..64e1c6f
--- /dev/null
+++ b/docs/plat/nxp/nxp-ls-fuse-prov.rst
@@ -0,0 +1,271 @@
+
+Steps to blow fuses on NXP LS SoC:
+==================================
+
+
+- Enable POVDD
+ -- Refer board GSG(Getting Started Guide) for the steps to enable POVDD.
+ -- Once the POVDD is enabled, make sure to set variable POVDD_ENABLE := yes, in the platform.mk.
+
++---+-----------------+-----------+------------+-----------------+-----------------------------+
+| | Platform | Jumper | Switch | LED to Verify | Through GPIO Pin (=number) |
++===+=================+===========+============+=================+=============================+
+| 1.| lx2160ardb | J9 | | | no |
++---+-----------------+-----------+------------+-----------------+-----------------------------+
+| 2.| lx2160aqds | J35 | | | no |
++---+-----------------+-----------+------------+-----------------+-----------------------------+
+| 3.| lx2162aqds | J35 | SW9[4] = 1 | D15 | no |
++---+-----------------+-----------+------------+-----------------+-----------------------------+
+
+- SFP registers to be written to:
+
++---+----------------------------------+----------------------+----------------------+
+| | Platform | OTPMKR0..OTPMKR7 | SRKHR0..SRKHR7 |
++===+==================================+======================+======================+
+| 1.| lx2160ardb/lx2160aqds/lx2162aqds | 0x1e80234..0x1e80250 | 0x1e80254..0x1e80270 |
++---+----------------------------------+----------------------+----------------------+
+
+- At U-Boot prompt, verify that SNVS register - HPSR, whether OTPMK was written, already:
+
++---+----------------------------------+-------------------------------------------+---------------+
+| | Platform | OTPMK_ZERO_BIT(=value) | SNVS_HPSR_REG |
++===+==================================+===========================================+===============+
+| 1.| lx2160ardb/lx2160aqds/lx2162aqds | 27 (= 1 means not blown, =0 means blown) | 0x01E90014 |
++---+----------------------------------+-------------------------------------------+---------------+
+
+From u-boot prompt:
+
+ -- Check for the OTPMK.
+ .. code:: shell
+
+ md $SNVS_HPSR_REG
+
+ Command Output:
+ 01e90014: 88000900
+
+ In case it is read as 00000000, then read this register using jtag (in development mode only through CW tap).
+ +0 +4 +8 +C
+ [0x01E90014] 88000900
+
+ Note: OTPMK_ZERO_BIT is 1, indicating that the OTPMK is not blown.
+
+ -- Check for the SRK Hash.
+ .. code:: shell
+
+ md $SRKHR0 0x10
+
+ Command Output:
+ 01e80254: 00000000 00000000 00000000 00000000 ................
+ 01e80264: 00000000 00000000 00000000 00000000 ................
+
+ Note: Zero means that SRK hash is not blown.
+
+- If not blown, then from the U-Boot prompt, using following commands:
+ -- Provision the OTPMK.
+
+ .. code:: shell
+
+ mw.l $OTPMKR0 <OTMPKR_0_32Bit_val>
+ mw.l $OTPMKR1 <OTMPKR_1_32Bit_val>
+ mw.l $OTPMKR2 <OTMPKR_2_32Bit_val>
+ mw.l $OTPMKR3 <OTMPKR_3_32Bit_val>
+ mw.l $OTPMKR4 <OTMPKR_4_32Bit_val>
+ mw.l $OTPMKR5 <OTMPKR_5_32Bit_val>
+ mw.l $OTPMKR6 <OTMPKR_6_32Bit_val>
+ mw.l $OTPMKR7 <OTMPKR_7_32Bit_val>
+
+ -- Provision the SRK Hash.
+
+ .. code:: shell
+
+ mw.l $SRKHR0 <SRKHR_0_32Bit_val>
+ mw.l $SRKHR1 <SRKHR_1_32Bit_val>
+ mw.l $SRKHR2 <SRKHR_2_32Bit_val>
+ mw.l $SRKHR3 <SRKHR_3_32Bit_val>
+ mw.l $SRKHR4 <SRKHR_4_32Bit_val>
+ mw.l $SRKHR5 <SRKHR_5_32Bit_val>
+ mw.l $SRKHR6 <SRKHR_6_32Bit_val>
+ mw.l $SRKHR7 <SRKHR_7_32Bit_val>
+
+ Note: SRK Hash should be carefully written keeping in mind the SFP Block Endianness.
+
+- At U-Boot prompt, verify that SNVS registers for OTPMK are correctly written:
+
+ -- Check for the OTPMK.
+ .. code:: shell
+
+ md $SNVS_HPSR_REG
+
+ Command Output:
+ 01e90014: 80000900
+
+ OTPMK_ZERO_BIT is zero, indicating that the OTPMK is blown.
+
+ Note: In case it is read as 00000000, then read this register using jtag (in development mode only through CW tap).
+
+ .. code:: shell
+
+ md $OTPMKR0 0x10
+
+ Command Output:
+ 01e80234: ffffffff ffffffff ffffffff ffffffff ................
+ 01e80244: ffffffff ffffffff ffffffff ffffffff ................
+
+ Note: OTPMK will never be visible in plain.
+
+ -- Check for the SRK Hash. For example, if following SRK hash is written:
+
+ SFP SRKHR0 = fdc2fed4
+ SFP SRKHR1 = 317f569e
+ SFP SRKHR2 = 1828425c
+ SFP SRKHR3 = e87b5cfd
+ SFP SRKHR4 = 34beab8f
+ SFP SRKHR5 = df792a70
+ SFP SRKHR6 = 2dff85e1
+ SFP SRKHR7 = 32a29687,
+
+ then following would be the value on dumping SRK hash.
+
+ .. code:: shell
+
+ md $SRKHR0 0x10
+
+ Command Output:
+ 01e80254: d4fec2fd 9e567f31 5c422818 fd5c7be8 ....1.V..(B\.{\.
+ 01e80264: 8fabbe34 702a79df e185ff2d 8796a232 4....y*p-...2...
+
+ Note: SRK Hash is visible in plain based on the SFP Block Endianness.
+
+- Caution: Donot proceed to the next step, until you are sure that OTPMK and SRKH are correctly blown from above steps.
+ -- After the next step, there is no turning back.
+ -- Fuses will be burnt, which cannot be undo.
+
+- Write SFP_INGR[INST] with the PROGFB(0x2) instruction to blow the fuses.
+ -- User need to save the SRK key pair and OTPMK Key forever, to continue using this board.
+
++---+----------------------------------+-------------------------------------------+-----------+
+| | Platform | SFP_INGR_REG | SFP_WRITE_DATE_FRM_MIRROR_REG_TO_FUSE |
++===+==================================+=======================================================+
+| 1.| lx2160ardb/lx2160aqds/lx2162aqds | 0x01E80020 | 0x2 |
++---+----------------------------------+--------------+----------------------------------------+
+
+ .. code:: shell
+
+ md $SFP_INGR_REG $SFP_WRITE_DATE_FRM_MIRROR_REG_TO_FUSE
+
+- On reset, if the SFP register were read from u-boot, it will show the following:
+ -- Check for the OTPMK.
+
+ .. code:: shell
+
+ md $SNVS_HPSR_REG
+
+ Command Output:
+ 01e90014: 80000900
+
+ In case it is read as 00000000, then read this register using jtag (in development mode only through CW tap).
+ +0 +4 +8 +C
+ [0x01E90014] 80000900
+
+ Note: OTPMK_ZERO_BIT is zero, indicating that the OTPMK is blown.
+
+ .. code:: shell
+
+ md $OTPMKR0 0x10
+
+ Command Output:
+ 01e80234: ffffffff ffffffff ffffffff ffffffff ................
+ 01e80244: ffffffff ffffffff ffffffff ffffffff ................
+
+ Note: OTPMK will never be visible in plain.
+
+ -- SRK Hash
+
+ .. code:: shell
+
+ md $SRKHR0 0x10
+
+ Command Output:
+ 01e80254: d4fec2fd 9e567f31 5c422818 fd5c7be8 ....1.V..(B\.{\.
+ 01e80264: 8fabbe34 702a79df e185ff2d 8796a232 4....y*p-...2...
+
+ Note: SRK Hash is visible in plain based on the SFP Block Endianness.
+
+Second method to do the fuse provsioning:
+=========================================
+
+This method is used for quick way to provision fuses.
+Typically used by those who needs to provision number of boards.
+
+- Enable POVDD:
+ -- Refer the table above to enable POVDD.
+
+ Note: If GPIO Pin supports enabling POVDD, it can be done through the below input_fuse_file.
+
+ -- Once the POVDD is enabled, make sure to set variable POVDD_ENABLE := yes, in the platform.mk.
+
+- User need to populate the "input_fuse_file", corresponding to the platform for:
+
+ -- OTPMK
+ -- SRKH
+
+ Table of fuse provisioning input file for every supported platform:
+
++---+----------------------------------+-----------------------------------------------------------------+
+| | Platform | FUSE_PROV_FILE |
++===+==================================+=================================================================+
+| 1.| lx2160ardb/lx2160aqds/lx2162aqds | ${CST_DIR}/input_files/gen_fusescr/ls2088_1088/input_fuse_file |
++---+----------------------------------+--------------+--------------------------------------------------+
+
+- Create the TF-A binary with FUSE_PROG=1.
+
+ .. code:: shell
+
+ make PLAT=$PLAT FUSE_PROG=1\
+ BOOT_MODE=<platform_supported_boot_mode> \
+ RCW=$RCW_BIN \
+ BL32=$TEE_BIN SPD=opteed\
+ BL33=$UBOOT_SECURE_BIN \
+ pbl \
+ fip \
+ fip_fuse \
+ FUSE_PROV_FILE=../../apps/security/cst/input_files/gen_fusescr/ls2088_1088/input_fuse_file
+
+- Deployment:
+ -- Refer the nxp-layerscape.rst for deploying TF-A images.
+ -- Deploying fip_fuse.bin:
+
+ For Flexspi-Nor:
+
+ .. code:: shell
+
+ tftp 82000000 $path/fuse_fip.bin;
+ i2c mw 66 50 20;sf probe 0:0; sf erase 0x880000 +$filesize; sf write 0x82000000 0x880000 $filesize;
+
+ For SD or eMMC [file_size_in_block_sizeof_512 = (Size_of_bytes_tftp / 512)]:
+
+ .. code:: shell
+
+ tftp 82000000 $path/fuse_fip.bin;
+ mmc write 82000000 0x4408 <file_size_in_block_sizeof_512>;
+
+- Valiation:
+
++---+----------------------------------+---------------------------------------------------+
+| | Platform | Error_Register | Error_Register_Address |
++===+==================================+===================================================+
+| 1.| lx2160ardb/lx2160aqds/lx2162aqds | DCFG scratch 4 register | 0x01EE020C |
++---+----------------------------------+---------------------------------------------------+
+
+ At the U-Boot prompt, check DCFG scratch 4 register for any error.
+
+ .. code:: shell
+
+ md $Error_Register_Address 1
+
+ Command Ouput:
+ 01ee020c: 00000000
+
+ Note:
+ - 0x00000000 shows no error, then fuse provisioning is successful.
+ - For non-zero value, refer the code header file ".../drivers/nxp/sfp/sfp_error_codes.h"
diff --git a/docs/plat/nxp/nxp-ls-tbbr.rst b/docs/plat/nxp/nxp-ls-tbbr.rst
new file mode 100644
index 0000000..43e15f7
--- /dev/null
+++ b/docs/plat/nxp/nxp-ls-tbbr.rst
@@ -0,0 +1,210 @@
+
+--------------
+NXP Platforms:
+--------------
+TRUSTED_BOARD_BOOT option can be enabled by specifying TRUSTED_BOARD_BOOT=1 on command line during make.
+
+
+
+Bare-Minimum Preparation to run TBBR on NXP Platforms:
+=======================================================
+- OTPMK(One Time Programable Key) needs to be burnt in fuses.
+ -- It is the 256 bit key that stores a secret value used by the NXP SEC 4.0 IP in Trusted or Secure mode.
+
+ Note: It is primarily for the purpose of decrypting additional secrets stored in system non-volatile memory.
+
+ -- NXP CST tool gives an option to generate it.
+
+ Use the below command from directory 'cst', with correct options.
+
+ .. code:: shell
+
+ ./gen_otpmk_drbg
+
+- SRKH (Super Root Key Hash) needs to be burnt in fuses.
+ -- It is the 256 bit hash of the list of the public keys of the SRK key pair.
+ -- NXP CST tool gives an option to generate the RSA key pair and its hash.
+
+ Use the below command from directory 'cst', with correct options.
+
+ .. code:: shell
+
+ ./gen_keys
+
+Refer fuse frovisioning readme 'nxp-ls-fuse-prov.rst' for steps to blow these keys.
+
+
+
+Two options are provided for TRUSTED_BOARD_BOOT:
+================================================
+
+-------------------------------------------------------------------------
+Option 1: CoT using X 509 certificates
+-------------------------------------------------------------------------
+
+- This CoT is as provided by ARM.
+
+- To use this option user needs to specify mbedtld dir path in MBEDTLS_DIR.
+
+- To generate CSF header, path of CST repository needs to be specified as CST_DIR
+
+- CSF header is embedded to each of the BL2 image.
+
+- GENERATE_COT=1 adds the tool 'cert_create' to the build environment to generate:
+ -- X509 Certificates as (.crt) files.
+ -- X509 Pem key file as (.pem) files.
+
+- SAVE_KEYS=1 saves the keys and certificates, if GENERATE_COT=1.
+ -- For this to work, file name for cert and keys are provided as part of compilation or build command.
+
+ --- default file names will be used, incase not provided as part compilation or build command.
+ --- default folder 'BUILD_PLAT' will be used to store them.
+
+- ROTPK for x.509 certificates is generated and embedded in bl2.bin and
+ verified as part of CoT by Boot ROM during secure boot.
+
+- Compilation steps:
+
+All Images
+ .. code:: shell
+
+ make PLAT=$PLAT TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 MBEDTLS_DIR=$MBEDTLS_PATH CST_DIR=$CST_DIR_PATH \
+ BOOT_MODE=<platform_supported_boot_mode> \
+ RCW=$RCW_BIN \
+ BL32=$TEE_BIN SPD=opteed\
+ BL33=$UBOOT_SECURE_BIN \
+ pbl \
+ fip
+
+Additional FIP_DDR Image (For NXP platforms like lx2160a)
+ .. code:: shell
+
+ make PLAT=$PLAT TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 MBEDTLS_DIR=$MBEDTLS_PATH fip_ddr
+
+ Note: make target 'fip_ddr' should never be combine with other make target 'fip', 'pbl' & 'bl2'.
+
+-------------------------------------------------------------------------
+Option 2: CoT using NXP CSF headers.
+-------------------------------------------------------------------------
+
+- This option is automatically selected when TRUSTED_BOARD_BOOT is set but MBEDTLS_DIR path is not specified.
+
+- CSF header is embedded to each of the BL31, BL32 and BL33 image.
+
+- To generate CSF header, path of CST repository needs to be specified as CST_DIR
+
+- Default input files for CSF header generation is added in this repo.
+
+- Default input file requires user to generate RSA key pair named
+ -- srk.pri, and
+ -- srk.pub, and add them in ATF repo.
+ -- These keys can be generated using gen_keys tool of CST.
+
+- To change the input file , user can use the options BL33_INPUT_FILE, BL32_INPUT_FILE, BL31_INPUT_FILE
+
+- There are 2 paths in secure boot flow :
+ -- Development Mode (sb_en in RCW = 1, SFP->OSPR, ITS = 0)
+
+ --- In this flow , even on ROTPK comparison failure, flow would continue.
+ --- However SNVS is transitioned to non-secure state
+
+ -- Production mode (SFP->OSPR, ITS = 1)
+
+ --- Any failure is fatal failure
+
+- Compilation steps:
+
+All Images
+ .. code:: shell
+
+ make PLAT=$PLAT TRUSTED_BOARD_BOOT=1 CST_DIR=$CST_DIR_PATH \
+ BOOT_MODE=<platform_supported_boot_mode> \
+ RCW=$RCW_BIN \
+ BL32=$TEE_BIN SPD=opteed\
+ BL33=$UBOOT_SECURE_BIN \
+ pbl \
+ fip
+
+Additional FIP_DDR Image (For NXP platforms like lx2160a)
+ .. code:: shell
+
+ make PLAT=$PLAT TRUSTED_BOARD_BOOT=1 CST_DIR=$CST_DIR_PATH fip_ddr
+
+- Compilation Steps with build option for generic image processing filters to prepend CSF header:
+ -- Generic image processing filters to prepend CSF header
+
+ BL32_INPUT_FILE = < file name>
+ BL33_INPUT_FILE = <file name>
+
+ .. code:: shell
+
+ make PLAT=$PLAT TRUSTED_BOARD_BOOT=1 CST_DIR=$CST_DIR_PATH \
+ BOOT_MODE=<platform_supported_boot_mode> \
+ RCW=$RCW_BIN \
+ BL32=$TEE_BIN SPD=opteed\
+ BL33=$UBOOT_SECURE_BIN \
+ BL33_INPUT_FILE = <ip file> \
+ BL32_INPUT_FILE = <ip_file> \
+ BL31_INPUT_FILE = <ip file> \
+ pbl \
+ fip
+
+
+Deploy ATF Images
+=================
+Same steps as mentioned in the readme "nxp-layerscape.rst".
+
+
+
+Verification to check if Secure state is achieved:
+==================================================
+
++---+----------------+-----------------+------------------------+----------------------------------+-------------------------------+
+| | Platform | SNVS_HPSR_REG | SYS_SECURE_BIT(=value) | SYSTEM_SECURE_CONFIG_BIT(=value) | SSM_STATE |
++===+================+=================+========================+==================================+===============================+
+| 1.| lx2160ardb or | 0x01E90014 | 15 | 14-12 | 11-8 |
+| | lx2160aqds or | | ( = 1, BootROM Booted) | ( = 010 means Intent to Secure, | (=1111 means secure boot) |
+| | lx2162aqds | | | ( = 000 Unsecure) | (=1011 means Non-secure Boot) |
++---+----------------+-----------------+------------------------+----------------------------------+-------------------------------+
+
+- Production mode (SFP->OSPR, ITS = 1)
+ -- Linux prompt will successfully come. if the TBBR is successful.
+
+ --- Else, Linux boot will be successful.
+
+ -- For secure-boot status, read SNVS Register $SNVS_HPSR_REG from u-boot prompt:
+
+ .. code:: shell
+
+ md $SNVS_HPSR_REG
+
+ Command Output:
+ 1e90014: 8000AF00
+
+ In case it is read as 00000000, then read this register using jtag (in development mode only through CW tap).
+ +0 +4 +8 +C
+ [0x01E90014] 8000AF00
+
+
+- Development Mode (sb_en in RCW = 1, SFP->OSPR, ITS = 0)
+ -- Refer the SoC specific table to read the register to interpret whether the secure boot is achieved or not.
+ -- Using JTAG (in development environment only, using CW tap):
+
+ --- For secure-boot status, read SNVS Register $SNVS_HPSR_REG
+
+ .. code:: shell
+
+ ccs::display_regs 86 0x01E90014 4 0 1
+
+ Command Output:
+ Using the SAP chain position number 86, following is the output.
+
+ +0 +4 +8 +C
+ [0x01E90014] 8000AF00
+
+ Note: Chain position number will vary from one SoC to other SoC.
+
+- Interpretation of the value:
+
+ -- 0xA indicates BootROM booted, with intent to secure.
+ -- 0xF = secure boot, as SSM_STATE.
diff --git a/docs/plat/poplar.rst b/docs/plat/poplar.rst
new file mode 100644
index 0000000..215f551
--- /dev/null
+++ b/docs/plat/poplar.rst
@@ -0,0 +1,176 @@
+Poplar
+======
+
+Poplar is the first development board compliant with the 96Boards Enterprise
+Edition TV Platform specification.
+
+The board features the Hi3798C V200 with an integrated quad-core 64-bit
+Arm Cortex A53 processor and high performance Mali T720 GPU, making it capable
+of running any commercial set-top solution based on Linux or Android.
+
+It supports a premium user experience with up to H.265 HEVC decoding of 4K
+video at 60 frames per second.
+
+::
+
+ SOC Hisilicon Hi3798CV200
+ CPU Quad-core Arm Cortex-A53 64 bit
+ DRAM DDR3/3L/4 SDRAM interface, maximum 32-bit data width 2 GB
+ USB Two USB 2.0 ports One USB 3.0 ports
+ CONSOLE USB-micro port for console support
+ ETHERNET 1 GBe Ethernet
+ PCIE One PCIe 2.0 interfaces
+ JTAG 8-Pin JTAG
+ EXPANSION INTERFACE Linaro 96Boards Low Speed Expansion slot
+ DIMENSION Standard 160×120 mm 96Boards Enterprice Edition form factor
+ WIFI 802.11AC 2*2 with Bluetooth
+ CONNECTORS One connector for Smart Card One connector for TSI
+
+At the start of the boot sequence, the bootROM executes the so called l-loader
+binary whose main role is to change the processor state to 64bit mode. This
+must happen prior to invoking Trusted Firmware-A:
+
+::
+
+ l-loader --> Trusted Firmware-A --> u-boot
+
+How to build
+------------
+
+Code Locations
+~~~~~~~~~~~~~~
+
+- Trusted Firmware-A:
+ `link <https://github.com/ARM-software/arm-trusted-firmware>`__
+
+- l-loader:
+ `link <https://github.com/Linaro/poplar-l-loader.git>`__
+
+- u-boot:
+ `link <http://git.denx.de/u-boot.git>`__
+
+Build Procedure
+~~~~~~~~~~~~~~~
+
+- Fetch all the above 3 repositories into local host.
+ Make all the repositories in the same ${BUILD\_PATH}.
+
+- Prepare the AARCH64 toolchain.
+
+- Build u-boot using poplar_defconfig
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-linux-gnu- poplar_defconfig
+ make CROSS_COMPILE=aarch64-linux-gnu-
+
+- Build atf providing the previously generated u-boot.bin as the BL33 image
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-linux-gnu- all fip SPD=none PLAT=poplar
+ BL33=u-boot.bin
+
+- Build l-loader (generated the final fastboot.bin)
+ 1. copy the atf generated files fip.bin and bl1.bin to l-loader/atf/
+ 2. export ARM_TRUSTED_FIRMWARE=${ATF_SOURCE_PATH)
+ 3. make
+
+Install Procedure
+-----------------
+
+- Copy l-loader/fastboot.bin to a FAT partition on a USB pen drive.
+
+- Plug the USB pen drive to any of the USB2 ports
+
+- Power the board while keeping S3 pressed (usb_boot)
+
+The system will boot into a u-boot shell which you can then use to write the
+working firmware to eMMC.
+
+Boot trace
+----------
+
+::
+
+ Bootrom start
+ Boot Media: eMMC
+ Decrypt auxiliary code ...OK
+
+ lsadc voltage min: 000000FE, max: 000000FF, aver: 000000FE, index: 00000000
+
+ Entry boot auxiliary code
+
+ Auxiliary code - v1.00
+ DDR code - V1.1.2 20160205
+ Build: Mar 24 2016 - 17:09:44
+ Reg Version: v134
+ Reg Time: 2016/03/18 09:44:55
+ Reg Name: hi3798cv2dmb_hi3798cv200_ddr3_2gbyte_8bitx4_4layers.reg
+
+ Boot auxiliary code success
+ Bootrom success
+
+ LOADER: Switched to aarch64 mode
+ LOADER: Entering ARM TRUSTED FIRMWARE
+ LOADER: CPU0 executes at 0x000ce000
+
+ INFO: BL1: 0xe1000 - 0xe7000 [size = 24576]
+ NOTICE: Booting Trusted Firmware
+ NOTICE: BL1: v1.3(debug):v1.3-372-g1ba9c60
+ NOTICE: BL1: Built : 17:51:33, Apr 30 2017
+ INFO: BL1: RAM 0xe1000 - 0xe7000
+ INFO: BL1: Loading BL2
+ INFO: Loading image id=1 at address 0xe9000
+ INFO: Image id=1 loaded at address 0xe9000, size = 0x5008
+ NOTICE: BL1: Booting BL2
+ INFO: Entry point address = 0xe9000
+ INFO: SPSR = 0x3c5
+ NOTICE: BL2: v1.3(debug):v1.3-372-g1ba9c60
+ NOTICE: BL2: Built : 17:51:33, Apr 30 2017
+ INFO: BL2: Loading BL31
+ INFO: Loading image id=3 at address 0x129000
+ INFO: Image id=3 loaded at address 0x129000, size = 0x8038
+ INFO: BL2: Loading BL33
+ INFO: Loading image id=5 at address 0x37000000
+ INFO: Image id=5 loaded at address 0x37000000, size = 0x58f17
+ NOTICE: BL1: Booting BL31
+ INFO: Entry point address = 0x129000
+ INFO: SPSR = 0x3cd
+ INFO: Boot bl33 from 0x37000000 for 364311 Bytes
+ NOTICE: BL31: v1.3(debug):v1.3-372-g1ba9c60
+ NOTICE: BL31: Built : 17:51:33, Apr 30 2017
+ INFO: BL31: Initializing runtime services
+ INFO: BL31: Preparing for EL3 exit to normal world
+ INFO: Entry point address = 0x37000000
+ INFO: SPSR = 0x3c9
+
+
+ U-Boot 2017.05-rc2-00130-gd2255b0 (Apr 30 2017 - 17:51:28 +0200)poplar
+
+ Model: HiSilicon Poplar Development Board
+ BOARD: Hisilicon HI3798cv200 Poplar
+ DRAM: 1 GiB
+ MMC: Hisilicon DWMMC: 0
+ In: serial@f8b00000
+ Out: serial@f8b00000
+ Err: serial@f8b00000
+ Net: Net Initialization Skipped
+ No ethernet found.
+
+ Hit any key to stop autoboot: 0
+ starting USB...
+ USB0: USB EHCI 1.00
+ scanning bus 0 for devices... 1 USB Device(s) found
+ USB1: USB EHCI 1.00
+ scanning bus 1 for devices... 4 USB Device(s) found
+ scanning usb for storage devices... 1 Storage Device(s) found
+ scanning usb for ethernet devices... 1 Ethernet Device(s) found
+
+ USB device 0:
+ Device 0: Vendor: SanDisk Rev: 1.00 Prod: Cruzer Blade
+ Type: Removable Hard Disk
+ Capacity: 7632.0 MB = 7.4 GB (15630336 x 512)
+ ... is now current device
+ Scanning usb 0:1...
+ =>
diff --git a/docs/plat/qemu-sbsa.rst b/docs/plat/qemu-sbsa.rst
new file mode 100644
index 0000000..bc82ae5
--- /dev/null
+++ b/docs/plat/qemu-sbsa.rst
@@ -0,0 +1,56 @@
+QEMU SBSA Target
+================
+
+Trusted Firmware-A (TF-A) implements the EL3 firmware layer for QEMU SBSA
+Armv8-A. While running Qemu from command line, we need to supply two Flash
+images. First Secure BootRom is supplied by -pflash argument. This Flash image
+is made by EDK2 build system by composing BL1 and FIP. Second parameter for Qemu
+is responsible for Non-secure rom which also given with -pflash argument and
+contains of UEFI and EFI variables (also made by EDK2 build system). Semihosting
+is not used
+
+When QEMU starts all CPUs are released simultaneously, BL1 selects a
+primary CPU to handle the boot and the secondaries are placed in a polling
+loop to be released by normal world via PSCI.
+
+BL2 edits the FDT, generated by QEMU at run-time to add a node describing PSCI
+and also enable methods for the CPUs.
+
+Current limitations:
+
+- Only cold boot is supported
+
+To build TF-A:
+
+::
+
+ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git tfa
+ cd tfa
+ export CROSS_COMPILE=aarch64-none-elf-
+ make PLAT=qemu_sbsa all fip
+
+To build TF-A with BL32 and SPM enabled(StandaloneMM as a Secure Payload):
+
+::
+
+ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git tfa
+ cd tfa
+ export CROSS_COMPILE=aarch64-none-elf-
+ make PLAT=qemu_sbsa BL32=../STANDALONE_MM.fd SPM_MM=1 EL3_EXCEPTION_HANDLING=1 all fip
+
+Images will be placed at build/qemu_sbsa/release (bl1.bin and fip.bin).
+Need to copy them into top directory for EDK2 compilation.
+
+::
+
+ cp build/qemu_sbsa/release/bl1.bin ../
+ cp build/qemu_sbsa/release/fip.bin ../
+
+Those images cannot be used by itself (no semihosing support). Flash images are built by
+EDK2 build system, refer to edk2-platform repo for full build instructions.
+
+::
+
+ git clone https://github.com/tianocore/edk2-platforms.git
+ Platform/Qemu/SbsaQemu/Readme.md
+
diff --git a/docs/plat/qemu.rst b/docs/plat/qemu.rst
new file mode 100644
index 0000000..6986326
--- /dev/null
+++ b/docs/plat/qemu.rst
@@ -0,0 +1,172 @@
+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.
+When QEMU starts all CPUs are released simultaneously, BL1 selects a
+primary CPU to handle the boot and the secondaries are placed in a polling
+loop to be released by normal world via PSCI.
+
+BL2 edits the Flattened Device Tree, FDT, generated by QEMU at run-time to
+add a node describing PSCI and also enable methods for the CPUs.
+
+If ``ARM_LINUX_KERNEL_AS_BL33`` is set to 1 then this FDT will be passed to BL33
+via register x0, as expected by a Linux kernel. This allows a Linux kernel image
+to be booted directly as BL33 rather than using a bootloader.
+
+An ARM64 defconfig v5.5 Linux kernel is known to boot, FDT doesn't need to be
+provided as it's generated by QEMU.
+
+Current limitations:
+
+- Only cold boot is supported
+
+Getting non-TF images
+---------------------
+
+``QEMU_EFI.fd`` can be downloaded from
+http://snapshots.linaro.org/components/kernel/leg-virt-tianocore-edk2-upstream/latest/QEMU-KERNEL-AARCH64/RELEASE_GCC5/QEMU_EFI.fd
+
+or, can be built as follows:
+
+.. code:: shell
+
+ git clone https://github.com/tianocore/edk2.git
+ cd edk2
+ git submodule update --init
+ make -C BaseTools
+ source edksetup.sh
+ export GCC5_AARCH64_PREFIX=aarch64-linux-gnu-
+ build -a AARCH64 -t GCC5 -p ArmVirtPkg/ArmVirtQemuKernel.dsc
+
+````
+
+Then, you will get ``Build/ArmVirtQemuKernel-AARCH64/DEBUG_GCC5/FV/QEMU_EFI.fd``
+
+Please note you do not need to use GCC 5 in spite of the environment variable
+``GCC5_AARCH64_PREFIX``
+
+The rootfs can be built by using Buildroot as follows:
+
+.. code:: shell
+
+ git clone git://git.buildroot.net/buildroot.git
+ cd buildroot
+ make qemu_aarch64_virt_defconfig
+ utils/config -e BR2_TARGET_ROOTFS_CPIO
+ utils/config -e BR2_TARGET_ROOTFS_CPIO_GZIP
+ make olddefconfig
+ make
+
+Then, you will get ``output/images/rootfs.cpio.gz``.
+
+Booting via semi-hosting option
+-------------------------------
+
+Boot binaries, except BL1, are primarily loaded via semi-hosting so all
+binaries has to reside in the same directory as QEMU is started from. This
+is conveniently achieved with symlinks the local names as:
+
+- ``bl2.bin`` -> BL2
+- ``bl31.bin`` -> BL31
+- ``bl33.bin`` -> BL33 (``QEMU_EFI.fd``)
+- ``Image`` -> linux/arch/arm64/boot/Image
+
+To build:
+
+.. code:: shell
+
+ make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu
+
+To start (QEMU v5.0.0):
+
+.. code:: shell
+
+ qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \
+ -kernel Image \
+ -append "console=ttyAMA0,38400 keep_bootcon" \
+ -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios bl1.bin \
+ -d unimp -semihosting-config enable,target=native
+
+Booting via flash based firmwares
+---------------------------------
+
+Boot firmwares are loaded via secure FLASH0 device so ``bl1.bin`` and
+``fip.bin`` should be concatenated to create a ``flash.bin`` that is flashed
+onto secure FLASH0.
+
+- ``bl32.bin`` -> BL32 (``tee-header_v2.bin``)
+- ``bl32_extra1.bin`` -> BL32 Extra1 (``tee-pager_v2.bin``)
+- ``bl32_extra2.bin`` -> BL32 Extra2 (``tee-pageable_v2.bin``)
+- ``bl33.bin`` -> BL33 (``QEMU_EFI.fd``)
+- ``Image`` -> linux/arch/arm64/boot/Image
+
+To build:
+
+.. code:: shell
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=qemu BL32=bl32.bin \
+ BL32_EXTRA1=bl32_extra1.bin BL32_EXTRA2=bl32_extra2.bin \
+ BL33=bl33.bin BL32_RAM_LOCATION=tdram SPD=opteed all fip
+
+To build with TBBR enabled, BL31 and BL32 encrypted with test key:
+
+.. code:: shell
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=qemu BL32=bl32.bin \
+ BL32_EXTRA1=bl32_extra1.bin BL32_EXTRA2=bl32_extra2.bin \
+ BL33=bl33.bin BL32_RAM_LOCATION=tdram SPD=opteed all fip \
+ MBEDTLS_DIR=<path-to-mbedtls-repo> TRUSTED_BOARD_BOOT=1 \
+ GENERATE_COT=1 DECRYPTION_SUPPORT=aes_gcm FW_ENC_STATUS=0 \
+ ENCRYPT_BL31=1 ENCRYPT_BL32=1
+
+To build flash.bin:
+
+.. code:: shell
+
+ dd if=build/qemu/release/bl1.bin of=flash.bin bs=4096 conv=notrunc
+ dd if=build/qemu/release/fip.bin of=flash.bin seek=64 bs=4096 conv=notrunc
+
+To start (QEMU v5.0.0):
+
+.. code:: shell
+
+ qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \
+ -kernel Image -no-acpi \
+ -append 'console=ttyAMA0,38400 keep_bootcon' \
+ -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios flash.bin \
+ -d unimp
+
+Running QEMU in OpenCI
+-----------------------
+
+Linaro's continuous integration platform OpenCI supports running emulated tests
+on QEMU. The tests are kicked off on Jenkins and deployed through the Linaro
+Automation and Validation Architecture `LAVA`_.
+
+There are a set of Linux boot tests provided in OpenCI. They rely on prebuilt
+`binaries`_ for UEFI, the kernel, root file system, as well as, any other TF-A
+dependencies, and are run as part of the OpenCI TF-A `daily job`_. To run them
+manually, a `builder`_ job may be triggered with the test configuration
+``qemu-boot-tests``.
+
+
+You may see the following warning repeated several times in the boot logs:
+
+.. code:: shell
+
+ pflash_write: Write to buffer emulation is flawed
+
+Please ignore this as it is an unresolved `issue in QEMU`_, it is an internal
+QEMU warning that logs flawed use of "write to buffer".
+
+.. note::
+ For more information on how to trigger jobs in OpenCI, please refer to
+ Linaro's CI documentation, which explains how to trigger a `manual job`_.
+
+.. _binaries: https://downloads.trustedfirmware.org/tf-a/linux_boot/
+.. _daily job: https://ci.trustedfirmware.org/view/TF-A/job/tf-a-main/
+.. _builder: https://ci.trustedfirmware.org/view/TF-A/job/tf-a-builder/
+.. _LAVA: https://tf.validation.linaro.org/
+.. _manual job: https://tf-ci-users-guide.readthedocs.io/en/latest/#manual-job-trigger
+.. _issue in QEMU: https://git.qemu.org/?p=qemu.git;a=blob;f=hw/block/pflash_cfi01.c;h=0cbc2fb4cbf62c9a033b8dd89012374ff74ed610;hb=refs/heads/master#l500
diff --git a/docs/plat/qti-msm8916.rst b/docs/plat/qti-msm8916.rst
new file mode 100644
index 0000000..09a79b7
--- /dev/null
+++ b/docs/plat/qti-msm8916.rst
@@ -0,0 +1,116 @@
+Qualcomm Snapdragon 410 (MSM8916/APQ8016)
+=========================================
+
+The `Qualcomm Snapdragon 410`_ is Qualcomm's first 64-bit SoC, released in 2014
+with four ARM Cortex-A53 cores. There are differents variants (MSM8916,
+APQ8016(E), ...) that are all very similar. A popular device based on APQ8016E
+is the `DragonBoard 410c`_ single-board computer, but the SoC is also used in
+various mid-range smartphones/tablets.
+
+The TF-A/BL31 port for MSM8916 provides a minimal, community-maintained
+EL3 firmware. It is primarily based on information from the public
+`Snapdragon 410E Technical Reference Manual`_ combined with a lot of
+trial and error to actually make it work.
+
+.. note::
+ Unlike the :doc:`QTI SC7180/SC7280 <qti>` ports, this port does **not**
+ make use of a proprietary binary components (QTISECLIB). It is fully
+ open-source but therefore limited to publicly documented hardware
+ components.
+
+Functionality
+-------------
+
+The BL31 port is much more minimal compared to the original firmware and
+therefore expects the non-secure world (e.g. Linux) to manage more hardware,
+such as the SMMUs and all remote processors (RPM, WCNSS, Venus, Modem).
+Everything except modem is currently functional with a slightly modified version
+of mainline Linux.
+
+.. warning::
+ This port is **not secure**. There is no special secure memory and the
+ used DRAM is available from both the non-secure and secure worlds.
+ Unfortunately, the hardware used for memory protection is not described
+ in the APQ8016E documentation.
+
+The port is primarily intended as a minimal PSCI implementation (without a
+separate secure world) where this limitation is not a big problem. Booting
+secondary CPU cores (PSCI ``CPU_ON``) is supported. Basic CPU core power
+management (``CPU_SUSPEND``) is functional but still work-in-progress and
+will be added later once ready.
+
+Boot Flow
+---------
+BL31 replaces the original ``tz`` firmware in the boot flow::
+
+ Boot ROM (PBL) -> SBL -> BL31 (EL3) -> U-Boot (EL2) -> Linux (EL2)
+
+By default, BL31 enters the non-secure world in EL2 AArch64 state at address
+``0x8f600000``. The original hypervisor firmware (``hyp``) is not used, you can
+use KVM or another hypervisor. The entry address is fixed in the BL31 binary
+but can be changed using the ``PRELOADED_BL33_BASE`` make file parameter.
+
+Using an AArch64 bootloader (such as `U-Boot for DragonBoard 410c`_) is
+recommended. AArch32 bootloaders (such as the original Little Kernel bootloader
+from Qualcomm) are not directly supported, although it is possible to use an EL2
+shim loader to temporarily switch to AArch32 state.
+
+Installation
+------------
+First, setup the cross compiler for AArch64 and build TF-A for ``msm8916``::
+
+ $ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=msm8916
+
+The BL31 ELF image is generated in ``build/msm8916/release/bl31/bl31.elf``.
+This image must be "signed" before flashing it, even if the board has secure
+boot disabled. In this case the signature does not provide any security,
+but it provides the firmware with required metadata.
+
+The `DragonBoard 410c`_ does not have secure boot enabled by default. In this
+case you can simply sign the ELF image using a randomly generated key. You can
+use e.g. `qtestsign`_::
+
+ $ ./qtestsign.py tz build/msm8916/release/bl31/bl31.elf
+
+Then install the resulting ``build/msm8916/release/bl31/bl31-test-signed.mbn``
+to the ``tz`` partition on the device. BL31 should be running after a reboot.
+
+.. warning::
+ Do not flash incorrectly signed firmware on devices that have secure
+ boot enabled! Make sure that you have a way to recover the board in case
+ of problems (e.g. using EDL).
+
+Boot Trace
+----------
+BL31 prints some lines on the debug console UART2, which will usually look like
+this (with ``DEBUG=1``, otherwise only the ``NOTICE`` lines are shown)::
+
+ ...
+ S - DDR Frequency, 400 MHz
+ NOTICE: BL31: v2.6(debug):v2.6
+ NOTICE: BL31: Built : 20:00:00, Dec 01 2021
+ INFO: BL31: Platform setup start
+ INFO: ARM GICv2 driver initialized
+ INFO: BL31: Platform setup done
+ INFO: BL31: Initializing runtime services
+ INFO: BL31: cortex_a53: CPU workaround for 819472 was applied
+ INFO: BL31: cortex_a53: CPU workaround for 824069 was applied
+ INFO: BL31: cortex_a53: CPU workaround for 826319 was applied
+ INFO: BL31: cortex_a53: CPU workaround for 827319 was applied
+ INFO: BL31: cortex_a53: CPU workaround for 835769 was applied
+ INFO: BL31: cortex_a53: CPU workaround for disable_non_temporal_hint was applied
+ INFO: BL31: cortex_a53: CPU workaround for 843419 was applied
+ INFO: BL31: cortex_a53: CPU workaround for 1530924 was applied
+ INFO: BL31: Preparing for EL3 exit to normal world
+ INFO: Entry point address = 0x8f600000
+ INFO: SPSR = 0x3c9
+
+ U-Boot 2021.10 (Dec 01 2021 - 20:00:00 +0000)
+ Qualcomm-DragonBoard 410C
+ ...
+
+.. _Qualcomm Snapdragon 410: https://www.qualcomm.com/products/snapdragon-processors-410
+.. _DragonBoard 410c: https://www.96boards.org/product/dragonboard410c/
+.. _Snapdragon 410E Technical Reference Manual: https://developer.qualcomm.com/download/sd410/snapdragon-410e-technical-reference-manual.pdf
+.. _U-Boot for DragonBoard 410c: https://u-boot.readthedocs.io/en/latest/board/qualcomm/dragonboard410c.html
+.. _qtestsign: https://github.com/msm8916-mainline/qtestsign
diff --git a/docs/plat/qti.rst b/docs/plat/qti.rst
new file mode 100644
index 0000000..1d483e7
--- /dev/null
+++ b/docs/plat/qti.rst
@@ -0,0 +1,43 @@
+Qualcomm Technologies, Inc.
+===========================
+
+Trusted Firmware-A (TF-A) implements the EL3 firmware layer for QTI SC7180,
+SC7280.
+
+Boot Trace
+-------------
+
+Bootrom --> BL1/BL2 --> BL31 --> BL33 --> Linux kernel
+
+BL1/2 and BL33 can currently be supplied from Coreboot + Depthcharge
+
+How to build
+------------
+
+Code Locations
+~~~~~~~~~~~~~~
+
+- Trusted Firmware-A:
+ `link <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git>`__
+
+Build Procedure
+~~~~~~~~~~~~~~~
+
+QTI SoC expects TF-A's BL31 to get integrated with other boot software
+Coreboot, so only bl31.elf need to get build from the TF-A repository.
+
+The build command looks like
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sc7180 COREBOOT=1
+
+update value of CROSS_COMPILE argument with your cross-compilation toolchain.
+
+Additional QTISECLIB_PATH=<path to qtiseclib> can be added in build command.
+if QTISECLIB_PATH is not added in build command stub implementation of qtiseclib
+is picked. qtiseclib with stub implementation doesn't boot device. This was
+added to satisfy compilation.
+
+QTISELIB for SC7180 is available at
+`link <https://github.com/coreboot/qc_blobs/blob/master/sc7180/qtiseclib/libqtisec.a?raw=true>`__
+QTISELIB for SC7280 is available at
+`link <https://github.com/coreboot/qc_blobs/blob/master/sc7280/qtiseclib/libqtisec.a?raw=true>`__
diff --git a/docs/plat/rcar-gen3.rst b/docs/plat/rcar-gen3.rst
new file mode 100644
index 0000000..7107bea
--- /dev/null
+++ b/docs/plat/rcar-gen3.rst
@@ -0,0 +1,268 @@
+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
+computing for the age of autonomous vehicles.
+
+The scalable R-Car hardware platform and flexible software platform
+cover the full product range, from the premium class to the entry
+level. Plug-ins are available for multiple open-source software tools.
+
+
+Renesas R-Car Gen3 evaluation boards:
+-------------------------------------
+
++------------+-----------------+-----------------------------+
+| | Standard | Low Cost Boards (LCB) |
++============+=================+=============================+
+| R-Car H3 | - Salvator-X | - R-Car Starter Kit Premier |
+| | - Salvator-XS | |
++------------+-----------------+-----------------------------+
+| R-Car M3-W | - Salvator-X | |
+| | - Salvator-XS | - R-Car Starter Kit Pro |
++------------+-----------------+-----------------------------+
+| R-Car M3-N | - Salvator-X | |
+| | - Salvator-XS | |
++------------+-----------------+-----------------------------+
+| R-Car V3M | - Eagle | - Starter Kit |
++------------+-----------------+-----------------------------+
+| R-Car V3H | - Condor | - Starter Kit |
++------------+-----------------+-----------------------------+
+| R-Car D3 | - Draak | |
++------------+-----------------+-----------------------------+
+
+`boards info <https://elinux.org/R-Car>`__
+
+The current TF-A port has been tested on the R-Car H3 Salvator-X
+Soc_id r8a7795 revision ES1.1 (uses a Secure Payload Dispatcher)
+
+
+::
+
+ ARM CA57 (ARMv8) 1.5 GHz quad core, with NEON/VFPv4, L1$ I/D
+ 48K/32K, L2$ 2MB
+ ARM CA53 (ARMv8) 1.2 GHz quad core, with NEON/VFPv4, L1$ I/D 32K/32K,
+ L2$ 512K
+ Memory controller for LPDDR4-3200 4GB in 2 channels, each 64-bit wide
+ Two- and three-dimensional graphics engines,
+ Video processing units,
+ 3 channels Display Output,
+ 6 channels Video Input,
+ SD card host interface,
+ USB3.0 and USB2.0 interfaces,
+ CAN interfaces
+ Ethernet AVB
+ PCI Express Interfaces
+ Memories
+ INTERNAL 384KB SYSTEM RAM
+ DDR 4 GB LPDDR4
+ HYPERFLASH 64 MB HYPER FLASH (512 MBITS, 160 MHZ, 320 MBYTES/S)
+ QSPI FLASH 16MB QSPI (128 MBITS,80 MHZ,80 MBYTES/S)1 HEADER QSPI
+ MODULE
+ EMMC 32 GB EMMC (HS400 240 MBYTES/S)
+ MICROSD-CARD SLOT (SDR104 100 MBYTES/S)
+
+
+Overview
+--------
+On the rcar-gen3 the BOOTROM starts the cpu at EL3; for this port BL2
+will therefore be entered at this exception level (the Renesas' ATF
+reference tree [1] resets into EL1 before entering BL2 - see its
+bl2.ld.S)
+
+BL2 initializes DDR (and on some platforms i2c to interface to the
+PMIC) before determining the boot reason (cold or warm).
+
+During suspend all CPUs are switched off and the DDR is put in backup
+mode (some kind of self-refresh mode). This means that BL2 is always
+entered in a cold boot scenario.
+
+Once BL2 boots, it determines the boot reason, writes it to shared
+memory (BOOT_KIND_BASE) together with the BL31 parameters
+(PARAMS_BASE) and jumps to BL31.
+
+To all effects, BL31 is as if it is being entered in reset mode since
+it still needs to initialize the rest of the cores; this is the reason
+behind using direct shared memory access to BOOT_KIND_BASE _and_
+PARAMS_BASE instead of using registers to get to those locations (see
+el3_common_macros.S and bl31_entrypoint.S for the RESET_TO_BL31 use
+case).
+
+Depending on the boot reason BL31 initializes the rest of the cores:
+in case of suspend, it uses a MBOX memory region to recover the
+program counters.
+
+[1] https://github.com/renesas-rcar/arm-trusted-firmware
+
+
+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
+
+$ 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]
+
+ commit 552754a6ee82bab25d1bdf28c8261a4518e65e4d
+ Merge: 68dbc94 f34a4c1
+ Author: Simon Butcher <simon.butcher@arm.com>
+ Date: Thu Aug 30 00:57:28 2018 +0100
+
+* optee_os:
+ https://github.com/BayLibre/optee_os
+
+ Until it gets merged into OP-TEE, the port requires Renesas'
+ Trusted Environment with a modification to support power
+ management.
+ commit 80105192cba9e704ebe8df7ab84095edc2922f84
+
+ Author: Jorge Ramirez-Ortiz <jramirez@baylibre.com>
+ Date: Thu Aug 30 16:49:49 2018 +0200
+ plat-rcar: cpu-suspend: handle the power level
+ Signed-off-by: Jorge Ramirez-Ortiz <jramirez@baylibre.com>
+
+* u-boot:
+ The port has beent tested using mainline uboot.
+
+ commit 4cdeda511f8037015b568396e6dcc3d8fb41e8c0
+ Author: Fabio Estevam <festevam@gmail.com>
+ Date: Tue Sep 4 10:23:12 2018 -0300
+
+* linux:
+ The port has beent tested using mainline kernel.
+
+ commit 7876320f88802b22d4e2daf7eb027dd14175a0f8
+ Author: Linus Torvalds <torvalds@linux-foundation.org>
+ Date: Sun Sep 16 11:52:37 2018 -0700
+ Linux 4.19-rc4
+
+TF-A Build Procedure
+~~~~~~~~~~~~~~~~~~~~
+
+- Fetch all the above 4 repositories.
+
+- Prepare the AARCH64 toolchain.
+
+- Build u-boot using r8a7795_salvator-x_defconfig.
+ Result: u-boot-elf.srec
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-linux-gnu-
+ r8a7795_salvator-x_defconfig
+
+ make CROSS_COMPILE=aarch64-linux-gnu-
+
+- Build atf
+ Result: bootparam_sa0.srec, cert_header_sa6.srec, bl2.srec, bl31.srec
+
+.. code:: bash
+
+ RCAR_OPT="LSI=H3 RCAR_DRAM_SPLIT=1 RCAR_LOSSY_ENABLE=1"
+
+ MBEDTLS_DIR=$mbedtls_src_tree make clean bl2 bl31 rcar \
+ PLAT=rcar ${RCAR_OPT} SPD=opteed
+
+- Build optee-os
+ Result: tee.srec
+
+.. code:: bash
+
+ make -j8 PLATFORM="rcar" CFG_ARM64_core=y
+
+Install Procedure
+~~~~~~~~~~~~~~~~~
+
+- Boot the board in Mini-monitor mode and enable access to the
+ Hyperflash.
+
+
+- Use the XSL2 Mini-monitor utility to accept all the SREC ascii
+ transfers over serial.
+
+
+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
+LOG_LEVEL=50 and DEBUG=1
+
+::
+
+ Initial Program Loader(CA57) Rev.1.0.22
+ NOTICE: BL2: PRR is R-Car H3 Ver.1.1
+ NOTICE: BL2: Board is Salvator-X Rev.1.0
+ NOTICE: BL2: Boot device is HyperFlash(80MHz)
+ NOTICE: BL2: LCM state is CM
+ NOTICE: AVS setting succeeded. DVFS_SetVID=0x53
+ NOTICE: BL2: DDR1600(rev.0.33)NOTICE: [COLD_BOOT]NOTICE: ..0
+ NOTICE: BL2: DRAM Split is 4ch
+ NOTICE: BL2: QoS is default setting(rev.0.37)
+ NOTICE: BL2: Lossy Decomp areas
+ NOTICE: Entry 0: DCMPAREACRAx:0x80000540 DCMPAREACRBx:0x570
+ NOTICE: Entry 1: DCMPAREACRAx:0x40000000 DCMPAREACRBx:0x0
+ NOTICE: Entry 2: DCMPAREACRAx:0x20000000 DCMPAREACRBx:0x0
+ NOTICE: BL2: v2.0(release):v2.0-rc0-32-gbcda69a
+ NOTICE: BL2: Built : 16:41:23, Oct 2 2018
+ NOTICE: BL2: Normal boot
+ INFO: BL2: Doing platform setup
+ INFO: BL2: Loading image id 3
+ NOTICE: BL2: dst=0xe6322000 src=0x8180000 len=512(0x200)
+ NOTICE: BL2: dst=0x43f00000 src=0x8180400 len=6144(0x1800)
+ WARNING: r-car ignoring the BL31 size from certificate,using
+ RCAR_TRUSTED_SRAM_SIZE instead
+ INFO: Loading image id=3 at address 0x44000000
+ NOTICE: rcar_file_len: len: 0x0003e000
+ NOTICE: BL2: dst=0x44000000 src=0x81c0000 len=253952(0x3e000)
+ INFO: Image id=3 loaded: 0x44000000 - 0x4403e000
+ INFO: BL2: Loading image id 4
+ INFO: Loading image id=4 at address 0x44100000
+ NOTICE: rcar_file_len: len: 0x00100000
+ NOTICE: BL2: dst=0x44100000 src=0x8200000 len=1048576(0x100000)
+ INFO: Image id=4 loaded: 0x44100000 - 0x44200000
+ INFO: BL2: Loading image id 5
+ INFO: Loading image id=5 at address 0x50000000
+ NOTICE: rcar_file_len: len: 0x00100000
+ NOTICE: BL2: dst=0x50000000 src=0x8640000 len=1048576(0x100000)
+ INFO: Image id=5 loaded: 0x50000000 - 0x50100000
+ NOTICE: BL2: Booting BL31
+ INFO: Entry point address = 0x44000000
+ INFO: SPSR = 0x3cd
+ VERBOSE: Argument #0 = 0xe6325578
+ VERBOSE: Argument #1 = 0x0
+ VERBOSE: Argument #2 = 0x0
+ VERBOSE: Argument #3 = 0x0
+ VERBOSE: Argument #4 = 0x0
+ VERBOSE: Argument #5 = 0x0
+ VERBOSE: Argument #6 = 0x0
+ VERBOSE: Argument #7 = 0x0
+
+
+ U-Boot 2018.09-rc3-00028-g3711616 (Sep 27 2018 - 18:50:24 +0200)
+
+ CPU: Renesas Electronics R8A7795 rev 1.1
+ Model: Renesas Salvator-X board based on r8a7795 ES2.0+
+ DRAM: 3.5 GiB
+ Flash: 64 MiB
+ MMC: sd@ee100000: 0, sd@ee140000: 1, sd@ee160000: 2
+ Loading Environment from MMC... OK
+ In: serial@e6e88000
+ Out: serial@e6e88000
+ Err: serial@e6e88000
+ Net: eth0: ethernet@e6800000
+ Hit any key to stop autoboot: 0
+ =>
diff --git a/docs/plat/rockchip.rst b/docs/plat/rockchip.rst
new file mode 100644
index 0000000..b7c43fb
--- /dev/null
+++ b/docs/plat/rockchip.rst
@@ -0,0 +1,55 @@
+Rockchip SoCs
+=============
+
+Trusted Firmware-A supports a number of Rockchip ARM SoCs from both
+AARCH32 and AARCH64 fields.
+
+This includes right now:
+- px30: Quad-Core Cortex-A53
+- rk3288: Quad-Core Cortex-A17 (past A12)
+- rk3328: Quad-Core Cortex-A53
+- rk3368: Octa-Core Cortex-A53
+- rk3399: Hexa-Core Cortex-A53/A72
+
+
+Boot Sequence
+-------------
+
+For AARCH32:
+ Bootrom --> BL1/BL2 --> BL32 --> BL33 --> Linux kernel
+
+For AARCH64:
+ Bootrom --> BL1/BL2 --> BL31 --> BL33 --> Linux kernel
+
+BL1/2 and BL33 can currently be supplied from either:
+- Coreboot + Depthcharge
+- U-Boot - either separately as TPL+SPL or only SPL
+
+
+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
+these images need to get build from the TF-A repository.
+
+For AARCH64 architectures the build command looks like
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=rk3399 bl32
+
+while AARCH32 needs a slightly different command
+
+ make ARCH=aarch32 CROSS_COMPILE=arm-linux-gnueabihf- PLAT=rk3288 AARCH32_SP=sp_min bl32
+
+Both need replacing the PLAT argument with the platform from above you
+want to build for and the CROSS_COMPILE argument with you cross-
+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.
+So after successfully building TF-A just follow their build instructions
+to continue.
diff --git a/docs/plat/rpi3.rst b/docs/plat/rpi3.rst
new file mode 100644
index 0000000..38c3dfa
--- /dev/null
+++ b/docs/plat/rpi3.rst
@@ -0,0 +1,466 @@
+Raspberry Pi 3
+==============
+
+The `Raspberry Pi 3`_ is an inexpensive single-board computer that contains four
+Arm Cortex-A53 cores.
+
+The following instructions explain how to use this port of the TF-A with the
+default distribution of `Raspbian`_ because that's the distribution officially
+supported by the Raspberry Pi Foundation. At the moment of writing this, the
+officially supported kernel is a AArch32 kernel. This doesn't mean that this
+port of TF-A can't boot a AArch64 kernel. The `Linux tree fork`_ maintained by
+the Foundation can be compiled for AArch64 by following the steps in
+`AArch64 kernel build instructions`_.
+
+**IMPORTANT NOTE**: This port isn't secure. All of the memory used is DRAM,
+which is available from both the Non-secure and Secure worlds. This port
+shouldn't be considered more than a prototype to play with and implement
+elements like PSCI to support the Linux kernel.
+
+Design
+------
+
+The SoC used by the Raspberry Pi 3 is the Broadcom BCM2837. It is a SoC with a
+VideoCore IV that acts as primary processor (and loads everything from the SD
+card) and is located between all Arm cores and the DRAM. Check the `Raspberry Pi
+3 documentation`_ for more information.
+
+This explains why it is possible to change the execution state (AArch64/AArch32)
+depending on a few files on the SD card. We only care about the cases in which
+the cores boot in AArch64 mode.
+
+The rules are simple:
+
+- If a file called ``kernel8.img`` is located on the ``boot`` partition of the
+ SD card, it will load it and execute in EL2 in AArch64. Basically, it executes
+ a `default AArch64 stub`_ at address **0x0** that jumps to the kernel.
+
+- If there is also a file called ``armstub8.bin``, it will load it at address
+ **0x0** (instead of the default stub) and execute it in EL3 in AArch64. All
+ the cores are powered on at the same time and start at address **0x0**.
+
+This means that we can use the default AArch32 kernel provided in the official
+`Raspbian`_ distribution by renaming it to ``kernel8.img``, while TF-A and
+anything else we need is in ``armstub8.bin``. This way we can forget about the
+default bootstrap code. When using a AArch64 kernel, it is only needed to make
+sure that the name on the SD card is ``kernel8.img``.
+
+Ideally, we want to load the kernel and have all cores available, which means
+that we need to make the secondary cores work in the way the kernel expects, as
+explained in `Secondary cores`_. In practice, a small bootstrap is needed
+between TF-A and the kernel.
+
+To get the most out of a AArch32 kernel, we want to boot it in Hypervisor mode
+in AArch32. This means that BL33 can't be in EL2 in AArch64 mode. The
+architecture specifies that AArch32 Hypervisor mode isn't present when AArch64
+is used for EL2. When using a AArch64 kernel, it should simply start in EL2.
+
+Placement of images
+~~~~~~~~~~~~~~~~~~~
+
+The file ``armstub8.bin`` contains BL1 and the FIP. It is needed to add padding
+between them so that the addresses they are loaded to match the ones specified
+when compiling TF-A. This is done automatically by the build system.
+
+The device tree block is loaded by the VideoCore loader from an appropriate
+file, but we can specify the address it is loaded to in ``config.txt``.
+
+The file ``kernel8.img`` contains a kernel image that is loaded to the address
+specified in ``config.txt``. The `Linux kernel tree`_ has information about how
+a AArch32 Linux kernel image is loaded in ``Documentation/arm/Booting``:
+
+::
+
+ The zImage may also be placed in system RAM and called there. The
+ kernel should be placed in the first 128MiB of RAM. It is recommended
+ that it is loaded above 32MiB in order to avoid the need to relocate
+ prior to decompression, which will make the boot process slightly
+ faster.
+
+There are no similar restrictions for AArch64 kernels, as specified in the file
+``Documentation/arm64/booting.txt``.
+
+This means that we need to avoid the first 128 MiB of RAM when placing the
+TF-A images (and specially the first 32 MiB, as they are directly used to
+place the uncompressed AArch32 kernel image. This way, both AArch32 and
+AArch64 kernels can be placed at the same address.
+
+In the end, the images look like the following diagram when placed in memory.
+All addresses are Physical Addresses from the point of view of the Arm cores.
+Again, note that this is all just part of the same DRAM that goes from
+**0x00000000** to **0x3F000000**, it just has different names to simulate a real
+secure platform!
+
+::
+
+ 0x00000000 +-----------------+
+ | ROM | BL1
+ 0x00020000 +-----------------+
+ | FIP |
+ 0x00200000 +-----------------+
+ | |
+ | ... |
+ | |
+ 0x01000000 +-----------------+
+ | DTB | (Loaded by the VideoCore)
+ +-----------------+
+ | |
+ | ... |
+ | |
+ 0x02000000 +-----------------+
+ | Kernel | (Loaded by the VideoCore)
+ +-----------------+
+ | |
+ | ... |
+ | |
+ 0x10000000 +-----------------+
+ | Secure SRAM | BL2, BL31
+ 0x10100000 +-----------------+
+ | Secure DRAM | BL32 (Secure payload)
+ 0x11000000 +-----------------+
+ | Non-secure DRAM | BL33
+ +-----------------+
+ | |
+ | ... |
+ | |
+ 0x3F000000 +-----------------+
+ | I/O |
+ 0x40000000 +-----------------+
+
+The area between **0x10000000** and **0x11000000** has to be manually protected
+so that the kernel doesn't use it. The current port tries to modify the live DTB
+to add a memreserve region that reserves the previously mentioned area.
+
+If this is not possible, the user may manually add ``memmap=16M$256M`` to the
+command line passed to the kernel in ``cmdline.txt``. See the `Setup SD card`_
+instructions to see how to do it. This system is strongly discouraged.
+
+The last 16 MiB of DRAM can only be accessed by the VideoCore, that has
+different mappings than the Arm cores in which the I/O addresses don't overlap
+the DRAM. The memory reserved to be used by the VideoCore is always placed at
+the end of the DRAM, so this space isn't wasted.
+
+Considering the 128 MiB allocated to the GPU and the 16 MiB allocated for
+TF-A, there are 880 MiB available for Linux.
+
+Boot sequence
+~~~~~~~~~~~~~
+
+The boot sequence of TF-A is the usual one except when booting an AArch32
+kernel. In that case, BL33 is booted in AArch32 Hypervisor mode so that it
+can jump to the kernel in the same mode and let it take over that privilege
+level. If BL33 was running in EL2 in AArch64 (as in the default bootflow of
+TF-A) it could only jump to the kernel in AArch32 in Supervisor mode.
+
+The `Linux kernel tree`_ has instructions on how to jump to the Linux kernel
+in ``Documentation/arm/Booting`` and ``Documentation/arm64/booting.txt``. The
+bootstrap should take care of this.
+
+This port support a direct boot of the Linux kernel from the firmware (as a BL33
+image). Alternatively, U-Boot or other bootloaders may be used.
+
+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
+the system off, it simply reboots it and asks the VideoCore firmware to keep it
+in a low power mode permanently.
+
+The kernel used by `Raspbian`_ doesn't have support for PSCI, so it is needed to
+use mailboxes to trap the secondary cores until they are ready to jump to the
+kernel. This mailbox is located at a different address in the AArch32 default
+kernel than in the AArch64 kernel.
+
+Kernels with PSCI support can use the PSCI calls instead for a cleaner boot.
+
+Also, this port of TF-A has another Trusted Mailbox in Shared BL RAM. During
+cold boot, all secondary cores wait in a loop until they are given given an
+address to jump to in this Mailbox (``bl31_warm_entrypoint``).
+
+Once BL31 has finished and the primary core has jumped to the BL33 payload, it
+has to call ``PSCI_CPU_ON`` to release the secondary CPUs from the wait loop.
+The payload then makes them wait in another waitloop listening from messages
+from the kernel. When the primary CPU jumps into the kernel, it will send an
+address to the mailbox so that the secondary CPUs jump to it and are recognised
+by the kernel.
+
+Build Instructions
+------------------
+
+To boot a AArch64 kernel, only the AArch64 toolchain is required.
+
+To boot a AArch32 kernel, both AArch64 and AArch32 toolchains are required. The
+AArch32 toolchain is needed for the AArch32 bootstrap needed to load a 32-bit
+kernel.
+
+The build system concatenates BL1 and the FIP so that the addresses match the
+ones in the memory map. The resulting file is ``armstub8.bin``, located in the
+build folder (e.g. ``build/rpi3/debug/armstub8.bin``). To know how to use this
+file, follow the instructions in `Setup SD card`_.
+
+The following build options are supported:
+
+- ``RPI3_BL33_IN_AARCH32``: This port can load a AArch64 or AArch32 BL33 image.
+ By default this option is 0, which means that TF-A will jump to BL33 in EL2
+ in AArch64 mode. If set to 1, it will jump to BL33 in Hypervisor in AArch32
+ mode.
+
+- ``PRELOADED_BL33_BASE``: Used to specify the address of a BL33 binary that has
+ been preloaded by any other system than using the firmware. ``BL33`` isn't
+ needed in the build command line if this option is used. Specially useful
+ because the file ``kernel8.img`` can be loaded anywhere by modifying the file
+ ``config.txt``. It doesn't have to contain a kernel, it could have any
+ arbitrary payload.
+
+- ``RPI3_DIRECT_LINUX_BOOT``: Disabled by default. Set to 1 to enable the direct
+ boot of the Linux kernel from the firmware. Option ``RPI3_PRELOADED_DTB_BASE``
+ is mandatory when the direct Linux kernel boot is used. Options
+ ``PRELOADED_BL33_BASE`` will most likely be needed as well because it is
+ unlikely that the kernel image will fit in the space reserved for BL33 images.
+ This option can be combined with ``RPI3_BL33_IN_AARCH32`` in order to boot a
+ 32-bit kernel. The only thing this option does is to set the arguments in
+ registers x0-x3 or r0-r2 as expected by the kernel.
+
+- ``RPI3_PRELOADED_DTB_BASE``: Auxiliary build option needed when using
+ ``RPI3_DIRECT_LINUX_BOOT=1``. This option allows to specify the location of a
+ DTB in memory.
+
+- ``RPI3_RUNTIME_UART``: Indicates whether the UART should be used at runtime
+ or disabled. ``-1`` (default) disables the runtime UART. Any other value
+ enables the default UART (currently UART1) for runtime messages.
+
+- ``RPI3_USE_UEFI_MAP``: Set to 1 to build ATF with the altername memory
+ mapping required for an UEFI firmware payload. These changes are needed
+ to be able to run Windows on ARM64. This option, which is disabled by
+ default, results in the following memory mappings:
+
+::
+
+ 0x00000000 +-----------------+
+ | ROM | BL1
+ 0x00010000 +-----------------+
+ | DTB | (Loaded by the VideoCore)
+ 0x00020000 +-----------------+
+ | FIP |
+ 0x00030000 +-----------------+
+ | |
+ | UEFI PAYLOAD |
+ | |
+ 0x00200000 +-----------------+
+ | Secure SRAM | BL2, BL31
+ 0x00300000 +-----------------+
+ | Secure DRAM | BL32 (Secure payload)
+ 0x00400000 +-----------------+
+ | |
+ | |
+ | Non-secure DRAM | BL33
+ | |
+ | |
+ 0x01000000 +-----------------+
+ | |
+ | ... |
+ | |
+ 0x3F000000 +-----------------+
+ | I/O |
+
+- ``BL32``: This port can load and run OP-TEE. The OP-TEE image is optional.
+ Please use the code from `here <https://github.com/OP-TEE/optee_os>`__.
+ Build the Trusted Firmware with option ``BL32=tee-header_v2.bin
+ BL32_EXTRA1=tee-pager_v2.bin BL32_EXTRA2=tee-pageable_v2.bin``
+ to put the binaries into the FIP.
+
+ .. 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
+ contents of the FIP automatically signed by the build process. The ROT key
+ will be generated and output to ``rot_key.pem`` in the build directory. It is
+ able to set ROT_KEY to your own key in PEM format. Also in order to build,
+ you need to clone mbed TLS from `here <https://github.com/ARMmbed/mbedtls>`__.
+ ``MBEDTLS_DIR`` must point at the mbed TLS source directory.
+
+- ``ENABLE_STACK_PROTECTOR``: Disabled by default. It uses the hardware RNG of
+ the board.
+
+The following is not currently supported:
+
+- AArch32 for TF-A itself.
+
+- ``EL3_PAYLOAD_BASE``: The reason is that you can already load anything to any
+ address by changing the file ``armstub8.bin``, so there's no point in using
+ TF-A in this case.
+
+- ``MULTI_CONSOLE_API=0``: The multi console API must be enabled. Note that the
+ crash console uses the internal 16550 driver functions directly in order to be
+ able to print error messages during early crashes before setting up the
+ multi console API.
+
+Building the firmware for kernels that don't support PSCI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the case for the 32-bit image of Raspbian, for example. 64-bit kernels
+always support PSCI, but they may not know that the system understands PSCI due
+to an incorrect DTB file.
+
+First, clone and compile the 32-bit version of the `Raspberry Pi 3 TF-A
+bootstrap`_. Choose the one needed for the architecture of your kernel.
+
+Then compile TF-A. For a 32-bit kernel, use the following command line:
+
+.. code:: shell
+
+ CROSS_COMPILE=aarch64-linux-gnu- make PLAT=rpi3 \
+ RPI3_BL33_IN_AARCH32=1 \
+ BL33=../rpi3-arm-tf-bootstrap/aarch32/el2-bootstrap.bin
+
+For a 64-bit kernel, use this other command line:
+
+.. code:: shell
+
+ CROSS_COMPILE=aarch64-linux-gnu- make PLAT=rpi3 \
+ BL33=../rpi3-arm-tf-bootstrap/aarch64/el2-bootstrap.bin
+
+However, enabling PSCI support in a 64-bit kernel is really easy. In the
+repository `Raspberry Pi 3 TF-A bootstrap`_ there is a patch that can be applied
+to the Linux kernel tree maintained by the Raspberry Pi foundation. It modifes
+the DTS to tell the kernel to use PSCI. Once this patch is applied, follow the
+instructions in `AArch64 kernel build instructions`_ to get a working 64-bit
+kernel image and supporting files.
+
+Building the firmware for kernels that support PSCI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For a 64-bit kernel:
+
+.. code:: shell
+
+ CROSS_COMPILE=aarch64-linux-gnu- make PLAT=rpi3 \
+ PRELOADED_BL33_BASE=0x02000000 \
+ RPI3_PRELOADED_DTB_BASE=0x01000000 \
+ RPI3_DIRECT_LINUX_BOOT=1
+
+For a 32-bit kernel:
+
+.. code:: shell
+
+ CROSS_COMPILE=aarch64-linux-gnu- make PLAT=rpi3 \
+ PRELOADED_BL33_BASE=0x02000000 \
+ RPI3_PRELOADED_DTB_BASE=0x01000000 \
+ RPI3_DIRECT_LINUX_BOOT=1 \
+ RPI3_BL33_IN_AARCH32=1
+
+AArch64 kernel build instructions
+---------------------------------
+
+The following instructions show how to install and run a AArch64 kernel by
+using a SD card with the default `Raspbian`_ install as base. Skip them if you
+want to use the default 32-bit kernel.
+
+Note that this system won't be fully 64-bit because all the tools in the
+filesystem are 32-bit binaries, but it's a quick way to get it working, and it
+allows the user to run 64-bit binaries in addition to 32-bit binaries.
+
+1. Clone the `Linux tree fork`_ maintained by the Raspberry Pi Foundation. To
+ speed things up, do a shallow clone of the desired branch.
+
+.. code:: shell
+
+ git clone --depth=1 -b rpi-4.18.y https://github.com/raspberrypi/linux
+ cd linux
+
+2. Configure and compile the kernel. Adapt the number after ``-j`` so that it is
+ 1.5 times the number of CPUs in your computer. This may take some time to
+ finish.
+
+.. code:: shell
+
+ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcmrpi3_defconfig
+ make -j 6 ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-
+
+3. Copy the kernel image and the device tree to the SD card. Replace the path
+ by the corresponding path in your computers to the ``boot`` partition of the
+ SD card.
+
+.. code:: shell
+
+ cp arch/arm64/boot/Image /path/to/boot/kernel8.img
+ cp arch/arm64/boot/dts/broadcom/bcm2710-rpi-3-b.dtb /path/to/boot/
+ cp arch/arm64/boot/dts/broadcom/bcm2710-rpi-3-b-plus.dtb /path/to/boot/
+
+4. Install the kernel modules. Replace the path by the corresponding path to the
+ filesystem partition of the SD card on your computer.
+
+.. code:: shell
+
+ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- \
+ INSTALL_MOD_PATH=/path/to/filesystem modules_install
+
+5. Follow the instructions in `Setup SD card`_ except for the step of renaming
+ the existing ``kernel7.img`` (we have already copied a AArch64 kernel).
+
+Setup SD card
+-------------
+
+The instructions assume that you have an SD card with a fresh install of
+`Raspbian`_ (or that, at least, the ``boot`` partition is untouched, or nearly
+untouched). They have been tested with the image available in 2018-03-13.
+
+1. Insert the SD card and open the ``boot`` partition.
+
+2. Rename ``kernel7.img`` to ``kernel8.img``. This tricks the VideoCore
+ bootloader into booting the Arm cores in AArch64 mode, like TF-A needs,
+ even though the kernel is not compiled for AArch64.
+
+3. Copy ``armstub8.bin`` here. When ``kernel8.img`` is available, The VideoCore
+ bootloader will look for a file called ``armstub8.bin`` and load it at
+ address **0x0** instead of a predefined one.
+
+4. To enable the serial port "Mini UART" in Linux, open ``cmdline.txt`` and add
+ ``console=serial0,115200 console=tty1``.
+
+5. Open ``config.txt`` and add the following lines at the end (``enable_uart=1``
+ is only needed to enable debugging through the Mini UART):
+
+::
+
+ enable_uart=1
+ kernel_address=0x02000000
+ device_tree_address=0x01000000
+
+If you connect a serial cable to the Mini UART and your computer, and connect
+to it (for example, with ``screen /dev/ttyUSB0 115200``) you should see some
+text. In the case of an AArch32 kernel, you should see something like this:
+
+::
+
+ NOTICE: Booting Trusted Firmware
+ NOTICE: BL1: v1.4(release):v1.4-329-g61e94684-dirty
+ NOTICE: BL1: Built : 00:09:25, Nov 6 2017
+ NOTICE: BL1: Booting BL2
+ NOTICE: BL2: v1.4(release):v1.4-329-g61e94684-dirty
+ NOTICE: BL2: Built : 00:09:25, Nov 6 2017
+ NOTICE: BL1: Booting BL31
+ NOTICE: BL31: v1.4(release):v1.4-329-g61e94684-dirty
+ NOTICE: BL31: Built : 00:09:25, Nov 6 2017
+ [ 0.266484] bcm2835-aux-uart 3f215040.serial: could not get clk: -517
+
+ Raspbian GNU/Linux 9 raspberrypi ttyS0
+ raspberrypi login:
+
+Just enter your credentials, everything should work as expected. Note that the
+HDMI output won't show any text during boot.
+
+.. _default Arm stub: https://github.com/raspberrypi/tools/blob/master/armstubs/armstub7.S
+.. _default AArch64 stub: https://github.com/raspberrypi/tools/blob/master/armstubs/armstub8.S
+.. _Linux kernel tree: https://github.com/torvalds/linux
+.. _Linux tree fork: https://github.com/raspberrypi/linux
+.. _Raspberry Pi 3: https://www.raspberrypi.org/products/raspberry-pi-3-model-b/
+.. _Raspberry Pi 3 TF-A bootstrap: https://github.com/AntonioND/rpi3-arm-tf-bootstrap
+.. _Raspberry Pi 3 documentation: https://www.raspberrypi.org/documentation/
+.. _Raspbian: https://www.raspberrypi.org/downloads/raspbian/
diff --git a/docs/plat/rpi4.rst b/docs/plat/rpi4.rst
new file mode 100644
index 0000000..6e83fd7
--- /dev/null
+++ b/docs/plat/rpi4.rst
@@ -0,0 +1,84 @@
+Raspberry Pi 4
+==============
+
+The `Raspberry Pi 4`_ is an inexpensive single-board computer that contains four
+Arm Cortex-A72 cores. Also in contrast to previous Raspberry Pi versions this
+model has a GICv2 interrupt controller.
+
+This port is a minimal port to support loading non-secure EL2 payloads such
+as a 64-bit Linux kernel. Other payloads such as U-Boot or EDK-II should work
+as well, but have not been tested at this point.
+
+**IMPORTANT NOTE**: This port isn't secure. All of the memory used is DRAM,
+which is available from both the Non-secure and Secure worlds. The SoC does
+not seem to feature a secure memory controller of any kind, so portions of
+DRAM can't be protected properly from the Non-secure world.
+
+Build Instructions
+------------------
+
+There are no real configuration options at this point, so there is only
+one universal binary (bl31.bin), which can be built with:
+
+.. code:: shell
+
+ CROSS_COMPILE=aarch64-linux-gnu- make PLAT=rpi4 DEBUG=1
+
+Copy the generated build/rpi4/debug/bl31.bin to the SD card, adding an entry
+starting with ``armstub=``, then followed by the respective file name to
+``config.txt``. You should have AArch64 code in the file loaded as the
+"kernel", as BL31 will drop into AArch64/EL2 to the respective load address.
+arm64 Linux kernels are known to work this way.
+
+Other options that should be set in ``config.txt`` to properly boot 64-bit
+kernels are:
+
+::
+
+ enable_uart=1
+ arm_64bit=1
+ enable_gic=1
+
+The BL31 code will patch the provided device tree blob in memory to advertise
+PSCI support, also will add a reserved-memory node to the DT to tell the
+non-secure payload to not touch the resident TF-A code.
+
+If you connect a serial cable between the Mini UART and your computer, and
+connect to it (for example, with ``screen /dev/ttyUSB0 115200``) you should
+see some text from BL31, followed by the output of the EL2 payload.
+The command line provided is read from the ``cmdline.txt`` file on the SD card.
+
+TF-A port design
+----------------
+
+In contrast to the existing Raspberry Pi 3 port this one here is a BL31-only
+port, also it deviates quite a lot from the RPi3 port in many other ways.
+There is not so much difference between the two models, so eventually those
+two could be (more) unified in the future.
+
+As with the previous models, the GPU and its firmware are the first entity to
+run after the SoC gets its power. The on-chip Boot ROM loads the next stage
+(bootcode.bin) from flash (EEPROM), which is again GPU code.
+This part knows how to access the MMC controller and how to parse a FAT
+filesystem, so it will load further components and configuration files
+from the first FAT partition on the SD card.
+
+To accommodate this existing way of configuring and setting up the board,
+we use as much of this workflow as possible.
+If bootcode.bin finds a file called ``armstub8.bin`` on the SD card or it gets
+pointed to such code by finding a ``armstub=`` key in ``config.txt``, it will
+load this file to the beginning of DRAM (address 0) and execute it in
+AArch64 EL3.
+But before doing that, it will also load a "kernel" and the device tree into
+memory. The load addresses have a default, but can also be changed by
+setting them in ``config.txt``. If the GPU firmware finds a magic value in the
+armstub image file, it will put those two load addresses in memory locations
+near the beginning of memory, where TF-A code picks them up.
+
+To keep things simple, we will just use the kernel load address as the BL33
+entry point, also put the DTB address in the x0 register, as requested by
+the arm64 Linux kernel boot protocol. This does not necessarily mean that
+the EL2 payload needs to be a Linux kernel, a bootloader or any other kernel
+would work as well, as long as it can cope with having the DT address in
+register x0. If the payload has other means of finding the device tree, it
+could ignore this address as well.
diff --git a/docs/plat/rz-g2.rst b/docs/plat/rz-g2.rst
new file mode 100644
index 0000000..e7ae620
--- /dev/null
+++ b/docs/plat/rz-g2.rst
@@ -0,0 +1,228 @@
+Renesas RZ/G
+============
+
+The "RZ/G" Family of high-end 64-bit Arm®-based microprocessors (MPUs)
+enables the solutions required for the smart society of the future.
+Through a variety of Arm Cortex®-A53 and A57-based devices, engineers can
+easily implement high-resolution human machine interfaces (HMI), embedded
+vision, embedded artificial intelligence (e-AI) and real-time control and
+industrial ethernet connectivity.
+
+The scalable RZ/G hardware platform and flexible software platform
+cover the full product range, from the premium class to the entry
+level. Plug-ins are available for multiple open-source software tools.
+
+
+Renesas RZ/G2 reference platforms:
+----------------------------------
+
++--------------+----------------------------------------------------------------------------------+
+| Board | Details |
++==============+===============+==================================================================+
+| hihope-rzg2h | "96 boards" compatible board from Hoperun equipped with Renesas RZ/G2H SoC |
+| +----------------------------------------------------------------------------------+
+| | http://hihope.org/product/musashi |
++--------------+----------------------------------------------------------------------------------+
+| hihope-rzg2m | "96 boards" compatible board from Hoperun equipped with Renesas RZ/G2M SoC |
+| +----------------------------------------------------------------------------------+
+| | http://hihope.org/product/musashi |
++--------------+----------------------------------------------------------------------------------+
+| hihope-rzg2n | "96 boards" compatible board from Hoperun equipped with Renesas RZ/G2N SoC |
+| +----------------------------------------------------------------------------------+
+| | http://hihope.org/product/musashi |
++--------------+----------------------------------------------------------------------------------+
+| ek874 | "96 boards" compatible board from Silicon Linux equipped with Renesas RZ/G2E SoC |
+| +----------------------------------------------------------------------------------+
+| | https://www.si-linux.co.jp/index.php?CAT%2FCAT874 |
++--------------+----------------------------------------------------------------------------------+
+
+`boards info <https://www.renesas.com/us/en/products/rzg-linux-platform/rzg-marcketplace/board-solutions.html#rzg2>`__
+
+The current TF-A port has been tested on the HiHope RZ/G2M
+SoC_id r8a774a1 revision ES1.3.
+
+
+::
+
+ ARM CA57 (ARMv8) 1.5 GHz dual core, with NEON/VFPv4, L1$ I/D 48K/32K, L2$ 1MB
+ ARM CA53 (ARMv8) 1.2 GHz quad core, with NEON/VFPv4, L1$ I/D 32K/32K, L2$ 512K
+ Memory controller for LPDDR4-3200 4GB in 2 channels(32-bit bus mode)
+ Two- and three-dimensional graphics engines,
+ Video processing units,
+ Display Output,
+ Video Input,
+ SD card host interface,
+ USB3.0 and USB2.0 interfaces,
+ CAN interfaces,
+ Ethernet AVB,
+ Wi-Fi + BT,
+ PCI Express Interfaces,
+ Memories
+ INTERNAL 384KB SYSTEM RAM
+ DDR 4 GB LPDDR4
+ QSPI FLASH 64MB
+ EMMC 32 GB EMMC (HS400 240 MBYTES/S)
+ MICROSD-CARD SLOT (SDR104 100 MBYTES/S)
+
+Overview
+--------
+On RZ/G2 SoCs the BOOTROM starts the cpu at EL3; for this port BL2
+will therefore be entered at this exception level (the Renesas' ATF
+reference tree [1] resets into EL1 before entering BL2 - see its
+bl2.ld.S)
+
+BL2 initializes DDR before determining the boot reason (cold or warm).
+
+Once BL2 boots, it determines the boot reason, writes it to shared
+memory (BOOT_KIND_BASE) together with the BL31 parameters
+(PARAMS_BASE) and jumps to BL31.
+
+To all effects, BL31 is as if it is being entered in reset mode since
+it still needs to initialize the rest of the cores; this is the reason
+behind using direct shared memory access to BOOT_KIND_BASE _and_
+PARAMS_BASE instead of using registers to get to those locations (see
+el3_common_macros.S and bl31_entrypoint.S for the RESET_TO_BL31 use
+case).
+
+[1] https://github.com/renesas-rz/meta-rzg2/tree/BSP-1.0.5/recipes-bsp/arm-trusted-firmware/files
+
+
+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 HiHope RZ/G2M development kit used in this port.
+
+Build Tested:
+~~~~~~~~~~~~~
+
+.. code:: bash
+
+ make bl2 bl31 rzg LOG_LEVEL=40 PLAT=rzg LSI=G2M RCAR_DRAM_SPLIT=2\
+ RCAR_LOSSY_ENABLE=1 SPD="none" MBEDTLS_DIR=$mbedtls
+
+System Tested:
+~~~~~~~~~~~~~~
+* mbed_tls:
+ git@github.com:ARMmbed/mbedtls.git [devel]
+
+| commit 72ca39737f974db44723760623d1b29980c00a88
+| Merge: ef94c4fcf dd9ec1c57
+| Author: Janos Follath <janos.follath@arm.com>
+| Date: Wed Oct 7 09:21:01 2020 +0100
+
+* u-boot:
+ The port has beent tested using mainline uboot with HiHope RZ/G2M board
+ specific patches.
+
+| commit 46ce9e777c1314ccb78906992b94001194eaa87b
+| Author: Heiko Schocher <hs@denx.de>
+| Date: Tue Nov 3 15:22:36 2020 +0100
+
+* linux:
+ The port has beent tested using mainline kernel.
+
+| commit f8394f232b1eab649ce2df5c5f15b0e528c92091
+| Author: Linus Torvalds <torvalds@linux-foundation.org>
+| Date: Sun Nov 8 16:10:16 2020 -0800
+| Linux 5.10-rc3
+
+TF-A Build Procedure
+~~~~~~~~~~~~~~~~~~~~
+
+- Fetch all the above 3 repositories.
+
+- Prepare the AARCH64 toolchain.
+
+- Build u-boot using hihope_rzg2_defconfig.
+
+ Result: u-boot-elf.srec
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-linux-gnu-
+ hihope_rzg2_defconfig
+
+ make CROSS_COMPILE=aarch64-linux-gnu-
+
+- Build TF-A
+
+ Result: bootparam_sa0.srec, cert_header_sa6.srec, bl2.srec, bl31.srec
+
+.. code:: bash
+
+ make bl2 bl31 rzg LOG_LEVEL=40 PLAT=rzg LSI=G2M RCAR_DRAM_SPLIT=2\
+ RCAR_LOSSY_ENABLE=1 SPD="none" MBEDTLS_DIR=$mbedtls
+
+
+Install Procedure
+~~~~~~~~~~~~~~~~~
+
+- Boot the board in Mini-monitor mode and enable access to the
+ QSPI flash.
+
+
+- Use the flash_writer utility[2] to flash all the SREC files.
+
+[2] https://github.com/renesas-rz/rzg2_flash_writer
+
+
+Boot trace
+----------
+::
+
+ INFO: ARM GICv2 driver initialized
+ NOTICE: BL2: RZ/G2 Initial Program Loader(CA57) Rev.2.0.6
+ NOTICE: BL2: PRR is RZ/G2M Ver.1.3
+ NOTICE: BL2: Board is HiHope RZ/G2M Rev.4.0
+ NOTICE: BL2: Boot device is QSPI Flash(40MHz)
+ NOTICE: BL2: LCM state is unknown
+ NOTICE: BL2: DDR3200(rev.0.40)
+ NOTICE: BL2: [COLD_BOOT]
+ NOTICE: BL2: DRAM Split is 2ch
+ NOTICE: BL2: QoS is default setting(rev.0.19)
+ NOTICE: BL2: DRAM refresh interval 1.95 usec
+ NOTICE: BL2: Periodic Write DQ Training
+ NOTICE: BL2: CH0: 400000000 - 47fffffff, 2 GiB
+ NOTICE: BL2: CH2: 600000000 - 67fffffff, 2 GiB
+ NOTICE: BL2: Lossy Decomp areas
+ NOTICE: Entry 0: DCMPAREACRAx:0x80000540 DCMPAREACRBx:0x570
+ NOTICE: Entry 1: DCMPAREACRAx:0x40000000 DCMPAREACRBx:0x0
+ NOTICE: Entry 2: DCMPAREACRAx:0x20000000 DCMPAREACRBx:0x0
+ NOTICE: BL2: FDT at 0xe631db30
+ NOTICE: BL2: v2.3(release):v2.4-rc0-2-g1433701e5
+ NOTICE: BL2: Built : 13:45:26, Nov 7 2020
+ NOTICE: BL2: Normal boot
+ INFO: BL2: Doing platform setup
+ INFO: BL2: Loading image id 3
+ NOTICE: BL2: dst=0xe631d200 src=0x8180000 len=512(0x200)
+ NOTICE: BL2: dst=0x43f00000 src=0x8180400 len=6144(0x1800)
+ WARNING: r-car ignoring the BL31 size from certificate,using RCAR_TRUSTED_SRAM_SIZE instead
+ INFO: Loading image id=3 at address 0x44000000
+ NOTICE: rcar_file_len: len: 0x0003e000
+ NOTICE: BL2: dst=0x44000000 src=0x81c0000 len=253952(0x3e000)
+ INFO: Image id=3 loaded: 0x44000000 - 0x4403e000
+ INFO: BL2: Loading image id 5
+ INFO: Loading image id=5 at address 0x50000000
+ NOTICE: rcar_file_len: len: 0x00100000
+ NOTICE: BL2: dst=0x50000000 src=0x8300000 len=1048576(0x100000)
+ INFO: Image id=5 loaded: 0x50000000 - 0x50100000
+ NOTICE: BL2: Booting BL31
+ INFO: Entry point address = 0x44000000
+ INFO: SPSR = 0x3cd
+
+
+ U-Boot 2021.01-rc1-00244-gac37e14fbd (Nov 04 2020 - 20:03:34 +0000)
+
+ CPU: Renesas Electronics R8A774A1 rev 1.3
+ Model: HopeRun HiHope RZ/G2M with sub board
+ DRAM: 3.9 GiB
+ MMC: mmc@ee100000: 0, mmc@ee160000: 1
+ Loading Environment from MMC... OK
+ In: serial@e6e88000
+ Out: serial@e6e88000
+ Err: serial@e6e88000
+ Net: eth0: ethernet@e6800000
+ Hit any key to stop autoboot: 0
+ =>
diff --git a/docs/plat/socionext-uniphier.rst b/docs/plat/socionext-uniphier.rst
new file mode 100644
index 0000000..9288193
--- /dev/null
+++ b/docs/plat/socionext-uniphier.rst
@@ -0,0 +1,116 @@
+Socionext UniPhier
+==================
+
+Socionext UniPhier Armv8-A SoCs use Trusted Firmware-A (TF-A) as the secure
+world firmware, supporting BL2 and BL31.
+
+UniPhier SoC family implements its internal boot ROM, which loads 64KB [1]_
+image from a non-volatile storage to the on-chip SRAM, and jumps over to it.
+TF-A provides a special mode, BL2-AT-EL3, which enables BL2 to execute at EL3.
+It is useful for platforms with non-TF-A boot ROM, like UniPhier. Here, a
+problem is BL2 does not fit in the 64KB limit if
+:ref:`Trusted Board Boot (TBB) <Trusted Board Boot>` is enabled.
+To solve this issue, Socionext provides a first stage loader called
+`UniPhier BL`_. This loader runs in the on-chip SRAM, initializes the DRAM,
+expands BL2 there, and hands the control over to it. Therefore, all images
+of TF-A run in DRAM.
+
+The UniPhier platform works with/without TBB. See below for the build process
+of each case. The image authentication for the UniPhier platform fully
+complies with the Trusted Board Boot Requirements (TBBR) specification.
+
+The UniPhier BL does not implement the authentication functionality, that is,
+it can not verify the BL2 image by itself. Instead, the UniPhier BL assures
+the BL2 validity in a different way; BL2 is GZIP-compressed and appended to
+the UniPhier BL. The concatenation of the UniPhier BL and the compressed BL2
+fits in the 64KB limit. The concatenated image is loaded by the internal boot
+ROM (and verified if the chip fuses are blown).
+
+
+Boot Flow
+---------
+
+1. The Boot ROM
+
+ This is hard-wired ROM, so never corrupted. It loads the UniPhier BL (with
+ compressed-BL2 appended) into the on-chip SRAM. If the SoC fuses are blown,
+ the image is verified by the SoC's own method.
+
+2. UniPhier BL
+
+ This runs in the on-chip SRAM. After the minimum SoC initialization and DRAM
+ setup, it decompresses the appended BL2 image into the DRAM, then jumps to
+ the BL2 entry.
+
+3. BL2 (at EL3)
+
+ This runs in the DRAM. It extracts more images such as BL31, BL33 (optionally
+ SCP_BL2, BL32 as well) from Firmware Image Package (FIP). If TBB is enabled,
+ they are all authenticated by the standard mechanism of TF-A.
+ After loading all the images, it jumps to the BL31 entry.
+
+4. BL31, BL32, and BL33
+
+ They all run in the DRAM. See :ref:`Firmware Design` for details.
+
+
+Basic Build
+-----------
+
+BL2 must be compressed for the reason above. The UniPhier's platform makefile
+provides a build target ``bl2_gzip`` for this.
+
+For a non-secure boot loader (aka BL33), U-Boot is well supported for UniPhier
+SoCs. The U-Boot image (``u-boot.bin``) must be built in advance. For the build
+procedure of U-Boot, refer to the document in the `U-Boot`_ project.
+
+To build minimum functionality for UniPhier (without TBB)::
+
+ make CROSS_COMPILE=<gcc-prefix> PLAT=uniphier BL33=<path-to-BL33> bl2_gzip fip
+
+Output images:
+
+- ``bl2.bin.gz``
+- ``fip.bin``
+
+
+Optional features
+-----------------
+
+- Trusted Board Boot
+
+ `mbed TLS`_ is needed as the cryptographic and image parser modules.
+ Refer to the :ref:`Prerequisites` document for the appropriate version of
+ mbed TLS.
+
+ To enable TBB, add the following options to the build command::
+
+ TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 MBEDTLS_DIR=<path-to-mbedtls>
+
+- System Control Processor (SCP)
+
+ If desired, FIP can include an SCP BL2 image. If BL2 finds an SCP BL2 image
+ in FIP, BL2 loads it into DRAM and kicks the SCP. Most of UniPhier boards
+ still work without SCP, but SCP provides better power management support.
+
+ To include SCP BL2, add the following option to the build command::
+
+ SCP_BL2=<path-to-SCP>
+
+- BL32 (Secure Payload)
+
+ To enable BL32, add the following options to the build command::
+
+ SPD=<spd> BL32=<path-to-BL32>
+
+ If you use TSP for BL32, ``BL32=<path-to-BL32>`` is not required. Just add the
+ following::
+
+ SPD=tspd
+
+
+.. [1] Some SoCs can load 80KB, but the software implementation must be aligned
+ to the lowest common denominator.
+.. _UniPhier BL: https://github.com/uniphier/uniphier-bl
+.. _U-Boot: https://www.denx.de/wiki/U-Boot
+.. _mbed TLS: https://tls.mbed.org/
diff --git a/docs/plat/stm32mp1.rst b/docs/plat/stm32mp1.rst
new file mode 100644
index 0000000..23ea25a
--- /dev/null
+++ b/docs/plat/stm32mp1.rst
@@ -0,0 +1,280 @@
+STMicroelectronics STM32MP1
+===========================
+
+STM32MP1 is a microprocessor designed by STMicroelectronics
+based on Arm Cortex-A7.
+It is an Armv7-A platform, using dedicated code from TF-A.
+More information can be found on `STM32MP1 Series`_ page.
+
+
+STM32MP1 Versions
+-----------------
+
+There are 2 variants for STM32MP1: STM32MP13 and STM32MP15
+
+STM32MP13 Versions
+~~~~~~~~~~~~~~~~~~
+The STM32MP13 series is available in 3 different lines which are pin-to-pin compatible:
+
+- STM32MP131: Single Cortex-A7 core
+- STM32MP133: STM32MP131 + 2*CAN, ETH2(GMAC), ADC1
+- STM32MP135: STM32MP133 + DCMIPP, LTDC
+
+Each line comes with a security option (cryptography & secure boot) and a Cortex-A frequency option:
+
+- A Cortex-A7 @ 650 MHz
+- C Secure Boot + HW Crypto + Cortex-A7 @ 650 MHz
+- D Cortex-A7 @ 900 MHz
+- F Secure Boot + HW Crypto + Cortex-A7 @ 900 MHz
+
+STM32MP15 Versions
+~~~~~~~~~~~~~~~~~~
+The STM32MP15 series is available in 3 different lines which are pin-to-pin compatible:
+
+- STM32MP157: Dual Cortex-A7 cores, Cortex-M4 core @ 209 MHz, 3D GPU, DSI display interface and CAN FD
+- STM32MP153: Dual Cortex-A7 cores, Cortex-M4 core @ 209 MHz and CAN FD
+- STM32MP151: Single Cortex-A7 core, Cortex-M4 core @ 209 MHz
+
+Each line comes with a security option (cryptography & secure boot) and a Cortex-A frequency option:
+
+- A Basic + Cortex-A7 @ 650 MHz
+- C Secure Boot + HW Crypto + Cortex-A7 @ 650 MHz
+- D Basic + Cortex-A7 @ 800 MHz
+- F Secure Boot + HW Crypto + Cortex-A7 @ 800 MHz
+
+The `STM32MP1 part number codification`_ page gives more information about part numbers.
+
+Design
+------
+The STM32MP1 resets in the ROM code of the Cortex-A7.
+The primary boot core (core 0) executes the boot sequence while
+secondary boot core (core 1) is kept in a holding pen loop.
+The ROM code boot sequence loads the TF-A binary image from boot device
+to embedded SRAM.
+
+The TF-A image must be properly formatted with a STM32 header structure
+for ROM code is able to load this image.
+Tool stm32image can be used to prepend this header to the generated TF-A binary.
+
+Boot with FIP
+~~~~~~~~~~~~~
+The use of FIP is now the recommended way to boot STM32MP1 platform.
+Only BL2 (with STM32 header) is loaded by ROM code. The other binaries are
+inside the FIP binary: BL32 (SP_min or OP-TEE), U-Boot and their respective
+device tree blobs.
+
+
+Memory mapping
+~~~~~~~~~~~~~~
+
+::
+
+ 0x00000000 +-----------------+
+ | | ROM
+ 0x00020000 +-----------------+
+ | |
+ | ... |
+ | |
+ 0x2FFC0000 +-----------------+ \
+ | BL32 DTB | |
+ 0x2FFC5000 +-----------------+ |
+ | BL32 | |
+ 0x2FFDF000 +-----------------+ |
+ | ... | |
+ 0x2FFE3000 +-----------------+ |
+ | BL2 DTB | | Embedded SRAM
+ 0x2FFEA000 +-----------------+ |
+ | BL2 | |
+ 0x2FFFF000 +-----------------+ |
+ | SCMI mailbox | |
+ 0x30000000 +-----------------+ /
+ | |
+ | ... |
+ | |
+ 0x40000000 +-----------------+
+ | |
+ | | Devices
+ | |
+ 0xC0000000 +-----------------+ \
+ | | |
+ 0xC0100000 +-----------------+ |
+ | BL33 | | Non-secure RAM (DDR)
+ | ... | |
+ | | |
+ 0xFFFFFFFF +-----------------+ /
+
+
+Boot sequence
+~~~~~~~~~~~~~
+
+ROM code -> BL2 (compiled with BL2_AT_EL3) -> BL32 (SP_min) -> BL33 (U-Boot)
+
+or if Op-TEE is used:
+
+ROM code -> BL2 (compiled with BL2_AT_EL3) -> OP-TEE -> BL33 (U-Boot)
+
+
+Build Instructions
+------------------
+Boot media(s) supported by BL2 must be specified in the build command.
+Available storage medias are:
+
+- ``STM32MP_SDMMC``
+- ``STM32MP_EMMC``
+- ``STM32MP_RAW_NAND``
+- ``STM32MP_SPI_NAND``
+- ``STM32MP_SPI_NOR``
+
+Serial boot devices:
+
+- ``STM32MP_UART_PROGRAMMER``
+- ``STM32MP_USB_PROGRAMMER``
+
+
+Other configuration flags:
+
+- | ``DTB_FILE_NAME``: to precise board device-tree blob to be used.
+ | Default: stm32mp157c-ev1.dtb
+- | ``DWL_BUFFER_BASE``: the 'serial boot' load address of FIP,
+ | default location (end of the first 128MB) is used when absent
+- | ``STM32MP_EARLY_CONSOLE``: to enable early traces before clock driver is setup.
+ | Default: 0 (disabled)
+- | ``STM32MP_RECONFIGURE_CONSOLE``: to re-configure crash console (especially after BL2).
+ | Default: 0 (disabled)
+- | ``STM32MP_UART_BAUDRATE``: to select UART baud rate.
+ | Default: 115200
+- | ``STM32_TF_VERSION``: to manage BL2 monotonic counter.
+ | Default: 0
+- | ``STM32MP13``: to select STM32MP13 variant configuration.
+ | Default: 0
+- | ``STM32MP15``: to select STM32MP15 variant configuration.
+ | Default: 1
+
+
+Boot with FIP
+~~~~~~~~~~~~~
+You need to build BL2, BL32 (SP_min or OP-TEE) and BL33 (U-Boot) before building FIP binary.
+
+U-Boot
+______
+
+.. code:: bash
+
+ cd <u-boot_directory>
+ make stm32mp15_trusted_defconfig
+ make DEVICE_TREE=stm32mp157c-ev1 all
+
+OP-TEE (optional)
+_________________
+
+.. code:: bash
+
+ cd <optee_directory>
+ make CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm PLATFORM=stm32mp1 \
+ CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts
+
+
+TF-A BL32 (SP_min)
+__________________
+If you choose not to use OP-TEE, you can use TF-A SP_min.
+To build TF-A BL32, and its device tree file:
+
+.. code:: bash
+
+ make CROSS_COMPILE=arm-none-eabi- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 \
+ AARCH32_SP=sp_min DTB_FILE_NAME=stm32mp157c-ev1.dtb bl32 dtbs
+
+TF-A BL2
+________
+To build TF-A BL2 with its STM32 header for SD-card boot:
+
+.. code:: bash
+
+ make CROSS_COMPILE=arm-none-eabi- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 \
+ DTB_FILE_NAME=stm32mp157c-ev1.dtb STM32MP_SDMMC=1
+
+For other boot devices, you have to replace STM32MP_SDMMC in the previous command
+with the desired device flag.
+
+This BL2 is independent of the BL32 used (SP_min or OP-TEE)
+
+
+FIP
+___
+With BL32 SP_min:
+
+.. code:: bash
+
+ make CROSS_COMPILE=arm-none-eabi- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 \
+ AARCH32_SP=sp_min \
+ DTB_FILE_NAME=stm32mp157c-ev1.dtb \
+ BL33=<u-boot_directory>/u-boot-nodtb.bin \
+ BL33_CFG=<u-boot_directory>/u-boot.dtb \
+ fip
+
+With OP-TEE:
+
+.. code:: bash
+
+ make CROSS_COMPILE=arm-none-eabi- PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 \
+ AARCH32_SP=optee \
+ DTB_FILE_NAME=stm32mp157c-ev1.dtb \
+ BL33=<u-boot_directory>/u-boot-nodtb.bin \
+ BL33_CFG=<u-boot_directory>/u-boot.dtb \
+ BL32=<optee_directory>/tee-header_v2.bin \
+ BL32_EXTRA1=<optee_directory>/tee-pager_v2.bin
+ BL32_EXTRA2=<optee_directory>/tee-pageable_v2.bin
+ fip
+
+Trusted Boot Board
+__________________
+
+.. code:: shell
+
+ tools/cert_create/cert_create -n --rot-key "build/stm32mp1/debug/rot_key.pem" \
+ --tfw-nvctr 0 \
+ --ntfw-nvctr 0 \
+ --key-alg ecdsa --hash-alg sha256 \
+ --trusted-key-cert build/stm32mp1/cert_images/trusted-key-cert.key-crt \
+ --tos-fw <optee_directory>/tee-header_v2.bin \
+ --tos-fw-extra1 <optee_directory>/tee-pager_v2.bin \
+ --tos-fw-extra2 <optee_directory>/tee-pageable_v2.bin \
+ --tos-fw-cert build/stm32mp1/cert_images/tee-header_v2.bin.crt \
+ --tos-fw-key-cert build/stm32mp1/cert_images/tee-header_v2.bin.key-crt \
+ --nt-fw <u-boot_directory>/u-boot-nodtb.bin \
+ --nt-fw-cert build/stm32mp1/cert_images/u-boot.bin.crt \
+ --nt-fw-key-cert build/stm32mp1/cert_images/u-boot.bin.key-crt \
+ --hw-config <u-boot_directory>/u-boot.dtb \
+ --fw-config build/stm32mp1/debug/fdts/fw-config.dtb \
+ --stm32mp-cfg-cert build/stm32mp1/cert_images/stm32mp_cfg_cert.crt
+
+ tools/fiptool/fiptool create --tos-fw <optee_directory>/tee-header_v2.bin \
+ --tos-fw-extra1 <optee_directory>/tee-pager_v2.bin \
+ --tos-fw-extra2 <optee_directory>/tee-pageable_v2.bin \
+ --nt-fw <u-boot_directory>/u-boot-nodtb.bin \
+ --hw-config <u-boot_directory>/u-boot.dtb \
+ --fw-config build/stm32mp1/debug/fdts/fw-config.dtb \
+ --tos-fw-cert build/stm32mp1/cert_images/tee-header_v2.bin.crt \
+ --tos-fw-key-cert build/stm32mp1/cert_images/tee-header_v2.bin.key-crt \
+ --nt-fw-cert build/stm32mp1/cert_images/u-boot.bin.crt \
+ --nt-fw-key-cert build/stm32mp1/cert_images/u-boot.bin.key-crt \
+ --stm32mp-cfg-cert build/stm32mp1/cert_images/stm32mp_cfg_cert.crt stm32mp1.fip
+
+
+
+Populate SD-card
+----------------
+
+Boot with FIP
+~~~~~~~~~~~~~
+The SD-card has to be formatted with GPT.
+It should contain at least those partitions:
+
+- fsbl: to copy the tf-a-stm32mp157c-ev1.stm32 binary (BL2)
+- fip: which contains the FIP binary
+
+Usually, two copies of fsbl are used (fsbl1 and fsbl2) instead of one partition fsbl.
+
+
+.. _STM32MP1 Series: https://www.st.com/en/microcontrollers-microprocessors/stm32mp1-series.html
+.. _STM32MP1 part number codification: https://wiki.st.com/stm32mpu/wiki/STM32MP15_microprocessor#Part_number_codification
diff --git a/docs/plat/synquacer.rst b/docs/plat/synquacer.rst
new file mode 100644
index 0000000..dd29d29
--- /dev/null
+++ b/docs/plat/synquacer.rst
@@ -0,0 +1,117 @@
+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
+processor. This port of the Trusted Firmware only supports this platform at
+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>`__
+
+- edk2:
+ `link <https://github.com/tianocore/edk2>`__
+
+- edk2-platforms:
+ `link <https://github.com/tianocore/edk2-platforms>`__
+
+- edk2-non-osi:
+ `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:
+
+ .. code:: shell
+
+ sudo apt install acpica-tools device-tree-compiler uuid-dev
+
+- Secondly, create a new working directory and store the absolute path to this
+ directory in an environment variable, WORKSPACE. It does not matter where
+ this directory is created but as an example:
+
+ .. code:: shell
+
+ export WORKSPACE=$HOME/build/developerbox-firmware
+ mkdir -p $WORKSPACE
+
+- Run the following commands to clone the source code:
+
+ .. code:: shell
+
+ cd $WORKSPACE
+ git clone https://github.com/ARM-software/arm-trusted-firmware -b master
+ git clone https://github.com/tianocore/edk2.git -b master
+ git clone https://github.com/tianocore/edk2-platforms.git -b master
+ git clone https://github.com/tianocore/edk2-non-osi.git -b master
+
+- Build ATF:
+
+ .. code:: shell
+
+ cd $WORKSPACE/arm-trusted-firmware
+ make -j`nproc` PLAT=synquacer PRELOADED_BL33_BASE=0x8200000 bl31 fiptool
+ tools/fiptool/fiptool create \
+ --tb-fw ./build/synquacer/release/bl31.bin \
+ --soc-fw ./build/synquacer/release/bl31.bin \
+ --scp-fw ./build/synquacer/release/bl31.bin \
+ ../edk2-non-osi/Platform/Socionext/DeveloperBox/fip_all_arm_tf.bin
+
+- Build EDK2:
+
+ .. code:: shell
+
+ cd $WORKSPACE
+ export PACKAGES_PATH=$WORKSPACE/edk2:$WORKSPACE/edk2-platforms:$WORKSPACE/edk2-non-osi
+ export ACTIVE_PLATFORM="Platform/Socionext/DeveloperBox/DeveloperBox.dsc"
+ export GCC5_AARCH64_PREFIX=aarch64-linux-gnu-
+ unset ARCH
+
+ . edk2/edksetup.sh
+ make -C edk2/BaseTools
+
+ build -p $ACTIVE_PLATFORM -b RELEASE -a AARCH64 -t GCC5 -n `nproc` -D DO_X86EMU=TRUE
+
+- The firmware image, which comprises the option ROM, ARM trusted firmware and
+ EDK2 itself, can be found $WORKSPACE/../Build/DeveloperBox/RELEASE_GCC5/FV/.
+ Use SYNQUACERFIRMWAREUPDATECAPSULEFMPPKCS7.Cap for UEFI capsule update and
+ SPI_NOR_IMAGE.fd for the serial flasher.
+
+ Note #1: -t GCC5 can be loosely translated as “enable link-time-optimization”;
+ any version of gcc >= 5 will support this feature and may be used to build EDK2.
+
+ 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
+ the capsule update method:.
+
+ .. code:: shell
+
+ sudo apt install fwupdate
+ sudo fwupdate --apply {50b94ce5-8b63-4849-8af4-ea479356f0e3} \
+ SYNQUACERFIRMWAREUPDATECAPSULEFMPPKCS7.Cap
+ sudo reboot
+
+- Alternatively you can install SPI_NOR_IMAGE.fd using the `board recovery method`_.
+
+.. _link: https://www.96boards.org/product/developerbox/
+.. _board recovery method: https://www.96boards.org/documentation/enterprise/developerbox/installation/board-recovery.md.html
diff --git a/docs/plat/ti-k3.rst b/docs/plat/ti-k3.rst
new file mode 100644
index 0000000..4843227
--- /dev/null
+++ b/docs/plat/ti-k3.rst
@@ -0,0 +1,57 @@
+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
+ \
+ Optional direct to Linux boot
+ \
+ --> BL33(Linux)
+
+Texas Instruments K3 SoCs contain an R5 processor used as the boot master, it
+loads the needed images for A53 startup, because of this we do not need BL1 or
+BL2 TF-A stages.
+
+Build Instructions
+------------------
+
+https://github.com/ARM-software/arm-trusted-firmware.git
+
+TF-A:
+
+.. code:: shell
+
+ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=k3 SPD=opteed all
+
+OP-TEE:
+
+.. code:: shell
+
+ make ARCH=arm CROSS_COMPILE64=aarch64-linux-gnu- PLATFORM=k3 CFG_ARM64_core=y all
+
+R5 U-Boot:
+
+.. code:: shell
+
+ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- am65x_evm_r5_defconfig
+ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- SYSFW=<path to SYSFW>
+
+A53 U-Boot:
+
+.. code:: shell
+
+ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- am65x_evm_a53_defconfig
+ make ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- ATF=<path> TEE=<path>
+
+Deploy Images
+-------------
+
+.. code:: shell
+
+ cp tiboot3.bin tispl.bin u-boot.img /sdcard/boot/
diff --git a/docs/plat/warp7.rst b/docs/plat/warp7.rst
new file mode 100644
index 0000000..f98a76f
--- /dev/null
+++ b/docs/plat/warp7.rst
@@ -0,0 +1,210 @@
+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.
+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
+------------------
+
+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
+~~~~~~
+
+https://git.linaro.org/landing-teams/working/mbl/u-boot.git
+
+.. code:: shell
+
+ git checkout -b rms-atf-optee-uboot linaro-mbl/rms-atf-optee-uboot
+ make warp7_bl33_defconfig;
+ make u-boot.imx arch=ARM CROSS_COMPILE=arm-linux-gnueabihf-
+
+OP-TEE
+~~~~~~
+
+https://github.com/OP-TEE/optee_os.git
+
+.. code:: shell
+
+ 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
+~~~~
+
+https://github.com/ARM-software/arm-trusted-firmware.git
+
+The following commands assume that a directory exits in the top-level TFA build
+directory "fiptool_images". "fiptool_images" contains
+
+- u-boot.bin
+ The binary output from the u-boot instructions above
+
+- tee-header_v2.bin
+- tee-pager_v2.bin
+- tee-pageable_v2.bin
+ Binary outputs from the previous OPTEE build steps
+
+It is also assumed copy of mbedtls is available on the path path ../mbedtls
+ https://github.com/ARMmbed/mbedtls.git
+ At the time of writing HEAD points to 0592ea772aee48ca1e6d9eb84eca8e143033d973
+
+.. code:: shell
+
+ mkdir fiptool_images
+ cp /path/to/optee/out/arm-plat-imx/core/tee-header_v2.bin fiptool_images
+ cp /path/to/optee/out/arm-plat-imx/core/tee-pager_v2.bin fiptool_images
+ cp /path/to/optee/out/arm-plat-imx/core/tee-pageable_v2.bin fiptool_images
+
+ make CROSS_COMPILE=${CROSS_COMPILE} PLAT=warp7 ARCH=aarch32 ARM_ARCH_MAJOR=7 \
+ ARM_CORTEX_A7=yes AARCH32_SP=optee PLAT_WARP7_UART=1 GENERATE_COT=1 \
+ TRUSTED_BOARD_BOOT=1 USE_TBBR_DEFS=1 MBEDTLS_DIR=../mbedtls \
+ NEED_BL32=yes BL32=fiptool_images/tee-header_v2.bin \
+ BL32_EXTRA1=fiptool_images/tee-pager_v2.bin \
+ BL32_EXTRA2=fiptool_images/tee-pageable_v2.bin \
+ BL33=fiptool_images/u-boot.bin certificates all
+
+ /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
+~~~
+
+.. code:: shell
+
+ cp /path/to/uboot/u-boot.bin fiptool_images
+ cp /path/to/linux/arch/boot/dts/imx7s-warp.dtb fiptool_images
+
+ tools/cert_create/cert_create -n --rot-key "build/warp7/debug/rot_key.pem" \
+ --tfw-nvctr 0 \
+ --ntfw-nvctr 0 \
+ --trusted-key-cert fiptool_images/trusted-key-cert.key-crt \
+ --tb-fw=build/warp7/debug/bl2.bin \
+ --tb-fw-cert fiptool_images/trusted-boot-fw.key-crt\
+ --tos-fw fiptool_images/tee-header_v2.bin \
+ --tos-fw-cert fiptool_images/tee-header_v2.bin.crt \
+ --tos-fw-key-cert fiptool_images/tee-header_v2.bin.key-crt \
+ --tos-fw-extra1 fiptool_images/tee-pager_v2.bin \
+ --tos-fw-extra2 fiptool_images/tee-pageable_v2.bin \
+ --nt-fw fiptool_images/u-boot.bin \
+ --nt-fw-cert fiptool_images/u-boot.bin.crt \
+ --nt-fw-key-cert fiptool_images/u-boot.bin.key-crt \
+ --hw-config fiptool_images/imx7s-warp.dtb
+
+ tools/fiptool/fiptool create --tos-fw fiptool_images/tee-header_v2.bin \
+ --tos-fw-extra1 fiptool_images/tee-pager_v2.bin \
+ --tos-fw-extra2 fiptool_images/tee-pageable_v2.bin \
+ --nt-fw fiptool_images/u-boot.bin \
+ --hw-config fiptool_images/imx7s-warp.dtb \
+ --tos-fw-cert fiptool_images/tee-header_v2.bin.crt \
+ --tos-fw-key-cert fiptool_images/tee-header_v2.bin.key-crt \
+ --nt-fw-cert fiptool_images/u-boot.bin.crt \
+ --nt-fw-key-cert fiptool_images/u-boot.bin.key-crt \
+ --trusted-key-cert fiptool_images/trusted-key-cert.key-crt \
+ --tb-fw-cert fiptool_images/trusted-boot-fw.key-crt warp7.fip
+
+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
+
+.. code:: shell
+
+ => ums 0 mmc 0
+
+Next flash bl2.imx and warp7.fip
+
+bl2.imx is flashed @ 1024 bytes
+warp7.fip is flash @ 1048576 bytes
+
+.. code:: shell
+
+ sudo dd if=bl2.bin.imx of=/dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0 bs=512 seek=2 conv=notrunc
+ # Offset is 1MB 1048576 => 1048576 / 512 = 2048
+ sudo dd if=./warp7.fip of=/dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0 bs=512 seek=2048 conv=notrunc
+
+Remember to umount the USB device pefore proceeding
+
+.. code:: shell
+
+ sudo umount /dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0*
+
+
+Signing BL2
+-----------
+
+A further step is to sign BL2.
+
+The image_sign.sh and bl2_sign.csf files alluded to blow are available here.
+
+https://github.com/bryanodonoghue/atf-code-signing
+
+It is suggested you use this script plus the example CSF file in order to avoid
+hard-coding data into your CSF files.
+
+Download both "image_sign.sh" and "bl2_sign.csf" to your
+arm-trusted-firmware top-level directory.
+
+.. code:: shell
+
+ #!/bin/bash
+ SIGN=image_sign.sh
+ TEMP=`pwd`/temp
+ BL2_CSF=bl2_sign.csf
+ BL2_IMX=bl2.bin.imx
+ CST_PATH=/path/to/cst-2.3.2
+ CST_BIN=${CST_PATH}/linux64/cst
+
+ #Remove temp
+ rm -rf ${TEMP}
+ mkdir ${TEMP}
+
+ # Generate IMX header
+ /path/to/u-boot/tools/mkimage -n u-boot.cfgout.warp7 -T imximage -e 0x9df00000 -d ./build/warp7/debug/bl2.bin ./build/warp7/debug/bl2.bin.imx > ${TEMP}/${BL2_IMX}.log
+
+ # Copy required items to $TEMP
+ cp build/warp7/debug/bl2.bin.imx ${TEMP}
+ cp ${CST_PATH}/keys/* ${TEMP}
+ cp ${CST_PATH}/crts/* ${TEMP}
+ cp ${BL2_CSF} ${TEMP}
+
+ # Generate signed BL2 image
+ ./${SIGN} image_sign_mbl_binary ${TEMP} ${BL2_CSF} ${BL2_IMX} ${CST_BIN}
+
+ # Copy signed BL2 to top-level directory
+ cp ${TEMP}/${BL2_IMX}-signed .
+ cp ${BL2_RECOVER_CSF} ${TEMP}
+
+
+The resulting bl2.bin.imx-signed can replace bl2.bin.imx in the Deploy
+Images section above, once done.
+
+Suggested flow for verifying.
+
+1. Followed all previous steps above and verify a non-secure ATF boot
+2. Down the NXP Code Singing Tool
+3. Generate keys
+4. Program the fuses on your board
+5. Replace bl2.bin.imx with bl2.bin.imx-signed
+6. Verify inside u-boot that "hab_status" shows no events
+7. Subsequently close your board.
+
+If you have HAB events @ step 6 - do not lock your board.
+
+To get a good over-view of generating keys and programming the fuses on the
+board read "High Assurance Boot for Dummies" by Boundary Devices.
+
+https://boundarydevices.com/high-assurance-boot-hab-dummies/
diff --git a/docs/plat/xilinx-versal-net.rst b/docs/plat/xilinx-versal-net.rst
new file mode 100644
index 0000000..5d2e663
--- /dev/null
+++ b/docs/plat/xilinx-versal-net.rst
@@ -0,0 +1,31 @@
+Xilinx Versal NET
+=================
+
+Trusted Firmware-A implements the EL3 firmware layer for Xilinx Versal NET.
+The platform only uses the runtime part of TF-A as Xilinx Versal NET already
+has a BootROM (BL1) and PMC FW (BL2).
+
+BL31 is TF-A.
+BL32 is an optional Secure Payload.
+BL33 is the non-secure world software (U-Boot, Linux etc).
+
+To build:
+```bash
+make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal_net bl31
+```
+
+Xilinx Versal NET platform specific build options
+-------------------------------------------------
+
+* `VERSAL_NET_ATF_MEM_BASE`: Specifies the base address of the bl31 binary.
+* `VERSAL_NET_ATF_MEM_SIZE`: Specifies the size of the memory region of the bl31 binary.
+* `VERSAL_NET_BL32_MEM_BASE`: Specifies the base address of the bl32 binary.
+* `VERSAL_NET_BL32_MEM_SIZE`: Specifies the size of the memory region of the bl32 binary.
+
+* `VERSAL_NET_CONSOLE`: Select the console driver. Options:
+ - `pl011`, `pl011_0`: ARM pl011 UART 0
+ - `pl011_1` : ARM pl011 UART 1
+
+* `TFA_NO_PM` : Platform Management support.
+ - 0 : Enable Platform Management (Default)
+ - 1 : Disable Platform Management
diff --git a/docs/plat/xilinx-versal.rst b/docs/plat/xilinx-versal.rst
new file mode 100644
index 0000000..09a6ee2
--- /dev/null
+++ b/docs/plat/xilinx-versal.rst
@@ -0,0 +1,55 @@
+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
+BootROM (BL1) and PMC FW (BL2).
+
+BL31 is TF-A.
+BL32 is an optional Secure Payload.
+BL33 is the non-secure world software (U-Boot, Linux etc).
+
+To build:
+```bash
+make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31
+```
+
+To build ATF for different platform (supported are "silicon"(default) and "versal_virt")
+```bash
+make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal VERSAL_PLATFORM=versal_virt bl31
+```
+
+To build TF-A for JTAG DCC console
+```bash
+make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 VERSAL_CONSOLE=dcc
+```
+
+To build TF-A with Straight-Line Speculation(SLS)
+```bash
+make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 HARDEN_SLS_ALL=1
+```
+
+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.
+* `VERSAL_BL32_MEM_SIZE`: Specifies the size of the memory region of the bl32 binary.
+
+* `VERSAL_CONSOLE`: Select the console driver. Options:
+ - `pl011`, `pl011_0`: ARM pl011 UART 0
+ - `pl011_1` : ARM pl011 UART 1
+
+* `VERSAL_PLATFORM`: Select the platform. Options:
+ - `versal_virt` : Versal Virtual platform
+ - `spp_itr6` : SPP ITR6
+ - `emu_itr6` : EMU ITR6
+
+# PLM->TF-A Parameter Passing
+------------------------------
+The PLM populates a data structure with image information for the TF-A. The TF-A
+uses that data to hand off to the loaded images. The address of the handoff
+data structure is passed in the ```PMC_GLOBAL_GLOB_GEN_STORAGE4``` register.
+The register is free to be used by other software once the TF-A is bringing up
+further firmware images.
diff --git a/docs/plat/xilinx-zynqmp.rst b/docs/plat/xilinx-zynqmp.rst
new file mode 100644
index 0000000..af1cb22
--- /dev/null
+++ b/docs/plat/xilinx-zynqmp.rst
@@ -0,0 +1,73 @@
+Xilinx Zynq UltraScale+ MPSoC
+=============================
+
+Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Xilinx Zynq
+UltraScale + MPSoC.
+The platform only uses the runtime part of TF-A as ZynqMP already has a
+BootROM (BL1) and FSBL (BL2).
+
+BL31 is TF-A.
+BL32 is an optional Secure Payload.
+BL33 is the non-secure world software (U-Boot, Linux etc).
+
+To build:
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp RESET_TO_BL31=1 bl31
+
+To build bl32 TSP you have to rebuild bl31 too:
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd RESET_TO_BL31=1 bl31 bl32
+
+To build TF-A for JTAG DCC console:
+
+.. code:: bash
+
+ make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp RESET_TO_BL31=1 bl31 ZYNQMP_CONSOLE=dcc
+
+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.
+- ``ZYNQMP_BL32_MEM_BASE``: Specifies the base address of the bl32 binary.
+- ``ZYNQMP_BL32_MEM_SIZE``: Specifies the size of the memory region of the bl32 binary.
+
+- ``ZYNQMP_CONSOLE``: Select the console driver. Options:
+
+ - ``cadence``, ``cadence0``: Cadence UART 0
+ - ``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
+structure is passed in the ``PMU_GLOBAL.GLOBAL_GEN_STORAGE6`` register. The
+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:
+
+::
+
+ +-+
+ |0|
+ +-+
+ +-------+---+---+-------+
+ | | | |
+ | | | |
+ v v v v
+ +-+ +-+ +-+ +-+
+ |0| |1| |2| |3|
+ +-+ +-+ +-+ +-+
+
+The 4 leaf power domains represent the individual A53 cores, while resources
+common to the cluster are grouped in the power domain on the top.