" 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"
+ " eager-split-size=n (KVM Eager Page Split chunk size, default 0, disabled. ARM only)\n"
" notify-vmexit=run|internal-error|disable,notify-window=n (enable notify VM exit and set notify window, x86 only)\n"
" thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
SRST
is disabled (dirty-ring-size=0). When enabled, KVM will instead
record dirty pages in a bitmap.
+ ``eager-split-size=n``
+ KVM implements dirty page logging at the PAGE_SIZE granularity and
+ enabling dirty-logging on a huge-page requires breaking it into
+ PAGE_SIZE pages in the first place. KVM on ARM does this splitting
+ lazily by default. There are performance benefits in doing huge-page
+ split eagerly, especially in situations where TLBI costs associated
+ with break-before-make sequences are considerable and also if guest
+ workloads are read intensive. The size here specifies how many pages
+ to break at a time and needs to be a valid block size which is
+ 1GB/2MB/4KB, 32MB/16KB and 512MB/64KB for 4KB/16KB/64KB PAGE_SIZE
+ respectively. Be wary of specifying a higher size as it will have an
+ impact on the memory. By default, this feature is disabled
+ (eager-split-size=0).
+
``notify-vmexit=run|internal-error|disable,notify-window=n``
Enables or disables notify VM exit support on x86 host and specify
the corresponding notify window to trigger the VM exit if enabled.
ERST
DEF("smp", HAS_ARG, QEMU_OPTION_smp,
- "-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,clusters=clusters][,cores=cores][,threads=threads]\n"
+ "-smp [[cpus=]n][,maxcpus=maxcpus][,drawers=drawers][,books=books][,sockets=sockets]\n"
+ " [,dies=dies][,clusters=clusters][,cores=cores][,threads=threads]\n"
" set the number of initial CPUs to 'n' [default=1]\n"
" maxcpus= maximum number of total CPUs, including\n"
" offline CPUs for hotplug, etc\n"
- " sockets= number of sockets on the machine board\n"
+ " drawers= number of drawers on the machine board\n"
+ " books= number of books in one drawer\n"
+ " sockets= number of sockets in one book\n"
" dies= number of dies in one socket\n"
" clusters= number of clusters in one die\n"
" cores= number of cores in one cluster\n"
ERST
-HXCOMM Deprecated by -audiodev
-DEF("audio-help", 0, QEMU_OPTION_audio_help,
- "-audio-help show -audiodev equivalent of the currently specified audio settings\n",
- QEMU_ARCH_ALL)
-SRST
-``-audio-help``
- Will show the -audiodev equivalent of the currently specified
- (deprecated) environment variables.
-ERST
-
DEF("audio", HAS_ARG, QEMU_OPTION_audio,
+ "-audio [driver=]driver[,prop[=value][,...]]\n"
+ " specifies default audio backend when `audiodev` is not\n"
+ " used to create a machine or sound device;"
+ " options are the same as for -audiodev\n"
"-audio [driver=]driver,model=value[,prop[=value][,...]]\n"
" specifies the audio backend and device to use;\n"
" apart from 'model', options are the same as for -audiodev.\n"
" use '-audio model=help' to show possible devices.\n",
QEMU_ARCH_ALL)
SRST
-``-audio [driver=]driver,model=value[,prop[=value][,...]]``
- This option is a shortcut for configuring both the guest audio
- hardware and the host audio backend in one go.
- The driver option is the same as with the corresponding ``-audiodev`` option below.
- The guest hardware model can be set with ``model=modelname``.
-
- Use ``driver=help`` to list the available drivers,
- and ``model=help`` to list the available device types.
+``-audio [driver=]driver[,model=value][,prop[=value][,...]]``
+ If the ``model`` option is specified, ``-audio`` is a shortcut
+ for configuring both the guest audio hardware and the host audio
+ backend in one go. The guest hardware model can be set with
+ ``model=modelname``. Use ``model=help`` to list the available
+ device types.
The following two example do exactly the same, to show how ``-audio``
can be used to shorten the command line length:
|qemu_system| -audiodev pa,id=pa -device sb16,audiodev=pa
|qemu_system| -audio pa,model=sb16
+
+ If the ``model`` option is not specified, ``-audio`` is used to
+ configure a default audio backend that will be used whenever the
+ ``audiodev`` property is not set on a device or machine. In
+ particular, ``-audio none`` ensures that no audio is produced even
+ for machines that have embedded sound hardware.
+
+ In both cases, the driver option is the same as with the corresponding
+ ``-audiodev`` option below. Use ``driver=help`` to list the available
+ drivers.
+
ERST
DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
ERST
DEF("hda", HAS_ARG, QEMU_OPTION_hda,
- "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
+ "-hda/-hdb file use 'file' as hard disk 0/1 image\n", QEMU_ARCH_ALL)
DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
- "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
+ "-hdc/-hdd file use 'file' as hard disk 2/3 image\n", QEMU_ARCH_ALL)
DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
SRST
``-hda file``
``-hdc file``
\
``-hdd file``
- Use file as hard disk 0, 1, 2 or 3 image (see the :ref:`disk images`
- chapter in the System Emulation Users Guide).
+ Use file as hard disk 0, 1, 2 or 3 image on the default bus of the
+ emulated machine (this is for example the IDE bus on most x86 machines,
+ but it can also be SCSI, virtio or something else on other target
+ architectures). See also the :ref:`disk images` chapter in the System
+ Emulation Users Guide.
ERST
DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
- "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
+ "-cdrom file use 'file' as CD-ROM image\n",
QEMU_ARCH_ALL)
SRST
``-cdrom file``
- Use file as CD-ROM image (you cannot use ``-hdc`` and ``-cdrom`` at
- the same time). You can use the host CD-ROM by using ``/dev/cdrom``
- as filename.
+ Use file as CD-ROM image on the default bus of the emulated machine
+ (which is IDE1 master on x86, so you cannot use ``-hdc`` and ``-cdrom``
+ at the same time there). On systems that support it, you can use the
+ host CD-ROM by using ``/dev/cdrom`` as filename.
ERST
DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
" VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
" netmap device, defaults to '/dev/netmap')\n"
#endif
+#ifdef CONFIG_AF_XDP
+ "-netdev af-xdp,id=str,ifname=name[,mode=native|skb][,force-copy=on|off]\n"
+ " [,queues=n][,start-queue=m][,inhibit=on|off][,sock-fds=x:y:...:z]\n"
+ " attach to the existing network interface 'name' with AF_XDP socket\n"
+ " use 'mode=MODE' to specify an XDP program attach mode\n"
+ " use 'force-copy=on|off' to force XDP copy mode even if device supports zero-copy (default: off)\n"
+ " use 'inhibit=on|off' to inhibit loading of a default XDP program (default: off)\n"
+ " with inhibit=on,\n"
+ " use 'sock-fds' to provide file descriptors for already open AF_XDP sockets\n"
+ " added to a socket map in XDP program. One socket per queue.\n"
+ " use 'queues=n' to specify how many queues of a multiqueue interface should be used\n"
+ " use 'start-queue=m' to specify the first queue that should be used\n"
+#endif
#ifdef CONFIG_POSIX
"-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
" configure a vhost-user network, backed by a chardev 'dev'\n"
#ifdef CONFIG_NETMAP
"netmap|"
#endif
+#ifdef CONFIG_AF_XDP
+ "af-xdp|"
+#endif
#ifdef CONFIG_POSIX
"vhost-user|"
#endif
#ifdef CONFIG_NETMAP
"netmap|"
#endif
+#ifdef CONFIG_AF_XDP
+ "af-xdp|"
+#endif
#ifdef CONFIG_VMNET
"vmnet-host|vmnet-shared|vmnet-bridged|"
#endif
" old way to initialize a host network interface\n"
" (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
SRST
-``-nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]``
+``-nic [tap|bridge|user|l2tpv3|vde|netmap|af-xdp|vhost-user|socket][,...][,mac=macaddr][,model=mn]``
This option is a shortcut for configuring both the on-board
(default) guest NIC hardware and the host network backend in one go.
The host backend options are the same as with the corresponding
# launch QEMU instance
|qemu_system| linux.img -nic vde,sock=/tmp/myswitch
+``-netdev af-xdp,id=str,ifname=name[,mode=native|skb][,force-copy=on|off][,queues=n][,start-queue=m][,inhibit=on|off][,sock-fds=x:y:...:z]``
+ Configure AF_XDP backend to connect to a network interface 'name'
+ using AF_XDP socket. A specific program attach mode for a default
+ XDP program can be forced with 'mode', defaults to best-effort,
+ where the likely most performant mode will be in use. Number of queues
+ 'n' should generally match the number or queues in the interface,
+ defaults to 1. Traffic arriving on non-configured device queues will
+ not be delivered to the network backend.
+
+ .. parsed-literal::
+
+ # set number of queues to 4
+ ethtool -L eth0 combined 4
+ # launch QEMU instance
+ |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \\
+ -netdev af-xdp,id=n1,ifname=eth0,queues=4
+
+ 'start-queue' option can be specified if a particular range of queues
+ [m, m + n] should be in use. For example, this is may be necessary in
+ order to use certain NICs in native mode. Kernel allows the driver to
+ create a separate set of XDP queues on top of regular ones, and only
+ these queues can be used for AF_XDP sockets. NICs that work this way
+ may also require an additional traffic redirection with ethtool to these
+ special queues.
+
+ .. parsed-literal::
+
+ # set number of queues to 1
+ ethtool -L eth0 combined 1
+ # redirect all the traffic to the second queue (id: 1)
+ # note: drivers may require non-empty key/mask pair.
+ ethtool -N eth0 flow-type ether \\
+ dst 00:00:00:00:00:00 m FF:FF:FF:FF:FF:FE action 1
+ ethtool -N eth0 flow-type ether \\
+ dst 00:00:00:00:00:01 m FF:FF:FF:FF:FF:FE action 1
+ # launch QEMU instance
+ |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \\
+ -netdev af-xdp,id=n1,ifname=eth0,queues=1,start-queue=1
+
+ XDP program can also be loaded externally. In this case 'inhibit' option
+ should be set to 'on' and 'sock-fds' provided with file descriptors for
+ already open but not bound XDP sockets already added to a socket map for
+ corresponding queues. One socket per queue.
+
+ .. parsed-literal::
+
+ |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \\
+ -netdev af-xdp,id=n1,ifname=eth0,queues=3,inhibit=on,sock-fds=15:16:17
+
``-netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]``
Establish a vhost-user netdev, backed by a chardev id. The chardev
should be a unix domain socket backed one. The vhost-user uses a
" prepare for incoming migration, listen on\n" \
" specified protocol and socket address\n" \
"-incoming fd:fd\n" \
+ "-incoming file:filename[,offset=offset]\n" \
"-incoming exec:cmdline\n" \
" accept incoming migration on given file descriptor\n" \
" or from given external command\n" \
Prepare for incoming migration, listen on a given unix socket.
``-incoming fd:fd``
- Accept incoming migration from a given filedescriptor.
+ Accept incoming migration from a given file descriptor.
+
+``-incoming file:filename[,offset=offset]``
+ Accept incoming migration from a given file starting at offset.
+ offset allows the common size suffixes, or a 0x prefix, but not both.
``-incoming exec:cmdline``
Accept incoming migration as an output from specified external
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,offset=offset,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,rom=on|off|auto``
Creates a memory file backend object, which can be used to back
the guest RAM with huge pages.
The ``readonly`` option specifies whether the backing file is opened
read-only or read-write (default).
+ The ``rom`` option specifies whether to create Read Only Memory
+ (ROM) that cannot be modified by the VM. Any write attempts to such
+ ROM will be denied. Most use cases want proper RAM instead of ROM.
+ However, selected use cases, like R/O NVDIMMs, can benefit from
+ ROM. If set to ``on``, create ROM; if set to ``off``, create
+ writable RAM; if set to ``auto`` (default), the value of the
+ ``readonly`` option is used. This option is primarily helpful when
+ we want to have writable RAM in configurations that would
+ traditionally create ROM before the ``rom`` option was introduced:
+ VM templating, where we want to open a file readonly
+ (``readonly=on``) and mark the memory to be private for QEMU
+ (``share=off``). For this use case, we need writable RAM instead
+ of ROM, and want to also set ``rom=off``.
+
``-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
projects / mirror_qemu.git / blobdiff