" 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"
``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
" 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
.. parsed-literal::
- |qemu_system_x86| -drive file=a -drive file=b"
+ |qemu_system_x86| -drive file=a -drive file=b
is interpreted like:
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,
ERST
DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
- "-iscsi [user=user][,password=password]\n"
- " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
+ "-iscsi [user=user][,password=password][,password-secret=secret-id]\n"
+ " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE]\n"
" [,initiator-name=initiator-iqn][,id=target-iqn]\n"
" [,timeout=timeout]\n"
" iSCSI session parameters\n", QEMU_ARCH_ALL)
" [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
" [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
" [,sasl=on|off][,disable-ticketing=on|off]\n"
- " [,password=<string>][,password-secret=<secret-id>]\n"
+ " [,password-secret=<secret-id>]\n"
" [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
" [,jpeg-wan-compression=[auto|never|always]]\n"
" [,zlib-glz-wan-compression=[auto|never|always]]\n"
``ipv4=on|off``; \ ``ipv6=on|off``; \ ``unix=on|off``
Force using the specified IP version.
- ``password=<string>``
- Set the password you need to authenticate.
-
- This option is deprecated and insecure because it leaves the
- password visible in the process listing. Use ``password-secret``
- instead.
-
``password-secret=<secret-id>``
Set the ID of the ``secret`` object containing the password
you need to authenticate.
" specify SMBIOS type 17 fields\n"
"-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]\n"
" specify SMBIOS type 41 fields\n",
- QEMU_ARCH_I386 | QEMU_ARCH_ARM)
+ QEMU_ARCH_I386 | QEMU_ARCH_ARM | QEMU_ARCH_LOONGARCH)
SRST
``-smbios file=binary``
Load SMBIOS entry from binary file.
"-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
" configure a network backend to connect to another network\n"
" using an UDP tunnel\n"
- "-netdev stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port[,to=maxport][,numeric=on|off][,keep-alive=on|off][,mptcp=on|off][,addr.ipv4=on|off][,addr.ipv6=on|off]\n"
- "-netdev stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off]\n"
- "-netdev stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor\n"
+ "-netdev stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port[,to=maxport][,numeric=on|off][,keep-alive=on|off][,mptcp=on|off][,addr.ipv4=on|off][,addr.ipv6=on|off][,reconnect=seconds]\n"
+ "-netdev stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off][,reconnect=seconds]\n"
+ "-netdev stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor[,reconnect=seconds]\n"
" configure a network backend to connect to another network\n"
" using a socket connection in stream mode.\n"
"-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]\n"
"-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
" [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
"-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
- "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
+ "-chardev file,id=id,path=path[,input-path=input-file][,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
"-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
#ifdef _WIN32
"-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
Create a ring buffer with fixed size ``size``. size must be a power
of two and defaults to ``64K``.
-``-chardev file,id=id,path=path``
+``-chardev file,id=id,path=path[,input-path=input-path]``
Log all traffic received from the guest to a file.
``path`` specifies the path of the file to be opened. This file will
be created if it does not already exist, and overwritten if it does.
``path`` is required.
+ If ``input-path`` is specified, this is the path of a second file
+ which will be used for input. If ``input-path`` is not specified,
+ no input will be available from the chardev.
+
+ Note that ``input-path`` is not supported on Windows hosts.
+
``-chardev pipe,id=id,path=path``
Create a two-way connection to the guest. The behaviour differs
slightly between Windows hosts and other hosts:
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, \
QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
SRST
``-semihosting``
- Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
+ Enable :ref:`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.
+ .. warning::
+ Note that this allows guest direct access to the host filesystem, so
+ should only be used with a trusted guest OS.
See the -semihosting-config option documentation for further
information about the facilities this enables.
QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
SRST
``-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,userspace=on|off][,arg=str[,...]]``
- Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V
+ Enable and configure :ref:`Semihosting` (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.
-
- On Arm this implements the standard semihosting API, version 2.0.
-
- On M68K this implements the "ColdFire GDB" interface used by
- libgloss.
-
- Xtensa semihosting provides basic file IO calls, such as
- 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.
+ .. warning::
+ Note that this allows guest direct access to the host filesystem, so
+ should only be used with a trusted guest OS.
``target=native|gdb|auto``
Defines where the semihosting calls will be addressed, to QEMU
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
+DEF("run-with", HAS_ARG, QEMU_OPTION_run_with,
+ "-run-with async-teardown[=on|off]\n"
+ " misc QEMU process lifecycle options\n"
+ " async-teardown=on enables asynchronous teardown\n",
+ QEMU_ARCH_ALL)
+SRST
+``-run-with``
+ 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.
+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