1.. SPDX-License-Identifier: GPL-2.0 2 3================= 4x86 Feature Flags 5================= 6 7Introduction 8============ 9 10On x86, flags appearing in /proc/cpuinfo have an X86_FEATURE definition 11in arch/x86/include/asm/cpufeatures.h. If the kernel cares about a feature 12or KVM want to expose the feature to a KVM guest, it can and should have 13an X86_FEATURE_* defined. These flags represent hardware features as 14well as software features. 15 16If users want to know if a feature is available on a given system, they 17try to find the flag in /proc/cpuinfo. If a given flag is present, it 18means that the kernel supports it and is currently making it available. 19If such flag represents a hardware feature, it also means that the 20hardware supports it. 21 22If the expected flag does not appear in /proc/cpuinfo, things are murkier. 23Users need to find out the reason why the flag is missing and find the way 24how to enable it, which is not always easy. There are several factors that 25can explain missing flags: the expected feature failed to enable, the feature 26is missing in hardware, platform firmware did not enable it, the feature is 27disabled at build or run time, an old kernel is in use, or the kernel does 28not support the feature and thus has not enabled it. In general, /proc/cpuinfo 29shows features which the kernel supports. For a full list of CPUID flags 30which the CPU supports, use tools/arch/x86/kcpuid. 31 32How are feature flags created? 33============================== 34 35a: Feature flags can be derived from the contents of CPUID leaves. 36------------------------------------------------------------------ 37These feature definitions are organized mirroring the layout of CPUID 38leaves and grouped in words with offsets as mapped in enum cpuid_leafs 39in cpufeatures.h (see arch/x86/include/asm/cpufeatures.h for details). 40If a feature is defined with a X86_FEATURE_<name> definition in 41cpufeatures.h, and if it is detected at run time, the flags will be 42displayed accordingly in /proc/cpuinfo. For example, the flag "avx2" 43comes from X86_FEATURE_AVX2 in cpufeatures.h. 44 45b: Flags can be from scattered CPUID-based features. 46---------------------------------------------------- 47Hardware features enumerated in sparsely populated CPUID leaves get 48software-defined values. Still, CPUID needs to be queried to determine 49if a given feature is present. This is done in init_scattered_cpuid_features(). 50For instance, X86_FEATURE_CQM_LLC is defined as 11*32 + 0 and its presence is 51checked at runtime in the respective CPUID leaf [EAX=f, ECX=0] bit EDX[1]. 52 53The intent of scattering CPUID leaves is to not bloat struct 54cpuinfo_x86.x86_capability[] unnecessarily. For instance, the CPUID leaf 55[EAX=7, ECX=0] has 30 features and is dense, but the CPUID leaf [EAX=7, EAX=1] 56has only one feature and would waste 31 bits of space in the x86_capability[] 57array. Since there is a struct cpuinfo_x86 for each possible CPU, the wasted 58memory is not trivial. 59 60c: Flags can be created synthetically under certain conditions for hardware features. 61------------------------------------------------------------------------------------- 62Examples of conditions include whether certain features are present in 63MSR_IA32_CORE_CAPS or specific CPU models are identified. If the needed 64conditions are met, the features are enabled by the set_cpu_cap or 65setup_force_cpu_cap macros. For example, if bit 5 is set in MSR_IA32_CORE_CAPS, 66the feature X86_FEATURE_SPLIT_LOCK_DETECT will be enabled and 67"split_lock_detect" will be displayed. The flag "ring3mwait" will be 68displayed only when running on INTEL_FAM6_XEON_PHI_[KNL|KNM] processors. 69 70d: Flags can represent purely software features. 71------------------------------------------------ 72These flags do not represent hardware features. Instead, they represent a 73software feature implemented in the kernel. For example, Kernel Page Table 74Isolation is purely software feature and its feature flag X86_FEATURE_PTI is 75also defined in cpufeatures.h. 76 77Naming of Flags 78=============== 79 80The script arch/x86/kernel/cpu/mkcapflags.sh processes the 81#define X86_FEATURE_<name> from cpufeatures.h and generates the 82x86_cap/bug_flags[] arrays in kernel/cpu/capflags.c. The names in the 83resulting x86_cap/bug_flags[] are used to populate /proc/cpuinfo. The naming 84of flags in the x86_cap/bug_flags[] are as follows: 85 86a: The name of the flag is from the string in X86_FEATURE_<name> by default. 87---------------------------------------------------------------------------- 88By default, the flag <name> in /proc/cpuinfo is extracted from the respective 89X86_FEATURE_<name> in cpufeatures.h. For example, the flag "avx2" is from 90X86_FEATURE_AVX2. 91 92b: The naming can be overridden. 93-------------------------------- 94If the comment on the line for the #define X86_FEATURE_* starts with a 95double-quote character (""), the string inside the double-quote characters 96will be the name of the flags. For example, the flag "sse4_1" comes from 97the comment "sse4_1" following the X86_FEATURE_XMM4_1 definition. 98 99There are situations in which overriding the displayed name of the flag is 100needed. For instance, /proc/cpuinfo is a userspace interface and must remain 101constant. If, for some reason, the naming of X86_FEATURE_<name> changes, one 102shall override the new naming with the name already used in /proc/cpuinfo. 103 104c: The naming override can be "", which means it will not appear in /proc/cpuinfo. 105---------------------------------------------------------------------------------- 106The feature shall be omitted from /proc/cpuinfo if it does not make sense for 107the feature to be exposed to userspace. For example, X86_FEATURE_ALWAYS is 108defined in cpufeatures.h but that flag is an internal kernel feature used 109in the alternative runtime patching functionality. So, its name is overridden 110with "". Its flag will not appear in /proc/cpuinfo. 111 112Flags are missing when one or more of these happen 113================================================== 114 115a: The hardware does not enumerate support for it. 116-------------------------------------------------- 117For example, when a new kernel is running on old hardware or the feature is 118not enabled by boot firmware. Even if the hardware is new, there might be a 119problem enabling the feature at run time, the flag will not be displayed. 120 121b: The kernel does not know about the flag. 122------------------------------------------- 123For example, when an old kernel is running on new hardware. 124 125c: The kernel disabled support for it at compile-time. 126------------------------------------------------------ 127For example, if 5-level-paging is not enabled when building (i.e., 128CONFIG_X86_5LEVEL is not selected) the flag "la57" will not show up [#f1]_. 129Even though the feature will still be detected via CPUID, the kernel disables 130it by clearing via setup_clear_cpu_cap(X86_FEATURE_LA57). 131 132d: The feature is disabled at boot-time. 133---------------------------------------- 134A feature can be disabled either using a command-line parameter or because 135it failed to be enabled. The command-line parameter clearcpuid= can be used 136to disable features using the feature number as defined in 137/arch/x86/include/asm/cpufeatures.h. For instance, User Mode Instruction 138Protection can be disabled using clearcpuid=514. The number 514 is calculated 139from #define X86_FEATURE_UMIP (16*32 + 2). 140 141In addition, there exists a variety of custom command-line parameters that 142disable specific features. The list of parameters includes, but is not limited 143to, nofsgsbase, nosgx, noxsave, etc. 5-level paging can also be disabled using 144"no5lvl". 145 146e: The feature was known to be non-functional. 147---------------------------------------------- 148The feature was known to be non-functional because a dependency was 149missing at runtime. For example, AVX flags will not show up if XSAVE feature 150is disabled since they depend on XSAVE feature. Another example would be broken 151CPUs and them missing microcode patches. Due to that, the kernel decides not to 152enable a feature. 153 154.. [#f1] 5-level paging uses linear address of 57 bits. 155