On 12/4/2025 12:06 AM, Peter Maydell wrote:
On Wed, 3 Dec 2025 at 14:00, Dr. David Alan Gilbert <[email protected]> wrote:
* Alex Bennée ([email protected]) wrote:
[email protected] writes:
From: "Dr. David Alan Gilbert" <[email protected]>
-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 <[email protected]>
Signed-off-by: Dr. David Alan Gilbert <[email protected]>
---
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/[email protected]/
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
