1TF-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 12 > export CROSS_COMPILE=/path/to/toolchain/aarch64-linux-gnu- 13 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 29Set MSS/SCP image path (mandatory only for A7K/A8K/CN913x when MSS_SUPPORT=1) 30 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 54- PLAT 55 56 Supported Marvell platforms are: 57 58 - a3700 - A3720 DB, EspressoBin and Turris MOX 59 - a70x0 60 - a70x0_amc - AMC board 61 - a70x0_mochabin - Globalscale MOCHAbin 62 - a80x0 63 - a80x0_mcbin - MacchiatoBin 64 - a80x0_puzzle - IEI Puzzle-M801 65 - t9130 - CN913x 66 - t9130_cex7_eval - CN913x CEx7 Evaluation Board 67 68- DEBUG 69 70 Default is without debug information (=0). in order to enable it use ``DEBUG=1``. 71 Can be enabled also when building UART recovery images, there is no issue with it. 72 73 Production TF-A images should be built without this debug option! 74 75- LOG_LEVEL 76 77 Defines the level of logging which will be purged to the default output port. 78 79 - 0 - LOG_LEVEL_NONE 80 - 10 - LOG_LEVEL_ERROR 81 - 20 - LOG_LEVEL_NOTICE (default for DEBUG=0) 82 - 30 - LOG_LEVEL_WARNING 83 - 40 - LOG_LEVEL_INFO (default for DEBUG=1) 84 - 50 - LOG_LEVEL_VERBOSE 85 86- USE_COHERENT_MEM 87 88 This flag determines whether to include the coherent memory region in the 89 BL memory map or not. Enabled by default. 90 91- LLC_ENABLE 92 93 Flag defining the LLC (L3) cache state. The cache is enabled by default (``LLC_ENABLE=1``). 94 95- LLC_SRAM 96 97 Flag enabling the LLC (L3) cache SRAM support. The LLC SRAM is activated and used 98 by Trusted OS (OP-TEE OS, BL32). The TF-A only prepares CCU address translation windows 99 for SRAM address range at BL31 execution stage with window target set to DRAM-0. 100 When Trusted OS activates LLC SRAM, the CCU window target is changed to SRAM. 101 There is no reason to enable this feature if OP-TEE OS built with CFG_WITH_PAGER=n. 102 Only set LLC_SRAM=1 if OP-TEE OS is built with CFG_WITH_PAGER=y. 103 104- MARVELL_SECURE_BOOT 105 106 Build trusted(=1)/non trusted(=0) image, default is non trusted. 107 This parameter is used only for ``mrvl_flash`` and ``mrvl_uart`` targets. 108 109- MV_DDR_PATH 110 111 This parameter is required for ``mrvl_flash`` and ``mrvl_uart`` targets. 112 For A7K/A8K/CN913x it is used for BLE build and for Armada37x0 it used 113 for ddr_tool build. 114 115 Specify path to the full checkout of Marvell mv-ddr-marvell git 116 repository. Checkout must contain also .git subdirectory because 117 mv-ddr build process calls git commands. 118 119 Do not remove any parts of git checkout becuase build process and other 120 applications need them for correct building and version determination. 121 122 123CN913x specific build options: 124 125- CP_NUM 126 127 Total amount of CPs (South Bridge) connected to AP. When the parameter is omitted, 128 the build uses the default number of CPs, which is a number of embedded CPs inside the 129 package: 1 or 2 depending on the SoC used. The parameter is valid for OcteonTX2 CN913x SoC 130 family (PLAT=t9130), which can have external CPs connected to the MCI ports. Valid 131 values with CP_NUM are in a range of 1 to 3. 132 133 134A7K/A8K/CN913x specific build options: 135 136- BLE_PATH 137 138 Points to BLE (Binary ROM extension) sources folder. 139 The parameter is optional, its default value is ``plat/marvell/armada/a8k/common/ble`` 140 which uses TF-A in-tree BLE implementation. 141 142- MSS_SUPPORT 143 144 When ``MSS_SUPPORT=1``, then TF-A includes support for Management SubSystem (MSS). 145 When enabled it is required to specify path to the MSS firmware image via ``SCP_BL2`` 146 option. 147 148 This option is by default enabled. 149 150- SCP_BL2 151 152 Specify path to the MSS fimware image binary which will run on Cortex-M3 coprocessor. 153 It is available in Marvell binaries-marvell git repository. Required when ``MSS_SUPPORT=1``. 154 155Globalscale MOCHAbin specific build options: 156 157- DDR_TOPOLOGY 158 159 The DDR topology map index/name, default is 0. 160 161 Supported Options: 162 - 0 - DDR4 1CS 2GB 163 - 1 - DDR4 1CS 4GB 164 - 2 - DDR4 2CS 8GB 165 166Armada37x0 specific build options: 167 168- HANDLE_EA_EL3_FIRST_NS 169 170 When ``HANDLE_EA_EL3_FIRST_NS=1``, External Aborts and SError Interrupts, resulting from errors 171 in NS world, will be always trapped in TF-A. TF-A in this case enables dirty hack / workaround for 172 a bug found in U-Boot and Linux kernel PCIe controller driver pci-aardvark.c, traps and then masks 173 SError interrupt caused by AXI SLVERR on external access (syndrome 0xbf000002). 174 175 Otherwise when ``HANDLE_EA_EL3_FIRST_NS=0``, these exceptions will be trapped in the current 176 exception level (or in EL1 if the current exception level is EL0). So exceptions caused by 177 U-Boot will be trapped in U-Boot, exceptions caused by Linux kernel (or user applications) 178 will be trapped in Linux kernel. 179 180 Mentioned bug in pci-aardvark.c driver is fixed in U-Boot version v2021.07 and Linux kernel 181 version v5.13 (workarounded since Linux kernel version 5.9) and also backported in Linux 182 kernel stable releases since versions v5.12.13, v5.10.46, v5.4.128, v4.19.198, v4.14.240. 183 184 If target system has already patched version of U-Boot and Linux kernel then it is strongly 185 recommended to not enable this workaround as it disallows propagating of all External Aborts 186 to running Linux kernel and makes correctable errors as fatal aborts. 187 188 This option is now disabled by default. In past this option has different name "HANDLE_EA_EL3_FIRST" and 189 was enabled by default in TF-A versions v2.2, v2.3, v2.4 and v2.5. 190 191- CM3_SYSTEM_RESET 192 193 When ``CM3_SYSTEM_RESET=1``, the Cortex-M3 secure coprocessor will be used for system reset. 194 195 TF-A will send command 0x0009 with a magic value via the rWTM mailbox interface to the 196 Cortex-M3 secure coprocessor. 197 The firmware running in the coprocessor must either implement this functionality or 198 ignore the 0x0009 command (which is true for the firmware from A3700-utils-marvell 199 repository). If this option is enabled but the firmware does not support this command, 200 an error message will be printed prior trying to reboot via the usual way. 201 202 This option is needed on Turris MOX as a workaround to a HW bug which causes reset to 203 sometime hang the board. 204 205- A3720_DB_PM_WAKEUP_SRC 206 207 For Armada 3720 Development Board only, when ``A3720_DB_PM_WAKEUP_SRC=1``, 208 TF-A will setup PM wake up src configuration. This option is disabled by default. 209 210 211Armada37x0 specific build options for ``mrvl_flash`` and ``mrvl_uart`` targets: 212 213- DDR_TOPOLOGY 214 215 The DDR topology map index/name, default is 0. 216 217 Supported Options: 218 - 0 - DDR3 1CS 512MB (DB-88F3720-DDR3-Modular, EspressoBin V3-V5) 219 - 1 - DDR4 1CS 512MB (DB-88F3720-DDR4-Modular) 220 - 2 - DDR3 2CS 1GB (EspressoBin V3-V5) 221 - 3 - DDR4 2CS 4GB (DB-88F3720-DDR4-Modular) 222 - 4 - DDR3 1CS 1GB (DB-88F3720-DDR3-Modular, EspressoBin V3-V5) 223 - 5 - DDR4 1CS 1GB (EspressoBin V7, EspressoBin-Ultra) 224 - 6 - DDR4 2CS 2GB (EspressoBin V7) 225 - 7 - DDR3 2CS 2GB (EspressoBin V3-V5) 226 - CUST - CUSTOMER BOARD (Customer board settings) 227 228- CLOCKSPRESET 229 230 The clock tree configuration preset including CPU and DDR frequency, 231 default is CPU_800_DDR_800. 232 233 - CPU_600_DDR_600 - CPU at 600 MHz, DDR at 600 MHz 234 - CPU_800_DDR_800 - CPU at 800 MHz, DDR at 800 MHz 235 - CPU_1000_DDR_800 - CPU at 1000 MHz, DDR at 800 MHz 236 - CPU_1200_DDR_750 - CPU at 1200 MHz, DDR at 750 MHz 237 238 Look at Armada37x0 chip package marking on board to identify correct CPU frequency. 239 The last line on package marking (next line after the 88F37x0 line) should contain: 240 241 - C080 or I080 - chip with 800 MHz CPU - use ``CLOCKSPRESET=CPU_800_DDR_800`` 242 - C100 or I100 - chip with 1000 MHz CPU - use ``CLOCKSPRESET=CPU_1000_DDR_800`` 243 - C120 - chip with 1200 MHz CPU - use ``CLOCKSPRESET=CPU_1200_DDR_750`` 244 245- BOOTDEV 246 247 The flash boot device, default is ``SPINOR``. 248 249 Currently, Armada37x0 only supports ``SPINOR``, ``SPINAND``, ``EMMCNORM`` and ``SATA``: 250 251 - SPINOR - SPI NOR flash boot 252 - SPINAND - SPI NAND flash boot 253 - EMMCNORM - eMMC Download Mode 254 255 Download boot loader or program code from eMMC flash into CM3 or CA53 256 Requires full initialization and command sequence 257 258 - SATA - SATA device boot 259 260 Image needs to be stored at disk LBA 0 or at disk partition with 261 MBR type 0x4d (ASCII 'M' as in Marvell) or at disk partition with 262 GPT partition type GUID ``6828311A-BA55-42A4-BCDE-A89BB5EDECAE``. 263 264- PARTNUM 265 266 The boot partition number, default is 0. 267 268 To boot from eMMC, the value should be aligned with the parameter in 269 U-Boot with name of ``CONFIG_SYS_MMC_ENV_PART``, whose value by default is 270 1. For details about CONFIG_SYS_MMC_ENV_PART, please refer to the U-Boot 271 build instructions. 272 273- WTMI_IMG 274 275 The path of the binary can point to an image which 276 does nothing, an image which supports EFUSE or a customized CM3 firmware 277 binary. The default image is ``fuse.bin`` that built from sources in WTP 278 folder, which is the next option. If the default image is OK, then this 279 option should be skipped. 280 281 Please note that this is not a full WTMI image, just a main loop without 282 hardware initialization code. Final WTMI image is built from this WTMI_IMG 283 binary and sys-init code from the WTP directory which sets DDR and CPU 284 clocks according to DDR_TOPOLOGY and CLOCKSPRESET options. 285 286 CZ.NIC as part of Turris project released free and open source WTMI 287 application firmware ``wtmi_app.bin`` for all Armada 3720 devices. 288 This firmware includes additional features like access to Hardware 289 Random Number Generator of Armada 3720 SoC which original Marvell's 290 ``fuse.bin`` image does not have. 291 292 CZ.NIC's Armada 3720 Secure Firmware is available at website: 293 294 https://gitlab.nic.cz/turris/mox-boot-builder/ 295 296- WTP 297 298 Specify path to the full checkout of Marvell A3700-utils-marvell git 299 repository. Checkout must contain also .git subdirectory because WTP 300 build process calls git commands. 301 302 WTP build process uses also Marvell mv-ddr-marvell git repository 303 specified in MV_DDR_PATH option. 304 305 Do not remove any parts of git checkout becuase build process and other 306 applications need them for correct building and version determination. 307 308- CRYPTOPP_PATH 309 310 Use this parameter to point to Crypto++ source code 311 directory. If this option is specified then Crypto++ source code in 312 CRYPTOPP_PATH directory will be automatically compiled. Crypto++ library 313 is required for building WTP image tool. Either CRYPTOPP_PATH or 314 CRYPTOPP_LIBDIR with CRYPTOPP_INCDIR needs to be specified for Armada37x0. 315 316- CRYPTOPP_LIBDIR 317 318 Use this parameter to point to the directory with 319 compiled Crypto++ library. By default it points to the CRYPTOPP_PATH. 320 321 On Debian systems it is possible to install system-wide Crypto++ library 322 via command ``apt install libcrypto++-dev`` and specify CRYPTOPP_LIBDIR 323 to ``/usr/lib/``. 324 325- CRYPTOPP_INCDIR 326 327 Use this parameter to point to the directory with 328 header files of Crypto++ library. By default it points to the CRYPTOPP_PATH. 329 330 On Debian systems it is possible to install system-wide Crypto++ library 331 via command ``apt install libcrypto++-dev`` and specify CRYPTOPP_INCDIR 332 to ``/usr/include/crypto++/``. 333 334 335For example, in order to build the image in debug mode with log level up to 'notice' level run 336 337.. code:: shell 338 339 > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 PLAT=<MARVELL_PLATFORM> mrvl_flash 340 341And if we want to build a Armada37x0 image in debug mode with log level up to 'notice' level, 342the image has the preset CPU at 1000 MHz, preset DDR3 at 800 MHz, the DDR topology of DDR4 2CS, 343the image boot from SPI NOR flash partition 0, and the image is non trusted in WTP, the command 344line is as following 345 346.. code:: shell 347 348 > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 CLOCKSPRESET=CPU_1000_DDR_800 \ 349 MARVELL_SECURE_BOOT=0 DDR_TOPOLOGY=3 BOOTDEV=SPINOR PARTNUM=0 PLAT=a3700 \ 350 MV_DDR_PATH=/path/to/mv-ddr-marvell/ WTP=/path/to/A3700-utils-marvell/ \ 351 CRYPTOPP_PATH=/path/to/cryptopp/ BL33=/path/to/u-boot.bin \ 352 all fip mrvl_bootimage mrvl_flash mrvl_uart 353 354To build just TF-A without WTMI image (useful for A3720 Turris MOX board), run following command: 355 356.. code:: shell 357 358 > make USE_COHERENT_MEM=0 PLAT=a3700 CM3_SYSTEM_RESET=1 BL33=/path/to/u-boot.bin \ 359 CROSS_COMPILE=aarch64-linux-gnu- mrvl_bootimage 360 361Here is full example how to build production release of Marvell firmware image (concatenated 362binary of Marvell's A3720 sys-init, CZ.NIC's Armada 3720 Secure Firmware, TF-A and U-Boot) for 363EspressoBin board (PLAT=a3700) with 1GHz CPU (CLOCKSPRESET=CPU_1000_DDR_800) and 3641GB DDR4 RAM (DDR_TOPOLOGY=5): 365 366.. code:: shell 367 368 > git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git 369 > git clone https://source.denx.de/u-boot/u-boot.git 370 > git clone https://github.com/weidai11/cryptopp.git 371 > git clone https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git 372 > git clone https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git 373 > git clone https://gitlab.nic.cz/turris/mox-boot-builder.git 374 > make -C u-boot CROSS_COMPILE=aarch64-linux-gnu- mvebu_espressobin-88f3720_defconfig u-boot.bin 375 > make -C mox-boot-builder CROSS_CM3=arm-linux-gnueabi- wtmi_app.bin 376 > make -C trusted-firmware-a CROSS_COMPILE=aarch64-linux-gnu- CROSS_CM3=arm-linux-gnueabi- \ 377 USE_COHERENT_MEM=0 PLAT=a3700 CLOCKSPRESET=CPU_1000_DDR_800 DDR_TOPOLOGY=5 \ 378 MV_DDR_PATH=$PWD/mv-ddr-marvell/ WTP=$PWD/A3700-utils-marvell/ \ 379 CRYPTOPP_PATH=$PWD/cryptopp/ BL33=$PWD/u-boot/u-boot.bin \ 380 WTMI_IMG=$PWD/mox-boot-builder/wtmi_app.bin FIP_ALIGN=0x100 mrvl_flash 381 382Produced Marvell firmware flash image: ``trusted-firmware-a/build/a3700/release/flash-image.bin`` 383 384Special Build Flags 385-------------------- 386 387- PLAT_RECOVERY_IMAGE_ENABLE 388 When set this option to enable secondary recovery function when build atf. 389 In order to build UART recovery image this operation should be disabled for 390 A7K/A8K/CN913x because of hardware limitation (boot from secondary image 391 can interrupt UART recovery process). This MACRO definition is set in 392 ``plat/marvell/armada/a8k/common/include/platform_def.h`` file. 393 394- DDR32 395 In order to work in 32bit DDR, instead of the default 64bit ECC DDR, 396 this flag should be set to 1. 397 398For more information about build options, please refer to the 399:ref:`Build Options` document. 400 401 402Build output 403------------ 404Marvell's TF-A compilation generates 8 files: 405 406 - ble.bin - BLe image (not available for Armada37x0) 407 - bl1.bin - BL1 image 408 - bl2.bin - BL2 image 409 - bl31.bin - BL31 image 410 - fip.bin - FIP image (contains BL2, BL31 & BL33 (U-Boot) images) 411 - boot-image.bin - TF-A image (contains BL1 and FIP images) 412 - flash-image.bin - Flashable Marvell firmware image. For Armada37x0 it 413 contains TIM, WTMI and boot-image.bin images. For other platforms it contains 414 BLe and boot-image.bin images. Should be placed on the boot flash/device. 415 - uart-images.tgz.bin - GZIPed TAR archive which contains Armada37x0 images 416 for booting via UART. Could be loaded via Marvell's WtpDownload tool from 417 A3700-utils-marvell repository. 418 419Additional make target ``mrvl_bootimage`` produce ``boot-image.bin`` file. Target 420``mrvl_flash`` produce final ``flash-image.bin`` file and target ``mrvl_uart`` 421produce ``uart-images.tgz.bin`` file. 422 423 424Tools and external components installation 425------------------------------------------ 426 427Armada37x0 Builds require installation of additional components 428~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 429 430(1) ARM cross compiler capable of building images for the service CPU (CM3). 431 This component is usually included in the Linux host packages. 432 On Debian/Ubuntu hosts the default GNU ARM tool chain can be installed 433 using the following command 434 435 .. code:: shell 436 437 > sudo apt-get install gcc-arm-linux-gnueabi 438 439 Only if required, the default tool chain prefix ``arm-linux-gnueabi-`` can be 440 overwritten using the environment variable ``CROSS_CM3``. 441 Example for BASH shell 442 443 .. code:: shell 444 445 > export CROSS_CM3=/opt/arm-cross/bin/arm-linux-gnueabi 446 447(2) DDR initialization library sources (mv_ddr) available at the following repository 448 (use the "master" branch): 449 450 https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git 451 452(3) Armada3700 tools available at the following repository 453 (use the "master" branch): 454 455 https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git 456 457(4) Crypto++ library available at the following repository: 458 459 https://github.com/weidai11/cryptopp.git 460 461(5) Optional CZ.NIC's Armada 3720 Secure Firmware: 462 463 https://gitlab.nic.cz/turris/mox-boot-builder.git 464 465Armada70x0, Armada80x0 and CN913x Builds require installation of additional components 466~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 467 468(1) DDR initialization library sources (mv_ddr) available at the following repository 469 (use the "master" branch): 470 471 https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git 472 473(2) MSS Management SubSystem Firmware available at the following repository 474 (use the "binaries-marvell-armada-SDK10.0.1.0" branch): 475 476 https://github.com/MarvellEmbeddedProcessors/binaries-marvell.git 477