" 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
You can open an image using pre-opened file descriptors from an fd set:
@example
-qemu-system-i386
--add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
--add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
--drive file=/dev/fdset/2,index=0,media=disk
+@value{qemu_system} \
+ -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
+ -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
+ -drive file=/dev/fdset/2,index=0,media=disk
@end example
ETEXI
Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
@example
-qemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img
+@value{qemu_system_x86} -global ide-hd.physical_block_size=4096 disk-image.img
@end example
In particular, you can use this to set driver properties for devices which are
@example
# try to boot from network first, then from hard disk
-qemu-system-i386 -boot order=nc
+@value{qemu_system_x86} -boot order=nc
# boot from CD-ROM first, switch back to default order after reboot
-qemu-system-i386 -boot once=d
+@value{qemu_system_x86} -boot once=d
# boot with a splash picture for 5 seconds.
-qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
+@value{qemu_system_x86} -boot menu=on,splash=/root/boot.bmp,splash-time=5000
@end example
Note: The legacy format '-boot @var{drives}' is still supported but its
memory the guest can reach to 4GB:
@example
-qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
+@value{qemu_system} -m 1G,slots=3,maxmem=4G
@end example
If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
" 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}][,...]]
@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
@findex -soundhw
Enable audio and selected sound hardware. Use 'help' to print all
-available sound hardware.
+available sound hardware. For example:
@example
-qemu-system-i386 -soundhw sb16,adlib disk.img
-qemu-system-i386 -soundhw es1370 disk.img
-qemu-system-i386 -soundhw ac97 disk.img
-qemu-system-i386 -soundhw hda disk.img
-qemu-system-i386 -soundhw all disk.img
-qemu-system-i386 -soundhw help
+@value{qemu_system_x86} -soundhw sb16,adlib disk.img
+@value{qemu_system_x86} -soundhw es1370 disk.img
+@value{qemu_system_x86} -soundhw ac97 disk.img
+@value{qemu_system_x86} -soundhw hda disk.img
+@value{qemu_system_x86} -soundhw all disk.img
+@value{qemu_system_x86} -soundhw help
@end example
Note that Linux's i810_audio OSS kernel (for AC97) module might
@code{-device @var{driver},help}.
Some drivers are:
-@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}]
+@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}][,guid=@var{uuid}]
Add an IPMI BMC. This is a simulation of a hardware management
interface processor that normally sits on a system. It provides
it.
@table @option
-@item bmc=@var{id}
-The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
+@item id=@var{id}
+The BMC id for interfaces to use this device.
@item slave_addr=@var{val}
Define slave address to use for the BMC. The default is 0x20.
@item sdrfile=@var{file}
size of a Field Replaceable Unit (FRU) area. The default is 1024.
@item frudatafile=@var{file}
file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
+@item guid=@var{uuid}
+value for the GUID for the BMC, in standard UUID format. If this is set,
+get "Get GUID" command to the BMC will return it. Otherwise "Get GUID"
+will return an error.
@end table
@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
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
Instead of @option{-cdrom} you can use:
@example
-qemu-system-i386 -drive file=file,index=2,media=cdrom
+@value{qemu_system} -drive file=file,index=2,media=cdrom
@end example
Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
use:
@example
-qemu-system-i386 -drive file=file,index=0,media=disk
-qemu-system-i386 -drive file=file,index=1,media=disk
-qemu-system-i386 -drive file=file,index=2,media=disk
-qemu-system-i386 -drive file=file,index=3,media=disk
+@value{qemu_system} -drive file=file,index=0,media=disk
+@value{qemu_system} -drive file=file,index=1,media=disk
+@value{qemu_system} -drive file=file,index=2,media=disk
+@value{qemu_system} -drive file=file,index=3,media=disk
@end example
You can open an image using pre-opened file descriptors from an fd set:
@example
-qemu-system-i386
--add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
--add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
--drive file=/dev/fdset/2,index=0,media=disk
+@value{qemu_system} \
+ -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
+ -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
+ -drive file=/dev/fdset/2,index=0,media=disk
@end example
You can connect a CDROM to the slave of ide0:
@example
-qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
+@value{qemu_system_x86} -drive file=file,if=ide,index=1,media=cdrom
@end example
If you don't specify the "file=" argument, you define an empty drive:
@example
-qemu-system-i386 -drive if=ide,index=1,media=cdrom
+@value{qemu_system_x86} -drive if=ide,index=1,media=cdrom
@end example
Instead of @option{-fda}, @option{-fdb}, you can use:
@example
-qemu-system-i386 -drive file=file,index=0,if=floppy
-qemu-system-i386 -drive file=file,index=1,if=floppy
+@value{qemu_system_x86} -drive file=file,index=0,if=floppy
+@value{qemu_system_x86} -drive file=file,index=1,if=floppy
@end example
By default, @var{interface} is "ide" and @var{index} is automatically
incremented:
@example
-qemu-system-i386 -drive file=a -drive file=b"
+@value{qemu_system_x86} -drive file=a -drive file=b"
@end example
is interpreted like:
@example
-qemu-system-i386 -hda a -hdb b
+@value{qemu_system_x86} -hda a -hdb b
@end example
ETEXI
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
be used to shorten the command line length (note that the e1000 is the default
on i386, so the @option{model=e1000} parameter could even be omitted here, too):
@example
-qemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
-qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
+@value{qemu_system} -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
+@value{qemu_system} -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
@end example
@item -nic none
Example:
@example
-qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
+@value{qemu_system} -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
@end example
@item domainname=@var{domain}
Example (using pxelinux):
@example
-qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \
+@value{qemu_system} -hda linux.img -boot n -device e1000,netdev=n1 \
-netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
@end example
@example
# on the host
-qemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
+@value{qemu_system} -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
# this host xterm should open in the guest X11 server
xterm -display :1
@end example
@example
# on the host
-qemu-system-i386 -nic user,hostfwd=tcp::5555-:23
+@value{qemu_system} -nic user,hostfwd=tcp::5555-:23
telnet localhost 5555
@end example
@example
# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
# the guest accesses it
-qemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
+@value{qemu_system} -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
@end example
Or you can execute a command on every TCP connection established by the guest,
@example
# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
# and connect the TCP stream to its stdin/stdout
-qemu-system-i386 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
+@value{qemu_system} -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
@end example
@end table
@example
#launch a QEMU instance with the default network script
-qemu-system-i386 linux.img -nic tap
+@value{qemu_system} linux.img -nic tap
@end example
@example
#launch a QEMU instance with two NICs, each one connected
#to a TAP device
-qemu-system-i386 linux.img \
+@value{qemu_system} linux.img \
-netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
-netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
@end example
@example
#launch a QEMU instance with the default network helper to
#connect a TAP device to bridge br0
-qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \
+@value{qemu_system} linux.img -device virtio-net-pci,netdev=n1 \
-netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
@end example
@example
#launch a QEMU instance with the default network helper to
#connect a TAP device to bridge br0
-qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
+@value{qemu_system} linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
@end example
@example
#launch a QEMU instance with the default network helper to
#connect a TAP device to bridge qemubr0
-qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
+@value{qemu_system} linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
@end example
@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
Example:
@example
# launch a first QEMU instance
-qemu-system-i386 linux.img \
+@value{qemu_system} linux.img \
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,listen=:1234
# connect the network of this instance to the network of the first instance
-qemu-system-i386 linux.img \
+@value{qemu_system} linux.img \
-device e1000,netdev=n2,mac=52:54:00:12:34:57 \
-netdev socket,id=n2,connect=127.0.0.1:1234
@end example
Example:
@example
# launch one QEMU instance
-qemu-system-i386 linux.img \
+@value{qemu_system} linux.img \
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,mcast=230.0.0.1:1234
# launch another QEMU instance on same "bus"
-qemu-system-i386 linux.img \
+@value{qemu_system} linux.img \
-device e1000,netdev=n2,mac=52:54:00:12:34:57 \
-netdev socket,id=n2,mcast=230.0.0.1:1234
# launch yet another QEMU instance on same "bus"
-qemu-system-i386 linux.img \
+@value{qemu_system} linux.img \
-device e1000,netdev=n3,mac=52:54:00:12:34:58 \
-netdev socket,id=n3,mcast=230.0.0.1:1234
@end example
Example (User Mode Linux compat.):
@example
# launch QEMU instance (note mcast address selected is UML's default)
-qemu-system-i386 linux.img \
+@value{qemu_system} linux.img \
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,mcast=239.192.168.1:1102
# launch UML
Example (send packets from host's 1.2.3.4):
@example
-qemu-system-i386 linux.img \
+@value{qemu_system} linux.img \
-device e1000,netdev=n1,mac=52:54:00:12:34:56 \
-netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
@end example
# on 4.3.2.1
# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
-qemu-system-i386 linux.img -device e1000,netdev=n1 \
+@value{qemu_system} linux.img -device e1000,netdev=n1 \
-netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
@end example
# launch vde switch
vde_switch -F -sock /tmp/myswitch
# launch QEMU instance
-qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
+@value{qemu_system} linux.img -nic vde,sock=/tmp/myswitch
@end example
@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
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
-qemu-system-i386 [...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:)
stdio are reasonable use case. The latter is allowing to start QEMU from
within gdb and establish the connection via a pipe:
@example
-(gdb) target remote | exec qemu-system-i386 -gdb stdio ...
+(gdb) target remote | exec @value{qemu_system} -gdb stdio ...
@end example
ETEXI
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)
Enable FIPS 140-2 compliance mode.
ETEXI
-HXCOMM Deprecated by -machine accel=tcg property
+HXCOMM Deprecated by -accel tcg
DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
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,
Creates a random number generator backend which obtains entropy from
QEMU builtin functions. The @option{id} parameter is a unique ID that
will be used to reference this entropy backend from the @option{virtio-rng}
-device.
+device. By default, the @option{virtio-rng} device uses this RNG backend.
@item -object rng-random,id=@var{id},filename=@var{/dev/random}
@example
- # qemu-system-x86_64 \
+ # @value{qemu_system} \
[...] \
-object cryptodev-backend-builtin,id=cryptodev0 \
-device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
@example
- # qemu-system-x86_64 \
+ # @value{qemu_system} \
[...] \
-chardev socket,id=chardev0,path=/path/to/socket \
-object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
@example
- # $QEMU -object secret,id=sec0,data=letmein,format=raw
+ # @value{qemu_system} -object secret,id=sec0,data=letmein,format=raw
@end example
The simplest secure usage is to provide the secret via a file
# printf "letmein" > mypasswd.txt
- # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw
+ # @value{qemu_system} -object secret,id=sec0,file=mypasswd.txt,format=raw
For greater security, AES-256-CBC should be used. To illustrate usage,
consider the openssl command line tool which can encrypt the data. Note
contents of @code{iv.b64} to the second secret
@example
- # $QEMU \
+ # @value{qemu_system} \
-object secret,id=secmaster0,format=base64,file=key.b64 \
-object secret,id=sec0,keyid=secmaster0,format=base64,\
data=$SECRET,iv=$(<iv.b64)
e.g to launch a SEV guest
@example
- # $QEMU \
+ # @value{qemu_system_x86} \
......
-object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
-machine ...,memory-encryption=sev0
An example authorization object to validate a x509 distinguished name
would look like:
@example
- # $QEMU \
+ # @value{qemu_system} \
...
-object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
...
An example authorization object to validate a SASL username
would look like:
@example
- # $QEMU \
+ # @value{qemu_system} \
...
-object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes
...
name would look like:
@example
- # $QEMU \
+ # @value{qemu_system} \
...
-object authz-pam,id=auth0,service=qemu-vnc
...
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