Skip to contentSkip to conversation

docs: improve -smp documentation

PATCH Applied Daniel P. Berrangé 5 participants 16 messages Jun 28, 2021 – Jul 13, 2021

v1 of 2 Applied Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover docs: improve -smp documentation

This is a spin off from this thread:

https://lists.gnu.org/archive/html/qemu-devel/2021-06/msg06135.html

to improve the documentation of the current behaviour of -smp arg. In that thread it is suggested that we change the behaviour to prefer use of cores over sockets, when topology is omitted. This documentation update explicitly notes that default topology is liable to change, to allow for this enhancement.

Daniel P. Berrangé (4):
docs: fix typo s/Intel/AMD/ in CPU model notes
qemu-options: re-arrange CPU topology options
qemu-options: tweak to show that CPU count is optional
qemu-options: rewrite help for -smp options

 docs/system/cpu-models-x86.rst.inc |  2 +-
 qemu-options.hx                    | 37 ++++++++++++++++++++----------
 2 files changed, 26 insertions(+), 13 deletions(-)
Signature · 1 line
2.31.1
#1 lore raw

PATCH 1/4 docs: fix typo s/Intel/AMD/ in CPU model notes

---
 docs/system/cpu-models-x86.rst.inc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
docs/system/cpu-models-x86.rst.inc +1 -1
index f40ee03ecc..9119f5dff5 100644
@@ -227,7 +227,7 @@ features are included if using "Host passthrough" or "Host model".
 Preferred CPU models for AMD x86 hosts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The following CPU models are preferred for use on Intel hosts.
+The following CPU models are preferred for use on AMD hosts.
 Administrators / applications are recommended to use the CPU model that
 matches the generation of the host CPUs in use. In a deployment with a
 mixture of host CPU models between machines, if live migration
Signature · 1 line
2.31.1
Reviewed-by on v1 1/4
#2 lore raw

Re: [PATCH 1/4] docs: fix typo s/Intel/AMD/ in CPU model notes

Hi Daniel,

Quoted 10 lines · Daniel P. Berrangé
---
  docs/system/cpu-models-x86.rst.inc | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
docs/system/cpu-models-x86.rst.inc +0 -0
index f40ee03ecc..9119f5dff5 100644

docs/system/cpu-models-x86.rst.inc features are included if using "Host passthrough" or "Host model". · line 233

Quoted 8 lines
docs/system/cpu-models-x86.rst.inc +1 -1
@@ -227,7 +227,7 @@ features are included if using "Host passthrough" or "Host model".
  Preferred CPU models for AMD x86 hosts
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The following CPU models are preferred for use on Intel hosts.
+The following CPU models are preferred for use on AMD hosts.
  Administrators / applications are recommended to use the CPU model that
  matches the generation of the host CPUs in use. In a deployment with a
  mixture of host CPU models between machines, if live migration

Thanks,
Yanan
.

#3 lore raw

PATCH 2/4 qemu-options: re-arrange CPU topology options

In reply to Daniel P. Berrangé

The list of CPU topology options are presented in a fairly arbitrary order currently. Re-arrange them so that they're ordered from largest to smallest unit

---
 qemu-options.hx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
qemu-options.hx +4 -4
index ba3ca9da1d..aa33dfdcfd 100644
@@ -196,17 +196,17 @@ SRST
 ERST
 
 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
-    "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
+    "-smp [cpus=]n[,maxcpus=cpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]\n"
     "                set the number of CPUs to 'n' [default=1]\n"
     "                maxcpus= maximum number of total cpus, including\n"
     "                offline CPUs for hotplug, etc\n"
+    "                sockets= number of discrete sockets in the system\n",
+    "                dies= number of CPU dies on one socket (for PC only)\n"
     "                cores= number of CPU cores on one socket (for PC, it's on one die)\n"
     "                threads= number of threads on one CPU core\n"
-    "                dies= number of CPU dies on one socket (for PC only)\n"
-    "                sockets= number of discrete sockets in the system\n",
         QEMU_ARCH_ALL)
 SRST
