" suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
" nvdimm=on|off controls NVDIMM support (default=off)\n"
" memory-encryption=@var{} memory encryption object to use (default=none)\n"
- " hmat=on|off controls ACPI HMAT support (default=off)\n",
+ " hmat=on|off controls ACPI HMAT support (default=off)\n"
+ " memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n",
QEMU_ARCH_ALL)
SRST
``-machine [type=]name[,prop=value[,...]]``
``hmat=on|off``
Enables or disables ACPI Heterogeneous Memory Attribute Table
(HMAT) support. The default is off.
+
+ ``memory-backend='id'``
+ An alternative to legacy ``-mem-path`` and ``mem-prealloc`` options.
+ Allows to use a memory backend as main RAM.
+
+ For example:
+ ::
+ -object memory-backend-file,id=pc.ram,size=512M,mem-path=/hugetlbfs,prealloc=on,share=on
+ -machine memory-backend=pc.ram
+ -m 512M
+
+ Migration compatibility note:
+ a) as backend id one shall use value of 'default-ram-id', advertised by
+ machine type (available via ``query-machines`` QMP command), if migration
+ to/from old QEMU (<5.0) is expected.
+ b) for machine types 4.0 and older, user shall
+ use ``x-use-canonical-path-for-ramblock-id=off`` backend option
+ if migration to/from old QEMU (<5.0) is expected.
+ For example:
+ ::
+ -object memory-backend-ram,id=pc.ram,size=512M,x-use-canonical-path-for-ramblock-id=off
+ -machine memory-backend=pc.ram
+ -m 512M
ERST
HXCOMM Deprecated by -machine
" 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"
+ " split-wx=on|off (enable TCG split w^x mapping)\n"
" tb-size=n (TCG translation block cache size)\n"
" thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
SRST
``kvm-shadow-mem=size``
Defines the size of the KVM shadow MMU.
+ ``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
+ such a case this will default on. On other operating systems, this
+ will default off, but one may enable this for testing or debugging.
+
``tb-size=n``
Controls the size (in MiB) of the TCG translation block cache.
#endif
#ifdef CONFIG_AUDIO_SDL
"-audiodev sdl,id=id[,prop[=value][,...]]\n"
+ " in|out.buffer-count= number of buffers\n"
#endif
#ifdef CONFIG_SPICE
"-audiodev spice,id=id[,prop[=value][,...]]\n"
``-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
- possible. This backend has no backend specific properties.
+ possible.
+
+ SDL specific options are:
+
+ ``in|out.buffer-count=count``
+ Sets the count of the buffers.
``-audiodev spice,id=id[,prop[=value][,...]]``
Creates a backend that sends audio through SPICE. This backend
DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
"-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n"
- " [,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode]\n"
+ " [,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode]\n"
" [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
" [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
" [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
" [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
" [[,throttling.iops-size=is]]\n"
- "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly]\n"
- "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly]\n"
+ "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly=on]\n"
+ "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly=on]\n"
"-fsdev synth,id=id\n",
QEMU_ARCH_ALL)
SRST
-``-fsdev local,id=id,path=path,security_model=security_model [,writeout=writeout][,readonly][,fmode=fmode][,dmode=dmode] [,throttling.option=value[,throttling.option=value[,...]]]``
+``-fsdev local,id=id,path=path,security_model=security_model [,writeout=writeout][,readonly=on][,fmode=fmode][,dmode=dmode] [,throttling.option=value[,throttling.option=value[,...]]]``
\
-``-fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly]``
+``-fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly=on]``
\
-``-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly]``
+``-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly=on]``
\
-``-fsdev synth,id=id[,readonly]``
+``-fsdev synth,id=id[,readonly=on]``
Define a new file system device. Valid options are:
``local``
guest only when the data has been reported as written by the
storage subsystem.
- ``readonly``
+ ``readonly=on``
Enables exporting 9p share as a readonly mount for guests. By
default read-write access is given.
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][,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",
+ " [,id=id][,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n"
+ "-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly=on]\n"
+ "-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly=on]\n"
+ "-virtfs synth,mount_tag=tag[,id=id][,readonly=on]\n",
QEMU_ARCH_ALL)
SRST
-``-virtfs local,path=path,mount_tag=mount_tag ,security_model=security_model[,writeout=writeout][,readonly] [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]``
+``-virtfs local,path=path,mount_tag=mount_tag ,security_model=security_model[,writeout=writeout][,readonly=on] [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]``
\
-``-virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=writeout][,readonly]``
+``-virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=writeout][,readonly=on]``
\
-``-virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=writeout][,readonly]``
+``-virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=writeout][,readonly=on]``
\
``-virtfs synth,mount_tag=mount_tag``
Define a new virtual filesystem device and expose it to the guest using
guest only when the data has been reported as written by the
storage subsystem.
- ``readonly``
+ ``readonly=on``
Enables exporting 9p share as a readonly mount for guests. By
default read-write access is given.
transmission. When not using an -audiodev argument, this option
must be omitted, otherwise is must be present and specify a
valid audiodev.
+
+ ``power-control``
+ Permit the remote client to issue shutdown, reboot or reset power
+ control requests.
ERST
ARCHHEADING(, QEMU_ARCH_I386)
Do not start CPU at startup (you must type 'c' in the monitor).
ERST
-DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
- "-realtime [mlock=on|off]\n"
- " run qemu with realtime features\n"
- " mlock=on|off controls mlock support (default: on)\n",
- QEMU_ARCH_ALL)
-SRST
-``-realtime mlock=on|off``
- Run qemu with realtime features. mlocking qemu and guest memory can
- be enabled via ``mlock=on`` (enabled by default).
-ERST
-
DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
"-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
" run qemu with overcommit hints\n"
Locking qemu and guest memory can be enabled via ``mem-lock=on``
(disabled by default). This works when host memory is not
- overcommitted and reduces the worst-case latency for guest. This is
- equivalent to ``realtime``.
+ overcommitted and reduces the worst-case latency for guest.
Guest ability to manage power state of host cpus (increasing latency
for other processes on the same host cpu, but decreasing latency for
changes to the disk image.
ERST
+DEF("action", HAS_ARG, QEMU_OPTION_action,
+ "-action reboot=reset|shutdown\n"
+ " action when guest reboots [default=reset]\n"
+ "-action shutdown=poweroff|pause\n"
+ " action when guest shuts down [default=poweroff]\n"
+ "-action panic=pause|shutdown|none\n"
+ " action when guest panics [default=shutdown]\n"
+ "-action watchdog=reset|shutdown|poweroff|inject-nmi|pause|debug|none\n"
+ " action when watchdog fires [default=reset]\n",
+ QEMU_ARCH_ALL)
+SRST
+``-action event=action``
+ The action parameter serves to modify QEMU's default behavior when
+ certain guest events occur. It provides a generic method for specifying the
+ same behaviors that are modified by the ``-no-reboot`` and ``-no-shutdown``
+ parameters.
+
+ Examples:
+
+ ``-action panic=none``
+ ``-action reboot=shutdown,shutdown=pause``
+ ``-watchdog i6300esb -action watchdog=pause``
+
+ERST
+
DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
"-loadvm [tag|id]\n" \
" start right away with a saved state (loadvm in monitor)\n",
ERST
DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
- "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
+ "-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=<filename>[,rrsnapshot=<snapshot>]]\n" \
" enable virtual instruction counter with 2^N clock ticks per\n" \
" instruction, enable aligning the host and virtual clocks\n" \
- " or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
+ " or disable real time cpu sleeping, and optionally enable\n" \
+ " record-and-replay mode\n", QEMU_ARCH_ALL)
SRST
-``-icount [shift=N|auto][,rr=record|replay,rrfile=filename,rrsnapshot=snapshot]``
+``-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=filename[,rrsnapshot=snapshot]]``
Enable virtual instruction counter. The virtual cpu will execute one
instruction every 2^N ns of virtual time. If ``auto`` is specified
then the virtual cpu speed will be automatically adjusted to keep
virtual time within a few seconds of real time.
- When the virtual cpu is sleeping, the virtual time will advance at
- default speed unless ``sleep=on|off`` is specified. With
- ``sleep=on|off``, the virtual time will jump to the next timer
- deadline instantly whenever the virtual cpu goes to sleep mode and
- will not advance if no timer is enabled. This behavior give
- deterministic execution times from the guest point of view.
-
Note that while this option can give deterministic behavior, it does
not provide cycle accurate emulation. Modern CPUs contain
superscalar out of order cores with complex cache hierarchies. The
number of instructions executed often has little or no correlation
with actual performance.
+ When the virtual cpu is sleeping, the virtual time will advance at
+ default speed unless ``sleep=on`` is specified. With
+ ``sleep=on``, the virtual time will jump to the next timer
+ deadline instantly whenever the virtual cpu goes to sleep mode and
+ will not advance if no timer is enabled. This behavior gives
+ deterministic execution times from the guest point of view.
+ The default if icount is enabled is ``sleep=off``.
+ ``sleep=on`` cannot be used together with either ``shift=auto``
+ or ``align=on``.
+
``align=on`` will activate the delay algorithm which will try to
synchronise the host clock and the virtual clock. The goal is to
have a guest running at the real frequency imposed by the shift
``shift`` is ``auto``. Note: The sync algorithm will work for those
shift values for which the guest clock runs ahead of the host clock.
Typically this happens when the shift value is high (how high
- depends on the host machine).
-
- When ``rr`` option is specified deterministic record/replay is
- enabled. Replay log is written into filename file in record mode and
- read from this file in replay mode.
-
- Option rrsnapshot is used to create new vm snapshot named snapshot
- at the start of execution recording. In replay mode this option is
- used to load the initial VM state.
+ depends on the host machine). The default if icount is enabled
+ is ``align=off``.
+
+ When the ``rr`` option is specified deterministic record/replay is
+ enabled. The ``rrfile=`` option must also be provided to
+ specify the path to the replay log. In record mode data is written
+ to this file, and in replay mode it is read back.
+ If the ``rrsnapshot`` option is given then it specifies a VM snapshot
+ name. In record mode, a new VM snapshot with the given name is created
+ at the start of execution recording. In replay mode this option
+ specifies the snapshot name used to load the initial VM state.
ERST
DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
ERST
-DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
- "-show-cursor show cursor\n", QEMU_ARCH_ALL)
-SRST
-``-show-cursor``
- Show cursor.
-ERST
-
-DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
- "-tb-size n set TB size\n", QEMU_ARCH_ALL)
-SRST
-``-tb-size n``
- Set TCG translation block cache size. Deprecated, use
- '\ ``-accel tcg,tb-size=n``\ ' instead.
-ERST
-
DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
"-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
"-incoming rdma:host:port[,ipv4][,ipv6]\n" \
DEF("semihosting", 0, QEMU_OPTION_semihosting,
"-semihosting semihosting mode\n",
QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
- QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2)
+ QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
SRST
``-semihosting``
- Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only).
+ Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
Note that this allows guest direct access to the host filesystem, so
should only be used with a trusted guest OS.
"-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]\n" \
" semihosting configuration\n",
QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
-QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2)
+QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
SRST
``-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]``
- Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II
+ Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V
only).
Note that this allows guest direct access to the host filesystem, so
open/read/write/seek/select. Tensilica baremetal libc for ISS and
linux platform "sim" use this interface.
+ On RISC-V this implements the standard semihosting API, version 0.2.
+
``target=native|gdb|auto``
Defines where the semihosting calls will be addressed, to QEMU
(``native``) or to GDB (``gdb``). The default is ``auto``, which
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``
+ ``-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``
Creates a memory file backend object, which can be used to back
the guest RAM with huge pages.
4.15) and the filesystem of ``mem-path`` mounted with DAX
option.
+ The ``readonly`` option specifies whether the backing file is opened
+ read-only or read-write (default).
+
``-object memory-backend-ram,id=id,merge=on|off,dump=on|off,share=on|off,prealloc=on|off,size=size,host-nodes=host-nodes,policy=default|preferred|bind|interleave``
Creates a memory backend object, which can be used to back the
guest RAM. Memory backend objects offer more control than the
Note the use of quotes due to the x509 distinguished name
containing whitespace, and escaping of ','.
- ``-object authz-listfile,id=id,filename=path,refresh=yes|no``
+ ``-object authz-listfile,id=id,filename=path,refresh=on|off``
Create an authorization object that will control access to
network services.
# |qemu_system| \\
... \\
- -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes \\
+ -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=on \\
...
``-object authz-pam,id=id,service=string``