LKML Archive on lore.kernel.org
help / color / mirror / Atom feed
From: Changbin Du <changbin.du@gmail.com>
To: corbet@lwn.net, tglx@linutronix.de, mingo@redhat.com, bp@alien8.de
Cc: x86@kernel.org, linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org, Changbin Du <changbin.du@gmail.com>,
	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Subject: [PATCH v4 03/27] Documentation: x86: convert topology.txt to reST
Date: Wed,  8 May 2019 23:21:17 +0800	[thread overview]
Message-ID: <20190508152141.8740-4-changbin.du@gmail.com> (raw)
In-Reply-To: <20190508152141.8740-1-changbin.du@gmail.com>

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>
---
 Documentation/x86/index.rst                   |  1 +
 .../x86/{topology.txt => topology.rst}        | 92 ++++++++++---------
 2 files changed, 49 insertions(+), 44 deletions(-)
 rename Documentation/x86/{topology.txt => topology.rst} (74%)

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
similarity index 74%
rename from Documentation/x86/topology.txt
rename to 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
-- 
2.20.1


  parent reply	other threads:[~2019-05-08 15:22 UTC|newest]

Thread overview: 29+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-05-08 15:21 [PATCH v4 00/27] Include linux x86 docs into Sphinx TOC tree Changbin Du
2019-05-08 15:21 ` [PATCH v4 01/27] Documentation: add Linux x86 docs to " Changbin Du
2019-05-08 15:21 ` [PATCH v4 02/27] Documentation: x86: convert boot.txt to reST Changbin Du
2019-05-08 15:21 ` Changbin Du [this message]
2019-05-08 15:21 ` [PATCH v4 04/27] Documentation: x86: convert exception-tables.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 05/27] Documentation: x86: convert kernel-stacks " Changbin Du
2019-05-08 15:21 ` [PATCH v4 06/27] Documentation: x86: convert entry_64.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 07/27] Documentation: x86: convert earlyprintk.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 08/27] Documentation: x86: convert zero-page.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 09/27] Documentation: x86: convert tlb.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 10/27] Documentation: x86: convert mtrr.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 11/27] Documentation: x86: convert pat.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 12/27] Documentation: x86: convert protection-keys.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 13/27] Documentation: x86: convert intel_mpx.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 14/27] Documentation: x86: convert amd-memory-encryption.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 15/27] Documentation: x86: convert pti.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 16/27] Documentation: x86: convert microcode.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 17/27] Documentation: x86: convert resctrl_ui.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 18/27] Documentation: x86: convert orc-unwinder.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 19/27] Documentation: x86: convert usb-legacy-support.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 20/27] Documentation: x86: convert i386/IO-APIC.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 21/27] Documentation: x86: convert x86_64/boot-options.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 22/27] Documentation: x86: convert x86_64/uefi.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 23/27] Documentation: x86: convert x86_64/mm.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 24/27] Documentation: x86: convert x86_64/5level-paging.txt " Changbin Du
2019-05-08 15:21 ` [PATCH v4 25/27] Documentation: x86: convert x86_64/fake-numa-for-cpusets " Changbin Du
2019-05-08 15:21 ` [PATCH v4 26/27] Documentation: x86: convert x86_64/cpu-hotplug-spec " Changbin Du
2019-05-08 15:21 ` [PATCH v4 27/27] Documentation: x86: convert x86_64/machinecheck " Changbin Du
2019-05-08 20:40 ` [PATCH v4 00/27] Include linux x86 docs into Sphinx TOC tree Jonathan Corbet

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190508152141.8740-4-changbin.du@gmail.com \
    --to=changbin.du@gmail.com \
    --cc=bp@alien8.de \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mchehab+samsung@kernel.org \
    --cc=mingo@redhat.com \
    --cc=tglx@linutronix.de \
    --cc=x86@kernel.org \
    --subject='Re: [PATCH v4 03/27] Documentation: x86: convert topology.txt to reST' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).