[PATCH] qemu-options.hx: Document -M as -machine alias

[PATCH] qemu-options.hx: Document -M as -machine alias

[dave]

From: "Dr. David Alan Gilbert" <dave@treblig.org>

-M is used heavily in documentation and scripts, but isn't actually
documented anywhere.
Document it as equivalent to -machine.

Reported-by: Julian Andres Klode <jak@jak-linux.org>
Signed-off-by: Dr. David Alan Gilbert <dave@treblig.org>
---
 qemu-options.hx | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index fca2b7bc74..ec92723f10 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -44,6 +44,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
 #endif
     "                memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n"
     "                cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n"
+    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n"
     "                smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel\n",
     QEMU_ARCH_ALL)
 SRST
@@ -179,6 +180,9 @@ SRST
 
             -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
 
+    ``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
+        Define an SGX EPC section.
+
     ``smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel``
         Define cache properties for SMP system.
 
@@ -208,12 +212,10 @@ SRST
 ERST
 
 DEF("M", HAS_ARG, QEMU_OPTION_M,
-    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n",
-    QEMU_ARCH_ALL)
-
+    "-M              as -machine\n", QEMU_ARCH_ALL)
 SRST
-``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
-    Define an SGX EPC section.
+``-M``
+    as -machine.
 ERST
 
 DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
-- 
2.52.0

Re: [PATCH] qemu-options.hx: Document -M as -machine alias

[Alex Bennée]

dave@treblig.org writes:

> From: "Dr. David Alan Gilbert" <dave@treblig.org>
>
> -M is used heavily in documentation and scripts, but isn't actually
> documented anywhere.
> Document it as equivalent to -machine.
>
> Reported-by: Julian Andres Klode <jak@jak-linux.org>
> Signed-off-by: Dr. David Alan Gilbert <dave@treblig.org>
> ---
>  qemu-options.hx | 12 +++++++-----
>  1 file changed, 7 insertions(+), 5 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index fca2b7bc74..ec92723f10 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -44,6 +44,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
>  #endif
>      "                memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n"
>      "                cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n"
> +    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n"
>      "                smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel\n",
>      QEMU_ARCH_ALL)
>  SRST
> @@ -179,6 +180,9 @@ SRST
>  
>              -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
>  
> +    ``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> +        Define an SGX EPC section.
> +

This seems unrelated.

>      ``smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel``
>          Define cache properties for SMP system.
>  
> @@ -208,12 +212,10 @@ SRST
>  ERST
>  
>  DEF("M", HAS_ARG, QEMU_OPTION_M,
> -    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n",
> -    QEMU_ARCH_ALL)
> -
> +    "-M              as -machine\n", QEMU_ARCH_ALL)
>  SRST
> -``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> -    Define an SGX EPC section.
> +``-M``
> +    as -machine.

Did we have a merge conflict at some point that messed things up?

>  ERST
>  
>  DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [PATCH] qemu-options.hx: Document -M as -machine alias

[Dr. David Alan Gilbert]

* Alex Bennée (alex.bennee@linaro.org) wrote:
> dave@treblig.org writes:
> 
> > From: "Dr. David Alan Gilbert" <dave@treblig.org>
> >
> > -M is used heavily in documentation and scripts, but isn't actually
> > documented anywhere.
> > Document it as equivalent to -machine.
> >
> > Reported-by: Julian Andres Klode <jak@jak-linux.org>
> > Signed-off-by: Dr. David Alan Gilbert <dave@treblig.org>
> > ---
> >  qemu-options.hx | 12 +++++++-----
> >  1 file changed, 7 insertions(+), 5 deletions(-)
> >
> > diff --git a/qemu-options.hx b/qemu-options.hx
> > index fca2b7bc74..ec92723f10 100644
> > --- a/qemu-options.hx
> > +++ b/qemu-options.hx
> > @@ -44,6 +44,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
> >  #endif
> >      "                memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n"
> >      "                cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n"
> > +    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n"
> >      "                smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel\n",
> >      QEMU_ARCH_ALL)
> >  SRST
> > @@ -179,6 +180,9 @@ SRST
> >  
> >              -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
> >  
> > +    ``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> > +        Define an SGX EPC section.
> > +
> 
> This seems unrelated.
> 
> >      ``smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel``
> >          Define cache properties for SMP system.
> >  
> > @@ -208,12 +212,10 @@ SRST
> >  ERST
> >  
> >  DEF("M", HAS_ARG, QEMU_OPTION_M,
> > -    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n",
> > -    QEMU_ARCH_ALL)
> > -
> > +    "-M              as -machine\n", QEMU_ARCH_ALL)
> >  SRST
> > -``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> > -    Define an SGX EPC section.
> > +``-M``
> > +    as -machine.
> 
> Did we have a merge conflict at some point that messed things up?

It's not clear - it was the only option hanging around in -M and it was
already appearing wrong in the man output.
I wondered if it was some requirement to have *something* in the -M
definition so thought it best to move it at the same time.

Dave

> >  ERST
> >  
> >  DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
> 
> -- 
> Alex Bennée
> Virtualisation Tech Lead @ Linaro
-- 
 -----Open up your eyes, open up your mind, open up your code -------   
/ Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
\        dave @ treblig.org |                               | In Hex /
 \ _________________________|_____ http://www.treblig.org   |_______/

Re: [PATCH] qemu-options.hx: Document -M as -machine alias

[Peter Maydell]

On Wed, 3 Dec 2025 at 14:00, Dr. David Alan Gilbert <dave@treblig.org> wrote:
>
> * Alex Bennée (alex.bennee@linaro.org) wrote:
> > dave@treblig.org writes:
> >
> > > From: "Dr. David Alan Gilbert" <dave@treblig.org>
> > >
> > > -M is used heavily in documentation and scripts, but isn't actually
> > > documented anywhere.
> > > Document it as equivalent to -machine.
> > >
> > > Reported-by: Julian Andres Klode <jak@jak-linux.org>
> > > Signed-off-by: Dr. David Alan Gilbert <dave@treblig.org>
> > > ---
> > >  qemu-options.hx | 12 +++++++-----
> > >  1 file changed, 7 insertions(+), 5 deletions(-)
> > >
> > > diff --git a/qemu-options.hx b/qemu-options.hx
> > > index fca2b7bc74..ec92723f10 100644
> > > --- a/qemu-options.hx
> > > +++ b/qemu-options.hx
> > > @@ -44,6 +44,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
> > >  #endif
> > >      "                memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n"
> > >      "                cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n"
> > > +    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n"
> > >      "                smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel\n",
> > >      QEMU_ARCH_ALL)
> > >  SRST
> > > @@ -179,6 +180,9 @@ SRST
> > >
> > >              -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
> > >
> > > +    ``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> > > +        Define an SGX EPC section.
> > > +
> >
> > This seems unrelated.
> >
> > >      ``smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel``
> > >          Define cache properties for SMP system.
> > >
> > > @@ -208,12 +212,10 @@ SRST
> > >  ERST
> > >
> > >  DEF("M", HAS_ARG, QEMU_OPTION_M,
> > > -    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n",
> > > -    QEMU_ARCH_ALL)
> > > -
> > > +    "-M              as -machine\n", QEMU_ARCH_ALL)
> > >  SRST
> > > -``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> > > -    Define an SGX EPC section.
> > > +``-M``
> > > +    as -machine.

Surprisingly, this and -h/--help are our only two options where
we provide a short synonym. I note that this handling of -M
is not consistent with how we document -h/--help, where we
print both on a single line:
-h or -help     display this help and exit

But it would be trickier to fit that in for -machine and
perhaps confusing given the suboptions.

> > Did we have a merge conflict at some point that messed things up?
>
> It's not clear - it was the only option hanging around in -M and it was
> already appearing wrong in the man output.
> I wondered if it was some requirement to have *something* in the -M
> definition so thought it best to move it at the same time.

It looks like this was incorrectly added under -M by
commit dfce81f1b9 ("vl: Add sgx compound properties to expose
SGX EPC sections to guest"), which should have put it under
-machine like all our other machine suboption documentation.

The result is that the sgx-epc documentation appears OK
in --help because the --help output just concatenates
everything so it gets tacked on after the -machine help,
but it is misrendered in the HTML docs:
https://qemu-project.gitlab.io/qemu/system/invocation.html
as it appears as if a top level option rather than one
indented to indicate that it's a machine sub-option.
So this change fixes that bug (and should ideally say so
in its commit message).

Before that it simply read
-HXCOMM Deprecated by -machine
-DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)

(Commit dfce81f1b9 also silently dropped that "deprecated"
comment, which it shouldn't really have done.)

thanks
-- PMM

Re: [PATCH] qemu-options.hx: Document -M as -machine alias

[Dr. David Alan Gilbert]

* Peter Maydell (peter.maydell@linaro.org) wrote:
> On Wed, 3 Dec 2025 at 14:00, Dr. David Alan Gilbert <dave@treblig.org> wrote:
> >
> > * Alex Bennée (alex.bennee@linaro.org) wrote:
> > > dave@treblig.org writes:
> > >
> > > > From: "Dr. David Alan Gilbert" <dave@treblig.org>
> > > >
> > > > -M is used heavily in documentation and scripts, but isn't actually
> > > > documented anywhere.
> > > > Document it as equivalent to -machine.
> > > >
> > > > Reported-by: Julian Andres Klode <jak@jak-linux.org>
> > > > Signed-off-by: Dr. David Alan Gilbert <dave@treblig.org>
> > > > ---
> > > >  qemu-options.hx | 12 +++++++-----
> > > >  1 file changed, 7 insertions(+), 5 deletions(-)
> > > >
> > > > diff --git a/qemu-options.hx b/qemu-options.hx
> > > > index fca2b7bc74..ec92723f10 100644
> > > > --- a/qemu-options.hx
> > > > +++ b/qemu-options.hx
> > > > @@ -44,6 +44,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
> > > >  #endif
> > > >      "                memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n"
> > > >      "                cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n"
> > > > +    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n"
> > > >      "                smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel\n",
> > > >      QEMU_ARCH_ALL)
> > > >  SRST
> > > > @@ -179,6 +180,9 @@ SRST
> > > >
> > > >              -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
> > > >
> > > > +    ``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> > > > +        Define an SGX EPC section.
> > > > +
> > >
> > > This seems unrelated.
> > >
> > > >      ``smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel``
> > > >          Define cache properties for SMP system.
> > > >
> > > > @@ -208,12 +212,10 @@ SRST
> > > >  ERST
> > > >
> > > >  DEF("M", HAS_ARG, QEMU_OPTION_M,
> > > > -    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n",
> > > > -    QEMU_ARCH_ALL)
> > > > -
> > > > +    "-M              as -machine\n", QEMU_ARCH_ALL)
> > > >  SRST
> > > > -``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> > > > -    Define an SGX EPC section.
> > > > +``-M``
> > > > +    as -machine.
> 
> Surprisingly, this and -h/--help are our only two options where
> we provide a short synonym. I note that this handling of -M
> is not consistent with how we document -h/--help, where we
> print both on a single line:
> -h or -help     display this help and exit
> 
> But it would be trickier to fit that in for -machine and
> perhaps confusing given the suboptions.

Right, that's one of the two reasons I kept it separate.
The other reason, is that I couldn't figure out how '-help' and '-h'
both got defined - why is the second DEF(...) not needed?

> > > Did we have a merge conflict at some point that messed things up?
> >
> > It's not clear - it was the only option hanging around in -M and it was
> > already appearing wrong in the man output.
> > I wondered if it was some requirement to have *something* in the -M
> > definition so thought it best to move it at the same time.
> 
> It looks like this was incorrectly added under -M by
> commit dfce81f1b9 ("vl: Add sgx compound properties to expose
> SGX EPC sections to guest"), which should have put it under
> -machine like all our other machine suboption documentation.
> 
> The result is that the sgx-epc documentation appears OK
> in --help because the --help output just concatenates
> everything so it gets tacked on after the -machine help,
> but it is misrendered in the HTML docs:
> https://qemu-project.gitlab.io/qemu/system/invocation.html
> as it appears as if a top level option rather than one
> indented to indicate that it's a machine sub-option.
> So this change fixes that bug (and should ideally say so
> in its commit message).
> 
> Before that it simply read
> -HXCOMM Deprecated by -machine
> -DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
> 
> (Commit dfce81f1b9 also silently dropped that "deprecated"
> comment, which it shouldn't really have done.)

Ah.

Dave

> thanks
> -- PMM
-- 
 -----Open up your eyes, open up your mind, open up your code -------   
/ Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
\        dave @ treblig.org |                               | In Hex /
 \ _________________________|_____ http://www.treblig.org   |_______/

Re: [PATCH] qemu-options.hx: Document -M as -machine alias

[Peter Maydell]

On Wed, 3 Dec 2025 at 16:20, Dr. David Alan Gilbert <dave@treblig.org> wrote:
>
> * Peter Maydell (peter.maydell@linaro.org) wrote:
> > Surprisingly, this and -h/--help are our only two options where
> > we provide a short synonym. I note that this handling of -M
> > is not consistent with how we document -h/--help, where we
> > print both on a single line:
> > -h or -help     display this help and exit
> >
> > But it would be trickier to fit that in for -machine and
> > perhaps confusing given the suboptions.
>
> Right, that's one of the two reasons I kept it separate.
> The other reason, is that I couldn't figure out how '-help' and '-h'
> both got defined - why is the second DEF(...) not needed?

A piece of delicious fudge lurking in system/vl.c: we have
this hardcoded entry in the qemu_options[] array before
the ones that are generated via the macro-magic from
qemu-options.hx:

    { "h", 0, QEMU_OPTION_h, QEMU_ARCH_ALL },

So we recognize -h on the command line and turn it into
QEMU_OPTION_h, the same as -help, but it doesn't result in
anything in the documentation (we leave that up to the
strings and RST in the DEF("help"...) section).

thanks
-- PMM

Re: [PATCH] qemu-options.hx: Document -M as -machine alias

[Dr. David Alan Gilbert]

* Peter Maydell (peter.maydell@linaro.org) wrote:
> On Wed, 3 Dec 2025 at 16:20, Dr. David Alan Gilbert <dave@treblig.org> wrote:
> >
> > * Peter Maydell (peter.maydell@linaro.org) wrote:
> > > Surprisingly, this and -h/--help are our only two options where
> > > we provide a short synonym. I note that this handling of -M
> > > is not consistent with how we document -h/--help, where we
> > > print both on a single line:
> > > -h or -help     display this help and exit
> > >
> > > But it would be trickier to fit that in for -machine and
> > > perhaps confusing given the suboptions.
> >
> > Right, that's one of the two reasons I kept it separate.
> > The other reason, is that I couldn't figure out how '-help' and '-h'
> > both got defined - why is the second DEF(...) not needed?
> 
> A piece of delicious fudge lurking in system/vl.c: we have
> this hardcoded entry in the qemu_options[] array before
> the ones that are generated via the macro-magic from
> qemu-options.hx:
> 
>     { "h", 0, QEMU_OPTION_h, QEMU_ARCH_ALL },
> 
> So we recognize -h on the command line and turn it into
> QEMU_OPTION_h, the same as -help, but it doesn't result in
> anything in the documentation (we leave that up to the
> strings and RST in the DEF("help"...) section).

Hah ok!  I guess that fudge could be removed and make it the
same way -M works.

Dave

> thanks
> -- PMM
-- 
 -----Open up your eyes, open up your mind, open up your code -------   
/ Dr. David Alan Gilbert    |       Running GNU/Linux       | Happy  \ 
\        dave @ treblig.org |                               | In Hex /
 \ _________________________|_____ http://www.treblig.org   |_______/

Re: [PATCH] qemu-options.hx: Document -M as -machine alias

[Peter Maydell]

On Wed, 3 Dec 2025 at 16:37, Dr. David Alan Gilbert <dave@treblig.org> wrote:
>
> * Peter Maydell (peter.maydell@linaro.org) wrote:
> > On Wed, 3 Dec 2025 at 16:20, Dr. David Alan Gilbert <dave@treblig.org> wrote:
> > >
> > > * Peter Maydell (peter.maydell@linaro.org) wrote:
> > > > Surprisingly, this and -h/--help are our only two options where
> > > > we provide a short synonym. I note that this handling of -M
> > > > is not consistent with how we document -h/--help, where we
> > > > print both on a single line:
> > > > -h or -help     display this help and exit
> > > >
> > > > But it would be trickier to fit that in for -machine and
> > > > perhaps confusing given the suboptions.
> > >
> > > Right, that's one of the two reasons I kept it separate.
> > > The other reason, is that I couldn't figure out how '-help' and '-h'
> > > both got defined - why is the second DEF(...) not needed?
> >
> > A piece of delicious fudge lurking in system/vl.c: we have
> > this hardcoded entry in the qemu_options[] array before
> > the ones that are generated via the macro-magic from
> > qemu-options.hx:
> >
> >     { "h", 0, QEMU_OPTION_h, QEMU_ARCH_ALL },
> >
> > So we recognize -h on the command line and turn it into
> > QEMU_OPTION_h, the same as -help, but it doesn't result in
> > anything in the documentation (we leave that up to the
> > strings and RST in the DEF("help"...) section).
>
> Hah ok!  I guess that fudge could be removed and make it the
> same way -M works.

Yeah, I was pondering that. Also, we don't document --help in
the HTML docs, only -h.

-- PMM

Re: [PATCH] qemu-options.hx: Document -M as -machine alias

[Xiaoyao Li]

On 12/4/2025 12:06 AM, Peter Maydell wrote:
> On Wed, 3 Dec 2025 at 14:00, Dr. David Alan Gilbert <dave@treblig.org> wrote:
>>
>> * Alex Bennée (alex.bennee@linaro.org) wrote:
>>> dave@treblig.org writes:
>>>
>>>> From: "Dr. David Alan Gilbert" <dave@treblig.org>
>>>>
>>>> -M is used heavily in documentation and scripts, but isn't actually
>>>> documented anywhere.
>>>> Document it as equivalent to -machine.
>>>>
>>>> Reported-by: Julian Andres Klode <jak@jak-linux.org>
>>>> Signed-off-by: Dr. David Alan Gilbert <dave@treblig.org>
>>>> ---
>>>>   qemu-options.hx | 12 +++++++-----
>>>>   1 file changed, 7 insertions(+), 5 deletions(-)
>>>>
>>>> diff --git a/qemu-options.hx b/qemu-options.hx
>>>> index fca2b7bc74..ec92723f10 100644
>>>> --- a/qemu-options.hx
>>>> +++ b/qemu-options.hx
>>>> @@ -44,6 +44,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
>>>>   #endif
>>>>       "                memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n"
>>>>       "                cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n"
>>>> +    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n"
>>>>       "                smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel\n",
>>>>       QEMU_ARCH_ALL)
>>>>   SRST
>>>> @@ -179,6 +180,9 @@ SRST
>>>>
>>>>               -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
>>>>
>>>> +    ``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
>>>> +        Define an SGX EPC section.
>>>> +
>>>
>>> This seems unrelated.
>>>
>>>>       ``smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel``
>>>>           Define cache properties for SMP system.
>>>>
>>>> @@ -208,12 +212,10 @@ SRST
>>>>   ERST
>>>>
>>>>   DEF("M", HAS_ARG, QEMU_OPTION_M,
>>>> -    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n",
>>>> -    QEMU_ARCH_ALL)
>>>> -
>>>> +    "-M              as -machine\n", QEMU_ARCH_ALL)
>>>>   SRST
>>>> -``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
>>>> -    Define an SGX EPC section.
>>>> +``-M``
>>>> +    as -machine.
> 
> Surprisingly, this and -h/--help are our only two options where
> we provide a short synonym. I note that this handling of -M
> is not consistent with how we document -h/--help, where we
> print both on a single line:
> -h or -help     display this help and exit
> 
> But it would be trickier to fit that in for -machine and
> perhaps confusing given the suboptions.
> 
>>> Did we have a merge conflict at some point that messed things up?
>>
>> It's not clear - it was the only option hanging around in -M and it was
>> already appearing wrong in the man output.
>> I wondered if it was some requirement to have *something* in the -M
>> definition so thought it best to move it at the same time.
> 
> It looks like this was incorrectly added under -M by
> commit dfce81f1b9 ("vl: Add sgx compound properties to expose
> SGX EPC sections to guest"), which should have put it under
> -machine like all our other machine suboption documentation.
> 
> The result is that the sgx-epc documentation appears OK
> in --help because the --help output just concatenates
> everything so it gets tacked on after the -machine help,
> but it is misrendered in the HTML docs:
> https://qemu-project.gitlab.io/qemu/system/invocation.html
> as it appears as if a top level option rather than one
> indented to indicate that it's a machine sub-option.
> So this change fixes that bug (and should ideally say so
> in its commit message).

Yeah, I found this bug before and sent the fix: 
https://lore.kernel.org/qemu-devel/20250714091953.448226-2-xiaoyao.li@intel.com/

But I was occupied with other stuff then so that had no time to sent out 
the v2.

> Before that it simply read
> -HXCOMM Deprecated by -machine
> -DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
> 
> (Commit dfce81f1b9 also silently dropped that "deprecated"
> comment, which it shouldn't really have done.)
> 
> thanks
> -- PMM
> 

Re: [PATCH] qemu-options.hx: Document -M as -machine alias

[Paolo Bonzini]

Queued, thanks.

Paolo

Re: [PATCH] qemu-options.hx: Document -M as -machine alias

[Thomas Huth]

On 03/12/2025 14.15, dave@treblig.org wrote:
> From: "Dr. David Alan Gilbert" <dave@treblig.org>
> 
> -M is used heavily in documentation and scripts, but isn't actually
> documented anywhere.
> Document it as equivalent to -machine.
> 
> Reported-by: Julian Andres Klode <jak@jak-linux.org>
> Signed-off-by: Dr. David Alan Gilbert <dave@treblig.org>
> ---
>   qemu-options.hx | 12 +++++++-----
>   1 file changed, 7 insertions(+), 5 deletions(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index fca2b7bc74..ec92723f10 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -44,6 +44,7 @@ DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
>   #endif
>       "                memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n"
>       "                cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n"
> +    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n"
>       "                smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel\n",
>       QEMU_ARCH_ALL)
>   SRST
> @@ -179,6 +180,9 @@ SRST
>   
>               -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
>   
> +    ``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> +        Define an SGX EPC section.
> +
>       ``smp-cache.0.cache=cachename,smp-cache.0.topology=topologylevel``
>           Define cache properties for SMP system.
>   
> @@ -208,12 +212,10 @@ SRST
>   ERST
>   
>   DEF("M", HAS_ARG, QEMU_OPTION_M,
> -    "                sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n",
> -    QEMU_ARCH_ALL)
> -
> +    "-M              as -machine\n", QEMU_ARCH_ALL)
>   SRST
> -``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
> -    Define an SGX EPC section.
> +``-M``
> +    as -machine.
>   ERST
>   
>   DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,

Reviewed-by: Thomas Huth <thuth@redhat.com>