mvebu: cp110: introduce COMPHY porting layer

Some of COMPHY parameters depends on the hw connection between the SoC
and the PHY, which can vary on different boards e.g. due to different
wires length. Define the "porting layer" with some defaults
parameters. It ease updating static values which needs to be updated due
to board differences, which are now grouped in one place.

Example porting layer for a8k-db is under:
plat/marvell/a8k/a80x0/board/phy-porting-layer.h

If for some boards parameters are not defined (missing
phy-porting-layer.h), the default values are used
(drivers/marvell/comphy/phy-default-porting-layer.h)
and the following compilation warning is show:
"Using default comphy params - you may need to suit them to your board".

The common COMPHY driver code is extracted in order to be shared with
future COMPHY driver for A3700 SoC platforms

Signed-off-by: Grzegorz Jaszczyk <jaz@semihalf.com>
Signed-off-by: Igal Liberman <igall@marvell.com>
Signed-off-by: Konstantin Porotchkin <kostap@marvell.com>

1 files changed, 52 insertions, 0 deletions

diff --git a/docs/marvell/porting.txt b/docs/marvell/porting.txt
index 78000e912..f9a39a054 100644
--- a/docs/marvell/porting.txt
+++ b/docs/marvell/porting.txt
@@ -1,3 +1,5 @@
+.. _porting:
+
 TF-A Porting Guide
 =================
 
@@ -64,3 +66,53 @@ Armada-70x0/Armada-80x0 Porting
 	- 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 :ref:`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/<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/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/<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/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".