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 HWCAP_SHA3
 123     Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.
 124
 125 HWCAP_SM3
 126     Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.
 127
 128 HWCAP_SM4
 129     Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.
 130
 131 HWCAP_ASIMDDP
 132     Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.
 133
 134 HWCAP_SHA512
 135     Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.
 136
 137 HWCAP_SVE
 138     Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.
 139
 140 HWCAP_ASIMDFHM
 141    Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.
 142
 143 HWCAP_DIT
 144     Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.
 145
 146 HWCAP_USCAT
 147     Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.
 148
 149 HWCAP_ILRCPC
 150     Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.
 151
 152 HWCAP_FLAGM
 153     Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.
 154
 155 HWCAP_SSBS
 156     Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010.
 157
 158 HWCAP_SB
 159     Functionality implied by ID_AA64ISAR1_EL1.SB == 0b0001.
 160
 161 HWCAP_PACA
 162     Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or
 163     ID_AA64ISAR1_EL1.API == 0b0001, as described by
 164     Documentation/arm64/pointer-authentication.rst.
 165
 166 HWCAP_PACG
 167     Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or
 168     ID_AA64ISAR1_EL1.GPI == 0b0001, as described by
 169     Documentation/arm64/pointer-authentication.rst.
 170
 171 HWCAP2_DCPODP
 172
 173     Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
 174
 175 HWCAP2_SVE2
 176
 177     Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001.
 178
 179 HWCAP2_SVEAES
 180
 181     Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0001.
 182
 183 HWCAP2_SVEPMULL
 184
 185     Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0010.
 186
 187 HWCAP2_SVEBITPERM
 188
 189     Functionality implied by ID_AA64ZFR0_EL1.BitPerm == 0b0001.
 190
 191 HWCAP2_SVESHA3
 192
 193     Functionality implied by ID_AA64ZFR0_EL1.SHA3 == 0b0001.
 194
 195 HWCAP2_SVESM4
 196
 197     Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
 198
 199 HWCAP2_FLAGM2
 200
 201     Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0010.
 202
 203 HWCAP2_FRINT
 204
 205     Functionality implied by ID_AA64ISAR1_EL1.FRINTTS == 0b0001.
 206
 207
 208 4. Unused AT_HWCAP bits
 209 -----------------------
 210
 211 For interoperation with userspace, the kernel guarantees that bits 62
 212 and 63 of AT_HWCAP will always be returned as 0.