Documentation/x86: Clarify naming of CPU features for /proc/cpuinfo

[PATCH] Documentation/x86: Clarify naming of CPU features for /proc/cpuinfo

Posted by Naveen N Rao (AMD) 10 months, 1 week ago

Commit 78ce84b9e0a5 ("x86/cpufeatures: Flip the /proc/cpuinfo appearance
logic") changed how CPU feature names should be specified. Update
document to reflect the same.

Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org>
---
 Documentation/arch/x86/cpuinfo.rst | 42 +++++++++---------------------
 1 file changed, 13 insertions(+), 29 deletions(-)

diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst
index 6ef426a52cdc..fecdc36e02a1 100644
--- a/Documentation/arch/x86/cpuinfo.rst
+++ b/Documentation/arch/x86/cpuinfo.rst
@@ -124,37 +124,21 @@ also defined in cpufeatures.h.
 Naming of Flags
 ===============
 
-The script arch/x86/kernel/cpu/mkcapflags.sh processes the
-#define X86_FEATURE_<name> from cpufeatures.h and generates the
-x86_cap/bug_flags[] arrays in kernel/cpu/capflags.c. The names in the
-resulting x86_cap/bug_flags[] are used to populate /proc/cpuinfo. The naming
-of flags in the x86_cap/bug_flags[] are as follows:
-
-a: The name of the flag is from the string in X86_FEATURE_<name> by default.
-----------------------------------------------------------------------------
-By default, the flag <name> in /proc/cpuinfo is extracted from the respective
-X86_FEATURE_<name> in cpufeatures.h. For example, the flag "avx2" is from
-X86_FEATURE_AVX2.
-
-b: The naming can be overridden.
---------------------------------
 If the comment on the line for the #define X86_FEATURE_* starts with a
-double-quote character (""), the string inside the double-quote characters
-will be the name of the flags. For example, the flag "sse4_1" comes from
-the comment "sse4_1" following the X86_FEATURE_XMM4_1 definition.
+double-quote character (""), the string inside the double-quote characters will
+be the name of the flag. For example, the flag "sse4_1" comes from the comment
+"sse4_1" following the X86_FEATURE_XMM4_1 definition. /proc/cpuinfo is a
+userspace interface and must remain constant. If, for some reason, the naming
+of X86_FEATURE_<name> changes, one shall retain the name already used in
+/proc/cpuinfo.
 
-There are situations in which overriding the displayed name of the flag is
-needed. For instance, /proc/cpuinfo is a userspace interface and must remain
-constant. If, for some reason, the naming of X86_FEATURE_<name> changes, one
-shall override the new naming with the name already used in /proc/cpuinfo.
-
-c: The naming override can be "", which means it will not appear in /proc/cpuinfo.
-----------------------------------------------------------------------------------
-The feature shall be omitted from /proc/cpuinfo if it does not make sense for
-the feature to be exposed to userspace. For example, X86_FEATURE_ALWAYS is
-defined in cpufeatures.h but that flag is an internal kernel feature used
-in the alternative runtime patching functionality. So, its name is overridden
-with "". Its flag will not appear in /proc/cpuinfo.
+If the comment on the line does not start with a double-quote character, then
+it will be omitted from /proc/cpuinfo. This is desirable if it does not make
+sense for the feature to be exposed to userspace. For example,
+X86_FEATURE_ALWAYS is defined in cpufeatures.h but that flag is an internal
+kernel feature used in the alternative runtime patching functionality. So, no
+name is specified within double-quotes and its flag will not appear in
+/proc/cpuinfo.
 
 Flags are missing when one or more of these happen
 ==================================================

base-commit: 1c13554a1d43317fe9009837ef6524f808e107b7
-- 
2.48.1

Re: [PATCH] Documentation/x86: Clarify naming of CPU features for /proc/cpuinfo

Posted by Borislav Petkov 10 months, 1 week ago

On Thu, Apr 03, 2025 at 03:13:08PM +0530, Naveen N Rao (AMD) wrote:
> Commit 78ce84b9e0a5 ("x86/cpufeatures: Flip the /proc/cpuinfo appearance
> logic") changed how CPU feature names should be specified. Update
> document to reflect the same.
> 
> Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org>
> ---
>  Documentation/arch/x86/cpuinfo.rst | 42 +++++++++---------------------
>  1 file changed, 13 insertions(+), 29 deletions(-)
> 
> diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst
> index 6ef426a52cdc..fecdc36e02a1 100644
> --- a/Documentation/arch/x86/cpuinfo.rst
> +++ b/Documentation/arch/x86/cpuinfo.rst
> @@ -124,37 +124,21 @@ also defined in cpufeatures.h.
>  Naming of Flags
>  ===============
>  
> -The script arch/x86/kernel/cpu/mkcapflags.sh processes the
> -#define X86_FEATURE_<name> from cpufeatures.h and generates the
> -x86_cap/bug_flags[] arrays in kernel/cpu/capflags.c. The names in the

This is not the patch I saw in internal review. The script still processes
cpufeatures.h

Please go through all the text you're changing and verify you're *actually*
doing the right thing.

-- 
Regards/Gruss,
    Boris.

https://people.kernel.org/tglx/notes-about-netiquette

Re: [PATCH] Documentation/x86: Clarify naming of CPU features for /proc/cpuinfo

Posted by Naveen N Rao 10 months, 1 week ago

On Thu, Apr 03, 2025 at 02:17:27PM +0200, Borislav Petkov wrote:
> On Thu, Apr 03, 2025 at 03:13:08PM +0530, Naveen N Rao (AMD) wrote:
> > Commit 78ce84b9e0a5 ("x86/cpufeatures: Flip the /proc/cpuinfo appearance
> > logic") changed how CPU feature names should be specified. Update
> > document to reflect the same.
> > 
> > Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org>
> > ---
> >  Documentation/arch/x86/cpuinfo.rst | 42 +++++++++---------------------
> >  1 file changed, 13 insertions(+), 29 deletions(-)
> > 
> > diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst
> > index 6ef426a52cdc..fecdc36e02a1 100644
> > --- a/Documentation/arch/x86/cpuinfo.rst
> > +++ b/Documentation/arch/x86/cpuinfo.rst
> > @@ -124,37 +124,21 @@ also defined in cpufeatures.h.
> >  Naming of Flags
> >  ===============
> >  
> > -The script arch/x86/kernel/cpu/mkcapflags.sh processes the
> > -#define X86_FEATURE_<name> from cpufeatures.h and generates the
> > -x86_cap/bug_flags[] arrays in kernel/cpu/capflags.c. The names in the
> 
> This is not the patch I saw in internal review. The script still processes
> cpufeatures.h

As far as I can tell, the script still processes cpufeatures.h but no 
longer "generates" names. It simply picks names within double-quotes if 
present. I don't think that is relevant for describing how the flags are 
named anymore.

> 
> Please go through all the text you're changing and verify you're *actually*
> doing the right thing.

I guess you missed that part of my response where I explicitly mentioned 
that I have dropped the part describing the script for the above reason, 
and also pasted how the section looks like.

Regardless, please take another look at this and let me know if you 
think this still doesn't read right, or is missing anything (the script 
part, in particular). For reference, here is how the flag naming section 
looks like with this patch:

---
Naming of Flags
===============

If the comment on the line for the #define X86_FEATURE_* starts with a
double-quote character (""), the string inside the double-quote characters will
be the name of the flag. For example, the flag "sse4_1" comes from the comment
"sse4_1" following the X86_FEATURE_XMM4_1 definition. /proc/cpuinfo is a
userspace interface and must remain constant. If, for some reason, the naming
of X86_FEATURE_<name> changes, one shall retain the name already used in
/proc/cpuinfo.

If the comment on the line does not start with a double-quote character, then
it will be omitted from /proc/cpuinfo. This is desirable if it does not make
sense for the feature to be exposed to userspace. For example,
X86_FEATURE_ALWAYS is defined in cpufeatures.h but that flag is an internal
kernel feature used in the alternative runtime patching functionality. So, no
name is specified within double-quotes and its flag will not appear in
/proc/cpuinfo.

Thanks,
Naveen

Re: [PATCH] Documentation/x86: Clarify naming of CPU features for /proc/cpuinfo

Posted by Borislav Petkov 10 months, 1 week ago

On Thu, Apr 03, 2025 at 06:40:00PM +0530, Naveen N Rao wrote:
> As far as I can tell, the script still processes cpufeatures.h but no 
> longer "generates" names. It simply picks names within double-quotes if 
> present. I don't think that is relevant for describing how the flags are 
> named anymore.

It is relevant in a documentation file which is called cpuinfo.rst. Because
this thing is somewhat of a magic - and Xen has even more magic there - so I'd
like that file to explain the *whole* story.

> Regardless, please take another look at this and let me know if you 
> think this still doesn't read right, or is missing anything (the script 
> part, in particular). For reference, here is how the flag naming section 
> looks like with this patch:

Tell you what: I'll take your text, put it in the file, edit it how I think it
should like and send you a patch for you to ack. This'll save us a lot of
time.

Thx.

-- 
Regards/Gruss,
    Boris.

https://people.kernel.org/tglx/notes-about-netiquette

Re: [PATCH] Documentation/x86: Clarify naming of CPU features for /proc/cpuinfo

Posted by Naveen N Rao 10 months, 1 week ago

On Thu, Apr 03, 2025 at 03:21:21PM +0200, Borislav Petkov wrote:
> On Thu, Apr 03, 2025 at 06:40:00PM +0530, Naveen N Rao wrote:
> > As far as I can tell, the script still processes cpufeatures.h but no 
> > longer "generates" names. It simply picks names within double-quotes if 
> > present. I don't think that is relevant for describing how the flags are 
> > named anymore.
> 
> It is relevant in a documentation file which is called cpuinfo.rst. Because
> this thing is somewhat of a magic - and Xen has even more magic there - so I'd
> like that file to explain the *whole* story.

Ok.

> 
> > Regardless, please take another look at this and let me know if you 
> > think this still doesn't read right, or is missing anything (the script 
> > part, in particular). For reference, here is how the flag naming section 
> > looks like with this patch:
> 
> Tell you what: I'll take your text, put it in the file, edit it how I think it
> should like and send you a patch for you to ack. This'll save us a lot of
> time.

