summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorChangbin Du <changbin.du@gmail.com>2019-05-08 23:21:17 +0800
committerJonathan Corbet <corbet@lwn.net>2019-05-08 14:34:09 -0600
commit848942cb2ef584752d7c41594b2cc91229fe7f01 (patch)
treefdc668df0481064c731e33ed1354d1135bf97851 /Documentation
parentf1f238a9f1ca1f1c7f53ebb7d5517066bf40c471 (diff)
downloadlwn-848942cb2ef584752d7c41594b2cc91229fe7f01.tar.gz
lwn-848942cb2ef584752d7c41594b2cc91229fe7f01.zip
Documentation: x86: convert topology.txt to reST
This converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du <changbin.du@gmail.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/x86/index.rst1
-rw-r--r--Documentation/x86/topology.rst (renamed from Documentation/x86/topology.txt)92
2 files changed, 49 insertions, 44 deletions
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index d7fc8efac192..da89bf0ad69f 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -9,3 +9,4 @@ x86-specific Documentation
:numbered:
boot
+ topology
diff --git a/Documentation/x86/topology.txt b/Documentation/x86/topology.rst
index 2953e3ec9a02..5176e5315faa 100644
--- a/Documentation/x86/topology.txt
+++ b/Documentation/x86/topology.rst
@@ -1,3 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
x86 Topology
============
@@ -33,14 +36,14 @@ The topology of a system is described in the units of:
- cores
- threads
-* Package:
-
- Packages contain a number of cores plus shared resources, e.g. DRAM
- controller, shared caches etc.
+Package
+=======
+Packages contain a number of cores plus shared resources, e.g. DRAM
+controller, shared caches etc.
- AMD nomenclature for package is 'Node'.
+AMD nomenclature for package is 'Node'.
- Package-related topology information in the kernel:
+Package-related topology information in the kernel:
- cpuinfo_x86.x86_max_cores:
@@ -66,40 +69,41 @@ The topology of a system is described in the units of:
- cpu_llc_id:
A per-CPU variable containing:
- - On Intel, the first APIC ID of the list of CPUs sharing the Last Level
- Cache
- - On AMD, the Node ID or Core Complex ID containing the Last Level
- Cache. In general, it is a number identifying an LLC uniquely on the
- system.
+ - On Intel, the first APIC ID of the list of CPUs sharing the Last Level
+ Cache
-* Cores:
+ - On AMD, the Node ID or Core Complex ID containing the Last Level
+ Cache. In general, it is a number identifying an LLC uniquely on the
+ system.
- A core consists of 1 or more threads. It does not matter whether the threads
- are SMT- or CMT-type threads.
+Cores
+=====
+A core consists of 1 or more threads. It does not matter whether the threads
+are SMT- or CMT-type threads.
- AMDs nomenclature for a CMT core is "Compute Unit". The kernel always uses
- "core".
+AMDs nomenclature for a CMT core is "Compute Unit". The kernel always uses
+"core".
- Core-related topology information in the kernel:
+Core-related topology information in the kernel:
- smp_num_siblings:
The number of threads in a core. The number of threads in a package can be
- calculated by:
+ calculated by::
threads_per_package = cpuinfo_x86.x86_max_cores * smp_num_siblings
-* Threads:
+Threads
+=======
+A thread is a single scheduling unit. It's the equivalent to a logical Linux
+CPU.
- A thread is a single scheduling unit. It's the equivalent to a logical Linux
- CPU.
+AMDs nomenclature for CMT threads is "Compute Unit Core". The kernel always
+uses "thread".
- AMDs nomenclature for CMT threads is "Compute Unit Core". The kernel always
- uses "thread".
-
- Thread-related topology information in the kernel:
+Thread-related topology information in the kernel:
- topology_core_cpumask():
@@ -113,15 +117,15 @@ The topology of a system is described in the units of:
The cpumask contains all online threads in the core to which a thread
belongs.
- - topology_logical_package_id():
+ - topology_logical_package_id():
The logical package ID to which a thread belongs.
- - topology_physical_package_id():
+ - topology_physical_package_id():
The physical package ID to which a thread belongs.
- - topology_core_id();
+ - topology_core_id();
The ID of the core to which a thread belongs. It is also printed in /proc/cpuinfo
"core_id."
@@ -129,41 +133,41 @@ The topology of a system is described in the units of:
System topology examples
+========================
-Note:
-
-The alternative Linux CPU enumeration depends on how the BIOS enumerates the
-threads. Many BIOSes enumerate all threads 0 first and then all threads 1.
-That has the "advantage" that the logical Linux CPU numbers of threads 0 stay
-the same whether threads are enabled or not. That's merely an implementation
-detail and has no practical impact.
+.. note::
+ The alternative Linux CPU enumeration depends on how the BIOS enumerates the
+ threads. Many BIOSes enumerate all threads 0 first and then all threads 1.
+ That has the "advantage" that the logical Linux CPU numbers of threads 0 stay
+ the same whether threads are enabled or not. That's merely an implementation
+ detail and has no practical impact.
-1) Single Package, Single Core
+1) Single Package, Single Core::
[package 0] -> [core 0] -> [thread 0] -> Linux CPU 0
2) Single Package, Dual Core
- a) One thread per core
+ a) One thread per core::
[package 0] -> [core 0] -> [thread 0] -> Linux CPU 0
-> [core 1] -> [thread 0] -> Linux CPU 1
- b) Two threads per core
+ b) Two threads per core::
[package 0] -> [core 0] -> [thread 0] -> Linux CPU 0
-> [thread 1] -> Linux CPU 1
-> [core 1] -> [thread 0] -> Linux CPU 2
-> [thread 1] -> Linux CPU 3
- Alternative enumeration:
+ Alternative enumeration::
[package 0] -> [core 0] -> [thread 0] -> Linux CPU 0
-> [thread 1] -> Linux CPU 2
-> [core 1] -> [thread 0] -> Linux CPU 1
-> [thread 1] -> Linux CPU 3
- AMD nomenclature for CMT systems:
+ AMD nomenclature for CMT systems::
[node 0] -> [Compute Unit 0] -> [Compute Unit Core 0] -> Linux CPU 0
-> [Compute Unit Core 1] -> Linux CPU 1
@@ -172,7 +176,7 @@ detail and has no practical impact.
4) Dual Package, Dual Core
- a) One thread per core
+ a) One thread per core::
[package 0] -> [core 0] -> [thread 0] -> Linux CPU 0
-> [core 1] -> [thread 0] -> Linux CPU 1
@@ -180,7 +184,7 @@ detail and has no practical impact.
[package 1] -> [core 0] -> [thread 0] -> Linux CPU 2
-> [core 1] -> [thread 0] -> Linux CPU 3
- b) Two threads per core
+ b) Two threads per core::
[package 0] -> [core 0] -> [thread 0] -> Linux CPU 0
-> [thread 1] -> Linux CPU 1
@@ -192,7 +196,7 @@ detail and has no practical impact.
-> [core 1] -> [thread 0] -> Linux CPU 6
-> [thread 1] -> Linux CPU 7
- Alternative enumeration:
+ Alternative enumeration::
[package 0] -> [core 0] -> [thread 0] -> Linux CPU 0
-> [thread 1] -> Linux CPU 4
@@ -204,7 +208,7 @@ detail and has no practical impact.
-> [core 1] -> [thread 0] -> Linux CPU 3
-> [thread 1] -> Linux CPU 7
- AMD nomenclature for CMT systems:
+ AMD nomenclature for CMT systems::
[node 0] -> [Compute Unit 0] -> [Compute Unit Core 0] -> Linux CPU 0
-> [Compute Unit Core 1] -> Linux CPU 1