-``-smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]``
+``-smp [cpus=]n[,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
     Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
     are supported. On Sparc32 target, Linux limits the number of usable
     CPUs to 4. For the PC target, the number of cores per die, the
Signature · 1 line
2.31.1
Reviewed-by on v1 2/4
#4 lore raw

Re: [PATCH 2/4] qemu-options: re-arrange CPU topology options

Quoted 14 lines · Daniel P. Berrangé

The list of CPU topology options are presented in a fairly arbitrary order currently. Re-arrange them so that they're ordered from largest to smallest unit

---
  qemu-options.hx | 8 ++++----
  1 file changed, 4 insertions(+), 4 deletions(-)
qemu-options.hx +0 -0
index ba3ca9da1d..aa33dfdcfd 100644

qemu-options.hx SRST · line 201

Quoted 7 lines
qemu-options.hx +1 -1
@@ -196,17 +196,17 @@ SRST
  ERST
 
  DEF("smp", HAS_ARG, QEMU_OPTION_smp,
-    "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
+    "-smp [cpus=]n[,maxcpus=cpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]\n"
      "                set the number of CPUs to 'n' [default=1]\n"
      "                maxcpus= maximum number of total cpus, including\n"

nit: There are always "CPUs" elsewhere, it's better to also use "total CPUs" here.

Quoted 4 lines
qemu-options.hx +2 -0
      "                offline CPUs for hotplug, etc\n"
+    "                sockets= number of discrete sockets in the system\n",
+    "                dies= number of CPU dies on one socket (for PC only)\n"
      "                cores= number of CPU cores on one socket (for PC, it's on one die)\n"

qemu-options.hx SRST · line 212

Quoted 10 lines
qemu-options.hx +1 -3
      "                threads= number of threads on one CPU core\n"
-    "                dies= number of CPU dies on one socket (for PC only)\n"
-    "                sockets= number of discrete sockets in the system\n",
          QEMU_ARCH_ALL)
  SRST
-``-smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]``
+``-smp [cpus=]n[,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
      Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
      are supported. On Sparc32 target, Linux limits the number of usable
      CPUs to 4. For the PC target, the number of cores per die, the

This improves the readability a lot,

Thanks,
Yanan
.

#5 lore raw

Re: [PATCH 2/4] qemu-options: re-arrange CPU topology options

In reply to Daniel P. Berrangé
Quoted 19 lines · Daniel P. Berrangé

The list of CPU topology options are presented in a fairly arbitrary order currently. Re-arrange them so that they're ordered from largest to smallest unit

---
 qemu-options.hx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
qemu-options.hx +1 -1
index ba3ca9da1d..aa33dfdcfd 100644
@@ -196,17 +196,17 @@ SRST
 ERST
 
 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
-    "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
+    "-smp [cpus=]n[,maxcpus=cpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]\n"

qemu-options.hx SRST · line 207

Quoted 10 lines
qemu-options.hx +2 -2
     "                set the number of CPUs to 'n' [default=1]\n"
     "                maxcpus= maximum number of total cpus, including\n"
     "                offline CPUs for hotplug, etc\n"
+    "                sockets= number of discrete sockets in the system\n",
+    "                dies= number of CPU dies on one socket (for PC only)\n"
     "                cores= number of CPU cores on one socket (for PC, it's on one die)\n"
     "                threads= number of threads on one CPU core\n"
-    "                dies= number of CPU dies on one socket (for PC only)\n"
-    "                sockets= number of discrete sockets in the system\n",
         QEMU_ARCH_ALL)

Stupid typo in this posting - didn't adjust the trailing ',' when moving the lines.

Quoted 9 lines
qemu-options.hx +1 -1
 SRST
-``-smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]``
+``-smp [cpus=]n[,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
     Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
     are supported. On Sparc32 target, Linux limits the number of usable
     CPUs to 4. For the PC target, the number of cores per die, the
Signature · 1 line
2.31.1

Regards,
Daniel

Signature · 3 lines
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
#6 lore raw

Re: [PATCH 2/4] qemu-options: re-arrange CPU topology options

Quoted 17 lines · Daniel P. Berrangé
Quoted 16 lines · Daniel P. Berrangé

The list of CPU topology options are presented in a fairly arbitrary order currently. Re-arrange them so that they're ordered from largest to smallest unit

---
  qemu-options.hx | 8 ++++----
  1 file changed, 4 insertions(+), 4 deletions(-)
qemu-options.hx +0 -0
index ba3ca9da1d..aa33dfdcfd 100644
@@ -196,17 +196,17 @@ SRST
  ERST
 
Quoted 15 lines

qemu-options.hx SRST · line 207

Quoted 13 lines
qemu-options.hx +3 -3
  DEF("smp", HAS_ARG, QEMU_OPTION_smp,
-    "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
+    "-smp [cpus=]n[,maxcpus=cpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]\n"
      "                set the number of CPUs to 'n' [default=1]\n"
      "                maxcpus= maximum number of total cpus, including\n"
      "                offline CPUs for hotplug, etc\n"
+    "                sockets= number of discrete sockets in the system\n",
+    "                dies= number of CPU dies on one socket (for PC only)\n"
      "                cores= number of CPU cores on one socket (for PC, it's on one die)\n"
      "                threads= number of threads on one CPU core\n"
-    "                dies= number of CPU dies on one socket (for PC only)\n"
-    "                sockets= number of discrete sockets in the system\n",
          QEMU_ARCH_ALL)

Stupid typo in this posting - didn't adjust the trailing ',' when moving the lines.

I can fix it incidentally in [1] if you wish. :)

