[Qemu-devel] what is the syntax and meaning of -numa cpus=foo-bar ?

[Qemu-devel] what is the syntax and meaning of -numa cpus=foo-bar ?

[Peter Maydell]

Hi; something we noticed recently is that some versions of
makeinfo gripe about the -numa option syntax in qemu-options.hx:

qemu-options.texi:60: warning: unlikely character [ in @var.
qemu-options.texi:60: warning: unlikely character ] in @var.
qemu-options.texi:61: warning: unlikely character [ in @var.
qemu-options.texi:61: warning: unlikely character ] in @var.

This is provoked by qemu-options.hx having:

@item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
@itemx -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]

The obvious simple syntax fix is to change it to
"cpus=@var{cpu}[-@var{cpu}]" (ie the @var{} covers only
the metasyntactic variables the user has to fill in,
not the '-' which is I think a literal and the [] which
are indicating that the second part is optional).

However, this leaves me still rather in the dark as a user of
the documentation about what the option actually does. The
text below doesn't explain what the two 'cpu' fields I
can fill in do, or what values they can take. They should
probably be different names as well (eg "start-end", or
whatever makes sense for the semantics) so that the text
can refer to them usefully.

Would somebody who understands the -numa option like to
propose a few lines of text to clarify things?

thanks
-- PMM

Re: [Qemu-devel] what is the syntax and meaning of -numa cpus=foo-bar ?

[Eduardo Habkost]

On Mon, Jan 23, 2017 at 03:14:28PM +0000, Peter Maydell wrote:
> Hi; something we noticed recently is that some versions of
> makeinfo gripe about the -numa option syntax in qemu-options.hx:
> 
> qemu-options.texi:60: warning: unlikely character [ in @var.
> qemu-options.texi:60: warning: unlikely character ] in @var.
> qemu-options.texi:61: warning: unlikely character [ in @var.
> qemu-options.texi:61: warning: unlikely character ] in @var.
> 
> This is provoked by qemu-options.hx having:
> 
> @item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
> @itemx -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
> 
> The obvious simple syntax fix is to change it to
> "cpus=@var{cpu}[-@var{cpu}]" (ie the @var{} covers only
> the metasyntactic variables the user has to fill in,
> not the '-' which is I think a literal and the [] which
> are indicating that the second part is optional).

Makes sense to me.

> 
> However, this leaves me still rather in the dark as a user of
> the documentation about what the option actually does. The
> text below doesn't explain what the two 'cpu' fields I
> can fill in do, or what values they can take. They should
> probably be different names as well (eg "start-end", or
> whatever makes sense for the semantics) so that the text
> can refer to them usefully.
> 

Yes, "start-end" would make it clearer. The "cpus" option can
also appear multiple times if the list of CPUs is a
non-contiguous range.

> Would somebody who understands the -numa option like to
> propose a few lines of text to clarify things?

I will take a look and propose a patch. Thanks for the report!

-- 
Eduardo