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