docs: improve -smp documentation
v2 cover docs: improve -smp documentation
Changed in v2:
- Fix misplaced ',' breaking build
- Two small typo fixes
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 | 41 ++++++++++++++++++++---------- 2 files changed, 28 insertions(+), 15 deletions(-)
Signature · 1 line
2.31.1
PATCH v2 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
@@ -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
Re: [PATCH v2 1/4] docs: fix typo s/Intel/AMD/ in CPU model notes
Quoted 12 lines
Reviewed-by Andrew Jones <[email protected]>Reviewed-by Yanan Wang <[email protected]>Signed-off-by Daniel P. Berrangé <[email protected]>--- docs/system/cpu-models-x86.rst.inc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)docs/system/cpu-models-x86.rst.inc +0
-0
docs/system/cpu-models-x86.rst.inc features are included if using "Host passthrough" or "Host model".
Quoted 9 lines
docs/system/cpu-models-x86.rst.inc +1
-2@@ -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 --
PATCH v2 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 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)
qemu-options.hx +6 -6
@@ -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" + " maxcpus= maximum number of total CPUs, including\n" " offline CPUs for hotplug, etc\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" + " sockets= number of discrete sockets in the system\n" " dies= number of CPU dies on one socket (for PC only)\n" - " sockets= number of discrete sockets in the system\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", 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
Re: [PATCH v2 2/4] qemu-options: re-arrange CPU topology options
Quoted 30 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
Reviewed-by Andrew Jones <[email protected]>Reviewed-by Yanan Wang <[email protected]>Signed-off-by Daniel P. Berrangé <[email protected]>--- qemu-options.hx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)qemu-options.hx +3
-5@@ -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" + " maxcpus= maximum number of total CPUs, including\n" " offline CPUs for hotplug, etc\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" + " sockets= number of discrete sockets in the system\n" " dies= number of CPU dies on one socket (for PC only)\n" - " sockets= number of discrete sockets in the system\n",
qemu-options.hx SRST
Quoted 10 lines
qemu-options.hx +3
-2+ " 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", 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 --
PATCH v2 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
@@ -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
Re: [PATCH v2 3/4] qemu-options: tweak to show that CPU count is optional
Quoted 24 lines
The initial CPU count number is not required, if any of the topology options are given, since it can be computed.
Reviewed-by Andrew Jones <[email protected]>Reviewed-by Yanan Wang <[email protected]>Signed-off-by Daniel P. Berrangé <[email protected]>--- qemu-options.hx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)qemu-options.hx +1
-1@@ -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,
Quoted 9 lines
qemu-options.hx +1
-2@@ -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 --
PATCH v2 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
@@ -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 a 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
Re: [PATCH v2 4/4] qemu-options: rewrite help for -smp options
Quoted 50 lines
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.
Reviewed-by Andrew Jones <[email protected]>Signed-off-by Daniel P. Berrangé <[email protected]>--- qemu-options.hx | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-)qemu-options.hx +15
-8@@ -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 a 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. +
qemu-options.hx DEF("smp", HAS_ARG, QEMU_OPTION_smp,
Quoted 10 lines
qemu-options.hx +6
-1+ 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, --