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 100KHz.
  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
 175     Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
 176
 177 HWCAP2_SVE2
 178
 179     Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001.
 180
 181 HWCAP2_SVEAES
 182
 183     Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0001.
 184
 185 HWCAP2_SVEPMULL
 186
 187     Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0010.
 188
 189 HWCAP2_SVEBITPERM
 190
 191     Functionality implied by ID_AA64ZFR0_EL1.BitPerm == 0b0001.
 192
 193 HWCAP2_SVESHA3
 194
 195     Functionality implied by ID_AA64ZFR0_EL1.SHA3 == 0b0001.
 196
 197 HWCAP2_SVESM4
 198
 199     Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
 200
 201 HWCAP2_FLAGM2
 202
 203     Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0010.
 204
 205 HWCAP2_FRINT
 206
 207     Functionality implied by ID_AA64ISAR1_EL1.FRINTTS == 0b0001.
 208
 209 HWCAP2_SVEI8MM
 210
 211     Functionality implied by ID_AA64ZFR0_EL1.I8MM == 0b0001.
 212
 213 HWCAP2_SVEF32MM
 214
 215     Functionality implied by ID_AA64ZFR0_EL1.F32MM == 0b0001.
 216
 217 HWCAP2_SVEF64MM
 218
 219     Functionality implied by ID_AA64ZFR0_EL1.F64MM == 0b0001.
 220
 221 HWCAP2_SVEBF16
 222
 223     Functionality implied by ID_AA64ZFR0_EL1.BF16 == 0b0001.
 224
 225 HWCAP2_I8MM
 226
 227     Functionality implied by ID_AA64ISAR1_EL1.I8MM == 0b0001.
 228
 229 HWCAP2_BF16
 230
 231     Functionality implied by ID_AA64ISAR1_EL1.BF16 == 0b0001.
 232
 233 HWCAP2_DGH
 234
 235     Functionality implied by ID_AA64ISAR1_EL1.DGH == 0b0001.
 236
 237 HWCAP2_RNG
 238
 239     Functionality implied by ID_AA64ISAR0_EL1.RNDR == 0b0001.
 240
 241 HWCAP2_BTI
 242
 243     Functionality implied by ID_AA64PFR0_EL1.BT == 0b0001.
 244
 245 HWCAP2_MTE
 246
 247     Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0010, as described
 248     by Documentation/arm64/memory-tagging-extension.rst.
 249
 250 4. Unused AT_HWCAP bits
 251 -----------------------
 252
 253 For interoperation with userspace, the kernel guarantees that bits 62
 254 and 63 of AT_HWCAP will always be returned as 0.