[PATCH] x86/cpu: Start documenting what the X86_FEATURE_ flag testing macros do

[Borislav Petkov <bp@alien8.de>]

From: Borislav Petkov <bp@suse.de>

... and how and when they should be used.

This keeps popping up everytime people start poking at the CPU features
testing machinery - which has admittedly grown some warts and would need
cleaning up - or when they are wondering what function/macro to use.

Start documenting it first. Proper cleanup will follow once all the
functionality has been agreed upon.

No functional changes.

Signed-off-by: Borislav Petkov <bp@suse.de>
Link: https://lore.kernel.org/r/20220718141123.136106-3-mlevitsk@redhat.com
---
 arch/x86/include/asm/cpufeature.h | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/arch/x86/include/asm/cpufeature.h b/arch/x86/include/asm/cpufeature.h
index 1a85e1fb0922..47ff025e7387 100644
--- a/arch/x86/include/asm/cpufeature.h
+++ b/arch/x86/include/asm/cpufeature.h
@@ -131,12 +131,13 @@ extern const char * const x86_bug_flags[NBUGINTS*32];
 		(unsigned long __percpu *)&cpu_info.x86_capability))
 
 /*
- * This macro is for detection of features which need kernel
- * infrastructure to be used.  It may *not* directly test the CPU
- * itself.  Use the cpu_has() family if you want true runtime
- * testing of CPU features, like in hypervisor code where you are
- * supporting a possible guest feature where host support for it
- * is not relevant.
+ * This is the preferred macro to use when testing X86_FEATURE_ bits
+ * support without the need to test on a particular CPU but rather
+ * system-wide. It takes into account build-time disabled feature
+ * support too. All those macros mirror the kernel's idea of enabled
+ * CPU features and not necessarily what real, hardware CPUID bits are
+ * set or clear. For that use tools/arch/x86/kcpuid/ and/or potentially
+ * extend if it's feature list is lacking.
  */
 #define cpu_feature_enabled(bit)	\
 	(__builtin_constant_p(bit) && DISABLED_MASK_BIT_SET(bit) ? 0 : static_cpu_has(bit))
@@ -145,9 +146,15 @@ extern const char * const x86_bug_flags[NBUGINTS*32];
 
 #define set_cpu_cap(c, bit)	set_bit(bit, (unsigned long *)((c)->x86_capability))
 
-extern void setup_clear_cpu_cap(unsigned int bit);
 extern void clear_cpu_cap(struct cpuinfo_x86 *c, unsigned int bit);
 
+/*
+ * The setup_* prefixed variants enable/disable feature bits on all
+ * CPUs in the system and are used to replicate those settings before
+ * apply_forced_caps() has synthesized enabled and disabled bits across
+ * every CPU.
+ */
+extern void setup_clear_cpu_cap(unsigned int bit);
 #define setup_force_cpu_cap(bit) do { \
 	set_cpu_cap(&boot_cpu_data, bit);	\
 	set_bit(bit, (unsigned long *)cpu_caps_set);	\
-- 
2.35.1