Sure, feel free to edit my patch as you see fit before applying. I am 
fine if you want to retain the section about the script - it should 
still be a minor edit, unless you want to rewrite other parts.


Thank you!
- Naveen

[PATCH 1/2] Documentation/x86: Update the naming of CPU features for /proc/cpuinfo

Posted by Borislav Petkov 10 months ago

From: "Naveen N Rao (AMD)" <naveen@kernel.org>
Date: Wed, 9 Apr 2025 12:42:45 +0200

Commit

  78ce84b9e0a5 ("x86/cpufeatures: Flip the /proc/cpuinfo appearance logic")

changed how CPU feature names should be specified. Update document to
reflect the same.

Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org>
Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
---
 Documentation/arch/x86/cpuinfo.rst | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst
index 6ef426a52cdc..7114f34ba3e6 100644
--- a/Documentation/arch/x86/cpuinfo.rst
+++ b/Documentation/arch/x86/cpuinfo.rst
@@ -130,14 +130,18 @@ x86_cap/bug_flags[] arrays in kernel/cpu/capflags.c. The names in the
 resulting x86_cap/bug_flags[] are used to populate /proc/cpuinfo. The naming
 of flags in the x86_cap/bug_flags[] are as follows:
 
-a: The name of the flag is from the string in X86_FEATURE_<name> by default.
-----------------------------------------------------------------------------
-By default, the flag <name> in /proc/cpuinfo is extracted from the respective
-X86_FEATURE_<name> in cpufeatures.h. For example, the flag "avx2" is from
-X86_FEATURE_AVX2.
-
-b: The naming can be overridden.
---------------------------------
+a: Flags do not appear by default in /proc/cpuinfo
+--------------------------------------------------
+
+Feature flags are omitted by default from /proc/cpuinfo as it does not make
+sense for the feature to be exposed to userspace in most cases. For example,
+X86_FEATURE_ALWAYS is defined in cpufeatures.h but that flag is an internal
+kernel feature used in the alternative runtime patching functionality. So the
+flag does not appear in /proc/cpuinfo.
+
+b: Specify a flag name if absolutely needed
+-------------------------------------------
+
 If the comment on the line for the #define X86_FEATURE_* starts with a
 double-quote character (""), the string inside the double-quote characters
 will be the name of the flags. For example, the flag "sse4_1" comes from
