Enables or disables ACPI Heterogeneous Memory Attribute Table
(HMAT) support. The default is off.
- ``memory-backend='id'``
+ ``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
+
+ -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.
+
+ * 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.
+ * 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
+
+ -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
-DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
+DEF("M", HAS_ARG, QEMU_OPTION_M,
+ " sgx-epc.0.memdev=memid\n",
+ QEMU_ARCH_ALL)
+
+SRST
+``sgx-epc.0.memdev=@var{memid}``
+ Define an SGX EPC section.
+ERST
DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
"-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
ERST
DEF("smp", HAS_ARG, QEMU_OPTION_smp,
- "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
+ "-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]\n"
" set the number of CPUs to 'n' [default=1]\n"
- " maxcpus= maximum number of total cpus, including\n"
+ " maxcpus= maximum number of total CPUs, including\n"
" offline CPUs for hotplug, etc\n"
- " cores= number of CPU cores on one socket (for PC, it's on one die)\n"
- " threads= number of threads on one CPU core\n"
+ " sockets= number of discrete sockets in the system\n"
" dies= number of CPU dies on one socket (for PC only)\n"
- " sockets= number of discrete sockets in the system\n",
+ " cores= number of CPU cores on one socket (for PC, it's on one die)\n"
+ " threads= number of threads on one CPU core\n",
QEMU_ARCH_ALL)
SRST
-``-smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]``
- Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
- are supported. On Sparc32 target, Linux limits the number of usable
- CPUs to 4. For the PC target, the number of cores per die, the
- number of threads per cores, the number of dies per packages and the
- total number of sockets can be specified. Missing values will be
- computed. If any on the three values is given, the total number of
- CPUs n can be omitted. maxcpus specifies the maximum number of
- hotpluggable CPUs.
+``-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,cores=cores][,threads=threads]``
+ Simulate a SMP system with '\ ``n``\ ' CPUs initially present on
+ the machine type board. On boards supporting CPU hotplug, the optional
+ '\ ``maxcpus``\ ' parameter can be set to enable further CPUs to be
+ added at runtime. When both parameters are omitted, the maximum number
+ of CPUs will be calculated from the provided topology members and the
+ initial CPU count will match the maximum number. When only one of them
+ is given then the omitted one will be set to its counterpart's value.
+ Both parameters may be specified, but the maximum number of CPUs must
+ be equal to or greater than the initial CPU count. Both parameters are
+ subject to an upper limit that is determined by the specific machine
+ type chosen.
+
+ To control reporting of CPU topology information, the number of sockets,
+ dies per socket, cores per die, and threads per core can be specified.
+ The sum `` sockets * cores * dies * threads `` must be equal to the
+ maximum CPU count. CPU targets may only support a subset of the topology
+ parameters. Where a CPU target does not support use of a particular
+ topology parameter, its value should be assumed to be 1 for the purpose
+ of computing the CPU maximum count.
+
+ Either the initial CPU count, or at least one of the topology parameters
+ must be specified. The specified parameters must be greater than zero,
+ explicit configuration like "cpus=0" is not allowed. Values for any
+ omitted parameters will be computed from those which are given.
+ Historically preference was given to the coarsest topology parameters
+ when computing missing values (ie sockets preferred over cores, which
+ were preferred over threads), however, this behaviour is considered
+ liable to change. Prior to 6.2 the preference was sockets over cores
+ over threads. Since 6.2 the preference is cores over sockets over threads.
ERST
DEF("numa", HAS_ARG, QEMU_OPTION_numa,
-m 2G \
-object memory-backend-ram,size=1G,id=m0 \
-object memory-backend-ram,size=1G,id=m1 \
- -smp 2 \
+ -smp 2,sockets=2,maxcpus=2 \
-numa node,nodeid=0,memdev=m0 \
-numa node,nodeid=1,memdev=m1,initiator=0 \
-numa cpu,node-id=0,socket-id=0 \
``-device pci-ipmi-bt,bmc=id``
Like the KCS interface, but defines a BT interface on the PCI bus.
+
+``-device intel-iommu[,option=...]``
+ This is only supported by ``-machine q35``, which will enable Intel VT-d
+ emulation within the guest. It supports below options:
+
+ ``intremap=on|off`` (default: auto)
+ This enables interrupt remapping feature. It's required to enable
+ complete x2apic. Currently it only supports kvm kernel-irqchip modes
+ ``off`` or ``split``, while full kernel-irqchip is not yet supported.
+ The default value is "auto", which will be decided by the mode of
+ kernel-irqchip.
+
+ ``caching-mode=on|off`` (default: off)
+ This enables caching mode for the VT-d emulated device. When
+ caching-mode is enabled, each guest DMA buffer mapping will generate an
+ IOTLB invalidation from the guest IOMMU driver to the vIOMMU device in
+ a synchronous way. It is required for ``-device vfio-pci`` to work
+ with the VT-d device, because host assigned devices requires to setup
+ the DMA mapping on the host before guest DMA starts.
+
+ ``device-iotlb=on|off`` (default: off)
+ This enables device-iotlb capability for the emulated VT-d device. So
+ far virtio/vhost should be the only real user for this parameter,
+ paired with ats=on configured for the device.
+
+ ``aw-bits=39|48`` (default: 39)
+ This decides the address width of IOVA address space. The address
+ space has 39 bits width for 3-level IOMMU page tables, and 48 bits for
+ 4-level IOMMU page tables.
+
+ Please also refer to the wiki page for general scenarios of VT-d
+ emulation in QEMU: https://wiki.qemu.org/Features/VT-d.
+
ERST
DEF("name", HAS_ARG, QEMU_OPTION_name,
"-display spice-app[,gl=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"
+ "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off][,gl=on|core|es|off]\n"
+ " [,grab-mod=<mod>][,show-cursor=on|off][,window-close=on|off]\n"
#endif
#if defined(CONFIG_GTK)
- "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
+ "-display gtk[,full-screen=on|off][,gl=on|off][,grab-on-hover=on|off]\n"
+ " [,show-cursor=on|off][,window-close=on|off]\n"
#endif
#if defined(CONFIG_VNC)
"-display vnc=<display>[,<optargs>]\n"
old style -sdl/-curses/... options. Use ``-display help`` to list
the available display types. Valid values for type are
+ ``spice-app[,gl=on|off]``
+ Start QEMU as a Spice server and launch the default Spice client
+ application. The Spice server will redirect the serial consoles
+ and QEMU monitors. (Since 4.0)
+
``sdl``
Display video output via SDL (usually in a separate graphics
window; see the SDL documentation for other possibilities).
+ Valid parameters are:
+
+ ``grab-mod=<mods>`` : Used to select the modifier keys for toggling
+ the mouse grabbing in conjunction with the "g" key. `<mods>` can be
+ either `lshift-lctrl-lalt` or `rctrl`.
+
+ ``alt_grab=on|off`` : Use Control+Alt+Shift-g to toggle mouse grabbing.
+ This parameter is deprecated - use ``grab-mod`` instead.
+
+ ``ctrl_grab=on|off`` : Use Right-Control-g to toggle mouse grabbing.
+ This parameter is deprecated - use ``grab-mod`` instead.
+
+ ``gl=on|off|core|es`` : Use OpenGL for displaying
+
+ ``show-cursor=on|off`` : Force showing the mouse cursor
+
+ ``window-close=on|off`` : Allow to quit qemu with window close button
+
+ ``gtk``
+ Display video output in a GTK window. This interface provides
+ drop-down menus and other UI elements to configure and control
+ the VM during runtime. Valid parameters are:
- ``curses``
+ ``full-screen=on|off`` : Start in fullscreen mode
+
+ ``gl=on|off`` : Use OpenGL for displaying
+
+ ``grab-on-hover=on|off`` : Grab keyboard input on mouse hover
+
+ ``show-cursor=on|off`` : Force showing the mouse cursor
+
+ ``window-close=on|off`` : Allow to quit qemu with window close button
+
+ ``curses[,charset=<encoding>]``
Display video output via curses. For graphics device models
which support a text mode, QEMU can display this output using a
curses/ncurses interface. Nothing is displayed when the graphics
``charset=CP850`` for IBM CP850 encoding. The default is
``CP437``.
+ ``egl-headless[,rendernode=<file>]``
+ Offload all OpenGL operations to a local DRI device. For any
+ graphical display, this display needs to be paired with either
+ VNC or SPICE displays.
+
+ ``vnc=<display>``
+ Start a VNC server on display <display>
+
``none``
Do not display video output. The guest will still see an
emulated graphics card, but its output will not be displayed to
that it only affects what is done with video output; -nographic
also changes the destination of the serial and parallel port
data.
-
- ``gtk``
- Display video output in a GTK window. This interface provides
- drop-down menus and other UI elements to configure and control
- the VM during runtime.
-
- ``vnc``
- Start a VNC server on display <arg>
-
- ``egl-headless``
- Offload all OpenGL operations to a local DRI device. For any
- graphical display, this display needs to be paired with either
- VNC or SPICE displays.
-
- ``spice-app``
- Start QEMU as a Spice server and launch the default Spice client
- application. The Spice server will redirect the serial consoles
- and QEMU monitors. (Since 4.0)
ERST
DEF("nographic", 0, QEMU_OPTION_nographic,
``-alt-grab``
Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that
this also affects the special keys (for fullscreen, monitor-mode
- switching, etc).
+ switching, etc). This option is deprecated - please use
+ ``-display sdl,grab-mod=lshift-lctrl-lalt`` instead.
ERST
DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
``-ctrl-grab``
Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this
also affects the special keys (for fullscreen, monitor-mode
- switching, etc).
+ switching, etc). This option is deprecated - please use
+ ``-display sdl,grab-mod=rctrl`` instead.
ERST
DEF("no-quit", 0, QEMU_OPTION_no_quit,
- "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
+ "-no-quit disable SDL/GTK window close capability (deprecated)\n", QEMU_ARCH_ALL)
SRST
``-no-quit``
- Disable SDL window close capability.
+ Disable window close capability (SDL and GTK only). This option is
+ deprecated, please use ``-display ...,window-close=off`` instead.
ERST
DEF("sdl", 0, QEMU_OPTION_sdl,
DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
"-chardev help\n"
"-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
- "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off][,reconnect=seconds]\n"
+ "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]\n"
" [,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds][,mux=on|off]\n"
" [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n"
"-chardev socket,id=id,path=path[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds]\n"
"-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. ``pretty`` is only valid when
- ``mode=control``, turning on JSON pretty printing to ease
+ 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``,
+ turning on JSON pretty printing to ease
human reading and debugging.
ERST
ERST
DEF("plugin", HAS_ARG, QEMU_OPTION_plugin,
- "-plugin [file=]<file>[,arg=<string>]\n"
+ "-plugin [file=]<file>[,<argname>=<argvalue>]\n"
" load a plugin\n",
QEMU_ARCH_ALL)
SRST
-``-plugin file=file[,arg=string]``
+``-plugin file=file[,argname=argvalue]``
Load a plugin.
``file=file``
Load the given plugin from a shared library file.
- ``arg=string``
- Argument string passed to the plugin. (Can be given multiple
- times.)
+ ``argname=argvalue``
+ Argument passed to the plugin. (Can be given multiple times.)
ERST
HXCOMM Internal use
CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
- ``-object iothread,id=id,poll-max-ns=poll-max-ns,poll-grow=poll-grow,poll-shrink=poll-shrink``
+ ``-object iothread,id=id,poll-max-ns=poll-max-ns,poll-grow=poll-grow,poll-shrink=poll-shrink,aio-max-batch=aio-max-batch``
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.
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
+ The ``aio-max-batch`` parameter is the maximum number of requests
+ in a batch for the AIO engine, 0 means that the engine will use
+ its default.
+
+ The IOThread parameters can be modified at run-time using the
``qom-set`` command (where ``iothread1`` is the IOThread's
``id``):
HXCOMM This is the last statement. Insert new options before this line!
+
+#undef DEF
+#undef DEFHEADING
+#undef ARCHHEADING