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