" selects emulated machine ('-machine help' for list)\n"
" property accel=accel1[:accel2[:...]] selects accelerator\n"
" supported accelerators are kvm, xen, hax, hvf, whpx or tcg (default: tcg)\n"
- " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n"
" vmport=on|off|auto controls emulation of vmport (default: auto)\n"
- " kvm_shadow_mem=size of KVM shadow MMU in bytes\n"
" dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
" mem-merge=on|off controls memory merge support (default: on)\n"
- " igd-passthru=on|off controls IGD GFX passthrough support (default=off)\n"
" aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
" dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
" suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
more than one accelerator specified, the next one is used if the previous one
fails to initialize.
-@item kernel_irqchip=on|off
-Controls in-kernel irqchip support for the chosen accelerator when available.
-@item gfx_passthru=on|off
-Enables IGD GFX passthrough support for the chosen machine when available.
@item vmport=on|off|auto
Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
value based on accel. For accel=xen the default is off otherwise the default
is on.
-@item kvm_shadow_mem=size
-Defines the size of the KVM shadow MMU.
@item dump-guest-core=on|off
Include guest memory in a core dump. The default is on.
@item mem-merge=on|off
ETEXI
DEF("accel", HAS_ARG, QEMU_OPTION_accel,
- "-accel [accel=]accelerator[,thread=single|multi]\n"
+ "-accel [accel=]accelerator[,prop[=value][,...]]\n"
" select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n"
+ " igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)\n"
+ " kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)\n"
+ " kvm-shadow-mem=size of KVM shadow MMU in bytes\n"
+ " tb-size=n (TCG translation block cache size)\n"
" thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
STEXI
@item -accel @var{name}[,prop=@var{value}[,...]]
more than one accelerator specified, the next one is used if the previous one
fails to initialize.
@table @option
+@item igd-passthru=on|off
+When Xen is in use, this option controls whether Intel integrated graphics
+devices can be passed through to the guest (default=off)
+@item kernel-irqchip=on|off|split
+Controls KVM in-kernel irqchip support. The default is full acceleration of the
+interrupt controllers. On x86, split irqchip reduces the kernel attack
+surface, at a performance cost for non-MSI interrupts. Disabling the in-kernel
+irqchip completely is not recommended except for debugging purposes.
+@item kvm-shadow-mem=size
+Defines the size of the KVM shadow MMU.
+@item tb-size=@var{n}
+Controls the size (in MiB) of the TCG translation block cache.
@item thread=single|multi
Controls number of TCG threads. When the TCG is multi-threaded there will be one
thread per vCPU therefor taking advantage of additional host cores. The default
" specifies the audio backend to use\n"
" id= identifier of the backend\n"
" timer-period= timer period in microseconds\n"
+ " in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n"
" in|out.fixed-settings= use fixed settings for host audio\n"
" in|out.frequency= frequency to use with fixed settings\n"
" in|out.channels= number of channels to use with fixed settings\n"
" in|out.format= sample format to use with fixed settings\n"
" valid values: s8, s16, s32, u8, u16, u32\n"
" in|out.voices= number of voices to use\n"
- " in|out.buffer-len= length of buffer in microseconds\n"
+ " in|out.buffer-length= length of buffer in microseconds\n"
"-audiodev none,id=id,[,prop[=value][,...]]\n"
" dummy driver that discards all output\n"
#ifdef CONFIG_AUDIO_ALSA
"-audiodev alsa,id=id[,prop[=value][,...]]\n"
" in|out.dev= name of the audio device to use\n"
- " in|out.period-len= length of period in microseconds\n"
+ " in|out.period-length= length of period in microseconds\n"
" in|out.try-poll= attempt to use poll mode\n"
" threshold= threshold (in microseconds) when playback starts\n"
#endif
"-audiodev pa,id=id[,prop[=value][,...]]\n"
" server= PulseAudio server address\n"
" in|out.name= source/sink device name\n"
+ " in|out.latency= desired latency in microseconds\n"
#endif
#ifdef CONFIG_AUDIO_SDL
"-audiodev sdl,id=id[,prop[=value][,...]]\n"
-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
@end example
+NOTE: parameter validation is known to be incomplete, in many cases
+specifying an invalid option causes QEMU to print an error message and
+continue emulation without sound.
+
Valid global options are:
@table @option
Sets the timer @var{period} used by the audio subsystem in microseconds.
Default is 10000 (10 ms).
+@item in|out.mixing-engine=on|off
+Use QEMU's mixing engine to mix all streams inside QEMU and convert
+audio formats when not supported by the backend. When off,
+@var{fixed-settings} must be off too. Note that disabling this option
+means that the selected backend must support multiple streams and the
+audio formats used by the virtual cards, otherwise you'll get no sound.
+It's not recommended to disable this option unless you want to use 5.1
+or 7.1 audio, as mixing engine only supports mono and stereo audio.
+Default is on.
+
@item in|out.fixed-settings=on|off
Use fixed settings for host audio. When off, it will change based on
how the guest opens the sound card. In this case you must not specify
@item in|out.voices=@var{voices}
Specify the number of @var{voices} to use. Default is 1.
-@item in|out.buffer=@var{usecs}
+@item in|out.buffer-length=@var{usecs}
Sets the size of the buffer in microseconds.
@end table
Specify the ALSA @var{device} to use for input and/or output. Default
is @code{default}.
-@item in|out.period-len=@var{usecs}
+@item in|out.period-length=@var{usecs}
Sets the period length in microseconds.
@item in|out.try-poll=on|off
@item in|out.name=@var{sink}
Use the specified source/sink for recording/playback.
+@item in|out.latency=@var{usecs}
+Desired latency in microseconds. The PulseAudio server will try to honor this
+value but actual latencies may be lower or higher.
+
@end table
@item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]]
DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
"-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
" [,cache.direct=on|off][,cache.no-flush=on|off]\n"
- " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n"
+ " [,read-only=on|off][,auto-read-only=on|off]\n"
+ " [,force-share=on|off][,detect-zeroes=on|off|unmap]\n"
" [,driver specific parameters...]\n"
" configure a block backend\n", QEMU_ARCH_ALL)
STEXI
For the top level, an explicit node name must be specified.
@item read-only
Open the node read-only. Guest write attempts will fail.
+
+Note that some block drivers support only read-only access, either generally or
+in certain configurations. In this case, the default value
+@option{read-only=off} does not work and the option must be specified
+explicitly.
+@item auto-read-only
+If @option{auto-read-only=on} is set, QEMU may fall back to read-only usage
+even when @option{read-only=off} is requested, or even switch between modes as
+needed, e.g. depending on whether the image file is writable or whether a
+writing user is attached to the node.
+@item force-share
+Override the image locking system of QEMU by forcing the node to utilize
+weaker shared access for permissions where it would normally request exclusive
+access. When there is the potential for multiple instances to have the same
+file open (whether this invocation of QEMU is the first or the second
+instance), both instances must permit shared access for the second instance to
+succeed at opening the file.
+
+Enabling @option{force-share=on} requires @option{read-only=on}.
@item cache.direct
The host page cache can be avoided with @option{cache.direct=on}. This will
attempt to do disk IO directly to the guest's memory. QEMU may still perform an
DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
"-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n"
- " [,id=id][,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode]\n"
+ " [,id=id][,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n"
"-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly]\n"
"-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly]\n"
"-virtfs synth,mount_tag=tag[,id=id][,readonly]\n",
STEXI
-@item -virtfs local,path=@var{path},mount_tag=@var{mount_tag} ,security_model=@var{security_model}[,writeout=@var{writeout}][,readonly] [,fmode=@var{fmode}][,dmode=@var{dmode}]
+@item -virtfs local,path=@var{path},mount_tag=@var{mount_tag} ,security_model=@var{security_model}[,writeout=@var{writeout}][,readonly] [,fmode=@var{fmode}][,dmode=@var{dmode}][,multidevs=@var{multidevs}]
@itemx -virtfs proxy,socket=@var{socket},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly]
@itemx -virtfs proxy,sock_fd=@var{sock_fd},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly]
@itemx -virtfs synth,mount_tag=@var{mount_tag}
only with security models "mapped-xattr" and "mapped-file".
@item mount_tag=@var{mount_tag}
Specifies the tag name to be used by the guest to mount this export point.
+@item multidevs=@var{multidevs}
+Specifies how to deal with multiple devices being shared with a 9p export.
+Supported behaviours are either "remap", "forbid" or "warn". The latter is
+the default behaviour on which virtfs 9p expects only one device to be
+shared with the same export, and if more than one device is shared and
+accessed via the same 9p export then only a warning message is logged
+(once) by qemu on host side. In order to avoid file ID collisions on guest
+you should either create a separate virtfs export for each device to be
+shared with guests (recommended way) or you might use "remap" instead which
+allows you to share multiple devices with only one export instead, which is
+achieved by remapping the original inode numbers from host to guest in a
+way that would prevent such collisions. Remapping inodes in such use cases
+is required because the original device IDs from host are never passed and
+exposed on guest. Instead all files of an export shared with virtfs always
+share the same device id on guest. So two files with identical inode
+numbers but from actually different devices on host would otherwise cause a
+file ID collision and hence potential misbehaviours on guest. "forbid" on
+the other hand assumes like "warn" that only one device is shared by the
+same export, however it will not only log a warning message but also
+deny access to additional devices on guest. Note though that "forbid" does
+currently not block all possible file access operations (e.g. readdir()
+would still return entries from other devices).
@end table
ETEXI
-DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
- "-virtfs_synth Create synthetic file system image\n",
- QEMU_ARCH_ALL)
-STEXI
-@item -virtfs_synth
-@findex -virtfs_synth
-Create synthetic file system image. Note that this option is now deprecated.
-Please use @code{-fsdev synth} and @code{-device virtio-9p-...} instead.
-ETEXI
-
DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
"-iscsi [user=user][,password=password]\n"
" [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
ETEXI
DEF("display", HAS_ARG, QEMU_OPTION_display,
+#if defined(CONFIG_SPICE)
"-display spice-app[,gl=on|off]\n"
- "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
+#endif
+#if defined(CONFIG_SDL)
+ "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n"
" [,window_close=on|off][,gl=on|core|es|off]\n"
+#endif
+#if defined(CONFIG_GTK)
"-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
+#endif
+#if defined(CONFIG_VNC)
"-display vnc=<display>[,<optargs>]\n"
+#endif
+#if defined(CONFIG_CURSES)
"-display curses[,charset=<encoding>]\n"
+#endif
+#if defined(CONFIG_OPENGL)
+ "-display egl-headless[,rendernode=<file>]\n"
+#endif
"-display none\n"
- "-display egl-headless[,rendernode=<file>]"
- " select display type\n"
- "The default display is equivalent to\n"
+ " select display backend type\n"
+ " The default display is equivalent to\n "
#if defined(CONFIG_GTK)
- "\t\"-display gtk\"\n"
+ "\"-display gtk\"\n"
#elif defined(CONFIG_SDL)
- "\t\"-display sdl\"\n"
+ "\"-display sdl\"\n"
#elif defined(CONFIG_COCOA)
- "\t\"-display cocoa\"\n"
+ "\"-display cocoa\"\n"
#elif defined(CONFIG_VNC)
- "\t\"-vnc localhost:0,to=99,id=default\"\n"
+ "\"-vnc localhost:0,to=99,id=default\"\n"
#else
- "\t\"-display none\"\n"
+ "\"-display none\"\n"
#endif
, QEMU_ARCH_ALL)
STEXI
DEF("g", 1, QEMU_OPTION_g ,
"-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
- QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
+ QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K)
STEXI
@item -g @var{width}x@var{height}[x@var{depth}]
@findex -g
ETEXI
DEFHEADING()
-DEFHEADING(Bluetooth(R) options:)
-STEXI
-@table @option
-ETEXI
-
-DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
- "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
- "-bt hci,host[:id]\n" \
- " use host's HCI with the given name\n" \
- "-bt hci[,vlan=n]\n" \
- " emulate a standard HCI in virtual scatternet 'n'\n" \
- "-bt vhci[,vlan=n]\n" \
- " add host computer to virtual scatternet 'n' using VHCI\n" \
- "-bt device:dev[,vlan=n]\n" \
- " emulate a bluetooth device 'dev' in scatternet 'n'\n",
- QEMU_ARCH_ALL)
-STEXI
-@item -bt hci[...]
-@findex -bt
-Defines the function of the corresponding Bluetooth HCI. -bt options
-are matched with the HCIs present in the chosen machine type. For
-example when emulating a machine with only one HCI built into it, only
-the first @code{-bt hci[...]} option is valid and defines the HCI's
-logic. The Transport Layer is decided by the machine type. Currently
-the machines @code{n800} and @code{n810} have one HCI and all other
-machines have none.
-
-Note: This option and the whole bluetooth subsystem is considered as deprecated.
-If you still use it, please send a mail to @email{qemu-devel@@nongnu.org} where
-you describe your usecase.
-
-@anchor{bt-hcis}
-The following three types are recognized:
-
-@table @option
-@item -bt hci,null
-(default) The corresponding Bluetooth HCI assumes no internal logic
-and will not respond to any HCI commands or emit events.
-
-@item -bt hci,host[:@var{id}]
-(@code{bluez} only) The corresponding HCI passes commands / events
-to / from the physical HCI identified by the name @var{id} (default:
-@code{hci0}) on the computer running QEMU. Only available on @code{bluez}
-capable systems like Linux.
-
-@item -bt hci[,vlan=@var{n}]
-Add a virtual, standard HCI that will participate in the Bluetooth
-scatternet @var{n} (default @code{0}). Similarly to @option{-net}
-VLANs, devices inside a bluetooth network @var{n} can only communicate
-with other devices in the same network (scatternet).
-@end table
-
-@item -bt vhci[,vlan=@var{n}]
-(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
-to the host bluetooth stack instead of to the emulated target. This
-allows the host and target machines to participate in a common scatternet
-and communicate. Requires the Linux @code{vhci} driver installed. Can
-be used as following:
-
-@example
-@value{qemu_system} [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
-@end example
-
-@item -bt device:@var{dev}[,vlan=@var{n}]
-Emulate a bluetooth device @var{dev} and place it in network @var{n}
-(default @code{0}). QEMU can only emulate one type of bluetooth devices
-currently:
-
-@table @option
-@item keyboard
-Virtual wireless keyboard implementing the HIDP bluetooth profile.
-@end table
-ETEXI
-
-STEXI
-@end table
-ETEXI
-DEFHEADING()
-
#ifdef CONFIG_TPM
DEFHEADING(TPM device options:)
STEXI
@item -tb-size @var{n}
@findex -tb-size
-Set TB size.
+Set TCG translation block cache size. Deprecated, use @samp{-accel tcg,tb-size=@var{n}}
+instead.
ETEXI
DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
@findex -trace
@include qemu-option-trace.texi
ETEXI
+DEF("plugin", HAS_ARG, QEMU_OPTION_plugin,
+ "-plugin [file=]<file>[,arg=<string>]\n"
+ " load a plugin\n",
+ QEMU_ARCH_ALL)
+STEXI
+@item -plugin file=@var{file}[,arg=@var{string}]
+@findex -plugin
+
+Load a plugin.
+
+@table @option
+@item file=@var{file}
+Load the given plugin from a shared library file.
+@item arg=@var{string}
+Argument string passed to the plugin. (Can be given multiple times.)
+@end table
+ETEXI
HXCOMM Internal use
DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
DEF("msg", HAS_ARG, QEMU_OPTION_msg,
"-msg timestamp[=on|off]\n"
- " change the format of messages\n"
- " on|off controls leading timestamps (default:on)\n",
+ " control error message format\n"
+ " timestamp=on enables timestamps (default: off)\n",
QEMU_ARCH_ALL)
STEXI
@item -msg timestamp[=on|off]
@findex -msg
-prepend a timestamp to each log message.(default:on)
+Control error message format.
+@table @option
+@item timestamp=on|off
+Prefix messages with a timestamp. Default is off.
+@end table
ETEXI
DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
@end example
+@item -object iothread,id=@var{id},poll-max-ns=@var{poll-max-ns},poll-grow=@var{poll-grow},poll-shrink=@var{poll-shrink}
+
+Creates a dedicated event loop thread that devices can be assigned to. This is
+known as an IOThread. By default device emulation happens in vCPU threads or
+the main event loop thread. This can become a scalability bottleneck.
+IOThreads allow device emulation and I/O to run on other host CPUs.
+
+The @option{id} parameter is a unique ID that will be used to reference this
+IOThread from @option{-device ...,iothread=@var{id}}. Multiple devices can be
+assigned to an IOThread. Note that not all devices support an
+@option{iothread} parameter.
+
+The @code{query-iothreads} QMP command lists IOThreads and reports their thread
+IDs so that the user can configure host CPU pinning/affinity.
+
+IOThreads use an adaptive polling algorithm to reduce event loop latency.
+Instead of entering a blocking system call to monitor file descriptors and then
+pay the cost of being woken up when an event occurs, the polling algorithm
+spins waiting for events for a short time. The algorithm's default parameters
+are suitable for many cases but can be adjusted based on knowledge of the
+workload and/or host device latency.
+
+The @option{poll-max-ns} parameter is the maximum number of nanoseconds to busy
+wait for events. Polling can be disabled by setting this value to 0.
+
+The @option{poll-grow} parameter is the multiplier used to increase the polling
+time when the algorithm detects it is missing events due to not polling long
+enough.
+
+The @option{poll-shrink} parameter is the divisor used to decrease the polling
+time when the algorithm detects it is spending too long polling without
+encountering events.
+
+The polling parameters can be modified at run-time using the @code{qom-set} command (where @code{iothread1} is the IOThread's @code{id}):
+
+@example
+(qemu) qom-set /objects/iothread1 poll-max-ns 100000
+@end example
@end table
projects / mirror_qemu.git / blobdiff