blob: c74ff7a57e00bb6fea0fdee563006e4f08c20eed [file] [log] [blame]
Paul Beesley97743022019-07-12 11:37:07 +01001TF-A Build Instructions for Marvell Platforms
2=============================================
3
4This section describes how to compile the Trusted Firmware-A (TF-A) project for Marvell's platforms.
5
6Build Instructions
7------------------
8(1) Set the cross compiler
9
10 .. code:: shell
11
Mark Dykesef3a4562020-01-08 20:37:18 +000012 > export CROSS_COMPILE=/path/to/toolchain/aarch64-linux-gnu-
Paul Beesley97743022019-07-12 11:37:07 +010013
14(2) Set path for FIP images:
15
16Set U-Boot image path (relatively to TF-A root or absolute path)
17
18 .. code:: shell
19
20 > export BL33=path/to/u-boot.bin
21
22For example: if U-Boot project (and its images) is located at ``~/project/u-boot``,
23BL33 should be ``~/project/u-boot/u-boot.bin``
24
25 .. note::
26
27 *u-boot.bin* should be used and not *u-boot-spl.bin*
28
Konstantin Porotchkin23099612020-10-12 18:13:07 +030029Set MSS/SCP image path (mandatory only for A7K/8K/CN913x when MSS_SUPPORT=1)
Paul Beesley97743022019-07-12 11:37:07 +010030
31 .. code:: shell
32
33 > export SCP_BL2=path/to/mrvl_scp_bl2*.img
34
35(3) Armada-37x0 build requires WTP tools installation.
36
37See below in the section "Tools and external components installation".
38Install ARM 32-bit cross compiler, which is required for building WTMI image for CM3
39
40 .. code:: shell
41
42 > sudo apt-get install gcc-arm-linux-gnueabi
43
44(4) Clean previous build residuals (if any)
45
46 .. code:: shell
47
48 > make distclean
49
50(5) Build TF-A
51
52There are several build options:
53
Pali Rohár179b6732021-02-01 12:22:37 +010054- PLAT
55
56 Supported Marvell platforms are:
57
58 - a3700 - A3720 DB, EspressoBin and Turris MOX
59 - a70x0
60 - a70x0_amc - AMC board
61 - a80x0
62 - a80x0_mcbin - MacchiatoBin
63 - a80x0_puzzle - IEI Puzzle-M801
64 - t9130 - CN913x
65
Paul Beesley97743022019-07-12 11:37:07 +010066- DEBUG
67
68 Default is without debug information (=0). in order to enable it use ``DEBUG=1``.
69 Must be disabled when building UART recovery images due to current console driver
70 implementation that is not compatible with Xmodem protocol used for boot image download.
71
72- LOG_LEVEL
73
74 Defines the level of logging which will be purged to the default output port.
75
Pali Rohár8dc46a02020-10-29 17:44:27 +010076 - 0 - LOG_LEVEL_NONE
77 - 10 - LOG_LEVEL_ERROR
78 - 20 - LOG_LEVEL_NOTICE (default for DEBUG=0)
79 - 30 - LOG_LEVEL_WARNING
80 - 40 - LOG_LEVEL_INFO (default for DEBUG=1)
81 - 50 - LOG_LEVEL_VERBOSE
Paul Beesley97743022019-07-12 11:37:07 +010082
83- USE_COHERENT_MEM
84
85 This flag determines whether to include the coherent memory region in the
Pali Rohár8dc46a02020-10-29 17:44:27 +010086 BL memory map or not. Enabled by default.
Paul Beesley97743022019-07-12 11:37:07 +010087
88- LLC_ENABLE
89
90 Flag defining the LLC (L3) cache state. The cache is enabled by default (``LLC_ENABLE=1``).
91
Konstantin Porotchkin2ef36a32019-03-31 16:58:11 +030092- LLC_SRAM
93
Konstantin Porotchkin28503262019-04-15 16:32:59 +030094 Flag enabling the LLC (L3) cache SRAM support. The LLC SRAM is activated and used
95 by Trusted OS (OP-TEE OS, BL32). The TF-A only prepares CCU address translation windows
96 for SRAM address range at BL31 execution stage with window target set to DRAM-0.
97 When Trusted OS activates LLC SRAM, the CCU window target is changed to SRAM.
98 There is no reason to enable this feature if OP-TEE OS built with CFG_WITH_PAGER=n.
99 Only set LLC_SRAM=1 if OP-TEE OS is built with CFG_WITH_PAGER=y.
Konstantin Porotchkin2ef36a32019-03-31 16:58:11 +0300100
Marek Behún19d85782021-01-05 14:01:05 +0100101- CM3_SYSTEM_RESET
102
103 For Armada37x0 only, when ``CM3_SYSTEM_RESET=1``, the Cortex-M3 secure coprocessor will
104 be used for system reset.
105 TF-A will send command 0x0009 with a magic value via the rWTM mailbox interface to the
106 Cortex-M3 secure coprocessor.
107 The firmware running in the coprocessor must either implement this functionality or
108 ignore the 0x0009 command (which is true for the firmware from A3700-utils-marvell
109 repository). If this option is enabled but the firmware does not support this command,
110 an error message will be printed prior trying to reboot via the usual way.
111
112 This option is needed on Turris MOX as a workaround to a HW bug which causes reset to
113 sometime hang the board.
114
Paul Beesley97743022019-07-12 11:37:07 +0100115- MARVELL_SECURE_BOOT
116
117 Build trusted(=1)/non trusted(=0) image, default is non trusted.
118
119- BLE_PATH
120
Konstantin Porotchkinefcc41e2019-02-19 10:40:33 +0200121 Points to BLE (Binary ROM extension) sources folder.
122 Only required for A7K/8K/CN913x builds.
Grzegorz Jaszczyk3039bce2019-11-05 13:14:59 +0100123 The parameter is optional, its default value is ``plat/marvell/armada/a8k/common/ble``.
Paul Beesley97743022019-07-12 11:37:07 +0100124
125- MV_DDR_PATH
126
Konstantin Porotchkinefcc41e2019-02-19 10:40:33 +0200127 For A7K/8K/CN913x, use this parameter to point to mv_ddr driver sources to allow BLE build. For A37x0,
Paul Beesley97743022019-07-12 11:37:07 +0100128 it is used for ddr_tool build.
129
130 Usage example: MV_DDR_PATH=path/to/mv_ddr
131
Konstantin Porotchkinefcc41e2019-02-19 10:40:33 +0200132 The parameter is optional for A7K/8K/CN913x, when this parameter is not set, the mv_ddr
Paul Beesley97743022019-07-12 11:37:07 +0100133 sources are expected to be located at: drivers/marvell/mv_ddr. However, the parameter
134 is necessary for A37x0.
135
136 For the mv_ddr source location, check the section "Tools and external components installation"
137
Pali Rohár88f225a2021-01-26 10:44:07 +0100138 If MV_DDR_PATH source code is a git snapshot then provide path to the full git
139 repository (including .git subdir) because mv_ddr build process calls git commands.
140
Konstantin Porotchkinefcc41e2019-02-19 10:40:33 +0200141- CP_NUM
142
143 Total amount of CPs (South Bridge) connected to AP. When the parameter is omitted,
144 the build uses the default number of CPs, which is a number of embedded CPs inside the
145 package: 1 or 2 depending on the SoC used. The parameter is valid for OcteonTX2 CN913x SoC
146 family (PLAT=t9130), which can have external CPs connected to the MCI ports. Valid
147 values with CP_NUM are in a range of 1 to 3.
148
Paul Beesley97743022019-07-12 11:37:07 +0100149- DDR_TOPOLOGY
150
151 For Armada37x0 only, the DDR topology map index/name, default is 0.
152
153 Supported Options:
Pali Rohár38686c22021-02-01 12:23:31 +0100154 - 0 - DDR3 1CS 512MB (DB-88F3720-DDR3-Modular, EspressoBin V3-V5)
155 - 1 - DDR4 1CS 512MB (DB-88F3720-DDR4-Modular)
156 - 2 - DDR3 2CS 1GB (EspressoBin V3-V5)
157 - 3 - DDR4 2CS 4GB (DB-88F3720-DDR4-Modular)
158 - 4 - DDR3 1CS 1GB (DB-88F3720-DDR3-Modular, EspressoBin V3-V5)
159 - 5 - DDR4 1CS 1GB (EspressoBin V7, EspressoBin-Ultra)
160 - 6 - DDR4 2CS 2GB (EspressoBin V7)
161 - 7 - DDR3 2CS 2GB (EspressoBin V3-V5)
162 - CUST - CUSTOMER BOARD (Customer board settings)
Paul Beesley97743022019-07-12 11:37:07 +0100163
164- CLOCKSPRESET
165
166 For Armada37x0 only, the clock tree configuration preset including CPU and DDR frequency,
167 default is CPU_800_DDR_800.
168
Pali Rohár8dc46a02020-10-29 17:44:27 +0100169 - CPU_600_DDR_600 - CPU at 600 MHz, DDR at 600 MHz
170 - CPU_800_DDR_800 - CPU at 800 MHz, DDR at 800 MHz
171 - CPU_1000_DDR_800 - CPU at 1000 MHz, DDR at 800 MHz
172 - CPU_1200_DDR_750 - CPU at 1200 MHz, DDR at 750 MHz
Paul Beesley97743022019-07-12 11:37:07 +0100173
Pali Rohár35142872021-02-01 12:24:42 +0100174 Look at Armada37x0 chip package marking on board to identify correct CPU frequency.
175 The last line on package marking (next line after the 88F37x0 line) should contain:
176
177 - C080 or I080 - chip with 800 MHz CPU - use ``CLOCKSPRESET=CPU_800_DDR_800``
178 - C100 or I100 - chip with 1000 MHz CPU - use ``CLOCKSPRESET=CPU_1000_DDR_800``
179 - C120 - chip with 1200 MHz CPU - use ``CLOCKSPRESET=CPU_1200_DDR_750``
180
Paul Beesley97743022019-07-12 11:37:07 +0100181- BOOTDEV
182
183 For Armada37x0 only, the flash boot device, default is ``SPINOR``.
184
185 Currently, Armada37x0 only supports ``SPINOR``, ``SPINAND``, ``EMMCNORM`` and ``SATA``:
186
187 - SPINOR - SPI NOR flash boot
188 - SPINAND - SPI NAND flash boot
189 - EMMCNORM - eMMC Download Mode
190
191 Download boot loader or program code from eMMC flash into CM3 or CA53
192 Requires full initialization and command sequence
193
194 - SATA - SATA device boot
195
Pali Rohára0747422021-01-28 13:09:36 +0100196 Image needs to be stored at disk LBA 0 or at disk partition with
197 MBR type 0x4d (ASCII 'M' as in Marvell) or at disk partition with
198 GPT name ``MARVELL BOOT PARTITION``.
199
Paul Beesley97743022019-07-12 11:37:07 +0100200- PARTNUM
201
202 For Armada37x0 only, the boot partition number, default is 0.
203
204 To boot from eMMC, the value should be aligned with the parameter in
205 U-Boot with name of ``CONFIG_SYS_MMC_ENV_PART``, whose value by default is
206 1. For details about CONFIG_SYS_MMC_ENV_PART, please refer to the U-Boot
207 build instructions.
208
209- WTMI_IMG
210
Pali Rohár2da2e6a2021-01-27 18:04:32 +0100211 For Armada37x0 only, the path of the binary can point to an image which
Paul Beesley97743022019-07-12 11:37:07 +0100212 does nothing, an image which supports EFUSE or a customized CM3 firmware
Pali Rohár2da2e6a2021-01-27 18:04:32 +0100213 binary. The default image is ``fuse.bin`` that built from sources in WTP
Paul Beesley97743022019-07-12 11:37:07 +0100214 folder, which is the next option. If the default image is OK, then this
215 option should be skipped.
216
Pali Rohár2da2e6a2021-01-27 18:04:32 +0100217 Please note that this is not a full WTMI image, just a main loop without
218 hardware initialization code. Final WTMI image is built from this WTMI_IMG
219 binary and sys-init code from the WTP directory which sets DDR and CPU
220 clocks according to DDR_TOPOLOGY and CLOCKSPRESET options.
221
Pali Rohár2c6e0a82021-04-08 10:33:04 +0200222 CZ.NIC as part of Turris project released free and open source WTMI
223 application firmware ``wtmi_app.bin`` for all Armada 3720 devices.
224 This firmware includes additional features like access to Hardware
225 Random Number Generator of Armada 3720 SoC which original Marvell's
226 ``fuse.bin`` image does not have.
227
228 CZ.NIC's Armada 3720 Secure Firmware is available at website:
229
230 https://gitlab.nic.cz/turris/mox-boot-builder/
231
Paul Beesley97743022019-07-12 11:37:07 +0100232- WTP
233
Pali Rohár8dc46a02020-10-29 17:44:27 +0100234 For Armada37x0 only, use this parameter to point to wtptools source code
235 directory, which can be found as a3700_utils.zip in the release. Usage
236 example: ``WTP=/path/to/a3700_utils``
Paul Beesley97743022019-07-12 11:37:07 +0100237
Pali Rohár88f225a2021-01-26 10:44:07 +0100238 If WTP source code is a git snapshot then provide path to the full git
239 repository (including .git subdir) because WTP build process calls git commands.
240
Pali Rohár8dc46a02020-10-29 17:44:27 +0100241- CRYPTOPP_PATH
Paul Beesley97743022019-07-12 11:37:07 +0100242
Pali Rohára304cf52021-01-26 10:44:07 +0100243 For Armada37x0 only, use this parameter to point to Crypto++ source code
244 directory. If this option is specified then Crypto++ source code in
245 CRYPTOPP_PATH directory will be automatically compiled. Crypto++ library
246 is required for building WTP image tool. Either CRYPTOPP_PATH or
247 CRYPTOPP_LIBDIR with CRYPTOPP_INCDIR needs to be specified for Armada37x0.
248
249- CRYPTOPP_LIBDIR
250
251 For Armada37x0 only, use this parameter to point to the directory with
252 compiled Crypto++ library. By default it points to the CRYPTOPP_PATH.
253
254- CRYPTOPP_INCDIR
255
256 For Armada37x0 only, use this parameter to point to the directory with
257 header files of Crypto++ library. By default it points to the CRYPTOPP_PATH.
Paul Beesley97743022019-07-12 11:37:07 +0100258
Paul Beesley97743022019-07-12 11:37:07 +0100259
Pali Rohár8dc46a02020-10-29 17:44:27 +0100260For example, in order to build the image in debug mode with log level up to 'notice' level run
Paul Beesley97743022019-07-12 11:37:07 +0100261
Pali Rohár8dc46a02020-10-29 17:44:27 +0100262.. code:: shell
263
264 > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 PLAT=<MARVELL_PLATFORM> mrvl_flash
Paul Beesley97743022019-07-12 11:37:07 +0100265
Pali Rohár8dc46a02020-10-29 17:44:27 +0100266And if we want to build a Armada37x0 image in debug mode with log level up to 'notice' level,
267the image has the preset CPU at 1000 MHz, preset DDR3 at 800 MHz, the DDR topology of DDR4 2CS,
268the image boot from SPI NOR flash partition 0, and the image is non trusted in WTP, the command
269line is as following
Paul Beesley97743022019-07-12 11:37:07 +0100270
Pali Rohár8dc46a02020-10-29 17:44:27 +0100271.. code:: shell
272
273 > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 CLOCKSPRESET=CPU_1000_DDR_800 \
274 MARVELL_SECURE_BOOT=0 DDR_TOPOLOGY=3 BOOTDEV=SPINOR PARTNUM=0 PLAT=a3700 \
275 MV_DDR_PATH=/path/to/mv-ddr-marvell/ WTP=/path/to/A3700-utils-marvell/ \
276 CRYPTOPP_PATH=/path/to/cryptopp/ BL33=/path/to/u-boot.bin \
Pali Rohár9e737b62021-01-26 10:44:07 +0100277 all fip mrvl_bootimage mrvl_flash mrvl_uart
Pali Rohár8dc46a02020-10-29 17:44:27 +0100278
279To build just TF-A without WTMI image (useful for A3720 Turris MOX board), run following command:
280
281.. code:: shell
282
Marek Behún19d85782021-01-05 14:01:05 +0100283 > make USE_COHERENT_MEM=0 PLAT=a3700 CM3_SYSTEM_RESET=1 BL33=/path/to/u-boot.bin \
284 CROSS_COMPILE=aarch64-linux-gnu- mrvl_bootimage
Pali Rohár8dc46a02020-10-29 17:44:27 +0100285
Pali Rohár0c0d2652021-02-01 12:32:36 +0100286Here is full example how to build production release of Marvell firmware image (concatenated
Pali Rohár2c6e0a82021-04-08 10:33:04 +0200287binary of Marvell's A3720 sys-init, CZ.NIC's Armada 3720 Secure Firmware, TF-A and U-Boot) for
288EspressoBin board (PLAT=a3700) with 1GHz CPU (CLOCKSPRESET=CPU_1000_DDR_800) and
2891GB DDR4 RAM (DDR_TOPOLOGY=5):
Luka Kovaciceb498352021-01-14 14:25:15 +0100290
291.. code:: shell
292
Pali Rohár2c6e0a82021-04-08 10:33:04 +0200293 > git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
294 > git clone https://source.denx.de/u-boot/u-boot.git
Pali Rohár0c0d2652021-02-01 12:32:36 +0100295 > git clone https://github.com/weidai11/cryptopp.git
Pali Rohár2c6e0a82021-04-08 10:33:04 +0200296 > git clone https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git
297 > git clone https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git
298 > git clone https://gitlab.nic.cz/turris/mox-boot-builder.git
Pali Rohár0c0d2652021-02-01 12:32:36 +0100299 > make -C u-boot CROSS_COMPILE=aarch64-linux-gnu- mvebu_espressobin-88f3720_defconfig u-boot.bin
Pali Rohár2c6e0a82021-04-08 10:33:04 +0200300 > make -C mox-boot-builder CROSS_CM3=arm-linux-gnueabi- wtmi_app.bin
Pali Rohár0c0d2652021-02-01 12:32:36 +0100301 > make -C trusted-firmware-a CROSS_COMPILE=aarch64-linux-gnu- CROSS_CM3=arm-linux-gnueabi- \
302 USE_COHERENT_MEM=0 PLAT=a3700 CLOCKSPRESET=CPU_1000_DDR_800 DDR_TOPOLOGY=5 \
Pali Rohár2c6e0a82021-04-08 10:33:04 +0200303 MV_DDR_PATH=$PWD/mv-ddr-marvell/ WTP=$PWD/A3700-utils-marvell/ \
304 CRYPTOPP_PATH=$PWD/cryptopp/ BL33=$PWD/u-boot/u-boot.bin \
305 WTMI_IMG=$PWD/mox-boot-builder/wtmi_app.bin FIP_ALIGN=0x100 mrvl_flash
Luka Kovaciceb498352021-01-14 14:25:15 +0100306
Pali Rohár0c0d2652021-02-01 12:32:36 +0100307Produced Marvell firmware flash image: ``trusted-firmware-a/build/a3700/release/flash-image.bin``
Paul Beesley97743022019-07-12 11:37:07 +0100308
309Special Build Flags
310--------------------
311
312- PLAT_RECOVERY_IMAGE_ENABLE
313 When set this option to enable secondary recovery function when build atf.
314 In order to build UART recovery image this operation should be disabled for
Konstantin Porotchkinefcc41e2019-02-19 10:40:33 +0200315 A7K/8K/CN913x because of hardware limitation (boot from secondary image
Paul Beesley97743022019-07-12 11:37:07 +0100316 can interrupt UART recovery process). This MACRO definition is set in
Grzegorz Jaszczyk3039bce2019-11-05 13:14:59 +0100317 ``plat/marvell/armada/a8k/common/include/platform_def.h`` file.
Paul Beesley97743022019-07-12 11:37:07 +0100318
Alex Leiboviched2fb472019-02-25 12:24:29 +0200319- DDR32
320 In order to work in 32bit DDR, instead of the default 64bit ECC DDR,
321 this flag should be set to 1.
322
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100323For more information about build options, please refer to the
324:ref:`Build Options` document.
Paul Beesley97743022019-07-12 11:37:07 +0100325
326
327Build output
328------------
Pali Rohár8dc46a02020-10-29 17:44:27 +0100329Marvell's TF-A compilation generates 8 files:
Paul Beesley97743022019-07-12 11:37:07 +0100330
Pali Roháre4bfc0a2021-02-01 12:25:46 +0100331 - ble.bin - BLe image (not available for Armada37x0)
Paul Beesley97743022019-07-12 11:37:07 +0100332 - bl1.bin - BL1 image
333 - bl2.bin - BL2 image
334 - bl31.bin - BL31 image
335 - fip.bin - FIP image (contains BL2, BL31 & BL33 (U-Boot) images)
336 - boot-image.bin - TF-A image (contains BL1 and FIP images)
Pali Roháre4bfc0a2021-02-01 12:25:46 +0100337 - flash-image.bin - Flashable Marvell firmware image. For Armada37x0 it
338 contains TIM, WTMI and boot-image.bin images. For other platforms it contains
339 BLe and boot-image.bin images. Should be placed on the boot flash/device.
Pali Rohár8dc46a02020-10-29 17:44:27 +0100340 - uart-images.tgz.bin - GZIPed TAR archive which contains Armada37x0 images
341 for booting via UART. Could be loaded via Marvell's WtpDownload tool from
342 A3700-utils-marvell repository.
Paul Beesley97743022019-07-12 11:37:07 +0100343
Pali Rohár9e737b62021-01-26 10:44:07 +0100344Additional make target ``mrvl_bootimage`` produce ``boot-image.bin`` file. Target
345``mrvl_flash`` produce final ``flash-image.bin`` file and target ``mrvl_uart``
346produce ``uart-images.tgz.bin`` file.
Pali Rohár8dc46a02020-10-29 17:44:27 +0100347
Paul Beesley97743022019-07-12 11:37:07 +0100348
349Tools and external components installation
350------------------------------------------
351
352Armada37x0 Builds require installation of 3 components
353~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
354
355(1) ARM cross compiler capable of building images for the service CPU (CM3).
356 This component is usually included in the Linux host packages.
357 On Debian/Ubuntu hosts the default GNU ARM tool chain can be installed
358 using the following command
359
360 .. code:: shell
361
362 > sudo apt-get install gcc-arm-linux-gnueabi
363
364 Only if required, the default tool chain prefix ``arm-linux-gnueabi-`` can be
365 overwritten using the environment variable ``CROSS_CM3``.
366 Example for BASH shell
367
368 .. code:: shell
369
370 > export CROSS_CM3=/opt/arm-cross/bin/arm-linux-gnueabi
371
372(2) DDR initialization library sources (mv_ddr) available at the following repository
Pali Roháreaeb5272021-01-26 10:44:07 +0100373 (use the "master" branch):
Paul Beesley97743022019-07-12 11:37:07 +0100374
375 https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git
376
Pali Rohár65c8d112020-10-07 11:01:00 +0200377(3) Armada3700 tools available at the following repository
Pali Roháreaeb5272021-01-26 10:44:07 +0100378 (use the "master" branch):
Paul Beesley97743022019-07-12 11:37:07 +0100379
380 https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git
381
Pali Rohár8dc46a02020-10-29 17:44:27 +0100382(4) Crypto++ library available at the following repository:
383
384 https://github.com/weidai11/cryptopp.git
385
Paul Beesley97743022019-07-12 11:37:07 +0100386Armada70x0 and Armada80x0 Builds require installation of an additional component
387~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
388
389(1) DDR initialization library sources (mv_ddr) available at the following repository
Pali Roháreaeb5272021-01-26 10:44:07 +0100390 (use the "master" branch):
Paul Beesley97743022019-07-12 11:37:07 +0100391
392 https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git