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