[1] https://lists.gnu.org/archive/html/qemu-devel/2021-07/msg00259.html

Thanks,
Yanan
.

Quoted 11 lines
Quoted 9 lines
qemu-options.hx +1 -1
  SRST
-``-smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]``
+``-smp [cpus=]n[,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
      Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
      are supported. On Sparc32 target, Linux limits the number of usable
      CPUs to 4. For the PC target, the number of cores per die, the
Signature · 1 line
2.31.1

Regards,
Daniel

Reviewed-by on v1 2/4
#7 lore raw

Re: [PATCH 2/4] qemu-options: re-arrange CPU topology options

In reply to Daniel P. Berrangé
Quoted 25 lines

The list of CPU topology options are presented in a fairly arbitrary order currently. Re-arrange them so that they're ordered from largest to smallest unit

---
 qemu-options.hx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
qemu-options.hx +3 -1
index ba3ca9da1d..aa33dfdcfd 100644
@@ -196,17 +196,17 @@ SRST
 ERST
 
 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
-    "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
+    "-smp [cpus=]n[,maxcpus=cpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]\n"
     "                set the number of CPUs to 'n' [default=1]\n"
     "                maxcpus= maximum number of total cpus, including\n"
     "                offline CPUs for hotplug, etc\n"
+    "                sockets= number of discrete sockets in the system\n",
+    "                dies= number of CPU dies on one socket (for PC only)\n"
     "                cores= number of CPU cores on one socket (for PC, it's on one die)\n"

qemu-options.hx SRST · line 212

Quoted 10 lines
qemu-options.hx +1 -3
     "                threads= number of threads on one CPU core\n"
-    "                dies= number of CPU dies on one socket (for PC only)\n"
-    "                sockets= number of discrete sockets in the system\n",
         QEMU_ARCH_ALL)
 SRST
