Paul Beesley | 9774302 | 2019-07-12 11:37:07 +0100 | [diff] [blame] | 1 | TF-A Porting Guide for Marvell Platforms |
| 2 | ======================================== |
| 3 | |
| 4 | This section describes how to port TF-A to a customer board, assuming that the |
| 5 | SoC being used is already supported in TF-A. |
| 6 | |
| 7 | |
| 8 | Source Code Structure |
| 9 | --------------------- |
| 10 | |
Grzegorz Jaszczyk | 3039bce | 2019-11-05 13:14:59 +0100 | [diff] [blame] | 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'). |
Paul Beesley | 9774302 | 2019-07-12 11:37:07 +0100 | [diff] [blame] | 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 | |
Grzegorz Jaszczyk | 3039bce | 2019-11-05 13:14:59 +0100 | [diff] [blame] | 17 | Files that require porting are located at ``plat/marvell/armada/<soc family>/<soc>_cust`` directory. |
Paul Beesley | 9774302 | 2019-07-12 11:37:07 +0100 | [diff] [blame] | 18 | |
| 19 | |
| 20 | Armada-70x0/Armada-80x0 Porting |
| 21 | ------------------------------- |
| 22 | |
| 23 | SoC Physical Address Map (marvell_plat_config.c) |
| 24 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 25 | |
| 26 | This file describes the SoC physical memory mapping to be used for the CCU, |
| 27 | IOWIN, AXI-MBUS and IOB address decode units (Refer to the functional spec for |
| 28 | more details). |
| 29 | |
| 30 | In most cases, using the default address decode windows should work OK. |
| 31 | |
| 32 | In cases where a special physical address map is needed (e.g. Special size for |
| 33 | PCIe MEM windows, large memory mapped SPI flash...), then porting of the SoC |
| 34 | memory 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 |
Grzegorz Jaszczyk | 8d2bdcd | 2018-12-10 12:01:29 +0100 | [diff] [blame^] | 39 | ``docs/plat/marvell/armada/misc/mvebu-[ccu/iob/amb/io-win].rst`` files. |
Paul Beesley | 9774302 | 2019-07-12 11:37:07 +0100 | [diff] [blame] | 40 | |
| 41 | boot 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 | |
| 66 | In A7040-DB specific implementation |
Grzegorz Jaszczyk | 3039bce | 2019-11-05 13:14:59 +0100 | [diff] [blame] | 67 | (``plat/marvell/armada/a8k/a70x0/board/marvell_plat_config.c``), the image skip is |
Paul Beesley | 9774302 | 2019-07-12 11:37:07 +0100 | [diff] [blame] | 68 | implemented using GPIO: mpp 33 (SW5). |
| 69 | |
| 70 | Before resetting the board make sure there is a valid image on the next flash |
| 71 | address: |
| 72 | |
| 73 | -tftp [valid address] flash-image.bin |
| 74 | -sf update [valid address] 0x2000000 [size] |
| 75 | |
| 76 | Press reset and keep pressing the button connected to the chosen GPIO pin. A |
| 77 | skip image request message is printed on the screen and boot rom boots from the |
| 78 | saved image at the next position. |
| 79 | |
| 80 | DDR Porting (dram_port.c) |
| 81 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 82 | |
| 83 | This file defines the dram topology and parameters of the target board. |
| 84 | |
| 85 | The DDR code is part of the BLE component, which is an extension of ARM Trusted |
| 86 | Firmware (TF-A). |
| 87 | |
| 88 | The DDR driver called mv_ddr is released separately apart from TF-A sources. |
| 89 | |
| 90 | The BLE and consequently, the DDR init code is executed at the early stage of |
| 91 | the boot process. |
| 92 | |
| 93 | Each supported platform of the TF-A has its own DDR porting file called |
Grzegorz Jaszczyk | 3039bce | 2019-11-05 13:14:59 +0100 | [diff] [blame] | 94 | dram_port.c located at ``atf/plat/marvell/armada/a8k/<platform>/board`` directory. |
Paul Beesley | 9774302 | 2019-07-12 11:37:07 +0100 | [diff] [blame] | 95 | |
| 96 | Please refer to '<path_to_mv_ddr_sources>/doc/porting_guide.txt' for detailed |
| 97 | porting description. |
| 98 | |
| 99 | The build target directory is "build/<platform>/release/ble". |
| 100 | |
| 101 | Comphy 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 | .. seealso:: |
| 114 | For XFI/SFI comphy type there is procedure "rx_training" which eases |
Paul Beesley | f2ec714 | 2019-10-04 16:17:46 +0000 | [diff] [blame] | 115 | process of suiting some of the parameters. Please see *uboot_cmd* |
Paul Beesley | 9774302 | 2019-07-12 11:37:07 +0100 | [diff] [blame] | 116 | section: rx_training. |
| 117 | |
| 118 | The PHY porting layer simplifies updating static values per board type, |
| 119 | which are now grouped in one place. |
| 120 | |
| 121 | .. note:: |
| 122 | The parameters for the same type of comphy may vary even for the same |
| 123 | board type, it is because the lanes from comphy-x to some PHY may have |
| 124 | different HW characteristic than lanes from comphy-y to the same |
| 125 | (multiplexed) or other PHY. |
| 126 | |
| 127 | - Porting: |
| 128 | The porting layer for PHY was introduced in TF-A. There is one file |
| 129 | ``drivers/marvell/comphy/phy-default-porting-layer.h`` which contains the |
| 130 | defaults. Those default parameters are used only if there is no appropriate |
Grzegorz Jaszczyk | 3039bce | 2019-11-05 13:14:59 +0100 | [diff] [blame] | 131 | phy-porting-layer.h file under: ``plat/marvell/armada/<soc |
Paul Beesley | 9774302 | 2019-07-12 11:37:07 +0100 | [diff] [blame] | 132 | family>/<platform>/board/phy-porting-layer.h``. If the phy-porting-layer.h |
| 133 | exists, the phy-default-porting-layer.h is not going to be included. |
| 134 | |
| 135 | .. warning:: |
| 136 | Not all comphy types are already reworked to support the PHY porting |
| 137 | layer, currently the porting layer is supported for XFI/SFI and SATA |
| 138 | comphy types. |
| 139 | |
| 140 | The easiest way to prepare the PHY porting layer for custom board is to copy |
| 141 | existing example to a new platform: |
| 142 | |
Grzegorz Jaszczyk | 3039bce | 2019-11-05 13:14:59 +0100 | [diff] [blame] | 143 | - cp ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/armada/<soc family>/<platform>/board/phy-porting-layer.h" |
Paul Beesley | 9774302 | 2019-07-12 11:37:07 +0100 | [diff] [blame] | 144 | - adjust relevant parameters or |
| 145 | - if different comphy index is used for specific feature, move it to proper table entry and then adjust. |
| 146 | |
| 147 | .. note:: |
| 148 | The final table size with comphy parameters can be different, depending |
| 149 | on the CP module count for given SoC type. |
| 150 | |
| 151 | - Example: |
| 152 | Example porting layer for armada-8040-db is under: |
Grzegorz Jaszczyk | 3039bce | 2019-11-05 13:14:59 +0100 | [diff] [blame] | 153 | ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` |
Paul Beesley | 9774302 | 2019-07-12 11:37:07 +0100 | [diff] [blame] | 154 | |
| 155 | .. note:: |
| 156 | If there is no PHY porting layer for new platform (missing |
| 157 | phy-porting-layer.h), the default values are used |
| 158 | (drivers/marvell/comphy/phy-default-porting-layer.h) and the user is |
| 159 | warned: |
| 160 | |
| 161 | .. warning:: |
| 162 | "Using default comphy parameters - it may be required to suit them for |
| 163 | your board". |