@@ -148,14 +152,6 @@ needed. For instance, /proc/cpuinfo is a userspace interface and must remain
 constant. If, for some reason, the naming of X86_FEATURE_<name> changes, one
 shall override the new naming with the name already used in /proc/cpuinfo.
 
-c: The naming override can be "", which means it will not appear in /proc/cpuinfo.
-----------------------------------------------------------------------------------
-The feature shall be omitted from /proc/cpuinfo if it does not make sense for
-the feature to be exposed to userspace. For example, X86_FEATURE_ALWAYS is
-defined in cpufeatures.h but that flag is an internal kernel feature used
-in the alternative runtime patching functionality. So, its name is overridden
-with "". Its flag will not appear in /proc/cpuinfo.
-
 Flags are missing when one or more of these happen
 ==================================================
 
-- 
2.43.0

-- 
Regards/Gruss,
    Boris.

https://people.kernel.org/tglx/notes-about-netiquette

[tip: x86/urgent] Documentation/x86: Update the naming of CPU features for /proc/cpuinfo

Posted by tip-bot2 for Naveen N Rao (AMD) 10 months ago

The following commit has been merged into the x86/urgent branch of tip:

Commit-ID:     af76f7d57ee9a3be7b3840595ce3e2bdedd594a7
Gitweb:        https://git.kernel.org/tip/af76f7d57ee9a3be7b3840595ce3e2bdedd594a7
Author:        Naveen N Rao (AMD) <naveen@kernel.org>
AuthorDate:    Wed, 09 Apr 2025 13:13:41 +02:00
Committer:     Ingo Molnar <mingo@kernel.org>
CommitterDate: Wed, 09 Apr 2025 13:56:52 +02:00

