1Build Options 2============= 3 4The TF-A build system supports the following build options. Unless mentioned 5otherwise, these options are expected to be specified at the build command 6line and are not to be modified in any component makefiles. Note that the 7build system doesn't track dependency for build options. Therefore, if any of 8the build options are changed from a previous build, a clean build must be 9performed. 10 11.. _build_options_common: 12 13Common build options 14-------------------- 15 16- ``AARCH32_INSTRUCTION_SET``: Choose the AArch32 instruction set that the 17 compiler should use. Valid values are T32 and A32. It defaults to T32 due to 18 code having a smaller resulting size. 19 20- ``AARCH32_SP`` : Choose the AArch32 Secure Payload component to be built as 21 as the BL32 image when ``ARCH=aarch32``. The value should be the path to the 22 directory containing the SP source, relative to the ``bl32/``; the directory 23 is expected to contain a makefile called ``<aarch32_sp-value>.mk``. 24 25- ``AMU_RESTRICT_COUNTERS``: Register reads to the group 1 counters will return 26 zero at all but the highest implemented exception level. External 27 memory-mapped debug accesses are unaffected by this control. 28 The default value is 1 for all platforms. 29 30- ``ARCH`` : Choose the target build architecture for TF-A. It can take either 31 ``aarch64`` or ``aarch32`` as values. By default, it is defined to 32 ``aarch64``. 33 34- ``ARM_ARCH_FEATURE``: Optional Arm Architecture build option which specifies 35 one or more feature modifiers. This option has the form ``[no]feature+...`` 36 and defaults to ``none``. It translates into compiler option 37 ``-march=armvX[.Y]-a+[no]feature+...``. See compiler's documentation for the 38 list of supported feature modifiers. 39 40- ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when 41 compiling TF-A. Its value must be numeric, and defaults to 8 . See also, 42 *Armv8 Architecture Extensions* and *Armv7 Architecture Extensions* in 43 :ref:`Firmware Design`. 44 45- ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when 46 compiling TF-A. Its value must be a numeric, and defaults to 0. See also, 47 *Armv8 Architecture Extensions* in :ref:`Firmware Design`. 48 49- ``ARM_BL2_SP_LIST_DTS``: Path to DTS file snippet to override the hardcoded 50 SP nodes in tb_fw_config. 51 52- ``ARM_SPMC_MANIFEST_DTS`` : path to an alternate manifest file used as the 53 SPMC Core manifest. Valid when ``SPD=spmd`` is selected. 54 55- ``BL2``: This is an optional build option which specifies the path to BL2 56 image for the ``fip`` target. In this case, the BL2 in the TF-A will not be 57 built. 58 59- ``BL2U``: This is an optional build option which specifies the path to 60 BL2U image. In this case, the BL2U in TF-A will not be built. 61 62- ``RESET_TO_BL2``: Boolean option to enable BL2 entrypoint as the CPU reset 63 vector instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 64 entrypoint) or 1 (CPU reset to BL2 entrypoint). 65 The default value is 0. 66 67- ``BL2_RUNS_AT_EL3``: This is an implicit flag to denote that BL2 runs at EL3. 68 While it is explicitly set to 1 when RESET_TO_BL2 is set to 1 it can also be 69 true in a 4-world system where RESET_TO_BL2 is 0. 70 71- ``BL2_INV_DCACHE``: This is an optional build option which control dcache 72 invalidation upon BL2 entry. Some platform cannot handle cache operations 73 during entry as the coherency unit is not yet initialized. This may cause 74 crashing. Leaving this option to '1' (default) will allow the operation. 75 This option is only relevant when BL2 is set to run at EL3. 76 77- ``BL2_ENABLE_SP_LOAD``: Boolean option to enable loading SP packages from the 78 FIP. Automatically enabled if ``SP_LAYOUT_FILE`` is provided. 79 80- ``BL2_IN_XIP_MEM``: In some use-cases BL2 will be stored in eXecute In Place 81 (XIP) memory, like BL1. In these use-cases, it is necessary to initialize 82 the RW sections in RAM, while leaving the RO sections in place. This option 83 enable this use-case. For now, this option is only supported 84 when RESET_TO_BL2 is set to '1'. 85 86- ``BL31``: This is an optional build option which specifies the path to 87 BL31 image for the ``fip`` target. In this case, the BL31 in TF-A will not 88 be built. 89 90- ``BL31_KEY``: This option is used when ``GENERATE_COT=1``. It specifies a 91 file that contains the BL31 private key in PEM format or a PKCS11 URI. If 92 ``SAVE_KEYS=1``, only a file is accepted and it will be used to save the key. 93 94- ``BL32``: This is an optional build option which specifies the path to 95 BL32 image for the ``fip`` target. In this case, the BL32 in TF-A will not 96 be built. 97 98- ``BL32_EXTRA1``: This is an optional build option which specifies the path to 99 Trusted OS Extra1 image for the ``fip`` target. 100 101- ``BL32_EXTRA2``: This is an optional build option which specifies the path to 102 Trusted OS Extra2 image for the ``fip`` target. 103 104- ``BL32_KEY``: This option is used when ``GENERATE_COT=1``. It specifies a 105 file that contains the BL32 private key in PEM format or a PKCS11 URI. If 106 ``SAVE_KEYS=1``, only a file is accepted and it will be used to save the key. 107 108- ``RMM``: This is an optional build option used when ``ENABLE_RMM`` is set. 109 It specifies the path to RMM binary for the ``fip`` target. If the RMM option 110 is not specified, TF-A builds the TRP to load and run at R-EL2. 111 112- ``BL33``: Path to BL33 image in the host file system. This is mandatory for 113 ``fip`` target in case TF-A BL2 is used. 114 115- ``BL33_KEY``: This option is used when ``GENERATE_COT=1``. It specifies a 116 file that contains the BL33 private key in PEM format or a PKCS11 URI. If 117 ``SAVE_KEYS=1``, only a file is accepted and it will be used to save the key. 118 119- ``BRANCH_PROTECTION``: Numeric value to enable ARMv8.3 Pointer Authentication 120 and ARMv8.5 Branch Target Identification support for TF-A BL images themselves. 121 If enabled, it is needed to use a compiler that supports the option 122 ``-mbranch-protection``. The value of the ``-march`` (via ``ARM_ARCH_MINOR`` 123 and ``ARM_ARCH_MAJOR``) option will control which instructions will be 124 emitted (HINT space or not). Selects the branch protection features to use: 125- 0: Default value turns off all types of branch protection (FEAT_STATE_DISABLED) 126- 1: Enables all types of branch protection features 127- 2: Return address signing to its standard level 128- 3: Extend the signing to include leaf functions 129- 4: Turn on branch target identification mechanism 130- 5: Enables all types of branch protection features, only if present in 131 hardware (FEAT_STATE_CHECK). 132 133 The table below summarizes ``BRANCH_PROTECTION`` values, GCC compilation options 134 and resulting PAuth/BTI features. 135 136 +-------+--------------+-------+-----+ 137 | Value | GCC option | PAuth | BTI | 138 +=======+==============+=======+=====+ 139 | 0 | none | N | N | 140 +-------+--------------+-------+-----+ 141 | 1 | standard | Y | Y | 142 +-------+--------------+-------+-----+ 143 | 2 | pac-ret | Y | N | 144 +-------+--------------+-------+-----+ 145 | 3 | pac-ret+leaf | Y | N | 146 +-------+--------------+-------+-----+ 147 | 4 | bti | N | Y | 148 +-------+--------------+-------+-----+ 149 | 5 | dynamic | Y | Y | 150 +-------+--------------+-------+-----+ 151 152 This option defaults to 0. 153 Note that Pointer Authentication is enabled for Non-secure world 154 irrespective of the value of this option if the CPU supports it. 155 156- ``BUILD_MESSAGE_TIMESTAMP``: String used to identify the time and date of the 157 compilation of each build. It must be set to a C string (including quotes 158 where applicable). Defaults to a string that contains the time and date of 159 the compilation. 160 161- ``BUILD_STRING``: Input string for VERSION_STRING, which allows the TF-A 162 build to be uniquely identified. Defaults to the current git commit id. 163 164- ``BUILD_BASE``: Output directory for the build. Defaults to ``./build`` 165 166- ``CFLAGS``: Extra user options appended on the compiler's command line in 167 addition to the options set by the build system. 168 169- ``COLD_BOOT_SINGLE_CPU``: This option indicates whether the platform may 170 release several CPUs out of reset. It can take either 0 (several CPUs may be 171 brought up) or 1 (only one CPU will ever be brought up during cold reset). 172 Default is 0. If the platform always brings up a single CPU, there is no 173 need to distinguish between primary and secondary CPUs and the boot path can 174 be optimised. The ``plat_is_my_cpu_primary()`` and 175 ``plat_secondary_cold_boot_setup()`` platform porting interfaces do not need 176 to be implemented in this case. 177 178- ``COT``: When Trusted Boot is enabled, selects the desired chain of trust. 179 Defaults to ``tbbr``. 180 181- ``CRASH_REPORTING``: A non-zero value enables a console dump of processor 182 register state when an unexpected exception occurs during execution of 183 BL31. This option defaults to the value of ``DEBUG`` - i.e. by default 184 this is only enabled for a debug build of the firmware. 185 186- ``CREATE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the 187 certificate generation tool to create new keys in case no valid keys are 188 present or specified. Allowed options are '0' or '1'. Default is '1'. 189 190- ``CTX_INCLUDE_AARCH32_REGS`` : Boolean option that, when set to 1, will cause 191 the AArch32 system registers to be included when saving and restoring the 192 CPU context. The option must be set to 0 for AArch64-only platforms (that 193 is on hardware that does not implement AArch32, or at least not at EL1 and 194 higher ELs). Default value is 1. 195 196- ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP 197 registers to be included when saving and restoring the CPU context. Default 198 is 0. 199 200- ``CTX_INCLUDE_MPAM_REGS``: Boolean option that, when set to 1, will cause the 201 Memory System Resource Partitioning and Monitoring (MPAM) 202 registers to be included when saving and restoring the CPU context. 203 Default is '0'. 204 205- ``CTX_INCLUDE_NEVE_REGS``: Numeric value, when set will cause the Armv8.4-NV 206 registers to be saved/restored when entering/exiting an EL2 execution 207 context. This flag can take values 0 to 2, to align with the 208 ``ENABLE_FEAT`` mechanism. Default value is 0. 209 210- ``CTX_INCLUDE_PAUTH_REGS``: Numeric value to enable the Pointer 211 Authentication for Secure world. This will cause the ARMv8.3-PAuth registers 212 to be included when saving and restoring the CPU context as part of world 213 switch. Automatically enabled when ``BRANCH_PROTECTION`` is enabled. This flag 214 can take values 0 to 2, to align with ``ENABLE_FEAT`` mechanism. Default value 215 is 0. 216 217 Note that Pointer Authentication is enabled for Non-secure world irrespective 218 of the value of this flag if the CPU supports it. Alternatively, when 219 ``BRANCH_PROTECTION`` is enabled, this flag is superseded. 220 221- ``CTX_INCLUDE_SVE_REGS``: Boolean option that, when set to 1, will cause the 222 SVE registers to be included when saving and restoring the CPU context. Note 223 that this build option requires ``ENABLE_SVE_FOR_SWD`` to be enabled. In 224 general, it is recommended to perform SVE context management in lower ELs 225 and skip in EL3 due to the additional cost of maintaining large data 226 structures to track the SVE state. Hence, the default value is 0. 227 228- ``DEBUG``: Chooses between a debug and release build. It can take either 0 229 (release) or 1 (debug) as values. 0 is the default. 230 231- ``DECRYPTION_SUPPORT``: This build flag enables the user to select the 232 authenticated decryption algorithm to be used to decrypt firmware/s during 233 boot. It accepts 2 values: ``aes_gcm`` and ``none``. The default value of 234 this flag is ``none`` to disable firmware decryption which is an optional 235 feature as per TBBR. 236 237- ``DISABLE_BIN_GENERATION``: Boolean option to disable the generation 238 of the binary image. If set to 1, then only the ELF image is built. 239 0 is the default. 240 241- ``DISABLE_MTPMU``: Numeric option to disable ``FEAT_MTPMU`` (Multi Threaded 242 PMU). ``FEAT_MTPMU`` is an optional feature available on Armv8.6 onwards. 243 This flag can take values 0 to 2, to align with the ``ENABLE_FEAT`` 244 mechanism. Default is ``0``. 245 246- ``DYN_DISABLE_AUTH``: Provides the capability to dynamically disable Trusted 247 Board Boot authentication at runtime. This option is meant to be enabled only 248 for development platforms. ``TRUSTED_BOARD_BOOT`` flag must be set if this 249 flag has to be enabled. 0 is the default. 250 251- ``E``: Boolean option to make warnings into errors. Default is 1. 252 253 When specifying higher warnings levels (``W=1`` and higher), this option 254 defaults to 0. This is done to encourage contributors to use them, as they 255 are expected to produce warnings that would otherwise fail the build. New 256 contributions are still expected to build with ``W=0`` and ``E=1`` (the 257 default). 258 259- ``EARLY_CONSOLE``: This option is used to enable early traces before default 260 console is properly setup. It introduces EARLY_* traces macros, that will 261 use the non-EARLY traces macros if the flag is enabled, or do nothing 262 otherwise. To use this feature, platforms will have to create the function 263 plat_setup_early_console(). 264 Default is 0 (disabled) 265 266- ``EL3_PAYLOAD_BASE``: This option enables booting an EL3 payload instead of 267 the normal boot flow. It must specify the entry point address of the EL3 268 payload. Please refer to the "Booting an EL3 payload" section for more 269 details. 270 271- ``ENABLE_AMU_AUXILIARY_COUNTERS``: Enables support for AMU auxiliary counters 272 (also known as group 1 counters). These are implementation-defined counters, 273 and as such require additional platform configuration. Default is 0. 274 275- ``ENABLE_ASSERTIONS``: This option controls whether or not calls to ``assert()`` 276 are compiled out. For debug builds, this option defaults to 1, and calls to 277 ``assert()`` are left in place. For release builds, this option defaults to 0 278 and calls to ``assert()`` function are compiled out. This option can be set 279 independently of ``DEBUG``. It can also be used to hide any auxiliary code 280 that is only required for the assertion and does not fit in the assertion 281 itself. 282 283- ``ENABLE_BACKTRACE``: This option controls whether to enable backtrace 284 dumps or not. It is supported in both AArch64 and AArch32. However, in 285 AArch32 the format of the frame records are not defined in the AAPCS and they 286 are defined by the implementation. This implementation of backtrace only 287 supports the format used by GCC when T32 interworking is disabled. For this 288 reason enabling this option in AArch32 will force the compiler to only 289 generate A32 code. This option is enabled by default only in AArch64 debug 290 builds, but this behaviour can be overridden in each platform's Makefile or 291 in the build command line. 292 293- ``FEATURE_DETECTION``: Boolean option to enable the architectural features 294 verification mechanism. This is a debug feature that compares the 295 architectural features enabled through the feature specific build flags 296 (ENABLE_FEAT_xxx) with the features actually available on the CPU running, 297 and reports any discrepancies. 298 299 It is expected that this feature is only used for flexible platforms like 300 software emulators, or for hardware platforms at bringup time, to verify 301 that the configured feature set matches the CPU. 302 Default value is ``0``. 303 304- ``ENABLE_FEAT_AMU``: Numeric value to enable Activity Monitor Unit 305 extensions. This flag can take the values 0 to 2, to align with the 306 ``ENABLE_FEAT`` mechanism. This is an optional architectural feature 307 available on v8.4 onwards. Some v8.2 implementations also implement an AMU 308 and this option can be used to enable this feature on those systems as well. 309 This flag can take the values 0 to 2, the default is 0. 310 311- ``ENABLE_FEAT_AMUv1p1``: Numeric value to enable the ``FEAT_AMUv1p1`` 312 extension. ``FEAT_AMUv1p1`` is an optional feature available on Arm v8.6 313 onwards. This flag can take the values 0 to 2, to align with the 314 ``ENABLE_FEAT`` mechanism. Default value is ``0``. 315 316- ``ENABLE_FEAT_CLRBHB``: Numeric value to enable the CLRBHB instruction. 317 Clear Branch History clears the branch history for the current context to 318 the extent that branch history information created before the CLRBHB instruction 319 cannot be used by code. This is an optional architectural feature available on v8.0 320 onwards and is a mandatory feature from v8.9 onwards. 321 This flag can take the values of 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. 322 Default value is ``0``. 323 324- ``ENABLE_FEAT_CPA2``: Numeric value to enable the ``FEAT_CPA2`` extension. 325 It enables checked pointer arithmetic in EL3, which will result in address 326 faults in the event that a pointer arithmetic overflow error occurs. This is 327 an optional feature starting from Arm v9.4 and This flag can take values 0 to 328 2, to align with the ``ENABLE_FEAT`` mechanism. Default value is ``0``. 329 330- ``ENABLE_FEAT_CSV2_2``: Numeric value to enable the ``FEAT_CSV2_2`` 331 extension. It allows access to the SCXTNUM_EL2 (Software Context Number) 332 register during EL2 context save/restore operations. ``FEAT_CSV2_2`` is an 333 optional feature available on Arm v8.0 onwards. This flag can take values 334 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. 335 Default value is ``0``. 336 337- ``ENABLE_FEAT_CSV2_3``: Numeric value to enable support for ``FEAT_CSV2_3`` 338 extension. This feature is supported in AArch64 state only and is an optional 339 feature available in Arm v8.0 implementations. 340 ``FEAT_CSV2_3`` implies the implementation of ``FEAT_CSV2_2``. 341 The flag can take values 0 to 2, to align with the ``ENABLE_FEAT`` 342 mechanism. Default value is ``0``. 343 344- ``ENABLE_FEAT_CRYPTO``: Numeric value to enable the ``FEAT_CRYPTO`` 345 extension. It allows using the SIMD crypto extension AES, SHA1 and SHA2 346 instructions for mbedtls HASH256, which speeds up the authentication process 347 of the subsequent images in BL1 and BL2. ``FEAT_CRYPTO`` is an optional 348 feature available on Arm v8 onwards. This flag can take values 349 0 to 2, to align with the ``ENABLE_FEAT`` mechanism, however, value ``2`` 350 is treated as ``0`` since there is no way to perform runtime check. 351 Default value is ``0``. 352 353- ``ENABLE_FEAT_CRYPTO_SHA3``: Numeric value to enable the ``FEAT_CRYPTO`` 354 extension. It allows using the SIMD crypto extension SHA3 instructions for 355 mbedtls HASH384 and HASH512, which speeds up the authentication process of 356 the subsequent images in BL1 and BL2. ``FEAT_CRYPTO_SHA3`` is an optional 357 feature available on Arm v8.2 onwards. This flag can take values 358 0 to 1, to align with the ``ENABLE_FEAT`` mechanism, however, value ``2`` 359 is treated as ``0`` since there is no way to perform runtime check. 360 Default value is ``0``. 361 362- ``ENABLE_FEAT_DEBUGV8P9``: Numeric value to enable ``FEAT_DEBUGV8P9`` 363 extension which allows the ability to implement more than 16 breakpoints 364 and/or watchpoints. This feature is mandatory from v8.9 and is optional 365 from v8.8. This flag can take the values of 0 to 2, to align with the 366 ``ENABLE_FEAT`` mechanism. Default value is ``0``. 367 368- ``ENABLE_FEAT_DIT``: Numeric value to enable ``FEAT_DIT`` (Data Independent 369 Timing) extension. It allows setting the ``DIT`` bit of PSTATE in EL3. 370 ``FEAT_DIT`` is a mandatory architectural feature and is enabled from v8.4 371 and upwards. This flag can take the values 0 to 2, to align with the 372 ``ENABLE_FEAT`` mechanism. Default value is ``0``. 373 374- ``ENABLE_FEAT_ECV``: Numeric value to enable support for the Enhanced Counter 375 Virtualization feature, allowing for access to the CNTPOFF_EL2 (Counter-timer 376 Physical Offset register) during EL2 to EL3 context save/restore operations. 377 Its a mandatory architectural feature and is enabled from v8.6 and upwards. 378 This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 379 mechanism. Default value is ``0``. 380 381- ``ENABLE_FEAT_FPMR``: Numerical value to enable support for Floating Point 382 Mode Register feature, allowing access to the FPMR register. FPMR register 383 controls the behaviors of FP8 instructions. It is an optional architectural 384 feature from v9.2 and upwards. This flag can take value of 0 to 2, to align 385 with the ``FEATURE_DETECTION`` mechanism. Default value is ``0``. 386 387- ``ENABLE_FEAT_FGT``: Numeric value to enable support for FGT (Fine Grain Traps) 388 feature allowing for access to the HDFGRTR_EL2 (Hypervisor Debug Fine-Grained 389 Read Trap Register) during EL2 to EL3 context save/restore operations. 390 Its a mandatory architectural feature and is enabled from v8.6 and upwards. 391 This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 392 mechanism. Default value is ``0``. 393 394- ``ENABLE_FEAT_FGT2``: Numeric value to enable support for FGT2 395 (Fine Grain Traps 2) feature allowing for access to Fine-grained trap 2 registers 396 during EL2 to EL3 context save/restore operations. 397 Its an optional architectural feature and is available from v8.8 and upwards. 398 This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 399 mechanism. Default value is ``0``. 400 401- ``ENABLE_FEAT_FGWTE3``: Numeric value to enable support for 402 Fine Grained Write Trap EL3 (FEAT_FGWTE3), a feature that allows EL3 to 403 restrict overwriting certain EL3 registers after boot. 404 This lockdown is established by setting individual trap bits for 405 system registers that are not expected to be overwritten after boot. 406 This feature is an optional architectural feature and is available from 407 Armv9.4 onwards. This flag can take values from 0 to 2, aligning with 408 the ``ENABLE_FEAT`` mechanism. The default value is 0. 409 410 .. note:: 411 This feature currently traps access to all EL3 registers in 412 ``FGWTE3_EL3``, except for ``MDCR_EL3``, ``MPAM3_EL3``, 413 ``TPIDR_EL3``(when ``CRASH_REPORTING=1``), and 414 ``SCTLR_EL3``(when ``HW_ASSISTED_COHERENCY=0``). 415 If additional traps need to be disabled for specific platforms, 416 please contact the Arm team on `TF-A public mailing list`_. 417 418- ``ENABLE_FEAT_HDBSS``: Numeric value to enable support for HDBSS (Hardware 419 Dirty state tracking structure) by setting ``SCR_EL3.HDBSSEn`` for NS world. 420 This is an optional architectural feature and is available from v9.4 and 421 upwards. This flag can take the values 0 to 2, to align with the 422 ``ENABLE_FEAT`` mechanism. Default value is ``0``. 423 424- ``ENABLE_FEAT_HACDBS``: Numeric value to enable support for 425 HACDBS (Hardware accelerator for cleaning Dirty state) by setting 426 ``SCR_EL3.HACDBSEn`` for NS world. This is an optional architectural feature 427 and is available from v9.4 and upwards. This flag can take the values 0 to 2, 428 to align with the ``ENABLE_FEAT`` mechanism. Default value is ``0``. 429 430- ``ENABLE_FEAT_HCX``: Numeric value to set the bit SCR_EL3.HXEn in EL3 to 431 allow access to HCRX_EL2 (extended hypervisor control register) from EL2 as 432 well as adding HCRX_EL2 to the EL2 context save/restore operations. Its a 433 mandatory architectural feature and is enabled from v8.7 and upwards. This 434 flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 435 mechanism. Default value is ``0``. 436 437- ``ENABLE_FEAT_IDTE3``: Numeric value to set SCR_EL3.TID3/TID5 bits which 438 enables trapping of ID register reads by lower ELs to EL3. This allows EL3 439 to control the feature visibility to lower ELs by returning a sanitized value 440 based on current feature enablement status. Hypervisors are expected to 441 cache ID register during their boot stage. This flag can take the 442 values 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. 443 Default value is ``0``. This feature is EXPERIMENTAL. 444 445 .. note:: 446 This feature traps all lower EL accesses to Group 3 and Group 5 447 ID registers to EL3. This can incur a performance impact and platforms 448 should enable them only if they have a specific need. 449 450- ``ENABLE_FEAT_MOPS``: Numeric value to enable FEAT_MOPS (Standardization 451 of memory operations) when INIT_UNUSED_NS_EL2=1. 452 This feature is mandatory from v8.8 and enabling of FEAT_MOPS does not 453 require any settings from EL3 as the controls are present in EL2 registers 454 (HCRX_EL2.{MSCEn,MCE2} and SCTLR_EL2.MSCEn) and in most configurations 455 we expect EL2 to be present. But in case of INIT_UNUSED_NS_EL2=1 , 456 EL3 should configure the EL2 registers. This flag 457 can take values 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. 458 Default value is ``0``. 459 460- ``ENABLE_FEAT_MTE2``: Numeric value to enable Memory Tagging Extension2 461 if the platform wants to use this feature and MTE2 is enabled at ELX. 462 This flag can take values 0 to 2, to align with the ``ENABLE_FEAT`` 463 mechanism. Default value is ``0``. 464 465- ``ENABLE_FEAT_PAN``: Numeric value to enable the ``FEAT_PAN`` (Privileged 466 Access Never) extension. ``FEAT_PAN`` adds a bit to PSTATE, generating a 467 permission fault for any privileged data access from EL1/EL2 to virtual 468 memory address, accessible at EL0, provided (HCR_EL2.E2H=1). It is a 469 mandatory architectural feature and is enabled from v8.1 and upwards. This 470 flag can take values 0 to 2, to align with the ``ENABLE_FEAT`` 471 mechanism. Default value is ``0``. 472 473- ``ENABLE_FEAT_PAUTH_LR``: Numeric value to enable the ``FEAT_PAUTH_LR`` 474 extension. ``FEAT_PAUTH_LR`` is an optional feature available from Arm v9.4 475 onwards. This feature requires PAUTH to be enabled via the 476 ``BRANCH_PROTECTION`` flag. This flag can take the values 0 to 2, to align 477 with the ``ENABLE_FEAT`` mechanism. Default value is ``0``. 478 479- ``ENABLE_FEAT_RNG``: Numeric value to enable the ``FEAT_RNG`` extension. 480 ``FEAT_RNG`` is an optional feature available on Arm v8.5 onwards. This 481 flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 482 mechanism. Default value is ``0``. 483 484- ``ENABLE_FEAT_RNG_TRAP``: Numeric value to enable the ``FEAT_RNG_TRAP`` 485 extension. This feature is only supported in AArch64 state. This flag can 486 take values 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. 487 Default value is ``0``. ``FEAT_RNG_TRAP`` is an optional feature from 488 Armv8.5 onwards. 489 490- ``ENABLE_FEAT_SB``: Numeric option to let the TF-A code use the ``FEAT_SB`` 491 (Speculation Barrier) instruction ``FEAT_SB`` is an optional feature and 492 defaults to ``0`` for pre-Armv8.5 CPUs, but is mandatory for Armv8.5 or 493 later CPUs. It is enabled from v8.5 and upwards and if needed can be 494 overidden from platforms explicitly. This flag can take values 0 to 2, to 495 align with the ``ENABLE_FEAT`` mechanism. Default value is ``0``. 496 497- ``ENABLE_FEAT_SEL2``: Numeric value to enable the ``FEAT_SEL2`` (Secure EL2) 498 extension. ``FEAT_SEL2`` is a mandatory feature available on Arm v8.4. 499 This flag can take values 0 to 2, to align with the ``ENABLE_FEAT`` 500 mechanism. Default is ``0``. 501 502- ``ENABLE_FEAT_TWED``: Numeric value to enable the ``FEAT_TWED`` (Delayed 503 trapping of WFE Instruction) extension. ``FEAT_TWED`` is a optional feature 504 available on Arm v8.6. This flag can take values 0 to 2, to align with the 505 ``ENABLE_FEAT`` mechanism. Default is ``0``. 506 507 When ``ENABLE_FEAT_TWED`` is set to ``1``, WFE instruction trapping gets 508 delayed by the amount of value in ``TWED_DELAY``. 509 510- ``ENABLE_FEAT_VHE``: Numeric value to enable the ``FEAT_VHE`` (Virtualization 511 Host Extensions) extension. It allows access to CONTEXTIDR_EL2 register 512 during EL2 context save/restore operations.``FEAT_VHE`` is a mandatory 513 architectural feature and is enabled from v8.1 and upwards. It can take 514 values 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. 515 Default value is ``0``. 516 517- ``ENABLE_FEAT_TCR2``: Numeric value to set the bit SCR_EL3.ENTCR2 in EL3 to 518 allow access to TCR2_EL2 (extended translation control) from EL2 as 519 well as adding TCR2_EL2 to the EL2 context save/restore operations. Its a 520 mandatory architectural feature and is enabled from v8.9 and upwards. This 521 flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 522 mechanism. Default value is ``0``. 523 524- ``ENABLE_FEAT_S2PIE``: Numeric value to enable support for FEAT_S2PIE 525 at EL2 and below, and context switch relevant registers. This flag 526 can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 527 mechanism. Default value is ``0``. 528 529- ``ENABLE_FEAT_S1PIE``: Numeric value to enable support for FEAT_S1PIE 530 at EL2 and below, and context switch relevant registers. This flag 531 can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 532 mechanism. Default value is ``0``. 533 534- ``ENABLE_FEAT_S2POE``: Numeric value to enable support for FEAT_S2POE 535 at EL2 and below, and context switch relevant registers. This flag 536 can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 537 mechanism. Default value is ``0``. 538 539- ``ENABLE_FEAT_S1POE``: Numeric value to enable support for FEAT_S1POE 540 at EL2 and below, and context switch relevant registers. This flag 541 can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 542 mechanism. Default value is ``0``. 543 544- ``ENABLE_FEAT_GCS``: Numeric value to set the bit SCR_EL3.GCSEn in EL3 to 545 allow use of Guarded Control Stack from EL2 as well as adding the GCS 546 registers to the EL2 context save/restore operations. This flag can take 547 the values 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. 548 Default value is ``0``. 549 550 - ``ENABLE_FEAT_GCIE``: Boolean value to enable support for the GICv5 CPU 551 interface (see ``USE_GIC_DRIVER`` for the IRI). GICv5 and GICv3 are mutually 552 exclusive, so the ``ENABLE_FEAT`` mechanism is currently not supported. 553 Default value is ``0``. 554 555- ``ENABLE_FEAT_THE``: Numeric value to enable support for FEAT_THE 556 (Translation Hardening Extension) at EL2 and below, setting the bit 557 SCR_EL3.RCWMASKEn in EL3 to allow access to RCWMASK_EL1 and RCWSMASK_EL1 558 registers and context switch them. 559 Its an optional architectural feature and is available from v8.8 and upwards. 560 This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 561 mechanism. Default value is ``0``. 562 563- ``ENABLE_FEAT_SCTLR2``: Numeric value to enable support for FEAT_SCTLR2 564 (Extension to SCTLR_ELx) at EL2 and below, setting the bit 565 SCR_EL3.SCTLR2En in EL3 to allow access to SCTLR2_ELx registers and 566 context switch them. This feature is OPTIONAL from Armv8.0 implementations 567 and mandatory in Armv8.9 implementations. 568 This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 569 mechanism. Default value is ``0``. 570 571- ``ENABLE_FEAT_STEP2``: Numeric value that enables support for FEAT_STEP2 by 572 setting ``MDCR_EL3.EnSTEPOP`` so that lower ELs can access ``MDSTEPOP_EL1``. 573 This feature is optional from Armv9.4 implementations and is mandatory in 574 Armv9.5 implementations. This flag can take the values 0 to 2, to align with 575 the ``ENABLE_FEAT`` mechanism Defaults value is ``0``. 576 577- ``ENABLE_FEAT_D128``: Numeric value to enable support for FEAT_D128 578 at EL2 and below, setting the bit SCT_EL3.D128En in EL3 to allow access to 579 128 bit version of system registers like PAR_EL1, TTBR0_EL1, TTBR1_EL1, 580 TTBR0_EL2, TTBR1_EL2, TTBR0_EL12, TTBR1_EL12 , VTTBR_EL2, RCWMASK_EL1, and 581 RCWSMASK_EL1. Its an optional architectural feature and is available from 582 9.3 and upwards. 583 This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 584 mechanism. Default value is ``0``. 585 586- ``ENABLE_FEAT_UINJ``: Numerical value to enable FEAT_UINJ support which 587 is hardware based injection of undefined instruction exceptions. 588 The objective of this feature is to provide higher privilege software with a 589 future proofed mechanism to inject an Undefined Instruction exception into 590 lower privilege software. It is an optional architectural feature from v9.0 591 and mandatory from v9.6. This flag can take value of 0 to 2, 592 to align with the ``FEATURE_DETECTION`` mechanism. Default value is ``0``. 593 594- ``ENABLE_LTO``: Boolean option to enable Link Time Optimization (LTO) 595 support. This option is currently only supported for AArch64. On GCC it only 596 applies to TF-A proper, and not its libraries. If LTO on libraries (except 597 the libc) is desired a platform can pass `-flto -ffat-lto-objects` as long as 598 GCC >= 14 is in use. ``ENABLE_LTO`` is enabled by default on release builds. 599 Default is 0. 600 601- ``ENABLE_FEAT_MPAM``: Numeric value to enable lower ELs to use MPAM 602 feature. MPAM is an optional Armv8.4 extension that enables various memory 603 system components and resources to define partitions; software running at 604 various ELs can assign themselves to desired partition to control their 605 performance aspects. 606 607 This flag can take values 0 to 2, to align with the ``ENABLE_FEAT`` 608 mechanism. When this option is set to ``1`` or ``2``, EL3 allows lower ELs to 609 access their own MPAM registers without trapping into EL3. This option 610 doesn't make use of partitioning in EL3, however. Platform initialisation 611 code should configure and use partitions in EL3 as required. This option 612 defaults to ``2`` since MPAM is enabled by default for NS world only. 613 The flag is automatically disabled when the target 614 architecture is AArch32. 615 616- ``ENABLE_FEAT_MPAM_PE_BW_CTRL``: This option enables Armv9.3 MPAM 617 PE-side bandwidth controls and disables traps to EL3/EL2 (when 618 ``INIT_UNUSED_NS_EL2`` = 1). The flag accepts values from 0 to 2, in 619 line with the ``ENABLE_FEAT`` mechanism, and defaults to ``0``. 620 621- ``ENABLE_FEAT_LS64_ACCDATA``: Numeric value to enable access and save and 622 restore the ACCDATA_EL1 system register, at EL2 and below. This flag can 623 take the values 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. 624 Default value is ``0``. 625 626- ``ENABLE_FEAT_AIE``: Numeric value to enable access to the (A)MAIR2 system 627 registers from non-secure world. This flag can take the values 0 to 2, to 628 align with the ``ENABLE_FEAT`` mechanism. 629 Default value is ``0``. 630 631- ``ENABLE_FEAT_PFAR``: Numeric value to enable access to the PFAR system 632 registers from non-secure world. This flag can take the values 0 to 2, to 633 align with the ``ENABLE_FEAT`` mechanism. 634 Default value is ``0``. 635 636- ``ENABLE_MPMM``: Boolean option to enable support for the Maximum Power 637 Mitigation Mechanism supported by certain Arm cores, which allows the SoC 638 firmware to detect and limit high activity events to assist in SoC processor 639 power domain dynamic power budgeting and limit the triggering of whole-rail 640 (i.e. clock chopping) responses to overcurrent conditions. Defaults to ``0``. 641 642- ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE) 643 support within generic code in TF-A. This option is currently only supported 644 in BL2, BL31, and BL32 (TSP) for AARCH64 binaries, and 645 in BL32 (SP_min) for AARCH32. Default is 0. 646 647- ``ENABLE_PMF``: Boolean option to enable support for optional Performance 648 Measurement Framework(PMF). Default is 0. 649 650- ``ENABLE_PSCI_STAT``: Boolean option to enable support for optional PSCI 651 functions ``PSCI_STAT_RESIDENCY`` and ``PSCI_STAT_COUNT``. Default is 0. 652 In the absence of an alternate stat collection backend, ``ENABLE_PMF`` must 653 be enabled. If ``ENABLE_PMF`` is set, the residency statistics are tracked in 654 software. 655 656- ``ENABLE_RUNTIME_INSTRUMENTATION``: Boolean option to enable runtime 657 instrumentation which injects timestamp collection points into TF-A to 658 allow runtime performance to be measured. Currently, only PSCI is 659 instrumented. Enabling this option enables the ``ENABLE_PMF`` build option 660 as well. Default is 0. 661 662- ``ENABLE_SPE_FOR_NS`` : Numeric value to enable Statistical Profiling 663 extensions. This is an optional architectural feature for AArch64. 664 This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 665 mechanism. The default is 2 but is automatically disabled when the target 666 architecture is AArch32. 667 668- ``ENABLE_SVE_FOR_NS``: Numeric value to enable Scalable Vector Extension 669 (SVE) for the Non-secure world only. SVE is an optional architectural feature 670 for AArch64. This flag can take the values 0 to 2, to align with the 671 ``ENABLE_FEAT`` mechanism. At this time, this build option cannot be used on 672 systems that have SPM_MM enabled. The default value is 2. 673 674 Note that when SVE is enabled for the Non-secure world, access 675 to SVE, SIMD and floating-point functionality from the Secure world is 676 independently controlled by build option ``ENABLE_SVE_FOR_SWD``. When enabling 677 ``CTX_INCLUDE_FPREGS`` and ``ENABLE_SVE_FOR_NS`` together, it is mandatory to 678 enable ``CTX_INCLUDE_SVE_REGS``. This is to avoid corruption of the Non-secure 679 world data in the Z-registers which are aliased by the SIMD and FP registers. 680 681- ``ENABLE_SVE_FOR_SWD``: Boolean option to enable SVE and FPU/SIMD functionality 682 for the Secure world. SVE is an optional architectural feature for AArch64. 683 The default is 0 and it is automatically disabled when the target architecture 684 is AArch32. 685 686 .. note:: 687 This build flag requires ``ENABLE_SVE_FOR_NS`` to be enabled. When enabling 688 ``ENABLE_SVE_FOR_SWD``, a developer must carefully consider whether 689 ``CTX_INCLUDE_SVE_REGS`` is also needed. 690 691- ``ENABLE_STACK_PROTECTOR``: String option to enable the stack protection 692 checks in GCC. Allowed values are "all", "strong", "default" and "none". The 693 default value is set to "none". "strong" is the recommended stack protection 694 level if this feature is desired. "none" disables the stack protection. For 695 all values other than "none", the ``plat_get_stack_protector_canary()`` 696 platform hook needs to be implemented. The value is passed as the last 697 component of the option ``-fstack-protector-$ENABLE_STACK_PROTECTOR``. 698 699- ``ENABLE_ERRATA_ALL``: This option is used only for testing purposes, Boolean 700 option to enable the workarounds for all errata that TF-A implements. Normally 701 they should be explicitly enabled depending on each platform's needs. Not 702 recommended for release builds. This option is default set to 0. 703 704- ``ENABLE_FEAT_MORELLO`` : Numeric option to enable the Morello capability aware 705 firmware. This flag can take the values 0 to 2, to align with the 706 ``ENABLE_FEAT`` mechanism. This option is experimental and supported only with 707 LLVM CLANG toolchain and not with GCC toolchain. Capability awareness is 708 currently enabled only in BL31 firmware and not in other firmware types of 709 trusted firmware. Enabling this on regular AARCH64 system might not work. 710 711- ``ENCRYPT_BL31``: Binary flag to enable encryption of BL31 firmware. This 712 flag depends on ``DECRYPTION_SUPPORT`` build flag. 713 714- ``ENCRYPT_BL32``: Binary flag to enable encryption of Secure BL32 payload. 715 This flag depends on ``DECRYPTION_SUPPORT`` build flag. 716 717- ``ENC_KEY``: A 32-byte (256-bit) symmetric key in hex string format. It could 718 either be SSK or BSSK depending on ``FW_ENC_STATUS`` flag. This value depends 719 on ``DECRYPTION_SUPPORT`` build flag. 720 721- ``ENC_NONCE``: A 12-byte (96-bit) encryption nonce or Initialization Vector 722 (IV) in hex string format. This value depends on ``DECRYPTION_SUPPORT`` 723 build flag. 724 725- ``ERROR_DEPRECATED``: This option decides whether to treat the usage of 726 deprecated platform APIs, helper functions or drivers within Trusted 727 Firmware as error. It can take the value 1 (flag the use of deprecated 728 APIs as error) or 0. The default is 0. 729 730- ``ETHOSN_NPU_DRIVER``: boolean option to enable a SiP service that can 731 configure an Arm® Ethos™-N NPU. To use this service the target platform's 732 ``HW_CONFIG`` must include the device tree nodes for the NPU. Currently, only 733 the Arm Juno platform has this included in its ``HW_CONFIG`` and the platform 734 only loads the ``HW_CONFIG`` in AArch64 builds. Default is 0. 735 736- ``ETHOSN_NPU_TZMP1``: boolean option to enable TZMP1 support for the 737 Arm® Ethos™-N NPU. Requires ``ETHOSN_NPU_DRIVER`` and 738 ``TRUSTED_BOARD_BOOT`` to be enabled. 739 740- ``ETHOSN_NPU_FW``: location of the NPU firmware binary 741 (```ethosn.bin```). This firmware image will be included in the FIP and 742 loaded at runtime. 743 744- ``EL3_EXCEPTION_HANDLING``: When set to ``1``, enable handling of exceptions 745 targeted at EL3. When set ``0`` (default), no exceptions are expected or 746 handled at EL3, and a panic will result. The exception to this rule is when 747 ``SPMD_SPM_AT_SEL2`` is set to ``1``, in which case, only exceptions 748 occuring during normal world execution, are trapped to EL3. Any exception 749 trapped during secure world execution are trapped to the SPMC. This is 750 supported only for AArch64 builds. 751 752- ``FAULT_INJECTION_SUPPORT``: ARMv8.4 extensions introduced support for fault 753 injection from lower ELs, and this build option enables lower ELs to use 754 Error Records accessed via System Registers to inject faults. This is 755 applicable only to AArch64 builds. 756 757 This feature is intended for testing purposes only, and is advisable to keep 758 disabled for production images. 759 760- ``FIP_NAME``: This is an optional build option which specifies the FIP 761 filename for the ``fip`` target. Default is ``fip.bin``. 762 763- ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU 764 FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``. 765 766- ``FW_ENC_STATUS``: Top level firmware's encryption numeric flag, values: 767 768 :: 769 770 0: Encryption is done with Secret Symmetric Key (SSK) which is common 771 for a class of devices. 772 1: Encryption is done with Binding Secret Symmetric Key (BSSK) which is 773 unique per device. 774 775 This flag depends on ``DECRYPTION_SUPPORT`` build flag. 776 777- ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create`` 778 tool to create certificates as per the Chain of Trust described in 779 :ref:`Trusted Board Boot`. The build system then calls ``fiptool`` to 780 include the certificates in the FIP and FWU_FIP. Default value is '0'. 781 782 Specify both ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=1`` to include support 783 for the Trusted Board Boot feature in the BL1 and BL2 images, to generate 784 the corresponding certificates, and to include those certificates in the 785 FIP and FWU_FIP. 786 787 Note that if ``TRUSTED_BOARD_BOOT=0`` and ``GENERATE_COT=1``, the BL1 and BL2 788 images will not include support for Trusted Board Boot. The FIP will still 789 include the corresponding certificates. This FIP can be used to verify the 790 Chain of Trust on the host machine through other mechanisms. 791 792 Note that if ``TRUSTED_BOARD_BOOT=1`` and ``GENERATE_COT=0``, the BL1 and BL2 793 images will include support for Trusted Board Boot, but the FIP and FWU_FIP 794 will not include the corresponding certificates, causing a boot failure. 795 796- ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have 797 inherent support for specific EL3 type interrupts. Setting this build option 798 to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both 799 by :ref:`platform abstraction layer<platform Interrupt Controller API>` and 800 :ref:`Interrupt Management Framework<Interrupt Management Framework>`. 801 This allows GICv2 platforms to enable features requiring EL3 interrupt type. 802 This also means that all GICv2 Group 0 interrupts are delivered to EL3, and 803 the Secure Payload interrupts needs to be synchronously handed over to Secure 804 EL1 for handling. The default value of this option is ``0``, which means the 805 Group 0 interrupts are assumed to be handled by Secure EL1. 806 807- ``HANDLE_EA_EL3_FIRST_NS``: When set to ``1``, External Aborts and SError 808 Interrupts, resulting from errors in NS world, will be always trapped in 809 EL3 i.e. in BL31 at runtime. When set to ``0`` (default), these exceptions 810 will be trapped in the current exception level (or in EL1 if the current 811 exception level is EL0). 812 813- ``HW_ASSISTED_COHERENCY``: On most Arm systems to-date, platform-specific 814 software operations are required for CPUs to enter and exit coherency. 815 However, newer systems exist where CPUs' entry to and exit from coherency 816 is managed in hardware. Such systems require software to only initiate these 817 operations, and the rest is managed in hardware, minimizing active software 818 management. In such systems, this boolean option enables TF-A to carry out 819 build and run-time optimizations during boot and power management operations. 820 This option defaults to 0 and if it is enabled, then it implies 821 ``WARMBOOT_ENABLE_DCACHE_EARLY`` is also enabled. 822 823 If this flag is disabled while the platform which TF-A is compiled for 824 includes cores that manage coherency in hardware, then a compilation error is 825 generated. This is based on the fact that a system cannot have, at the same 826 time, cores that manage coherency in hardware and cores that don't. In other 827 words, a platform cannot have, at the same time, cores that require 828 ``HW_ASSISTED_COHERENCY=1`` and cores that require 829 ``HW_ASSISTED_COHERENCY=0``. 830 831 Note that, when ``HW_ASSISTED_COHERENCY`` is enabled, version 2 of 832 translation library (xlat tables v2) must be used; version 1 of translation 833 library is not supported. 834 835- ``IMPDEF_SYSREG_TRAP``: Numeric value to enable the handling traps for 836 implementation defined system register accesses from lower ELs. Default 837 value is ``0``. 838 839- ``INVERTED_MEMMAP``: memmap tool print by default lower addresses at the 840 bottom, higher addresses at the top. This build flag can be set to '1' to 841 invert this behavior. Lower addresses will be printed at the top and higher 842 addresses at the bottom. 843 844- ``INIT_UNUSED_NS_EL2``: This build flag guards code that disables EL2 845 safely in scenario where NS-EL2 is present but unused. This flag is set to 0 846 by default. Platforms without NS-EL2 in use must enable this flag. 847 848- ``KEY_ALG``: This build flag enables the user to select the algorithm to be 849 used for generating the PKCS keys and subsequent signing of the certificate. 850 It accepts 5 values: ``rsa``, ``rsa_1_5``, ``ecdsa``, ``ecdsa-brainpool-regular`` 851 and ``ecdsa-brainpool-twisted``. The option ``rsa_1_5`` is the legacy PKCS#1 852 RSA 1.5 algorithm which is not TBBR compliant and is retained only for 853 compatibility. The default value of this flag is ``rsa`` which is the TBBR 854 compliant PKCS#1 RSA 2.1 scheme. 855 856- ``KEY_SIZE``: This build flag enables the user to select the key size for 857 the algorithm specified by ``KEY_ALG``. The valid values for ``KEY_SIZE`` 858 depend on the chosen algorithm and the cryptographic module. 859 860 +---------------------------+------------------------------------+ 861 | KEY_ALG | Possible key sizes | 862 +===========================+====================================+ 863 | rsa | 1024 , 2048 (default), 3072, 4096 | 864 +---------------------------+------------------------------------+ 865 | ecdsa | 256 (default), 384 | 866 +---------------------------+------------------------------------+ 867 | ecdsa-brainpool-regular | 256 (default) | 868 +---------------------------+------------------------------------+ 869 | ecdsa-brainpool-twisted | 256 (default) | 870 +---------------------------+------------------------------------+ 871 872- ``HASH_ALG``: This build flag enables the user to select the secure hash 873 algorithm. It accepts 3 values: ``sha256``, ``sha384`` and ``sha512``. 874 The default value of this flag is ``sha256``. 875 876- ``HW_CONFIG_BASE``: This option specifies the location in memory where the DTB 877 should either be loaded by BL2 or can be found by later stages. 878 879- ``LDFLAGS``: Extra user options appended to the linkers' command line in 880 addition to the one set by the build system. 881 882- ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log 883 output compiled into the build. This should be one of the following: 884 885 :: 886 887 0 (LOG_LEVEL_NONE) 888 10 (LOG_LEVEL_ERROR) 889 20 (LOG_LEVEL_NOTICE) 890 30 (LOG_LEVEL_WARNING) 891 40 (LOG_LEVEL_INFO) 892 50 (LOG_LEVEL_VERBOSE) 893 894 All log output up to and including the selected log level is compiled into 895 the build. The default value is 40 in debug builds and 20 in release builds. 896 897 ``LOG_DEBUG``: Boolean option to enable support for module level internal 898 logs. There can be situation where a module has detail internal debugging 899 logs, these debugging logs may not be required to print even when log level 900 is VERBOSE. Such logs can be put under this flag. This is a file 901 level build flag. By default this should be disabled (``0``) in each file. 902 903- ``MEASURED_BOOT``: Boolean flag to include support for the Measured Boot 904 feature. This flag can be enabled with ``TRUSTED_BOARD_BOOT`` in order to 905 provide trust that the code taking the measurements and recording them has 906 not been tampered with. 907 908 This option defaults to 0. 909 910- ``DISCRETE_TPM``: Boolean flag to include support for a Discrete TPM. 911 912 This option defaults to 0. 913 914- ``TPM_INTERFACE``: When ``DISCRETE_TPM=1``, this is a required flag to 915 select the TPM interface. Currently only one interface is supported: 916 917 :: 918 919 FIFO_SPI 920 921- ``MBOOT_TPM_HASH_ALG``: Build flag to select the TPM hash algorithm used during 922 Measured Boot. Currently only accepts ``sha256`` as a valid algorithm. 923 924- ``MARCH_DIRECTIVE``: used to pass a -march option from the platform build 925 options to the compiler. An example usage: 926 927 .. code:: make 928 929 MARCH_DIRECTIVE := -march=armv8.5-a 930 931- ``HARDEN_SLS``: used to pass -mharden-sls=all from the TF-A build 932 options to the compiler currently supporting only of the options. 933 GCC documentation: 934 https://gcc.gnu.org/onlinedocs/gcc/AArch64-Options.html#index-mharden-sls 935 936 An example usage: 937 938 .. code:: make 939 940 HARDEN_SLS := 1 941 942 This option defaults to 0. 943 944- ``NON_TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It 945 specifies a file that contains the Non-Trusted World private key in PEM 946 format or a PKCS11 URI. If ``SAVE_KEYS=1``, only a file is accepted and it 947 will be used to save the key. 948 949- ``NS_BL2U``: Path to NS_BL2U image in the host file system. This image is 950 optional. It is only needed if the platform makefile specifies that it 951 is required in order to build the ``fwu_fip`` target. 952 953- ``NS_TIMER_SWITCH``: (deprecated) Enable save and restore for non-secure 954 timer register contents upon world switch. It can take either 0 (don't save 955 and restore) or 1 (do save and restore). 0 is the default. An SPD may set 956 this to 1 if it wants the timer registers to be saved and restored. This 957 option has been deprecated since it breaks Linux preemption model. 958 959- ``OVERRIDE_LIBC``: This option allows platforms to override the default libc 960 for the BL image. It can be either 0 (include) or 1 (remove). The default 961 value is 0. 962 963- ``PL011_GENERIC_UART``: Boolean option to indicate the PL011 driver that 964 the underlying hardware is not a full PL011 UART but a minimally compliant 965 generic UART, which is a subset of the PL011. The driver will not access 966 any register that is not part of the SBSA generic UART specification. 967 Default value is 0 (a full PL011 compliant UART is present). 968 969- ``PLAT``: Choose a platform to build TF-A for. The chosen platform name 970 must be subdirectory of any depth under ``plat/``, and must contain a 971 platform makefile named ``platform.mk``. For example, to build TF-A for the 972 Arm Juno board, select PLAT=juno. 973 974- ``PLATFORM_REPORT_CTX_MEM_USE``: Reports the context memory allocated for 975 each core as well as the global context. The data includes the memory used 976 by each world and each privileged exception level. This build option is 977 applicable only for ``ARCH=aarch64`` builds. The default value is 0. 978 979- ``PLAT_EXTRA_LD_SCRIPT``: Allows the platform to include a custom LD script 980 snippet for any custom sections that cannot be expressed otherwise. Defaults 981 to 0. 982 983- ``PRELOADED_BL33_BASE``: This option enables booting a preloaded BL33 image 984 instead of the normal boot flow. When defined, it must specify the entry 985 point address for the preloaded BL33 image. This option is incompatible with 986 ``EL3_PAYLOAD_BASE``. If both are defined, ``EL3_PAYLOAD_BASE`` has priority 987 over ``PRELOADED_BL33_BASE``. 988 989- ``PRESERVE_DSU_PMU_REGS``: This options when enabled allows the platform to 990 save/restore the DynamIQ Shared Unit's(DSU) Performance Monitoring Unit(PMU) 991 registers when the cluster goes through a power cycle. This is disabled by 992 default and platforms that require this feature have to enable them. 993 994- ``PROGRAMMABLE_RESET_ADDRESS``: This option indicates whether the reset 995 vector address can be programmed or is fixed on the platform. It can take 996 either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a 997 programmable reset address, it is expected that a CPU will start executing 998 code directly at the right address, both on a cold and warm reset. In this 999 case, there is no need to identify the entrypoint on boot and the boot path 1000 can be optimised. The ``plat_get_my_entrypoint()`` platform porting interface 1001 does not need to be implemented in this case. 1002 1003- ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats 1004 possible for the PSCI power-state parameter: original and extended State-ID 1005 formats. This flag if set to 1, configures the generic PSCI layer to use the 1006 extended format. The default value of this flag is 0, which means by default 1007 the original power-state format is used by the PSCI implementation. This flag 1008 should be specified by the platform makefile and it governs the return value 1009 of PSCI_FEATURES API for CPU_SUSPEND smc function id. When this option is 1010 enabled on Arm platforms, the option ``ARM_RECOM_STATE_ID_ENC`` needs to be 1011 set to 1 as well. 1012 1013- ``PSCI_OS_INIT_MODE``: Boolean flag to enable support for optional PSCI 1014 OS-initiated mode. This option defaults to 0. 1015 1016- ``ARCH_FEATURE_AVAILABILITY``: Boolean flag to enable support for the 1017 optional SMCCC_ARCH_FEATURE_AVAILABILITY call. This option implicitly 1018 interacts with IMPDEF_SYSREG_TRAP and software emulation. This option 1019 defaults to 0. 1020 1021- ``ENABLE_FEAT_RAS``: Numeric flag to enable Armv8.2 RAS features. RAS 1022 features are an optional extension for pre-Armv8.2 CPUs, but are mandatory 1023 for Armv8.2 or later CPUs. NOTE: This flag enables use of IESB capability to 1024 reduce entry latency into EL3 even when RAS error handling is not performed 1025 on the platform. Hence this flag is recommended to be turned on Armv8.2 and 1026 later CPUs. This flag can take the values 0 to 2, to align with the 1027 ``ENABLE_FEAT`` mechanism. The default is 0. 1028 1029- ``RESET_TO_BL31``: Enable BL31 entrypoint as the CPU reset vector instead 1030 of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 1031 entrypoint) or 1 (CPU reset to BL31 entrypoint). 1032 The default value is 0. 1033 1034- ``RESET_TO_SP_MIN``: SP_MIN is the minimal AArch32 Secure Payload provided 1035 in TF-A. This flag configures SP_MIN entrypoint as the CPU reset vector 1036 instead of the BL1 entrypoint. It can take the value 0 (CPU reset to BL1 1037 entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default value is 0. 1038 1039- ``RME_GPT_BITLOCK_BLOCK``: This defines the block size (in number of 512MB 1040 blocks) covered by a single bit of the bitlock structure during RME GPT 1041 operations. The lower the block size, the better opportunity for 1042 parallelising GPT operations but at the cost of more bits being needed 1043 for the bitlock structure. This numeric parameter can take the values 1044 from 0 to 512 and must be a power of 2. The value of 0 is special and 1045 and it chooses a single spinlock for all GPT L1 table entries. Default 1046 value is 1 which corresponds to block size of 512MB per bit of bitlock 1047 structure. 1048 1049- ``RME_GPT_MAX_BLOCK``: Numeric value in MB to define the maximum size of 1050 supported contiguous blocks in GPT Library. This parameter can take the 1051 values 0, 2, 32 and 512. Setting this value to 0 disables use of Contigious 1052 descriptors. Default value is 512. 1053 1054- ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies a 1055 file that contains the ROT private key in PEM format or a PKCS11 URI and 1056 enforces public key hash generation. If ``SAVE_KEYS=1``, only a file is 1057 accepted and it will be used to save the key. 1058 1059- ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the 1060 certificate generation tool to save the keys used to establish the Chain of 1061 Trust. Allowed options are '0' or '1'. Default is '0' (do not save). 1062 1063- ``SCP_BL2``: Path to SCP_BL2 image in the host file system. This image is optional. 1064 If a SCP_BL2 image is present then this option must be passed for the ``fip`` 1065 target. 1066 1067- ``SCP_BL2_KEY``: This option is used when ``GENERATE_COT=1``. It specifies a 1068 file that contains the SCP_BL2 private key in PEM format or a PKCS11 URI. 1069 If ``SAVE_KEYS=1``, only a file is accepted and it will be used to save the key. 1070 1071- ``SCP_BL2U``: Path to SCP_BL2U image in the host file system. This image is 1072 optional. It is only needed if the platform makefile specifies that it 1073 is required in order to build the ``fwu_fip`` target. 1074 1075- ``SDEI_SUPPORT``: Setting this to ``1`` enables support for Software 1076 Delegated Exception Interface to BL31 image. This defaults to ``0``. 1077 1078 When set to ``1``, the build option ``EL3_EXCEPTION_HANDLING`` must also be 1079 set to ``1``. 1080 1081- ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be 1082 isolated on separate memory pages. This is a trade-off between security and 1083 memory usage. See "Isolating code and read-only data on separate memory 1084 pages" section in :ref:`Firmware Design`. This flag is disabled by default 1085 and affects all BL images. 1086 1087- ``SEPARATE_NOBITS_REGION``: Setting this option to ``1`` allows the NOBITS 1088 sections of BL31 (.bss, stacks, page tables, and coherent memory) to be 1089 allocated in RAM discontiguous from the loaded firmware image. When set, the 1090 platform is expected to provide definitions for ``BL31_NOBITS_BASE`` and 1091 ``BL31_NOBITS_LIMIT``. When the option is ``0`` (the default), NOBITS 1092 sections are placed in RAM immediately following the loaded firmware image. 1093 1094- ``SEPARATE_BL2_NOLOAD_REGION``: Setting this option to ``1`` allows the 1095 NOLOAD sections of BL2 (.bss, stacks, page tables) to be allocated in RAM 1096 discontiguous from loaded firmware images. When set, the platform need to 1097 provide definitions of ``BL2_NOLOAD_START`` and ``BL2_NOLOAD_LIMIT``. This 1098 flag is disabled by default and NOLOAD sections are placed in RAM immediately 1099 following the loaded firmware image. 1100 1101- ``SEPARATE_BL2_FIP``: This option enables the separation of the BL2 FIP image 1102 from the main FIP image. When this option is enabled, the BL2 FIP image is built 1103 as a separate FIP image. The default value is 0. 1104 1105- ``SEPARATE_SIMD_SECTION``: Setting this option to ``1`` allows the SIMD context 1106 data structures to be put in a dedicated memory region as decided by platform 1107 integrator. Default value is ``0`` which means the SIMD context is put in BSS 1108 section of EL3 firmware. 1109 1110- ``SMC_PCI_SUPPORT``: This option allows platforms to handle PCI configuration 1111 access requests via a standard SMCCC defined in `DEN0115`_. When combined with 1112 UEFI+ACPI this can provide a certain amount of OS forward compatibility 1113 with newer platforms that aren't ECAM compliant. 1114 1115- ``SPD``: Choose a Secure Payload Dispatcher component to be built into TF-A. 1116 This build option is only valid if ``ARCH=aarch64``. The value should be 1117 the path to the directory containing the SPD source, relative to 1118 ``services/spd/``; the directory is expected to contain a makefile called 1119 ``<spd-value>.mk``. The SPM Dispatcher standard service is located in 1120 services/std_svc/spmd and enabled by ``SPD=spmd``. The SPM Dispatcher 1121 cannot be enabled when the ``SPM_MM`` option is enabled. 1122 1123- ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can 1124 take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops 1125 execution in BL1 just before handing over to BL31. At this point, all 1126 firmware images have been loaded in memory, and the MMU and caches are 1127 turned off. Refer to the "Debugging options" section for more details. 1128 1129- ``SPMC_AT_EL3`` : This boolean option is used jointly with the SPM 1130 Dispatcher option (``SPD=spmd``). When enabled (1) it indicates the SPMC 1131 component runs at the EL3 exception level. The default value is ``0`` ( 1132 disabled). This configuration supports pre-Armv8.4 platforms (aka not 1133 implementing the ``FEAT_SEL2`` extension). 1134 1135- ``SPMC_AT_EL3_SEL0_SP`` : Boolean option to enable SEL0 SP load support when 1136 ``SPMC_AT_EL3`` is enabled. The default value if ``0`` (disabled). This 1137 option cannot be enabled (``1``) when (``SPMC_AT_EL3``) is disabled. 1138 1139- ``SPMC_OPTEE`` : This boolean option is used jointly with the SPM 1140 Dispatcher option (``SPD=spmd``) and with ``SPMD_SPM_AT_SEL2=0`` to 1141 indicate that the SPMC at S-EL1 is OP-TEE and an OP-TEE specific loading 1142 mechanism should be used. 1143 1144- ``SPMD_SPM_AT_SEL2`` : This boolean option is used jointly with the SPM 1145 Dispatcher option (``SPD=spmd``). When enabled (1) it indicates the SPMC 1146 component runs at the S-EL2 exception level provided by the ``FEAT_SEL2`` 1147 extension. This is the default when enabling the SPM Dispatcher. When 1148 disabled (0) it indicates the SPMC component runs at the S-EL1 execution 1149 state or at EL3 if ``SPMC_AT_EL3`` is enabled. The latter configurations 1150 support pre-Armv8.4 platforms (aka not implementing the ``FEAT_SEL2`` 1151 extension). 1152 1153- ``SPM_MM`` : Boolean option to enable the Management Mode (MM)-based Secure 1154 Partition Manager (SPM) implementation. The default value is ``0`` 1155 (disabled). This option cannot be enabled (``1``) when SPM Dispatcher is 1156 enabled (``SPD=spmd``). 1157 1158- ``SP_LAYOUT_FILE``: Platform provided path to JSON file containing the 1159 description of secure partitions. The build system will parse this file and 1160 package all secure partition blobs into the FIP. This file is not 1161 necessarily part of TF-A tree. Only available when ``SPD=spmd``. 1162 1163- ``SP_MIN_WITH_SECURE_FIQ``: Boolean flag to indicate the SP_MIN handles 1164 secure interrupts (caught through the FIQ line). Platforms can enable 1165 this directive if they need to handle such interruption. When enabled, 1166 the FIQ are handled in monitor mode and non secure world is not allowed 1167 to mask these events. Platforms that enable FIQ handling in SP_MIN shall 1168 implement the api ``sp_min_plat_fiq_handler()``. The default value is 0. 1169 1170- ``SVE_VECTOR_LEN``: SVE vector length to configure in ZCR_EL3. 1171 Platforms can configure this if they need to lower the hardware 1172 limit, for example due to asymmetric configuration or limitations of 1173 software run at lower ELs. The default is the architectural maximum 1174 of 2048 which should be suitable for most configurations, the 1175 hardware will limit the effective VL to the maximum physically supported 1176 VL. 1177 1178- ``TRNG_SUPPORT``: Setting this to ``1`` enables support for True 1179 Random Number Generator Interface to BL31 image. This defaults to ``0``. 1180 1181- ``TRUSTED_BOARD_BOOT``: Boolean flag to include support for the Trusted Board 1182 Boot feature. When set to '1', BL1 and BL2 images include support to load 1183 and verify the certificates and images in a FIP, and BL1 includes support 1184 for the Firmware Update. The default value is '0'. Generation and inclusion 1185 of certificates in the FIP and FWU_FIP depends upon the value of the 1186 ``GENERATE_COT`` option. 1187 1188 .. warning:: 1189 This option depends on ``CREATE_KEYS`` to be enabled. If the keys 1190 already exist in disk, they will be overwritten without further notice. 1191 1192- ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It 1193 specifies a file that contains the Trusted World private key in PEM 1194 format or a PKCS11 URI. If ``SAVE_KEYS=1``, only a file is accepted and 1195 it will be used to save the key. 1196 1197- ``TSP_INIT_ASYNC``: Choose BL32 initialization method as asynchronous or 1198 synchronous, (see "Initializing a BL32 Image" section in 1199 :ref:`Firmware Design`). It can take the value 0 (BL32 is initialized using 1200 synchronous method) or 1 (BL32 is initialized using asynchronous method). 1201 Default is 0. 1202 1203- ``TSP_NS_INTR_ASYNC_PREEMPT``: A non zero value enables the interrupt 1204 routing model which routes non-secure interrupts asynchronously from TSP 1205 to EL3 causing immediate preemption of TSP. The EL3 is responsible 1206 for saving and restoring the TSP context in this routing model. The 1207 default routing model (when the value is 0) is to route non-secure 1208 interrupts to TSP allowing it to save its context and hand over 1209 synchronously to EL3 via an SMC. 1210 1211 .. note:: 1212 When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT`` 1213 must also be set to ``1``. 1214 1215- ``TS_SP_FW_CONFIG``: DTC build flag to include Trusted Services (Crypto and 1216 internal-trusted-storage) as SP in tb_fw_config device tree. 1217 1218- ``TWED_DELAY``: Numeric value to be set in order to delay the trapping of 1219 WFE instruction. ``ENABLE_FEAT_TWED`` build option must be enabled to set 1220 this delay. It can take values in the range (0-15). Default value is ``0`` 1221 and based on this value, 2^(TWED_DELAY + 8) cycles will be delayed. 1222 Platforms need to explicitly update this value based on their requirements. 1223 1224- ``USE_ARM_LINK``: This flag determines whether to enable support for ARM 1225 linker. When the ``LINKER`` build variable points to the armlink linker, 1226 this flag is enabled automatically. To enable support for armlink, platforms 1227 will have to provide a scatter file for the BL image. Currently, Tegra 1228 platforms use the armlink support to compile BL3-1 images. 1229 1230- ``USE_COHERENT_MEM``: This flag determines whether to include the coherent 1231 memory region in the BL memory map or not (see "Use of Coherent memory in 1232 TF-A" section in :ref:`Firmware Design`). It can take the value 1 1233 (Coherent memory region is included) or 0 (Coherent memory region is 1234 excluded). Default is 1. 1235 1236- ``USE_KERNEL_DT_CONVENTION``: When this option is enabled, the hardware 1237 device tree is passed to BL33 using register x0, aligning with the expectations 1238 of the Linux kernel on Arm platforms. If this option is disabled, a different 1239 register, typically x1, may be used instead. This build option is 1240 not necessary when firmware handoff is active (that is, when TRANSFER_LIST=1 1241 is set), and it will be removed once all platforms have transitioned to that 1242 convention. 1243 1244- ``USE_DSU_DRIVER``: This flag enables DSU (DynamIQ Shared Unit) driver. 1245 The DSU driver allows save/restore of DSU PMU registers through 1246 ``PRESERVE_DSU_PMU_REGS`` build option, provides access to PMU registers at 1247 EL1 and allows platforms to configure powerdown and power settings of DSU. 1248 1249- ``ARM_IO_IN_DTB``: This flag determines whether to use IO based on the 1250 firmware configuration framework. This will move the io_policies into a 1251 configuration device tree, instead of static structure in the code base. 1252 1253- ``COT_DESC_IN_DTB``: This flag determines whether to create COT descriptors 1254 at runtime using fconf. If this flag is enabled, COT descriptors are 1255 statically captured in tb_fw_config file in the form of device tree nodes 1256 and properties. Currently, COT descriptors used by BL2 are moved to the 1257 device tree and COT descriptors used by BL1 are retained in the code 1258 base statically. 1259 1260- ``SDEI_IN_FCONF``: This flag determines whether to configure SDEI setup in 1261 runtime using firmware configuration framework. The platform specific SDEI 1262 shared and private events configuration is retrieved from device tree rather 1263 than static C structures at compile time. This is only supported if 1264 SDEI_SUPPORT build flag is enabled. 1265 1266- ``SEC_INT_DESC_IN_FCONF``: This flag determines whether to configure Group 0 1267 and Group1 secure interrupts using the firmware configuration framework. The 1268 platform specific secure interrupt property descriptor is retrieved from 1269 device tree in runtime rather than depending on static C structure at compile 1270 time. 1271 1272- ``USE_ROMLIB``: This flag determines whether library at ROM will be used. 1273 This feature creates a library of functions to be placed in ROM and thus 1274 reduces SRAM usage. Refer to :ref:`Library at ROM` for further details. Default 1275 is 0. 1276 1277- ``V``: Verbose build. If assigned anything other than 0, the build commands 1278 are printed. Default is 0. 1279 1280- ``VERSION_STRING``: String used in the log output for each TF-A image. 1281 Defaults to a string formed by concatenating the version number, build type 1282 and build string. 1283 1284- ``W``: Warning level. Some compiler warning options of interest have been 1285 regrouped and put in the root Makefile. This flag can take the values 0 to 3, 1286 each level enabling more warning options. Default is 0. 1287 1288 This option is closely related to the ``E`` option, which enables 1289 ``-Werror``. 1290 1291 - ``W=0`` (default) 1292 1293 Enables a wide assortment of warnings, most notably ``-Wall`` and 1294 ``-Wextra``, as well as various bad practices and things that are likely to 1295 result in errors. Includes some compiler specific flags. No warnings are 1296 expected at this level for any build. 1297 1298 - ``W=1`` 1299 1300 Enables warnings we want the generic build to include but are too time 1301 consuming to fix at the moment. It re-enables warnings taken out for 1302 ``W=0`` builds (a few of the ``-Wextra`` additions). This level is expected 1303 to eventually be merged into ``W=0``. Some warnings are expected on some 1304 builds, but new contributions should not introduce new ones. 1305 1306 - ``W=2`` (recommended) 1307 1308 Enables warnings we want the generic build to include but cannot be enabled 1309 due to external libraries. This level is expected to eventually be merged 1310 into ``W=0``. Lots of warnings are expected, primarily from external 1311 libraries like zlib and compiler-rt, but new controbutions should not 1312 introduce new ones. 1313 1314 - ``W=3`` 1315 1316 Enables warnings that are informative but not necessary and generally too 1317 verbose and frequently ignored. A very large number of warnings are 1318 expected. 1319 1320 The exact set of warning flags depends on the compiler and TF-A warning 1321 level, however they are all succinctly set in the top-level Makefile. Please 1322 refer to the `GCC`_ or `Clang`_ documentation for more information on the 1323 individual flags. 1324 1325- ``WARMBOOT_ENABLE_DCACHE_EARLY`` : Boolean option to enable D-cache early on 1326 the CPU after warm boot. This is applicable for platforms which do not 1327 require interconnect programming to enable cache coherency (eg: single 1328 cluster platforms). If this option is enabled, then warm boot path 1329 enables D-caches immediately after enabling MMU. This option defaults to 0. 1330 1331- ``ERRATA_SPECULATIVE_AT``: This flag determines whether to enable ``AT`` 1332 speculative errata workaround or not. It accepts 2 values: ``1`` and ``0``. 1333 The default value of this flag is ``0``. 1334 1335 ``AT`` speculative errata workaround disables stage1 page table walk for 1336 lower ELs (EL1 and EL0) in EL3 so that ``AT`` speculative fetch at any point 1337 produces either the correct result or failure without TLB allocation. 1338 1339 This boolean option enables errata for all below CPUs. 1340 1341 +---------+--------------+-------------------------+ 1342 | Errata | CPU | Workaround Define | 1343 +=========+==============+=========================+ 1344 | 1165522 | Cortex-A76 | ``ERRATA_A76_1165522`` | 1345 +---------+--------------+-------------------------+ 1346 | 1319367 | Cortex-A72 | ``ERRATA_A72_1319367`` | 1347 +---------+--------------+-------------------------+ 1348 | 1541130 | Cortex-A65 | ``ERRATA_A65_1541130`` | 1349 +---------+--------------+-------------------------+ 1350 | 1638571 | Cortex-A65AE | ``ERRATA_A65AE_1638571``| 1351 +---------+--------------+-------------------------+ 1352 | 1319537 | Cortex-A57 | ``ERRATA_A57_1319537`` | 1353 +---------+--------------+-------------------------+ 1354 | 1530923 | Cortex-A55 | ``ERRATA_A55_1530923`` | 1355 +---------+--------------+-------------------------+ 1356 | 1530924 | Cortex-A53 | ``ERRATA_A53_1530924`` | 1357 +---------+--------------+-------------------------+ 1358 1359 .. note:: 1360 This option is enabled by build only if platform sets any of above defines 1361 mentioned in ’Workaround Define' column in the table. 1362 If this option is enabled for the EL3 software then EL2 software also must 1363 implement this workaround due to the behaviour of the errata mentioned 1364 in new SDEN document which will get published soon. 1365 1366- ``RAS_TRAP_NS_ERR_REC_ACCESS``: This flag enables/disables the SCR_EL3.TERR 1367 bit, to trap access to the RAS ERR and RAS ERX registers from lower ELs. 1368 This flag is disabled by default. 1369 1370- ``OPENSSL_DIR``: This option is used to provide the path to a directory on the 1371 host machine where a custom installation of OpenSSL is located, which is used 1372 to build the certificate generation, firmware encryption and FIP tools. If 1373 this option is not set, the default OS installation will be used. 1374 1375- ``USE_SP804_TIMER``: Use the SP804 timer instead of the Generic Timer for 1376 functions that wait for an arbitrary time length (udelay and mdelay). The 1377 default value is 0. 1378 1379- ``ENABLE_BRBE_FOR_NS``: Numeric value to enable access to the branch record 1380 buffer registers from NS ELs when FEAT_BRBE is implemented. BRBE is an 1381 optional architectural feature for AArch64. This flag can take the values 1382 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. The default is 0 1383 and it is automatically disabled when the target architecture is AArch32. 1384 1385- ``ENABLE_TRBE_FOR_NS``: Numeric value to enable access of trace buffer 1386 control registers from NS ELs, NS-EL2 or NS-EL1(when NS-EL2 is implemented 1387 but unused) when FEAT_TRBE is implemented. TRBE is an optional architectural 1388 feature for AArch64. This flag can take the values 0 to 2, to align with the 1389 ``ENABLE_FEAT`` mechanism. The default is 0 and it is automatically 1390 disabled when the target architecture is AArch32. 1391 1392- ``USE_SPINLOCK_CAS``: Numeric value to use FEAT_LSE atomics instead of 1393 load/store exclusive instructions with spinlocks. FEAT_LSE is a mandatory 1394 feature from v8.1, however it is only architecturally guaranteed to work on 1395 "conventional memory" which may not apply to tightly coupled memory (eg. SRAM, 1396 TF-A's usual place). Platforms must check if TF-A's memory can be targetted 1397 by atomics before enabling this feature. Expected to increase performance on 1398 systems with many cores. This flag can take the values 0 to 2, to align with 1399 the ``ENABLE_FEAT`` mechanism. The default is 0. 1400 1401- ``ENABLE_SYS_REG_TRACE_FOR_NS``: Numeric value to enable trace system 1402 registers access from NS ELs, NS-EL2 or NS-EL1 (when NS-EL2 is implemented 1403 but unused). This feature is available if trace unit such as ETMv4.x, and 1404 ETE(extending ETM feature) is implemented. This flag can take the values 1405 0 to 2, to align with the ``ENABLE_FEAT`` mechanism. The default is 0. 1406 1407- ``ENABLE_TRF_FOR_NS``: Numeric value to enable trace filter control registers 1408 access from NS ELs, NS-EL2 or NS-EL1 (when NS-EL2 is implemented but unused), 1409 if FEAT_TRF is implemented. This flag can take the values 0 to 2, to align 1410 with the ``ENABLE_FEAT`` mechanism. This flag is disabled by default. 1411 1412- ``CONDITIONAL_CMO``: Boolean option to enable call to platform-defined routine 1413 ``plat_can_cmo`` which will return zero if cache management operations should 1414 be skipped and non-zero otherwise. By default, this option is disabled which 1415 means platform hook won't be checked and CMOs will always be performed when 1416 related functions are called. 1417 1418- ``ERRATA_ABI_SUPPORT``: Boolean option to enable support for Errata management 1419 firmware interface for the BL31 image. By default its disabled (``0``). 1420 1421- ``ERRATA_NON_ARM_INTERCONNECT``: Boolean option to enable support for the 1422 errata mitigation for platforms with a non-arm interconnect using the errata 1423 ABI. By default its disabled (``0``). 1424 1425- ``ENABLE_CONSOLE_GETC``: Boolean option to enable `getc()` feature in console 1426 driver(s). By default it is disabled (``0``) because it constitutes an attack 1427 vector into TF-A by potentially allowing an attacker to inject arbitrary data. 1428 This option should only be enabled on a need basis if there is a use case for 1429 reading characters from the console. 1430 1431GIC driver options 1432-------------------- 1433 1434The generic GIC driver can be included with the ``USE_GIC_DRIVER`` option. It is 1435a numeric option that can take the following values: 1436 1437 - ``0``: generic GIC driver not enabled. Any support is entirely in platform 1438 code. Strongly discouraged for GIC based interrupt controllers. 1439 1440 - ``1``: enable the use of the generic GIC driver but do not include any files 1441 or function definitions. It is then the platform's responsibility to provide 1442 these. This is useful if the platform either has a custom GIC implementation 1443 or an alternative interrupt controller design. Use of this option is strongly 1444 discouraged for standard GIC implementations. 1445 1446 - ``2``: use the GICv2 driver 1447 1448 - ``3``: use the GICv3 driver. See the next section on how to further configure 1449 it. Use this option for GICv4 implementations. Requires calling 1450 ``gic_set_gicr_frames()``. 1451 1452 - ``5``: use the EXPERIMENTAL GICv5 driver. Requires ``ENABLE_FEAT_GCIE=1``. 1453 1454 For GIC driver versions other than ``1``, deciding when to save and restore GIC 1455 context on a power domain state transition, as well as any GIC actions outside 1456 of the PSCI library's visibility are the platform's responsibility. The driver 1457 provides implementations of all necessary subroutines, they only need to be 1458 called as appropriate. 1459 1460GICv3 driver options 1461~~~~~~~~~~~~~~~~~~~~ 1462 1463``USE_GIC_DRIVER=3`` is the preferred way of including GICv3 driver files. The 1464old (deprecated) way of included them is using the directive: 1465``include drivers/arm/gic/v3/gicv3.mk`` 1466 1467The driver can be configured with the following options set in the platform 1468makefile: 1469 1470- ``GICV3_SUPPORT_GIC600``: Add support for the GIC-600 variants of GICv3. 1471 Enabling this option will add runtime detection support for the 1472 GIC-600, so is safe to select even for a GIC500 implementation. 1473 This option defaults to 0. 1474 1475- ``GICV3_SUPPORT_GIC600AE_FMU``: Add support for the Fault Management Unit 1476 for GIC-600 AE. Enabling this option will introduce support to initialize 1477 the FMU. Platforms should call the init function during boot to enable the 1478 FMU and its safety mechanisms. This option defaults to 0. 1479 1480- ``GICV3_IMPL_GIC600_MULTICHIP``: Selects GIC-600 variant with multichip 1481 functionality. This option defaults to 0 1482 1483- ``GICV3_OVERRIDE_DISTIF_PWR_OPS``: Allows override of default implementation 1484 of ``arm_gicv3_distif_pre_save`` and ``arm_gicv3_distif_post_restore`` 1485 functions. This is required for FVP platform which need to simulate GIC save 1486 and restore during SYSTEM_SUSPEND without powering down GIC. Default is 0. 1487 1488- ``GIC_ENABLE_V4_EXTN`` : Enables GICv4 related changes in GICv3 driver. 1489 This option defaults to 0. 1490 1491- ``GIC_EXT_INTID``: When set to ``1``, GICv3 driver will support extended 1492 PPI (1056-1119) and SPI (4096-5119) range. This option defaults to 0. 1493 1494Debugging options 1495----------------- 1496 1497To compile a debug version and make the build more verbose use 1498 1499.. code:: shell 1500 1501 make PLAT=<platform> DEBUG=1 V=1 all 1502 1503AArch64 GCC 11 uses DWARF version 5 debugging symbols by default. Some tools 1504(for example Arm-DS) might not support this and may need an older version of 1505DWARF symbols to be emitted by GCC. This can be achieved by using the 1506``-gdwarf-<version>`` flag, with the version being set to 2, 3, 4 or 5. Setting 1507the version to 4 is recommended for Arm-DS. 1508 1509When debugging logic problems it might also be useful to disable all compiler 1510optimizations by using ``-O0``. 1511 1512.. warning:: 1513 Using ``-O0`` could cause output images to be larger and base addresses 1514 might need to be recalculated (see the **Memory layout on Arm development 1515 platforms** section in the :ref:`Firmware Design`). 1516 1517Extra debug options can be passed to the build system by setting ``CFLAGS`` or 1518``LDFLAGS``: 1519 1520.. code:: shell 1521 1522 CFLAGS='-O0 -gdwarf-2' \ 1523 make PLAT=<platform> DEBUG=1 V=1 all 1524 1525Note that using ``-Wl,`` style compilation driver options in ``CFLAGS`` will be 1526ignored as the linker is called directly. 1527 1528It is also possible to introduce an infinite loop to help in debugging the 1529post-BL2 phase of TF-A. This can be done by rebuilding BL1 with the 1530``SPIN_ON_BL1_EXIT=1`` build flag. Refer to the :ref:`build_options_common` 1531section. In this case, the developer may take control of the target using a 1532debugger when indicated by the console output. When using Arm-DS, the following 1533commands can be used: 1534 1535:: 1536 1537 # Stop target execution 1538 interrupt 1539 1540 # 1541 # Prepare your debugging environment, e.g. set breakpoints 1542 # 1543 1544 # Jump over the debug loop 1545 set var $AARCH64::$Core::$PC = $AARCH64::$Core::$PC + 4 1546 1547 # Resume execution 1548 continue 1549 1550.. _build_options_experimental: 1551 1552Experimental build options 1553--------------------------- 1554 1555Common build options 1556~~~~~~~~~~~~~~~~~~~~ 1557 1558- ``DICE_PROTECTION_ENVIRONMENT``: Boolean flag to specify the measured boot 1559 backend when ``MEASURED_BOOT`` is enabled. The default value is ``0``. When 1560 set to ``1`` then measurements and additional metadata collected during the 1561 measured boot process are sent to the DICE Protection Environment for storage 1562 and processing. A certificate chain, which represents the boot state of the 1563 device, can be queried from the DPE. 1564 1565- ``DRTM_SUPPORT``: Boolean flag to enable support for Dynamic Root of Trust 1566 for Measurement (DRTM). This feature has trust dependency on BL31 for taking 1567 the measurements and recording them as per `PSA DRTM specification`_. For 1568 platforms which use BL2 to load/authenticate BL31 ``TRUSTED_BOARD_BOOT`` can 1569 be used and for the platforms which use ``RESET_TO_BL31`` platform owners 1570 should have mechanism to authenticate BL31. This option defaults to 0. 1571 1572- ``ENABLE_RMM``: Boolean flag to enable the Realm-EL2 payload (RMM). 1573 This will take care of loading and initialising an image in Realm-EL2, and 1574 will at runtime dispatch calls from non-secure world to the RMM, if 1575 applicable. 1576 Default value is 0. Setting this flag implies that RMM must be enabled 1577 therefore, it mandates ``ENABLE_FEAT_RME`` to 1. 1578 1579- ``ENABLE_FEAT_RME``: Numeric value to enable support for the ARMv9 Realm 1580 Management Extension. This flag can take the values 0 to 2, to align with 1581 the ``ENABLE_FEAT`` mechanism. Default value is 0. 1582 This flag solely controls the architectural bits of RME, to let TF-A run 1583 in the "root" physical address space and this will setup Granule Protection 1584 Tables (GPT). Also this will make BL2 run in EL3, so it has access to the new 1585 root address space. For deploying a Realm-EL2 payload (RMM), also set 1586 ``ENABLE_RMM`` and provide an RMM image file. 1587 1588- ``ENABLE_RME``: This options will be deprecated. Please use 1589 ``ENABLE_FEAT_RME``. Until deprecated, setting this option to 1, will also 1590 set ``ENABLE_FEAT_RME`` and ``ENABLE_RMM`` to 1. 1591 1592- ``ENABLE_FEAT_MEC``: Numeric value to enable support for the ARMv9.2 Memory 1593 Encryption Contexts (MEC). This flag can take the values 0 to 2, to align 1594 with the ``ENABLE_FEAT`` mechanism. MEC supports multiple encryption 1595 contexts for Realm security state and only one encryption context for the 1596 rest of the security states. Default value is 0. 1597 1598- ``RMM_V1_COMPAT``: Boolean flag to enable support for RMM v1.x compatibility 1599 mode. When set to 0, TF-A will use the RMM-EL3 interface version required 1600 for RMMv2.0. Default value is 0. 1601 1602- ``FIRME_SUPPORT``: This option enables the FIRME service in TF-A. 1603 1604- ``RMMD_ENABLE_EL3_TOKEN_SIGN``: Numeric value to enable support for singing 1605 realm attestation token signing requests in EL3. This flag can take the 1606 values 0 and 1. The default value is ``0``. When set to ``1``, this option 1607 enables additional RMMD SMCs to push and pop requests for signing to 1608 EL3 along with platform hooks that must be implemented to service those 1609 requests and responses. 1610 1611- ``ENABLE_SME_FOR_NS``: Numeric value to enable Scalable Matrix Extension 1612 (SME), SVE, and FPU/SIMD for the non-secure world only. These features share 1613 registers so are enabled together. Using this option without 1614 ENABLE_SME_FOR_SWD=1 will cause SME, SVE, and FPU/SIMD instructions in secure 1615 world to trap to EL3. Requires ``ENABLE_SVE_FOR_NS`` to be set as SME is a 1616 superset of SVE. SME is an optional architectural feature for AArch64. 1617 At this time, this build option cannot be used on systems that have 1618 SPD=spmd/SPM_MM and atempting to build with this option will fail. 1619 This flag can take the values 0 to 2, to align with the ``ENABLE_FEAT`` 1620 mechanism. Default is 0. 1621 1622- ``ENABLE_SME2_FOR_NS``: Numeric value to enable Scalable Matrix Extension 1623 version 2 (SME2) for the non-secure world only. SME2 is an optional 1624 architectural feature for AArch64. 1625 This should be set along with ENABLE_SME_FOR_NS=1, if not, the default SME 1626 accesses will still be trapped. This flag can take the values 0 to 2, to 1627 align with the ``ENABLE_FEAT`` mechanism. Default is 0. 1628 1629- ``ENABLE_SME_FOR_SWD``: Boolean option to enable the Scalable Matrix 1630 Extension for secure world. Used along with SVE and FPU/SIMD. 1631 ENABLE_SME_FOR_NS and ENABLE_SVE_FOR_SWD must also be set to use this. 1632 Default is 0. 1633 1634- ``ENABLE_SPMD_LP`` : This boolean option is used jointly with the SPM 1635 Dispatcher option (``SPD=spmd``). When enabled (1) it indicates support 1636 for logical partitions in EL3, managed by the SPMD as defined in the 1637 FF-A v1.2 specification. This flag is disabled by default. This flag 1638 must not be used if ``SPMC_AT_EL3`` is enabled. 1639 1640- ``PSA_CRYPTO``: Boolean option for enabling MbedTLS PSA crypto APIs support. 1641 The platform will use PSA compliant Crypto APIs during authentication and 1642 image measurement process by enabling this option. It uses APIs defined as 1643 per the `PSA Crypto API specification`_. This feature is only supported if 1644 using MbedTLS 3.x version. It is disabled (``0``) by default. 1645 1646- ``LFA_SUPPORT``: Boolean flag to enable support for Live Firmware 1647 activation as per the specification. This option defaults to 0. 1648 1649- ``TRANSFER_LIST``: Setting this to ``1`` enables support for Firmware 1650 Handoff using Transfer List defined in `Firmware Handoff specification`_. 1651 This defaults to ``0``. Current implementation follows the Firmware Handoff 1652 specification v0.9. 1653 1654- ``USE_DEBUGFS``: When set to 1 this option exposes a virtual filesystem 1655 interface through BL31 as a SiP SMC function. 1656 Default is disabled (0). 1657 1658- ``HOB_LIST``: Setting this to ``1`` enables support for passing boot 1659 information using HOB defined in `Platform Initialization specification`_. 1660 This defaults to ``0``. 1661 1662- ``ENABLE_ACS_SMC``: When set to ``1``, this enables support for ACS SMC 1663 handler code to handle SMC calls from the Architecture Compliance Suite. The 1664 handler is intentionally empty to reserve the SMC section and allow 1665 project-specific implementations in future ACS use cases. 1666 1667Firmware update options 1668~~~~~~~~~~~~~~~~~~~~~~~ 1669 1670- ``PSA_FWU_SUPPORT``: Enable the firmware update mechanism as per the 1671 `PSA FW update specification`_. The default value is 0. 1672 PSA firmware update implementation has few limitations, such as: 1673 1674 - BL2 is not part of the protocol-updatable images. If BL2 needs to 1675 be updated, then it should be done through another platform-defined 1676 mechanism. 1677 1678 - It assumes the platform's hardware supports CRC32 instructions. 1679 1680- ``NR_OF_FW_BANKS``: Define the number of firmware banks. This flag is used 1681 in defining the firmware update metadata structure. This flag is by default 1682 set to '2'. 1683 1684- ``NR_OF_IMAGES_IN_FW_BANK``: Define the number of firmware images in each 1685 firmware bank. Each firmware bank must have the same number of images as per 1686 the `PSA FW update specification`_. 1687 This flag is used in defining the firmware update metadata structure. This 1688 flag is by default set to '1'. 1689 1690- ``PSA_FWU_METADATA_FW_STORE_DESC``: To be enabled when the FWU 1691 metadata contains image description. The default value is 1. 1692 1693 The version 2 of the FWU metadata allows for an opaque metadata 1694 structure where a platform can choose to not include the firmware 1695 store description in the metadata structure. This option indicates 1696 if the firmware store description, which provides information on 1697 the updatable images is part of the structure. 1698 1699.. _sp_live_activation_build_options: 1700 1701SP Live Activation build options 1702~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1703 1704- ``SUPPORT_SP_LIVE_ACTIVATION``: Boolean option to enable live activation of 1705 Secure Partition(s) by using common SPMD LSP helpers. Enforces all of the 1706 following dependencies are met: 1707 1708 - ``LFA_SUPPORT=1`` to enable the live activation service in BL31. 1709 - ``ENABLE_SPMD_LP=1`` allows SPMD logical secure partition to be enabled. 1710 - ``SPMD_SPM_AT_SEL2=1`` as the current implementation only supports working 1711 with an S-EL2 SPMC (for example, Hafnium) to live activate an SP; It is 1712 incompatible with EL3 SPMC. 1713 1714 This flag is experimental and currently exercised on FVP. Default value is 0. 1715 1716Negative test scenario options 1717~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1718 1719- ``TEST_IO_SHORT_READ_FI``: Boolean flag to enable a negative-test for the 1720 BL image loader. When set to ``1``, TF-A intentionally simulates a short 1721 read for the image selected by ``TEST_IO_SHORT_READ_FI_IMAGE_ID`` by reporting 1722 fewer bytes read than the image size. This exercises the "read too short" 1723 error handling path in ``load_image()`` and is intended for test/CI only. 1724 Default is ``0`` (disabled). Must not be used on production devices. 1725 1726- ``TEST_IO_SHORT_READ_FI_IMAGE_ID``: Numeric flag that selects the ``image_id`` 1727 for which the short-read fault is injected when ``TEST_IO_SHORT_READ_FI=1``. 1728 The value must match the image identifiers used by the platform image loading 1729 flow (for example ``BL31_IMAGE_ID``, ``BL33_IMAGE_ID``, etc., depending on the 1730 build and platform). Default is ``0``. 1731 1732-------------- 1733 1734*Copyright (c) 2019-2026, Arm Limited. All rights reserved.* 1735 1736.. _DEN0115: https://developer.arm.com/docs/den0115/latest 1737.. _PSA FW update specification: https://developer.arm.com/documentation/den0118/latest/ 1738.. _PSA DRTM specification: https://developer.arm.com/documentation/den0113/a 1739.. _GCC: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html 1740.. _Clang: https://clang.llvm.org/docs/DiagnosticsReference.html 1741.. _Firmware Handoff specification: https://github.com/FirmwareHandoff/firmware_handoff/releases/tag/v0.9 1742.. _PSA Crypto API specification: https://armmbed.github.io/mbed-crypto/html/ 1743.. _Platform Initialization specification: https://uefi.org/specs/PI/1.8/index.html 1744.. _TF-A public mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/ 1745