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

From: "wangyanan (Y)" <wangyanan55@huawei.com>
To: "Daniel P. Berrangé" <berrange@redhat.com>, qemu-devel@nongnu.org
Cc: Igor Mammedov <imammedo@redhat.com>,
	Andrew Jones <drjones@redhat.com>,
	Richard Henderson <richard.henderson@linaro.org>,
	Eduardo Habkost <ehabkost@redhat.com>,
	Paolo Bonzini <pbonzini@redhat.com>
Subject: Re: [PATCH 4/4] qemu-options: rewrite help for -smp options
Date: Mon, 28 Jun 2021 21:46:16 +0800	[thread overview]
Message-ID: <0fe6ae73-62f2-569b-1e9d-04bd7da7458a@huawei.com> (raw)
In-Reply-To: <20210628113047.462498-5-berrange@redhat.com>

Hi Daniel,

On 2021/6/28 19:30, Daniel P. Berrangé wrote:
> 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.
>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>   qemu-options.hx | 29 +++++++++++++++++++++--------
>   1 file changed, 21 insertions(+), 8 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 5871df7291..0021e9ec7b 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -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
Should be "a SMP system".
> +    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.
> +
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.
> +    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
.