Documentation/arm64/elf_hwcaps.rst

   1 .. _elf_hwcaps_index:
   2
   3 ================
   4 ARM64 ELF hwcaps
   5 ================
   6
   7 This document describes the usage and semantics of the arm64 ELF hwcaps.
   8
   9
  10 1. Introduction
  11 ---------------
  12
  13 Some hardware or software features are only available on some CPU
  14 implementations, and/or with certain kernel configurations, but have no
  15 architected discovery mechanism available to userspace code at EL0. The
  16 kernel exposes the presence of these features to userspace through a set
  17 of flags called hwcaps, exposed in the auxilliary vector.
  18
  19 Userspace software can test for features by acquiring the AT_HWCAP or
  20 AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant
  21 flags are set, e.g.::
  22
  23         bool floating_point_is_present(void)
  24         {
  25                 unsigned long hwcaps = getauxval(AT_HWCAP);
  26                 if (hwcaps & HWCAP_FP)
  27                         return true;
  28
  29                 return false;
  30         }
  31
  32 Where software relies on a feature described by a hwcap, it should check
  33 the relevant hwcap flag to verify that the feature is present before
  34 attempting to make use of the feature.
  35
  36 Features cannot be probed reliably through other means. When a feature
  37 is not available, attempting to use it may result in unpredictable
  38 behaviour, and is not guaranteed to result in any reliable indication
  39 that the feature is unavailable, such as a SIGILL.
  40
  41
  42 2. Interpretation of hwcaps
  43 ---------------------------
  44
  45 The majority of hwcaps are intended to indicate the presence of features
  46 which are described by architected ID registers inaccessible to
  47 userspace code at EL0. These hwcaps are defined in terms of ID register
  48 fields, and should be interpreted with reference to the definition of
  49 these fields in the ARM Architecture Reference Manual (ARM ARM).
  50
  51 Such hwcaps are described below in the form::
  52
  53     Functionality implied by idreg.field == val.
  54
  55 Such hwcaps indicate the availability of functionality that the ARM ARM
  56 defines as being present when idreg.field has value val, but do not
  57 indicate that idreg.field is precisely equal to val, nor do they
  58 indicate the absence of functionality implied by other values of
  59 idreg.field.
  60
  61 Other hwcaps may indicate the presence of features which cannot be
  62 described by ID registers alone. These may be described without
  63 reference to ID registers, and may refer to other documentation.
  64
  65
  66 3. The hwcaps exposed in AT_HWCAP
  67 ---------------------------------
  68
  69 HWCAP_FP
  70     Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.
  71
  72 HWCAP_ASIMD
  73     Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000.
  74
  75 HWCAP_EVTSTRM
  76     The generic timer is configured to generate events at a frequency of
  77     approximately 10KHz.
  78
  79 HWCAP_AES
  80     Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0001.
  81
  82 HWCAP_PMULL
  83     Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0010.
  84
  85 HWCAP_SHA1
  86     Functionality implied by ID_AA64ISAR0_EL1.SHA1 == 0b0001.
  87
  88 HWCAP_SHA2
  89     Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0001.
  90
  91 HWCAP_CRC32
  92     Functionality implied by ID_AA64ISAR0_EL1.CRC32 == 0b0001.
  93
  94 HWCAP_ATOMICS
  95     Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0010.
  96
  97 HWCAP_FPHP
  98     Functionality implied by ID_AA64PFR0_EL1.FP == 0b0001.
  99
 100 HWCAP_ASIMDHP
 101     Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0001.
 102
 103 HWCAP_CPUID
 104     EL0 access to certain ID registers is available, to the extent
 105     described by Documentation/arm64/cpu-feature-registers.rst.
 106
 107     These ID registers may imply the availability of features.
 108
 109 HWCAP_ASIMDRDM
 110     Functionality implied by ID_AA64ISAR0_EL1.RDM == 0b0001.
 111
 112 HWCAP_JSCVT
 113     Functionality implied by ID_AA64ISAR1_EL1.JSCVT == 0b0001.
 114
 115 HWCAP_FCMA
 116     Functionality implied by ID_AA64ISAR1_EL1.FCMA == 0b0001.
 117
 118 HWCAP_LRCPC
 119     Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0001.
 120
 121 HWCAP_DCPOP
 122     Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0001.
 123
 124 HWCAP_SHA3
 125     Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.
 126
 127 HWCAP_SM3
 128     Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.
 129
 130 HWCAP_SM4
 131     Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.
 132
 133 HWCAP_ASIMDDP
 134     Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.
 135
 136 HWCAP_SHA512
 137     Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.
 138
 139 HWCAP_SVE
 140     Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.
 141
 142 HWCAP_ASIMDFHM
 143    Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.
 144
 145 HWCAP_DIT
 146     Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.
 147
 148 HWCAP_USCAT
 149     Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.
 150
 151 HWCAP_ILRCPC
 152     Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.
 153
 154 HWCAP_FLAGM
 155     Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.
 156
 157 HWCAP_SSBS
 158     Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010.
 159
 160 HWCAP_SB
 161     Functionality implied by ID_AA64ISAR1_EL1.SB == 0b0001.
 162
 163 HWCAP_PACA
 164     Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or
 165     ID_AA64ISAR1_EL1.API == 0b0001, as described by
 166     Documentation/arm64/pointer-authentication.rst.
 167
 168 HWCAP_PACG
 169     Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or
 170     ID_AA64ISAR1_EL1.GPI == 0b0001, as described by
 171     Documentation/arm64/pointer-authentication.rst.
 172
 173 HWCAP2_DCPODP
 174     Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
 175
 176 HWCAP2_SVE2
 177     Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001.
 178
 179 HWCAP2_SVEAES
 180     Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0001.
 181
 182 HWCAP2_SVEPMULL
 183     Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0010.
 184
 185 HWCAP2_SVEBITPERM
 186     Functionality implied by ID_AA64ZFR0_EL1.BitPerm == 0b0001.
 187
 188 HWCAP2_SVESHA3
 189     Functionality implied by ID_AA64ZFR0_EL1.SHA3 == 0b0001.
 190
 191 HWCAP2_SVESM4
 192     Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
 193
 194 HWCAP2_FLAGM2
 195     Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0010.
 196
 197 HWCAP2_FRINT
 198     Functionality implied by ID_AA64ISAR1_EL1.FRINTTS == 0b0001.
 199
 200 HWCAP2_SVEI8MM
 201     Functionality implied by ID_AA64ZFR0_EL1.I8MM == 0b0001.
 202
 203 HWCAP2_SVEF32MM
 204     Functionality implied by ID_AA64ZFR0_EL1.F32MM == 0b0001.
 205
 206 HWCAP2_SVEF64MM
 207     Functionality implied by ID_AA64ZFR0_EL1.F64MM == 0b0001.
 208
 209 HWCAP2_SVEBF16
 210     Functionality implied by ID_AA64ZFR0_EL1.BF16 == 0b0001.
 211
 212 HWCAP2_I8MM
 213     Functionality implied by ID_AA64ISAR1_EL1.I8MM == 0b0001.
 214
 215 HWCAP2_BF16
 216     Functionality implied by ID_AA64ISAR1_EL1.BF16 == 0b0001.
 217
 218 HWCAP2_DGH
 219     Functionality implied by ID_AA64ISAR1_EL1.DGH == 0b0001.
 220
 221 HWCAP2_RNG
 222     Functionality implied by ID_AA64ISAR0_EL1.RNDR == 0b0001.
 223
 224 HWCAP2_BTI
 225     Functionality implied by ID_AA64PFR0_EL1.BT == 0b0001.
 226
 227 HWCAP2_MTE
 228     Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0010, as described
 229     by Documentation/arm64/memory-tagging-extension.rst.
 230
 231 HWCAP2_ECV
 232     Functionality implied by ID_AA64MMFR0_EL1.ECV == 0b0001.
 233
 234 HWCAP2_AFP
 235     Functionality implied by ID_AA64MFR1_EL1.AFP == 0b0001.
 236
 237 HWCAP2_RPRES
 238     Functionality implied by ID_AA64ISAR2_EL1.RPRES == 0b0001.
 239
 240 HWCAP2_MTE3
 241     Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0011, as described
 242     by Documentation/arm64/memory-tagging-extension.rst.
 243
 244 HWCAP2_SME
 245     Functionality implied by ID_AA64PFR1_EL1.SME == 0b0001, as described
 246     by Documentation/arm64/sme.rst.
 247
 248 HWCAP2_SME_I16I64
 249     Functionality implied by ID_AA64SMFR0_EL1.I16I64 == 0b1111.
 250
 251 HWCAP2_SME_F64F64
 252     Functionality implied by ID_AA64SMFR0_EL1.F64F64 == 0b1.
 253
 254 HWCAP2_SME_I8I32
 255     Functionality implied by ID_AA64SMFR0_EL1.I8I32 == 0b1111.
 256
 257 HWCAP2_SME_F16F32
 258     Functionality implied by ID_AA64SMFR0_EL1.F16F32 == 0b1.
 259
 260 HWCAP2_SME_B16F32
 261     Functionality implied by ID_AA64SMFR0_EL1.B16F32 == 0b1.
 262
 263 HWCAP2_SME_F32F32
 264     Functionality implied by ID_AA64SMFR0_EL1.F32F32 == 0b1.
 265
 266 HWCAP2_SME_FA64
 267     Functionality implied by ID_AA64SMFR0_EL1.FA64 == 0b1.
 268
 269 HWCAP2_WFXT
 270     Functionality implied by ID_AA64ISAR2_EL1.WFXT == 0b0010.
 271
 272 HWCAP2_EBF16
 273     Functionality implied by ID_AA64ISAR1_EL1.BF16 == 0b0010.
 274
 275 HWCAP2_SVE_EBF16
 276     Functionality implied by ID_AA64ZFR0_EL1.BF16 == 0b0010.
 277
 278 4. Unused AT_HWCAP bits
 279 -----------------------
 280
 281 For interoperation with userspace, the kernel guarantees that bits 62
 282 and 63 of AT_HWCAP will always be returned as 0.