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/build.rst b/docs/plat/marvell/armada/build.rst
new file mode 100644
index 0000000..1b60fc5
--- /dev/null
+++ b/docs/plat/marvell/armada/build.rst
@@ -0,0 +1,253 @@
+TF-A Build Instructions for Marvell Platforms
+=============================================
+
+This section describes how to compile the Trusted Firmware-A (TF-A) project for Marvell's platforms.
+
+Build Instructions
+------------------
+(1) Set the cross compiler
+
+ .. code:: shell
+
+ > export CROSS_COMPILE=/path/to/toolchain/aarch64-linux-gnu-
+
+(2) Set path for FIP images:
+
+Set U-Boot image path (relatively to TF-A root or absolute path)
+
+ .. code:: shell
+
+ > 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 (mandatory only for Armada80x0)
+
+ .. code:: shell
+
+ > export SCP_BL2=path/to/mrvl_scp_bl2*.img
+
+(3) Armada-37x0 build requires WTP tools installation.
+
+See below in the section "Tools and external components installation".
+Install ARM 32-bit cross compiler, which is required for building WTMI image for CM3
+
+ .. code:: shell
+
+ > sudo apt-get install gcc-arm-linux-gnueabi
+
+(4) Clean previous build residuals (if any)
+
+ .. code:: shell
+
+ > make distclean
+
+(5) Build TF-A
+
+There are several build options:
+
+- DEBUG
+
+ Default is without debug information (=0). in order to enable it use ``DEBUG=1``.
+ Must be disabled when building UART recovery images due to current console driver
+ implementation that is not compatible with Xmodem protocol used for boot image download.
+
+- LOG_LEVEL
+
+ Defines the level of logging which will be purged to the default output port.
+
+ LOG_LEVEL_NONE 0
+ LOG_LEVEL_ERROR 10
+ LOG_LEVEL_NOTICE 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.
+
+- LLC_ENABLE
+
+ Flag defining the LLC (L3) cache state. The cache is enabled by default (``LLC_ENABLE=1``).
+
+- MARVELL_SECURE_BOOT
+
+ Build trusted(=1)/non trusted(=0) image, default is non trusted.
+
+- BLE_PATH
+
+ Points to BLE (Binary ROM extension) sources folder. Only required for A8K builds.
+ The parameter is optional, its default value is ``plat/marvell/armada/a8k/common/ble``.
+
+- MV_DDR_PATH
+
+ For A7/8K, use this parameter to point to mv_ddr driver sources to allow BLE build. For A37x0,
+ it is used for ddr_tool build.
+
+ Usage example: MV_DDR_PATH=path/to/mv_ddr
+
+ The parameter is optional for A7/8K, when this parameter is not set, the mv_ddr
+ sources are expected to be located at: drivers/marvell/mv_ddr. However, the parameter
+ is necessary for A37x0.
+
+ For the mv_ddr source location, check the section "Tools and external components installation"
+
+- DDR_TOPOLOGY
+
+ For Armada37x0 only, the DDR topology map index/name, 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 V3-V5 (1GB)
+ - DDR4 2CS (3): DB-88F3720-DDR4-Modular (4GB)
+ - DDR3 1CS (4): DB-88F3720-DDR3-Modular (1GB)
+ - DDR4 1CS (5): EspressoBin V7 (1GB)
+ - DDR4 2CS (6): EspressoBin V7 (2GB)
+ - CUSTOMER (CUST): Customer board, DDR3 1CS 512MB
+
+- 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
+ - CPU_1200_DDR_750 - CPU at 1200 MHz, DDR at 750 MHz
+
+- BOOTDEV
+
+ For Armada37x0 only, the flash boot device, default is ``SPINOR``.
+
+ Currently, 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 details about CONFIG_SYS_MMC_ENV_PART, please refer to the U-Boot
+ build instructions.
+
+- WTMI_IMG
+
+ For Armada37x0 only, the path of the WTMI image can point to an image which
+ does nothing, an image which supports EFUSE or a customized CM3 firmware
+ binary. The default image is wtmi.bin that built from sources in WTP
+ folder, which is the next option. If the default image is OK, then this
+ option should be skipped.
+
+- WTP
+
+ For Armada37x0 only, use this parameter to point to wtptools source code
+ directory, which can be found as a3700_utils.zip in the release. Usage
+ example: ``WTP=/path/to/a3700_utils``
+
+ For example, in order to build the image in debug mode with log level up to 'notice' level run
+
+ .. code:: shell
+
+ > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 PLAT=<MARVELL_PLATFORM> all fip
+
+ And if we want to build a Armada37x0 image in debug mode with log level up to 'notice' level,
+ the image has the preset CPU at 1000 MHz, preset DDR3 at 800 MHz, the DDR topology of DDR4 2CS,
+ the image boot from SPI NOR flash partition 0, and the image is non trusted in WTP, the command
+ line is as following
+
+ .. code:: shell
+
+ > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 CLOCKSPRESET=CPU_1000_DDR_800 \
+ MARVELL_SECURE_BOOT=0 DDR_TOPOLOGY=3 BOOTDEV=SPINOR PARTNUM=0 PLAT=a3700 all fip
+
+ Supported MARVELL_PLATFORM are:
+ - a3700 (for both A3720 DB and EspressoBin)
+ - a70x0
+ - a70x0_amc (for AMC board)
+ - a80x0
+ - a80x0_mcbin (for MacciatoBin)
+
+Special Build Flags
+--------------------
+
+- PLAT_RECOVERY_IMAGE_ENABLE
+ When set this option to enable secondary recovery function when build atf.
+ In order to build UART recovery image this operation should be disabled for
+ a70x0 and a80x0 because of hardware limitation (boot from secondary image
+ can interrupt UART recovery process). This MACRO definition is set in
+ ``plat/marvell/armada/a8k/common/include/platform_def.h`` file.
+
+For more information about build options, please refer to the
+:ref:`Build Options` document.
+
+
+Build output
+------------
+Marvell's TF-A 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 - TF-A 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 and external components installation
+------------------------------------------
+
+Armada37x0 Builds require installation of 3 components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(1) ARM cross compiler capable of building images for the service CPU (CM3).
+ This component is usually included in the Linux host packages.
+ On Debian/Ubuntu hosts the default GNU ARM tool chain can be installed
+ using the following command
+
+ .. code:: shell
+
+ > sudo apt-get install gcc-arm-linux-gnueabi
+
+ Only if required, the default tool chain prefix ``arm-linux-gnueabi-`` can be
+ overwritten using the environment variable ``CROSS_CM3``.
+ Example for BASH shell
+
+ .. code:: shell
+
+ > export CROSS_CM3=/opt/arm-cross/bin/arm-linux-gnueabi
+
+(2) DDR initialization library sources (mv_ddr) available at the following repository
+ (use the "mv_ddr-armada-atf-mainline" branch):
+
+ https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git
+
+(3) Armada3700 tools available at the following repository (use the latest release branch):
+
+ https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git
+
+Armada70x0 and Armada80x0 Builds require installation of an additional component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(1) DDR initialization library sources (mv_ddr) available at the following repository
+ (use the "mv_ddr-armada-atf-mainline" branch):
+
+ https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git
diff --git a/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst b/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst
new file mode 100644
index 0000000..e88a458
--- /dev/null
+++ b/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst
@@ -0,0 +1,49 @@
+Address decoding flow and address translation units of Marvell Armada 8K SoC family
+===================================================================================
+
+::
+
+ +--------------------------------------------------------------------------------------------------+
+ | +-------------+ +--------------+ |
+ | | Memory +----- DRAM CS | |
+ |+------------+ +-----------+ +-----------+ | Controller | +--------------+ |
+ || AP DMA | | | | | +-------------+ |
+ || SD/eMMC | | CA72 CPUs | | AP MSS | +-------------+ |
+ || MCI-0/1 | | | | | | Memory | |
+ |+------+-----+ +--+--------+ +--------+--+ +------------+ | Controller | +-------------+ |
+ | | | | | +----- Translaton | |AP | |
+ | | | | | | +-------------+ |Configuration| |
+ | | | +-----+ +-------------------------Space | |
+ | | | +-------------+ | CCU | +-------------+ |
+ | | | | MMU +---------+ Windows | +-----------+ +-------------+ |
+ | | +-| translation | | Lookup +---- +--------- AP SPI | |
+ | | +-------------+ | | | | +-------------+ |
+ | | +-------------+ | | | IO | +-------------+ |
+ | +------------| SMMU +---------+ | | Windows +--------- AP MCI0/1 | |
+ | | translation | +------------+ | Lookup | +-------------+ |
+ | +---------+---+ | | +-------------+ |
+ | - | | +--------- AP STM | |
+ | +----------------- | | +-------------+ |
+ | AP | | +-+---------+ |
+ +---------------------------------------------------------------|----------------------------------+
+ +-------------|-------------------------------------------------|----------------------------------+
+ | CP | +-------------+ +------+-----+ +-------------------+ |
+ | | | | | +------- SB CFG Space | |
+ | | | DIOB | | | +-------------------+ |
+ | | | Windows ----------------- IOB | +-------------------+ |
+ | | | Control | | Windows +------| SB PCIe-0 - PCIe2 | |
+ | | | | | Lookup | +-------------------+ |
+ | | +------+------+ | | +-------------------+ |
+ | | | | +------+ SB NAND | |
+ | | | +------+-----+ +-------------------+ |
+ | | | | |
+ | | | | |
+ | +------------------+ +------------+ +------+-----+ +-------------------+ |
+ | | Network Engine | | | | +------- SB SPI-0/SPI-1 | |
+ | | Security Engine | | PCIe, MSS | | RUNIT | +-------------------+ |
+ | | SATA, USB | | DMA | | Windows | +-------------------+ |
+ | | SD/eMMC | | | | Lookup +------- SB Device Bus | |
+ | | TDM, I2C | | | | | +-------------------+ |
+ | +------------------+ +------------+ +------------+ |
+ | |
+ +--------------------------------------------------------------------------------------------------+
diff --git a/docs/plat/marvell/armada/misc/mvebu-amb.rst b/docs/plat/marvell/armada/misc/mvebu-amb.rst
new file mode 100644
index 0000000..d734003
--- /dev/null
+++ b/docs/plat/marvell/armada/misc/mvebu-amb.rst
@@ -0,0 +1,58 @@
+AMB - AXI MBUS address decoding
+===============================
+
+AXI to M-bridge decoding unit driver for Marvell Armada 8K and 8K+ SoCs.
+
+The Runit offers a second level of address windows lookup. It is used to map
+transaction towards the CD BootROM, SPI0, SPI1 and Device bus (NOR).
+
+The Runit contains eight configurable windows. Each window defines a contiguous,
+address space and the properties associated with that address space.
+
+::
+
+ Unit Bank ATTR
+ Device-Bus DEV_BOOT_CS 0x2F
+ DEV_CS0 0x3E
+ DEV_CS1 0x3D
+ DEV_CS2 0x3B
+ DEV_CS3 0x37
+ SPI-0 SPI_A_CS0 0x1E
+ SPI_A_CS1 0x5E
+ SPI_A_CS2 0x9E
+ SPI_A_CS3 0xDE
+ SPI_A_CS4 0x1F
+ SPI_A_CS5 0x5F
+ SPI_A_CS6 0x9F
+ SPI_A_CS7 0xDF
+ SPI SPI_B_CS0 0x1A
+ SPI_B_CS1 0x5A
+ SPI_B_CS2 0x9A
+ SPI_B_CS3 0xDA
+ BOOT_ROM BOOT_ROM 0x1D
+ UART UART 0x01
+
+Mandatory functions
+-------------------
+
+- marvell_get_amb_memory_map
+ Returns the AMB windows configuration and the number of windows
+
+Mandatory structures
+--------------------
+
+- amb_memory_map
+ Array that include the configuration of the windows. Every window/entry is a
+ struct which has 2 parameters:
+
+ - Base address of the window
+ - Attribute of the window
+
+Examples
+--------
+
+.. code:: c
+
+ struct addr_map_win amb_memory_map[] = {
+ {0xf900, AMB_DEV_CS0_ID},
+ };
diff --git a/docs/plat/marvell/armada/misc/mvebu-ccu.rst b/docs/plat/marvell/armada/misc/mvebu-ccu.rst
new file mode 100644
index 0000000..5bac11f
--- /dev/null
+++ b/docs/plat/marvell/armada/misc/mvebu-ccu.rst
@@ -0,0 +1,33 @@
+Marvell CCU address decoding bindings
+=====================================
+
+CCU configration driver (1st stage address translation) for Marvell Armada 8K and 8K+ SoCs.
+
+The CCU node includes a description of the address decoding configuration.
+
+Mandatory functions
+-------------------
+
+- marvell_get_ccu_memory_map
+ Return the CCU windows configuration and the number of windows of the
+ specific AP.
+
+Mandatory structures
+--------------------
+
+- ccu_memory_map
+ Array that includes the configuration of the windows. Every window/entry is
+ a struct which has 3 parameters:
+
+ - Base address of the window
+ - Size of the window
+ - Target-ID of the window
+
+Example
+-------
+
+.. code:: c
+
+ struct addr_map_win ccu_memory_map[] = {
+ {0x00000000f2000000, 0x00000000e000000, IO_0_TID}, /* IO window */
+ };
diff --git a/docs/plat/marvell/armada/misc/mvebu-io-win.rst b/docs/plat/marvell/armada/misc/mvebu-io-win.rst
new file mode 100644
index 0000000..52845ca
--- /dev/null
+++ b/docs/plat/marvell/armada/misc/mvebu-io-win.rst
@@ -0,0 +1,46 @@
+Marvell IO WIN address decoding bindings
+========================================
+
+IO Window configration driver (2nd stage address translation) for Marvell Armada 8K and 8K+ SoCs.
+
+The IO WIN includes a description of the address decoding configuration.
+
+Transactions that are decoded by CCU windows as IO peripheral, have an additional
+layer of decoding. This additional address decoding layer defines one of the
+following targets:
+
+- **0x0** = BootRom
+- **0x1** = STM (Serial Trace Macro-cell, a programmer's port into trace stream)
+- **0x2** = SPI direct access
+- **0x3** = PCIe registers
+- **0x4** = MCI Port
+- **0x5** = PCIe port
+
+Mandatory functions
+-------------------
+
+- marvell_get_io_win_memory_map
+ Returns the IO windows configuration and the number of windows of the
+ specific AP.
+
+Mandatory structures
+--------------------
+
+- io_win_memory_map
+ Array that include the configuration of the windows. Every window/entry is
+ a struct which has 3 parameters:
+
+ - Base address of the window
+ - Size of the window
+ - Target-ID of the window
+
+Example
+-------
+
+.. code:: c
+
+ struct addr_map_win io_win_memory_map[] = {
+ {0x00000000fe000000, 0x000000001f00000, PCIE_PORT_TID}, /* PCIe window 31Mb for PCIe port*/
+ {0x00000000ffe00000, 0x000000000100000, PCIE_REGS_TID}, /* PCI-REG window 64Kb for PCIe-reg*/
+ {0x00000000f6000000, 0x000000000100000, MCIPHY_TID}, /* MCI window 1Mb for PHY-reg*/
+ };
diff --git a/docs/plat/marvell/armada/misc/mvebu-iob.rst b/docs/plat/marvell/armada/misc/mvebu-iob.rst
new file mode 100644
index 0000000..d02a7e8
--- /dev/null
+++ b/docs/plat/marvell/armada/misc/mvebu-iob.rst
@@ -0,0 +1,52 @@
+Marvell IOB address decoding bindings
+=====================================
+
+IO bridge configration driver (3rd stage address translation) for Marvell Armada 8K and 8K+ SoCs.
+
+The IOB includes a description of the address decoding configuration.
+
+IOB supports up to n (in CP110 n=24) windows for external memory transaction.
+When a transaction passes through the IOB, its address is compared to each of
+the enabled windows. If there is a hit and it passes the security checks, it is
+advanced to the target port.
+
+Mandatory functions
+-------------------
+
+- marvell_get_iob_memory_map
+ Returns the IOB windows configuration and the number of windows
+
+Mandatory structures
+--------------------
+
+- iob_memory_map
+ Array that includes the configuration of the windows. Every window/entry is
+ a struct which has 3 parameters:
+
+ - Base address of the window
+ - Size of the window
+ - Target-ID of the window
+
+Target ID options
+-----------------
+
+- **0x0** = Internal configuration space
+- **0x1** = MCI0
+- **0x2** = PEX1_X1
+- **0x3** = PEX2_X1
+- **0x4** = PEX0_X4
+- **0x5** = NAND flash
+- **0x6** = RUNIT (NOR/SPI/BootRoom)
+- **0x7** = MCI1
+
+Example
+-------
+
+.. code:: c
+
+ struct addr_map_win iob_memory_map[] = {
+ {0x00000000f7000000, 0x0000000001000000, PEX1_TID}, /* PEX1_X1 window */
+ {0x00000000f8000000, 0x0000000001000000, PEX2_TID}, /* PEX2_X1 window */
+ {0x00000000f6000000, 0x0000000001000000, PEX0_TID}, /* PEX0_X4 window */
+ {0x00000000f9000000, 0x0000000001000000, NAND_TID} /* NAND window */
+ };
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".