docs/plat/marvell/porting.rst

   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
  11 - The customer platform specific code shall reside under ``plat/marvell/<soc family>/<soc>_cust``
  12   (e.g. 'plat/marvell/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
  17 Files that require porting are located at ``plat/marvell/<soc family>/<soc>_cust`` directory.
  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
  39    ``docs/marvell/misc/mvebu-[ccu/iob/amb/io-win].txt`` files.
  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
  67 (``plat/marvell/a8k/a70x0/board/marvell_plat_config.c``), the image skip is
  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
  94 dram_port.c located at ``atf/plat/marvell/a8k/<platform>/board`` directory.
  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
 115         process of suiting some of the parameters. Please see *uboot_cmd*
 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
 131     phy-porting-layer.h file under: ``plat/marvell/<soc
 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
 143     - cp ``plat/marvell/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/<soc family>/<platform>/board/phy-porting-layer.h"
 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:
 153     ``plat/marvell/a8k/a80x0/board/phy-porting-layer.h``
 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".