Documentation/arch/x86/cpuinfo.rst

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