1================
2ARM64 ELF hwcaps
3================
4
5This document describes the usage and semantics of the arm64 ELF hwcaps.
6
7
81. Introduction
9---------------
10
11Some hardware or software features are only available on some CPU
12implementations, and/or with certain kernel configurations, but have no
13architected discovery mechanism available to userspace code at EL0. The
14kernel exposes the presence of these features to userspace through a set
15of flags called hwcaps, exposed in the auxilliary vector.
16
17Userspace software can test for features by acquiring the AT_HWCAP or
18AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant
19flags 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
30Where software relies on a feature described by a hwcap, it should check
31the relevant hwcap flag to verify that the feature is present before
32attempting to make use of the feature.
33
34Features cannot be probed reliably through other means. When a feature
35is not available, attempting to use it may result in unpredictable
36behaviour, and is not guaranteed to result in any reliable indication
37that the feature is unavailable, such as a SIGILL.
38
39
402. Interpretation of hwcaps
41---------------------------
42
43The majority of hwcaps are intended to indicate the presence of features
44which are described by architected ID registers inaccessible to
45userspace code at EL0. These hwcaps are defined in terms of ID register
46fields, and should be interpreted with reference to the definition of
47these fields in the ARM Architecture Reference Manual (ARM ARM).
48
49Such hwcaps are described below in the form::
50
51    Functionality implied by idreg.field == val.
52
53Such hwcaps indicate the availability of functionality that the ARM ARM
54defines as being present when idreg.field has value val, but do not
55indicate that idreg.field is precisely equal to val, nor do they
56indicate the absence of functionality implied by other values of
57idreg.field.
58
59Other hwcaps may indicate the presence of features which cannot be
60described by ID registers alone. These may be described without
61reference to ID registers, and may refer to other documentation.
62
63
643. The hwcaps exposed in AT_HWCAP
65---------------------------------
66
67HWCAP_FP
68    Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.
69
70HWCAP_ASIMD
71    Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000.
72
73HWCAP_EVTSTRM
74    The generic timer is configured to generate events at a frequency of
75    approximately 100KHz.
76
77HWCAP_AES
78    Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0001.
79
80HWCAP_PMULL
81    Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0010.
82
83HWCAP_SHA1
84    Functionality implied by ID_AA64ISAR0_EL1.SHA1 == 0b0001.
85
86HWCAP_SHA2
87    Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0001.
88
89HWCAP_CRC32
90    Functionality implied by ID_AA64ISAR0_EL1.CRC32 == 0b0001.
91
92HWCAP_ATOMICS
93    Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0010.
94
95HWCAP_FPHP
96    Functionality implied by ID_AA64PFR0_EL1.FP == 0b0001.
97
98HWCAP_ASIMDHP
99    Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0001.
100
101HWCAP_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
107HWCAP_ASIMDRDM
108    Functionality implied by ID_AA64ISAR0_EL1.RDM == 0b0001.
109
110HWCAP_JSCVT
111    Functionality implied by ID_AA64ISAR1_EL1.JSCVT == 0b0001.
112
113HWCAP_FCMA
114    Functionality implied by ID_AA64ISAR1_EL1.FCMA == 0b0001.
115
116HWCAP_LRCPC
117    Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0001.
118
119HWCAP_DCPOP
120    Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0001.
121
122HWCAP_SHA3
123    Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.
124
125HWCAP_SM3
126    Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.
127
128HWCAP_SM4
129    Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.
130
131HWCAP_ASIMDDP
132    Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.
133
134HWCAP_SHA512
135    Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.
136
137HWCAP_SVE
138    Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.
139
140HWCAP_ASIMDFHM
141   Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.
142
143HWCAP_DIT
144    Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.
145
146HWCAP_USCAT
147    Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.
148
149HWCAP_ILRCPC
150    Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.
151
152HWCAP_FLAGM
153    Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.
154
155HWCAP_SSBS
156    Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010.
157
158HWCAP_SB
159    Functionality implied by ID_AA64ISAR1_EL1.SB == 0b0001.
160
161HWCAP_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
166HWCAP_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
171HWCAP2_DCPODP
172
173    Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
174
175HWCAP2_SVE2
176
177    Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001.
178
179HWCAP2_SVEAES
180
181    Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0001.
182
183HWCAP2_SVEPMULL
184
185    Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0010.
186
187HWCAP2_SVEBITPERM
188
189    Functionality implied by ID_AA64ZFR0_EL1.BitPerm == 0b0001.
190
191HWCAP2_SVESHA3
192
193    Functionality implied by ID_AA64ZFR0_EL1.SHA3 == 0b0001.
194
195HWCAP2_SVESM4
196
197    Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
198
199HWCAP2_FLAGM2
200
201    Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0010.
202
203HWCAP2_FRINT
204
205    Functionality implied by ID_AA64ISAR1_EL1.FRINTTS == 0b0001.
206
207HWCAP2_SVEI8MM
208
209    Functionality implied by ID_AA64ZFR0_EL1.I8MM == 0b0001.
210
211HWCAP2_SVEF32MM
212
213    Functionality implied by ID_AA64ZFR0_EL1.F32MM == 0b0001.
214
215HWCAP2_SVEF64MM
216
217    Functionality implied by ID_AA64ZFR0_EL1.F64MM == 0b0001.
218
219HWCAP2_SVEBF16
220
221    Functionality implied by ID_AA64ZFR0_EL1.BF16 == 0b0001.
222
223HWCAP2_I8MM
224
225    Functionality implied by ID_AA64ISAR1_EL1.I8MM == 0b0001.
226
227HWCAP2_BF16
228
229    Functionality implied by ID_AA64ISAR1_EL1.BF16 == 0b0001.
230
231HWCAP2_DGH
232
233    Functionality implied by ID_AA64ISAR1_EL1.DGH == 0b0001.
234
235HWCAP2_RNG
236
237    Functionality implied by ID_AA64ISAR0_EL1.RNDR == 0b0001.
238
239HWCAP2_BTI
240
241    Functionality implied by ID_AA64PFR0_EL1.BT == 0b0001.
242
243HWCAP2_MTE
244
245    Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0010, as described
246    by Documentation/arm64/memory-tagging-extension.rst.
247
2484. Unused AT_HWCAP bits
249-----------------------
250
251For interoperation with userspace, the kernel guarantees that bits 62
252and 63 of AT_HWCAP will always be returned as 0.
253