Re: [RFC PATCH 1/3] Documentation/x86: Add documentation for /proc/cpuinfo feature flags

[Kyung Min Park]

Hi Borislav,

On Mon, 2020-06-15 at 20:15 +0200, Borislav Petkov wrote:
> On Wed, Jun 10, 2020 at 01:06:59PM -0700, Kyung Min Park wrote:
> > Add documentation for /proc/cpuinfo feature flags enumeration.
> > Document how and when x86 feature flags are used. Also discuss what
> > their presence or absence mean for the kernel, users, and
> > applications.
> > 
> > Suggested-by: Dave Hansen <dave.hansen@xxxxxxxxx>
> > Co-developed-by: Ricardo Neri <
> > ricardo.neri-calderon@xxxxxxxxxxxxxxx>
> > Signed-off-by: Ricardo Neri <ricardo.neri-calderon@xxxxxxxxxxxxxxx>
> > Signed-off-by: Kyung Min Park <kyung.min.park@xxxxxxxxx>
> > ---
> >  Documentation/x86/cpuinfo.rst | 152
> > ++++++++++++++++++++++++++++++++++
> >  Documentation/x86/index.rst   |   1 +
> >  2 files changed, 153 insertions(+)
> >  create mode 100644 Documentation/x86/cpuinfo.rst
> 
> I guess, although if we ever change how all that works, we need to
> update the documentation but this is the usual thing with
> documentation.
> Maybe it should not be documented in such a detail. :)
> 

Sure :)

> > diff --git a/Documentation/x86/cpuinfo.rst
> > b/Documentation/x86/cpuinfo.rst
> > new file mode 100644
> > index 000000000000..d01d2c03a4d7
> > --- /dev/null
> > +++ b/Documentation/x86/cpuinfo.rst
> > @@ -0,0 +1,152 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +=================
> > +x86 Feature Flags
> > +=================
> > +
> > +Introduction
> > +============
> > +
> > +On x86, flags appearing in /proc/cpuinfo have an X86_FEATURE
> > definition
> > +in arch/x86/include/asm/cpufeatures.h. If the kernel, any
> > application,
> > +or an end user
> 
> The kernel yes - the other two, not really. Userspace simply does
> CPUID
> directly.
> 

Okay, let me remove those two (application, user) here.

> > might care about a feature, it can and should have
> > +X86_FEATURE_* defined. These flags represent hardware features as
> > +well as software features.
> > +
> > +If users want to know if a feature is available on a given system,
> > they
> > +try to find the flag in /proc/cpuinfo. If a given flag is present,
> > it
> > +means that the kernel supports it and is currently making it
> > available.
> > +If such flag represents a hardware feature, it also means that the
> > +hardware supports it.
> > +
> > +If the expected flag does not appear in /proc/cpuinfo, things are
> > murkier.
> > +Users need to find out the reason why the flag is missing and find
> > the way
> > +how to enable it, which is not always easy.
> 
> This needs to say:
> 
> It can be that the kernel doesn't support that feature and thus
> hasn't
> enabled it.
> 

Sure, Let me modify.

> > There are several factors that
> > +can explain missing flags: the expected feature failed to enable,
> > the feature
> > +is missing in hardware, platform firmware did not enable it, the
> > feature is
> > +disabled at build or run time, or an old kernel is in use. In such
> > cases,
> > +the users need to rely on tools like 
> > http://www.etallen.com/cpuid.html
> > +(which is not updated with kernel releases) or other custom tools
> > that
> > +read CPUID.
> 
> In general, this should say something along the lines that
> /proc/cpuinfo
> shows features which the kernel supports.
> 
> "For a full list of CPUID flags which the CPU supports, use
> tools/arch/x86/tools/cpuid/cpuid"
> 
> :-)

Sure.

> 
> > +
> > +How are feature flags created?
> > +==============================
> > +
> > +a: 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).
> > +If a feature is defined with a X86_FEATURE_<name> definition in
> > +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.
> > +----------------------------------------------------
> > +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().
> > +For instance, X86_FEATURE_CQM_LLC is defined as 11*32 + 0 and its
> > presence is
> > +checked at runtime in the respective CPUID leaf [EAX=f, ECX=0] bit
> > EDX[1].
> > +
> > +The intent of scattering CPUID leaves is to not bloat struct
> > +cpuinfo_x86.x86_capability[] unnecessarily. For instance, the
> > CPUID leaf
> > +[EAX=7, ECX=0] has 30 features and is dense, but the CPUID leaf
> > [EAX=7, EAX=1]
> > +has only one feature and would waste 31 bits of space in the
> > x86_capability[]
> > +array.
> 
> ... and that per-CPU.

Let me add more explanation regarding with per-CPU.

> 
> > +
> > +c: 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 macro
> > set_cpu_cap or
> > +setup_force_cpu_cap macro.
> 
> ... by the ... macros.
> 
Sure, let me fix that.