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