Add a new section describing the different CPUID leaves and fields used
to parse topology on x86 systems.
Suggested-by: Borislav Petkov <bp@alien8.de>
Signed-off-by: K Prateek Nayak <kprateek.nayak@amd.com>
---
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(+)
diff --git a/Documentation/arch/x86/topology.rst b/Documentation/arch/x86/topology.rst
index c12837e61bda..4227eba65957 100644
--- a/Documentation/arch/x86/topology.rst
+++ b/Documentation/arch/x86/topology.rst
@@ -141,6 +141,204 @@ 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.
+
+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) 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
+ 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.
+
+ 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 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.
+
+ 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 `LevelType` in `ECX[15:8]` at the level provides the detail of 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.
+
+ 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
+ 0x80000008 ECX.
+
+ The support for the leaf is expected to be 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.
+
+ If `ApicIdSize` is reported to be zero, the shift is calculated as the
+ order of the `number of threads` calculated from `NC` field in
+ `ECX[7:0]` which describes the `number of threads - 1` on the package.
+
+ Unless Extended APIC ID is supported, the APIC ID used to find the
+ Socket ID is from the `LocalApicId` field of CPUID leaf 0x00000001
+ `EBX[31:24]`.
+
+ The topology parsing continues to detect if Extended APIC ID is
+ supported or not.
+
+
+ 4) CPUID leaf 0x8000001E [Extended APIC ID, Core Identifiers, Node Identifiers]
+ (Core::X86::Cpuid::{ExtApicId,CoreId,NodeId})
+
+ The support for Extended APIC ID can be detected by checking for the
+ presence of `TopologyExtensions` in `ECX[22]` of CPUID leaf 0x80000001
+ [Feature Identifiers] (Core::X86::Cpuid::FeatureExtIdEcx).
+
+ If Topology Extensions is supported, the APIC ID from `ExtendedApicId`
+ from CPUID leaf 0x8000001E `EAX[31:0]` should be preferred over that from
+ `LocalApicId` field of CPUID leaf 0x00000001 `EBX[31:24]` for topology
+ enumeration.
+
+ On processors of Family 0x17 and above that do not support CPUID leaf
+ 0x80000026 or CPUID leaf 0xB, the shifts from the APIC ID for the Core
+ ID is calculated using the order of `number of threads per core`
+ calculated using the `ThreadsPerCore` field in `EBX[15:8]` which
+ describes `number of threads per core - 1`.
+
+ On Processors of Family 0x15, the Core ID from `EBX[7:0]` is used as the
+ `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
+ (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
+ `ECX[19]` of CPUID leaf 0x80000001 [Feature Identifiers]
+ (Core::X86::Cpuid::FeatureExtIdEcx).
+
+
+2) Intel
+
+ On Intel platforms, the CPUID leaves that enumerate the processor
+ topology are as follows:
+
+ 1) CPUID leaf 0x1F (V2 Extended Topology Enumeration Leaf)
+
+ The CPUID leaf 0x1F is the extension of the CPUID leaf 0xB and provides
+ 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 `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 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]`
+ to get a unique Topology ID for the topology level. CPUs with the same
+ Topology ID share the resources at that level.
+
+ If CPUID leaf 0x1F is supported, further parsing is not required.
+
+
+ 2) CPUID leaf 0x0000000B (Extended Topology Enumeration Leaf)
+
+ The extended CPUID leaf 0x0000000B is the predecessor of the V2 Extended
+ 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.
+
+ CPUID leaf 0x0000000B shares the same layout as CPUID leaf 0x1F and
+ should be enumerated in a similar manner.
+
+ If CPUID leaf 0xB is supported, further parsing is not required.
+
+
+ 3) CPUID leaf 0x00000004 (Deterministic Cache Parameters Leaf)
+
+ On Intel processors that support neither CPUID leaf 0x1F, nor CPUID leaf
+ 0xB, the shifts for the SMT domains is calculated using the number of
+ CPUs sharing the L1 cache.
+
+ Processors that feature Hyper-Threading is detected using `EDX[28]` of
+ CPUID leaf 0x1 (Basic CPUID Information).
+
+ The order of `Maximum number of addressable IDs for logical processors
+ sharing this cache` from `EAX[25:14]` of level-0 of CPUID 0x4 provides
+ the shifts from the APIC ID required to compute the Core ID.
+
+ The APIC ID and Package information is computed using the data from
+ CPUID leaf 0x1.
+
+
+ 4) CPUID leaf 0x00000001 (Basic CPUID Information)
+
+ The mask and shifts to derive the Physical Package (socket) ID is
+ computed using the `Maximum number of addressable IDs for logical
+ processors in this physical package` from `EBX[23:16]` of CPUID leaf
+ 0x1.
+
+ The APIC ID on the legacy platforms is derived from the `Initial APIC
+ ID` field from `EBX[31:24]` of CPUID leaf 0x1.
+
+
+3) Centaur and Zhaoxin
+
+ Similar to Intel, Centaur and Zhaoxin use a combination of CPUID leaf
+ 0x00000004 (Deterministic Cache Parameters Leaf) and CPUID leaf 0x00000001
+ (Basic CPUID Information) to derive the topology information.
+
+
+
System topology examples
========================
--
2.34.1On 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@alien8.de>
> Signed-off-by: K Prateek Nayak <kprateek.nayak@amd.com>
> ---
> 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
© 2016 - 2025 Red Hat, Inc.