1TF-A Porting Guide for Marvell Platforms 2======================================== 3 4This section describes how to port TF-A to a customer board, assuming that the 5SoC being used is already supported in TF-A. 6 7 8Source Code Structure 9--------------------- 10 11- The customer platform specific code shall reside under ``plat/marvell/armada/<soc family>/<soc>_cust`` 12 (e.g. 'plat/marvell/armada/a8k/a7040_cust'). 13- The platform name for build purposes is called ``<soc>_cust`` (e.g. ``a7040_cust``). 14- The build system will reuse all files from within the soc directory, and take only the porting 15 files from the customer platform directory. 16 17Files that require porting are located at ``plat/marvell/armada/<soc family>/<soc>_cust`` directory. 18 19 20Armada-70x0/Armada-80x0 Porting 21------------------------------- 22 23SoC Physical Address Map (marvell_plat_config.c) 24~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 25 26This file describes the SoC physical memory mapping to be used for the CCU, 27IOWIN, AXI-MBUS and IOB address decode units (Refer to the functional spec for 28more details). 29 30In most cases, using the default address decode windows should work OK. 31 32In cases where a special physical address map is needed (e.g. Special size for 33PCIe MEM windows, large memory mapped SPI flash...), then porting of the SoC 34memory map is required. 35 36.. note:: 37 For a detailed information on how CCU, IOWIN, AXI-MBUS & IOB work, please 38 refer to the SoC functional spec, and under 39 ``docs/plat/marvell/armada/misc/mvebu-[ccu/iob/amb/io-win].rst`` files. 40 41boot loader recovery (marvell_plat_config.c) 42~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 43 44- Background: 45 46 Boot rom can skip the current image and choose to boot from next position if a 47 specific value (``0xDEADB002``) is returned by the ble main function. This 48 feature is used for boot loader recovery by booting from a valid flash-image 49 saved in next position on flash (e.g. address 2M in SPI flash). 50 51 Supported options to implement the skip request are: 52 - GPIO 53 - I2C 54 - User defined 55 56- Porting: 57 58 Under marvell_plat_config.c, implement struct skip_image that includes 59 specific board parameters. 60 61 .. warning:: 62 To disable this feature make sure the struct skip_image is not implemented. 63 64- Example: 65 66In A7040-DB specific implementation 67(``plat/marvell/armada/a8k/a70x0/board/marvell_plat_config.c``), the image skip is 68implemented using GPIO: mpp 33 (SW5). 69 70Before resetting the board make sure there is a valid image on the next flash 71address: 72 73 -tftp [valid address] flash-image.bin 74 -sf update [valid address] 0x2000000 [size] 75 76Press reset and keep pressing the button connected to the chosen GPIO pin. A 77skip image request message is printed on the screen and boot rom boots from the 78saved image at the next position. 79 80DDR Porting (dram_port.c) 81~~~~~~~~~~~~~~~~~~~~~~~~~ 82 83This file defines the dram topology and parameters of the target board. 84 85The DDR code is part of the BLE component, which is an extension of ARM Trusted 86Firmware (TF-A). 87 88The DDR driver called mv_ddr is released separately apart from TF-A sources. 89 90The BLE and consequently, the DDR init code is executed at the early stage of 91the boot process. 92 93Each supported platform of the TF-A has its own DDR porting file called 94dram_port.c located at ``atf/plat/marvell/armada/a8k/<platform>/board`` directory. 95 96Please refer to '<path_to_mv_ddr_sources>/doc/porting_guide.txt' for detailed 97porting description. 98 99The build target directory is "build/<platform>/release/ble". 100 101Comphy Porting (phy-porting-layer.h or phy-default-porting-layer.h) 102~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 103 104- Background: 105 Some of the comphy's parameters value depend on the HW connection between 106 the SoC and the PHY. Every board type has specific HW characteristics like 107 wire length. Due to those differences some comphy parameters vary between 108 board types. Therefore each board type can have its own list of values for 109 all relevant comphy parameters. The PHY porting layer specifies which 110 parameters need to be suited and the board designer should provide relevant 111 values. 112 113 The PHY porting layer simplifies updating static values per board type, 114 which are now grouped in one place. 115 116 .. note:: 117 The parameters for the same type of comphy may vary even for the same 118 board type, it is because the lanes from comphy-x to some PHY may have 119 different HW characteristic than lanes from comphy-y to the same 120 (multiplexed) or other PHY. 121 122- Porting: 123 The porting layer for PHY was introduced in TF-A. There is one file 124 ``drivers/marvell/comphy/phy-default-porting-layer.h`` which contains the 125 defaults. Those default parameters are used only if there is no appropriate 126 phy-porting-layer.h file under: ``plat/marvell/armada/<soc 127 family>/<platform>/board/phy-porting-layer.h``. If the phy-porting-layer.h 128 exists, the phy-default-porting-layer.h is not going to be included. 129 130 .. warning:: 131 Not all comphy types are already reworked to support the PHY porting 132 layer, currently the porting layer is supported for XFI/SFI and SATA 133 comphy types. 134 135 The easiest way to prepare the PHY porting layer for custom board is to copy 136 existing example to a new platform: 137 138 - cp ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/armada/<soc family>/<platform>/board/phy-porting-layer.h" 139 - adjust relevant parameters or 140 - if different comphy index is used for specific feature, move it to proper table entry and then adjust. 141 142 .. note:: 143 The final table size with comphy parameters can be different, depending 144 on the CP module count for given SoC type. 145 146- Example: 147 Example porting layer for armada-8040-db is under: 148 ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` 149 150 .. note:: 151 If there is no PHY porting layer for new platform (missing 152 phy-porting-layer.h), the default values are used 153 (drivers/marvell/comphy/phy-default-porting-layer.h) and the user is 154 warned: 155 156 .. warning:: 157 "Using default comphy parameters - it may be required to suit them for 158 your board". 159