[PATCH] Documentation: x86: Explain Intel model naming convention

[Tony Luck]

This was written in an e-mail by Dave Hansen, but not everybody
reads the entire LKML archive before posting a patch.

https://lkml.kernel.org/r/91eefbe4-e32b-d762-be4d-672ff915db47@xxxxxxxxx

Signed-off-by: Tony Luck <tony.luck@xxxxxxxxx>
---
 Documentation/x86/index.rst            |  1 +
 Documentation/x86/intel-cpu-models.rst | 37 ++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)
 create mode 100644 Documentation/x86/intel-cpu-models.rst

diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index af64c4bb4447..6ba9e9cc5938 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -19,6 +19,7 @@ x86-specific Documentation
    tlb
    mtrr
    pat
+   intel-cpu-models
    intel_mpx
    intel-iommu
    intel_txt
diff --git a/Documentation/x86/intel-cpu-models.rst b/Documentation/x86/intel-cpu-models.rst
new file mode 100644
index 000000000000..75b5267a5354
--- /dev/null
+++ b/Documentation/x86/intel-cpu-models.rst
@@ -0,0 +1,37 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+Intel CPU model numbers
+=======================
+
+The CPU model number on a running system can be found by executing
+the CPUID(EAX=0) instruction to find the vendor, family, model
+and stepping.  The model number is found by concatenating two bit
+fields from the EAX return value. Bits 19:16 (extended model number)
+and 7:4 (model number).
+
+Inside the Linux kernel the vendor, family, model and stepping are
+stored in the cpuinfo_x86 structure. Model specific code typically
+uses x86_match_cpu() to determine if it is running on any of some
+list of CPU models.
+
+There are several subsystems that need model specific handling on
+Intel CPUs. For code legibility it is better to assign names for
+the various model numbers in the include file <asm/intel-family.h>
+
+Currently all interesting Intel CPU models are in family 6.
+
+HOWTO Build an INTEL_FAM6_ definition:
+
+1. Start with INTEL_FAM6_
+2. If not Core-family, add a note about it, like "ATOM".  There are only
+   two options for this (Xeon Phi and Atom).  It is exceedingly unlikely
+   that you are adding a cpu which needs a new option here.
+3. Add the processor microarchitecture, not the platform name
+4. Add a short differentiator if necessary.  Add an _X to differentiate
+   Server from Client.
+5. Add an optional comment with the platform name(s)
+
+It should end up looking like this:
+
+INTEL_FAM6_<ATOM?>_<MICROARCH>_<SHORT...> /* Platform Name */
-- 
2.20.1