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

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

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

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

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

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