marvell: armada: add extra level in marvell platform hierarchy
This commit is a preparation for upcoming support for OcteonTX and
OcteonTX2 product families. Armada platform related files (docs,
plat, include/plat) are moved to the new "armada" sub-folder.
Change-Id: Icf03356187078ad6a2e56c9870992be3ca4c9655
Signed-off-by: Grzegorz Jaszczyk <jaz@semihalf.com>
Signed-off-by: Marcin Wojtas <mw@semihalf.com>
diff --git a/docs/plat/marvell/armada/porting.rst b/docs/plat/marvell/armada/porting.rst
new file mode 100644
index 0000000..1723ebb
--- /dev/null
+++ b/docs/plat/marvell/armada/porting.rst
@@ -0,0 +1,163 @@
+TF-A Porting Guide for Marvell Platforms
+========================================
+
+This section describes how to port TF-A to a customer board, assuming that the
+SoC being used is already supported in TF-A.
+
+
+Source Code Structure
+---------------------
+
+- The customer platform specific code shall reside under ``plat/marvell/armada/<soc family>/<soc>_cust``
+ (e.g. 'plat/marvell/armada/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.
+
+Files that require porting are located at ``plat/marvell/armada/<soc family>/<soc>_cust`` directory.
+
+
+Armada-70x0/Armada-80x0 Porting
+-------------------------------
+
+SoC Physical Address Map (marvell_plat_config.c)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This file describes the SoC physical memory mapping to be used for the CCU,
+IOWIN, 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, IOWIN, AXI-MBUS & IOB work, please
+ refer to the SoC functional spec, and under
+ ``docs/marvell/misc/mvebu-[ccu/iob/amb/io-win].txt`` files.
+
+boot loader recovery (marvell_plat_config.c)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Background:
+
+ Boot rom 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 boot loader recovery by booting from a valid flash-image
+ saved in next position on flash (e.g. address 2M in SPI flash).
+
+ Supported options to implement the skip request are:
+ - GPIO
+ - I2C
+ - User defined
+
+- Porting:
+
+ Under marvell_plat_config.c, implement struct skip_image that includes
+ specific board parameters.
+
+ .. warning::
+ To disable this feature make sure the struct skip_image is not implemented.
+
+- Example:
+
+In A7040-DB specific implementation
+(``plat/marvell/armada/a8k/a70x0/board/marvell_plat_config.c``), the image skip is
+implemented using GPIO: mpp 33 (SW5).
+
+Before resetting 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 the button connected to the chosen GPIO pin. A
+skip image request message is printed on the screen and boot rom 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 (TF-A).
+
+The DDR driver called mv_ddr is released separately apart from TF-A sources.
+
+The BLE and consequently, the DDR init code is executed at the early stage of
+the boot process.
+
+Each supported platform of the TF-A has its own DDR porting file called
+dram_port.c located at ``atf/plat/marvell/armada/a8k/<platform>/board`` directory.
+
+Please refer to '<path_to_mv_ddr_sources>/doc/porting_guide.txt' for detailed
+porting description.
+
+The build target directory is "build/<platform>/release/ble".
+
+Comphy Porting (phy-porting-layer.h or phy-default-porting-layer.h)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Background:
+ Some of the comphy's parameters value depend on the HW connection between
+ the SoC and the PHY. Every board type has specific HW characteristics like
+ wire length. Due to those differences some comphy parameters vary between
+ board types. Therefore each board type can have its own list of values for
+ all relevant comphy parameters. The PHY porting layer specifies which
+ parameters need to be suited and the board designer should provide relevant
+ values.
+
+ .. seealso::
+ For XFI/SFI comphy type there is procedure "rx_training" which eases
+ process of suiting some of the parameters. Please see *uboot_cmd*
+ section: rx_training.
+
+ The PHY porting layer simplifies updating static values per board type,
+ which are now grouped in one place.
+
+ .. note::
+ The parameters for the same type of comphy may vary even for the same
+ board type, it is because the lanes from comphy-x to some PHY may have
+ different HW characteristic than lanes from comphy-y to the same
+ (multiplexed) or other PHY.
+
+- Porting:
+ The porting layer for PHY was introduced in TF-A. There is one file
+ ``drivers/marvell/comphy/phy-default-porting-layer.h`` which contains the
+ defaults. Those default parameters are used only if there is no appropriate
+ phy-porting-layer.h file under: ``plat/marvell/armada/<soc
+ family>/<platform>/board/phy-porting-layer.h``. If the phy-porting-layer.h
+ exists, the phy-default-porting-layer.h is not going to be included.
+
+ .. warning::
+ Not all comphy types are already reworked to support the PHY porting
+ layer, currently the porting layer is supported for XFI/SFI and SATA
+ comphy types.
+
+ The easiest way to prepare the PHY porting layer for custom board is to copy
+ existing example to a new platform:
+
+ - cp ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/armada/<soc family>/<platform>/board/phy-porting-layer.h"
+ - adjust relevant parameters or
+ - if different comphy index is used for specific feature, move it to proper table entry and then adjust.
+
+ .. note::
+ The final table size with comphy parameters can be different, depending
+ on the CP module count for given SoC type.
+
+- Example:
+ Example porting layer for armada-8040-db is under:
+ ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h``
+
+ .. note::
+ If there is no PHY porting layer for new platform (missing
+ phy-porting-layer.h), the default values are used
+ (drivers/marvell/comphy/phy-default-porting-layer.h) and the user is
+ warned:
+
+ .. warning::
+ "Using default comphy parameters - it may be required to suit them for
+ your board".