qemu-options: remove extraneous [] around arg values
There are quite a few inappropriate uses of [...] around argument values. The [] are intended to indicate optionality, but in some cases it is used to wrap a set of enum values. In other cases it is being used to show the value is entirely optional, which was common behaviour for boolean values in the past. QEMU has deprecated short-form boolean options for quite a while though, and we should thus not advertize this possibility in the docs. Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Daniel P. Berrangé committed
Jan 8, 2026 at 16:05 UTC
cbb724e0bd3fde72f0d68abceb79c6d94de08e01
1 file changed
+56
-56
qemu-options.hx
+56
-56
@@ -25,7 +25,7 @@ SRST
25
ERST
26
27
DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
28
- "-machine [type=]name[,prop[=value][,...]]\n"
28
+ "-machine [type=]name[,prop=value[,...]]\n"
29
" selects emulated machine ('-machine help' for list)\n"
30
" property accel=accel1[:accel2[:...]] selects accelerator\n"
31
" supported accelerators are kvm, xen, hvf, nitro, nvmm, whpx, mshv or tcg (default: tcg)\n"
@@ -227,7 +227,7 @@ SRST
227
ERST
228
229
DEF("accel", HAS_ARG, QEMU_OPTION_accel,
230
- "-accel [accel=]accelerator[,prop[=value][,...]]\n"
230
+ "-accel [accel=]accelerator[,prop=value[,...]]\n"
231
" select accelerator (kvm, xen, hvf, nitro, nvmm, whpx, mshv or tcg; use 'help' for a list)\n"
232
" igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)\n"
233
" kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)\n"
@@ -789,17 +789,17 @@ ERST
789
790
791
DEF("audio", HAS_ARG, QEMU_OPTION_audio,
792
- "-audio [driver=]driver[,prop[=value][,...]]\n"
792
+ "-audio [driver=]driver[,prop=value[,...]]\n"
793
" specifies default audio backend when `audiodev` is not\n"
794
" used to create a machine or sound device;"
795
" options are the same as for -audiodev\n"
796
- "-audio [driver=]driver,model=value[,prop[=value][,...]]\n"
796
+ "-audio [driver=]driver,model=value[,prop=value[,...]]\n"
797
" specifies the audio backend and device to use;\n"
798
" apart from 'model', options are the same as for -audiodev.\n"
799
" use '-audio model=help' to show possible devices.\n",
800
QEMU_ARCH_ALL)
801
SRST
802
-``-audio [driver=]driver[,model=value][,prop[=value][,...]]``
802
+``-audio [driver=]driver[,model=value][,prop=value[,...]]``
803
If the ``model`` option is specified, ``-audio`` is a shortcut
804
for configuring both the guest audio hardware and the host audio
805
backend in one go. The guest hardware model can be set with
@@ -827,7 +827,7 @@ SRST
827
ERST
828
829
DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
830
- "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
830
+ "-audiodev [driver=]driver,id=id[,prop=value[,...]]\n"
831
" specifies the audio backend to use\n"
832
" Use ``-audiodev help`` to list the available drivers\n"
833
" id= identifier of the backend\n"
@@ -840,25 +840,25 @@ DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
840
" valid values: s8, s16, s32, u8, u16, u32, f32\n"
841
" in|out.voices= number of voices to use\n"
842
" in|out.buffer-length= length of buffer in microseconds\n"
843
- "-audiodev none,id=id,[,prop[=value][,...]]\n"
843
+ "-audiodev none,id=id,[,prop=value[,...]]\n"
844
" dummy driver that discards all output\n"
845
#ifdef CONFIG_AUDIO_ALSA
846
- "-audiodev alsa,id=id[,prop[=value][,...]]\n"
846
+ "-audiodev alsa,id=id[,prop=value[,...]]\n"
847
" in|out.dev= name of the audio device to use\n"
848
" in|out.period-length= length of period in microseconds\n"
849
" in|out.try-poll= attempt to use poll mode\n"
850
" threshold= threshold (in microseconds) when playback starts\n"
851
#endif
852
#ifdef CONFIG_AUDIO_COREAUDIO
853
- "-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
853
+ "-audiodev coreaudio,id=id[,prop=value[,...]]\n"
854
" in|out.buffer-count= number of buffers\n"
855
#endif
856
#ifdef CONFIG_AUDIO_DSOUND
857
- "-audiodev dsound,id=id[,prop[=value][,...]]\n"
857
+ "-audiodev dsound,id=id[,prop=value[,...]]\n"
858
" latency= add extra latency to playback in microseconds\n"
859
#endif
860
#ifdef CONFIG_AUDIO_OSS
861
- "-audiodev oss,id=id[,prop[=value][,...]]\n"
861
+ "-audiodev oss,id=id[,prop=value[,...]]\n"
862
" in|out.dev= path of the audio device to use\n"
863
" in|out.buffer-count= number of buffers\n"
864
" in|out.try-poll= attempt to use poll mode\n"
@@ -867,35 +867,35 @@ DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
867
" dsp-policy= set timing policy (0..10), -1 to use fragment mode\n"
868
#endif
869
#ifdef CONFIG_AUDIO_PA
870
- "-audiodev pa,id=id[,prop[=value][,...]]\n"
870
+ "-audiodev pa,id=id[,prop=value[,...]]\n"
871
" server= PulseAudio server address\n"
872
" in|out.name= source/sink device name\n"
873
" in|out.latency= desired latency in microseconds\n"
874
#endif
875
#ifdef CONFIG_AUDIO_PIPEWIRE
876
- "-audiodev pipewire,id=id[,prop[=value][,...]]\n"
876
+ "-audiodev pipewire,id=id[,prop=value[,...]]\n"
877
" in|out.name= source/sink device name\n"
878
" in|out.stream-name= name of pipewire stream\n"
879
" in|out.latency= desired latency in microseconds\n"
880
#endif
881
#ifdef CONFIG_AUDIO_SDL
882
- "-audiodev sdl,id=id[,prop[=value][,...]]\n"
882
+ "-audiodev sdl,id=id[,prop=value[,...]]\n"
883
" in|out.buffer-count= number of buffers\n"
884
#endif
885
#ifdef CONFIG_AUDIO_SNDIO
886
- "-audiodev sndio,id=id[,prop[=value][,...]]\n"
886
+ "-audiodev sndio,id=id[,prop=value[,...]]\n"
887
#endif
888
#ifdef CONFIG_SPICE
889
- "-audiodev spice,id=id[,prop[=value][,...]]\n"
889
+ "-audiodev spice,id=id[,prop=value[,...]]\n"
890
#endif
891
#ifdef CONFIG_DBUS_DISPLAY
892
- "-audiodev dbus,id=id[,prop[=value][,...]]\n"
892
+ "-audiodev dbus,id=id[,prop=value[,...]]\n"
893
#endif
894
- "-audiodev wav,id=id[,prop[=value][,...]]\n"
894
+ "-audiodev wav,id=id[,prop=value[,...]]\n"
895
" path= path of wav file to record\n",
896
QEMU_ARCH_ALL)
897
SRST
898
-``-audiodev [driver=]driver,id=id[,prop[=value][,...]]``
898
+``-audiodev [driver=]driver,id=id[,prop=value[,...]]``
899
Adds a new audio backend driver identified by id.
900
901
If no audio backend is specified, QEMU will attempt to select a
@@ -959,11 +959,11 @@ SRST
959
``in|out.buffer-length=usecs``
960
Sets the size of the buffer in microseconds.
961
962
-``-audiodev none,id=id[,prop[=value][,...]]``
962
+``-audiodev none,id=id[,prop=value[,...]]``
963
Creates a dummy backend that discards all outputs. This backend has
964
no backend specific properties.
965
966
-``-audiodev alsa,id=id[,prop[=value][,...]]``
966
+``-audiodev alsa,id=id[,prop=value[,...]]``
967
Creates backend using the ALSA. This backend is only available on
968
Linux.
969
@@ -982,7 +982,7 @@ SRST
982
``threshold=threshold``
983
Threshold (in microseconds) when playback starts. Default is 0.
984
985
-``-audiodev coreaudio,id=id[,prop[=value][,...]]``
985
+``-audiodev coreaudio,id=id[,prop=value[,...]]``
986
Creates a backend using Apple's Core Audio. This backend is only
987
available on Mac OS and only supports playback.
988
@@ -991,7 +991,7 @@ SRST
991
``in|out.buffer-count=count``
992
Sets the count of the buffers.
993
994
-``-audiodev dbus,id=id[,prop[=value][,...]]``
994
+``-audiodev dbus,id=id[,prop=value[,...]]``
995
Creates a D-Bus backend. It must be associated with the display
996
(as ``-display dbus,audiodev=id``). (Since 7.0)
997
@@ -1001,7 +1001,7 @@ SRST
1001
Number of samples per read/write (default to 480, 10ms at 48kHz)
1002
(Since 10.0)
1003
1004
-``-audiodev dsound,id=id[,prop[=value][,...]]``
1004
+``-audiodev dsound,id=id[,prop=value[,...]]``
1005
Creates a backend using Microsoft's DirectSound. This backend is
1006
only available on Windows and only supports playback.
1007
@@ -1011,7 +1011,7 @@ SRST
1011
Add extra usecs microseconds latency to playback. Default is
1012
10000 (10 ms).
1013
1014
-``-audiodev oss,id=id[,prop[=value][,...]]``
1014
+``-audiodev oss,id=id[,prop=value[,...]]``
1015
Creates a backend using OSS. This backend is available on most
1016
Unix-like systems.
1017
@@ -1040,7 +1040,7 @@ SRST
1040
buffer sizes specified by ``buffer`` and ``buffer-count``. This
1041
option is ignored if you do not have OSS 4. Default is 5.
1042
1043
-``-audiodev pa,id=id[,prop[=value][,...]]``
1043
+``-audiodev pa,id=id[,prop=value[,...]]``
1044
Creates a backend using PulseAudio. This backend is available on
1045
most systems.
1046
@@ -1056,7 +1056,7 @@ SRST
1056
Desired latency in microseconds. The PulseAudio server will try
1057
to honor this value but actual latencies may be lower or higher.
1058
1059
-``-audiodev pipewire,id=id[,prop[=value][,...]]``
1059
+``-audiodev pipewire,id=id[,prop=value[,...]]``
1060
Creates a backend using PipeWire. This backend is available on
1061
most systems.
1062
@@ -1071,7 +1071,7 @@ SRST
1071
``in|out.stream-name``
1072
Specify the name of pipewire stream.
1073
1074
-``-audiodev sdl,id=id[,prop[=value][,...]]``
1074
+``-audiodev sdl,id=id[,prop=value[,...]]``
1075
Creates a backend using SDL. This backend is available on most
1076
systems, but you should use your platform's native backend if
1077
possible.
@@ -1081,7 +1081,7 @@ SRST
1081
``in|out.buffer-count=count``
1082
Sets the count of the buffers.
1083
1084
-``-audiodev sndio,id=id[,prop[=value][,...]]``
1084
+``-audiodev sndio,id=id[,prop=value[,...]]``
1085
Creates a backend using SNDIO. This backend is available on
1086
OpenBSD and most other Unix-like systems.
1087
@@ -1094,13 +1094,13 @@ SRST
1094
``in|out.latency=usecs``
1095
Sets the desired period length in microseconds.
1096
1097
-``-audiodev spice,id=id[,prop[=value][,...]]``
1097
+``-audiodev spice,id=id[,prop=value[,...]]``
1098
Creates a backend that sends audio through SPICE. This backend
1099
requires ``-spice`` and automatically selected in that case, so
1100
usually you can ignore this option. This backend has no backend
1101
specific properties.
1102
1103
-``-audiodev wav,id=id[,prop[=value][,...]]``
1103
+``-audiodev wav,id=id[,prop=value[,...]]``
1104
Creates a backend that writes audio to a WAV file.
1105
1106
Backend specific options are:
@@ -1111,21 +1111,21 @@ SRST
1111
ERST
1112
1113
DEF("device", HAS_ARG, QEMU_OPTION_device,
1114
- "-device driver[,prop[=value][,...]]\n"
1114
+ "-device driver[,prop=value[,...]]\n"
1115
" add device (based on driver)\n"
1116
" prop=value,... sets driver properties\n"
1117
" use '-device help' to print all possible drivers\n"
1118
" use '-device driver,help' to print all possible properties\n",
1119
QEMU_ARCH_ALL)
1120
SRST
1121
-``-device driver[,prop[=value][,...]]``
1121
+``-device driver[,prop=value[,...]]``
1122
Add device driver. prop=value sets driver properties. Valid
1123
properties depend on the driver. To get help on possible drivers and
1124
properties, use ``-device help`` and ``-device driver,help``.
1125
1126
Some drivers are:
1127
1128
-``-device ipmi-bmc-sim,id=id[,prop[=value][,...]]``
1128
+``-device ipmi-bmc-sim,id=id[,prop=value[,...]]``
1129
Add an IPMI BMC. This is a simulation of a hardware management
1130
interface processor that normally sits on a system. It provides a
1131
watchdog and the ability to reset and power control the system. You
@@ -2355,19 +2355,19 @@ DEF("spice", HAS_ARG, QEMU_OPTION_spice,
2355
" [,x509-dh-key-file=<file>][,addr=addr]\n"
2356
" [,ipv4=on|off][,ipv6=on|off][,unix=on|off]\n"
2357
" [,tls-ciphers=<list>]\n"
2358
- " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
2359
- " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
2358
+ " [,tls-channel=main|display|cursor|inputs|record|playback]\n"
2359
+ " [,plaintext-channel=main|display|cursor|inputs|record|playback]\n"
2360
" [,sasl=on|off][,disable-ticketing=on|off]\n"
2361
" [,password-secret=<secret-id>]\n"
2362
- " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
2363
- " [,jpeg-wan-compression=[auto|never|always]]\n"
2364
- " [,zlib-glz-wan-compression=[auto|never|always]]\n"
2365
- " [,streaming-video=[off|all|filter]][,disable-copy-paste=on|off]\n"
2366
- " [,disable-agent-file-xfer=on|off][,agent-mouse=[on|off]]\n"
2367
- " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
2362
+ " [,image-compression=auto_glz|auto_lz|quic|glz|lz|off]\n"
2363
+ " [,jpeg-wan-compression=auto|never|always]\n"
2364
+ " [,zlib-glz-wan-compression=auto|never|always]\n"
2365
+ " [,streaming-video=off|all|filter][,disable-copy-paste=on|off]\n"
2366
+ " [,disable-agent-file-xfer=on|off][,agent-mouse=on|off]\n"
2367
+ " [,playback-compression=on|off][,seamless-migration=on|off]\n"
2368
" [,video-codec=<codec>\n"
2369
" [,max-refresh-rate=rate\n"
2370
- " [,gl=[on|off]][,rendernode=<file>]\n"
2370
+ " [,gl=on|off][,rendernode=<file>]\n"
2371
" enable spice\n"
2372
" at least one of {port, tls-port} is mandatory\n",
2373
QEMU_ARCH_ALL)
@@ -2427,7 +2427,7 @@ SRST
2427
``tls-ciphers=<list>``
2428
Specify which ciphers to use.
2429
2430
- ``tls-channel=[main|display|cursor|inputs|record|playback]``; \ ``plaintext-channel=[main|display|cursor|inputs|record|playback]``
2430
+ ``tls-channel=main|display|cursor|inputs|record|playback``; \ ``plaintext-channel=main|display|cursor|inputs|record|playback``
2431
Force specific channel to be used with or without TLS
2432
encryption. The options can be specified multiple times to
2433
configure multiple channels. The special name "default" can be
@@ -2435,24 +2435,24 @@ SRST
2435
explicitly forced into one mode the spice client is allowed to
2436
pick tls/plaintext as he pleases.
2437
2438
- ``image-compression=[auto_glz|auto_lz|quic|glz|lz|off]``
2438
+ ``image-compression=auto_glz|auto_lz|quic|glz|lz|off``
2439
Configure image compression (lossless). Default is auto\_glz.
2440
2441
- ``jpeg-wan-compression=[auto|never|always]``; \ ``zlib-glz-wan-compression=[auto|never|always]``
2441
+ ``jpeg-wan-compression=auto|never|always``; \ ``zlib-glz-wan-compression=auto|never|always``
2442
Configure wan image compression (lossy for slow links). Default
2443
is auto.
2444
2445
- ``streaming-video=[off|all|filter]``
2445
+ ``streaming-video=off|all|filter``
2446
Configure video stream detection. Default is off.
2447
2448
- ``agent-mouse=[on|off]``
2448
+ ``agent-mouse=on|off``
2449
Enable/disable passing mouse events via vdagent. Default is on.
2450
2451
- ``playback-compression=[on|off]``
2451
+ ``playback-compression=on|off``
2452
Enable/disable audio stream compression (using celt 0.5.1).
2453
Default is on.
2454
2455
- ``seamless-migration=[on|off]``
2455
+ ``seamless-migration=on|off``
2456
Enable/disable spice seamless migration. Default is off.
2457
2458
``video-codec=<codec>``
@@ -2466,7 +2466,7 @@ SRST
2466
Provide the maximum refresh rate (or FPS) at which the encoding
2467
requests should be sent to the Spice server. Default would be 30.
2468
2469
- ``gl=[on|off]``
2469
+ ``gl=on|off``
2470
Enable/disable OpenGL context. Default is off.
2471
2472
``rendernode=<file>``
@@ -2696,7 +2696,7 @@ SRST
2696
bandwidth when playing videos. Disabling adaptive encodings
2697
restores the original static behavior of encodings like Tight.
2698
2699
- ``share=[allow-exclusive|force-shared|ignore]``
2699
+ ``share=allow-exclusive|force-shared|ignore``
2700
Set display sharing policy. 'allow-exclusive' allows clients to
2701
ask for exclusive access. As suggested by the rfb spec this is
2702
implemented by dropping other connections. Connecting multiple
@@ -4870,9 +4870,9 @@ SRST
4870
ERST
4871
4872
DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
4873
- "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
4873
+ "-mon [chardev=]name[,mode=readline|control][,pretty=on|off]\n", QEMU_ARCH_ALL)
4874
SRST
4875
-``-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]``
4875
+``-mon [chardev=]name[,mode=readline|control][,pretty=on|off]``
4876
Set up a monitor connected to the chardev ``name``.
4877
QEMU supports two monitors: the Human Monitor Protocol
4878
(HMP; for human interaction), and the QEMU Monitor Protocol
@@ -5561,14 +5561,14 @@ ERST
5561
#endif
5562
5563
DEF("msg", HAS_ARG, QEMU_OPTION_msg,
5564
- "-msg [timestamp[=on|off]][,guest-name=[on|off]]\n"
5564
+ "-msg [timestamp=on|off][,guest-name=on|off]\n"
5565
" control error message format\n"
5566
" timestamp=on enables timestamps (default: off)\n"
5567
" guest-name=on enables guest name prefix but only if\n"
5568
" -name guest option is set (default: off)\n",
5569
QEMU_ARCH_ALL)
5570
SRST
5571
-``-msg [timestamp[=on|off]][,guest-name[=on|off]]``
5571
+``-msg [timestamp=on|off][,guest-name=on|off]``
5572
Control error message format.
5573
5574
``timestamp=on|off``