From nobody Mon Feb 9 20:59:59 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=nongnu.org ARC-Seal: i=1; a=rsa-sha256; t=1640683551; cv=none; d=zohomail.com; s=zohoarc; b=T1R5pMfvcYsdVfrnUKf4SRZisYgxxykURf8NO6Sz74ZU8WqkLVJRdFdczeY1O6SZw6/BydAbUtdnb/+gK05brUokvj3cwynF9ylNqU2MwZfdkah6krA6BARG/Cxq7YrrClXNxSY2Bq+FylgjtHMEr3jMfZgOh8DNCd1U6lu1LX4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1640683551; h=Content-Type:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To; bh=pmnc+VGLOtPXnHuOpKcXtWjlOVMjwBF383Okgwyu70U=; b=dkmzpQ4F/q6jTwaKJbvPRz3b5VGhPmwm/D03waCr1cQhPbHmTY6SMTQJkzpGY3Xz2tovm+J0O997kvlqQR5wHs11Z1MC/2DPqYKKwucxu7B/qSQug3CuKBNjB1MkL3NR6/6KOunoIW5s2K5Ljy0Q43okRfeD0oppdlqlAUuFI9E= ARC-Authentication-Results: i=1; mx.zohomail.com; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1640683551403314.6923586606184; Tue, 28 Dec 2021 01:25:51 -0800 (PST) Received: from localhost ([::1]:43858 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n28ju-0004Gd-OA for importer@patchew.org; Tue, 28 Dec 2021 04:25:50 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52100) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n28h2-0007cH-Dg; Tue, 28 Dec 2021 04:22:52 -0500 Received: from szxga01-in.huawei.com ([45.249.212.187]:3433) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n28gy-00077U-SB; Tue, 28 Dec 2021 04:22:52 -0500 Received: from dggpemm500023.china.huawei.com (unknown [172.30.72.56]) by szxga01-in.huawei.com (SkyGuard) with ESMTP id 4JNTZW2rNFzcb82; Tue, 28 Dec 2021 17:22:11 +0800 (CST) Received: from DESKTOP-TMVL5KK.china.huawei.com (10.174.187.128) by dggpemm500023.china.huawei.com (7.185.36.83) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2308.20; Tue, 28 Dec 2021 17:22:38 +0800 To: , CC: Peter Maydell , Andrew Jones , Eduardo Habkost , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Marcel Apfelbaum , Paolo Bonzini , "Michael S . Tsirkin" , Igor Mammedov , Shannon Zhao , Ani Sinha , Markus Armbruster , Eric Blake , , Yanan Wang Subject: [PATCH v5 01/14] qemu-options: Improve readability of SMP related Docs Date: Tue, 28 Dec 2021 17:22:08 +0800 Message-ID: <20211228092221.21068-2-wangyanan55@huawei.com> X-Mailer: git-send-email 2.8.4.windows.1 In-Reply-To: <20211228092221.21068-1-wangyanan55@huawei.com> References: <20211228092221.21068-1-wangyanan55@huawei.com> MIME-Version: 1.0 X-Originating-IP: [10.174.187.128] X-ClientProxiedBy: dggems703-chm.china.huawei.com (10.3.19.180) To dggpemm500023.china.huawei.com (7.185.36.83) X-CFilter-Loop: Reflected Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=45.249.212.187; envelope-from=wangyanan55@huawei.com; helo=szxga01-in.huawei.com X-Spam_score_int: -41 X-Spam_score: -4.2 X-Spam_bar: ---- X-Spam_report: (-4.2 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Reply-to: Yanan Wang From: Yanan Wang via X-ZM-MESSAGEID: 1640683552805000001 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" We have a description in qemu-options.hx for each CPU topology parameter to explain what it exactly means, and also an extra declaration for the target-specific one, e.g. "for PC only" when describing "dies", and "for PC, it's on one die" when describing "cores". Now we are going to introduce one more non-generic parameter "clusters", it will make the Doc less readable and if we still continue to use the legacy way to describe it. So let's at first make two tweaks of the Docs to improve the readability and also scalability: 1) In the -help text: Delete the extra specific declaration and describe each topology parameter level by level. Then add a note to declare that different machines may support different subsets and the actual meaning of the supported parameters will vary accordingly. 2) In the rST text: List all the sub-hierarchies currently supported in QEMU, and correspondingly give an example of -smp configuration for each of them. Signed-off-by: Yanan Wang Reviewed-by: Philippe Mathieu-Daud=C3=A9 --- qemu-options.hx | 76 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 59 insertions(+), 17 deletions(-) diff --git a/qemu-options.hx b/qemu-options.hx index 7d47510947..b39377de3f 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -207,14 +207,26 @@ ERST =20 DEF("smp", HAS_ARG, QEMU_OPTION_smp, "-smp [[cpus=3D]n][,maxcpus=3Dmaxcpus][,sockets=3Dsockets][,dies=3Ddie= s][,cores=3Dcores][,threads=3Dthreads]\n" - " set the number of CPUs to 'n' [default=3D1]\n" + " set the number of initial CPUs to 'n' [default=3D1]\n" " maxcpus=3D maximum number of total CPUs, including\n" " offline CPUs for hotplug, etc\n" - " sockets=3D number of discrete sockets in the system\n" - " dies=3D number of CPU dies on one socket (for PC only= )\n" - " cores=3D number of CPU cores on one socket (for PC, i= t's on one die)\n" - " threads=3D number of threads on one CPU core\n", - QEMU_ARCH_ALL) + " sockets=3D number of sockets on the machine board\n" + " dies=3D number of dies in one socket\n" + " cores=3D number of cores in one die\n" + " threads=3D number of threads in one core\n" + "Note: Different machines may have different subsets of the CPU topolo= gy\n" + " parameters supported, so the actual meaning of the supported pa= rameters\n" + " will vary accordingly. For example, for a machine type that sup= ports a\n" + " three-level CPU hierarchy of sockets/cores/threads, the paramet= ers will\n" + " sequentially mean as below:\n" + " sockets means the number of sockets on the machine bo= ard\n" + " cores means the number of cores in one socket\n" + " threads means the number of threads in one core\n" + " For a particular machine type board, an expected CPU topology h= ierarchy\n" + " can be defined through the supported sub-option. Unsupported pa= rameters\n" + " can also be provided in addition to the sub-option, but their v= alues\n" + " must be set as 1 in the purpose of correct parsing.\n", + QEMU_ARCH_ALL) SRST ``-smp [[cpus=3D]n][,maxcpus=3Dmaxcpus][,sockets=3Dsockets][,dies=3Ddies][= ,cores=3Dcores][,threads=3Dthreads]`` Simulate a SMP system with '\ ``n``\ ' CPUs initially present on @@ -225,27 +237,57 @@ SRST initial CPU count will match the maximum number. When only one of them is given then the omitted one will be set to its counterpart's value. Both parameters may be specified, but the maximum number of CPUs must - be equal to or greater than the initial CPU count. Both parameters are - subject to an upper limit that is determined by the specific machine - type chosen. - - To control reporting of CPU topology information, the number of socket= s, - dies per socket, cores per die, and threads per core can be specified. - The sum `` sockets * cores * dies * threads `` must be equal to the - maximum CPU count. CPU targets may only support a subset of the topolo= gy - parameters. Where a CPU target does not support use of a particular - topology parameter, its value should be assumed to be 1 for the purpose - of computing the CPU maximum count. + be equal to or greater than the initial CPU count. Product of the + CPU topology hierarchy must be equal to the maximum number of CPUs. + Both parameters are subject to an upper limit that is determined by + the specific machine type chosen. + + To control reporting of CPU topology information, values of the topolo= gy + parameters can be specified. Machines may only support a subset of the + parameters and different machines may have different subsets supported + which vary depending on capacity of the corresponding CPU targets. So + for a particular machine type board, an expected topology hierarchy can + be defined through the supported sub-option. Unsupported parameters can + also be provided in addition to the sub-option, but their values must = be + set as 1 in the purpose of correct parsing. =20 Either the initial CPU count, or at least one of the topology paramete= rs must be specified. The specified parameters must be greater than zero, explicit configuration like "cpus=3D0" is not allowed. Values for any omitted parameters will be computed from those which are given. + + For example, the following sub-option defines a CPU topology hierarchy + (2 sockets totally on the machine, 2 cores per socket, 2 threads per + core) for a machine that only supports sockets/cores/threads. + Some members of the option can be omitted but their values will be + automatically computed: + + :: + + -smp 8,sockets=3D2,cores=3D2,threads=3D2,maxcpus=3D8 + + The following sub-option defines a CPU topology hierarchy (2 sockets + totally on the machine, 2 dies per socket, 2 cores per die, 2 threads + per core) for PC machines which support sockets/dies/cores/threads. + Some members of the option can be omitted but their values will be + automatically computed: + + :: + + -smp 16,sockets=3D2,dies=3D2,cores=3D2,threads=3D2,maxcpus=3D16 + Historically preference was given to the coarsest topology parameters when computing missing values (ie sockets preferred over cores, which were preferred over threads), however, this behaviour is considered liable to change. Prior to 6.2 the preference was sockets over cores over threads. Since 6.2 the preference is cores over sockets over thre= ads. + + For example, the following option defines a machine board with 2 socke= ts + of 1 core before 6.2 and 1 socket of 2 cores after 6.2: + + :: + + -smp 2 ERST =20 DEF("numa", HAS_ARG, QEMU_OPTION_numa, --=20 2.27.0