1Architecture Features 2===================== 3 4The Arm architecture evolves through versioning, with new architectural features being introduced 5almost every year listed in `Feature_description`_. While most of these features require no control 6at EL3, some demand explicit configuration of EL3 control registers to enable their use at lower 7Exception Levels. For features with EL3 controls, it is relatively straightforward to examine the 8code and determine whether TF-A support them. However, for features that are transparent to EL3, it 9is more challenging to confirm whether they have been analyzed and verified as not requiring changes 10in TF-A. 11 12This document serves as a central reference point to track and clarify the support status of 13architectural features within TF-A. 14 15This document organizes features according to the yearly updates, while the specific architecture 16versions (8.X, 9.X) to which they apply can be found in `Feature_description`_ 17 18.. note:: 19 20 **Status legend** — 21 22 * ``OK``: TF-A has explicit support; 23 * ``NA``: Transparent from EL3 (no EL3 changes required); 24 * ``NO``: Analyzed but decided not to implement; 25 * ``WIP``: Implementation in progress; 26 * *(empty)*: Not analyzed. 27 282025 Extensions 29--------------- 30 31+-------------------------+--------+ 32| Feature | Status | 33+=========================+========+ 34| FEAT_GCIE | OK | 35+-------------------------+--------+ 36| FEAT_GCIE_LEGACY | NA | 37+-------------------------+--------+ 38| FEAT_F16F32DOT | NA | 39+-------------------------+--------+ 40| FEAT_F16F32MM | NA | 41+-------------------------+--------+ 42| FEAT_F16MM | NA | 43+-------------------------+--------+ 44| FEAT_SVE_B16MM | NA | 45+-------------------------+--------+ 46| FEAT_SME2p3 | NA | 47+-------------------------+--------+ 48| FEAT_MTE_EIRG | NA | 49+-------------------------+--------+ 50| FEAT_MTETC | NA | 51+-------------------------+--------+ 52| FEAT_SVE2p3 | NA | 53+-------------------------+--------+ 54| FEAT_SCR2 | | 55+-------------------------+--------+ 56| FEAT_LSCP | NA | 57+-------------------------+--------+ 58| FEAT_MPAMv2_VID | NA | 59+-------------------------+--------+ 60| FEAT_MPAMv2_MSC | NA | 61+-------------------------+--------+ 62| FEAT_MPAMv2_MSC_MON_SEC | NA | 63+-------------------------+--------+ 64| FEAT_MPAMv2_ALT_ID | NA | 65+-------------------------+--------+ 66| FEAT_MPAMv2 | | 67+-------------------------+--------+ 68| FEAT_FDIT | | 69+-------------------------+--------+ 70| FEAT_CMH | NA | 71+-------------------------+--------+ 72| FEAT_EAESR | NA | 73+-------------------------+--------+ 74| FEAT_TLBID | NA | 75+-------------------------+--------+ 76| FEAT_SRMASK2 | | 77+-------------------------+--------+ 78| FEAT_BBML3 | NA | 79+-------------------------+--------+ 80| FEAT_NV3 | | 81+-------------------------+--------+ 82| FEAT_PAuth_EnhCtl | | 83+-------------------------+--------+ 84| FEAT_LORRL | NA | 85+-------------------------+--------+ 86 872024 Extensions 88--------------- 89 90+-----------------------+--------+ 91| Feature | Status | 92+=======================+========+ 93| FEAT_PMUv3_EXTPMN | NA | 94+-----------------------+--------+ 95| FEAT_SPEv1p5 | NA | 96+-----------------------+--------+ 97| FEAT_SPE_EXC | | 98+-----------------------+--------+ 99| FEAT_SPE_nVM | | 100+-----------------------+--------+ 101| FEAT_TRBEv1p1 | NA | 102+-----------------------+--------+ 103| FEAT_TRBE_EXC | | 104+-----------------------+--------+ 105| FEAT_SME_MOP4 | NA | 106+-----------------------+--------+ 107| FEAT_SME_TMOP | NA | 108+-----------------------+--------+ 109| FEAT_PoPS | NA | 110+-----------------------+--------+ 111| FEAT_SME2p2 | NA | 112+-----------------------+--------+ 113| FEAT_CMPBR | NA | 114+-----------------------+--------+ 115| FEAT_SSVE_AES | NA | 116+-----------------------+--------+ 117| FEAT_RME_GPC3 | WIP | 118+-----------------------+--------+ 119| FEAT_RME_GDI | OK | 120+-----------------------+--------+ 121| FEAT_SVE2p2 | NA | 122+-----------------------+--------+ 123| FEAT_SSVE_BitPerm | NA | 124+-----------------------+--------+ 125| FEAT_SSVE_FEXPA | NA | 126+-----------------------+--------+ 127| FEAT_SVE_AES2 | NA | 128+-----------------------+--------+ 129| FEAT_LSFE | NA | 130+-----------------------+--------+ 131| FEAT_FPRCVT | NA | 132+-----------------------+--------+ 133| FEAT_SVE_F16F32MM | NA | 134+-----------------------+--------+ 135| FEAT_F8F16MM | NA | 136+-----------------------+--------+ 137| FEAT_F8F32MM | NA | 138+-----------------------+--------+ 139| FEAT_SVE_BFSCALE | NA | 140+-----------------------+--------+ 141| FEAT_OCCMO | NA | 142+-----------------------+--------+ 143| FEAT_LS64WB | NA | 144+-----------------------+--------+ 145| FEAT_AMU_EXTACR | NA | 146+-----------------------+--------+ 147| FEAT_MPAM_MSC_DOMAINS | NA | 148+-----------------------+--------+ 149| FEAT_MPAM_MSC_DCTRL | NA | 150+-----------------------+--------+ 151| FEAT_MPAM_PE_BW_CTRL | OK | 152+-----------------------+--------+ 153| FEAT_PCDPHINT | NA | 154+-----------------------+--------+ 155| FEAT_SRMASK | | 156+-----------------------+--------+ 157| FEAT_IDTE3 | OK | 158+-----------------------+--------+ 159| FEAT_UINJ | OK | 160+-----------------------+--------+ 161| FEAT_NV2p1 | NA | 162+-----------------------+--------+ 163| FEAT_LSUI | NA | 164+-----------------------+--------+ 165 1662023 Extensions 167--------------- 168 169+-------------------+--------+ 170| Feature | Status | 171+===================+========+ 172| FEAT_E2H0 | NA | 173+-------------------+--------+ 174| FEAT_SME_LUTv2 | NA | 175+-------------------+--------+ 176| FEAT_LUT | NA | 177+-------------------+--------+ 178| FEAT_FAMINMAX | NA | 179+-------------------+--------+ 180| FEAT_FPMR | OK | 181+-------------------+--------+ 182| FEAT_FP8 | NA | 183+-------------------+--------+ 184| FEAT_FP8FMA | NA | 185+-------------------+--------+ 186| FEAT_SSVE_FP8FMA | NA | 187+-------------------+--------+ 188| FEAT_FP8DOT4 | NA | 189+-------------------+--------+ 190| FEAT_SSVE_FP8DOT4 | NA | 191+-------------------+--------+ 192| FEAT_FP8DOT2 | NA | 193+-------------------+--------+ 194| FEAT_SSVE_FP8DOT2 | NA | 195+-------------------+--------+ 196| FEAT_SME_F8F16 | NA | 197+-------------------+--------+ 198| FEAT_SME_F8F32 | NA | 199+-------------------+--------+ 200| FEAT_CPA | NA | 201+-------------------+--------+ 202| FEAT_CPA2 | OK | 203+-------------------+--------+ 204| FEAT_STEP2 | OK | 205+-------------------+--------+ 206| FEAT_BWE2 | NA | 207+-------------------+--------+ 208| FEAT_SPE_FPF | NA | 209+-------------------+--------+ 210| FEAT_SPE_EFT | NA | 211+-------------------+--------+ 212| FEAT_PMUv3_TH2 | NA | 213+-------------------+--------+ 214| FEAT_SPMU2 | NA | 215+-------------------+--------+ 216| FEAT_E3DSE | | 217+-------------------+--------+ 218| FEAT_PMUv3_SME | NA | 219+-------------------+--------+ 220| FEAT_SPE_SME | NA | 221+-------------------+--------+ 222| FEAT_SPE_ALTCLK | NA | 223+-------------------+--------+ 224| FEAT_HDBSS | OK | 225+-------------------+--------+ 226| FEAT_HACDBS | OK | 227+-------------------+--------+ 228| FEAT_TLBIW | NA | 229+-------------------+--------+ 230| FEAT_ASID2 | NA | 231+-------------------+--------+ 232| FEAT_RME_GPC2 | OK | 233+-------------------+--------+ 234| FEAT_FGWTE3 | OK | 235+-------------------+--------+ 236| FEAT_PAuth_LR | OK | 237+-------------------+--------+ 238| FEAT_ETS3 | NA | 239+-------------------+--------+ 240 2412022 Extensions 242--------------- 243 244+--------------------------+--------+ 245| Feature | Status | 246+==========================+========+ 247| FEAT_BWE | NA | 248+--------------------------+--------+ 249| FEAT_ADERR | | 250+--------------------------+--------+ 251| FEAT_ANERR | | 252+--------------------------+--------+ 253| FEAT_DoubleFault2 | | 254+--------------------------+--------+ 255| FEAT_PFAR | OK | 256+--------------------------+--------+ 257| FEAT_RASv2 | | 258+--------------------------+--------+ 259| FEAT_CSSC | NA | 260+--------------------------+--------+ 261| FEAT_RPRFM | NA | 262+--------------------------+--------+ 263| FEAT_PRFMSLC | NA | 264+--------------------------+--------+ 265| FEAT_SPECRES2 | | 266+--------------------------+--------+ 267| FEAT_CLRBHB | Ok | 268+--------------------------+--------+ 269| FEAT_ECBHB | NA | 270+--------------------------+--------+ 271| FEAT_SME2p1 | NA | 272+--------------------------+--------+ 273| FEAT_SME_F16F16 | NA | 274+--------------------------+--------+ 275| FEAT_SVE_B16B16 | NA | 276+--------------------------+--------+ 277| FEAT_SME_B16B16 | NA | 278+--------------------------+--------+ 279| FEAT_FGT2 | OK | 280+--------------------------+--------+ 281| FEAT_MTE4 | NA | 282+--------------------------+--------+ 283| FEAT_MTE_CANONICAL_TAGS | NA | 284+--------------------------+--------+ 285| FEAT_MTE_NO_ADDRESS_TAGS | NA | 286+--------------------------+--------+ 287| FEAT_MTE_TAGGED_FAR | NA | 288+--------------------------+--------+ 289| FEAT_MTE_PERM | NA | 290+--------------------------+--------+ 291| FEAT_MTE_STORE_ONLY | NA | 292+--------------------------+--------+ 293| FEAT_ITE | NA | 294+--------------------------+--------+ 295| FEAT_TRBE_EXT | NA | 296+--------------------------+--------+ 297| FEAT_TRBE_MPAM | | 298+--------------------------+--------+ 299| FEAT_ETEv1p3 | NA | 300+--------------------------+--------+ 301| FEAT_GCS | OK | 302+--------------------------+--------+ 303| FEAT_CHK | NA | 304+--------------------------+--------+ 305| FEAT_SPE_DPFZS | NA | 306+--------------------------+--------+ 307| FEAT_SPE_CRR | NA | 308+--------------------------+--------+ 309| FEAT_EBEP | OK | 310+--------------------------+--------+ 311| FEAT_SEBEP | OK | 312+--------------------------+--------+ 313| FEAT_PMUv3_SS | | 314+--------------------------+--------+ 315| FEAT_SPMU | | 316+--------------------------+--------+ 317| FEAT_PMUv3_ICNTR | | 318+--------------------------+--------+ 319| FEAT_PMUv3p9 | OK | 320+--------------------------+--------+ 321| FEAT_SVE2p1 | NA | 322+--------------------------+--------+ 323| FEAT_Debugv8p9 | OK | 324+--------------------------+--------+ 325| FEAT_ABLE | NA | 326+--------------------------+--------+ 327| FEAT_PCSRv8p9 | NA | 328+--------------------------+--------+ 329| FEAT_LRCPC3 | NA | 330+--------------------------+--------+ 331| FEAT_SPEv1p4 | NA | 332+--------------------------+--------+ 333| FEAT_SPE_FDS | OK | 334+--------------------------+--------+ 335| FEAT_PMUv3_EDGE | NA | 336+--------------------------+--------+ 337| FEAT_D128 | OK | 338+--------------------------+--------+ 339| FEAT_AIE | OK | 340+--------------------------+--------+ 341| FEAT_S1PIE | OK | 342+--------------------------+--------+ 343| FEAT_ATS1A | NA | 344+--------------------------+--------+ 345| FEAT_S1POE | OK | 346+--------------------------+--------+ 347| FEAT_S2PIE | OK | 348+--------------------------+--------+ 349| FEAT_S2POE | OK | 350+--------------------------+--------+ 351| FEAT_SYSREG128 | OK | 352+--------------------------+--------+ 353| FEAT_SYSINSTR128 | NA | 354+--------------------------+--------+ 355| FEAT_LSE128 | NA | 356+--------------------------+--------+ 357| FEAT_HAFT | NA | 358+--------------------------+--------+ 359| FEAT_THE | OK | 360+--------------------------+--------+ 361| FEAT_LVA3 | NA | 362+--------------------------+--------+ 363| FEAT_MTE_ASYNC | NA | 364+--------------------------+--------+ 365| FEAT_EDHSR | NA | 366+--------------------------+--------+ 367| FEAT_AMU_EXT64 | NA | 368+--------------------------+--------+ 369 370 3712021 Extensions 372--------------- 373 374+------------------+--------+ 375| Feature | Status | 376+==================+========+ 377| FEAT_SME2 | OK | 378+------------------+--------+ 379| FEAT_MEC | OK | 380+------------------+--------+ 381| FEAT_BRBEv1p1 | WIP | 382+------------------+--------+ 383| FEAT_CMOW | NA | 384+------------------+--------+ 385| FEAT_Debugv8p8 | NA | 386+------------------+--------+ 387| FEAT_HBC | NA | 388+------------------+--------+ 389| FEAT_MOPS | OK | 390+------------------+--------+ 391| FEAT_NMI | OK | 392+------------------+--------+ 393| FEAT_SPEv1p3 | NA | 394+------------------+--------+ 395| FEAT_TIDCP1 | NA | 396+------------------+--------+ 397| FEAT_PMUv3_TH | NA | 398+------------------+--------+ 399| FEAT_PMUv3p8 | NA | 400+------------------+--------+ 401| FEAT_SCTLR2 | OK | 402+------------------+--------+ 403| FEAT_TCR2 | OK | 404+------------------+--------+ 405| FEAT_PMUv3_EXT64 | NA | 406+------------------+--------+ 407 408 4092020 Extensions 410--------------- 411 412+---------------------+--------+ 413| Feature | Status | 414+=====================+========+ 415| FEAT_EBF16 | NA | 416+---------------------+--------+ 417| FEAT_ETEv1p1 | NA | 418+---------------------+--------+ 419| FEAT_HCX | OK | 420+---------------------+--------+ 421| FEAT_PAN3 | OK | 422+---------------------+--------+ 423| FEAT_WFxT | NA | 424+---------------------+--------+ 425| FEAT_XS | NO | 426+---------------------+--------+ 427| FEAT_AFP | NA | 428+---------------------+--------+ 429| FEAT_RPRES | NA | 430+---------------------+--------+ 431| FEAT_LPA2 | NO | 432+---------------------+--------+ 433| FEAT_LS64 | NA | 434+---------------------+--------+ 435| FEAT_LS64_V | NA | 436+---------------------+--------+ 437| FEAT_LS64_ACCDATA | OK | 438+---------------------+--------+ 439| FEAT_MTE3 | NA | 440+---------------------+--------+ 441| FEAT_MTE_ASYM_FAULT | NA | 442+---------------------+--------+ 443| FEAT_SPEv1p2 | OK | 444+---------------------+--------+ 445| FEAT_SPE_FnE | NA | 446+---------------------+--------+ 447| FEAT_SPE_PBT | OK | 448+---------------------+--------+ 449| FEAT_PMUv3p7 | OK | 450+---------------------+--------+ 451 452The ``ENABLE_FEAT`` mechanism 453----------------------------- 454 455The Arm architecture defines several architecture extension features, named 456FEAT_xxx in the architecure manual. Some of those features require setup code in 457higher exception levels, other features might be used by TF-A code itself. 458 459Most of the feature flags defined in the TF-A build system are allowed to take 460the values 0, 1 or 2, with the following meaning: 461 462:: 463 464 ENABLE_FEAT_* = 0: Feature is unconditionally disabled at compile time. 465 ENABLE_FEAT_* = 1: Feature is unconditionally enabled at compile time. 466 ENABLE_FEAT_* = 2: Feature support is compiled in, but only enabled if the 467 feature present at runtime. 468 469When setting the flag to 0, the feature is disabled during compilation, and the 470compiler's optimization stage and the linker will try to remove as much of this 471code as possible. 472 473If it is defined to 1, the code will use the feature unconditionally, so the CPU 474is expected to support that feature. The FEATURE_DETECTION debug feature, if 475enabled, will verify this. 476 477If the feature flag is set to 2, support for the feature will be compiled in, 478but its existence will be checked at runtime, so it works on CPUs with or 479without the feature. This is mostly useful for platforms which either support 480multiple different CPUs, or where the CPU is configured at runtime, like in 481emulators. 482 483Adding support for a new feature 484-------------------------------- 485 486Adding support for a feature is required when: 487 488a) a feature is added to the architecture and it includes controls at EL3 489 490b) a feature is to be used by EL3 itself 491 492c) EL3 wants to hide a feature from lower ELs (eg. with ``FEAT_IDTE3``) 493 494The following is a checklist with guidance on what to do to add a new feature, 495in this case a fictional ``FEAT_ABC``. This is not an exhaustive list on how to 496do this, so please consult with previous such patches and/or maintainers. Please 497consult the Arm ARM on any specifics about the feature itself. 498 499- Add a feature flag to the build system. 500 501 - The flag's name should be in the form ``ENABLE_FEAT_ABC``. 502 503 - Add it to the ``assert_numerics`` and ``add_defines`` lists in the 504 ``Makefile``. 505 506 - Add a default of ``0`` for it in ``make_helpers/arch_features.mk``. If the 507 feature is listed as mandatory from a certain revision of the architecture, 508 add it to the appropriate list at the top of the same file. 509 510 - Add any constraints in ``make_helpers/constraints.mk``. This will usually be 511 other features which this feature depends on or is incompatible with and can 512 be found in the main description of the feature in the Arm ARM. 513 514- Add the feature accessor functions in ``include/arch/aarch64/arch_features.h``. 515 516 A pair of functions must be defined in the form of ``is_feat_abc_present()`` 517 and ``is_feat_abc_supported()``. Please use the provided macros to define 518 these. 519 520 - The ``_supported`` variant is the one that should usually be used. If common 521 code is to use it, a corresponding AArch32 version should be provided. It 522 should return ``false`` if AArch32 is not to be supported. 523 524 - In rare occasions, the feature must be checked in assembly. A 525 ``is_feat_abc_present_asm`` macro must be added to 526 ``include/lib/cpus/aarch64/cpu_macros.S``. 527 528- Register the feature in ``common/feat_detect.c``. 529 530- Register the feature in lib/extensions/idte/idte3.c. 531 532- Add support for the feature. This will be very feature specific and exact code 533 will depend on why support is being added. Usually, support will be a few 534 lines in ``lib/el3_runtime/aarch64/context_mgmt.c``. Some common things to do 535 include: 536 537 - If support requires more extensive code sequences, consider adding them to a 538 file in ``lib/extensions/abc/``. Functions in this file must be named 539 similar to other features. Those are likely to be ``abc_enable()``, 540 ``abc_enable_el3()``, or ``abc_disable()``. Naming depends on the call site. 541 542 - If the feature introduces ``SCR_EL3``, ``MDCR_EL3``, or ``CPTR_EL3`` controls 543 for lower ELs, access must be enabled for at least NS world, preferably all 544 worlds by setting/clearing the bit in the context copy of this register. 545 546 - If the feature introduces any control bits in ``SCR_EL3``, ``MDCR_EL3``, 547 ``CPTR_EL3``, or ``MPAM3_EL3``, those must be added to the appropriate list 548 in ``include/services/arm_arch_svc.h`` to register with 549 ``ARCH_FEATURE_AVAILABILITY``. This must also be done in the 550 ``test_smccc_arch_feature_availability`` test in TFTF, otherwise CI will 551 fail. 552 553 - If the feature comes with registers, those should be context switched if 554 enabling the feature for multiple worlds. 555 556 - Consider whether the feature introduces any potential side channels and how 557 to close them. 558 559- Add documentation in ``docs/getting_started/build-options.rst``. This should 560 include a brief description of what the enablement does, what values the flag 561 can take, the default, and that it conforms to the ``ENABLE_FEAT`` mechanism. 562 Adding feature enablement that does not conform to this mechanism is only done 563 in exceptional cases. You should also update the list of features at the top 564 of this file. 565 566- Enable the feature for the FVP platform in ``plat/arm/board/fvp/platform.mk``, 567 setting it to ``2`` (``FEAT_STATE_CHECKED``). 568 569- If the feature is optional, enable it in CI in the "allconfig" fragments. 570 Those are currently ``run_config/fvp-aemv8a.all.bmcov``, 571 ``run_config/fvp-spm.all.bmcov``, ``run_config/fvp-spm.all``, and 572 ``run_config/fvp-aemv8a.all``. Mandatory features are expected to be covered 573 by the architecture revision passed to the model. 574 575- Optionally, although recommended, is to add a test in TFTF. This should only 576 be done if there are observable effects from lower ELs like register traps. It 577 is not necessary to add a test for functionality that does not have EL3 578 involvement (eg. whether a new instruction that cannot trap works). 579 580.. _Feature_description: https://developer.arm.com/documentation/109697/latest/ 581