doc: Add Marvell build and porting documentation

Add marvell platform build and porting documents.

Change-Id: I8e4ffb200269551fb1dd65d2ea4dfa3da399a8ae
Signed-off-by: Haim Boot <hayim@marvell.com>
Signed-off-by: Konstantin Porotchkin <kostap@marvell.com>
Reviewed-on: http://vgitil04.il.marvell.com:8080/38135

2 files changed, 259 insertions, 0 deletions

diff --git a/docs/marvell/build.txt b/docs/marvell/build.txt
new file mode 100644
index 00000000..c18c142a
--- /dev/null
+++ b/docs/marvell/build.txt
@@ -0,0 +1,153 @@
+ATF Build Instructions
+======================
+
+This section describes how to compile the ARM Trusted Firmware (ATF) project for Marvell's platforms.
+
+Build Instructions
+------------------
+1. Set the cross compiler:
+
+		# export CROSS_COMPILE=/path/to/toolchain/aarch64-marvell-linux-gnu-
+
+2. Set path for FIP images:
+
+	Set U-Boot image path (relatively to ATF 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 (only for Armada70x0, Armada80x0):
+
+		# export SCP_BL2=path/to/scp_image.bin
+
+3. Armada37x0 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 ATF:
+
+	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_NOTICE	10
+		LOG_LEVEL_ERROR		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. It should be set to 0.
+	- MARVELL_SECURE_BOOT: build trusted(=1)/non trusted(=0) image, default is non trusted.
+	- MV_DDR_PATH: For A7/8K only, use this parameter to point to mv_ddr driver sources to allow BLE build.
+		Usage example: MV_DDR_PATH=path/to/mv_ddr
+		when this parameter is not set, the mv_ddr sources are expected to be located at:
+		drivers/marvell/mv_ddr
+	- DDR_TOPOLOGY: For Armada37x0 only, the DDR topology map index, 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)
+	- 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
+	- BOOTDEV: For Armada37x0 only, the flash boot device, default is SPINOR,
+			Now 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 detail about CONFIG_SYS_MMC_ENV_PART, please refer to u-boot build instructions.
+
+	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 run,
+	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_cust (for customers)
+		- a80x0
+		- a80x0_cust (for customers)
+
+Special Build Flags
+--------------------
+	- PALLADIUM: Enables building ATF for palladium target. This mainly involves changing the UART baud rate
+		and the timer frequency to a lower values to match palladium's setup.
+
+(for more information about build options, please refer to section 'Summary of build options' in  ATF user-guide:
+ https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.md)
+
+
+Build output
+-------------
+Marvell's ATF 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	- ATF 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
+-----------------------------------
+1. Extract the tools/wtp/WTPTP_TOOLS_x_x_xx.zip into a temporary directory
+
+		# cd tools/wtp
+		# 7z x WTPTP_TOOLS_x_x_xx.zip
+
+2. If required, add executable permissions to files in the extracted
+   WTPTP_TOOLS_x_x_xx/Linux_Tools folder:
+
+		# sudo chmod a+x WTPTP_TOOLS_x_x_xx/Linux_Tools/*.exe
+
+3. Copy executable files from WTPTP_TOOLS_x_x_xx/Linux_Tools
+   to location pointed to $PATH environment variable.
+   For instance:
+
+		# sudo cp WTPTP_TOOLS_x_x_xx/Linux_Tools/*.exe /usr/local/bin
+
+4. Make sure the "ntbb_linux.exe" can be executed from any
+   location and "make" passes without error.
+
+5. Install a cross GNU ARM tool chain for building the WTMI binary.
+   Any cross GNU ARM tool chain 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 environment variable CROSS_CM3.
+   Example for BASH shell:
+
+		# export CROSS_CM3=/opt/arm-cross/bin/arm-linux-gnueabi
diff --git a/docs/marvell/porting.txt b/docs/marvell/porting.txt
new file mode 100644
index 00000000..83190eee
--- /dev/null
+++ b/docs/marvell/porting.txt
@@ -0,0 +1,106 @@
+ATF Porting Guide
+=================
+
+This section describes how to port ATF to a customer board, assuming that the SoC being used is already supported
+in ATF.
+
+Source code structure
+---------------------
+- The cusomer platform specific code shall reside under "plat/marvell/<soc family>/<soc>_cust"
+	(e.g. 'plat/marvell/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.
+
+
+Porting
+-------
+Files that require porting are located at "plat/marvell/<soc family>/<soc>_cust" directory.
+
+A7K/A8K specific:
+
+  - SoC Physical Address Map (soc_phys_map_config.c):
+	- This file describes the SoC physical memory mapping to be used for the CCU, RFU, 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, RFU, AXI-MBUS & IOB work, please refer to the SoC functional spec,
+	  and under "doc/marvell/misc/mvebu-[ccu/iob/amb/rfu].txt" files.
+
+  - booloader recovery (marvell_plat_config.c):
+	- Background:
+		bootrom 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 bootloader recovery by booting from a valid flash-image saved on the next
+		position on flash.
+		(e.g. address 2M in SPI flash)
+		supported options to implement the skip request:
+		o GPIO
+		o I2C
+		o User defined
+
+	- Porting:
+		under marvell_plat_config.c need to implement struct that includes the specific board
+		parameters.
+	- Example
+		o A7040-DB specific implementation (.....marvell/plat/a8k/a70x0/board/marvell_plat_config.c)
+		The image skip is implemented by using GPIO:
+		mpp 33 (SW5)
+		before reseting 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 on the button connected to the chosen GPIO pin, a skip image request
+		message is supposed to print on the screen and the bootrom 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 (ATF).
+	- The DDR driver called mv_ddr is released separately apart from ATF sources.
+	- The BLE and consequently, the DDR init code is executed at the early stage of the boot process.
+	- Each supported platform of the ATF has its own DDR porting file called dram_port.c located at
+		"atf/plat/marvell/a8k/<platform>/board" directory.
+	- Please refer to 'mv_ddr/doc/porting_guide.txt' for detailed porting description.
+	  The build target directory is "build/<platform>/release/ble".
+
+A3700 specific:
+
+  - Wake up source configuration for Low Power mode (pm_src.c):
+	- This file defines the wake up source for Low Power mode of the target board.
+	- Each supported platform of the ATF should have its own wake up source file called pm_src.c
+		located at "atf/plat/marvell/a3700/<platform>/board" directory.
+	- In pm_src.c, a dedicate routine with name mv_wake_up_src_config_get() should be defined, which
+		would be called by A3700 power management framework to get wake up source configuration.
+			struct pm_wake_up_src_config *mv_wake_up_src_config_get(void)
+	- The only supported wake up source is South bridge and North bridge GPIO, and each platform
+		could have up to 4 different wake up sources at the same time.
+	- Wake up source configuration is defined as "struct pm_wake_up_src_config"
+		o wake_up_src_num: the number of wake up source, could be up to 4.
+		o wake_up_src: the array for each wake up source configuration.
+			- wake_up_src_type: now the only supported one is WAKE_UP_SRC_GPIO.
+			- wake_up_data: wake up source data.
+				gpio_data.bank_num: GPIO bank number, 0 for North bridge GPIO, 1 for
+					South bridge GPIO.
+				gpio_data.gpio_num: GPIO number that is used as wake up source.
+	- Example of A3700-DB wake up source:
+		static struct pm_wake_up_src_config wake_up_src_cfg = {
+			.wake_up_src_num = 2,
+			.wake_up_src[0] = {
+				.wake_up_src_type = WAKE_UP_SRC_GPIO,
+				.wake_up_data = {
+					.gpio_data.bank_num = 0, /* North Bridge */
+					.gpio_data.gpio_num = 14
+				}
+			},
+			.wake_up_src[1] = {
+				.wake_up_src_type = WAKE_UP_SRC_GPIO,
+				.wake_up_data = {
+					.gpio_data.bank_num = 1, /* South Bridge */
+					.gpio_data.gpio_num = 2
+				}
+			}
+		};
+		struct pm_wake_up_src_config *mv_wake_up_src_config_get(void)
+		{
+			return &wake_up_src_cfg;
+		}