1 .. SPDX-License-Identifier: GPL-2.0
2
3 =================
4 x86 Feature Flags
5 =================
6
7 Introduction
8 ============
9
10 The list of feature flags in /proc/cpuinfo is
11 represents an ill-fated attempt from long time
12 in an easy to find place for userspace.
13
14 However, the amount of feature flags is growin
15 leading to unparseable and unwieldy /proc/cpui
16
17 What is more, those feature flags do not even
18 because userspace doesn't care about them - gl
19 CPUID to find out what the target machine supp
20
21 And even if it doesn't show a particular featu
22 still does have support for the respective har
23 said CPU supports CPUID faulting - userspace c
24 feature and figure out if it is supported or n
25 it is being advertised somewhere.
26
27 Furthermore, those flag strings become an ABI
28 there and maintaining them forever when nothin
29 of wasted effort.
30
31 So, the current use of /proc/cpuinfo is to sho
32 kernel has *enabled* and *supports*. As in: th
33 there, there's an additional setup which the k
34 booting and the functionality is ready to use.
35 that is "user_shstk" where additional code ena
36 kernel to support shadow stack for user progra
37
38 So, if users want to know if a feature is avai
39 they try to find the flag in /proc/cpuinfo. If
40 it means that
41
42 * the kernel knows about the feature enough to
43
44 * the kernel supports it and is currently maki
45 userspace or some other part of the kernel
46
47 * if the flag represents a hardware feature th
48
49 The absence of a flag in /proc/cpuinfo by itse
50 an end user.
51
52 On the one hand, a feature like "vaes" might b
53 applications on a kernel that has not defined
54 there is no "vaes" in /proc/cpuinfo.
55
56 On the other hand, a new kernel running on non
57 have no "vaes" in /proc/cpuinfo. There's no w
58 user to tell the difference.
59
60 The end result is that the flags field in /pro
61 useful for kernel debugging, but not really fo
62 Applications should instead use things like th
63 querying CPU support. Users should rely on to
64 tools/arch/x86/kcpuid and cpuid(1).
65
66 Regarding implementation, flags appearing in /
67 X86_FEATURE definition in arch/x86/include/asm
68 represent hardware features as well as softwar
69
70 If the kernel cares about a feature or KVM wan
71 a KVM guest, it should only then expose it to
72 needs to parse /proc/cpuinfo. Which, as mentio
73 unlikely. KVM can synthesize the CPUID bit and
74 query CPUID and figure out what the hypervisor
75 already stated, /proc/cpuinfo is not a dumping
76 feature flags.
77
78
79 How are feature flags created?
80 ==============================
81
82 a: Feature flags can be derived from the conte
83 ----------------------------------------------
84 These feature definitions are organized mirror
85 leaves and grouped in words with offsets as ma
86 in cpufeatures.h (see arch/x86/include/asm/cpu
87 If a feature is defined with a X86_FEATURE_<na
88 cpufeatures.h, and if it is detected at run ti
89 displayed accordingly in /proc/cpuinfo. For ex
90 comes from X86_FEATURE_AVX2 in cpufeatures.h.
91
92 b: Flags can be from scattered CPUID-based fea
93 ----------------------------------------------
94 Hardware features enumerated in sparsely popul
95 software-defined values. Still, CPUID needs to
96 if a given feature is present. This is done in
97 For instance, X86_FEATURE_CQM_LLC is defined a
98 checked at runtime in the respective CPUID lea
99
100 The intent of scattering CPUID leaves is to no
101 cpuinfo_x86.x86_capability[] unnecessarily. Fo
102 [EAX=7, ECX=0] has 30 features and is dense, b
103 has only one feature and would waste 31 bits o
104 array. Since there is a struct cpuinfo_x86 for
105 memory is not trivial.
106
107 c: Flags can be created synthetically under ce
108 ----------------------------------------------
109 Examples of conditions include whether certain
110 MSR_IA32_CORE_CAPS or specific CPU models are
111 conditions are met, the features are enabled b
112 setup_force_cpu_cap macros. For example, if bi
113 the feature X86_FEATURE_SPLIT_LOCK_DETECT will
114 "split_lock_detect" will be displayed. The fla
115 displayed only when running on INTEL_XEON_PHI_
116
117 d: Flags can represent purely software feature
118 ----------------------------------------------
119 These flags do not represent hardware features
120 software feature implemented in the kernel. Fo
121 Isolation is purely software feature and its f
122 also defined in cpufeatures.h.
123
124 Naming of Flags
125 ===============
126
127 The script arch/x86/kernel/cpu/mkcapflags.sh p
128 #define X86_FEATURE_<name> from cpufeatures.h
129 x86_cap/bug_flags[] arrays in kernel/cpu/capfl
130 resulting x86_cap/bug_flags[] are used to popu
131 of flags in the x86_cap/bug_flags[] are as fol
132
133 a: The name of the flag is from the string in
134 ----------------------------------------------
135 By default, the flag <name> in /proc/cpuinfo i
136 X86_FEATURE_<name> in cpufeatures.h. For examp
137 X86_FEATURE_AVX2.
138
139 b: The naming can be overridden.
140 --------------------------------
141 If the comment on the line for the #define X86
142 double-quote character (""), the string inside
143 will be the name of the flags. For example, th
144 the comment "sse4_1" following the X86_FEATURE
145
146 There are situations in which overriding the d
147 needed. For instance, /proc/cpuinfo is a users
148 constant. If, for some reason, the naming of X
149 shall override the new naming with the name al
150
151 c: The naming override can be "", which means
152 ----------------------------------------------
153 The feature shall be omitted from /proc/cpuinf
154 the feature to be exposed to userspace. For ex
155 defined in cpufeatures.h but that flag is an i
156 in the alternative runtime patching functional
157 with "". Its flag will not appear in /proc/cpu
158
159 Flags are missing when one or more of these ha
160 ==============================================
161
162 a: The hardware does not enumerate support for
163 ----------------------------------------------
164 For example, when a new kernel is running on o
165 not enabled by boot firmware. Even if the hard
166 problem enabling the feature at run time, the
167
168 b: The kernel does not know about the flag.
169 -------------------------------------------
170 For example, when an old kernel is running on
171
172 c: The kernel disabled support for it at compi
173 ----------------------------------------------
174 For example, if 5-level-paging is not enabled
175 CONFIG_X86_5LEVEL is not selected) the flag "l
176 Even though the feature will still be detected
177 it by clearing via setup_clear_cpu_cap(X86_FEA
178
179 d: The feature is disabled at boot-time.
180 ----------------------------------------
181 A feature can be disabled either using a comma
182 it failed to be enabled. The command-line para
183 to disable features using the feature number a
184 /arch/x86/include/asm/cpufeatures.h. For insta
185 Protection can be disabled using clearcpuid=51
186 from #define X86_FEATURE_UMIP (16*32 + 2).
187
188 In addition, there exists a variety of custom
189 disable specific features. The list of paramet
190 to, nofsgsbase, nosgx, noxsave, etc. 5-level p
191 "no5lvl".
192
193 e: The feature was known to be non-functional.
194 ----------------------------------------------
195 The feature was known to be non-functional bec
196 missing at runtime. For example, AVX flags wil
197 is disabled since they depend on XSAVE feature
198 CPUs and them missing microcode patches. Due t
199 enable a feature.
200
201 .. [#f1] 5-level paging uses linear address of
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.