qemu/qemu-options.hx
Richard Henderson d74ec4d7dd trivial patches for 2024-07-17
-----BEGIN PGP SIGNATURE-----
 
 iQEzBAABCAAdFiEEe3O61ovnosKJMUsicBtPaxppPlkFAmaXpakACgkQcBtPaxpp
 Plnvvwf8DdybFjyhAVmiG6+6WhB5s0hJhZRiWzUY6ieMbgPzCUgWzfr/pJh6q44x
 rw+aVfe2kf1ysycx3DjcJpucrC1rQD/qV6dB3IA1rxidBOZfCb8iZwoaB6yS9Epp
 4uXIdfje4zO6oCMN17MTXvuQIEUK3ZHN0EQOs7vsA2d8/pHqBqRoixjz9KnKHlpk
 P6kyIXceZ4wLAtwFJqa/mBBRnpcSdaWuQpzpBsg1E3BXRXXfeuXJ8WmGp0kEOpzQ
 k7+2sPpuah2z7D+jNFBW0+3ZYDvO9Z4pomQ4al4w+DHDyWBF49WnnSdDSDbWwxI5
 K0vUlsDVU8yTnIEgN8BL82F8eub5Ug==
 =ZYHJ
 -----END PGP SIGNATURE-----

Merge tag 'pull-trivial-patches' of https://gitlab.com/mjt0k/qemu into staging

trivial patches for 2024-07-17

# -----BEGIN PGP SIGNATURE-----
#
# iQEzBAABCAAdFiEEe3O61ovnosKJMUsicBtPaxppPlkFAmaXpakACgkQcBtPaxpp
# Plnvvwf8DdybFjyhAVmiG6+6WhB5s0hJhZRiWzUY6ieMbgPzCUgWzfr/pJh6q44x
# rw+aVfe2kf1ysycx3DjcJpucrC1rQD/qV6dB3IA1rxidBOZfCb8iZwoaB6yS9Epp
# 4uXIdfje4zO6oCMN17MTXvuQIEUK3ZHN0EQOs7vsA2d8/pHqBqRoixjz9KnKHlpk
# P6kyIXceZ4wLAtwFJqa/mBBRnpcSdaWuQpzpBsg1E3BXRXXfeuXJ8WmGp0kEOpzQ
# k7+2sPpuah2z7D+jNFBW0+3ZYDvO9Z4pomQ4al4w+DHDyWBF49WnnSdDSDbWwxI5
# K0vUlsDVU8yTnIEgN8BL82F8eub5Ug==
# =ZYHJ
# -----END PGP SIGNATURE-----
# gpg: Signature made Wed 17 Jul 2024 09:06:17 PM AEST
# gpg:                using RSA key 7B73BAD68BE7A2C289314B22701B4F6B1A693E59
# gpg: Good signature from "Michael Tokarev <mjt@tls.msk.ru>" [full]
# gpg:                 aka "Michael Tokarev <mjt@debian.org>" [full]
# gpg:                 aka "Michael Tokarev <mjt@corpit.ru>" [full]

* tag 'pull-trivial-patches' of https://gitlab.com/mjt0k/qemu:
  meson: Update meson-buildoptions.sh
  backends/rng-random: Get rid of qemu_open_old()
  backends/iommufd: Get rid of qemu_open_old()
  backends/hostmem-epc: Get rid of qemu_open_old()
  hw/vfio/container: Get rid of qemu_open_old()
  hw/usb/u2f-passthru: Get rid of qemu_open_old()
  hw/usb/host-libusb: Get rid of qemu_open_old()
  hw/i386/sgx: Get rid of qemu_open_old()
  tests/avocado: Remove the non-working virtio_check_params test
  doc/net/l2tpv3: Update boolean fields' description to avoid short-form use
  target/hexagon/imported/mmvec: Fix superfluous trailing semicolon
  util/oslib-posix: Fix superfluous trailing semicolon
  hw/i386/x86: Fix superfluous trailing semicolon
  accel/kvm/kvm-all: Fix superfluous trailing semicolon
  README.rst: add the missing punctuations
  block/curl: rewrite http header parsing function

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2024-07-18 10:07:23 +10:00

5901 lines
253 KiB
Haxe

