"-machine [type=]name[,prop[=value][,...]]\n"
" selects emulated machine ('-machine help' for list)\n"
" property accel=accel1[:accel2[:...]] selects accelerator\n"
- " supported accelerators are kvm, xen, hax, hvf, nvmm, whpx or tcg (default: tcg)\n"
+ " supported accelerators are kvm, xen, hvf, nvmm, whpx or tcg (default: tcg)\n"
" vmport=on|off|auto controls emulation of vmport (default: auto)\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"
``accel=accels1[:accels2[:...]]``
This is used to enable an accelerator. Depending on the target
- architecture, kvm, xen, hax, hvf, nvmm, whpx or tcg can be available.
+ architecture, kvm, xen, hvf, nvmm, 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.
DEF("accel", HAS_ARG, QEMU_OPTION_accel,
"-accel [accel=]accelerator[,prop[=value][,...]]\n"
- " select accelerator (kvm, xen, hax, hvf, nvmm, whpx or tcg; use 'help' for a list)\n"
+ " select accelerator (kvm, xen, hvf, nvmm, 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"
+ " one-insn-per-tb=on|off (one guest instruction per TCG translation block)\n"
" split-wx=on|off (enable TCG split w^x mapping)\n"
" tb-size=n (TCG translation block cache size)\n"
" dirty-ring-size=n (KVM dirty ring GFN count, default 0)\n"
SRST
``-accel name[,prop=value[,...]]``
This is used to enable an accelerator. Depending on the target
- architecture, kvm, xen, hax, hvf, nvmm, whpx or tcg can be available. By
+ architecture, kvm, xen, hvf, nvmm, 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.
``kvm-shadow-mem=size``
Defines the size of the KVM shadow MMU.
+ ``one-insn-per-tb=on|off``
+ Makes the TCG accelerator put only one guest instruction into
+ each translation block. This slows down emulation a lot, but
+ can be useful in some situations, such as when trying to analyse
+ the logs produced by the ``-d`` option.
+
``split-wx=on|off``
Controls the use of split w^x mapping for the TCG code generation
buffer. Some operating systems require this to be enabled, and in
-numa node,nodeid=0 -numa node,nodeid=1 \
-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
- Legacy '\ ``mem``\ ' assigns a given RAM amount to a node (not supported
- for 5.1 and newer machine types). '\ ``memdev``\ ' assigns RAM from
- a given memory backend device to a node. If '\ ``mem``\ ' and
- '\ ``memdev``\ ' are omitted in all nodes, RAM is split equally between them.
+ '\ ``memdev``\ ' option assigns RAM from a given memory backend
+ device to a node. It is recommended to use '\ ``memdev``\ ' option
+ over legacy '\ ``mem``\ ' option. This is because '\ ``memdev``\ '
+ option provides better performance and more control over the
+ backend's RAM (e.g. '\ ``prealloc``\ ' parameter of
+ '\ ``-memory-backend-ram``\ ' allows memory preallocation).
+ For compatibility reasons, legacy '\ ``mem``\ ' option is
+ supported in 5.0 and older machine types. Note that '\ ``mem``\ '
+ and '\ ``memdev``\ ' are mutually exclusive. If one node uses
+ '\ ``memdev``\ ', the rest nodes have to use '\ ``memdev``\ '
+ option, and vice versa.
- '\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive.
- Furthermore, if one node uses '\ ``memdev``\ ', all of them have to
- use it.
+ Users must specify memory for all NUMA nodes by '\ ``memdev``\ '
+ (or legacy '\ ``mem``\ ' if available). In QEMU 5.2, the support
+ for '\ ``-numa node``\ ' without memory specified was removed.
'\ ``initiator``\ ' is an additional option that points to an
initiator NUMA node that has best performance (the lowest latency or
" size: initial amount of guest memory\n"
" slots: number of hotplug slots (default: none)\n"
" maxmem: maximum amount of guest memory (default: none)\n"
- "NOTE: Some architectures might enforce a specific granularity\n",
+ " Note: Some architectures might enforce a specific granularity\n",
QEMU_ARCH_ALL)
SRST
``-m [size=]megs[,slots=n,maxmem=size]``
" in|out.name= source/sink device name\n"
" in|out.latency= desired latency in microseconds\n"
#endif
+#ifdef CONFIG_AUDIO_PIPEWIRE
+ "-audiodev pipewire,id=id[,prop[=value][,...]]\n"
+ " in|out.name= source/sink device name\n"
+ " in|out.stream-name= name of pipewire stream\n"
+ " in|out.latency= desired latency in microseconds\n"
+#endif
#ifdef CONFIG_AUDIO_SDL
"-audiodev sdl,id=id[,prop[=value][,...]]\n"
" in|out.buffer-count= number of buffers\n"
Desired latency in microseconds. The PulseAudio server will try
to honor this value but actual latencies may be lower or higher.
+``-audiodev pipewire,id=id[,prop[=value][,...]]``
+ Creates a backend using PipeWire. This backend is available on
+ most systems.
+
+ PipeWire specific options are:
+
+ ``in|out.latency=usecs``
+ Desired latency in microseconds.
+
+ ``in|out.name=sink``
+ Use the specified source/sink for recording/playback.
+
+ ``in|out.stream-name``
+ Specify the name of pipewire stream.
+
``-audiodev sdl,id=id[,prop[=value][,...]]``
Creates a backend using SDL. This backend is available on most
systems, but you should use your platform's native backend if
of the block layer have grown. Many online guides to QEMU often
reference older and deprecated options, which can lead to confusion.
-The recommended modern way to describe disks is to use a combination of
+The most explicit way to describe disks is to use a combination of
``-device`` to specify the hardware device and ``-blockdev`` to
describe the backend. The device defines what the guest sees and the
-backend describes how QEMU handles the data.
+backend describes how QEMU handles the data. It is the only guaranteed
+stable interface for describing block devices and as such is
+recommended for management tools and scripting.
+
+The ``-drive`` option combines the device and backend into a single
+command line option which is a more human friendly. There is however no
+interface stability guarantee although some older board models still
+need updating to work with the modern blockdev forms.
+
+Older options like ``-hda`` are essentially macros which expand into
+``-drive`` options for various drive interfaces. The original forms
+bake in a lot of assumptions from the days when QEMU was emulating a
+legacy PC, they are not recommended for modern configurations.
ERST
issued on other occasions where a cluster gets freed
(on/off; default: off)
+ ``discard-no-unref``
+ When enabled, discards from the guest will not cause cluster
+ allocations to be relinquished. This prevents qcow2 fragmentation
+ that would be caused by such discards. Besides potential
+ performance degradation, such fragmentation can lead to increased
+ allocation of clusters past the end of the image file,
+ resulting in image files whose file length can grow much larger
+ than their guest disk size would suggest.
+ If image file length is of concern (e.g. when storing qcow2
+ images directly on block devices), you should consider enabling
+ this option.
+
``overlap-check``
Which overlap checks to perform for writes to the image
(none/constant/cached/all; default: cached). For details or
the raw disk image you use is not written back. You can however
force the write back by pressing C-a s (see the :ref:`disk images`
chapter in the System Emulation Users Guide).
+
+ .. warning::
+ snapshot is incompatible with ``-blockdev`` (instead use qemu-img
+ to manually create snapshot images to attach to your blockdev).
+ If you have mixed ``-blockdev`` and ``-drive`` declarations you
+ can use the 'snapshot' property on your drive declarations
+ instead of this global option.
+
ERST
DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
Accesses to the filesystem are done by QEMU.
``proxy``
- Accesses to the filesystem are done by virtfs-proxy-helper(1).
+ Accesses to the filesystem are done by virtfs-proxy-helper(1). This
+ option is deprecated (since QEMU 8.1) and will be removed in a future
+ version of QEMU. Use ``local`` instead.
``synth``
Synthetic filesystem, only used by QTests.
``proxy``
Accesses to the filesystem are done by virtfs-proxy-helper(1).
+ This option is deprecated (since QEMU 8.1) and will be removed in a
+ future version of QEMU. Use ``local`` instead.
``synth``
Synthetic filesystem, only used by QTests.
``show-menubar=on|off`` : Display the main window menubar, defaults to "on"
+ ``zoom-to-fit=on|off`` : Expand video output to the window size,
+ defaults to "off"
+
``curses[,charset=<encoding>]``
Display video output via curses. For graphics device models
which support a text mode, QEMU can display this output using a
" [,disable-agent-file-xfer=on|off][,agent-mouse=[on|off]]\n"
" [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
" [,gl=[on|off]][,rendernode=<file>]\n"
- " enable spice\n"
- " at least one of {port, tls-port} is mandatory\n",
+ " enable spice\n"
+ " at least one of {port, tls-port} is mandatory\n",
QEMU_ARCH_ALL)
#endif
SRST
QEMU_ARCH_ALL)
SRST
``-qmp dev``
- Like -monitor but opens in 'control' mode.
+ Like ``-monitor`` but opens in 'control' mode. For example, to make
+ QMP available on localhost port 4444::
+
+ -qmp tcp:localhost:4444,server=on,wait=off
+
+ Not all options are configurable via this syntax; for maximum
+ flexibility use the ``-mon`` option and an accompanying ``-chardev``.
+
ERST
DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
"-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
QEMU_ARCH_ALL)
SRST
``-qmp-pretty dev``
- Like -qmp but uses pretty JSON formatting.
+ Like ``-qmp`` but uses pretty JSON formatting.
ERST
DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
"-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
SRST
``-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]``
- Setup monitor on chardev name. ``mode=control`` configures
- a QMP monitor (a JSON RPC-style protocol) and it is not the
- same as HMP, the human monitor that has a "(qemu)" prompt.
- ``pretty`` is only valid when ``mode=control``,
+ Set up a monitor connected to the chardev ``name``.
+ QEMU supports two monitors: the Human Monitor Protocol
+ (HMP; for human interaction), and the QEMU Monitor Protocol
+ (QMP; a JSON RPC-style protocol).
+ The default is HMP; ``mode=control`` selects QMP instead.
+ ``pretty`` is only valid when ``mode=control``,
turning on JSON pretty printing to ease
human reading and debugging.
+
+ For example::
+
+ -chardev socket,id=mon1,host=localhost,port=4444,server=on,wait=off \
+ -mon chardev=mon1,mode=control,pretty=on
+
+ enables the QMP monitor on localhost port 4444 with pretty-printing.
ERST
DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
ERST
DEF("singlestep", 0, QEMU_OPTION_singlestep, \
- "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
+ "-singlestep deprecated synonym for -accel tcg,one-insn-per-tb=on\n", QEMU_ARCH_ALL)
SRST
``-singlestep``
- Run the emulation in single step mode.
+ This is a deprecated synonym for the TCG accelerator property
+ ``one-insn-per-tb``.
ERST
DEF("preconfig", 0, QEMU_OPTION_preconfig, \
#ifndef _WIN32
DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
- "-chroot dir chroot to dir just before starting the VM\n",
+ "-chroot dir chroot to dir just before starting the VM (deprecated)\n",
QEMU_ARCH_ALL)
#endif
SRST
``-chroot dir``
+ Deprecated, use '-run-with chroot=...' instead.
Immediately before starting guest execution, chroot to the specified
directory. Especially useful in combination with -runas.
ERST
DEF("async-teardown", 0, QEMU_OPTION_asyncteardown,
"-async-teardown enable asynchronous teardown\n",
QEMU_ARCH_ALL)
-#endif
SRST
``-async-teardown``
- Enable asynchronous teardown. A new process called "cleanup/<QEMU_PID>"
- will be created at startup sharing the address space with the main qemu
- process, using clone. It will wait for the main qemu process to
- terminate completely, and then exit.
- This allows qemu to terminate very quickly even if the guest was
- huge, leaving the teardown of the address space to the cleanup
- process. Since the cleanup process shares the same cgroups as the
- main qemu process, accounting is performed correctly. This only
- works if the cleanup process is not forcefully killed with SIGKILL
- before the main qemu process has terminated completely.
+ This option is deprecated and should no longer be used. The new option
+ ``-run-with async-teardown=on`` is a replacement.
+ERST
+#endif
+#ifdef CONFIG_POSIX
+DEF("run-with", HAS_ARG, QEMU_OPTION_run_with,
+ "-run-with [async-teardown=on|off][,chroot=dir]\n"
+ " Set miscellaneous QEMU process lifecycle options:\n"
+ " async-teardown=on enables asynchronous teardown (Linux only)\n"
+ " chroot=dir chroot to dir just before starting the VM\n",
+ QEMU_ARCH_ALL)
+SRST
+``-run-with [async-teardown=on|off][,chroot=dir]``
+ Set QEMU process lifecycle options.
+
+ ``async-teardown=on`` enables asynchronous teardown. A new process called
+ "cleanup/<QEMU_PID>" will be created at startup sharing the address
+ space with the main QEMU process, using clone. It will wait for the
+ main QEMU process to terminate completely, and then exit. This allows
+ QEMU to terminate very quickly even if the guest was huge, leaving the
+ teardown of the address space to the cleanup process. Since the cleanup
+ process shares the same cgroups as the main QEMU process, accounting is
+ performed correctly. This only works if the cleanup process is not
+ forcefully killed with SIGKILL before the main QEMU process has
+ terminated completely.
+
+ ``chroot=dir`` can be used for doing a chroot to the specified directory
+ immediately before starting the guest execution. This is especially useful
+ in combination with -runas.
ERST
+#endif
DEF("msg", HAS_ARG, QEMU_OPTION_msg,
"-msg [timestamp[=on|off]][,guest-name=[on|off]]\n"
they are specified. Note that the 'id' property must be set. These
objects are placed in the '/objects' path.
- ``-object memory-backend-file,id=id,size=size,mem-path=dir,share=on|off,discard-data=on|off,merge=on|off,dump=on|off,prealloc=on|off,host-nodes=host-nodes,policy=default|preferred|bind|interleave,align=align,readonly=on|off``
+ ``-object memory-backend-file,id=id,size=size,mem-path=dir,share=on|off,discard-data=on|off,merge=on|off,dump=on|off,prealloc=on|off,host-nodes=host-nodes,policy=default|preferred|bind|interleave,align=align,offset=offset,readonly=on|off``
Creates a memory file backend object, which can be used to back
the guest RAM with huge pages.
such cases, users can specify the required alignment via this
option.
+ The ``offset`` option specifies the offset into the target file
+ that the region starts at. You can use this parameter to back
+ multiple regions with a single file.
+
The ``pmem`` option specifies whether the backing file specified
by ``mem-path`` is in host persistent memory that can be
accessed using the SNIA NVM programming model (e.g. Intel
physical address space. The ``reduced-phys-bits`` is used to
provide the number of bits we loose in physical address space.
Similar to C-bit, the value is Host family dependent. On EPYC,
- the value should be 5.
+ a guest will lose a maximum of 1 bit, so the value should be 1.
The ``sev-device`` provides the device file to use for
communicating with the SEV firmware running inside AMD Secure
# |qemu_system_x86| \\
...... \\
- -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \\
+ -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=1 \\
-machine ...,memory-encryption=sev0 \\
.....
projects / mirror_qemu.git / blobdiff