Documentation/x86: Update the naming of CPU features for /proc/cpuinfo

Commit:

  78ce84b9e0a5 ("x86/cpufeatures: Flip the /proc/cpuinfo appearance logic")

changed how CPU feature names should be specified. Update document to
reflect the same.

Signed-off-by: Naveen N Rao (AMD) <naveen@kernel.org>
Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Link: https://lore.kernel.org/r/20250409111341.GDZ_ZWZS4LckBcirLE@fat_crate.local
---
 Documentation/arch/x86/cpuinfo.rst | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst
index 6ef426a..7114f34 100644
--- a/Documentation/arch/x86/cpuinfo.rst
+++ b/Documentation/arch/x86/cpuinfo.rst
@@ -130,14 +130,18 @@ x86_cap/bug_flags[] arrays in kernel/cpu/capflags.c. The names in the
 resulting x86_cap/bug_flags[] are used to populate /proc/cpuinfo. The naming
 of flags in the x86_cap/bug_flags[] are as follows:
 
-a: The name of the flag is from the string in X86_FEATURE_<name> by default.
-----------------------------------------------------------------------------
-By default, the flag <name> in /proc/cpuinfo is extracted from the respective
-X86_FEATURE_<name> in cpufeatures.h. For example, the flag "avx2" is from
-X86_FEATURE_AVX2.
-
-b: The naming can be overridden.
---------------------------------
+a: Flags do not appear by default in /proc/cpuinfo
+--------------------------------------------------
+
+Feature flags are omitted by default from /proc/cpuinfo as it does not make
+sense for the feature to be exposed to userspace in most cases. For example,
+X86_FEATURE_ALWAYS is defined in cpufeatures.h but that flag is an internal
+kernel feature used in the alternative runtime patching functionality. So the
+flag does not appear in /proc/cpuinfo.
+
+b: Specify a flag name if absolutely needed
+-------------------------------------------
+
 If the comment on the line for the #define X86_FEATURE_* starts with a
 double-quote character (""), the string inside the double-quote characters
 will be the name of the flags. For example, the flag "sse4_1" comes from
@@ -148,14 +152,6 @@ needed. For instance, /proc/cpuinfo is a userspace interface and must remain
 constant. If, for some reason, the naming of X86_FEATURE_<name> changes, one
 shall override the new naming with the name already used in /proc/cpuinfo.
 
