blob: 1723ebb5778bdd1115b8f8cb102365d9edd859c2 [file] [log] [blame]
Paul Beesley97743022019-07-12 11:37:07 +01001TF-A Porting Guide for Marvell Platforms
2========================================
3
4This section describes how to port TF-A to a customer board, assuming that the
5SoC being used is already supported in TF-A.
6
7
8Source Code Structure
9---------------------
10
Grzegorz Jaszczyk3039bce2019-11-05 13:14:59 +010011- 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 Beesley97743022019-07-12 11:37:07 +010013- 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 Jaszczyk3039bce2019-11-05 13:14:59 +010017Files that require porting are located at ``plat/marvell/armada/<soc family>/<soc>_cust`` directory.
Paul Beesley97743022019-07-12 11:37:07 +010018
19
20Armada-70x0/Armada-80x0 Porting
21-------------------------------
22
23SoC Physical Address Map (marvell_plat_config.c)
24~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
25
26This file describes the SoC physical memory mapping to be used for the CCU,
27IOWIN, AXI-MBUS and IOB address decode units (Refer to the functional spec for
28more details).
29
30In most cases, using the default address decode windows should work OK.
31
32In cases where a special physical address map is needed (e.g. Special size for
33PCIe MEM windows, large memory mapped SPI flash...), then porting of the SoC
34memory 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
41boot 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
66In A7040-DB specific implementation
Grzegorz Jaszczyk3039bce2019-11-05 13:14:59 +010067(``plat/marvell/armada/a8k/a70x0/board/marvell_plat_config.c``), the image skip is
Paul Beesley97743022019-07-12 11:37:07 +010068implemented using GPIO: mpp 33 (SW5).
69
70Before resetting the board make sure there is a valid image on the next flash
71address:
72
73 -tftp [valid address] flash-image.bin
74 -sf update [valid address] 0x2000000 [size]
75
76Press reset and keep pressing the button connected to the chosen GPIO pin. A
77skip image request message is printed on the screen and boot rom boots from the
78saved image at the next position.
79
80DDR Porting (dram_port.c)
81~~~~~~~~~~~~~~~~~~~~~~~~~
82
83This file defines the dram topology and parameters of the target board.
84
85The DDR code is part of the BLE component, which is an extension of ARM Trusted
86Firmware (TF-A).
87
88The DDR driver called mv_ddr is released separately apart from TF-A sources.
89
90The BLE and consequently, the DDR init code is executed at the early stage of
91the boot process.
92
93Each supported platform of the TF-A has its own DDR porting file called
Grzegorz Jaszczyk3039bce2019-11-05 13:14:59 +010094dram_port.c located at ``atf/plat/marvell/armada/a8k/<platform>/board`` directory.
Paul Beesley97743022019-07-12 11:37:07 +010095
96Please refer to '<path_to_mv_ddr_sources>/doc/porting_guide.txt' for detailed
97porting description.
98
99The build target directory is "build/<platform>/release/ble".
100
101Comphy 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 Beesleyf2ec7142019-10-04 16:17:46 +0000115 process of suiting some of the parameters. Please see *uboot_cmd*
Paul Beesley97743022019-07-12 11:37:07 +0100116 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 Jaszczyk3039bce2019-11-05 13:14:59 +0100131 phy-porting-layer.h file under: ``plat/marvell/armada/<soc
Paul Beesley97743022019-07-12 11:37:07 +0100132 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 Jaszczyk3039bce2019-11-05 13:14:59 +0100143 - cp ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/armada/<soc family>/<platform>/board/phy-porting-layer.h"
Paul Beesley97743022019-07-12 11:37:07 +0100144 - 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 Jaszczyk3039bce2019-11-05 13:14:59 +0100153 ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h``
Paul Beesley97743022019-07-12 11:37:07 +0100154
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".