HXCOMM See docs/devel/docs.rst for the format of this file.
HXCOMM
HXCOMM Use DEFHEADING() to define headings in both help text and rST.
HXCOMM Text between SRST and ERST is copied to the rST version and
HXCOMM discarded from C version.
HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
HXCOMM construct option structures, enums and help message for specified
HXCOMM architectures.
HXCOMM HXCOMM can be used for comments, discarded from both rST and C.
DEFHEADING(Standard options:)
DEF("help", 0, QEMU_OPTION_h,
"-h or -help display this help and exit\n", QEMU_ARCH_ALL)
SRST
``-h``
Display help and exit
ERST
DEF("version", 0, QEMU_OPTION_version,
"-version display version information and exit\n", QEMU_ARCH_ALL)
SRST
``-version``
Display version information and exit
ERST
DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
"-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, 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"
" aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
" dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
" 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"
" memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n"
" cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\n",
QEMU_ARCH_ALL)
SRST
``-machine [type=]name[,prop=value[,...]]``
Select the emulated machine by name. Use ``-machine help`` to list
available machines.
For architectures which aim to support live migration compatibility
across releases, each release will introduce a new versioned machine
type. For example, the 2.8.0 release introduced machine types
"pc-i440fx-2.8" and "pc-q35-2.8" for the x86\_64/i686 architectures.
To allow live migration of guests from QEMU version 2.8.0, to QEMU
version 2.9.0, the 2.9.0 version must support the "pc-i440fx-2.8"
and "pc-q35-2.8" machines too. To allow users live migrating VMs to
skip multiple intermediate releases when upgrading, new releases of
QEMU will support machine types from many previous versions.
Supported machine properties are:
``accel=accels1[:accels2[:...]]``
This is used to enable an accelerator. Depending on the target
architecture, kvm, xen, 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.
``vmport=on|off|auto``
Enables emulation of VMWare IO port, for vmmouse etc. auto says
to select the value based on accel. For accel=xen the default is
off otherwise the default is on.
``dump-guest-core=on|off``
Include guest memory in a core dump. The default is on.
``mem-merge=on|off``
Enables or disables memory merge support. This feature, when
supported by the host, de-duplicates identical memory pages
among VMs instances (enabled by default).
``aes-key-wrap=on|off``
Enables or disables AES key wrapping support on s390-ccw hosts.
This feature controls whether AES wrapping keys will be created
to allow execution of AES cryptographic functions. The default
is on.
``dea-key-wrap=on|off``
Enables or disables DEA key wrapping support on s390-ccw hosts.
This feature controls whether DEA wrapping keys will be created
to allow execution of DEA cryptographic functions. The default
is on.
``nvdimm=on|off``
Enables or disables NVDIMM support. The default is off.
``memory-encryption=``
Memory encryption object to use. The default is none.
``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:
* 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
``cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]``
Define a CXL Fixed Memory Window (CFMW).
Described in the CXL 2.0 ECN: CEDT CFMWS & QTG _DSM.
They are regions of Host Physical Addresses (HPA) on a system which
may be interleaved across one or more CXL host bridges. The system
software will assign particular devices into these windows and
configure the downstream Host-managed Device Memory (HDM) decoders
in root ports, switch ports and devices appropriately to meet the
interleave requirements before enabling the memory devices.
``targets.X=target`` provides the mapping to CXL host bridges
which may be identified by the id provided in the -device entry.
Multiple entries are needed to specify all the targets when
the fixed memory window represents interleaved memory. X is the
target index from 0.
``size=size`` sets the size of the CFMW. This must be a multiple of
256MiB. The region will be aligned to 256MiB but the location is
platform and configuration dependent.
``interleave-granularity=granularity`` sets the granularity of
interleave. Default 256 (bytes). Only 256, 512, 1k, 2k,
4k, 8k and 16k granularities supported.
Example:
::
-machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
ERST
DEF("M", HAS_ARG, QEMU_OPTION_M,
" sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n",
QEMU_ARCH_ALL)
SRST
``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
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)
SRST
``-cpu model``
Select CPU model (``-cpu help`` for list and additional feature
selection)
ERST
DEF("accel", HAS_ARG, QEMU_OPTION_accel,
"-accel [accel=]accelerator[,prop[=value][,...]]\n"
" select accelerator (kvm, xen, 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"
" 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"
" 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"
" device=path (KVM device path, default /dev/kvm)\n", QEMU_ARCH_ALL)
SRST
``-accel name[,prop=value[,...]]``
This is used to enable an accelerator. Depending on the target
architecture, kvm, xen, 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.
``igd-passthru=on|off``
When Xen is in use, this option controls whether Intel
integrated graphics devices can be passed through to the guest
(default=off)
``kernel-irqchip=on|off|split``
Controls KVM in-kernel irqchip support. The default is full
acceleration of the interrupt controllers. On x86, split irqchip
reduces the kernel attack surface, at a performance cost for
non-MSI interrupts. Disabling the in-kernel irqchip completely
is not recommended except for debugging purposes.
``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
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.
``thread=single|multi``
Controls number of TCG threads. When the TCG is multi-threaded
there will be one thread per vCPU therefore taking advantage of
additional host cores. The default is to enable multi-threading
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.
``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.
``run`` option enables the feature. It does nothing and continue
if the exit happens. ``internal-error`` option enables the feature.
It raises a internal error. ``disable`` option doesn't enable the feature.
This feature can mitigate the CPU stuck issue due to event windows don't
open up for a specified of time (i.e. notify-window).
Default: notify-vmexit=run,notify-window=0.
``device=path``
Sets the path to the KVM device node. Defaults to ``/dev/kvm``. This
option can be used to pass the KVM device to use via a file descriptor
by setting the value to ``/dev/fdset/NN``.
ERST
DEF("smp", HAS_ARG, QEMU_OPTION_smp,
"-smp [[cpus=]n][,maxcpus=maxcpus][,drawers=drawers][,books=books][,sockets=sockets]\n"
" [,dies=dies][,clusters=clusters][,modules=modules][,cores=cores]\n"
" [,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"
" 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"
" modules= number of modules in one cluster\n"
" cores= number of cores in one module\n"
" threads= number of threads in one core\n"
"Note: Different machines may have different subsets of the CPU topology\n"
" parameters supported, so the actual meaning of the supported parameters\n"
" will vary accordingly. For example, for a machine type that supports a\n"
" three-level CPU hierarchy of sockets/cores/threads, the parameters will\n"
" sequentially mean as below:\n"
" sockets means the number of sockets on the machine board\n"
" cores means the number of cores in one socket\n"
" threads means the number of threads in one core\n"
" For a particular machine type board, an expected CPU topology hierarchy\n"
" can be defined through the supported sub-option. Unsupported parameters\n"
" can also be provided in addition to the sub-option, but their values\n"
" must be set as 1 in the purpose of correct parsing.\n",
QEMU_ARCH_ALL)
SRST
``-smp [[cpus=]n][,maxcpus=maxcpus][,drawers=drawers][,books=books][,sockets=sockets][,dies=dies][,clusters=clusters][,modules=modules][,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. Product of the
CPU topology hierarchy must be equal to the maximum number of CPUs.
Both parameters are subject to an upper limit that is determined by
the specific machine type chosen.
To control reporting of CPU topology information, values of the topology
parameters can be specified. Machines may only support a subset of the
parameters and different machines may have different subsets supported
which vary depending on capacity of the corresponding CPU targets. So
for a particular machine type board, an expected topology hierarchy can
be defined through the supported sub-option. Unsupported parameters can
also be provided in addition to the sub-option, but their values must be
set as 1 in the purpose of correct parsing.
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.
For example, the following sub-option defines a CPU topology hierarchy
(2 sockets totally on the machine, 2 cores per socket, 2 threads per
core) for a machine that only supports sockets/cores/threads.
Some members of the option can be omitted but their values will be
automatically computed:
::
-smp 8,sockets=2,cores=2,threads=2,maxcpus=8
The following sub-option defines a CPU topology hierarchy (2 sockets
totally on the machine, 2 dies per socket, 2 modules per die, 2 cores per
module, 2 threads per core) for PC machines which support sockets/dies
/modules/cores/threads. Some members of the option can be omitted but
their values will be automatically computed:
::
-smp 32,sockets=2,dies=2,modules=2,cores=2,threads=2,maxcpus=32
The following sub-option defines a CPU topology hierarchy (2 sockets
totally on the machine, 2 clusters per socket, 2 cores per cluster,
2 threads per core) for ARM virt machines which support sockets/clusters
/cores/threads. Some members of the option can be omitted but their values
will be automatically computed:
::
-smp 16,sockets=2,clusters=2,cores=2,threads=2,maxcpus=16
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.
For example, the following option defines a machine board with 2 sockets
of 1 core before 6.2 and 1 socket of 2 cores after 6.2:
::
-smp 2
Note: The cluster topology will only be generated in ACPI and exposed
to guest if it's explicitly specified in -smp.
ERST
DEF("numa", HAS_ARG, QEMU_OPTION_numa,
"-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
"-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
"-numa dist,src=source,dst=destination,val=distance\n"
"-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n"
"-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]\n"
"-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]\n",
QEMU_ARCH_ALL)
SRST
``-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
\
``-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
\
``-numa dist,src=source,dst=destination,val=distance``
\
``-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]``
\
``-numa hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=type[,latency=lat][,bandwidth=bw]``
\
``-numa hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]``
Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
distance from a source node to a destination node. Set the ACPI
Heterogeneous Memory Attributes for the given nodes.
Legacy VCPU assignment uses '\ ``cpus``\ ' option where firstcpu and
lastcpu are CPU indexes. Each '\ ``cpus``\ ' option represent a
contiguous range of CPU indexes (or a single VCPU if lastcpu is
omitted). A non-contiguous set of VCPUs can be represented by
providing multiple '\ ``cpus``\ ' options. If '\ ``cpus``\ ' is
omitted on all nodes, VCPUs are automatically split between them.
For example, the following option assigns VCPUs 0, 1, 2 and 5 to a
NUMA node:
::
-numa node,cpus=0-2,cpus=5
'\ ``cpu``\ ' option is a new alternative to '\ ``cpus``\ ' option
which uses '\ ``socket-id|core-id|thread-id``\ ' properties to
assign CPU objects to a node using topology layout properties of
CPU. The set of properties is machine specific, and depends on used
machine type/'\ ``smp``\ ' options. It could be queried with
'\ ``hotpluggable-cpus``\ ' monitor command. '\ ``node-id``\ '
property specifies node to which CPU object will be assigned, it's
required for node to be declared with '\ ``node``\ ' option before
it's used with '\ ``cpu``\ ' option.
For example:
::
-M pc \
-smp 1,sockets=2,maxcpus=2 \
-numa node,nodeid=0 -numa node,nodeid=1 \
-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
'\ ``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.
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
largest bandwidth) to this NUMA node. Note that this option can be
set only when the machine property 'hmat' is set to 'on'.
Following example creates a machine with 2 NUMA nodes, node 0 has
CPU. node 1 has only memory, and its initiator is node 0. Note that
because node 0 has CPU, by default the initiator of node 0 is itself
and must be itself.
::
-machine hmat=on \
-m 2G,slots=2,maxmem=4G \
-object memory-backend-ram,size=1G,id=m0 \
-object memory-backend-ram,size=1G,id=m1 \
-numa node,nodeid=0,memdev=m0 \
-numa node,nodeid=1,memdev=m1,initiator=0 \
-smp 2,sockets=2,maxcpus=2 \
-numa cpu,node-id=0,socket-id=0 \
-numa cpu,node-id=0,socket-id=1
source and destination are NUMA node IDs. distance is the NUMA
distance from source to destination. The distance from a node to
itself is always 10. If any pair of nodes is given a distance, then
all pairs must be given distances. Although, when distances are only
given in one direction for each pair of nodes, then the distances in
the opposite directions are assumed to be the same. If, however, an
asymmetrical pair of distances is given for even one node pair, then
all node pairs must be provided distance values for both directions,
even when they are symmetrical. When a node is unreachable from
another node, set the pair's distance to 255.
Note that the -``numa`` option doesn't allocate any of the specified
resources, it just assigns existing resources to NUMA nodes. This
means that one still has to use the ``-m``, ``-smp`` options to
allocate RAM and VCPUs respectively.
Use '\ ``hmat-lb``\ ' to set System Locality Latency and Bandwidth
Information between initiator and target NUMA nodes in ACPI
Heterogeneous Attribute Memory Table (HMAT). Initiator NUMA node can
create memory requests, usually it has one or more processors.
Target NUMA node contains addressable memory.
In '\ ``hmat-lb``\ ' option, node are NUMA node IDs. hierarchy is
the memory hierarchy of the target NUMA node: if hierarchy is
'memory', the structure represents the memory performance; if
hierarchy is 'first-level\|second-level\|third-level', this
structure represents aggregated performance of memory side caches
for each domain. type of 'data-type' is type of data represented by
this structure instance: if 'hierarchy' is 'memory', 'data-type' is
'access\|read\|write' latency or 'access\|read\|write' bandwidth of
the target memory; if 'hierarchy' is
'first-level\|second-level\|third-level', 'data-type' is
'access\|read\|write' hit latency or 'access\|read\|write' hit
bandwidth of the target memory side cache.
lat is latency value in nanoseconds. bw is bandwidth value, the
possible value and units are NUM[M\|G\|T], mean that the bandwidth
value are NUM byte per second (or MB/s, GB/s or TB/s depending on
used suffix). Note that if latency or bandwidth value is 0, means
the corresponding latency or bandwidth information is not provided.
In '\ ``hmat-cache``\ ' option, node-id is the NUMA-id of the memory
belongs. size is the size of memory side cache in bytes. level is
the cache level described in this structure, note that the cache
level 0 should not be used with '\ ``hmat-cache``\ ' option.
associativity is the cache associativity, the possible value is
'none/direct(direct-mapped)/complex(complex cache indexing)'. policy
is the write policy. line is the cache Line size in bytes.
For example, the following options describe 2 NUMA nodes. Node 0 has
2 cpus and a ram, node 1 has only a ram. The processors in node 0
access memory in node 0 with access-latency 5 nanoseconds,
access-bandwidth is 200 MB/s; The processors in NUMA node 0 access
memory in NUMA node 1 with access-latency 10 nanoseconds,
access-bandwidth is 100 MB/s. And for memory side cache information,
NUMA node 0 and 1 both have 1 level memory cache, size is 10KB,
policy is write-back, the cache Line size is 8 bytes:
::
-machine hmat=on \
-m 2G \
-object memory-backend-ram,size=1G,id=m0 \
-object memory-backend-ram,size=1G,id=m1 \
-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 \
-numa cpu,node-id=0,socket-id=1 \
-numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
-numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
-numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
-numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
-numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
-numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
ERST
DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
"-add-fd fd=fd,set=set[,opaque=opaque]\n"
" Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
SRST
``-add-fd fd=fd,set=set[,opaque=opaque]``
Add a file descriptor to an fd set. Valid options are:
``fd=fd``
This option defines the file descriptor of which a duplicate is
added to fd set. The file descriptor cannot be stdin, stdout, or
stderr.
``set=set``
This option defines the ID of the fd set to add the file
descriptor to.
``opaque=opaque``
This option defines a free-form string that can be used to
describe fd.
You can open an image using pre-opened file descriptors from an fd
set:
.. parsed-literal::
|qemu_system| \\
-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \\
-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \\
-drive file=/dev/fdset/2,index=0,media=disk
ERST
DEF("set", HAS_ARG, QEMU_OPTION_set,
"-set group.id.arg=value\n"
" set <arg> parameter for item <id> of type <group>\n"
" i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
SRST
``-set group.id.arg=value``
Set parameter arg for item id of type group
ERST
DEF("global", HAS_ARG, QEMU_OPTION_global,
"-global driver.property=value\n"
"-global driver=driver,property=property,value=value\n"
" set a global default for a driver property\n",
QEMU_ARCH_ALL)
SRST
``-global driver.prop=value``
\
``-global driver=driver,property=property,value=value``
Set default value of driver's property prop to value, e.g.:
.. parsed-literal::
|qemu_system_x86| -global ide-hd.physical_block_size=4096 disk-image.img
In particular, you can use this to set driver properties for devices
which are created automatically by the machine model. To create a
device which is not created automatically and set properties on it,
use -``device``.
-global driver.prop=value is shorthand for -global
driver=driver,property=prop,value=value. The longhand syntax works
even when driver contains a dot.
ERST
DEF("boot", HAS_ARG, QEMU_OPTION_boot,
"-boot [order=drives][,once=drives][,menu=on|off]\n"
" [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
" 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
" 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
" 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
" 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
QEMU_ARCH_ALL)
SRST
``-boot [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off]``
Specify boot order drives as a string of drive letters. Valid drive
letters depend on the target architecture. The x86 PC uses: a, b
(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p
(Etherboot from network adapter 1-4), hard disk boot is the default.
To apply a particular boot order only on the first startup, specify
it via ``once``. Note that the ``order`` or ``once`` parameter
should not be used together with the ``bootindex`` property of
devices, since the firmware implementations normally do not support
both at the same time.
Interactive boot menus/prompts can be enabled via ``menu=on`` as far
as firmware/BIOS supports them. The default is non-interactive boot.
A splash picture could be passed to bios, enabling user to show it
as logo, when option splash=sp\_name is given and menu=on, If
firmware/BIOS supports them. Currently Seabios for X86 system
support it. limitation: The splash file could be a jpeg file or a
BMP file in 24 BPP format(true color). The resolution should be
supported by the SVGA mode, so the recommended is 320x240, 640x480,
800x640.
A timeout could be passed to bios, guest will pause for rb\_timeout
ms when boot failed, then reboot. If rb\_timeout is '-1', guest will
not reboot, qemu passes '-1' to bios by default. Currently Seabios
for X86 system support it.
Do strict boot via ``strict=on`` as far as firmware/BIOS supports
it. This only effects when boot priority is changed by bootindex
options. The default is non-strict boot.
.. parsed-literal::
# try to boot from network first, then from hard disk
|qemu_system_x86| -boot order=nc
# boot from CD-ROM first, switch back to default order after reboot
|qemu_system_x86| -boot once=d
# boot with a splash picture for 5 seconds.
|qemu_system_x86| -boot menu=on,splash=/root/boot.bmp,splash-time=5000
Note: The legacy format '-boot drives' is still supported but its
use is discouraged as it may be removed from future versions.
ERST
DEF("m", HAS_ARG, QEMU_OPTION_m,
"-m [size=]megs[,slots=n,maxmem=size]\n"
" configure guest RAM\n"
" size: initial amount of guest memory\n"
" slots: number of hotplug slots (default: none)\n"
" maxmem: maximum amount of guest memory (default: none)\n"
" Note: Some architectures might enforce a specific granularity\n",
QEMU_ARCH_ALL)
SRST
``-m [size=]megs[,slots=n,maxmem=size]``
Sets guest startup RAM size to megs megabytes. Default is 128 MiB.
Optionally, a suffix of "M" or "G" can be used to signify a value in
megabytes or gigabytes respectively. Optional pair slots, maxmem
could be used to set amount of hotpluggable memory slots and maximum
amount of memory. Note that maxmem must be aligned to the page size.
For example, the following command-line sets the guest startup RAM
size to 1GB, creates 3 slots to hotplug additional memory and sets
the maximum memory the guest can reach to 4GB:
.. parsed-literal::
|qemu_system| -m 1G,slots=3,maxmem=4G
If slots and maxmem are not specified, memory hotplug won't be
enabled and the guest startup RAM will never increase.
ERST
DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
"-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
SRST
``-mem-path path``
Allocate guest RAM from a temporarily created file in path.
ERST
DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
"-mem-prealloc preallocate guest memory (use with -mem-path)\n",
QEMU_ARCH_ALL)
SRST
``-mem-prealloc``
Preallocate memory when using -mem-path.
ERST
DEF("k", HAS_ARG, QEMU_OPTION_k,
"-k language use keyboard layout (for example 'fr' for French)\n",
QEMU_ARCH_ALL)
SRST
``-k language``
Use keyboard layout language (for example ``fr`` for French). This
option is only needed where it is not easy to get raw PC keycodes
(e.g. on Macs, with some X11 servers or with a VNC or curses
display). You don't normally need to use it on PC/Linux or
PC/Windows hosts.
The available layouts are:
::
ar de-ch es fo fr-ca hu ja mk no pt-br sv
da en-gb et fr fr-ch is lt nl pl ru th
de en-us fi fr-be hr it lv nl-be pt sl tr
The default is ``en-us``.
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][,...]]``
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:
.. parsed-literal::
|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,
"-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
" specifies the audio backend to use\n"
" Use ``-audiodev help`` to list the available drivers\n"
" id= identifier of the backend\n"
" timer-period= timer period in microseconds\n"
" in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n"
" in|out.fixed-settings= use fixed settings for host audio\n"
" in|out.frequency= frequency to use with fixed settings\n"
" in|out.channels= number of channels to use with fixed settings\n"
" in|out.format= sample format to use with fixed settings\n"
" valid values: s8, s16, s32, u8, u16, u32, f32\n"
" in|out.voices= number of voices to use\n"
" in|out.buffer-length= length of buffer in microseconds\n"
"-audiodev none,id=id,[,prop[=value][,...]]\n"
" dummy driver that discards all output\n"
#ifdef CONFIG_AUDIO_ALSA
"-audiodev alsa,id=id[,prop[=value][,...]]\n"
" in|out.dev= name of the audio device to use\n"
" in|out.period-length= length of period in microseconds\n"
" in|out.try-poll= attempt to use poll mode\n"
" threshold= threshold (in microseconds) when playback starts\n"
#endif
#ifdef CONFIG_AUDIO_COREAUDIO
"-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
" in|out.buffer-count= number of buffers\n"
#endif
#ifdef CONFIG_AUDIO_DSOUND
"-audiodev dsound,id=id[,prop[=value][,...]]\n"
" latency= add extra latency to playback in microseconds\n"
#endif
#ifdef CONFIG_AUDIO_OSS
"-audiodev oss,id=id[,prop[=value][,...]]\n"
" in|out.dev= path of the audio device to use\n"
" in|out.buffer-count= number of buffers\n"
" in|out.try-poll= attempt to use poll mode\n"
" try-mmap= try using memory mapped access\n"
" exclusive= open device in exclusive mode\n"
" dsp-policy= set timing policy (0..10), -1 to use fragment mode\n"
#endif
#ifdef CONFIG_AUDIO_PA
"-audiodev pa,id=id[,prop[=value][,...]]\n"
" server= PulseAudio server address\n"
" 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"
#endif
#ifdef CONFIG_AUDIO_SNDIO
"-audiodev sndio,id=id[,prop[=value][,...]]\n"
#endif
#ifdef CONFIG_SPICE
"-audiodev spice,id=id[,prop[=value][,...]]\n"
#endif
#ifdef CONFIG_DBUS_DISPLAY
"-audiodev dbus,id=id[,prop[=value][,...]]\n"
#endif
"-audiodev wav,id=id[,prop[=value][,...]]\n"
" path= path of wav file to record\n",
QEMU_ARCH_ALL)
SRST
``-audiodev [driver=]driver,id=id[,prop[=value][,...]]``
Adds a new audio backend driver identified by id. There are global
and driver specific properties. Some values can be set differently
for input and output, they're marked with ``in|out.``. You can set
the input's property with ``in.prop`` and the output's property with
``out.prop``. For example:
::
-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
NOTE: parameter validation is known to be incomplete, in many cases
specifying an invalid option causes QEMU to print an error message
and continue emulation without sound.
Valid global options are:
``id=identifier``
Identifies the audio backend.
``timer-period=period``
Sets the timer period used by the audio subsystem in
microseconds. Default is 10000 (10 ms).
``in|out.mixing-engine=on|off``
Use QEMU's mixing engine to mix all streams inside QEMU and
convert audio formats when not supported by the backend. When
off, fixed-settings must be off too. Note that disabling this
option means that the selected backend must support multiple
streams and the audio formats used by the virtual cards,
otherwise you'll get no sound. It's not recommended to disable
this option unless you want to use 5.1 or 7.1 audio, as mixing
engine only supports mono and stereo audio. Default is on.
``in|out.fixed-settings=on|off``
Use fixed settings for host audio. When off, it will change
based on how the guest opens the sound card. In this case you
must not specify frequency, channels or format. Default is on.
``in|out.frequency=frequency``
Specify the frequency to use when using fixed-settings. Default
is 44100Hz.
``in|out.channels=channels``
Specify the number of channels to use when using fixed-settings.
Default is 2 (stereo).
``in|out.format=format``
Specify the sample format to use when using fixed-settings.
Valid values are: ``s8``, ``s16``, ``s32``, ``u8``, ``u16``,
``u32``, ``f32``. Default is ``s16``.
``in|out.voices=voices``
Specify the number of voices to use. Default is 1.
``in|out.buffer-length=usecs``
Sets th