-c: The naming override can be "", which means it will not appear in /proc/cpuinfo.
-----------------------------------------------------------------------------------
-The feature shall be omitted from /proc/cpuinfo if it does not make sense for
-the feature to be exposed to userspace. For example, X86_FEATURE_ALWAYS is
-defined in cpufeatures.h but that flag is an internal kernel feature used
-in the alternative runtime patching functionality. So, its name is overridden
-with "". Its flag will not appear in /proc/cpuinfo.
-
 Flags are missing when one or more of these happen
 ==================================================

[PATCH 2/2] Documentation/x86: Zap the subsection letters

Posted by Borislav Petkov 10 months ago

From: "Borislav Petkov (AMD)" <bp@alien8.de>
Date: Wed, 9 Apr 2025 12:45:58 +0200

The subsections already have numbering - no need for the letters too.

Zap the latter.

Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
---
 Documentation/arch/x86/cpuinfo.rst | 51 +++++++++++++++++-------------
 1 file changed, 29 insertions(+), 22 deletions(-)

diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst
index 7114f34ba3e6..f80e2a558d2a 100644
--- a/Documentation/arch/x86/cpuinfo.rst
+++ b/Documentation/arch/x86/cpuinfo.rst
@@ -79,8 +79,9 @@ feature flags.
 How are feature flags created?
 ==============================
 
-a: Feature flags can be derived from the contents of CPUID leaves.
-------------------------------------------------------------------
+Feature flags can be derived from the contents of CPUID leaves
+--------------------------------------------------------------
+
 These feature definitions are organized mirroring the layout of CPUID
 leaves and grouped in words with offsets as mapped in enum cpuid_leafs
 in 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
 displayed accordingly in /proc/cpuinfo. For example, the flag "avx2"
 comes from X86_FEATURE_AVX2 in cpufeatures.h.
 
-b: Flags can be from scattered CPUID-based features.
-----------------------------------------------------
+Flags can be from scattered CPUID-based features
+------------------------------------------------
+
 Hardware features enumerated in sparsely populated CPUID leaves get
 software-defined values. Still, CPUID needs to be queried to determine
 if 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[]
 array. Since there is a struct cpuinfo_x86 for each possible CPU, the wasted
 memory is not trivial.
 
-c: Flags can be created synthetically under certain conditions for hardware features.
--------------------------------------------------------------------------------------
+Flags can be created synthetically under certain conditions for hardware features
+---------------------------------------------------------------------------------
+
 Examples of conditions include whether certain features are present in
 MSR_IA32_CORE_CAPS or specific CPU models are identified. If the needed
 conditions 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
 "split_lock_detect" will be displayed. The flag "ring3mwait" will be
 displayed only when running on INTEL_XEON_PHI_[KNL|KNM] processors.
 
-d: Flags can represent purely software features.
-------------------------------------------------
+Flags can represent purely software features
+--------------------------------------------
 These flags do not represent hardware features. Instead, they represent a
 software feature implemented in the kernel. For example, Kernel Page Table
 Isolation is purely software feature and its feature flag X86_FEATURE_PTI is
@@ -130,8 +133,8 @@ x86_cap/bug_flags[] arrays in kernel/cpu/capflags.c. The names in the
 resulting x86_cap/bug_flags[] are used to populate /proc/cpuinfo. The naming
 of flags in the x86_cap/bug_flags[] are as follows:
 
-a: Flags do not appear by default in /proc/cpuinfo
---------------------------------------------------
+Flags do not appear by default in /proc/cpuinfo
+-----------------------------------------------
 
 Feature flags are omitted by default from /proc/cpuinfo as it does not make
 sense for the feature to be exposed to userspace in most cases. For example,
@@ -139,8 +142,8 @@ X86_FEATURE_ALWAYS is defined in cpufeatures.h but that flag is an internal
 kernel feature used in the alternative runtime patching functionality. So the
 flag does not appear in /proc/cpuinfo.
 
-b: Specify a flag name if absolutely needed
--------------------------------------------
+Specify a flag name if absolutely needed
+----------------------------------------
 
 If the comment on the line for the #define X86_FEATURE_* starts with a
 double-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.
 Flags are missing when one or more of these happen
 ==================================================
 
-a: The hardware does not enumerate support for it.
---------------------------------------------------
+The hardware does not enumerate support for it
+----------------------------------------------
+
 For example, when a new kernel is running on old hardware or the feature is
 not enabled by boot firmware. Even if the hardware is new, there might be a
 problem enabling the feature at run time, the flag will not be displayed.
 
