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