On Mon, Sep 01, 2025 at 05:04:18PM +0000, K Prateek Nayak wrote:
> Add a new section describing the different CPUID leaves and fields used
> to parse topology on x86 systems.
>
> Suggested-by: Borislav Petkov <bp@xxxxxxxxx>
> Signed-off-by: K Prateek Nayak <kprateek.nayak@xxxxxxx>
> ---
> Changelog v4..v5:
>
> o Added a nte about the NODE_ID_MSR on AMD platforms.
> ---
> Documentation/arch/x86/topology.rst | 198 ++++++++++++++++++++++++++++
> 1 file changed, 198 insertions(+)
Some trivial simplifications and cleanups ontop:
---
diff --git a/Documentation/arch/x86/topology.rst b/Documentation/arch/x86/topology.rst
index 4227eba65957..86bec8ac2c4d 100644
--- a/Documentation/arch/x86/topology.rst
+++ b/Documentation/arch/x86/topology.rst
@@ -143,76 +143,69 @@ Thread-related topology information in the kernel:
System topology enumeration
===========================
+
The topology on x86 systems can be discovered using a combination of vendor
-specific CPUID leaves introduced specifically to enumerate the processor
-topology and the cache hierarchy.
+specific CPUID leaves which enumerate the processor topology and the cache
+hierarchy.
The CPUID leaves in their preferred order of parsing for each x86 vendor is as
follows:
-1) AMD and Hygon
-
- On AMD and Hygon platforms, the CPUID leaves that enumerate the processor
- topology are as follows:
+1) AMD
1) CPUID leaf 0x80000026 [Extended CPU Topology] (Core::X86::Cpuid::ExCpuTopology)
The extended CPUID leaf 0x80000026 is the extension of the CPUID leaf 0xB
- and provides the topology information of Core, Complex, CCD(Die), and
+ and provides the topology information of Core, Complex, CCD (Die), and
Socket in each level.
- The support for the leaf is expected to be discovered by checking if the
- supported extended CPUID level is >= 0x80000026 and then checking if
- `LogProcAtThisLevel` in `EBX[15:0]` at a particular level (starting from
- 0) is non-zero.
+ Support for the leaf is discovered by checking if the maximum extended
+ CPUID level is >= 0x80000026 and then checking if `LogProcAtThisLevel`
+ in `EBX[15:0]` at a particular level (starting from 0) is non-zero.
- The `LevelType` in `ECX[15:8]` at the level provides the detail of the
- topology domain that the level describes - Core, Complex, CCD(Die), or
- the Socket.
+ The `LevelType` in `ECX[15:8]` at the level provides the topology domain
+ the level describes - Core, Complex, CCD(Die), or the Socket.
The kernel uses the `CoreMaskWidth` from `EAX[4:0]` to discover the
- number of bits that need to be right shifted from the
- `ExtendedLocalApicId` in `EDX[31:0]` to get a unique Topology ID for
- the topology level. CPUs with the same Topology ID share the resources
- at that level.
+ number of bits that need to be right-shifted from `ExtendedLocalApicId`
+ in `EDX[31:0]` in order to get a unique Topology ID for the topology
+ level. CPUs with the same Topology ID share the resources at that level.
- CPUID leaf 0x80000026 also provides more information regarding the
- power and efficiency rankings, and about the core type on AMD
- processors with heterogeneous characteristics.
+ CPUID leaf 0x80000026 also provides more information regarding the power
+ and efficiency rankings, and about the core type on AMD processors with
+ heterogeneous characteristics.
If CPUID leaf 0x80000026 is supported, further parsing is not required.
-
2) CPUID leaf 0x0000000B [Extended Topology Enumeration] (Core::X86::Cpuid::ExtTopEnum)
The extended CPUID leaf 0x0000000B is the predecessor on the extended
CPUID leaf 0x80000026 and only describes the core, and the socket domains
of the processor topology.
- The support for the leaf is expected to be discovered by checking if the
- supported CPUID level is >= 0xB and then checking if `EBX[31:0]` at a
- particular level (starting from 0) is non-zero.
+ The support for the leaf is discovered by checking if the maximum supported
+ CPUID level is >= 0xB and then if `EBX[31:0]` at a particular level
+ (starting from 0) is non-zero.
- The `LevelType` in `ECX[15:8]` at the level provides the detail of the
- topology domain that the level describes - Thread, or Processor (Socket).
+ The `LevelType` in `ECX[15:8]` at the level provides the topology domain
+ that the level describes - Thread, or Processor (Socket).
The kernel uses the `CoreMaskWidth` from `EAX[4:0]` to discover the
- number of bits that need to be right shifted from the
- `ExtendedLocalApicId` in `EDX[31:0]` to get a unique Topology ID for
- that topology level. CPUs sharing the Topology ID share the resources
- at that level.
+ number of bits that need to be right-shifted from the `ExtendedLocalApicId`
+ in `EDX[31:0]` to get a unique Topology ID for that topology level. CPUs
+ sharing the Topology ID share the resources at that level.
If CPUID leaf 0xB is supported, further parsing is not required.
3) CPUID leaf 0x80000008 ECX [Size Identifiers] (Core::X86::Cpuid::SizeId)
- If neither the CPUID leaf 0x80000026 or CPUID leaf 0xB is supported, the
- number of CPUs on the package is detected using the Size Identifier leaf
+ If neither the CPUID leaf 0x80000026 nor 0xB is supported, the number of
+ CPUs on the package is detected using the Size Identifier leaf
0x80000008 ECX.
- The support for the leaf is expected to be discovered by checking if the
- supported extended CPUID level is >= 0x80000008.
+ The support for the leaf is discovered by checking if the supported
+ extended CPUID level is >= 0x80000008.
The shifts from the APIC ID for the Socket ID is calculated from the
`ApicIdSize` field in `ECX[15:12]` if it is non-zero.
@@ -251,8 +244,8 @@ follows:
`cu_id` (Compute Unit ID) to detect CPUs that share the compute units.
- All AMD and Hygon processors that support the `TopologyExtensions` feature
- stores the `NodeId` from the `ECX[7:0]` of CPUID leaf 0x8000001E
+ All AMD processors that support the `TopologyExtensions` feature store the
+ `NodeId` from the `ECX[7:0]` of CPUID leaf 0x8000001E
(Core::X86::Cpuid::NodeId) as the per-CPU `node_id`. On older processors,
the `node_id` was discovered using MSR_FAM10H_NODE_ID MSR (MSR
0x0xc001_100c). The presence of the NODE_ID MSR was detected by checking
@@ -271,13 +264,13 @@ follows:
the topology information of Core, Module, Tile, Die, DieGrp, and Socket
in each level.
- The support for the leaf is expected to be discovered by checking if
- the supported CPUID level is >= 0x1F and then `EBX[31:0]` at a
- particular level (starting from 0) is non-zero.
+ The support for the leaf is discovered by checking if the supported
+ CPUID level is >= 0x1F and then `EBX[31:0]` at a particular level
+ (starting from 0) is non-zero.
- The `Domain Type` in `ECX[15:8]` of the sub-leaf provides the detail of
- the topology domain that the level describes - Core, Module, Tile, Die,
- DieGrp, and Socket.
+ The `Domain Type` in `ECX[15:8]` of the sub-leaf provides the topology
+ domain that the level describes - Core, Module, Tile, Die, DieGrp, and
+ Socket.
The kernel uses the value from `EAX[4:0]` to discover the number of
bits that need to be right shifted from the `x2APIC ID` in `EDX[31:0]`
@@ -293,9 +286,9 @@ follows:
Topology Enumeration Leaf 0x1F and only describes the core, and the
socket domains of the processor topology.
- The support for the leaf is expected to be discovered by checking if the
- supported CPUID level is >= 0xB and then checking if `EBX[31:0]` at a
- particular level (starting from 0) is non-zero.
+ The support for the leaf is iscovered by checking if the supported CPUID
+ level is >= 0xB and then checking if `EBX[31:0]` at a particular level
+ (starting from 0) is non-zero.
CPUID leaf 0x0000000B shares the same layout as CPUID leaf 0x1F and
should be enumerated in a similar manner.
--
Regards/Gruss,
Boris.
https://people.kernel.org/tglx/notes-about-netiquette
