Adding upstream version 2.8.0+dfsg.upstream/2.8.0+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

9 files changed, 990 insertions, 0 deletions

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