docs: Add Marvell build and porting documents
Change-Id: I341440701b7e5e3555e604dd9d0a356795e6c4fb
Signed-off-by: Hanna Hawa <hannah@marvell.com>
Signed-off-by: Konstantin Porotchkin <kostap@marvell.com>
diff --git a/docs/marvell/build.txt b/docs/marvell/build.txt
new file mode 100644
index 0000000..63a40a8
--- /dev/null
+++ b/docs/marvell/build.txt
@@ -0,0 +1,181 @@
+TF-A Build Instructions
+======================
+
+This section describes how to compile the ARM Trusted Firmware (TF-A) project for Marvell's platforms.
+
+Build Instructions
+------------------
+(1) Set the cross compiler::
+
+ > 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)::
+
+ > 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 Armada80x0 and Aramada8xxy)::
+
+ > export SCP_BL2=path/to/mrvl_scp_bl2*.img
+
+(3) Armada-37x0 build requires WTP tools installation.
+
+ See below in the section "Tools Installation for Armada37x0 Builds".
+ Install ARM 32-bit cross compiler, which is required by building WTMI image for CM3::
+
+ > sudo apt-get install gcc-arm-linux-gnueabi
+
+(4) Clean previous build residuals (if any)::
+
+ > make distclean
+
+(5) Build TF-A:
+
+ There are several build options:
+
+ - DEBUG: default is without debug information (=0). in order to enable it use DEBUG=1
+
+ - LOG_LEVEL: defines the level of logging which will be purged to the default output port.
+
+ LOG_LEVEL_NONE 0
+ LOG_LEVEL_ERROR 10
+ LOG_LEVEL_NOTICE 20
+ LOG_LEVEL_WARNING 30
+ LOG_LEVEL_INFO 40
+ LOG_LEVEL_VERBOSE 50
+
+ - USE_COHERENT_MEM: This flag determines whether to include the coherent memory region in the
+ BL memory map or not.
+
+ -LLC_ENABLE: Flag defining the LLC (L3) cache state. The cache is enabled by default (LLC_ENABLE=1).
+
+ - MARVELL_SECURE_BOOT: build trusted(=1)/non trusted(=0) image, default is non trusted.
+
+ - BLE_PATH:
+ Points to BLE (Binary ROM extension) sources folder. Only required for A8K and A8K+ builds.
+ The parameter is optional, its default value is "ble".
+
+ - MV_DDR_PATH:
+ For A7/8K, use this parameter to point to mv_ddr driver sources to allow BLE build. For A37x0,
+ it is used for ddr_tool build.
+ Usage example: MV_DDR_PATH=path/to/mv_ddr
+ The parameter is optional for A7/8K, when this parameter is not set, the mv_ddr
+ sources are expected to be located at: drivers/marvell/mv_ddr. However, the parameter
+ is necessary for A37x0.
+
+ - DDR_TOPOLOGY: For Armada37x0 only, the DDR topology map index/name, default is 0.
+ Supported Options:
+ - DDR3 1CS (0): DB-88F3720-DDR3-Modular (512MB); EspressoBIN (512MB)
+ - DDR4 1CS (1): DB-88F3720-DDR4-Modular (512MB)
+ - DDR3 2CS (2): EspressoBIN (1GB)
+ - DDR4 2CS (3): DB-88F3720-DDR4-Modular (4GB)
+ - DDR3 1CS (4): DB-88F3720-DDR3-Modular (1GB)
+ - CUSTOMER (CUST): Customer board, DDR3 1CS 512MB
+
+ - CLOCKSPRESET: For Armada37x0 only, 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
+
+ - BOOTDEV: For Armada37x0 only, 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
+
+ - PARTNUM: For Armada37x0 only, 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: For Armada37x0 only, the path of the WTMI image can point to an image which does
+ nothing, an image which supports EFUSE or a customized CM3 firmware binary. The default image
+ is wtmi.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.
+ - WTP: For Armada37x0 only, use this parameter to point to wtptools source code directory, which
+ can be found as a3700_utils.zip in the release.
+ Usage example: WTP=/path/to/a3700_utils
+
+ - CP_NUM: Total amount of CPs (South Bridge) chips wired to the interconnected APs.
+ When the parameter is omitted, the build is uses the default number of CPs equal to 2.
+ The parameter is valid for Armada 8K-plus SoC family (PLAT=a8xxy) and results in a build of images
+ suitable for a8xxY SoC, where "Y" is a number of connected CPs and "xx" is a number of CPU cores.
+ Valid values with CP_NUM is in a range of 0 to 8.
+ The CPs defined by this parameter are evenly distributed across interconnected APs that in turn
+ are dynamically detected. For instance, if the CP_NUM=6 and the TF-A detects 2 interconnected
+ APs, each AP assumed to have 3 attached CPs. With the same amount of APs and CP_NUM=3, the AP0
+ will have 2 CPs connected and AP1 - a just single CP.
+
+ For example, in order to build the image in debug mode with log level up to 'notice' level run::
+
+ > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 PLAT=<MARVELL_PLATFORM> all fip
+
+ 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 DDR3 2CS,
+ the image boot from SPI NOR flash partition 0, and the image is non trusted in WTP, the command
+ line is as following::
+
+ > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 SECURE=0 CLOCKSPRESET=CPU_1000_DDR_800 \
+ DDR_TOPOLOGY=2 BOOTDEV=SPINOR PARTNUM=0 PLAT=a3700 all fip
+
+ Supported MARVELL_PLATFORM are:
+ - a3700
+ - a70x0
+ - a70x0_amc (for AMC board)
+ - a70x0_cust (for customers)
+ - a80x0
+ - a80x0_mcbin (for MacciatoBin)
+
+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 a70x0 and a80x0
+ because of hardware limitation(boot from secondary image can interrupt uart recovery process).
+ This MACRO definition is set in plat/marvell/a8k/common/include/platform_def.h file
+
+(for more information about build options, please refer to section 'Summary of build options' in TF-A user-guide:
+ https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.md)
+
+
+Build output
+-------------
+Marvell's TF-A compilation generates 7 files:
+ - ble.bin - BLe image
+ - 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 - Image which contains boot-image.bin and SPL image; should be placed on the boot flash/device.
+
+
+Tools Installation for Armada37x0 Builds
+-----------------------------------------
+Install a cross GNU ARM tool chain for building the WTMI binary.
+Any cross GNU ARM tool chain that is able to build ARM Cortex M3 binaries
+is suitable.
+
+On Debian/Uboot hosts the default GNU ARM tool chain can be installed
+using the following command::
+
+ > sudo apt-get install gcc-arm-linux-gnueabi
+
+If required, the default tool chain prefix "arm-linux-gnueabi-" can be
+overwritten using the environment variable CROSS_CM3.
+Example for BASH shell::
+
+ > export CROSS_CM3=/opt/arm-cross/bin/arm-linux-gnueabi