@@ -79,8 +79,9 @@ feature flags.
7979How are feature flags created?
8080==============================
8181
82- a: Feature flags can be derived from the contents of CPUID leaves.
83- ------------------------------------------------------------------
82+ Feature flags can be derived from the contents of CPUID leaves
83+ --------------------------------------------------------------
84+
8485These feature definitions are organized mirroring the layout of CPUID
8586leaves and grouped in words with offsets as mapped in enum cpuid_leafs
8687in cpufeatures.h (see arch/x86/include/asm/cpufeatures.h for details).
@@ -89,8 +90,9 @@ cpufeatures.h, and if it is detected at run time, the flags will be
8990displayed accordingly in /proc/cpuinfo. For example, the flag "avx2"
9091comes from X86_FEATURE_AVX2 in cpufeatures.h.
9192
92- b: Flags can be from scattered CPUID-based features.
93- ----------------------------------------------------
93+ Flags can be from scattered CPUID-based features
94+ ------------------------------------------------
95+
9496Hardware features enumerated in sparsely populated CPUID leaves get
9597software-defined values. Still, CPUID needs to be queried to determine
9698if a given feature is present. This is done in init_scattered_cpuid_features().
@@ -104,8 +106,9 @@ has only one feature and would waste 31 bits of space in the x86_capability[]
104106array. Since there is a struct cpuinfo_x86 for each possible CPU, the wasted
105107memory is not trivial.
106108
107- c: Flags can be created synthetically under certain conditions for hardware features.
108- -------------------------------------------------------------------------------------
109+ Flags can be created synthetically under certain conditions for hardware features
110+ ---------------------------------------------------------------------------------
111+
109112Examples of conditions include whether certain features are present in
110113MSR_IA32_CORE_CAPS or specific CPU models are identified. If the needed
111114conditions are met, the features are enabled by the set_cpu_cap or
@@ -114,8 +117,8 @@ the feature X86_FEATURE_SPLIT_LOCK_DETECT will be enabled and
114117"split_lock_detect" will be displayed. The flag "ring3mwait" will be
115118displayed only when running on INTEL_XEON_PHI_[KNL|KNM] processors.
116119
117- d: Flags can represent purely software features.
118- ------------------------------------------------
120+ Flags can represent purely software features
121+ --------------------------------------------
119122These flags do not represent hardware features. Instead, they represent a
120123software feature implemented in the kernel. For example, Kernel Page Table
121124Isolation is purely software feature and its feature flag X86_FEATURE_PTI is
@@ -130,17 +133,17 @@ x86_cap/bug_flags[] arrays in kernel/cpu/capflags.c. The names in the
130133resulting x86_cap/bug_flags[] are used to populate /proc/cpuinfo. The naming
131134of flags in the x86_cap/bug_flags[] are as follows:
132135
133- a: Flags do not appear by default in /proc/cpuinfo
134- --------------------------------------------------
136+ Flags do not appear by default in /proc/cpuinfo
137+ -----------------------------------------------
135138
136139Feature flags are omitted by default from /proc/cpuinfo as it does not make
137140sense for the feature to be exposed to userspace in most cases. For example,
138141X86_FEATURE_ALWAYS is defined in cpufeatures.h but that flag is an internal
139142kernel feature used in the alternative runtime patching functionality. So the
140143flag does not appear in /proc/cpuinfo.
141144
142- b: Specify a flag name if absolutely needed
143- -------------------------------------------
145+ Specify a flag name if absolutely needed
146+ ----------------------------------------
144147
145148If the comment on the line for the #define X86_FEATURE_* starts with a
146149double-quote character (""), the string inside the double-quote characters
@@ -155,25 +158,28 @@ shall override the new naming with the name already used in /proc/cpuinfo.
155158Flags are missing when one or more of these happen
156159==================================================
157160
158- a: The hardware does not enumerate support for it.
159- --------------------------------------------------
161+ The hardware does not enumerate support for it
162+ ----------------------------------------------
163+
160164For example, when a new kernel is running on old hardware or the feature is
161165not enabled by boot firmware. Even if the hardware is new, there might be a
162166problem enabling the feature at run time, the flag will not be displayed.
163167
164- b: The kernel does not know about the flag.
165- -------------------------------------------
168+ The kernel does not know about the flag
169+ ---------------------------------------
170+
166171For example, when an old kernel is running on new hardware.
167172
168- c: The kernel disabled support for it at compile-time.
169- ------------------------------------------------------
173+ The kernel disabled support for it at compile-time
174+ --------------------------------------------------
175+
170176For example, if 5-level-paging is not enabled when building (i.e.,
171177CONFIG_X86_5LEVEL is not selected) the flag "la57" will not show up [#f1 ]_.
172178Even though the feature will still be detected via CPUID, the kernel disables
173179it by clearing via setup_clear_cpu_cap(X86_FEATURE_LA57).
174180
175- d: The feature is disabled at boot-time.
176- ----------------------------------------
181+ The feature is disabled at boot-time
182+ ------------------------------------
177183A feature can be disabled either using a command-line parameter or because
178184it failed to be enabled. The command-line parameter clearcpuid= can be used
179185to disable features using the feature number as defined in
@@ -186,8 +192,9 @@ disable specific features. The list of parameters includes, but is not limited
186192to, nofsgsbase, nosgx, noxsave, etc. 5-level paging can also be disabled using
187193"no5lvl".
188194
189- e: The feature was known to be non-functional.
190- ----------------------------------------------
195+ The feature was known to be non-functional
196+ ------------------------------------------
197+
191198The feature was known to be non-functional because a dependency was
192199missing at runtime. For example, AVX flags will not show up if XSAVE feature
193200is disabled since they depend on XSAVE feature. Another example would be broken
0 commit comments