Documentation/arm64/elf_hwcaps.rst

   1 ================
   2 ARM64 ELF hwcaps
   3 ================
   4
   5 This document describes the usage and semantics of the arm64 ELF hwcaps.
   6
   7
   8 1. Introduction
   9 ---------------
  10
  11 Some hardware or software features are only available on some CPU
  12 implementations, and/or with certain kernel configurations, but have no
  13 architected discovery mechanism available to userspace code at EL0. The
  14 kernel exposes the presence of these features to userspace through a set
  15 of flags called hwcaps, exposed in the auxilliary vector.
  16
  17 Userspace software can test for features by acquiring the AT_HWCAP or
  18 AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant
  19 flags are set, e.g.::
  20
  21         bool floating_point_is_present(void)
  22         {
  23                 unsigned long hwcaps = getauxval(AT_HWCAP);
  24                 if (hwcaps & HWCAP_FP)
  25                         return true;
  26
  27                 return false;
  28         }
  29
  30 Where software relies on a feature described by a hwcap, it should check
  31 the relevant hwcap flag to verify that the feature is present before
  32 attempting to make use of the feature.
  33
  34 Features cannot be probed reliably through other means. When a feature
  35 is not available, attempting to use it may result in unpredictable
  36 behaviour, and is not guaranteed to result in any reliable indication
  37 that the feature is unavailable, such as a SIGILL.
  38
  39
  40 2. Interpretation of hwcaps
  41 ---------------------------
  42
  43 The majority of hwcaps are intended to indicate the presence of features
  44 which are described by architected ID registers inaccessible to
  45 userspace code at EL0. These hwcaps are defined in terms of ID register
  46 fields, and should be interpreted with reference to the definition of
  47 these fields in the ARM Architecture Reference Manual (ARM ARM).
  48
  49 Such hwcaps are described below in the form::
  50
  51     Functionality implied by idreg.field == val.
  52
  53 Such hwcaps indicate the availability of functionality that the ARM ARM
  54 defines as being present when idreg.field has value val, but do not
  55 indicate that idreg.field is precisely equal to val, nor do they
  56 indicate the absence of functionality implied by other values of
  57 idreg.field.
  58
  59 Other hwcaps may indicate the presence of features which cannot be
  60 described by ID registers alone. These may be described without
  61 reference to ID registers, and may refer to other documentation.
  62
  63
  64 3. The hwcaps exposed in AT_HWCAP
  65 ---------------------------------
  66
  67 HWCAP_FP
  68     Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.
  69
  70 HWCAP_ASIMD
  71     Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000.
  72
  73 HWCAP_EVTSTRM
  74     The generic timer is configured to generate events at a frequency of
  75     approximately 100KHz.
  76
  77 HWCAP_AES
  78     Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0001.
  79
  80 HWCAP_PMULL
  81     Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0010.
  82
  83 HWCAP_SHA1
  84     Functionality implied by ID_AA64ISAR0_EL1.SHA1 == 0b0001.
  85
  86 HWCAP_SHA2
  87     Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0001.
  88
  89 HWCAP_CRC32
  90     Functionality implied by ID_AA64ISAR0_EL1.CRC32 == 0b0001.
  91
  92 HWCAP_ATOMICS
  93     Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0010.
  94
  95 HWCAP_FPHP
  96     Functionality implied by ID_AA64PFR0_EL1.FP == 0b0001.
  97
  98 HWCAP_ASIMDHP
  99     Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0001.
 100
 101 HWCAP_CPUID
 102     EL0 access to certain ID registers is available, to the extent
 103     described by Documentation/arm64/cpu-feature-registers.rst.
 104
 105     These ID registers may imply the availability of features.
 106
 107 HWCAP_ASIMDRDM
 108     Functionality implied by ID_AA64ISAR0_EL1.RDM == 0b0001.
 109
 110 HWCAP_JSCVT
 111     Functionality implied by ID_AA64ISAR1_EL1.JSCVT == 0b0001.
 112
 113 HWCAP_FCMA
 114     Functionality implied by ID_AA64ISAR1_EL1.FCMA == 0b0001.
 115
 116 HWCAP_LRCPC
 117     Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0001.
 118
 119 HWCAP_DCPOP
 120     Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0001.
 121
 122 HWCAP2_DCPODP
 123
 124     Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
 125
 126 HWCAP_SHA3
 127     Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.
 128
 129 HWCAP_SM3
 130     Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.
 131
 132 HWCAP_SM4
 133     Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.
 134
 135 HWCAP_ASIMDDP
 136     Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.
 137
 138 HWCAP_SHA512
 139     Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.
 140
 141 HWCAP_SVE
 142     Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.
 143
 144 HWCAP2_SVE2
 145
 146     Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001.
 147
 148 HWCAP2_SVEAES
 149
 150     Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0001.
 151
 152 HWCAP2_SVEPMULL
 153
 154     Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0010.
 155
 156 HWCAP2_SVEBITPERM
 157
 158     Functionality implied by ID_AA64ZFR0_EL1.BitPerm == 0b0001.
 159
 160 HWCAP2_SVESHA3
 161
 162     Functionality implied by ID_AA64ZFR0_EL1.SHA3 == 0b0001.
 163
 164 HWCAP2_SVESM4
 165
 166     Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
 167
 168 HWCAP_ASIMDFHM
 169    Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.
 170
 171 HWCAP_DIT
 172     Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.
 173
 174 HWCAP_USCAT
 175     Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.
 176
 177 HWCAP_ILRCPC
 178     Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.
 179
 180 HWCAP_FLAGM
 181     Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.
 182
 183 HWCAP2_FLAGM2
 184
 185     Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0010.
 186
 187 HWCAP_SSBS
 188     Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010.
 189
 190 HWCAP_PACA
 191     Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or
 192     ID_AA64ISAR1_EL1.API == 0b0001, as described by
 193     Documentation/arm64/pointer-authentication.rst.
 194
 195 HWCAP_PACG
 196     Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or
 197     ID_AA64ISAR1_EL1.GPI == 0b0001, as described by
 198     Documentation/arm64/pointer-authentication.rst.
 199
 200 HWCAP2_FRINT
 201
 202     Functionality implied by ID_AA64ISAR1_EL1.FRINTTS == 0b0001.
 203
 204
 205 4. Unused AT_HWCAP bits
 206 -----------------------
 207
 208 For interoperation with userspace, the kernel guarantees that bits 62
 209 and 63 of AT_HWCAP will always be returned as 0.