-b: The kernel does not know about the flag.
--------------------------------------------
+The kernel does not know about the flag
+---------------------------------------
+
 For example, when an old kernel is running on new hardware.
 
-c: The kernel disabled support for it at compile-time.
-------------------------------------------------------
+The kernel disabled support for it at compile-time
+--------------------------------------------------
+
 For example, if 5-level-paging is not enabled when building (i.e.,
 CONFIG_X86_5LEVEL is not selected) the flag "la57" will not show up [#f1]_.
 Even though the feature will still be detected via CPUID, the kernel disables
 it by clearing via setup_clear_cpu_cap(X86_FEATURE_LA57).
 
-d: The feature is disabled at boot-time.
-----------------------------------------
+The feature is disabled at boot-time
+------------------------------------
 A feature can be disabled either using a command-line parameter or because
 it failed to be enabled. The command-line parameter clearcpuid= can be used
 to 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
 to, nofsgsbase, nosgx, noxsave, etc. 5-level paging can also be disabled using
 "no5lvl".
 
-e: The feature was known to be non-functional.
-----------------------------------------------
+The feature was known to be non-functional
+------------------------------------------
+
 The feature was known to be non-functional because a dependency was
 missing at runtime. For example, AVX flags will not show up if XSAVE feature
 is disabled since they depend on XSAVE feature. Another example would be broken
-- 
2.43.0


-- 
Regards/Gruss,
    Boris.

https://people.kernel.org/tglx/notes-about-netiquette

[tip: x86/urgent] Documentation/x86: Zap the subsection letters

Posted by tip-bot2 for Borislav Petkov (AMD) 10 months ago

The following commit has been merged into the x86/urgent branch of tip:

Commit-ID:     254a6d14c9c952e8eae0fafd4fed3778721b948e
Gitweb:        https://git.kernel.org/tip/254a6d14c9c952e8eae0fafd4fed3778721b948e
Author:        Borislav Petkov (AMD) <bp@alien8.de>
AuthorDate:    Wed, 09 Apr 2025 13:14:35 +02:00
Committer:     Ingo Molnar <mingo@kernel.org>
CommitterDate: Wed, 09 Apr 2025 13:56:52 +02:00

Documentation/x86: Zap the subsection letters

The subsections already have numbering - no need for the letters too.

Zap the latter.

Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Link: https://lore.kernel.org/r/20250409111435.GEZ_ZWmz3_lkP8S9Lb@fat_crate.local
---
 Documentation/arch/x86/cpuinfo.rst | 51 ++++++++++++++++-------------
 1 file changed, 29 insertions(+), 22 deletions(-)

diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst
index 7114f34..f80e2a5 100644
--- a/Documentation/arch/x86/cpuinfo.rst
+++ b/Documentation/arch/x86/cpuinfo.rst
@@ -79,8 +79,9 @@ feature flags.
 How are feature flags created?
 ==============================
 
-a: Feature flags can be derived from the contents of CPUID leaves.
-------------------------------------------------------------------
+Feature flags can be derived from the contents of CPUID leaves
+--------------------------------------------------------------
+
 These feature definitions are organized mirroring the layout of CPUID
 leaves and grouped in words with offsets as mapped in enum cpuid_leafs
 in 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
 displayed accordingly in /proc/cpuinfo. For example, the flag "avx2"
 comes from X86_FEATURE_AVX2 in cpufeatures.h.
 
-b: Flags can be from scattered CPUID-based features.
-----------------------------------------------------
+Flags can be from scattered CPUID-based features
+------------------------------------------------
+
 Hardware features enumerated in sparsely populated CPUID leaves get
 software-defined values. Still, CPUID needs to be queried to determine
 if 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[]
 array. Since there is a struct cpuinfo_x86 for each possible CPU, the wasted
 memory is not trivial.
 
-c: Flags can be created synthetically under certain conditions for hardware features.
--------------------------------------------------------------------------------------
+Flags can be created synthetically under certain conditions for hardware features
+---------------------------------------------------------------------------------
+
 Examples of conditions include whether certain features are present in
 MSR_IA32_CORE_CAPS or specific CPU models are identified. If the needed
 conditions 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
 "split_lock_detect" will be displayed. The flag "ring3mwait" will be
 displayed only when running on INTEL_XEON_PHI_[KNL|KNM] processors.
 
-d: Flags can represent purely software features.
-------------------------------------------------
+Flags can represent purely software features
+--------------------------------------------
 These flags do not represent hardware features. Instead, they represent a
 software feature implemented in the kernel. For example, Kernel Page Table
 Isolation is purely software feature and its feature flag X86_FEATURE_PTI is
@@ -130,8 +133,8 @@ x86_cap/bug_flags[] arrays in kernel/cpu/capflags.c. The names in the
 resulting x86_cap/bug_flags[] are used to populate /proc/cpuinfo. The naming
 of flags in the x86_cap/bug_flags[] are as follows:
 
-a: Flags do not appear by default in /proc/cpuinfo
---------------------------------------------------
+Flags do not appear by default in /proc/cpuinfo
+-----------------------------------------------
 
 Feature flags are omitted by default from /proc/cpuinfo as it does not make
 sense for the feature to be exposed to userspace in most cases. For example,
@@ -139,8 +142,8 @@ X86_FEATURE_ALWAYS is defined in cpufeatures.h but that flag is an internal
 kernel feature used in the alternative runtime patching functionality. So the
 flag does not appear in /proc/cpuinfo.
 
-b: Specify a flag name if absolutely needed
--------------------------------------------
+Specify a flag name if absolutely needed
+----------------------------------------
 
 If the comment on the line for the #define X86_FEATURE_* starts with a
 double-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.
 Flags are missing when one or more of these happen
 ==================================================
 
-a: The hardware does not enumerate support for it.
---------------------------------------------------
+The hardware does not enumerate support for it
+----------------------------------------------
+
 For example, when a new kernel is running on old hardware or the feature is
 not enabled by boot firmware. Even if the hardware is new, there might be a
 problem enabling the feature at run time, the flag will not be displayed.
 
-b: The kernel does not know about the flag.
--------------------------------------------
+The kernel does not know about the flag
+---------------------------------------
+
 For example, when an old kernel is running on new hardware.
 
-c: The kernel disabled support for it at compile-time.
-------------------------------------------------------
+The kernel disabled support for it at compile-time
+--------------------------------------------------
+
 For example, if 5-level-paging is not enabled when building (i.e.,
 CONFIG_X86_5LEVEL is not selected) the flag "la57" will not show up [#f1]_.
 Even though the feature will still be detected via CPUID, the kernel disables
 it by clearing via setup_clear_cpu_cap(X86_FEATURE_LA57).
 
-d: The feature is disabled at boot-time.
-----------------------------------------
+The feature is disabled at boot-time
+------------------------------------
 A feature can be disabled either using a command-line parameter or because
 it failed to be enabled. The command-line parameter clearcpuid= can be used
 to 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
 to, nofsgsbase, nosgx, noxsave, etc. 5-level paging can also be disabled using
 "no5lvl".
 
-e: The feature was known to be non-functional.
-----------------------------------------------
+The feature was known to be non-functional
+------------------------------------------
+
 The feature was known to be non-functional because a dependency was
 missing at runtime. For example, AVX flags will not show up if XSAVE feature
 is disabled since they depend on XSAVE feature. Another example would be broken

Re: [PATCH] Documentation/x86: Clarify naming of CPU features for /proc/cpuinfo

Posted by Bagas Sanjaya 10 months, 1 week ago

On Thu, Apr 03, 2025 at 03:13:08PM +0530, Naveen N Rao (AMD) wrote:
>  If the comment on the line for the #define X86_FEATURE_* starts with a
> -double-quote character (""), the string inside the double-quote characters
> -will be the name of the flags. For example, the flag "sse4_1" comes from
> -the comment "sse4_1" following the X86_FEATURE_XMM4_1 definition.
> +double-quote character (""), the string inside the double-quote characters will
                           "... the quoted string ..."
> +be the name of the flag. For example, the flag "sse4_1" comes from the comment
> +"sse4_1" following the X86_FEATURE_XMM4_1 definition. /proc/cpuinfo is a
> +userspace interface and must remain constant. If, for some reason, the naming
> +of X86_FEATURE_<name> changes, one shall retain the name already used in
> +/proc/cpuinfo.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara