Received: by 2002:a25:4158:0:0:0:0:0 with SMTP id o85csp1815487yba; Sat, 27 Apr 2019 07:42:56 -0700 (PDT) X-Google-Smtp-Source: APXvYqwvAUWVQaUXFq1otAKEeDqrUBZI+5wg6G4o2YzZnnR3EXNxhv+gRiEZ70wnLC3N/8LYn6aE X-Received: by 2002:a17:902:e185:: with SMTP id cd5mr11665826plb.124.1556376176256; Sat, 27 Apr 2019 07:42:56 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1556376176; cv=none; d=google.com; s=arc-20160816; b=dYXdln+fHcMYa4022KPu6pf52TqIhGt1D3+2CWHLYQ2umTg6EjZ5UJJ9hBFCPHrfKS +ms4QDVcaszx0CCCbM+9ffKoUvrJCC+hfCYguSEP+gBJJGNmrUEVvLrrFHcryBoa2GKE +tPl/ehFrgx/DTfwWQmYyePzhjwS/AkDfl24TciBnHAZ2GSO8WMRmTjQSEj5FrMBkM0B SgCn3DgRWzR0YYrOjFy/ABfv/z0mury2SVXwmhtItNUwzgxAOs1QTRdlvWZb0+nvJg2r 6e866/gWmtrd0ftwZpA7aURloJt/EGKcd49Q7ghwxizQAM0oN2muc2eVfOoRd2pV1VB2 OnZw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:subject:cc:to:from:date :dkim-signature; bh=ws+mFvuDPU5R9sCajelbZqczWkg7DqO0k2aub68jS/w=; b=gqK4HSt42w0gXXX19iHHQl8vYSxpmNbK9zDOlJ6BQbI/irlLyQlGYwu1SLo0rhOGJq OAJcOCu9kbynLy39d0nqFgHEjfNRvPceg7N35uiu9aOwGR5N1XGoTInTXV+0WbUCPYxj s1B8SGdKW8x2NZ2xWXPgGpjkEd3YneyXaeXEpaOlKE+pVPuqbCqa7fBIcRBOO4rOSu7u Q/9qNF7JkgTFZip5NS4SnFPiKLcd4pxe2RE7x2t7OKZJkQ6pZpKHo2WVtAR5/G/adW2u pdEWYsR1J7Rv6jnFV9rZuKMOp+CFowwdFd3m37c7s/kw6s91x/Nf665cfGwZwp+IKRxj OUhQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@infradead.org header.s=casper.20170209 header.b=LBheJcgT; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id 31si29528856plk.42.2019.04.27.07.42.41; Sat, 27 Apr 2019 07:42:56 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=fail header.i=@infradead.org header.s=casper.20170209 header.b=LBheJcgT; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726157AbfD0Olv (ORCPT + 99 others); Sat, 27 Apr 2019 10:41:51 -0400 Received: from casper.infradead.org ([85.118.1.10]:42152 "EHLO casper.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725942AbfD0Olv (ORCPT ); Sat, 27 Apr 2019 10:41:51 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.20170209; h=Content-Transfer-Encoding:Content-Type: MIME-Version:References:In-Reply-To:Message-ID:Subject:Cc:To:From:Date:Sender :Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=ws+mFvuDPU5R9sCajelbZqczWkg7DqO0k2aub68jS/w=; b=LBheJcgTsVav3/sVVHMZnvwgDS 8HuwuyEvGpYwmDagSGn+LC87AVCp8q8N/aV2367cxyEsJaXxy8SHMWCzG1gwek/Ss2+JGKk3VLVd3 AIJYf3tYNTsCyyNVc7A8Cxp48OiGgNfAW11n5tD4L6rVuW0oOOMmjcJeQmNlC3nStsBJDCoJNrucb hUAZ/FK36yI7kin6Gm3qA4I04F7nC35t6XX9fMrFPRWnPNVeDQvH9Kv8dkiaPU7aXeXQA/u7FMAqo 5oe0zSOR2+gJo35/5qxMGSEiUWFkU1GuLkr5fG7FwvdauZgzdUUpe4H6ENE5rC3oCaKNm5oEFQS3S wTJ9+Qxg==; Received: from 177.17.250.151.dynamic.adsl.gvt.net.br ([177.17.250.151] helo=coco.lan) by casper.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1hKOWO-0007f0-Ft; Sat, 27 Apr 2019 14:41:45 +0000 Date: Sat, 27 Apr 2019 11:41:39 -0300 From: Mauro Carvalho Chehab To: Changbin Du Cc: Jonathan Corbet , tglx@linutronix.de, mingo@redhat.com, bp@alien8.de, x86@kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH 03/27] Documentation: x86: convert topology.txt to reST Message-ID: <20190427114139.2a6c587c@coco.lan> In-Reply-To: <20190426153150.21228-4-changbin.du@gmail.com> References: <20190426153150.21228-1-changbin.du@gmail.com> <20190426153150.21228-4-changbin.du@gmail.com> X-Mailer: Claws Mail 3.17.3 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Fri, 26 Apr 2019 23:31:26 +0800 Changbin Du escreveu: > 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 Reviewed-by: Mauro Carvalho Chehab > --- > 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 8f08caf4fbbb..2033791e53bc 100644 > --- a/Documentation/x86/index.rst > +++ b/Documentation/x86/index.rst > @@ -9,3 +9,4 @@ Linux x86 Support > :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 Thanks, Mauro