-``-smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]``
+``-smp [cpus=]n[,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
     Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
     are supported. On Sparc32 target, Linux limits the number of usable
     CPUs to 4. For the PC target, the number of cores per die, the

Looks cleaner. With the nit mentioned by Dan:

#8 lore raw

PATCH 3/4 qemu-options: tweak to show that CPU count is optional

In reply to Daniel P. Berrangé

The initial CPU count number is not required, if any of the topology options are given, since it can be computed.

---
 qemu-options.hx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
qemu-options.hx +2 -2
index aa33dfdcfd..5871df7291 100644
@@ -196,7 +196,7 @@ SRST
 ERST
 
 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
-    "-smp [cpus=]n[,maxcpus=cpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]\n"
+    "-smp [[cpus=]n][,maxcpus=cpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]\n"
     "                set the number of CPUs to 'n' [default=1]\n"
     "                maxcpus= maximum number of total cpus, including\n"
     "                offline CPUs for hotplug, etc\n"
@@ -206,7 +206,7 @@ DEF("smp", HAS_ARG, QEMU_OPTION_smp,
     "                threads= number of threads on one CPU core\n"
         QEMU_ARCH_ALL)
 SRST
-``-smp [cpus=]n[,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
+``-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
     Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
     are supported. On Sparc32 target, Linux limits the number of usable
     CPUs to 4. For the PC target, the number of cores per die, the
Signature · 1 line
2.31.1
Reviewed-by on v1 3/4
#9 lore raw

Re: [PATCH 3/4] qemu-options: tweak to show that CPU count is optional

Quoted 22 lines · Daniel P. Berrangé

The initial CPU count number is not required, if any of the topology options are given, since it can be computed.

---
  qemu-options.hx | 4 ++--
  1 file changed, 2 insertions(+), 2 deletions(-)
qemu-options.hx +1 -1
index aa33dfdcfd..5871df7291 100644
@@ -196,7 +196,7 @@ SRST
  ERST
 
  DEF("smp", HAS_ARG, QEMU_OPTION_smp,
-    "-smp [cpus=]n[,maxcpus=cpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]\n"
+    "-smp [[cpus=]n][,maxcpus=cpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]\n"
      "                set the number of CPUs to 'n' [default=1]\n"
      "                maxcpus= maximum number of total cpus, including\n"
      "                offline CPUs for hotplug, etc\n"

qemu-options.hx DEF("smp", HAS_ARG, QEMU_OPTION_smp, · line 212

Quoted 8 lines
qemu-options.hx +1 -1
@@ -206,7 +206,7 @@ DEF("smp", HAS_ARG, QEMU_OPTION_smp,
      "                threads= number of threads on one CPU core\n"
          QEMU_ARCH_ALL)
  SRST
-``-smp [cpus=]n[,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
+``-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
      Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
      are supported. On Sparc32 target, Linux limits the number of usable
      CPUs to 4. For the PC target, the number of cores per die, the

This looks correct to me:

Thanks,
Yanan
.

#10 lore raw

PATCH 4/4 qemu-options: rewrite help for -smp options

In reply to Daniel P. Berrangé

The -smp option help is peculiarly specific about mentioning the CPU upper limits, but these are wrong. The "PC" target has varying max CPU counts depending on the machine type picked. Notes about guest OS limits are inappropriate for QEMU docs. There are way too many machine types for it to be practical to mention actual limits, and some limits are even modified by downstream distribtions. Thus it is better to remove the specific limits entirely.

The CPU topology reporting is also not neccessarily specific to the PC platform and descriptions around the rules of usage are somewhat terse. Expand this information with some examples to show effects of defaulting.

---
 qemu-options.hx | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)
qemu-options.hx +21 -8
index 5871df7291..0021e9ec7b 100644
@@ -207,14 +207,27 @@ DEF("smp", HAS_ARG, QEMU_OPTION_smp,
         QEMU_ARCH_ALL)
 SRST
 ``-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
-    Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
-    are supported. On Sparc32 target, Linux limits the number of usable
-    CPUs to 4. For the PC target, the number of cores per die, the
-    number of threads per cores, the number of dies per packages and the
-    total number of sockets can be specified. Missing values will be
-    computed. If any on the three values is given, the total number of
-    CPUs n can be omitted. maxcpus specifies the maximum number of
-    hotpluggable CPUs.
+    Simulate an SMP system with '\ ``n``\ ' CPUs initially present on
+    the machine type board. On boards supporting CPU hotplug, the optional
+    '\ ``maxcpus``\ ' parameter can be set to enable further CPUs to be
+    added at runtime. If omitted the maximum number of CPUs will be
+    set to match 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 sockets,
+    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 topology
+    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.
+
+    Either the initial CPU count, or at least one of the topology parameters
+    must be specified. Values for any omitted parameters will be computed
+    from those which are given. 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.
 ERST
 
 DEF("numa", HAS_ARG, QEMU_OPTION_numa,
Signature · 1 line
2.31.1
#11 lore raw

Re: [PATCH 4/4] qemu-options: rewrite help for -smp options

Hi Daniel,

Quoted 25 lines · Daniel P. Berrangé

The -smp option help is peculiarly specific about mentioning the CPU upper limits, but these are wrong. The "PC" target has varying max CPU counts depending on the machine type picked. Notes about guest OS limits are inappropriate for QEMU docs. There are way too many machine types for it to be practical to mention actual limits, and some limits are even modified by downstream distribtions. Thus it is better to remove the specific limits entirely.

The CPU topology reporting is also not neccessarily specific to the PC platform and descriptions around the rules of usage are somewhat terse. Expand this information with some examples to show effects of defaulting.

---
  qemu-options.hx | 29 +++++++++++++++++++++--------
  1 file changed, 21 insertions(+), 8 deletions(-)
qemu-options.hx +0 -0
index 5871df7291..0021e9ec7b 100644
@@ -207,14 +207,27 @@ DEF("smp", HAS_ARG, QEMU_OPTION_smp,
          QEMU_ARCH_ALL)
  SRST

qemu-options.hx DEF("smp", HAS_ARG, QEMU_OPTION_smp, · line 210

Quoted 10 lines
qemu-options.hx +1 -8
  ``-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
-    Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
-    are supported. On Sparc32 target, Linux limits the number of usable
-    CPUs to 4. For the PC target, the number of cores per die, the
-    number of threads per cores, the number of dies per packages and the
-    total number of sockets can be specified. Missing values will be
-    computed. If any on the three values is given, the total number of
-    CPUs n can be omitted. maxcpus specifies the maximum number of
-    hotpluggable CPUs.
+    Simulate an SMP system with '\ ``n``\ ' CPUs initially present on

Should be "a SMP system".

Quoted 4 lines
qemu-options.hx +4 -0
+    the machine type board. On boards supporting CPU hotplug, the optional
+    '\ ``maxcpus``\ ' parameter can be set to enable further CPUs to be
+    added at runtime. If omitted the maximum number of CPUs will be
+    set to match the initial CPU count. Both parameters are subject to

qemu-options.hx DEF("smp", HAS_ARG, QEMU_OPTION_smp, · line 224

Quoted 10 lines
qemu-options.hx +10 -0
+    an upper limit that is determined by the specific machine type chosen.
+
+    To control reporting of CPU topology information, the number of sockets,
+    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 topology
+    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.
+

Explicitly saying "sockets * dies * cores * threads" seems not arch-neutral at first glance, although we have the explanation behind. How about the following statement for this paragraph?

"
To control reporting of CPU topology information, at most the number of sockets, dies per socket, cores per die, and threads per core can be specified. CPU targets may only support a subset of the topology parameters. If a CPU target does not support use of a particular topology parameter, it must not be specified. The sum of the supported subset of parameters must be equal to the maximum CPU count. "

I think this also make it easier to expand if we are going to add one more topology parameter, e.g, cluster, in the future.

qemu-options.hx DEF("smp", HAS_ARG, QEMU_OPTION_smp, · line 233

Quoted 9 lines
qemu-options.hx +6 -0
+    Either the initial CPU count, or at least one of the topology parameters
+    must be specified. Values for any omitted parameters will be computed
+    from those which are given. 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.
  ERST
 
  DEF("numa", HAS_ARG, QEMU_OPTION_numa,

Thanks,
Yanan
.

#12 lore raw

Re: [PATCH 4/4] qemu-options: rewrite help for -smp options

Quoted 31 lines · wangyanan (Y)

Hi Daniel,

Quoted 28 lines · Daniel P. Berrangé

The -smp option help is peculiarly specific about mentioning the CPU upper limits, but these are wrong. The "PC" target has varying max CPU counts depending on the machine type picked. Notes about guest OS limits are inappropriate for QEMU docs. There are way too many machine types for it to be practical to mention actual limits, and some limits are even modified by downstream distribtions. Thus it is better to remove the specific limits entirely.

The CPU topology reporting is also not neccessarily specific to the PC platform and descriptions around the rules of usage are somewhat terse. Expand this information with some examples to show effects of defaulting.

---
  qemu-options.hx | 29 +++++++++++++++++++++--------
  1 file changed, 21 insertions(+), 8 deletions(-)
qemu-options.hx +0 -2
index 5871df7291..0021e9ec7b 100644
@@ -207,14 +207,27 @@ DEF("smp", HAS_ARG, QEMU_OPTION_smp,
          QEMU_ARCH_ALL)
  SRST
  ``-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
-    Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
-    are supported. On Sparc32 target, Linux limits the number of usable
Quoted 8 lines

qemu-options.hx DEF("smp", HAS_ARG, QEMU_OPTION_smp, · line 210

Quoted 7 lines
qemu-options.hx +1 -6
-    CPUs to 4. For the PC target, the number of cores per die, the
-    number of threads per cores, the number of dies per packages and the
-    total number of sockets can be specified. Missing values will be
-    computed. If any on the three values is given, the total number of
-    CPUs n can be omitted. maxcpus specifies the maximum number of
-    hotpluggable CPUs.
+    Simulate an SMP system with '\ ``n``\ ' CPUs initially present on

Should be "a SMP system".

Pre-existing bug, but I'll fix it anyway

Quoted 32 lines
Quoted 4 lines
qemu-options.hx +4 -0
+    the machine type board. On boards supporting CPU hotplug, the optional
+    '\ ``maxcpus``\ ' parameter can be set to enable further CPUs to be
+    added at runtime. If omitted the maximum number of CPUs will be
+    set to match the initial CPU count. Both parameters are subject to

qemu-options.hx DEF("smp", HAS_ARG, QEMU_OPTION_smp, · line 224

Quoted 10 lines
qemu-options.hx +10 -0
+    an upper limit that is determined by the specific machine type chosen.
+
+    To control reporting of CPU topology information, the number of sockets,
+    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 topology
+    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.
+

Explicitly saying "sockets * dies * cores * threads" seems not arch-neutral at
first glance, although we have the explanation behind. How about the following statement for this paragraph?

"
To control reporting of CPU topology information, at most the number of sockets,
dies per socket, cores per die, and threads per core can be specified. CPU targets
may only support a subset of the topology parameters. If a CPU target does not
support use of a particular topology parameter, it must not be specified. The sum
of the supported subset of parameters must be equal to the maximum CPU count.
"

Quoted 3 lines

I think this also make it easier to expand if we are going to add one more topology
parameter, e.g, cluster, in the future.

I won't make this suggested change, since we discussed against another patch that mgmt apps like libvirt will already be setting 'dies=1' for any target. We merely need QEMU to reject values > 1 if not supported.

Quoted 8 lines

qemu-options.hx DEF("smp", HAS_ARG, QEMU_OPTION_smp, · line 233

Quoted 8 lines
qemu-options.hx +6 -0
+    Either the initial CPU count, or at least one of the topology parameters
+    must be specified. Values for any omitted parameters will be computed
+    from those which are given. 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.
  ERST
  DEF("numa", HAS_ARG, QEMU_OPTION_numa,
Quoted 4 lines

Thanks,
Yanan
.

Regards,
Daniel

Signature · 3 lines
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
Reviewed-by on the v1 series
#13 lore raw
In reply to Daniel P. Berrangé
Quoted 16 lines · Daniel P. Berrangé

This is a spin off from this thread:

https://lists.gnu.org/archive/html/qemu-devel/2021-06/msg06135.html

to improve the documentation of the current behaviour of -smp arg. In that thread it is suggested that we change the behaviour to prefer use of cores over sockets, when topology is omitted. This documentation update explicitly notes that default topology is liable to change, to allow for this enhancement.

Daniel P. Berrangé (4):
docs: fix typo s/Intel/AMD/ in CPU model notes
qemu-options: re-arrange CPU topology options
qemu-options: tweak to show that CPU count is optional
qemu-options: rewrite help for -smp options

Quoted 8 lines
 docs/system/cpu-models-x86.rst.inc |  2 +-
 qemu-options.hx                    | 37 ++++++++++++++++++++----------
 2 files changed, 26 insertions(+), 13 deletions(-)
Signature · 1 line
2.31.1

For the series

#14 lore raw
In reply to Daniel P. Berrangé
Quoted 9 lines · Daniel P. Berrangé

This is a spin off from this thread:

https://lists.gnu.org/archive/html/qemu-devel/2021-06/msg06135.html

to improve the documentation of the current behaviour of -smp arg. In that thread it is suggested that we change the behaviour to prefer use of cores over sockets, when topology is omitted. This documentation update explicitly notes that default topology is liable to change, to allow for this enhancement.

Queued, thanks!

Signature · 1 line
Eduardo
#15 lore raw
Quoted 5 lines · Eduardo Habkost
Quoted 4 lines · Daniel P. Berrangé

This is a spin off from this thread:

https://lists.gnu.org/archive/html/qemu-devel/2021-06/msg06135.html

Quoted 7 lines
Quoted 5 lines

to improve the documentation of the current behaviour of -smp arg. In that thread it is suggested that we change the behaviour to prefer use of cores over sockets, when topology is omitted. This documentation update explicitly notes that default topology is liable to change, to allow for this enhancement.

Queued, thanks!

I had to remove it due to build failures:
https://gitlab.com/ehabkost/qemu/-/jobs/1413791527#L1139

FAILED: libqemu-microblazeel-softmmu.fa.p/softmmu_vl.c.o
cc -Ilibqemu-microblazeel-softmmu.fa.p -I. -I.. -Itarget/microblaze -I../target/microblaze -I../capstone/include/capstone -Iqapi -Itrace -Iui -Iui/shader -I/usr/include/pixman-1 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -fdiagnostics-color=auto -pipe -Wall -Winvalid-pch -Werror -std=gnu11 -O2 -g -isystem /builds/ehabkost/qemu/linux-headers -isystem linux-headers -iquote . -iquote /builds/ehabkost/qemu -iquote /builds/ehabkost/qemu/include -iquote /builds/ehabkost/qemu/disas/libvixl -iquote /builds/ehabkost/qemu/tcg/i386 -pthread -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=2 -m32 -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -Wstrict-prototypes -Wredundant-decls -Wundef -Wwrite-strings -Wmissing-prototypes -fno-strict-aliasing -fno-common -fwrapv -m32 -Wold-style-declaration -Wold-style-definition -Wtype-limits -Wformat-security -Wformat-y2k -Winit-self -Wignored-qualifiers -Wempty-body -Wnested-externs -Wendif-labels -Wexpansion-to-defined -Wimplicit-fallthrough=2 -Wno-missing-include-dirs -Wno-shift-negative-value -Wno-psabi -fstack-protector-strong -fPIC -isystem../linux-headers -isystemlinux-headers -DNEED_CPU_H '-DCONFIG_TARGET="microblazeel-softmmu-config-target.h"' '-DCONFIG_DEVICES="microblazeel-softmmu-config-devices.h"' -MD -MQ libqemu-microblazeel-softmmu.fa.p/softmmu_vl.c.o -MF libqemu-microblazeel-softmmu.fa.p/softmmu_vl.c.o.d -o libqemu-microblazeel-softmmu.fa.p/softmmu_vl.c.o -c ../softmmu/vl.c ./qemu-options.def: In function 'help':
./qemu-options.def:52:1: error: expected ')' before 'QEMU_ARCH_ALL'
52 | QEMU_ARCH_ALL)

      | ^~~~~~~~~~~~~
../softmmu/vl.c:809:10: note: in definition of macro 'DEF'
  809 |     if ((arch_mask) & arch_type)                               \
      |          ^~~~~~~~~

../softmmu/vl.c:809:9: note: to match this '('
809 | if ((arch_mask) & arch_type) \
| ^
./qemu-options.def:43:1: note: in expansion of macro 'DEF'
43 | DEF("smp", HAS_ARG, QEMU_OPTION_smp,

      | ^~~
../softmmu/vl.c:809:21: error: invalid operands to binary & (have 'const char *' and 'uint32_t' {aka 'const unsigned int'})
  809 |     if ((arch_mask) & arch_type)                               \
      |         ~           ^
      |         |
      |         const char *
./qemu-options.def:43:1: note: in expansion of macro 'DEF'
   43 | DEF("smp", HAS_ARG, QEMU_OPTION_smp,
      | ^~~
./qemu-options.def: At top level:
./qemu-options.def:49:1: error: initialization of 'unsigned int' from 'const char *' makes integer from pointer without a cast [-Werror=int-conversion]
   49 | "                dies= number of CPU dies on one socket (for PC only)\n"
      | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

../softmmu/vl.c:845:34: note: in definition of macro 'DEF'
845 | { option, opt_arg, opt_enum, arch_mask },
| ^~~~~~~~~
./qemu-options.def:49:1: note: (near initialization for 'qemu_options[7].arch_mask')
49 | " dies= number of CPU dies on one socket (for PC only)\n"

      | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

../softmmu/vl.c:845:34: note: in definition of macro 'DEF'
845 | { option, opt_arg, opt_enum, arch_mask },
| ^~~~~~~~~
./qemu-options.def:52:1: error: expected '}' before 'QEMU_ARCH_ALL'
52 | QEMU_ARCH_ALL)

      | ^~~~~~~~~~~~~

../softmmu/vl.c:845:34: note: in definition of macro 'DEF'
845 | { option, opt_arg, opt_enum, arch_mask },
| ^~~~~~~~~
../softmmu/vl.c:845:5: note: to match this '{'

  845 |     { option, opt_arg, opt_enum, arch_mask },
      |     ^
./qemu-options.def:43:1: note: in expansion of macro 'DEF'
   43 | DEF("smp", HAS_ARG, QEMU_OPTION_smp,
      | ^~~

cc1: all warnings being treated as errors
[663/5259] Compiling C object libqemu-microblazeel-softmmu.fa.p/accel_tcg_tcg-accel-ops-icount.c.o
ninja: build stopped: subcommand failed.
make: *** [Makefile:154: run-ninja] Error 1

Signature · 1 line
Eduardo