From 3cbd96a876a00eb4c30af69ce827307a1dbf455c Mon Sep 17 00:00:00 2001 From: Konstantin Porotchkin Date: Wed, 29 Mar 2017 12:55:51 +0300 Subject: doc: Add Marvell build and porting documentation Add marvell platform build and porting documents. Change-Id: I8e4ffb200269551fb1dd65d2ea4dfa3da399a8ae Signed-off-by: Haim Boot Signed-off-by: Konstantin Porotchkin Reviewed-on: http://vgitil04.il.marvell.com:8080/38135 --- docs/marvell/build.txt | 153 +++++++++++++++++++++++++++++++++++++++++++++++ docs/marvell/porting.txt | 106 ++++++++++++++++++++++++++++++++ 2 files changed, 259 insertions(+) create mode 100644 docs/marvell/build.txt create mode 100644 docs/marvell/porting.txt 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= 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//_cust" + (e.g. 'plat/marvell/a8k/a7040_cust'). +- The platform name for build purposes is called "_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//_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//board" directory. + - Please refer to 'mv_ddr/doc/porting_guide.txt' for detailed porting description. + The build target directory is "build//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//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; + } -- cgit