1.. SPDX-License-Identifier: GPL-2.0 2 3================= 4x86 Feature Flags 5================= 6 7Introduction 8============ 9 10The list of feature flags in /proc/cpuinfo is not complete and 11represents an ill-fated attempt from long time ago to put feature flags 12in an easy to find place for userspace. 13 14However, the amount of feature flags is growing by the CPU generation, 15leading to unparseable and unwieldy /proc/cpuinfo. 16 17What is more, those feature flags do not even need to be in that file 18because userspace doesn't care about them - glibc et al already use 19CPUID to find out what the target machine supports and what not. 20 21And even if it doesn't show a particular feature flag - although the CPU 22still does have support for the respective hardware functionality and 23said CPU supports CPUID faulting - userspace can simply probe for the 24feature and figure out if it is supported or not, regardless of whether 25it is being advertised somewhere. 26 27Furthermore, those flag strings become an ABI the moment they appear 28there and maintaining them forever when nothing even uses them is a lot 29of wasted effort. 30 31So, the current use of /proc/cpuinfo is to show features which the 32kernel has *enabled* and *supports*. As in: the CPUID feature flag is 33there, there's an additional setup which the kernel has done while 34booting and the functionality is ready to use. A perfect example for 35that is "user_shstk" where additional code enablement is present in the 36kernel to support shadow stack for user programs. 37 38So, if users want to know if a feature is available on a given system, 39they try to find the flag in /proc/cpuinfo. If a given flag is present, 40it means that 41 42* the kernel knows about the feature enough to have an X86_FEATURE bit 43 44* the kernel supports it and is currently making it available either to 45 userspace or some other part of the kernel 46 47* if the flag represents a hardware feature the hardware supports it. 48 49The absence of a flag in /proc/cpuinfo by itself means almost nothing to 50an end user. 51 52On the one hand, a feature like "vaes" might be fully available to user 53applications on a kernel that has not defined X86_FEATURE_VAES and thus 54there is no "vaes" in /proc/cpuinfo. 55 56On the other hand, a new kernel running on non-VAES hardware would also 57have no "vaes" in /proc/cpuinfo. There's no way for an application or 58user to tell the difference. 59 60The end result is that the flags field in /proc/cpuinfo is marginally 61useful for kernel debugging, but not really for anything else. 62Applications should instead use things like the glibc facilities for 63querying CPU support. Users should rely on tools like 64tools/arch/x86/kcpuid and cpuid(1). 65 66Regarding implementation, flags appearing in /proc/cpuinfo have an 67X86_FEATURE definition in arch/x86/include/asm/cpufeatures.h. These flags 68represent hardware features as well as software features. 69 70If the kernel cares about a feature or KVM want to expose the feature to 71a KVM guest, it should only then expose it to the guest when the guest 72needs to parse /proc/cpuinfo. Which, as mentioned above, is highly 73unlikely. KVM can synthesize the CPUID bit and the KVM guest can simply 74query CPUID and figure out what the hypervisor supports and what not. As 75already stated, /proc/cpuinfo is not a dumping ground for useless 76feature flags. 77 78 79How are feature flags created? 80============================== 81 82a: Feature flags can be derived from the contents of CPUID leaves. 83------------------------------------------------------------------ 84These feature definitions are organized mirroring the layout of CPUID 85leaves and grouped in words with offsets as mapped in enum cpuid_leafs 86in cpufeatures.h (see arch/x86/include/asm/cpufeatures.h for details). 87If a feature is defined with a X86_FEATURE_<name> definition in 88cpufeatures.h, and if it is detected at run time, the flags will be 89displayed accordingly in /proc/cpuinfo. For example, the flag "avx2" 90comes from X86_FEATURE_AVX2 in cpufeatures.h. 91 92b: Flags can be from scattered CPUID-based features. 93---------------------------------------------------- 94Hardware features enumerated in sparsely populated CPUID leaves get 95software-defined values. Still, CPUID needs to be queried to determine 96if a given feature is present. This is done in init_scattered_cpuid_features(). 97For instance, X86_FEATURE_CQM_LLC is defined as 11*32 + 0 and its presence is 98checked at runtime in the respective CPUID leaf [EAX=f, ECX=0] bit EDX[1]. 99 100The intent of scattering CPUID leaves is to not bloat struct 101cpuinfo_x86.x86_capability[] unnecessarily. For instance, the CPUID leaf 102[EAX=7, ECX=0] has 30 features and is dense, but the CPUID leaf [EAX=7, EAX=1] 103has only one feature and would waste 31 bits of space in the x86_capability[] 104array. Since there is a struct cpuinfo_x86 for each possible CPU, the wasted 105memory is not trivial. 106 107c: Flags can be created synthetically under certain conditions for hardware features. 108------------------------------------------------------------------------------------- 109Examples of conditions include whether certain features are present in 110MSR_IA32_CORE_CAPS or specific CPU models are identified. If the needed 111conditions are met, the features are enabled by the set_cpu_cap or 112setup_force_cpu_cap macros. For example, if bit 5 is set in MSR_IA32_CORE_CAPS, 113the feature X86_FEATURE_SPLIT_LOCK_DETECT will be enabled and 114"split_lock_detect" will be displayed. The flag "ring3mwait" will be 115displayed only when running on INTEL_FAM6_XEON_PHI_[KNL|KNM] processors. 116 117d: Flags can represent purely software features. 118------------------------------------------------ 119These flags do not represent hardware features. Instead, they represent a 120software feature implemented in the kernel. For example, Kernel Page Table 121Isolation is purely software feature and its feature flag X86_FEATURE_PTI is 122also defined in cpufeatures.h. 123 124Naming of Flags 125=============== 126 127The script arch/x86/kernel/cpu/mkcapflags.sh processes the 128#define X86_FEATURE_<name> from cpufeatures.h and generates the 129x86_cap/bug_flags[] arrays in kernel/cpu/capflags.c. The names in the 130resulting x86_cap/bug_flags[] are used to populate /proc/cpuinfo. The naming 131of flags in the x86_cap/bug_flags[] are as follows: 132 133a: The name of the flag is from the string in X86_FEATURE_<name> by default. 134---------------------------------------------------------------------------- 135By default, the flag <name> in /proc/cpuinfo is extracted from the respective 136X86_FEATURE_<name> in cpufeatures.h. For example, the flag "avx2" is from 137X86_FEATURE_AVX2. 138 139b: The naming can be overridden. 140-------------------------------- 141If the comment on the line for the #define X86_FEATURE_* starts with a 142double-quote character (""), the string inside the double-quote characters 143will be the name of the flags. For example, the flag "sse4_1" comes from 144the comment "sse4_1" following the X86_FEATURE_XMM4_1 definition. 145 146There are situations in which overriding the displayed name of the flag is 147needed. For instance, /proc/cpuinfo is a userspace interface and must remain 148constant. If, for some reason, the naming of X86_FEATURE_<name> changes, one 149shall override the new naming with the name already used in /proc/cpuinfo. 150 151c: The naming override can be "", which means it will not appear in /proc/cpuinfo. 152---------------------------------------------------------------------------------- 153The feature shall be omitted from /proc/cpuinfo if it does not make sense for 154the feature to be exposed to userspace. For example, X86_FEATURE_ALWAYS is 155defined in cpufeatures.h but that flag is an internal kernel feature used 156in the alternative runtime patching functionality. So, its name is overridden 157with "". Its flag will not appear in /proc/cpuinfo. 158 159Flags are missing when one or more of these happen 160================================================== 161 162a: The hardware does not enumerate support for it. 163-------------------------------------------------- 164For example, when a new kernel is running on old hardware or the feature is 165not enabled by boot firmware. Even if the hardware is new, there might be a 166problem enabling the feature at run time, the flag will not be displayed. 167 168b: The kernel does not know about the flag. 169------------------------------------------- 170For example, when an old kernel is running on new hardware. 171 172c: The kernel disabled support for it at compile-time. 173------------------------------------------------------ 174For example, if 5-level-paging is not enabled when building (i.e., 175CONFIG_X86_5LEVEL is not selected) the flag "la57" will not show up [#f1]_. 176Even though the feature will still be detected via CPUID, the kernel disables 177it by clearing via setup_clear_cpu_cap(X86_FEATURE_LA57). 178 179d: The feature is disabled at boot-time. 180---------------------------------------- 181A feature can be disabled either using a command-line parameter or because 182it failed to be enabled. The command-line parameter clearcpuid= can be used 183to disable features using the feature number as defined in 184/arch/x86/include/asm/cpufeatures.h. For instance, User Mode Instruction 185Protection can be disabled using clearcpuid=514. The number 514 is calculated 186from #define X86_FEATURE_UMIP (16*32 + 2). 187 188In addition, there exists a variety of custom command-line parameters that 189disable specific features. The list of parameters includes, but is not limited 190to, nofsgsbase, nosgx, noxsave, etc. 5-level paging can also be disabled using 191"no5lvl". 192 193e: The feature was known to be non-functional. 194---------------------------------------------- 195The feature was known to be non-functional because a dependency was 196missing at runtime. For example, AVX flags will not show up if XSAVE feature 197is disabled since they depend on XSAVE feature. Another example would be broken 198CPUs and them missing microcode patches. Due to that, the kernel decides not to 199enable a feature. 200 201.. [#f1] 5-level paging uses linear address of 57 bits. 202