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