"-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, whpx or tcg (default: tcg)\n"
+ " supported accelerators are kvm, xen, hax, 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, whpx or tcg can be available.
+ architecture, kvm, xen, hax, 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, whpx or tcg; use 'help' for a list)\n"
+ " select accelerator (kvm, xen, hax, 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"
" 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"
" thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
SRST
``-accel name[,prop=value[,...]]``
This is used to enable an accelerator. Depending on the target
- architecture, kvm, xen, hax, hvf, whpx or tcg can be available. By
+ architecture, kvm, xen, hax, 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.
where both the back-end and front-ends support it and no
incompatible TCG features have been enabled (e.g.
icount/replay).
+
+ ``dirty-ring-size=n``
+ When the KVM accelerator is used, it controls the size of the per-vCPU
+ dirty page ring buffer (number of entries for each vCPU). It should
+ be a value that is power of two, and it should be 1024 or bigger (but
+ still less than the maximum value that the kernel supports). 4096
+ could be a good initial value if you have no idea which is the best.
+ Set this value to 0 to disable the feature. By default, this feature
+ is disabled (dirty-ring-size=0). When enabled, KVM will instead
+ record dirty pages in a bitmap.
+
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=cpus][,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. If omitted the maximum number of CPUs will be
+ set to match 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. 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.
ERST
DEF("numa", HAS_ARG, QEMU_OPTION_numa,
``-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,
DEFHEADING()
-DEFHEADING(USB options:)
+DEFHEADING(USB convenience options:)
DEF("usb", 0, QEMU_OPTION_usb,
"-usb enable on-board USB host controller (if not enabled by default)\n",
QEMU_ARCH_ALL)
SRST
``-usbdevice devname``
- Add the USB device devname. Note that this option is deprecated,
- please use ``-device usb-...`` instead. See the chapter about
+ Add the USB device devname, and enable an on-board USB controller
+ if possible and necessary (just like it can be done via
+ ``-machine usb=on``). Note that this option is mainly intended for
+ the user's convenience only. More fine-grained control can be
+ achieved by selecting a USB host controller (if necessary) and the
+ desired USB device via the ``-device`` option instead. For example,
+ instead of using ``-usbdevice mouse`` it is possible to use
+ ``-device qemu-xhci -device usb-mouse`` to connect the USB mouse
+ to a USB 3.0 controller instead (at least on machines that support
+ PCI and do not have an USB controller enabled by default yet).
+ For more details, see the chapter about
:ref:`Connecting USB devices` in the System Emulation Users Guide.
+ Possible devices for devname are:
+
+ ``braille``
+ Braille device. This will use BrlAPI to display the braille
+ output on a real or fake device (i.e. it also creates a
+ corresponding ``braille`` chardev automatically beside the
+ ``usb-braille`` USB device).
+
+ ``keyboard``
+ Standard USB keyboard. Will override the PS/2 keyboard (if present).
``mouse``
Virtual Mouse. This will override the PS/2 mouse emulation when
position without having to grab the mouse. Also overrides the
PS/2 mouse emulation when activated.
- ``braille``
- Braille device. This will use BrlAPI to display the braille
- output on a real or fake device.
+ ``wacom-tablet``
+ Wacom PenPartner USB tablet.
+
+
ERST
DEFHEADING()
"-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"
+ " [,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:
+
+ ``alt_grab=on|off`` : Use Control+Alt+Shift-g to toggle mouse grabbing
+
+ ``ctrl_grab=on|off`` : Use Right-Control-g to toggle mouse grabbing
+
+ ``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:
+
+ ``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
- ``curses``
+ ``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,
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,
" [,tls-ciphers=<list>]\n"
" [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
" [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
- " [,sasl=on|off][,password=<secret>][,disable-ticketing=on|off]\n"
+ " [,sasl=on|off][,disable-ticketing=on|off]\n"
+ " [,password=<string>][,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=<secret>``
+ ``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.
+
``sasl=on|off``
Require that the client use SASL to authenticate with the spice.
The exact choice of authentication method used is controlled
time to allow <protocol> password to expire immediately or never
expire.
+ ``password-secret=<secret-id>``
+ Require that password based authentication is used for client
+ connections, using the password provided by the ``secret``
+ object identified by ``secret-id``.
+
``tls-creds=ID``
Provides the ID of a set of TLS credentials to use to secure the
VNC server. They will apply to both the normal VNC server socket
" specify SMBIOS type 11 fields\n"
"-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
" [,asset=str][,part=str][,speed=%d]\n"
- " specify SMBIOS type 17 fields\n",
+ " 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)
SRST
``-smbios file=binary``
``-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]``
Specify SMBIOS type 17 fields
+
+``-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]``
+ Specify SMBIOS type 41 fields
+
+ This argument can be repeated multiple times. Its main use is to allow network interfaces be created
+ as ``enoX`` on Linux, with X being the instance number, instead of the name depending on the interface
+ position on the PCI bus.
+
+ Here is an example of use:
+
+ .. parsed-literal::
+
+ -netdev user,id=internet \\
+ -device virtio-net-pci,mac=50:54:00:00:00:42,netdev=internet,id=internet-dev \\
+ -smbios type=41,designation='Onboard LAN',instance=1,kind=ethernet,pcidev=internet-dev
+
+ In the guest OS, the device should then appear as ``eno1``:
+
+ ..parsed-literal::
+
+ $ ip -brief l
+ lo UNKNOWN 00:00:00:00:00:00 <LOOPBACK,UP,LOWER_UP>
+ eno1 UP 50:54:00:00:00:42 <BROADCAST,MULTICAST,UP,LOWER_UP>
+
+ Currently, the PCI device has to be attached to the root bus.
+
ERST
DEFHEADING()
DEFHEADING(Debug/Expert options:)
+DEF("compat", HAS_ARG, QEMU_OPTION_compat,
+ "-compat [deprecated-input=accept|reject|crash][,deprecated-output=accept|hide]\n"
+ " Policy for handling deprecated management interfaces\n",
+ QEMU_ARCH_ALL)
+SRST
+``-compat [deprecated-input=@var{input-policy}][,deprecated-output=@var{output-policy}]``
+ Set policy for handling deprecated management interfaces (experimental):
+
+ ``deprecated-input=accept`` (default)
+ Accept deprecated commands and arguments
+ ``deprecated-input=reject``
+ Reject deprecated commands and arguments
+ ``deprecated-input=crash``
+ Crash on deprecated commands and arguments
+ ``deprecated-output=accept`` (default)
+ Emit deprecated command results and events
+ ``deprecated-output=hide``
+ Suppress deprecated command results and events
+
+ Limitation: covers only syntactic aspects of QMP.
+ERST
+
DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
"-fw_cfg [name=]<name>,file=<file>\n"
" add named fw_cfg entry with contents from file\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`` turns on JSON pretty
- printing easing human reading and debugging.
+ 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
DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
ERST
DEF("semihosting", 0, QEMU_OPTION_semihosting,
"-semihosting semihosting mode\n",
- QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 |
+ QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA |
QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
SRST
``-semihosting``
DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config,
"-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_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA |
QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
SRST
``-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]``
the guest RAM with huge pages.
The ``id`` parameter is a unique ID that will be used to
- reference this memory region when configuring the ``-numa``
- argument.
+ reference this memory region in other parameters, e.g. ``-numa``,
+ ``-device nvdimm``, etc.
The ``size`` option provides the size of the memory region, and
- accepts common suffixes, eg ``500M``.
+ accepts common suffixes, e.g. ``500M``.
The ``mem-path`` provides the path to either a shared memory or
huge page filesystem mount.
HXCOMM This is the last statement. Insert new options before this line!
+
+#undef DEF
+#undef DEFHEADING
+#undef ARCHHEADING
projects / mirror_qemu.git / blobdiff