HXCOMM HXCOMM can be used for comments, discarded from both texi and C
DEFHEADING(Standard options:)
-STEXI
-@table @option
-ETEXI
DEF("help", 0, QEMU_OPTION_h,
"-h or -help display this help and exit\n", QEMU_ARCH_ALL)
-STEXI
-@item -h
-@findex -h
-Display help and exit
-ETEXI
+SRST
+``-h``
+ Display help and exit
+ERST
DEF("version", 0, QEMU_OPTION_version,
"-version display version information and exit\n", QEMU_ARCH_ALL)
-STEXI
-@item -version
-@findex -version
-Display version information and exit
-ETEXI
+SRST
+``-version``
+ Display version information and exit
+ERST
DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
"-machine [type=]name[,prop[=value][,...]]\n"
" suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
" nvdimm=on|off controls NVDIMM support (default=off)\n"
" enforce-config-section=on|off enforce configuration section migration (default=off)\n"
- " memory-encryption=@var{} memory encryption object to use (default=none)\n",
+ " memory-encryption=@var{} memory encryption object to use (default=none)\n"
+ " hmat=on|off controls ACPI HMAT support (default=off)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -machine [type=]@var{name}[,prop=@var{value}[,...]]
-@findex -machine
-Select the emulated machine by @var{name}. Use @code{-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:
-@table @option
-@item accel=@var{accels1}[:@var{accels2}[:...]]
-This is used to enable an accelerator. Depending on the target architecture,
-kvm, xen, hax, hvf, 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.
-@item 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.
-@item dump-guest-core=on|off
-Include guest memory in a core dump. The default is on.
-@item 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).
-@item 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.
-@item 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.
-@item nvdimm=on|off
-Enables or disables NVDIMM support. The default is off.
-@item enforce-config-section=on|off
-If @option{enforce-config-section} is set to @var{on}, force migration
-code to send configuration section even if the machine-type sets the
-@option{migration.send-configuration} property to @var{off}.
-NOTE: this parameter is deprecated. Please use @option{-global}
-@option{migration.send-configuration}=@var{on|off} instead.
-@item memory-encryption=@var{}
-Memory encryption object to use. The default is none.
-@end table
-ETEXI
+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, hax, hvf, 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.
+
+ ``enforce-config-section=on|off``
+ If ``enforce-config-section`` is set to on, force migration code
+ to send configuration section even if the machine-type sets the
+ ``migration.send-configuration`` property to off. NOTE: this
+ parameter is deprecated. Please use ``-global``
+ ``migration.send-configuration``\ =on\|off instead.
+
+ ``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.
+ERST
HXCOMM Deprecated by -machine
DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
"-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
-STEXI
-@item -cpu @var{model}
-@findex -cpu
-Select CPU model (@code{-cpu help} for list and additional feature selection)
-ETEXI
+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"
" kvm-shadow-mem=size of KVM shadow MMU in bytes\n"
" tb-size=n (TCG translation block cache size)\n"
" thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
-STEXI
-@item -accel @var{name}[,prop=@var{value}[,...]]
-@findex -accel
-This is used to enable an accelerator. Depending on the target architecture,
-kvm, xen, hax, hvf, 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.
-@table @option
-@item 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)
-@item 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.
-@item kvm-shadow-mem=size
-Defines the size of the KVM shadow MMU.
-@item tb-size=@var{n}
-Controls the size (in MiB) of the TCG translation block cache.
-@item thread=single|multi
-Controls number of TCG threads. When the TCG is multi-threaded there will be one
-thread per vCPU therefor 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).
-@end table
-ETEXI
+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
+ 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.
+
+ ``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 therefor 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).
+ERST
DEF("smp", HAS_ARG, QEMU_OPTION_smp,
"-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
" dies= number of CPU dies on one socket (for PC only)\n"
" sockets= number of discrete sockets in the system\n",
QEMU_ARCH_ALL)
-STEXI
-@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,dies=dies][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
-@findex -smp
-Simulate an SMP system with @var{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 @var{cores} per die, the number of @var{threads}
-per cores, the number of @var{dies} per packages and the total number of
-@var{sockets} can be specified. Missing values will be computed.
-If any on the three values is given, the total number of CPUs @var{n} can be omitted.
-@var{maxcpus} specifies the maximum number of hotpluggable CPUs.
-ETEXI
+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.
+ERST
DEF("numa", HAS_ARG, QEMU_OPTION_numa,
- "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
- "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n"
+ "-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 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)
-STEXI
-@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
-@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}]
-@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance}
-@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}]
-@findex -numa
-Define a NUMA node and assign RAM and VCPUs to it.
-Set the NUMA distance from a source node to a destination node.
-
-Legacy VCPU assignment uses @samp{cpus} option where
-@var{firstcpu} and @var{lastcpu} are CPU indexes. Each
-@samp{cpus} option represent a contiguous range of CPU indexes
-(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
-set of VCPUs can be represented by providing multiple @samp{cpus}
-options. If @samp{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:
-@example
--numa node,cpus=0-2,cpus=5
-@end example
-
-@samp{cpu} option is a new alternative to @samp{cpus} option
-which uses @samp{socket-id|core-id|thread-id} properties to assign
-CPU objects to a @var{node} using topology layout properties of CPU.
-The set of properties is machine specific, and depends on used
-machine type/@samp{smp} options. It could be queried with
-@samp{hotpluggable-cpus} monitor command.
-@samp{node-id} property specifies @var{node} to which CPU object
-will be assigned, it's required for @var{node} to be declared
-with @samp{node} option before it's used with @samp{cpu} option.
-
-For example:
-@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
-@end example
-
-@samp{mem} assigns a given RAM amount to a node. @samp{memdev}
-assigns RAM from a given memory backend device to a node. If
-@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
-split equally between them.
-
-@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
-if one node uses @samp{memdev}, all of them have to use it.
-
-@var{source} and @var{destination} are NUMA node IDs.
-@var{distance} is the NUMA distance from @var{source} to @var{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 -@option{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 @option{-m},
-@option{-smp} options to allocate RAM and VCPUs respectively.
-
-ETEXI
+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=tpye[,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
+
+ '\ ``mem``\ ' assigns a given RAM amount to a node. '\ ``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.
+
+ '\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive.
+ Furthermore, if one node uses '\ ``memdev``\ ', all of them have to
+ use it.
+
+ '\ ``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 \
+ -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)
-STEXI
-@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
-@findex -add-fd
-
-Add a file descriptor to an fd set. Valid options are:
-
-@table @option
-@item fd=@var{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.
-@item set=@var{set}
-This option defines the ID of the fd set to add the file descriptor to.
-@item opaque=@var{opaque}
-This option defines a free-form string that can be used to describe @var{fd}.
-@end table
-
-You can open an image using pre-opened file descriptors from an fd set:
-@example
-@value{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
-@end example
-ETEXI
+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)
-STEXI
-@item -set @var{group}.@var{id}.@var{arg}=@var{value}
-@findex -set
-Set parameter @var{arg} for item @var{id} of type @var{group}
-ETEXI
+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)
-STEXI
-@item -global @var{driver}.@var{prop}=@var{value}
-@itemx -global driver=@var{driver},property=@var{property},value=@var{value}
-@findex -global
-Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
+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::
-@example
-@value{qemu_system_x86} -global ide-hd.physical_block_size=4096 disk-image.img
-@end example
+ |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 -@option{device}.
+ 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 @var{driver}.@var{prop}=@var{value} is shorthand for -global
-driver=@var{driver},property=@var{prop},value=@var{value}. The
-longhand syntax works even when @var{driver} contains a dot.
-ETEXI
+ -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"
" '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)
-STEXI
-@item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off][,splash=@var{sp_name}][,splash-time=@var{sp_time}][,reboot-timeout=@var{rb_timeout}][,strict=on|off]
-@findex -boot
-Specify boot order @var{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
-@option{once}. Note that the @option{order} or @option{once} parameter
-should not be used together with the @option{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 @option{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=@var{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 @var{rb_timeout} ms
-when boot failed, then reboot. If @var{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 @option{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.
-
-@example
-# try to boot from network first, then from hard disk
-@value{qemu_system_x86} -boot order=nc
-# boot from CD-ROM first, switch back to default order after reboot
-@value{qemu_system_x86} -boot once=d
-# boot with a splash picture for 5 seconds.
-@value{qemu_system_x86} -boot menu=on,splash=/root/boot.bmp,splash-time=5000
-@end example
-
-Note: The legacy format '-boot @var{drives}' is still supported but its
-use is discouraged as it may be removed from future versions.
-ETEXI
+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"
" maxmem: maximum amount of guest memory (default: none)\n"
"NOTE: Some architectures might enforce a specific granularity\n",
QEMU_ARCH_ALL)
-STEXI
-@item -m [size=]@var{megs}[,slots=n,maxmem=size]
-@findex -m
-Sets guest startup RAM size to @var{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 @var{slots}, @var{maxmem}
-could be used to set amount of hotpluggable memory slots and maximum amount of
-memory. Note that @var{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:
-
-@example
-@value{qemu_system} -m 1G,slots=3,maxmem=4G
-@end example
-
-If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
-be enabled and the guest startup RAM will never increase.
-ETEXI
+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)
-STEXI
-@item -mem-path @var{path}
-@findex -mem-path
-Allocate guest RAM from a temporarily created file in @var{path}.
-ETEXI
+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)
-STEXI
-@item -mem-prealloc
-@findex -mem-prealloc
-Preallocate memory when using -mem-path.
-ETEXI
+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)
-STEXI
-@item -k @var{language}
-@findex -k
-Use keyboard layout @var{language} (for example @code{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:
-@example
-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
-@end example
-
-The default is @code{en-us}.
-ETEXI
+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
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)
-STEXI
-@item -audio-help
-@findex -audio-help
-Will show the -audiodev equivalent of the currently specified
-(deprecated) environment variables.
-ETEXI
+SRST
+``-audio-help``
+ Will show the -audiodev equivalent of the currently specified
+ (deprecated) environment variables.
+ERST
DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
"-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
"-audiodev wav,id=id[,prop[=value][,...]]\n"
" path= path of wav file to record\n",
QEMU_ARCH_ALL)
-STEXI
-@item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]]
-@findex -audiodev
-Adds a new audio backend @var{driver} identified by @var{id}. There are
-global and driver specific properties. Some values can be set
-differently for input and output, they're marked with @code{in|out.}.
-You can set the input's property with @code{in.@var{prop}} and the
-output's property with @code{out.@var{prop}}. For example:
-@example
--audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
--audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
-@end example
-
-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:
-
-@table @option
-@item id=@var{identifier}
-Identifies the audio backend.
+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:
-@item timer-period=@var{period}
-Sets the timer @var{period} used by the audio subsystem in microseconds.
-Default is 10000 (10 ms).
+ ::
-@item 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,
-@var{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.
+ -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
+ -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
-@item 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
-@var{frequency}, @var{channels} or @var{format}. Default is on.
+ 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.
-@item in|out.frequency=@var{frequency}
-Specify the @var{frequency} to use when using @var{fixed-settings}.
-Default is 44100Hz.
+ Valid global options are:
-@item in|out.channels=@var{channels}
-Specify the number of @var{channels} to use when using
-@var{fixed-settings}. Default is 2 (stereo).
+ ``id=identifier``
+ Identifies the audio backend.
-@item in|out.format=@var{format}
-Specify the sample @var{format} to use when using @var{fixed-settings}.
-Valid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8},
-@code{u16}, @code{u32}. Default is @code{s16}.
+ ``timer-period=period``
+ Sets the timer period used by the audio subsystem in
+ microseconds. Default is 10000 (10 ms).
-@item in|out.voices=@var{voices}
-Specify the number of @var{voices} to use. Default is 1.
+ ``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.
-@item in|out.buffer-length=@var{usecs}
-Sets the size of the buffer in microseconds.
+ ``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.
-@end table
+ ``in|out.frequency=frequency``
+ Specify the frequency to use when using fixed-settings. Default
+ is 44100Hz.
-@item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]]
-Creates a dummy backend that discards all outputs. This backend has no
-backend specific properties.
+ ``in|out.channels=channels``
+ Specify the number of channels to use when using fixed-settings.
+ Default is 2 (stereo).
-@item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
-Creates backend using the ALSA. This backend is only available on
-Linux.
+ ``in|out.format=format``
+ Specify the sample format to use when using fixed-settings.
+ Valid values are: ``s8``, ``s16``, ``s32``, ``u8``, ``u16``,
+ ``u32``. Default is ``s16``.
-ALSA specific options are:
+ ``in|out.voices=voices``
+ Specify the number of voices to use. Default is 1.
-@table @option
+ ``in|out.buffer-length=usecs``
+ Sets the size of the buffer in microseconds.
-@item in|out.dev=@var{device}
-Specify the ALSA @var{device} to use for input and/or output. Default
-is @code{default}.
+``-audiodev none,id=id[,prop[=value][,...]]``
+ Creates a dummy backend that discards all outputs. This backend has
+ no backend specific properties.
-@item in|out.period-length=@var{usecs}
-Sets the period length in microseconds.
+``-audiodev alsa,id=id[,prop[=value][,...]]``
+ Creates backend using the ALSA. This backend is only available on
+ Linux.
-@item in|out.try-poll=on|off
-Attempt to use poll mode with the device. Default is on.
+ ALSA specific options are:
-@item threshold=@var{threshold}
-Threshold (in microseconds) when playback starts. Default is 0.
+ ``in|out.dev=device``
+ Specify the ALSA device to use for input and/or output. Default
+ is ``default``.
-@end table
+ ``in|out.period-length=usecs``
+ Sets the period length in microseconds.
-@item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]]
-Creates a backend using Apple's Core Audio. This backend is only
-available on Mac OS and only supports playback.
+ ``in|out.try-poll=on|off``
+ Attempt to use poll mode with the device. Default is on.
-Core Audio specific options are:
+ ``threshold=threshold``
+ Threshold (in microseconds) when playback starts. Default is 0.
-@table @option
+``-audiodev coreaudio,id=id[,prop[=value][,...]]``
+ Creates a backend using Apple's Core Audio. This backend is only
+ available on Mac OS and only supports playback.
-@item in|out.buffer-count=@var{count}
-Sets the @var{count} of the buffers.
+ Core Audio specific options are:
-@end table
+ ``in|out.buffer-count=count``
+ Sets the count of the buffers.
-@item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]]
-Creates a backend using Microsoft's DirectSound. This backend is only
-available on Windows and only supports playback.
+``-audiodev dsound,id=id[,prop[=value][,...]]``
+ Creates a backend using Microsoft's DirectSound. This backend is
+ only available on Windows and only supports playback.
-DirectSound specific options are:
+ DirectSound specific options are:
-@table @option
+ ``latency=usecs``
+ Add extra usecs microseconds latency to playback. Default is
+ 10000 (10 ms).
-@item latency=@var{usecs}
-Add extra @var{usecs} microseconds latency to playback. Default is
-10000 (10 ms).
+``-audiodev oss,id=id[,prop[=value][,...]]``
+ Creates a backend using OSS. This backend is available on most
+ Unix-like systems.
-@end table
+ OSS specific options are:
-@item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]]
-Creates a backend using OSS. This backend is available on most
-Unix-like systems.
+ ``in|out.dev=device``
+ Specify the file name of the OSS device to use. Default is
+ ``/dev/dsp``.
-OSS specific options are:
+ ``in|out.buffer-count=count``
+ Sets the count of the buffers.
-@table @option
+ ``in|out.try-poll=on|of``
+ Attempt to use poll mode with the device. Default is on.
-@item in|out.dev=@var{device}
-Specify the file name of the OSS @var{device} to use. Default is
-@code{/dev/dsp}.
+ ``try-mmap=on|off``
+ Try using memory mapped device access. Default is off.
-@item in|out.buffer-count=@var{count}
-Sets the @var{count} of the buffers.
+ ``exclusive=on|off``
+ Open the device in exclusive mode (vmix won't work in this
+ case). Default is off.
-@item in|out.try-poll=on|of
-Attempt to use poll mode with the device. Default is on.
+ ``dsp-policy=policy``
+ Sets the timing policy (between 0 and 10, where smaller number
+ means smaller latency but higher CPU usage). Use -1 to use
+ buffer sizes specified by ``buffer`` and ``buffer-count``. This
+ option is ignored if you do not have OSS 4. Default is 5.
-@item try-mmap=on|off
-Try using memory mapped device access. Default is off.
+``-audiodev pa,id=id[,prop[=value][,...]]``
+ Creates a backend using PulseAudio. This backend is available on
+ most systems.
-@item exclusive=on|off
-Open the device in exclusive mode (vmix won't work in this case).
-Default is off.
+ PulseAudio specific options are:
-@item dsp-policy=@var{policy}
-Sets the timing policy (between 0 and 10, where smaller number means
-smaller latency but higher CPU usage). Use -1 to use buffer sizes
-specified by @code{buffer} and @code{buffer-count}. This option is
-ignored if you do not have OSS 4. Default is 5.
+ ``server=server``
+ Sets the PulseAudio server to connect to.
-@end table
+ ``in|out.name=sink``
+ Use the specified source/sink for recording/playback.
-@item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
-Creates a backend using PulseAudio. This backend is available on most
-systems.
+ ``in|out.latency=usecs``
+ Desired latency in microseconds. The PulseAudio server will try
+ to honor this value but actual latencies may be lower or higher.
-PulseAudio specific options are:
+``-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
+ possible. This backend has no backend specific properties.
-@table @option
+``-audiodev spice,id=id[,prop[=value][,...]]``
+ Creates a backend that sends audio through SPICE. This backend
+ requires ``-spice`` and automatically selected in that case, so
+ usually you can ignore this option. This backend has no backend
+ specific properties.
-@item server=@var{server}
-Sets the PulseAudio @var{server} to connect to.
+``-audiodev wav,id=id[,prop[=value][,...]]``
+ Creates a backend that writes audio to a WAV file.
-@item in|out.name=@var{sink}
-Use the specified source/sink for recording/playback.
+ Backend specific options are:
-@item in|out.latency=@var{usecs}
-Desired latency in microseconds. The PulseAudio server will try to honor this
-value but actual latencies may be lower or higher.
-
-@end table
-
-@item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]]
-Creates a backend using SDL. This backend is available on most systems,
-but you should use your platform's native backend if possible. This
-backend has no backend specific properties.
-
-@item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]]
-Creates a backend that sends audio through SPICE. This backend requires
-@code{-spice} and automatically selected in that case, so usually you
-can ignore this option. This backend has no backend specific
-properties.
-
-@item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]]
-Creates a backend that writes audio to a WAV file.
-
-Backend specific options are:
-
-@table @option
-
-@item path=@var{path}
-Write recorded audio into the specified file. Default is
-@code{qemu.wav}.
-
-@end table
-ETEXI
+ ``path=path``
+ Write recorded audio into the specified file. Default is
+ ``qemu.wav``.
+ERST
DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
"-soundhw c1,... enable audio support\n"
" and only specified sound cards (comma separated list)\n"
" use '-soundhw help' to get the list of supported cards\n"
" use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
-STEXI
-@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
-@findex -soundhw
-Enable audio and selected sound hardware. Use 'help' to print all
-available sound hardware. For example:
-
-@example
-@value{qemu_system_x86} -soundhw sb16,adlib disk.img
-@value{qemu_system_x86} -soundhw es1370 disk.img
-@value{qemu_system_x86} -soundhw ac97 disk.img
-@value{qemu_system_x86} -soundhw hda disk.img
-@value{qemu_system_x86} -soundhw all disk.img
-@value{qemu_system_x86} -soundhw help
-@end example
-
-Note that Linux's i810_audio OSS kernel (for AC97) module might
-require manually specifying clocking.
-
-@example
-modprobe i810_audio clocking=48000
-@end example
-ETEXI
+SRST
+``-soundhw card1[,card2,...] or -soundhw all``
+ Enable audio and selected sound hardware. Use 'help' to print all
+ available sound hardware. For example:
+
+ .. parsed-literal::
+
+ |qemu_system_x86| -soundhw sb16,adlib disk.img
+ |qemu_system_x86| -soundhw es1370 disk.img
+ |qemu_system_x86| -soundhw ac97 disk.img
+ |qemu_system_x86| -soundhw hda disk.img
+ |qemu_system_x86| -soundhw all disk.img
+ |qemu_system_x86| -soundhw help
+
+ Note that Linux's i810\_audio OSS kernel (for AC97) module might
+ require manually specifying clocking.
+
+ ::
+
+ modprobe i810_audio clocking=48000
+ERST
DEF("device", HAS_ARG, QEMU_OPTION_device,
"-device driver[,prop[=value][,...]]\n"
" use '-device help' to print all possible drivers\n"
" use '-device driver,help' to print all possible properties\n",
QEMU_ARCH_ALL)
-STEXI
-@item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
-@findex -device
-Add device @var{driver}. @var{prop}=@var{value} sets driver
-properties. Valid properties depend on the driver. To get help on
-possible drivers and properties, use @code{-device help} and
-@code{-device @var{driver},help}.
-
-Some drivers are:
-@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}][,guid=@var{uuid}]
-
-Add an IPMI BMC. This is a simulation of a hardware management
-interface processor that normally sits on a system. It provides
-a watchdog and the ability to reset and power control the system.
-You need to connect this to an IPMI interface to make it useful
-
-The IPMI slave address to use for the BMC. The default is 0x20.
-This address is the BMC's address on the I2C network of management
-controllers. If you don't know what this means, it is safe to ignore
-it.
-
-@table @option
-@item id=@var{id}
-The BMC id for interfaces to use this device.
-@item slave_addr=@var{val}
-Define slave address to use for the BMC. The default is 0x20.
-@item sdrfile=@var{file}
-file containing raw Sensor Data Records (SDR) data. The default is none.
-@item fruareasize=@var{val}
-size of a Field Replaceable Unit (FRU) area. The default is 1024.
-@item frudatafile=@var{file}
-file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
-@item guid=@var{uuid}
-value for the GUID for the BMC, in standard UUID format. If this is set,
-get "Get GUID" command to the BMC will return it. Otherwise "Get GUID"
-will return an error.
-@end table
-
-@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
-
-Add a connection to an external IPMI BMC simulator. Instead of
-locally emulating the BMC like the above item, instead connect
-to an external entity that provides the IPMI services.
-
-A connection is made to an external BMC simulator. If you do this, it
-is strongly recommended that you use the "reconnect=" chardev option
-to reconnect to the simulator if the connection is lost. Note that if
-this is not used carefully, it can be a security issue, as the
-interface has the ability to send resets, NMIs, and power off the VM.
-It's best if QEMU makes a connection to an external simulator running
-on a secure port on localhost, so neither the simulator nor QEMU is
-exposed to any outside network.
-
-See the "lanserv/README.vm" file in the OpenIPMI library for more
-details on the external interface.
-
-@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
-
-Add a KCS IPMI interafce on the ISA bus. This also adds a
-corresponding ACPI and SMBIOS entries, if appropriate.
-
-@table @option
-@item bmc=@var{id}
-The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
-@item ioport=@var{val}
-Define the I/O address of the interface. The default is 0xca0 for KCS.
-@item irq=@var{val}
-Define the interrupt to use. The default is 5. To disable interrupts,
-set this to 0.
-@end table
-
-@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
-
-Like the KCS interface, but defines a BT interface. The default port is
-0xe4 and the default interrupt is 5.
-
-ETEXI
+SRST
+``-device driver[,prop[=value][,...]]``
+ Add device driver. prop=value sets driver properties. Valid
+ properties depend on the driver. To get help on possible drivers and
+ properties, use ``-device help`` and ``-device driver,help``.
+
+ Some drivers are:
+
+``-device ipmi-bmc-sim,id=id[,slave_addr=val][,sdrfile=file][,furareasize=val][,furdatafile=file][,guid=uuid]``
+ Add an IPMI BMC. This is a simulation of a hardware management
+ interface processor that normally sits on a system. It provides a
+ watchdog and the ability to reset and power control the system. You
+ need to connect this to an IPMI interface to make it useful
+
+ The IPMI slave address to use for the BMC. The default is 0x20. This
+ address is the BMC's address on the I2C network of management
+ controllers. If you don't know what this means, it is safe to ignore
+ it.
+
+ ``id=id``
+ The BMC id for interfaces to use this device.
+
+ ``slave_addr=val``
+ Define slave address to use for the BMC. The default is 0x20.
+
+ ``sdrfile=file``
+ file containing raw Sensor Data Records (SDR) data. The default
+ is none.
+
+ ``fruareasize=val``
+ size of a Field Replaceable Unit (FRU) area. The default is
+ 1024.
+
+ ``frudatafile=file``
+ file containing raw Field Replaceable Unit (FRU) inventory data.
+ The default is none.
+
+ ``guid=uuid``
+ value for the GUID for the BMC, in standard UUID format. If this
+ is set, get "Get GUID" command to the BMC will return it.
+ Otherwise "Get GUID" will return an error.
+
+``-device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]``
+ Add a connection to an external IPMI BMC simulator. Instead of
+ locally emulating the BMC like the above item, instead connect to an
+ external entity that provides the IPMI services.
+
+ A connection is made to an external BMC simulator. If you do this,
+ it is strongly recommended that you use the "reconnect=" chardev
+ option to reconnect to the simulator if the connection is lost. Note
+ that if this is not used carefully, it can be a security issue, as
+ the interface has the ability to send resets, NMIs, and power off
+ the VM. It's best if QEMU makes a connection to an external
+ simulator running on a secure port on localhost, so neither the
+ simulator nor QEMU is exposed to any outside network.
+
+ See the "lanserv/README.vm" file in the OpenIPMI library for more
+ details on the external interface.
+
+``-device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]``
+ Add a KCS IPMI interafce on the ISA bus. This also adds a
+ corresponding ACPI and SMBIOS entries, if appropriate.
+
+ ``bmc=id``
+ The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern
+ above.
+
+ ``ioport=val``
+ Define the I/O address of the interface. The default is 0xca0
+ for KCS.
+
+ ``irq=val``
+ Define the interrupt to use. The default is 5. To disable
+ interrupts, set this to 0.
+
+``-device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]``
+ Like the KCS interface, but defines a BT interface. The default port
+ is 0xe4 and the default interrupt is 5.
+ERST
DEF("name", HAS_ARG, QEMU_OPTION_name,
"-name string1[,process=string2][,debug-threads=on|off]\n"
" When debug-threads is enabled, individual threads are given a separate name\n"
" NOTE: The thread names are for debugging and not a stable API.\n",
QEMU_ARCH_ALL)
-STEXI
-@item -name @var{name}
-@findex -name
-Sets the @var{name} of the guest.
-This name will be displayed in the SDL window caption.
-The @var{name} will also be used for the VNC server.
-Also optionally set the top visible process name in Linux.
-Naming of individual threads can also be enabled on Linux to aid debugging.
-ETEXI
+SRST
+``-name name``
+ Sets the name of the guest. This name will be displayed in the SDL
+ window caption. The name will also be used for the VNC server. Also
+ optionally set the top visible process name in Linux. Naming of
+ individual threads can also be enabled on Linux to aid debugging.
+ERST
DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
"-uuid %08x-%04x-%04x-%04x-%012x\n"
" specify machine UUID\n", QEMU_ARCH_ALL)
-STEXI
-@item -uuid @var{uuid}
-@findex -uuid
-Set system UUID.
-ETEXI
-
-STEXI
-@end table
-ETEXI
+SRST
+``-uuid uuid``
+ Set system UUID.
+ERST
+
DEFHEADING()
DEFHEADING(Block device options:)
-STEXI
-@table @option
-ETEXI
DEF("fda", HAS_ARG, QEMU_OPTION_fda,
"-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
-STEXI
-@item -fda @var{file}
-@itemx -fdb @var{file}
-@findex -fda
-@findex -fdb
-Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
-ETEXI
+SRST
+``-fda file``
+ \
+``-fdb file``
+ Use file as floppy disk 0/1 image (see
+ :ref:`disk_005fimages`).
+ERST
DEF("hda", HAS_ARG, QEMU_OPTION_hda,
"-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", 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)
DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
-STEXI
-@item -hda @var{file}
-@itemx -hdb @var{file}
-@itemx -hdc @var{file}
-@itemx -hdd @var{file}
-@findex -hda
-@findex -hdb
-@findex -hdc
-@findex -hdd
-Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
-ETEXI
+SRST
+``-hda file``
+ \
+``-hdb file``
+ \
+``-hdc file``
+ \
+``-hdd file``
+ Use file as hard disk 0, 1, 2 or 3 image (see
+ :ref:`disk_005fimages`).
+ERST
DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
"-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -cdrom @var{file}
-@findex -cdrom
-Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
-@option{-cdrom} at the same time). You can use the host CD-ROM by
-using @file{/dev/cdrom} as filename (@pxref{host_drives}).
-ETEXI
+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.
+ERST
DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
"-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
" [,force-share=on|off][,detect-zeroes=on|off|unmap]\n"
" [,driver specific parameters...]\n"
" configure a block backend\n", QEMU_ARCH_ALL)
-STEXI
-@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
-@findex -blockdev
-
-Define a new block driver node. Some of the options apply to all block drivers,
-other options are only accepted for a specific block driver. See below for a
-list of generic options and options for the most common block drivers.
-
-Options that expect a reference to another node (e.g. @code{file}) can be
-given in two ways. Either you specify the node name of an already existing node
-(file=@var{node-name}), or you define a new node inline, adding options
-for the referenced node after a dot (file.filename=@var{path},file.aio=native).
-
-A block driver node created with @option{-blockdev} can be used for a guest
-device by specifying its node name for the @code{drive} property in a
-@option{-device} argument that defines a block device.
-
-@table @option
-@item Valid options for any block driver node:
-
-@table @code
-@item driver
-Specifies the block driver to use for the given node.
-@item node-name
-This defines the name of the block driver node by which it will be referenced
-later. The name must be unique, i.e. it must not match the name of a different
-block driver node, or (if you use @option{-drive} as well) the ID of a drive.
-
-If no node name is specified, it is automatically generated. The generated node
-name is not intended to be predictable and changes between QEMU invocations.
-For the top level, an explicit node name must be specified.
-@item read-only
-Open the node read-only. Guest write attempts will fail.
-
-Note that some block drivers support only read-only access, either generally or
-in certain configurations. In this case, the default value
-@option{read-only=off} does not work and the option must be specified
-explicitly.
-@item auto-read-only
-If @option{auto-read-only=on} is set, QEMU may fall back to read-only usage
-even when @option{read-only=off} is requested, or even switch between modes as
-needed, e.g. depending on whether the image file is writable or whether a
-writing user is attached to the node.
-@item force-share
-Override the image locking system of QEMU by forcing the node to utilize
-weaker shared access for permissions where it would normally request exclusive
-access. When there is the potential for multiple instances to have the same
-file open (whether this invocation of QEMU is the first or the second
-instance), both instances must permit shared access for the second instance to
-succeed at opening the file.
-
-Enabling @option{force-share=on} requires @option{read-only=on}.
-@item cache.direct
-The host page cache can be avoided with @option{cache.direct=on}. This will
-attempt to do disk IO directly to the guest's memory. QEMU may still perform an
-internal copy of the data.
-@item cache.no-flush
-In case you don't care about data integrity over host failures, you can use
-@option{cache.no-flush=on}. This option tells QEMU that it never needs to write
-any data to the disk but can instead keep things in cache. If anything goes
-wrong, like your host losing power, the disk storage getting disconnected
-accidentally, etc. your image will most probably be rendered unusable.
-@item discard=@var{discard}
-@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls
-whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are
-ignored or passed to the filesystem. Some machine types may not support
-discard requests.
-@item detect-zeroes=@var{detect-zeroes}
-@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
-conversion of plain zero writes by the OS to driver specific optimized
-zero write commands. You may even choose "unmap" if @var{discard} is set
-to "unmap" to allow a zero write to be converted to an @code{unmap} operation.
-@end table
-
-@item Driver-specific options for @code{file}
-
-This is the protocol-level block driver for accessing regular files.
-
-@table @code
-@item filename
-The path to the image file in the local filesystem
-@item aio
-Specifies the AIO backend (threads/native, default: threads)
-@item locking
-Specifies whether the image file is protected with Linux OFD / POSIX locks. The
-default is to use the Linux Open File Descriptor API if available, otherwise no
-lock is applied. (auto/on/off, default: auto)
-@end table
-Example:
-@example
--blockdev driver=file,node-name=disk,filename=disk.img
-@end example
-
-@item Driver-specific options for @code{raw}
-
-This is the image format block driver for raw images. It is usually
-stacked on top of a protocol level block driver such as @code{file}.
-
-@table @code
-@item file
-Reference to or definition of the data source block driver node
-(e.g. a @code{file} driver node)
-@end table
-Example 1:
-@example
--blockdev driver=file,node-name=disk_file,filename=disk.img
--blockdev driver=raw,node-name=disk,file=disk_file
-@end example
-Example 2:
-@example
--blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
-@end example
-
-@item Driver-specific options for @code{qcow2}
-
-This is the image format block driver for qcow2 images. It is usually
-stacked on top of a protocol level block driver such as @code{file}.
-
-@table @code
-@item file
-Reference to or definition of the data source block driver node
-(e.g. a @code{file} driver node)
-
-@item backing
-Reference to or definition of the backing file block device (default is taken
-from the image file). It is allowed to pass @code{null} here in order to disable
-the default backing file.
-
-@item lazy-refcounts
-Whether to enable the lazy refcounts feature (on/off; default is taken from the
-image file)
-
-@item cache-size
-The maximum total size of the L2 table and refcount block caches in bytes
-(default: the sum of l2-cache-size and refcount-cache-size)
-
-@item l2-cache-size
-The maximum size of the L2 table cache in bytes
-(default: if cache-size is not specified - 32M on Linux platforms, and 8M on
-non-Linux platforms; otherwise, as large as possible within the cache-size,
-while permitting the requested or the minimal refcount cache size)
-
-@item refcount-cache-size
-The maximum size of the refcount block cache in bytes
-(default: 4 times the cluster size; or if cache-size is specified, the part of
-it which is not used for the L2 cache)
-
-@item cache-clean-interval
-Clean unused entries in the L2 and refcount caches. The interval is in seconds.
-The default value is 600 on supporting platforms, and 0 on other platforms.
-Setting it to 0 disables this feature.
-
-@item pass-discard-request
-Whether discard requests to the qcow2 device should be forwarded to the data
-source (on/off; default: on if discard=unmap is specified, off otherwise)
-
-@item pass-discard-snapshot
-Whether discard requests for the data source should be issued when a snapshot
-operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
-default: on)
-
-@item pass-discard-other
-Whether discard requests for the data source should be issued on other
-occasions where a cluster gets freed (on/off; default: off)
-
-@item overlap-check
-Which overlap checks to perform for writes to the image
-(none/constant/cached/all; default: cached). For details or finer
-granularity control refer to the QAPI documentation of @code{blockdev-add}.
-@end table
-
-Example 1:
-@example
--blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
--blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
-@end example
-Example 2:
-@example
--blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
-@end example
-
-@item Driver-specific options for other drivers
-Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
-
-@end table
-
-ETEXI
+SRST
+``-blockdev option[,option[,option[,...]]]``
+ Define a new block driver node. Some of the options apply to all
+ block drivers, other options are only accepted for a specific block
+ driver. See below for a list of generic options and options for the
+ most common block drivers.
+
+ Options that expect a reference to another node (e.g. ``file``) can
+ be given in two ways. Either you specify the node name of an already
+ existing node (file=node-name), or you define a new node inline,
+ adding options for the referenced node after a dot
+ (file.filename=path,file.aio=native).
+
+ A block driver node created with ``-blockdev`` can be used for a
+ guest device by specifying its node name for the ``drive`` property
+ in a ``-device`` argument that defines a block device.
+
+ ``Valid options for any block driver node:``
+ ``driver``
+ Specifies the block driver to use for the given node.
+
+ ``node-name``
+ This defines the name of the block driver node by which it
+ will be referenced later. The name must be unique, i.e. it
+ must not match the name of a different block driver node, or
+ (if you use ``-drive`` as well) the ID of a drive.
+
+ If no node name is specified, it is automatically generated.
+ The generated node name is not intended to be predictable
+ and changes between QEMU invocations. For the top level, an
+ explicit node name must be specified.
+
+ ``read-only``
+ Open the node read-only. Guest write attempts will fail.
+
+ Note that some block drivers support only read-only access,
+ either generally or in certain configurations. In this case,
+ the default value ``read-only=off`` does not work and the
+ option must be specified explicitly.
+
+ ``auto-read-only``
+ If ``auto-read-only=on`` is set, QEMU may fall back to
+ read-only usage even when ``read-only=off`` is requested, or
+ even switch between modes as needed, e.g. depending on
+ whether the image file is writable or whether a writing user
+ is attached to the node.
+
+ ``force-share``
+ Override the image locking system of QEMU by forcing the
+ node to utilize weaker shared access for permissions where
+ it would normally request exclusive access. When there is
+ the potential for multiple instances to have the same file
+ open (whether this invocation of QEMU is the first or the
+ second instance), both instances must permit shared access
+ for the second instance to succeed at opening the file.
+
+ Enabling ``force-share=on`` requires ``read-only=on``.
+
+ ``cache.direct``
+ The host page cache can be avoided with ``cache.direct=on``.
+ This will attempt to do disk IO directly to the guest's
+ memory. QEMU may still perform an internal copy of the data.
+
+ ``cache.no-flush``
+ In case you don't care about data integrity over host
+ failures, you can use ``cache.no-flush=on``. This option
+ tells QEMU that it never needs to write any data to the disk
+ but can instead keep things in cache. If anything goes
+ wrong, like your host losing power, the disk storage getting
+ disconnected accidentally, etc. your image will most
+ probably be rendered unusable.
+
+ ``discard=discard``
+ discard is one of "ignore" (or "off") or "unmap" (or "on")
+ and controls whether ``discard`` (also known as ``trim`` or
+ ``unmap``) requests are ignored or passed to the filesystem.
+ Some machine types may not support discard requests.
+
+ ``detect-zeroes=detect-zeroes``
+ detect-zeroes is "off", "on" or "unmap" and enables the
+ automatic conversion of plain zero writes by the OS to
+ driver specific optimized zero write commands. You may even
+ choose "unmap" if discard is set to "unmap" to allow a zero
+ write to be converted to an ``unmap`` operation.
+
+ ``Driver-specific options for file``
+ This is the protocol-level block driver for accessing regular
+ files.
+
+ ``filename``
+ The path to the image file in the local filesystem
+
+ ``aio``
+ Specifies the AIO backend (threads/native, default: threads)
+
+ ``locking``
+ Specifies whether the image file is protected with Linux OFD
+ / POSIX locks. The default is to use the Linux Open File
+ Descriptor API if available, otherwise no lock is applied.
+ (auto/on/off, default: auto)
+
+ Example:
+
+ ::
+
+ -blockdev driver=file,node-name=disk,filename=disk.img
+
+ ``Driver-specific options for raw``
+ This is the image format block driver for raw images. It is
+ usually stacked on top of a protocol level block driver such as
+ ``file``.
+
+ ``file``
+ Reference to or definition of the data source block driver
+ node (e.g. a ``file`` driver node)
+
+ Example 1:
+
+ ::
+
+ -blockdev driver=file,node-name=disk_file,filename=disk.img
+ -blockdev driver=raw,node-name=disk,file=disk_file
+
+ Example 2:
+
+ ::
+
+ -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
+
+ ``Driver-specific options for qcow2``
+ This is the image format block driver for qcow2 images. It is
+ usually stacked on top of a protocol level block driver such as
+ ``file``.
+
+ ``file``
+ Reference to or definition of the data source block driver
+ node (e.g. a ``file`` driver node)
+
+ ``backing``
+ Reference to or definition of the backing file block device
+ (default is taken from the image file). It is allowed to
+ pass ``null`` here in order to disable the default backing
+ file.
+
+ ``lazy-refcounts``
+ Whether to enable the lazy refcounts feature (on/off;
+ default is taken from the image file)
+
+ ``cache-size``
+ The maximum total size of the L2 table and refcount block
+ caches in bytes (default: the sum of l2-cache-size and
+ refcount-cache-size)
+
+ ``l2-cache-size``
+ The maximum size of the L2 table cache in bytes (default: if
+ cache-size is not specified - 32M on Linux platforms, and 8M
+ on non-Linux platforms; otherwise, as large as possible
+ within the cache-size, while permitting the requested or the
+ minimal refcount cache size)
+
+ ``refcount-cache-size``
+ The maximum size of the refcount block cache in bytes
+ (default: 4 times the cluster size; or if cache-size is
+ specified, the part of it which is not used for the L2
+ cache)
+
+ ``cache-clean-interval``
+ Clean unused entries in the L2 and refcount caches. The
+ interval is in seconds. The default value is 600 on
+ supporting platforms, and 0 on other platforms. Setting it
+ to 0 disables this feature.
+
+ ``pass-discard-request``
+ Whether discard requests to the qcow2 device should be
+ forwarded to the data source (on/off; default: on if
+ discard=unmap is specified, off otherwise)
+
+ ``pass-discard-snapshot``
+ Whether discard requests for the data source should be
+ issued when a snapshot operation (e.g. deleting a snapshot)
+ frees clusters in the qcow2 file (on/off; default: on)
+
+ ``pass-discard-other``
+ Whether discard requests for the data source should be
+ issued on other occasions where a cluster gets freed
+ (on/off; default: off)
+
+ ``overlap-check``
+ Which overlap checks to perform for writes to the image
+ (none/constant/cached/all; default: cached). For details or
+ finer granularity control refer to the QAPI documentation of
+ ``blockdev-add``.
+
+ Example 1:
+
+ ::
+
+ -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
+ -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
+
+ Example 2:
+
+ ::
+
+ -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
+
+ ``Driver-specific options for other drivers``
+ Please refer to the QAPI documentation of the ``blockdev-add``
+ QMP command.
+ERST
DEF("drive", HAS_ARG, QEMU_OPTION_drive,
"-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
" [[,iops_size=is]]\n"
" [[,group=g]]\n"
" use 'file' as a drive image\n", QEMU_ARCH_ALL)
-STEXI
-@item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
-@findex -drive
-
-Define a new drive. This includes creating a block driver node (the backend) as
-well as a guest device, and is mostly a shortcut for defining the corresponding
-@option{-blockdev} and @option{-device} options.
-
-@option{-drive} accepts all options that are accepted by @option{-blockdev}. In
-addition, it knows the following options:
-
-@table @option
-@item file=@var{file}
-This option defines which disk image (@pxref{disk_images}) to use with
-this drive. If the filename contains comma, you must double it
-(for instance, "file=my,,file" to use file "my,file").
-
-Special files such as iSCSI devices can be specified using protocol
-specific URLs. See the section for "Device URL Syntax" for more information.
-@item if=@var{interface}
-This option defines on which type on interface the drive is connected.
-Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
-@item bus=@var{bus},unit=@var{unit}
-These options define where is connected the drive by defining the bus number and
-the unit id.
-@item index=@var{index}
-This option defines where is connected the drive by using an index in the list
-of available connectors of a given interface type.
-@item media=@var{media}
-This option defines the type of the media: disk or cdrom.
-@item snapshot=@var{snapshot}
-@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
-(see @option{-snapshot}).
-@item cache=@var{cache}
-@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough"
-and controls how the host cache is used to access block data. This is a
-shortcut that sets the @option{cache.direct} and @option{cache.no-flush}
-options (as in @option{-blockdev}), and additionally @option{cache.writeback},
-which provides a default for the @option{write-cache} option of block guest
-devices (as in @option{-device}). The modes correspond to the following
-settings:
-
-@c Our texi2pod.pl script doesn't support @multitable, so fall back to using
-@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage
-@c and the HTML output.
-@example
-@ │ cache.writeback cache.direct cache.no-flush
-─────────────┼─────────────────────────────────────────────────
-writeback │ on off off
-none │ on on off
-writethrough │ off off off
-directsync │ off on off
-unsafe │ on off on
-@end example
-
-The default mode is @option{cache=writeback}.
-
-@item aio=@var{aio}
-@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
-@item format=@var{format}
-Specify which disk @var{format} will be used rather than detecting
-the format. Can be used to specify format=raw to avoid interpreting
-an untrusted format header.
-@item werror=@var{action},rerror=@var{action}
-Specify which @var{action} to take on write and read errors. Valid actions are:
-"ignore" (ignore the error and try to continue), "stop" (pause QEMU),
-"report" (report the error to the guest), "enospc" (pause QEMU only if the
-host disk is full; report the error to the guest otherwise).
-The default setting is @option{werror=enospc} and @option{rerror=report}.
-@item copy-on-read=@var{copy-on-read}
-@var{copy-on-read} is "on" or "off" and enables whether to copy read backing
-file sectors into the image file.
-@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
-Specify bandwidth throttling limits in bytes per second, either for all request
-types or for reads or writes only. Small values can lead to timeouts or hangs
-inside the guest. A safe minimum for disks is 2 MB/s.
-@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
-Specify bursts in bytes per second, either for all request types or for reads
-or writes only. Bursts allow the guest I/O to spike above the limit
-temporarily.
-@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
-Specify request rate limits in requests per second, either for all request
-types or for reads or writes only.
-@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
-Specify bursts in requests per second, either for all request types or for reads
-or writes only. Bursts allow the guest I/O to spike above the limit
-temporarily.
-@item iops_size=@var{is}
-Let every @var{is} bytes of a request count as a new request for iops
-throttling purposes. Use this option to prevent guests from circumventing iops
-limits by sending fewer but larger requests.
-@item group=@var{g}
-Join a throttling quota group with given name @var{g}. All drives that are
-members of the same group are accounted for together. Use this option to
-prevent guests from circumventing throttling limits by using many small disks
-instead of a single larger disk.
-@end table
-
-By default, the @option{cache.writeback=on} mode is used. It will report data
-writes as completed as soon as the data is present in the host page cache.
-This is safe as long as your guest OS makes sure to correctly flush disk caches
-where needed. If your guest OS does not handle volatile disk write caches
-correctly and your host crashes or loses power, then the guest may experience
-data corruption.
-
-For such guests, you should consider using @option{cache.writeback=off}. This
-means that the host page cache will be used to read and write data, but write
-notification will be sent to the guest only after QEMU has made sure to flush
-each write to the disk. Be aware that this has a major impact on performance.
-
-When using the @option{-snapshot} option, unsafe caching is always used.
-
-Copy-on-read avoids accessing the same backing file sectors repeatedly and is
-useful when the backing file is over a slow network. By default copy-on-read
-is off.
-
-Instead of @option{-cdrom} you can use:
-@example
-@value{qemu_system} -drive file=file,index=2,media=cdrom
-@end example
-
-Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
-use:
-@example
-@value{qemu_system} -drive file=file,index=0,media=disk
-@value{qemu_system} -drive file=file,index=1,media=disk
-@value{qemu_system} -drive file=file,index=2,media=disk
-@value{qemu_system} -drive file=file,index=3,media=disk
-@end example
-
-You can open an image using pre-opened file descriptors from an fd set:
-@example
-@value{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
-@end example
-
-You can connect a CDROM to the slave of ide0:
-@example
-@value{qemu_system_x86} -drive file=file,if=ide,index=1,media=cdrom
-@end example
-
-If you don't specify the "file=" argument, you define an empty drive:
-@example
-@value{qemu_system_x86} -drive if=ide,index=1,media=cdrom
-@end example
-
-Instead of @option{-fda}, @option{-fdb}, you can use:
-@example
-@value{qemu_system_x86} -drive file=file,index=0,if=floppy
-@value{qemu_system_x86} -drive file=file,index=1,if=floppy
-@end example
-
-By default, @var{interface} is "ide" and @var{index} is automatically
-incremented:
-@example
-@value{qemu_system_x86} -drive file=a -drive file=b"
-@end example
-is interpreted like:
-@example
-@value{qemu_system_x86} -hda a -hdb b
-@end example
-ETEXI
+SRST
+``-drive option[,option[,option[,...]]]``
+ Define a new drive. This includes creating a block driver node (the
+ backend) as well as a guest device, and is mostly a shortcut for
+ defining the corresponding ``-blockdev`` and ``-device`` options.
+
+ ``-drive`` accepts all options that are accepted by ``-blockdev``.
+ In addition, it knows the following options:
+
+ ``file=file``
+ This option defines which disk image (see
+ :ref:`disk_005fimages`) to use with this drive. If
+ the filename contains comma, you must double it (for instance,
+ "file=my,,file" to use file "my,file").
+
+ Special files such as iSCSI devices can be specified using
+ protocol specific URLs. See the section for "Device URL Syntax"
+ for more information.
+
+ ``if=interface``
+ This option defines on which type on interface the drive is
+ connected. Available types are: ide, scsi, sd, mtd, floppy,
+ pflash, virtio, none.
+
+ ``bus=bus,unit=unit``
+ These options define where is connected the drive by defining
+ the bus number and the unit id.
+
+ ``index=index``
+ This option defines where is connected the drive by using an
+ index in the list of available connectors of a given interface
+ type.
+
+ ``media=media``
+ This option defines the type of the media: disk or cdrom.
+
+ ``snapshot=snapshot``
+ snapshot is "on" or "off" and controls snapshot mode for the
+ given drive (see ``-snapshot``).
+
+ ``cache=cache``
+ cache is "none", "writeback", "unsafe", "directsync" or
+ "writethrough" and controls how the host cache is used to access
+ block data. This is a shortcut that sets the ``cache.direct``
+ and ``cache.no-flush`` options (as in ``-blockdev``), and
+ additionally ``cache.writeback``, which provides a default for
+ the ``write-cache`` option of block guest devices (as in
+ ``-device``). The modes correspond to the following settings:
+
+ ============= =============== ============ ==============
+ \ cache.writeback cache.direct cache.no-flush
+ ============= =============== ============ ==============
+ writeback on off off
+ none on on off
+ writethrough off off off
+ directsync off on off
+ unsafe on off on
+ ============= =============== ============ ==============
+
+ The default mode is ``cache=writeback``.
+
+ ``aio=aio``
+ aio is "threads", or "native" and selects between pthread based
+ disk I/O and native Linux AIO.
+
+ ``format=format``
+ Specify which disk format will be used rather than detecting the
+ format. Can be used to specify format=raw to avoid interpreting
+ an untrusted format header.
+
+ ``werror=action,rerror=action``
+ Specify which action to take on write and read errors. Valid
+ actions are: "ignore" (ignore the error and try to continue),
+ "stop" (pause QEMU), "report" (report the error to the guest),
+ "enospc" (pause QEMU only if the host disk is full; report the
+ error to the guest otherwise). The default setting is
+ ``werror=enospc`` and ``rerror=report``.
+
+ ``copy-on-read=copy-on-read``
+ copy-on-read is "on" or "off" and enables whether to copy read
+ backing file sectors into the image file.
+
+ ``bps=b,bps_rd=r,bps_wr=w``
+ Specify bandwidth throttling limits in bytes per second, either
+ for all request types or for reads or writes only. Small values
+ can lead to timeouts or hangs inside the guest. A safe minimum
+ for disks is 2 MB/s.
+
+ ``bps_max=bm,bps_rd_max=rm,bps_wr_max=wm``
+ Specify bursts in bytes per second, either for all request types
+ or for reads or writes only. Bursts allow the guest I/O to spike
+ above the limit temporarily.
+
+ ``iops=i,iops_rd=r,iops_wr=w``
+ Specify request rate limits in requests per second, either for
+ all request types or for reads or writes only.
+
+ ``iops_max=bm,iops_rd_max=rm,iops_wr_max=wm``
+ Specify bursts in requests per second, either for all request
+ types or for reads or writes only. Bursts allow the guest I/O to
+ spike above the limit temporarily.
+
+ ``iops_size=is``
+ Let every is bytes of a request count as a new request for iops
+ throttling purposes. Use this option to prevent guests from
+ circumventing iops limits by sending fewer but larger requests.
+
+ ``group=g``
+ Join a throttling quota group with given name g. All drives that
+ are members of the same group are accounted for together. Use
+ this option to prevent guests from circumventing throttling
+ limits by using many small disks instead of a single larger
+ disk.
+
+ By default, the ``cache.writeback=on`` mode is used. It will report
+ data writes as completed as soon as the data is present in the host
+ page cache. This is safe as long as your guest OS makes sure to
+ correctly flush disk caches where needed. If your guest OS does not
+ handle volatile disk write caches correctly and your host crashes or
+ loses power, then the guest may experience data corruption.
+
+ For such guests, you should consider using ``cache.writeback=off``.
+ This means that the host page cache will be used to read and write
+ data, but write notification will be sent to the guest only after
+ QEMU has made sure to flush each write to the disk. Be aware that
+ this has a major impact on performance.
+
+ When using the ``-snapshot`` option, unsafe caching is always used.
+
+ Copy-on-read avoids accessing the same backing file sectors
+ repeatedly and is useful when the backing file is over a slow
+ network. By default copy-on-read is off.
+
+ Instead of ``-cdrom`` you can use:
+
+ .. parsed-literal::
+
+ |qemu_system| -drive file=file,index=2,media=cdrom
+
+ Instead of ``-hda``, ``-hdb``, ``-hdc``, ``-hdd``, you can use:
+
+ .. parsed-literal::
+
+ |qemu_system| -drive file=file,index=0,media=disk
+ |qemu_system| -drive file=file,index=1,media=disk
+ |qemu_system| -drive file=file,index=2,media=disk
+ |qemu_system| -drive file=file,index=3,media=disk
+
+ 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
+
+ You can connect a CDROM to the slave of ide0:
+
+ .. parsed-literal::
+
+ |qemu_system_x86| -drive file=file,if=ide,index=1,media=cdrom
+
+ If you don't specify the "file=" argument, you define an empty
+ drive:
+
+ .. parsed-literal::
+
+ |qemu_system_x86| -drive if=ide,index=1,media=cdrom
+
+ Instead of ``-fda``, ``-fdb``, you can use:
+
+ .. parsed-literal::
+
+ |qemu_system_x86| -drive file=file,index=0,if=floppy
+ |qemu_system_x86| -drive file=file,index=1,if=floppy
+
+ By default, interface is "ide" and index is automatically
+ incremented:
+
+ .. parsed-literal::
+
+ |qemu_system_x86| -drive file=a -drive file=b"
+
+ is interpreted like:
+
+ .. parsed-literal::
+
+ |qemu_system_x86| -hda a -hdb b
+ERST
DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
"-mtdblock file use 'file' as on-board Flash memory image\n",
QEMU_ARCH_ALL)
-STEXI
-@item -mtdblock @var{file}
-@findex -mtdblock
-Use @var{file} as on-board Flash memory image.
-ETEXI
+SRST
+``-mtdblock file``
+ Use file as on-board Flash memory image.
+ERST
DEF("sd", HAS_ARG, QEMU_OPTION_sd,
"-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
-STEXI
-@item -sd @var{file}
-@findex -sd
-Use @var{file} as SecureDigital card image.
-ETEXI
+SRST
+``-sd file``
+ Use file as SecureDigital card image.
+ERST
DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
"-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
-STEXI
-@item -pflash @var{file}
-@findex -pflash
-Use @var{file} as a parallel flash image.
-ETEXI
+SRST
+``-pflash file``
+ Use file as a parallel flash image.
+ERST
DEF("snapshot", 0, QEMU_OPTION_snapshot,
"-snapshot write to temporary files instead of disk image files\n",
QEMU_ARCH_ALL)
-STEXI
-@item -snapshot
-@findex -snapshot
-Write to temporary files instead of disk image files. In this case,
-the raw disk image you use is not written back. You can however force
-the write back by pressing @key{C-a s} (@pxref{disk_images}).
-ETEXI
+SRST
+``-snapshot``
+ Write to temporary files instead of disk image files. In this case,
+ the raw disk image you use is not written back. You can however
+ force the write back by pressing C-a s (see
+ :ref:`disk_005fimages`).
+ERST
DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
"-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n"
"-fsdev synth,id=id\n",
QEMU_ARCH_ALL)
-STEXI
-
-@item -fsdev local,id=@var{id},path=@var{path},security_model=@var{security_model} [,writeout=@var{writeout}][,readonly][,fmode=@var{fmode}][,dmode=@var{dmode}] [,throttling.@var{option}=@var{value}[,throttling.@var{option}=@var{value}[,...]]]
-@itemx -fsdev proxy,id=@var{id},socket=@var{socket}[,writeout=@var{writeout}][,readonly]
-@itemx -fsdev proxy,id=@var{id},sock_fd=@var{sock_fd}[,writeout=@var{writeout}][,readonly]
-@itemx -fsdev synth,id=@var{id}[,readonly]
-@findex -fsdev
-Define a new file system device. Valid options are:
-@table @option
-@item local
-Accesses to the filesystem are done by QEMU.
-@item proxy
-Accesses to the filesystem are done by virtfs-proxy-helper(1).
-@item synth
-Synthetic filesystem, only used by QTests.
-@item id=@var{id}
-Specifies identifier for this device.
-@item path=@var{path}
-Specifies the export path for the file system device. Files under
-this path will be available to the 9p client on the guest.
-@item security_model=@var{security_model}
-Specifies the security model to be used for this export path.
-Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
-In "passthrough" security model, files are stored using the same
-credentials as they are created on the guest. This requires QEMU
-to run as root. In "mapped-xattr" security model, some of the file
-attributes like uid, gid, mode bits and link target are stored as
-file attributes. For "mapped-file" these attributes are stored in the
-hidden .virtfs_metadata directory. Directories exported by this security model cannot
-interact with other unix tools. "none" security model is same as
-passthrough except the sever won't report failures if it fails to
-set file attributes like ownership. Security model is mandatory
-only for local fsdriver. Other fsdrivers (like proxy) don't take
-security model as a parameter.
-@item writeout=@var{writeout}
-This is an optional argument. The only supported value is "immediate".
-This means that host page cache will be used to read and write data but
-write notification will be sent to the guest only when the data has been
-reported as written by the storage subsystem.
-@item readonly
-Enables exporting 9p share as a readonly mount for guests. By default
-read-write access is given.
-@item socket=@var{socket}
-Enables proxy filesystem driver to use passed socket file for communicating
-with virtfs-proxy-helper(1).
-@item sock_fd=@var{sock_fd}
-Enables proxy filesystem driver to use passed socket descriptor for
-communicating with virtfs-proxy-helper(1). Usually a helper like libvirt
-will create socketpair and pass one of the fds as sock_fd.
-@item fmode=@var{fmode}
-Specifies the default mode for newly created files on the host. Works only
-with security models "mapped-xattr" and "mapped-file".
-@item dmode=@var{dmode}
-Specifies the default mode for newly created directories on the host. Works
-only with security models "mapped-xattr" and "mapped-file".
-@item throttling.bps-total=@var{b},throttling.bps-read=@var{r},throttling.bps-write=@var{w}
-Specify bandwidth throttling limits in bytes per second, either for all request
-types or for reads or writes only.
-@item throttling.bps-total-max=@var{bm},bps-read-max=@var{rm},bps-write-max=@var{wm}
-Specify bursts in bytes per second, either for all request types or for reads
-or writes only. Bursts allow the guest I/O to spike above the limit
-temporarily.
-@item throttling.iops-total=@var{i},throttling.iops-read=@var{r}, throttling.iops-write=@var{w}
-Specify request rate limits in requests per second, either for all request
-types or for reads or writes only.
-@item throttling.iops-total-max=@var{im},throttling.iops-read-max=@var{irm}, throttling.iops-write-max=@var{iwm}
-Specify bursts in requests per second, either for all request types or for reads
-or writes only. Bursts allow the guest I/O to spike above the limit temporarily.
-@item throttling.iops-size=@var{is}
-Let every @var{is} bytes of a request count as a new request for iops
-throttling purposes.
-@end table
-
--fsdev option is used along with -device driver "virtio-9p-...".
-@item -device virtio-9p-@var{type},fsdev=@var{id},mount_tag=@var{mount_tag}
-Options for virtio-9p-... driver are:
-@table @option
-@item @var{type}
-Specifies the variant to be used. Supported values are "pci", "ccw" or "device",
-depending on the machine type.
-@item fsdev=@var{id}
-Specifies the id value specified along with -fsdev option.
-@item mount_tag=@var{mount_tag}
-Specifies the tag name to be used by the guest to mount this export point.
-@end table
-
-ETEXI
+SRST
+``-fsdev local,id=id,path=path,security_model=security_model [,writeout=writeout][,readonly][,fmode=fmode][,dmode=dmode] [,throttling.option=value[,throttling.option=value[,...]]]``
+ \
+``-fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly]``
+ \
+``-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly]``
+ \
+``-fsdev synth,id=id[,readonly]``
+ Define a new file system device. Valid options are:
+
+ ``local``
+ Accesses to the filesystem are done by QEMU.
+
+ ``proxy``
+ Accesses to the filesystem are done by virtfs-proxy-helper(1).
+
+ ``synth``
+ Synthetic filesystem, only used by QTests.
+
+ ``id=id``
+ Specifies identifier for this device.
+
+ ``path=path``
+ Specifies the export path for the file system device. Files
+ under this path will be available to the 9p client on the guest.
+
+ ``security_model=security_model``
+ Specifies the security model to be used for this export path.
+ Supported security models are "passthrough", "mapped-xattr",
+ "mapped-file" and "none". In "passthrough" security model, files
+ are stored using the same credentials as they are created on the
+ guest. This requires QEMU to run as root. In "mapped-xattr"
+ security model, some of the file attributes like uid, gid, mode
+ bits and link target are stored as file attributes. For
+ "mapped-file" these attributes are stored in the hidden
+ .virtfs\_metadata directory. Directories exported by this
+ security model cannot interact with other unix tools. "none"
+ security model is same as passthrough except the sever won't
+ report failures if it fails to set file attributes like
+ ownership. Security model is mandatory only for local fsdriver.
+ Other fsdrivers (like proxy) don't take security model as a
+ parameter.
+
+ ``writeout=writeout``
+ This is an optional argument. The only supported value is
+ "immediate". This means that host page cache will be used to
+ read and write data but write notification will be sent to the
+ guest only when the data has been reported as written by the
+ storage subsystem.
+
+ ``readonly``
+ Enables exporting 9p share as a readonly mount for guests. By
+ default read-write access is given.
+
+ ``socket=socket``
+ Enables proxy filesystem driver to use passed socket file for
+ communicating with virtfs-proxy-helper(1).
+
+ ``sock_fd=sock_fd``
+ Enables proxy filesystem driver to use passed socket descriptor
+ for communicating with virtfs-proxy-helper(1). Usually a helper
+ like libvirt will create socketpair and pass one of the fds as
+ sock\_fd.
+
+ ``fmode=fmode``
+ Specifies the default mode for newly created files on the host.
+ Works only with security models "mapped-xattr" and
+ "mapped-file".
+
+ ``dmode=dmode``
+ Specifies the default mode for newly created directories on the
+ host. Works only with security models "mapped-xattr" and
+ "mapped-file".
+
+ ``throttling.bps-total=b,throttling.bps-read=r,throttling.bps-write=w``
+ Specify bandwidth throttling limits in bytes per second, either
+ for all request types or for reads or writes only.
+
+ ``throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm``
+ Specify bursts in bytes per second, either for all request types
+ or for reads or writes only. Bursts allow the guest I/O to spike
+ above the limit temporarily.
+
+ ``throttling.iops-total=i,throttling.iops-read=r, throttling.iops-write=w``
+ Specify request rate limits in requests per second, either for
+ all request types or for reads or writes only.
+
+ ``throttling.iops-total-max=im,throttling.iops-read-max=irm, throttling.iops-write-max=iwm``
+ Specify bursts in requests per second, either for all request
+ types or for reads or writes only. Bursts allow the guest I/O to
+ spike above the limit temporarily.
+
+ ``throttling.iops-size=is``
+ Let every is bytes of a request count as a new request for iops
+ throttling purposes.
+
+ -fsdev option is used along with -device driver "virtio-9p-...".
+
+``-device virtio-9p-type,fsdev=id,mount_tag=mount_tag``
+ Options for virtio-9p-... driver are:
+
+ ``type``
+ Specifies the variant to be used. Supported values are "pci",
+ "ccw" or "device", depending on the machine type.
+
+ ``fsdev=id``
+ Specifies the id value specified along with -fsdev option.
+
+ ``mount_tag=mount_tag``
+ Specifies the tag name to be used by the guest to mount this
+ export point.
+ERST
DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
"-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n"
"-virtfs synth,mount_tag=tag[,id=id][,readonly]\n",
QEMU_ARCH_ALL)
-STEXI
-
-@item -virtfs local,path=@var{path},mount_tag=@var{mount_tag} ,security_model=@var{security_model}[,writeout=@var{writeout}][,readonly] [,fmode=@var{fmode}][,dmode=@var{dmode}][,multidevs=@var{multidevs}]
-@itemx -virtfs proxy,socket=@var{socket},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly]
-@itemx -virtfs proxy,sock_fd=@var{sock_fd},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly]
-@itemx -virtfs synth,mount_tag=@var{mount_tag}
-@findex -virtfs
-
-Define a new filesystem device and expose it to the guest using a virtio-9p-device. The general form of a Virtual File system pass-through options are:
-@table @option
-@item local
-Accesses to the filesystem are done by QEMU.
-@item proxy
-Accesses to the filesystem are done by virtfs-proxy-helper(1).
-@item synth
-Synthetic filesystem, only used by QTests.
-@item id=@var{id}
-Specifies identifier for the filesystem device
-@item path=@var{path}
-Specifies the export path for the file system device. Files under
-this path will be available to the 9p client on the guest.
-@item security_model=@var{security_model}
-Specifies the security model to be used for this export path.
-Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
-In "passthrough" security model, files are stored using the same
-credentials as they are created on the guest. This requires QEMU
-to run as root. In "mapped-xattr" security model, some of the file
-attributes like uid, gid, mode bits and link target are stored as
-file attributes. For "mapped-file" these attributes are stored in the
-hidden .virtfs_metadata directory. Directories exported by this security model cannot
-interact with other unix tools. "none" security model is same as
-passthrough except the sever won't report failures if it fails to
-set file attributes like ownership. Security model is mandatory only
-for local fsdriver. Other fsdrivers (like proxy) don't take security
-model as a parameter.
-@item writeout=@var{writeout}
-This is an optional argument. The only supported value is "immediate".
-This means that host page cache will be used to read and write data but
-write notification will be sent to the guest only when the data has been
-reported as written by the storage subsystem.
-@item readonly
-Enables exporting 9p share as a readonly mount for guests. By default
-read-write access is given.
-@item socket=@var{socket}
-Enables proxy filesystem driver to use passed socket file for
-communicating with virtfs-proxy-helper(1). Usually a helper like libvirt
-will create socketpair and pass one of the fds as sock_fd.
-@item sock_fd
-Enables proxy filesystem driver to use passed 'sock_fd' as the socket
-descriptor for interfacing with virtfs-proxy-helper(1).
-@item fmode=@var{fmode}
-Specifies the default mode for newly created files on the host. Works only
-with security models "mapped-xattr" and "mapped-file".
-@item dmode=@var{dmode}
-Specifies the default mode for newly created directories on the host. Works
-only with security models "mapped-xattr" and "mapped-file".
-@item mount_tag=@var{mount_tag}
-Specifies the tag name to be used by the guest to mount this export point.
-@item multidevs=@var{multidevs}
-Specifies how to deal with multiple devices being shared with a 9p export.
-Supported behaviours are either "remap", "forbid" or "warn". The latter is
-the default behaviour on which virtfs 9p expects only one device to be
-shared with the same export, and if more than one device is shared and
-accessed via the same 9p export then only a warning message is logged
-(once) by qemu on host side. In order to avoid file ID collisions on guest
-you should either create a separate virtfs export for each device to be
-shared with guests (recommended way) or you might use "remap" instead which
-allows you to share multiple devices with only one export instead, which is
-achieved by remapping the original inode numbers from host to guest in a
-way that would prevent such collisions. Remapping inodes in such use cases
-is required because the original device IDs from host are never passed and
-exposed on guest. Instead all files of an export shared with virtfs always
-share the same device id on guest. So two files with identical inode
-numbers but from actually different devices on host would otherwise cause a
-file ID collision and hence potential misbehaviours on guest. "forbid" on
-the other hand assumes like "warn" that only one device is shared by the
-same export, however it will not only log a warning message but also
-deny access to additional devices on guest. Note though that "forbid" does
-currently not block all possible file access operations (e.g. readdir()
-would still return entries from other devices).
-@end table
-ETEXI
+SRST
+``-virtfs local,path=path,mount_tag=mount_tag ,security_model=security_model[,writeout=writeout][,readonly] [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]``
+ \
+``-virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=writeout][,readonly]``
+ \
+``-virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=writeout][,readonly]``
+ \
+``-virtfs synth,mount_tag=mount_tag``
+ Define a new filesystem device and expose it to the guest using a
+ virtio-9p-device. The general form of a Virtual File system
+ pass-through options are:
+
+ ``local``
+ Accesses to the filesystem are done by QEMU.
+
+ ``proxy``
+ Accesses to the filesystem are done by virtfs-proxy-helper(1).
+
+ ``synth``
+ Synthetic filesystem, only used by QTests.
+
+ ``id=id``
+ Specifies identifier for the filesystem device
+
+ ``path=path``
+ Specifies the export path for the file system device. Files
+ under this path will be available to the 9p client on the guest.
+
+ ``security_model=security_model``
+ Specifies the security model to be used for this export path.
+ Supported security models are "passthrough", "mapped-xattr",
+ "mapped-file" and "none". In "passthrough" security model, files
+ are stored using the same credentials as they are created on the
+ guest. This requires QEMU to run as root. In "mapped-xattr"
+ security model, some of the file attributes like uid, gid, mode
+ bits and link target are stored as file attributes. For
+ "mapped-file" these attributes are stored in the hidden
+ .virtfs\_metadata directory. Directories exported by this
+ security model cannot interact with other unix tools. "none"
+ security model is same as passthrough except the sever won't
+ report failures if it fails to set file attributes like
+ ownership. Security model is mandatory only for local fsdriver.
+ Other fsdrivers (like proxy) don't take security model as a
+ parameter.
+
+ ``writeout=writeout``
+ This is an optional argument. The only supported value is
+ "immediate". This means that host page cache will be used to
+ read and write data but write notification will be sent to the
+ guest only when the data has been reported as written by the
+ storage subsystem.
+
+ ``readonly``
+ Enables exporting 9p share as a readonly mount for guests. By
+ default read-write access is given.
+
+ ``socket=socket``
+ Enables proxy filesystem driver to use passed socket file for
+ communicating with virtfs-proxy-helper(1). Usually a helper like
+ libvirt will create socketpair and pass one of the fds as
+ sock\_fd.
+
+ ``sock_fd``
+ Enables proxy filesystem driver to use passed 'sock\_fd' as the
+ socket descriptor for interfacing with virtfs-proxy-helper(1).
+
+ ``fmode=fmode``
+ Specifies the default mode for newly created files on the host.
+ Works only with security models "mapped-xattr" and
+ "mapped-file".
+
+ ``dmode=dmode``
+ Specifies the default mode for newly created directories on the
+ host. Works only with security models "mapped-xattr" and
+ "mapped-file".
+
+ ``mount_tag=mount_tag``
+ Specifies the tag name to be used by the guest to mount this
+ export point.
+
+ ``multidevs=multidevs``
+ Specifies how to deal with multiple devices being shared with a
+ 9p export. Supported behaviours are either "remap", "forbid" or
+ "warn". The latter is the default behaviour on which virtfs 9p
+ expects only one device to be shared with the same export, and
+ if more than one device is shared and accessed via the same 9p
+ export then only a warning message is logged (once) by qemu on
+ host side. In order to avoid file ID collisions on guest you
+ should either create a separate virtfs export for each device to
+ be shared with guests (recommended way) or you might use "remap"
+ instead which allows you to share multiple devices with only one
+ export instead, which is achieved by remapping the original
+ inode numbers from host to guest in a way that would prevent
+ such collisions. Remapping inodes in such use cases is required
+ because the original device IDs from host are never passed and
+ exposed on guest. Instead all files of an export shared with
+ virtfs always share the same device id on guest. So two files
+ with identical inode numbers but from actually different devices
+ on host would otherwise cause a file ID collision and hence
+ potential misbehaviours on guest. "forbid" on the other hand
+ assumes like "warn" that only one device is shared by the same
+ export, however it will not only log a warning message but also
+ deny access to additional devices on guest. Note though that
+ "forbid" does currently not block all possible file access
+ operations (e.g. readdir() would still return entries from other
+ devices).
+ERST
DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
"-iscsi [user=user][,password=password]\n"
" [,timeout=timeout]\n"
" iSCSI session parameters\n", QEMU_ARCH_ALL)
-STEXI
-@item -iscsi
-@findex -iscsi
-Configure iSCSI session parameters.
-ETEXI
+SRST
+``-iscsi``
+ Configure iSCSI session parameters.
+ERST
-STEXI
-@end table
-ETEXI
DEFHEADING()
DEFHEADING(USB options:)
-STEXI
-@table @option
-ETEXI
DEF("usb", 0, QEMU_OPTION_usb,
"-usb enable on-board USB host controller (if not enabled by default)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -usb
-@findex -usb
-Enable USB emulation on machine types with an on-board USB host controller (if
-not enabled by default). Note that on-board USB host controllers may not
-support USB 3.0. In this case @option{-device qemu-xhci} can be used instead
-on machines with PCI.
-ETEXI
+SRST
+``-usb``
+ Enable USB emulation on machine types with an on-board USB host
+ controller (if not enabled by default). Note that on-board USB host
+ controllers may not support USB 3.0. In this case
+ ``-device qemu-xhci`` can be used instead on machines with PCI.
+ERST
DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
"-usbdevice name add the host or guest USB device 'name'\n",
QEMU_ARCH_ALL)
-STEXI
-
-@item -usbdevice @var{devname}
-@findex -usbdevice
-Add the USB device @var{devname}. Note that this option is deprecated,
-please use @code{-device usb-...} instead. @xref{usb_devices}.
-
-@table @option
-
-@item mouse
-Virtual Mouse. This will override the PS/2 mouse emulation when activated.
-
-@item tablet
-Pointer device that uses absolute coordinates (like a touchscreen). This
-means QEMU is able to report the mouse position without having to grab the
-mouse. Also overrides the PS/2 mouse emulation when activated.
+SRST
+``-usbdevice devname``
+ Add the USB device devname. Note that this option is deprecated,
+ please use ``-device usb-...`` instead. See
+ :ref:`usb_005fdevices`.
+
+ ``mouse``
+ Virtual Mouse. This will override the PS/2 mouse emulation when
+ activated.
+
+ ``tablet``
+ Pointer device that uses absolute coordinates (like a
+ touchscreen). This means QEMU is able to report the mouse
+ 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.
+ERST
-@item braille
-Braille device. This will use BrlAPI to display the braille output on a real
-or fake device.
-
-@end table
-ETEXI
-
-STEXI
-@end table
-ETEXI
DEFHEADING()
DEFHEADING(Display options:)
-STEXI
-@table @option
-ETEXI
DEF("display", HAS_ARG, QEMU_OPTION_display,
#if defined(CONFIG_SPICE)
"\"-display none\"\n"
#endif
, QEMU_ARCH_ALL)
-STEXI
-@item -display @var{type}
-@findex -display
-Select type of display to use. This option is a replacement for the
-old style -sdl/-curses/... options. Valid values for @var{type} are
-@table @option
-@item sdl
-Display video output via SDL (usually in a separate graphics
-window; see the SDL documentation for other possibilities).
-@item curses
-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
-device is in graphical mode or if the graphics device does not support
-a text mode. Generally only the VGA device models support text mode.
-The font charset used by the guest can be specified with the
-@code{charset} option, for example @code{charset=CP850} for IBM CP850
-encoding. The default is @code{CP437}.
-@item none
-Do not display video output. The guest will still see an emulated
-graphics card, but its output will not be displayed to the QEMU
-user. This option differs from the -nographic option in that it
-only affects what is done with video output; -nographic also changes
-the destination of the serial and parallel port data.
-@item 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.
-@item vnc
-Start a VNC server on display <arg>
-@item 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.
-@item 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)
-@end table
-ETEXI
+SRST
+``-display type``
+ Select type of display to use. This option is a replacement for the
+ old style -sdl/-curses/... options. Use ``-display help`` to list
+ the available display types. Valid values for type are
+
+ ``sdl``
+ Display video output via SDL (usually in a separate graphics
+ window; see the SDL documentation for other possibilities).
+
+ ``curses``
+ 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
+ device is in graphical mode or if the graphics device does not
+ support a text mode. Generally only the VGA device models
+ support text mode. The font charset used by the guest can be
+ specified with the ``charset`` option, for example
+ ``charset=CP850`` for IBM CP850 encoding. The default is
+ ``CP437``.
+
+ ``none``
+ Do not display video output. The guest will still see an
+ emulated graphics card, but its output will not be displayed to
+ the QEMU user. This option differs from the -nographic option in
+ 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,
"-nographic disable graphical output and redirect serial I/Os to console\n",
QEMU_ARCH_ALL)
-STEXI
-@item -nographic
-@findex -nographic
-Normally, if QEMU is compiled with graphical window support, it displays
-output such as guest graphics, guest console, and the QEMU monitor in a
-window. With this option, you can totally disable graphical output so
-that QEMU is a simple command line application. The emulated serial port
-is redirected on the console and muxed with the monitor (unless
-redirected elsewhere explicitly). Therefore, you can still use QEMU to
-debug a Linux kernel with a serial console. Use @key{C-a h} for help on
-switching between the console and monitor.
-ETEXI
+SRST
+``-nographic``
+ Normally, if QEMU is compiled with graphical window support, it
+ displays output such as guest graphics, guest console, and the QEMU
+ monitor in a window. With this option, you can totally disable
+ graphical output so that QEMU is a simple command line application.
+ The emulated serial port is redirected on the console and muxed with
+ the monitor (unless redirected elsewhere explicitly). Therefore, you
+ can still use QEMU to debug a Linux kernel with a serial console.
+ Use C-a h for help on switching between the console and monitor.
+ERST
DEF("curses", 0, QEMU_OPTION_curses,
"-curses shorthand for -display curses\n",
QEMU_ARCH_ALL)
-STEXI
-@item -curses
-@findex -curses
-Normally, if QEMU is compiled with graphical window support, it displays
-output such as guest graphics, guest console, and the QEMU monitor in a
-window. With this option, QEMU can display the VGA output when in text
-mode using a curses/ncurses interface. Nothing is displayed in graphical
-mode.
-ETEXI
+SRST
+``-curses``
+ Normally, if QEMU is compiled with graphical window support, it
+ displays output such as guest graphics, guest console, and the QEMU
+ monitor in a window. With this option, QEMU can display the VGA
+ output when in text mode using a curses/ncurses interface. Nothing
+ is displayed in graphical mode.
+ERST
DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
"-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -alt-grab
-@findex -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).
-ETEXI
+SRST
+``-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).
+ERST
DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
"-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -ctrl-grab
-@findex -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).
-ETEXI
+SRST
+``-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).
+ERST
DEF("no-quit", 0, QEMU_OPTION_no_quit,
"-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
-STEXI
-@item -no-quit
-@findex -no-quit
-Disable SDL window close capability.
-ETEXI
+SRST
+``-no-quit``
+ Disable SDL window close capability.
+ERST
DEF("sdl", 0, QEMU_OPTION_sdl,
"-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL)
-STEXI
-@item -sdl
-@findex -sdl
-Enable SDL.
-ETEXI
+SRST
+``-sdl``
+ Enable SDL.
+ERST
DEF("spice", HAS_ARG, QEMU_OPTION_spice,
"-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
" enable spice\n"
" at least one of {port, tls-port} is mandatory\n",
QEMU_ARCH_ALL)
-STEXI
-@item -spice @var{option}[,@var{option}[,...]]
-@findex -spice
-Enable the spice remote desktop protocol. Valid options are
-
-@table @option
-
-@item port=<nr>
-Set the TCP port spice is listening on for plaintext channels.
+SRST
+``-spice option[,option[,...]]``
+ Enable the spice remote desktop protocol. Valid options are
-@item addr=<addr>
-Set the IP address spice is listening on. Default is any address.
+ ``port=<nr>``
+ Set the TCP port spice is listening on for plaintext channels.
-@item ipv4
-@itemx ipv6
-@itemx unix
-Force using the specified IP version.
+ ``addr=<addr>``
+ Set the IP address spice is listening on. Default is any
+ address.
-@item password=<secret>
-Set the password you need to authenticate.
+ ``ipv4``; \ ``ipv6``; \ ``unix``
+ Force using the specified IP version.
-@item sasl
-Require that the client use SASL to authenticate with the spice.
-The exact choice of authentication method used is controlled from the
-system / user's SASL configuration file for the 'qemu' service. This
-is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
-unprivileged user, an environment variable SASL_CONF_PATH can be used
-to make it search alternate locations for the service config.
-While some SASL auth methods can also provide data encryption (eg GSSAPI),
-it is recommended that SASL always be combined with the 'tls' and
-'x509' settings to enable use of SSL and server certificates. This
-ensures a data encryption preventing compromise of authentication
-credentials.
+ ``password=<secret>``
+ Set the password you need to authenticate.
-@item disable-ticketing
-Allow client connects without authentication.
+ ``sasl``
+ Require that the client use SASL to authenticate with the spice.
+ The exact choice of authentication method used is controlled
+ from the system / user's SASL configuration file for the 'qemu'
+ service. This is typically found in /etc/sasl2/qemu.conf. If
+ running QEMU as an unprivileged user, an environment variable
+ SASL\_CONF\_PATH can be used to make it search alternate
+ locations for the service config. While some SASL auth methods
+ can also provide data encryption (eg GSSAPI), it is recommended
+ that SASL always be combined with the 'tls' and 'x509' settings
+ to enable use of SSL and server certificates. This ensures a
+ data encryption preventing compromise of authentication
+ credentials.
-@item disable-copy-paste
-Disable copy paste between the client and the guest.
+ ``disable-ticketing``
+ Allow client connects without authentication.
-@item disable-agent-file-xfer
-Disable spice-vdagent based file-xfer between the client and the guest.
+ ``disable-copy-paste``
+ Disable copy paste between the client and the guest.
-@item tls-port=<nr>
-Set the TCP port spice is listening on for encrypted channels.
+ ``disable-agent-file-xfer``
+ Disable spice-vdagent based file-xfer between the client and the
+ guest.
-@item x509-dir=<dir>
-Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
+ ``tls-port=<nr>``
+ Set the TCP port spice is listening on for encrypted channels.
-@item x509-key-file=<file>
-@itemx x509-key-password=<file>
-@itemx x509-cert-file=<file>
-@itemx x509-cacert-file=<file>
-@itemx x509-dh-key-file=<file>
-The x509 file names can also be configured individually.
+ ``x509-dir=<dir>``
+ Set the x509 file directory. Expects same filenames as -vnc
+ $display,x509=$dir
-@item tls-ciphers=<list>
-Specify which ciphers to use.
+ ``x509-key-file=<file>``; \ ``x509-key-password=<file>``; \ ``x509-cert-file=<file>``; \ ``x509-cacert-file=<file>``; \ ``x509-dh-key-file=<file>``
+ The x509 file names can also be configured individually.
-@item tls-channel=[main|display|cursor|inputs|record|playback]
-@itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
-Force specific channel to be used with or without TLS encryption. The
-options can be specified multiple times to configure multiple
-channels. The special name "default" can be used to set the default
-mode. For channels which are not explicitly forced into one mode the
-spice client is allowed to pick tls/plaintext as he pleases.
+ ``tls-ciphers=<list>``
+ Specify which ciphers to use.
-@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
-Configure image compression (lossless).
-Default is auto_glz.
+ ``tls-channel=[main|display|cursor|inputs|record|playback]``; \ ``plaintext-channel=[main|display|cursor|inputs|record|playback]``
+ Force specific channel to be used with or without TLS
+ encryption. The options can be specified multiple times to
+ configure multiple channels. The special name "default" can be
+ used to set the default mode. For channels which are not
+ explicitly forced into one mode the spice client is allowed to
+ pick tls/plaintext as he pleases.
-@item jpeg-wan-compression=[auto|never|always]
-@itemx zlib-glz-wan-compression=[auto|never|always]
-Configure wan image compression (lossy for slow links).
-Default is auto.
+ ``image-compression=[auto_glz|auto_lz|quic|glz|lz|off]``
+ Configure image compression (lossless). Default is auto\_glz.
-@item streaming-video=[off|all|filter]
-Configure video stream detection. Default is off.
+ ``jpeg-wan-compression=[auto|never|always]``; \ ``zlib-glz-wan-compression=[auto|never|always]``
+ Configure wan image compression (lossy for slow links). Default
+ is auto.
-@item agent-mouse=[on|off]
-Enable/disable passing mouse events via vdagent. Default is on.
+ ``streaming-video=[off|all|filter]``
+ Configure video stream detection. Default is off.
-@item playback-compression=[on|off]
-Enable/disable audio stream compression (using celt 0.5.1). Default is on.
+ ``agent-mouse=[on|off]``
+ Enable/disable passing mouse events via vdagent. Default is on.
-@item seamless-migration=[on|off]
-Enable/disable spice seamless migration. Default is off.
+ ``playback-compression=[on|off]``
+ Enable/disable audio stream compression (using celt 0.5.1).
+ Default is on.
-@item gl=[on|off]
-Enable/disable OpenGL context. Default is off.
+ ``seamless-migration=[on|off]``
+ Enable/disable spice seamless migration. Default is off.
-@item rendernode=<file>
-DRM render node for OpenGL rendering. If not specified, it will pick
-the first available. (Since 2.9)
+ ``gl=[on|off]``
+ Enable/disable OpenGL context. Default is off.
-@end table
-ETEXI
+ ``rendernode=<file>``
+ DRM render node for OpenGL rendering. If not specified, it will
+ pick the first available. (Since 2.9)
+ERST
DEF("portrait", 0, QEMU_OPTION_portrait,
"-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -portrait
-@findex -portrait
-Rotate graphical output 90 deg left (only PXA LCD).
-ETEXI
+SRST
+``-portrait``
+ Rotate graphical output 90 deg left (only PXA LCD).
+ERST
DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
"-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -rotate @var{deg}
-@findex -rotate
-Rotate graphical output some deg left (only PXA LCD).
-ETEXI
+SRST
+``-rotate deg``
+ Rotate graphical output some deg left (only PXA LCD).
+ERST
DEF("vga", HAS_ARG, QEMU_OPTION_vga,
"-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
" select video card type\n", QEMU_ARCH_ALL)
-STEXI
-@item -vga @var{type}
-@findex -vga
-Select type of VGA card to emulate. Valid values for @var{type} are
-@table @option
-@item cirrus
-Cirrus Logic GD5446 Video card. All Windows versions starting from
-Windows 95 should recognize and use this graphic card. For optimal
-performances, use 16 bit color depth in the guest and the host OS.
-(This card was the default before QEMU 2.2)
-@item std
-Standard VGA card with Bochs VBE extensions. If your guest OS
-supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
-to use high resolution modes (>= 1280x1024x16) then you should use
-this option. (This card is the default since QEMU 2.2)
-@item vmware
-VMWare SVGA-II compatible adapter. Use it if you have sufficiently
-recent XFree86/XOrg server or Windows guest with a driver for this
-card.
-@item qxl
-QXL paravirtual graphic card. It is VGA compatible (including VESA
-2.0 VBE support). Works best with qxl guest drivers installed though.
-Recommended choice when using the spice protocol.
-@item tcx
-(sun4m only) Sun TCX framebuffer. This is the default framebuffer for
-sun4m machines and offers both 8-bit and 24-bit colour depths at a
-fixed resolution of 1024x768.
-@item cg3
-(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
-for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
-resolutions aimed at people wishing to run older Solaris versions.
-@item virtio
-Virtio VGA card.
-@item none
-Disable VGA card.
-@end table
-ETEXI
+SRST
+``-vga type``
+ Select type of VGA card to emulate. Valid values for type are
+
+ ``cirrus``
+ Cirrus Logic GD5446 Video card. All Windows versions starting
+ from Windows 95 should recognize and use this graphic card. For
+ optimal performances, use 16 bit color depth in the guest and
+ the host OS. (This card was the default before QEMU 2.2)
+
+ ``std``
+ Standard VGA card with Bochs VBE extensions. If your guest OS
+ supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if
+ you want to use high resolution modes (>= 1280x1024x16) then you
+ should use this option. (This card is the default since QEMU
+ 2.2)
+
+ ``vmware``
+ VMWare SVGA-II compatible adapter. Use it if you have
+ sufficiently recent XFree86/XOrg server or Windows guest with a
+ driver for this card.
+
+ ``qxl``
+ QXL paravirtual graphic card. It is VGA compatible (including
+ VESA 2.0 VBE support). Works best with qxl guest drivers
+ installed though. Recommended choice when using the spice
+ protocol.
+
+ ``tcx``
+ (sun4m only) Sun TCX framebuffer. This is the default
+ framebuffer for sun4m machines and offers both 8-bit and 24-bit
+ colour depths at a fixed resolution of 1024x768.
+
+ ``cg3``
+ (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit
+ framebuffer for sun4m machines available in both 1024x768
+ (OpenBIOS) and 1152x900 (OBP) resolutions aimed at people
+ wishing to run older Solaris versions.
+
+ ``virtio``
+ Virtio VGA card.
+
+ ``none``
+ Disable VGA card.
+ERST
DEF("full-screen", 0, QEMU_OPTION_full_screen,
"-full-screen start in full screen\n", QEMU_ARCH_ALL)
-STEXI
-@item -full-screen
-@findex -full-screen
-Start in full screen.
-ETEXI
+SRST
+``-full-screen``
+ Start in full screen.
+ERST
-DEF("g", 1, QEMU_OPTION_g ,
+DEF("g", HAS_ARG, QEMU_OPTION_g ,
"-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K)
-STEXI
-@item -g @var{width}x@var{height}[x@var{depth}]
-@findex -g
-Set the initial graphical resolution and depth (PPC, SPARC only).
-ETEXI
-
-DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
- "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
-STEXI
-@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
-@findex -vnc
-Normally, if QEMU is compiled with graphical window support, it displays
-output such as guest graphics, guest console, and the QEMU monitor in a
-window. With this option, you can have QEMU listen on VNC display
-@var{display} and redirect the VGA display over the VNC session. It is
-very useful to enable the usb tablet device when using this option
-(option @option{-device usb-tablet}). When using the VNC display, you
-must use the @option{-k} parameter to set the keyboard layout if you are
-not using en-us. Valid syntax for the @var{display} is
-
-@table @option
-
-@item to=@var{L}
-
-With this option, QEMU will try next available VNC @var{display}s, until the
-number @var{L}, if the origianlly defined "-vnc @var{display}" is not
-available, e.g. port 5900+@var{display} is already used by another
-application. By default, to=0.
-
-@item @var{host}:@var{d}
-
-TCP connections will only be allowed from @var{host} on display @var{d}.
-By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
-be omitted in which case the server will accept connections from any host.
-
-@item unix:@var{path}
-
-Connections will be allowed over UNIX domain sockets where @var{path} is the
-location of a unix socket to listen for connections on.
-
-@item none
-
-VNC is initialized but not started. The monitor @code{change} command
-can be used to later start the VNC server.
-
-@end table
-
-Following the @var{display} value there may be one or more @var{option} flags
-separated by commas. Valid options are
-
-@table @option
-
-@item reverse
-
-Connect to a listening VNC client via a ``reverse'' connection. The
-client is specified by the @var{display}. For reverse network
-connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
-is a TCP port number, not a display number.
+SRST
+``-g`` *width*\ ``x``\ *height*\ ``[x``\ *depth*\ ``]``
+ Set the initial graphical resolution and depth (PPC, SPARC only).
-@item websocket
+ For PPC the default is 800x600x32.
-Opens an additional TCP listening port dedicated to VNC Websocket connections.
-If a bare @var{websocket} option is given, the Websocket port is
-5700+@var{display}. An alternative port can be specified with the
-syntax @code{websocket}=@var{port}.
+ For SPARC with the TCX graphics device, the default is 1024x768x8
+ with the option of 1024x768x24. For cgthree, the default is
+ 1024x768x8 with the option of 1152x900x8 for people who wish to use
+ OBP.
+ERST
-If @var{host} is specified connections will only be allowed from this host.
-It is possible to control the websocket listen address independently, using
-the syntax @code{websocket}=@var{host}:@var{port}.
-
-If no TLS credentials are provided, the websocket connection runs in
-unencrypted mode. If TLS credentials are provided, the websocket connection
-requires encrypted client connections.
-
-@item password
-
-Require that password based authentication is used for client connections.
-
-The password must be set separately using the @code{set_password} command in
-the @ref{pcsys_monitor}. The syntax to change your password is:
-@code{set_password <protocol> <password>} where <protocol> could be either
-"vnc" or "spice".
-
-If you would like to change <protocol> password expiration, you should use
-@code{expire_password <protocol> <expiration-time>} where expiration time could
-be one of the following options: now, never, +seconds or UNIX time of
-expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
-to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
-date and time).
-
-You can also use keywords "now" or "never" for the expiration time to
-allow <protocol> password to expire immediately or never expire.
-
-@item tls-creds=@var{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
-and the websocket socket (if enabled). Setting TLS credentials
-will cause the VNC server socket to enable the VeNCrypt auth
-mechanism. The credentials should have been previously created
-using the @option{-object tls-creds} argument.
-
-@item tls-authz=@var{ID}
-
-Provides the ID of the QAuthZ authorization object against which
-the client's x509 distinguished name will validated. This object is
-only resolved at time of use, so can be deleted and recreated on the
-fly while the VNC server is active. If missing, it will default
-to denying access.
-
-@item sasl
-
-Require that the client use SASL to authenticate with the VNC server.
-The exact choice of authentication method used is controlled from the
-system / user's SASL configuration file for the 'qemu' service. This
-is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
-unprivileged user, an environment variable SASL_CONF_PATH can be used
-to make it search alternate locations for the service config.
-While some SASL auth methods can also provide data encryption (eg GSSAPI),
-it is recommended that SASL always be combined with the 'tls' and
-'x509' settings to enable use of SSL and server certificates. This
-ensures a data encryption preventing compromise of authentication
-credentials. See the @ref{vnc_security} section for details on using
-SASL authentication.
-
-@item sasl-authz=@var{ID}
-
-Provides the ID of the QAuthZ authorization object against which
-the client's SASL username will validated. This object is
-only resolved at time of use, so can be deleted and recreated on the
-fly while the VNC server is active. If missing, it will default
-to denying access.
-
-@item acl
-
-Legacy method for enabling authorization of clients against the
-x509 distinguished name and SASL username. It results in the creation
-of two @code{authz-list} objects with IDs of @code{vnc.username} and
-@code{vnc.x509dname}. The rules for these objects must be configured
-with the HMP ACL commands.
-
-This option is deprecated and should no longer be used. The new
-@option{sasl-authz} and @option{tls-authz} options are a
-replacement.
+DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
+ "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
+SRST
+``-vnc display[,option[,option[,...]]]``
+ Normally, if QEMU is compiled with graphical window support, it
+ displays output such as guest graphics, guest console, and the QEMU
+ monitor in a window. With this option, you can have QEMU listen on
+ VNC display display and redirect the VGA display over the VNC
+ session. It is very useful to enable the usb tablet device when
+ using this option (option ``-device usb-tablet``). When using the
+ VNC display, you must use the ``-k`` parameter to set the keyboard
+ layout if you are not using en-us. Valid syntax for the display is
+
+ ``to=L``
+ With this option, QEMU will try next available VNC displays,
+ until the number L, if the origianlly defined "-vnc display" is
+ not available, e.g. port 5900+display is already used by another
+ application. By default, to=0.
+
+ ``host:d``
+ TCP connections will only be allowed from host on display d. By
+ convention the TCP port is 5900+d. Optionally, host can be
+ omitted in which case the server will accept connections from
+ any host.
+
+ ``unix:path``
+ Connections will be allowed over UNIX domain sockets where path
+ is the location of a unix socket to listen for connections on.
+
+ ``none``
+ VNC is initialized but not started. The monitor ``change``
+ command can be used to later start the VNC server.
+
+ Following the display value there may be one or more option flags
+ separated by commas. Valid options are
+
+ ``reverse``
+ Connect to a listening VNC client via a "reverse" connection.
+ The client is specified by the display. For reverse network
+ connections (host:d,``reverse``), the d argument is a TCP port
+ number, not a display number.
+
+ ``websocket``
+ Opens an additional TCP listening port dedicated to VNC
+ Websocket connections. If a bare websocket option is given, the
+ Websocket port is 5700+display. An alternative port can be
+ specified with the syntax ``websocket``\ =port.
+
+ If host is specified connections will only be allowed from this
+ host. It is possible to control the websocket listen address
+ independently, using the syntax ``websocket``\ =host:port.
+
+ If no TLS credentials are provided, the websocket connection
+ runs in unencrypted mode. If TLS credentials are provided, the
+ websocket connection requires encrypted client connections.
+
+ ``password``
+ Require that password based authentication is used for client
+ connections.
+
+ The password must be set separately using the ``set_password``
+ command in the :ref:`pcsys_005fmonitor`. The
+ syntax to change your password is:
+ ``set_password <protocol> <password>`` where <protocol> could be
+ either "vnc" or "spice".
+
+ If you would like to change <protocol> password expiration, you
+ should use ``expire_password <protocol> <expiration-time>``
+ where expiration time could be one of the following options:
+ now, never, +seconds or UNIX time of expiration, e.g. +60 to
+ make password expire in 60 seconds, or 1335196800 to make
+ password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for
+ this date and time).
+
+ You can also use keywords "now" or "never" for the expiration
+ time to allow <protocol> password to expire immediately or never
+ expire.
+
+ ``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
+ and the websocket socket (if enabled). Setting TLS credentials
+ will cause the VNC server socket to enable the VeNCrypt auth
+ mechanism. The credentials should have been previously created
+ using the ``-object tls-creds`` argument.
+
+ ``tls-authz=ID``
+ Provides the ID of the QAuthZ authorization object against which
+ the client's x509 distinguished name will validated. This object
+ is only resolved at time of use, so can be deleted and recreated
+ on the fly while the VNC server is active. If missing, it will
+ default to denying access.
+
+ ``sasl``
+ Require that the client use SASL to authenticate with the VNC
+ server. The exact choice of authentication method used is
+ controlled from the system / user's SASL configuration file for
+ the 'qemu' service. This is typically found in
+ /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user,
+ an environment variable SASL\_CONF\_PATH can be used to make it
+ search alternate locations for the service config. While some
+ SASL auth methods can also provide data encryption (eg GSSAPI),
+ it is recommended that SASL always be combined with the 'tls'
+ and 'x509' settings to enable use of SSL and server
+ certificates. This ensures a data encryption preventing
+ compromise of authentication credentials. See the
+ :ref:`vnc_005fsecurity` section for details on
+ using SASL authentication.
+
+ ``sasl-authz=ID``
+ Provides the ID of the QAuthZ authorization object against which
+ the client's SASL username will validated. This object is only
+ resolved at time of use, so can be deleted and recreated on the
+ fly while the VNC server is active. If missing, it will default
+ to denying access.
+
+ ``acl``
+ Legacy method for enabling authorization of clients against the
+ x509 distinguished name and SASL username. It results in the
+ creation of two ``authz-list`` objects with IDs of
+ ``vnc.username`` and ``vnc.x509dname``. The rules for these
+ objects must be configured with the HMP ACL commands.
+
+ This option is deprecated and should no longer be used. The new
+ ``sasl-authz`` and ``tls-authz`` options are a replacement.
+
+ ``lossy``
+ Enable lossy compression methods (gradient, JPEG, ...). If this
+ option is set, VNC client may receive lossy framebuffer updates
+ depending on its encoding settings. Enabling this option can
+ save a lot of bandwidth at the expense of quality.
+
+ ``non-adaptive``
+ Disable adaptive encodings. Adaptive encodings are enabled by
+ default. An adaptive encoding will try to detect frequently
+ updated screen regions, and send updates in these regions using
+ a lossy encoding (like JPEG). This can be really helpful to save
+ bandwidth when playing videos. Disabling adaptive encodings
+ restores the original static behavior of encodings like Tight.
+
+ ``share=[allow-exclusive|force-shared|ignore]``
+ Set display sharing policy. 'allow-exclusive' allows clients to
+ ask for exclusive access. As suggested by the rfb spec this is
+ implemented by dropping other connections. Connecting multiple
+ clients in parallel requires all clients asking for a shared
+ session (vncviewer: -shared switch). This is the default.
+ 'force-shared' disables exclusive client access. Useful for
+ shared desktop sessions, where you don't want someone forgetting
+ specify -shared disconnect everybody else. 'ignore' completely
+ ignores the shared flag and allows everybody connect
+ unconditionally. Doesn't conform to the rfb spec but is
+ traditional QEMU behavior.
+
+ ``key-delay-ms``
+ Set keyboard delay, for key down and key up events, in
+ milliseconds. Default is 10. Keyboards are low-bandwidth
+ devices, so this slowdown can help the device and guest to keep
+ up and not lose events in case events are arriving in bulk.
+ Possible causes for the latter are flaky network connections, or
+ scripts for automated testing.
+
+ ``audiodev=audiodev``
+ Use the specified audiodev when the VNC client requests audio
+ transmission. When not using an -audiodev argument, this option
+ must be omitted, otherwise is must be present and specify a
+ valid audiodev.
+ERST
-@item lossy
-
-Enable lossy compression methods (gradient, JPEG, ...). If this
-option is set, VNC client may receive lossy framebuffer updates
-depending on its encoding settings. Enabling this option can save
-a lot of bandwidth at the expense of quality.
-
-@item non-adaptive
-
-Disable adaptive encodings. Adaptive encodings are enabled by default.
-An adaptive encoding will try to detect frequently updated screen regions,
-and send updates in these regions using a lossy encoding (like JPEG).
-This can be really helpful to save bandwidth when playing videos. Disabling
-adaptive encodings restores the original static behavior of encodings
-like Tight.
-
-@item share=[allow-exclusive|force-shared|ignore]
-
-Set display sharing policy. 'allow-exclusive' allows clients to ask
-for exclusive access. As suggested by the rfb spec this is
-implemented by dropping other connections. Connecting multiple
-clients in parallel requires all clients asking for a shared session
-(vncviewer: -shared switch). This is the default. 'force-shared'
-disables exclusive client access. Useful for shared desktop sessions,
-where you don't want someone forgetting specify -shared disconnect
-everybody else. 'ignore' completely ignores the shared flag and
-allows everybody connect unconditionally. Doesn't conform to the rfb
-spec but is traditional QEMU behavior.
-
-@item key-delay-ms
-
-Set keyboard delay, for key down and key up events, in milliseconds.
-Default is 10. Keyboards are low-bandwidth devices, so this slowdown
-can help the device and guest to keep up and not lose events in case
-events are arriving in bulk. Possible causes for the latter are flaky
-network connections, or scripts for automated testing.
-
-@item audiodev=@var{audiodev}
-
-Use the specified @var{audiodev} when the VNC client requests audio
-transmission. When not using an -audiodev argument, this option must
-be omitted, otherwise is must be present and specify a valid audiodev.
-
-@end table
-ETEXI
-
-STEXI
-@end table
-ETEXI
ARCHHEADING(, QEMU_ARCH_I386)
ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
-STEXI
-@table @option
-ETEXI
DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
"-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
QEMU_ARCH_I386)
-STEXI
-@item -win2k-hack
-@findex -win2k-hack
-Use it when installing Windows 2000 to avoid a disk full bug. After
-Windows 2000 is installed, you no longer need this option (this option
-slows down the IDE transfers).
-ETEXI
+SRST
+``-win2k-hack``
+ Use it when installing Windows 2000 to avoid a disk full bug. After
+ Windows 2000 is installed, you no longer need this option (this
+ option slows down the IDE transfers).
+ERST
DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
"-no-fd-bootchk disable boot signature checking for floppy disks\n",
QEMU_ARCH_I386)
-STEXI
-@item -no-fd-bootchk
-@findex -no-fd-bootchk
-Disable boot signature checking for floppy disks in BIOS. May
-be needed to boot from old floppy disks.
-ETEXI
+SRST
+``-no-fd-bootchk``
+ Disable boot signature checking for floppy disks in BIOS. May be
+ needed to boot from old floppy disks.
+ERST
DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
"-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
-STEXI
-@item -no-acpi
-@findex -no-acpi
-Disable ACPI (Advanced Configuration and Power Interface) support. Use
-it if your guest OS complains about ACPI problems (PC target machine
-only).
-ETEXI
+SRST
+``-no-acpi``
+ Disable ACPI (Advanced Configuration and Power Interface) support.
+ Use it if your guest OS complains about ACPI problems (PC target
+ machine only).
+ERST
DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
"-no-hpet disable HPET\n", QEMU_ARCH_I386)
-STEXI
-@item -no-hpet
-@findex -no-hpet
-Disable HPET support.
-ETEXI
+SRST
+``-no-hpet``
+ Disable HPET support.
+ERST
DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
"-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n][,asl_compiler_id=str][,asl_compiler_rev=n][,{data|file}=file1[:file2]...]\n"
" ACPI table description\n", QEMU_ARCH_I386)
-STEXI
-@item -acpitable [sig=@var{str}][,rev=@var{n}][,oem_id=@var{str}][,oem_table_id=@var{str}][,oem_rev=@var{n}] [,asl_compiler_id=@var{str}][,asl_compiler_rev=@var{n}][,data=@var{file1}[:@var{file2}]...]
-@findex -acpitable
-Add ACPI table with specified header fields and context from specified files.
-For file=, take whole ACPI table from the specified files, including all
-ACPI headers (possible overridden by other options).
-For data=, only data
-portion of the table is used, all header information is specified in the
-command line.
-If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
-fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order
-to ensure the field matches required by the Microsoft SLIC spec and the ACPI
-spec.
-ETEXI
+SRST
+``-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n] [,asl_compiler_id=str][,asl_compiler_rev=n][,data=file1[:file2]...]``
+ Add ACPI table with specified header fields and context from
+ specified files. For file=, take whole ACPI table from the specified
+ files, including all ACPI headers (possible overridden by other
+ options). For data=, only data portion of the table is used, all
+ header information is specified in the command line. If a SLIC table
+ is supplied to QEMU, then the SLIC's oem\_id and oem\_table\_id
+ fields will override the same in the RSDT and the FADT (a.k.a.
+ FACP), in order to ensure the field matches required by the
+ Microsoft SLIC spec and the ACPI spec.
+ERST
DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
"-smbios file=binary\n"
" [,asset=str][,part=str][,speed=%d]\n"
" specify SMBIOS type 17 fields\n",
QEMU_ARCH_I386 | QEMU_ARCH_ARM)
-STEXI
-@item -smbios file=@var{binary}
-@findex -smbios
-Load SMBIOS entry from binary file.
+SRST
+``-smbios file=binary``
+ Load SMBIOS entry from binary file.
-@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off]
-Specify SMBIOS type 0 fields
+``-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]``
+ Specify SMBIOS type 0 fields
-@item -smbios type=1[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,uuid=@var{uuid}][,sku=@var{str}][,family=@var{str}]
-Specify SMBIOS type 1 fields
+``-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str][,uuid=uuid][,sku=str][,family=str]``
+ Specify SMBIOS type 1 fields
-@item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}]
-Specify SMBIOS type 2 fields
+``-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str]``
+ Specify SMBIOS type 2 fields
-@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}]
-Specify SMBIOS type 3 fields
+``-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str]``
+ Specify SMBIOS type 3 fields
-@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}]
-Specify SMBIOS type 4 fields
+``-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str]``
+ Specify SMBIOS type 4 fields
-@item -smbios type=17[,loc_pfx=@var{str}][,bank=@var{str}][,manufacturer=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}][,speed=@var{%d}]
-Specify SMBIOS type 17 fields
-ETEXI
+``-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]``
+ Specify SMBIOS type 17 fields
+ERST
-STEXI
-@end table
-ETEXI
DEFHEADING()
DEFHEADING(Network options:)
-STEXI
-@table @option
-ETEXI
DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
#ifdef CONFIG_SLIRP
" Linux kernel 3.3+ as well as most routers can talk\n"
" L2TPv3. This transport allows connecting a VM to a VM,\n"
" VM to a router and even VM to Host. It is a nearly-universal\n"
- " standard (RFC3391). Note - this implementation uses static\n"
+ " standard (RFC3931). Note - this implementation uses static\n"
" pre-configured tunnels (same as the Linux kernel).\n"
" use 'src=' to specify source address\n"
" use 'dst=' to specify destination address\n"
"socket][,option][,option][,...]\n"
" old way to initialize a host network interface\n"
" (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
-STEXI
-@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
-@findex -nic
-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 @option{-netdev} options below.
-The guest NIC model can be set with @option{model=@var{modelname}}.
-Use @option{model=help} to list the available device types.
-The hardware MAC address can be set with @option{mac=@var{macaddr}}.
-
-The following two example do exactly the same, to show how @option{-nic} can
-be used to shorten the command line length (note that the e1000 is the default
-on i386, so the @option{model=e1000} parameter could even be omitted here, too):
-@example
-@value{qemu_system} -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
-@value{qemu_system} -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
-@end example
-
-@item -nic none
-Indicate that no network devices should be configured. It is used to override
-the default configuration (default NIC with ``user'' host network backend)
-which is activated if no other networking options are provided.
-
-@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...]
-@findex -netdev
-Configure user mode host network backend which requires no administrator
-privilege to run. Valid options are:
-
-@table @option
-@item id=@var{id}
-Assign symbolic name for use in monitor commands.
-
-@item ipv4=on|off and ipv6=on|off
-Specify that either IPv4 or IPv6 must be enabled. If neither is specified
-both protocols are enabled.
-
-@item net=@var{addr}[/@var{mask}]
-Set IP network address the guest will see. Optionally specify the netmask,
-either in the form a.b.c.d or as number of valid top-most bits. Default is
-10.0.2.0/24.
-
-@item host=@var{addr}
-Specify the guest-visible address of the host. Default is the 2nd IP in the
-guest network, i.e. x.x.x.2.
-
-@item ipv6-net=@var{addr}[/@var{int}]
-Set IPv6 network address the guest will see (default is fec0::/64). The
-network prefix is given in the usual hexadecimal IPv6 address
-notation. The prefix size is optional, and is given as the number of
-valid top-most bits (default is 64).
-
-@item ipv6-host=@var{addr}
-Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in
-the guest network, i.e. xxxx::2.
-
-@item restrict=on|off
-If this option is enabled, the guest will be isolated, i.e. it will not be
-able to contact the host and no guest IP packets will be routed over the host
-to the outside. This option does not affect any explicitly set forwarding rules.
-
-@item hostname=@var{name}
-Specifies the client hostname reported by the built-in DHCP server.
-
-@item dhcpstart=@var{addr}
-Specify the first of the 16 IPs the built-in DHCP server can assign. Default
-is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
-
-@item dns=@var{addr}
-Specify the guest-visible address of the virtual nameserver. The address must
-be different from the host address. Default is the 3rd IP in the guest network,
-i.e. x.x.x.3.
-
-@item ipv6-dns=@var{addr}
-Specify the guest-visible address of the IPv6 virtual nameserver. The address
-must be different from the host address. Default is the 3rd IP in the guest
-network, i.e. xxxx::3.
-
-@item dnssearch=@var{domain}
-Provides an entry for the domain-search list sent by the built-in
-DHCP server. More than one domain suffix can be transmitted by specifying
-this option multiple times. If supported, this will cause the guest to
-automatically try to append the given domain suffix(es) in case a domain name
-can not be resolved.
-
-Example:
-@example
-@value{qemu_system} -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
-@end example
-
-@item domainname=@var{domain}
-Specifies the client domain name reported by the built-in DHCP server.
-
-@item tftp=@var{dir}
-When using the user mode network stack, activate a built-in TFTP
-server. The files in @var{dir} will be exposed as the root of a TFTP server.
-The TFTP client on the guest must be configured in binary mode (use the command
-@code{bin} of the Unix TFTP client).
-
-@item tftp-server-name=@var{name}
-In BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option
-66). This can be used to advise the guest to load boot files or configurations
-from a different server than the host address.
-
-@item bootfile=@var{file}
-When using the user mode network stack, broadcast @var{file} as the BOOTP
-filename. In conjunction with @option{tftp}, this can be used to network boot
-a guest from a local directory.
-
-Example (using pxelinux):
-@example
-@value{qemu_system} -hda linux.img -boot n -device e1000,netdev=n1 \
- -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
-@end example
-
-@item smb=@var{dir}[,smbserver=@var{addr}]
-When using the user mode network stack, activate a built-in SMB
-server so that Windows OSes can access to the host files in @file{@var{dir}}
-transparently. The IP address of the SMB server can be set to @var{addr}. By
-default the 4th IP in the guest network is used, i.e. x.x.x.4.
-
-In the guest Windows OS, the line:
-@example
-10.0.2.4 smbserver
-@end example
-must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
-or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
-
-Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
-
-Note that a SAMBA server must be installed on the host OS.
-
-@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
-Redirect incoming TCP or UDP connections to the host port @var{hostport} to
-the guest IP address @var{guestaddr} on guest port @var{guestport}. If
-@var{guestaddr} is not specified, its value is x.x.x.15 (default first address
-given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
-be bound to a specific host interface. If no connection type is set, TCP is
-used. This option can be given multiple times.
-
-For example, to redirect host X11 connection from screen 1 to guest
-screen 0, use the following:
-
-@example
-# on the host
-@value{qemu_system} -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
-# this host xterm should open in the guest X11 server
-xterm -display :1
-@end example
-
-To redirect telnet connections from host port 5555 to telnet port on
-the guest, use the following:
-
-@example
-# on the host
-@value{qemu_system} -nic user,hostfwd=tcp::5555-:23
-telnet localhost 5555
-@end example
-
-Then when you use on the host @code{telnet localhost 5555}, you
-connect to the guest telnet server.
-
-@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
-@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command}
-Forward guest TCP connections to the IP address @var{server} on port @var{port}
-to the character device @var{dev} or to a program executed by @var{cmd:command}
-which gets spawned for each connection. This option can be given multiple times.
-
-You can either use a chardev directly and have that one used throughout QEMU's
-lifetime, like in the following example:
-
-@example
-# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
-# the guest accesses it
-@value{qemu_system} -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
-@end example
-
-Or you can execute a command on every TCP connection established by the guest,
-so that QEMU behaves similar to an inetd process for that virtual server:
-
-@example
-# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
-# and connect the TCP stream to its stdin/stdout
-@value{qemu_system} -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
-@end example
-
-@end table
-
-@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}]
-Configure a host TAP network backend with ID @var{id}.
-
-Use the network script @var{file} to configure it and the network script
-@var{dfile} to deconfigure it. If @var{name} is not provided, the OS
-automatically provides one. The default network configure script is
-@file{/etc/qemu-ifup} and the default network deconfigure script is
-@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
-to disable script execution.
-
-If running QEMU as an unprivileged user, use the network helper
-@var{helper} to configure the TAP interface and attach it to the bridge.
-The default network helper executable is @file{/path/to/qemu-bridge-helper}
-and the default bridge device is @file{br0}.
-
-@option{fd}=@var{h} can be used to specify the handle of an already
-opened host TAP interface.
-
-Examples:
-
-@example
-#launch a QEMU instance with the default network script
-@value{qemu_system} linux.img -nic tap
-@end example
-
-@example
-#launch a QEMU instance with two NICs, each one connected
-#to a TAP device
-@value{qemu_system} linux.img \
- -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
- -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
-@end example
-
-@example
-#launch a QEMU instance with the default network helper to
-#connect a TAP device to bridge br0
-@value{qemu_system} linux.img -device virtio-net-pci,netdev=n1 \
- -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
-@end example
-
-@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}]
-Connect a host TAP network interface to a host bridge device.
-
-Use the network helper @var{helper} to configure the TAP interface and
-attach it to the bridge. The default network helper executable is
-@file{/path/to/qemu-bridge-helper} and the default bridge
-device is @file{br0}.
-
-Examples:
-
-@example
-#launch a QEMU instance with the default network helper to
-#connect a TAP device to bridge br0
-@value{qemu_system} linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
-@end example
-
-@example
-#launch a QEMU instance with the default network helper to
-#connect a TAP device to bridge qemubr0
-@value{qemu_system} linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
-@end example
-
-@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
-
-This host network backend can be used to connect the guest's network to
-another QEMU virtual machine using a TCP socket connection. If @option{listen}
-is specified, QEMU waits for incoming connections on @var{port}
-(@var{host} is optional). @option{connect} is used to connect to
-another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
-specifies an already opened TCP socket.
-
-Example:
-@example
-# launch a first QEMU instance
-@value{qemu_system} linux.img \
- -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
- -netdev socket,id=n1,listen=:1234
-# connect the network of this instance to the network of the first instance
-@value{qemu_system} linux.img \
- -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
- -netdev socket,id=n2,connect=127.0.0.1:1234
-@end example
-
-@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
-
-Configure a socket host network backend to share the guest's network traffic
-with another QEMU virtual machines using a UDP multicast socket, effectively
-making a bus for every QEMU with same multicast address @var{maddr} and @var{port}.
-NOTES:
-@enumerate
-@item
-Several QEMU can be running on different hosts and share same bus (assuming
-correct multicast setup for these hosts).
-@item
-mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
-@url{http://user-mode-linux.sf.net}.
-@item
-Use @option{fd=h} to specify an already opened UDP multicast socket.
-@end enumerate
-
-Example:
-@example
-# launch one QEMU instance
-@value{qemu_system} linux.img \
- -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
- -netdev socket,id=n1,mcast=230.0.0.1:1234
-# launch another QEMU instance on same "bus"
-@value{qemu_system} linux.img \
- -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
- -netdev socket,id=n2,mcast=230.0.0.1:1234
-# launch yet another QEMU instance on same "bus"
-@value{qemu_system} linux.img \
- -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
- -netdev socket,id=n3,mcast=230.0.0.1:1234
-@end example
-
-Example (User Mode Linux compat.):
-@example
-# launch QEMU instance (note mcast address selected is UML's default)
-@value{qemu_system} linux.img \
- -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
- -netdev socket,id=n1,mcast=239.192.168.1:1102
-# launch UML
-/path/to/linux ubd0=/path/to/root_fs eth0=mcast
-@end example
-
-Example (send packets from host's 1.2.3.4):
-@example
-@value{qemu_system} linux.img \
- -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
- -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
-@end example
-
-@item -netdev l2tpv3,id=@var{id},src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}]
-Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a
-popular protocol to transport Ethernet (and other Layer 2) data frames between
-two systems. It is present in routers, firewalls and the Linux kernel
-(from version 3.3 onwards).
-
-This transport allows a VM to communicate to another VM, router or firewall directly.
-
-@table @option
-@item src=@var{srcaddr}
- source address (mandatory)
-@item dst=@var{dstaddr}
- destination address (mandatory)
-@item udp
- select udp encapsulation (default is ip).
-@item srcport=@var{srcport}
- source udp port.
-@item dstport=@var{dstport}
- destination udp port.
-@item ipv6
- force v6, otherwise defaults to v4.
-@item rxcookie=@var{rxcookie}
-@itemx txcookie=@var{txcookie}
- Cookies are a weak form of security in the l2tpv3 specification.
-Their function is mostly to prevent misconfiguration. By default they are 32
-bit.
-@item cookie64
- Set cookie size to 64 bit instead of the default 32
-@item counter=off
- Force a 'cut-down' L2TPv3 with no counter as in
-draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
-@item pincounter=on
- Work around broken counter handling in peer. This may also help on
-networks which have packet reorder.
-@item offset=@var{offset}
- Add an extra offset between header and data
-@end table
-
-For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
-on the remote Linux host 1.2.3.4:
-@example
-# Setup tunnel on linux host using raw ip as encapsulation
-# on 1.2.3.4
-ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
- encap udp udp_sport 16384 udp_dport 16384
-ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
- 0xFFFFFFFF peer_session_id 0xFFFFFFFF
-ifconfig vmtunnel0 mtu 1500
-ifconfig vmtunnel0 up
-brctl addif br-lan vmtunnel0
-
-
-# on 4.3.2.1
-# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
-
-@value{qemu_system} linux.img -device e1000,netdev=n1 \
- -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
-
-@end example
-
-@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
-Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and
-listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
-and MODE @var{octalmode} to change default ownership and permissions for
-communication port. This option is only available if QEMU has been compiled
-with vde support enabled.
-
-Example:
-@example
-# launch vde switch
-vde_switch -F -sock /tmp/myswitch
-# launch QEMU instance
-@value{qemu_system} linux.img -nic vde,sock=/tmp/myswitch
-@end example
-
-@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n]
-
-Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should
-be a unix domain socket backed one. The vhost-user uses a specifically defined
-protocol to pass vhost ioctl replacement messages to an application on the other
-end of the socket. On non-MSIX guests, the feature can be forced with
-@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to
-be created for multiqueue vhost-user.
-
-Example:
-@example
-qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
- -numa node,memdev=mem \
- -chardev socket,id=chr0,path=/path/to/socket \
- -netdev type=vhost-user,id=net0,chardev=chr0 \
- -device virtio-net-pci,netdev=net0
-@end example
-
-@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}]
-
-Create a hub port on the emulated hub with ID @var{hubid}.
-
-The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a
-single netdev. Alternatively, you can also connect the hubport to another
-netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option.
-
-@item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
-@findex -net
-Legacy option to configure or create an on-board (or machine default) Network
-Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e.
-the default hub), or to the netdev @var{nd}.
-The NIC is an e1000 by default on the PC target. Optionally, the MAC address
-can be changed to @var{mac}, the device address set to @var{addr} (PCI cards
-only), and a @var{name} can be assigned for use in monitor commands.
-Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
-that the card should have; this option currently only affects virtio cards; set
-@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
-NIC is created. QEMU can emulate several different models of network card.
-Use @code{-net nic,model=help} for a list of available devices for your target.
-
-@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}]
-Configure a host network backend (with the options corresponding to the same
-@option{-netdev} option) and connect it to the emulated hub 0 (the default
-hub). Use @var{name} to specify the name of the hub port.
-ETEXI
-
-STEXI
-@end table
-ETEXI
+SRST
+``-nic [tap|bridge|user|l2tpv3|vde|netmap|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
+ ``-netdev`` options below. The guest NIC model can be set with
+ ``model=modelname``. Use ``model=help`` to list the available device
+ types. The hardware MAC address can be set with ``mac=macaddr``.
+
+ The following two example do exactly the same, to show how ``-nic``
+ can be used to shorten the command line length:
+
+ .. parsed-literal::
+
+ |qemu_system| -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
+ |qemu_system| -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
+
+``-nic none``
+ Indicate that no network devices should be configured. It is used to
+ override the default configuration (default NIC with "user" host
+ network backend) which is activated if no other networking options
+ are provided.
+
+``-netdev user,id=id[,option][,option][,...]``
+ Configure user mode host network backend which requires no
+ administrator privilege to run. Valid options are:
+
+ ``id=id``
+ Assign symbolic name for use in monitor commands.
+
+ ``ipv4=on|off and ipv6=on|off``
+ Specify that either IPv4 or IPv6 must be enabled. If neither is
+ specified both protocols are enabled.
+
+ ``net=addr[/mask]``
+ Set IP network address the guest will see. Optionally specify
+ the netmask, either in the form a.b.c.d or as number of valid
+ top-most bits. Default is 10.0.2.0/24.
+
+ ``host=addr``
+ Specify the guest-visible address of the host. Default is the
+ 2nd IP in the guest network, i.e. x.x.x.2.
+
+ ``ipv6-net=addr[/int]``
+ Set IPv6 network address the guest will see (default is
+ fec0::/64). The network prefix is given in the usual hexadecimal
+ IPv6 address notation. The prefix size is optional, and is given
+ as the number of valid top-most bits (default is 64).
+
+ ``ipv6-host=addr``
+ Specify the guest-visible IPv6 address of the host. Default is
+ the 2nd IPv6 in the guest network, i.e. xxxx::2.
+
+ ``restrict=on|off``
+ If this option is enabled, the guest will be isolated, i.e. it
+ will not be able to contact the host and no guest IP packets
+ will be routed over the host to the outside. This option does
+ not affect any explicitly set forwarding rules.
+
+ ``hostname=name``
+ Specifies the client hostname reported by the built-in DHCP
+ server.
+
+ ``dhcpstart=addr``
+ Specify the first of the 16 IPs the built-in DHCP server can
+ assign. Default is the 15th to 31st IP in the guest network,
+ i.e. x.x.x.15 to x.x.x.31.
+
+ ``dns=addr``
+ Specify the guest-visible address of the virtual nameserver. The
+ address must be different from the host address. Default is the
+ 3rd IP in the guest network, i.e. x.x.x.3.
+
+ ``ipv6-dns=addr``
+ Specify the guest-visible address of the IPv6 virtual
+ nameserver. The address must be different from the host address.
+ Default is the 3rd IP in the guest network, i.e. xxxx::3.
+
+ ``dnssearch=domain``
+ Provides an entry for the domain-search list sent by the
+ built-in DHCP server. More than one domain suffix can be
+ transmitted by specifying this option multiple times. If
+ supported, this will cause the guest to automatically try to
+ append the given domain suffix(es) in case a domain name can not
+ be resolved.
+
+ Example:
+
+ .. parsed-literal::
+
+ |qemu_system| -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
+
+ ``domainname=domain``
+ Specifies the client domain name reported by the built-in DHCP
+ server.
+
+ ``tftp=dir``
+ When using the user mode network stack, activate a built-in TFTP
+ server. The files in dir will be exposed as the root of a TFTP
+ server. The TFTP client on the guest must be configured in
+ binary mode (use the command ``bin`` of the Unix TFTP client).
+
+ ``tftp-server-name=name``
+ In BOOTP reply, broadcast name as the "TFTP server name"
+ (RFC2132 option 66). This can be used to advise the guest to
+ load boot files or configurations from a different server than
+ the host address.
+
+ ``bootfile=file``
+ When using the user mode network stack, broadcast file as the
+ BOOTP filename. In conjunction with ``tftp``, this can be used
+ to network boot a guest from a local directory.
+
+ Example (using pxelinux):
+
+ .. parsed-literal::
+
+ |qemu_system| -hda linux.img -boot n -device e1000,netdev=n1 \
+ -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
+
+ ``smb=dir[,smbserver=addr]``
+ When using the user mode network stack, activate a built-in SMB
+ server so that Windows OSes can access to the host files in
+ ``dir`` transparently. The IP address of the SMB server can be
+ set to addr. By default the 4th IP in the guest network is used,
+ i.e. x.x.x.4.
+
+ In the guest Windows OS, the line:
+
+ ::
+
+ 10.0.2.4 smbserver
+
+ must be added in the file ``C:\WINDOWS\LMHOSTS`` (for windows
+ 9x/Me) or ``C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS`` (Windows
+ NT/2000).
+
+ Then ``dir`` can be accessed in ``\\smbserver\qemu``.
+
+ Note that a SAMBA server must be installed on the host OS.
+
+ ``hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport``
+ Redirect incoming TCP or UDP connections to the host port
+ hostport to the guest IP address guestaddr on guest port
+ guestport. If guestaddr is not specified, its value is x.x.x.15
+ (default first address given by the built-in DHCP server). By
+ specifying hostaddr, the rule can be bound to a specific host
+ interface. If no connection type is set, TCP is used. This
+ option can be given multiple times.
+
+ For example, to redirect host X11 connection from screen 1 to
+ guest screen 0, use the following:
+
+ .. parsed-literal::
+
+ # on the host
+ |qemu_system| -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
+ # this host xterm should open in the guest X11 server
+ xterm -display :1
+
+ To redirect telnet connections from host port 5555 to telnet
+ port on the guest, use the following:
+
+ .. parsed-literal::
+
+ # on the host
+ |qemu_system| -nic user,hostfwd=tcp::5555-:23
+ telnet localhost 5555
+
+ Then when you use on the host ``telnet localhost 5555``, you
+ connect to the guest telnet server.
+
+ ``guestfwd=[tcp]:server:port-dev``; \ ``guestfwd=[tcp]:server:port-cmd:command``
+ Forward guest TCP connections to the IP address server on port
+ port to the character device dev or to a program executed by
+ cmd:command which gets spawned for each connection. This option
+ can be given multiple times.
+
+ You can either use a chardev directly and have that one used
+ throughout QEMU's lifetime, like in the following example:
+
+ .. parsed-literal::
+
+ # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
+ # the guest accesses it
+ |qemu_system| -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
+
+ Or you can execute a command on every TCP connection established
+ by the guest, so that QEMU behaves similar to an inetd process
+ for that virtual server:
+
+ .. parsed-literal::
+
+ # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
+ # and connect the TCP stream to its stdin/stdout
+ |qemu_system| -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
+
+``-netdev tap,id=id[,fd=h][,ifname=name][,script=file][,downscript=dfile][,br=bridge][,helper=helper]``
+ Configure a host TAP network backend with ID id.
+
+ Use the network script file to configure it and the network script
+ dfile to deconfigure it. If name is not provided, the OS
+ automatically provides one. The default network configure script is
+ ``/etc/qemu-ifup`` and the default network deconfigure script is
+ ``/etc/qemu-ifdown``. Use ``script=no`` or ``downscript=no`` to
+ disable script execution.
+
+ If running QEMU as an unprivileged user, use the network helper
+ helper to configure the TAP interface and attach it to the bridge.
+ The default network helper executable is
+ ``/path/to/qemu-bridge-helper`` and the default bridge device is
+ ``br0``.
+
+ ``fd``\ =h can be used to specify the handle of an already opened
+ host TAP interface.
+
+ Examples:
+
+ .. parsed-literal::
+
+ #launch a QEMU instance with the default network script
+ |qemu_system| linux.img -nic tap
+
+ .. parsed-literal::
+
+ #launch a QEMU instance with two NICs, each one connected
+ #to a TAP device
+ |qemu_system| linux.img \
+ -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
+ -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
+
+ .. parsed-literal::
+
+ #launch a QEMU instance with the default network helper to
+ #connect a TAP device to bridge br0
+ |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \
+ -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
+
+``-netdev bridge,id=id[,br=bridge][,helper=helper]``
+ Connect a host TAP network interface to a host bridge device.
+
+ Use the network helper helper to configure the TAP interface and
+ attach it to the bridge. The default network helper executable is
+ ``/path/to/qemu-bridge-helper`` and the default bridge device is
+ ``br0``.
+
+ Examples:
+
+ .. parsed-literal::
+
+ #launch a QEMU instance with the default network helper to
+ #connect a TAP device to bridge br0
+ |qemu_system| linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
+
+ .. parsed-literal::
+
+ #launch a QEMU instance with the default network helper to
+ #connect a TAP device to bridge qemubr0
+ |qemu_system| linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
+
+``-netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]``
+ This host network backend can be used to connect the guest's network
+ to another QEMU virtual machine using a TCP socket connection. If
+ ``listen`` is specified, QEMU waits for incoming connections on port
+ (host is optional). ``connect`` is used to connect to another QEMU
+ instance using the ``listen`` option. ``fd``\ =h specifies an
+ already opened TCP socket.
+
+ Example:
+
+ .. parsed-literal::
+
+ # launch a first QEMU instance
+ |qemu_system| linux.img \
+ -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
+ -netdev socket,id=n1,listen=:1234
+ # connect the network of this instance to the network of the first instance
+ |qemu_system| linux.img \
+ -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
+ -netdev socket,id=n2,connect=127.0.0.1:1234
+
+``-netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]``
+ Configure a socket host network backend to share the guest's network
+ traffic with another QEMU virtual machines using a UDP multicast
+ socket, effectively making a bus for every QEMU with same multicast
+ address maddr and port. NOTES:
+
+ 1. Several QEMU can be running on different hosts and share same bus
+ (assuming correct multicast setup for these hosts).
+
+ 2. mcast support is compatible with User Mode Linux (argument
+ ``ethN=mcast``), see http://user-mode-linux.sf.net.
+
+ 3. Use ``fd=h`` to specify an already opened UDP multicast socket.
+
+ Example:
+
+ .. parsed-literal::
+
+ # launch one QEMU instance
+ |qemu_system| linux.img \
+ -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
+ -netdev socket,id=n1,mcast=230.0.0.1:1234
+ # launch another QEMU instance on same "bus"
+ |qemu_system| linux.img \
+ -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
+ -netdev socket,id=n2,mcast=230.0.0.1:1234
+ # launch yet another QEMU instance on same "bus"
+ |qemu_system| linux.img \
+ -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
+ -netdev socket,id=n3,mcast=230.0.0.1:1234
+
+ Example (User Mode Linux compat.):
+
+ .. parsed-literal::
+
+ # launch QEMU instance (note mcast address selected is UML's default)
+ |qemu_system| linux.img \
+ -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
+ -netdev socket,id=n1,mcast=239.192.168.1:1102
+ # launch UML
+ /path/to/linux ubd0=/path/to/root_fs eth0=mcast
+
+ Example (send packets from host's 1.2.3.4):
+
+ .. parsed-literal::
+
+ |qemu_system| linux.img \
+ -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
+ -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
+
+``-netdev l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]``
+ Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931)
+ is a popular protocol to transport Ethernet (and other Layer 2) data
+ frames between two systems. It is present in routers, firewalls and
+ the Linux kernel (from version 3.3 onwards).
+
+ This transport allows a VM to communicate to another VM, router or
+ firewall directly.
+
+ ``src=srcaddr``
+ source address (mandatory)
+
+ ``dst=dstaddr``
+ destination address (mandatory)
+
+ ``udp``
+ select udp encapsulation (default is ip).
+
+ ``srcport=srcport``
+ source udp port.
+
+ ``dstport=dstport``
+ destination udp port.
+
+ ``ipv6``
+ force v6, otherwise defaults to v4.
+
+ ``rxcookie=rxcookie``; \ ``txcookie=txcookie``
+ Cookies are a weak form of security in the l2tpv3 specification.
+ Their function is mostly to prevent misconfiguration. By default
+ they are 32 bit.
+
+ ``cookie64``
+ Set cookie size to 64 bit instead of the default 32
+
+ ``counter=off``
+ Force a 'cut-down' L2TPv3 with no counter as in
+ draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
+
+ ``pincounter=on``
+ Work around broken counter handling in peer. This may also help
+ on networks which have packet reorder.
+
+ ``offset=offset``
+ Add an extra offset between header and data
+
+ For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to
+ the bridge br-lan on the remote Linux host 1.2.3.4:
+
+ .. parsed-literal::
+
+ # Setup tunnel on linux host using raw ip as encapsulation
+ # on 1.2.3.4
+ ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
+ encap udp udp_sport 16384 udp_dport 16384
+ ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
+ 0xFFFFFFFF peer_session_id 0xFFFFFFFF
+ ifconfig vmtunnel0 mtu 1500
+ ifconfig vmtunnel0 up
+ brctl addif br-lan vmtunnel0
+
+
+ # on 4.3.2.1
+ # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
+
+ |qemu_system| linux.img -device e1000,netdev=n1 \
+ -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
+
+``-netdev vde,id=id[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]``
+ Configure VDE backend to connect to PORT n of a vde switch running
+ on host and listening for incoming connections on socketpath. Use
+ GROUP groupname and MODE octalmode to change default ownership and
+ permissions for communication port. This option is only available if
+ QEMU has been compiled with vde support enabled.
+
+ Example:
+
+ .. parsed-literal::
+
+ # launch vde switch
+ vde_switch -F -sock /tmp/myswitch
+ # launch QEMU instance
+ |qemu_system| linux.img -nic vde,sock=/tmp/myswitch
+
+``-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
+ specifically defined protocol to pass vhost ioctl replacement
+ messages to an application on the other end of the socket. On
+ non-MSIX guests, the feature can be forced with vhostforce. Use
+ 'queues=n' to specify the number of queues to be created for
+ multiqueue vhost-user.
+
+ Example:
+
+ ::
+
+ qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
+ -numa node,memdev=mem \
+ -chardev socket,id=chr0,path=/path/to/socket \
+ -netdev type=vhost-user,id=net0,chardev=chr0 \
+ -device virtio-net-pci,netdev=net0
+
+``-netdev hubport,id=id,hubid=hubid[,netdev=nd]``
+ Create a hub port on the emulated hub with ID hubid.
+
+ The hubport netdev lets you connect a NIC to a QEMU emulated hub
+ instead of a single netdev. Alternatively, you can also connect the
+ hubport to another netdev with ID nd by using the ``netdev=nd``
+ option.
+
+``-net nic[,netdev=nd][,macaddr=mac][,model=type] [,name=name][,addr=addr][,vectors=v]``
+ Legacy option to configure or create an on-board (or machine
+ default) Network Interface Card(NIC) and connect it either to the
+ emulated hub with ID 0 (i.e. the default hub), or to the netdev nd.
+ If model is omitted, then the default NIC model associated with the
+ machine type is used. Note that the default NIC model may change in
+ future QEMU releases, so it is highly recommended to always specify
+ a model. Optionally, the MAC address can be changed to mac, the
+ device address set to addr (PCI cards only), and a name can be
+ assigned for use in monitor commands. Optionally, for PCI cards, you
+ can specify the number v of MSI-X vectors that the card should have;
+ this option currently only affects virtio cards; set v = 0 to
+ disable MSI-X. If no ``-net`` option is specified, a single NIC is
+ created. QEMU can emulate several different models of network card.
+ Use ``-net nic,model=help`` for a list of available devices for your
+ target.
+
+``-net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]``
+ Configure a host network backend (with the options corresponding to
+ the same ``-netdev`` option) and connect it to the emulated hub 0
+ (the default hub). Use name to specify the name of the hub port.
+ERST
+
DEFHEADING()
DEFHEADING(Character device options:)
, QEMU_ARCH_ALL
)
-STEXI
-
+SRST
The general form of a character device option is:
-@table @option
-@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}]
-@findex -chardev
-Backend is one of:
-@option{null},
-@option{socket},
-@option{udp},
-@option{msmouse},
-@option{vc},
-@option{ringbuf},
-@option{file},
-@option{pipe},
-@option{console},
-@option{serial},
-@option{pty},
-@option{stdio},
-@option{braille},
-@option{tty},
-@option{parallel},
-@option{parport},
-@option{spicevmc},
-@option{spiceport}.
-The specific backend will determine the applicable options.
-
-Use @code{-chardev help} to print all available chardev backend types.
-
-All devices must have an id, which can be any string up to 127 characters long.
-It is used to uniquely identify this device in other command line directives.
-
-A character device may be used in multiplexing mode by multiple front-ends.
-Specify @option{mux=on} to enable this mode.
-A multiplexer is a "1:N" device, and here the "1" end is your specified chardev
-backend, and the "N" end is the various parts of QEMU that can talk to a chardev.
-If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will
-create a multiplexer with your specified ID, and you can then configure multiple
-front ends to use that chardev ID for their input/output. Up to four different
-front ends can be connected to a single multiplexed chardev. (Without
-multiplexing enabled, a chardev can only be used by a single front end.)
-For instance you could use this to allow a single stdio chardev to be used by
-two serial ports and the QEMU monitor:
-
-@example
--chardev stdio,mux=on,id=char0 \
--mon chardev=char0,mode=readline \
--serial chardev:char0 \
--serial chardev:char0
-@end example
-
-You can have more than one multiplexer in a system configuration; for instance
-you could have a TCP port multiplexed between UART 0 and UART 1, and stdio
-multiplexed between the QEMU monitor and a parallel port:
-
-@example
--chardev stdio,mux=on,id=char0 \
--mon chardev=char0,mode=readline \
--parallel chardev:char0 \
--chardev tcp,...,mux=on,id=char1 \
--serial chardev:char1 \
--serial chardev:char1
-@end example
-
-When you're using a multiplexed character device, some escape sequences are
-interpreted in the input. @xref{mux_keys, Keys in the character backend
-multiplexer}.
-
-Note that some other command line options may implicitly create multiplexed
-character backends; for instance @option{-serial mon:stdio} creates a
-multiplexed stdio backend connected to the serial port and the QEMU monitor,
-and @option{-nographic} also multiplexes the console and the monitor to
-stdio.
-
-There is currently no support for multiplexing in the other direction
-(where a single QEMU front end takes input and output from multiple chardevs).
-
-Every backend supports the @option{logfile} option, which supplies the path
-to a file to record all data transmitted via the backend. The @option{logappend}
-option controls whether the log file will be truncated or appended to when
-opened.
-
-@end table
-
-The available backends are:
-
-@table @option
-@item -chardev null,id=@var{id}
-A void device. This device will not emit any data, and will drop any data it
-receives. The null backend does not take any options.
-
-@item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,websocket][,reconnect=@var{seconds}][,tls-creds=@var{id}][,tls-authz=@var{id}]
-
-Create a two-way stream socket, which can be either a TCP or a unix socket. A
-unix socket will be created if @option{path} is specified. Behaviour is
-undefined if TCP options are specified for a unix socket.
-
-@option{server} specifies that the socket shall be a listening socket.
-@option{nowait} specifies that QEMU should not block waiting for a client to
-connect to a listening socket.
+``-chardev backend,id=id[,mux=on|off][,options]``
+ Backend is one of: ``null``, ``socket``, ``udp``, ``msmouse``,
+ ``vc``, ``ringbuf``, ``file``, ``pipe``, ``console``, ``serial``,
+ ``pty``, ``stdio``, ``braille``, ``tty``, ``parallel``, ``parport``,
+ ``spicevmc``, ``spiceport``. The specific backend will determine the
+ applicable options.
+
+ Use ``-chardev help`` to print all available chardev backend types.
+
+ All devices must have an id, which can be any string up to 127
+ characters long. It is used to uniquely identify this device in
+ other command line directives.
+
+ A character device may be used in multiplexing mode by multiple
+ front-ends. Specify ``mux=on`` to enable this mode. A multiplexer is
+ a "1:N" device, and here the "1" end is your specified chardev
+ backend, and the "N" end is the various parts of QEMU that can talk
+ to a chardev. If you create a chardev with ``id=myid`` and
+ ``mux=on``, QEMU will create a multiplexer with your specified ID,
+ and you can then configure multiple front ends to use that chardev
+ ID for their input/output. Up to four different front ends can be
+ connected to a single multiplexed chardev. (Without multiplexing
+ enabled, a chardev can only be used by a single front end.) For
+ instance you could use this to allow a single stdio chardev to be
+ used by two serial ports and the QEMU monitor:
+
+ ::
+
+ -chardev stdio,mux=on,id=char0 \
+ -mon chardev=char0,mode=readline \
+ -serial chardev:char0 \
+ -serial chardev:char0
+
+ You can have more than one multiplexer in a system configuration;
+ for instance you could have a TCP port multiplexed between UART 0
+ and UART 1, and stdio multiplexed between the QEMU monitor and a
+ parallel port:
+
+ ::
+
+ -chardev stdio,mux=on,id=char0 \
+ -mon chardev=char0,mode=readline \
+ -parallel chardev:char0 \
+ -chardev tcp,...,mux=on,id=char1 \
+ -serial chardev:char1 \
+ -serial chardev:char1
+
+ When you're using a multiplexed character device, some escape
+ sequences are interpreted in the input. See :ref:`mux_005fkeys`.
+
+ Note that some other command line options may implicitly create
+ multiplexed character backends; for instance ``-serial mon:stdio``
+ creates a multiplexed stdio backend connected to the serial port and
+ the QEMU monitor, and ``-nographic`` also multiplexes the console
+ and the monitor to stdio.
+
+ There is currently no support for multiplexing in the other
+ direction (where a single QEMU front end takes input and output from
+ multiple chardevs).
+
+ Every backend supports the ``logfile`` option, which supplies the
+ path to a file to record all data transmitted via the backend. The
+ ``logappend`` option controls whether the log file will be truncated
+ or appended to when opened.
-@option{telnet} specifies that traffic on the socket should interpret telnet
-escape sequences.
-
-@option{websocket} specifies that the socket uses WebSocket protocol for
-communication.
-
-@option{reconnect} sets the timeout for reconnecting on non-server sockets when
-the remote end goes away. qemu will delay this many seconds and then attempt
-to reconnect. Zero disables reconnecting, and is the default.
-
-@option{tls-creds} requests enablement of the TLS protocol for encryption,
-and specifies the id of the TLS credentials to use for the handshake. The
-credentials must be previously created with the @option{-object tls-creds}
-argument.
-
-@option{tls-auth} provides the ID of the QAuthZ authorization object against
-which the client's x509 distinguished name will be validated. This object is
-only resolved at time of use, so can be deleted and recreated on the fly
-while the chardev server is active. If missing, it will default to denying
-access.
-
-TCP and unix socket options are given below:
-
-@table @option
-
-@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay]
-
-@option{host} for a listening socket specifies the local address to be bound.
-For a connecting socket species the remote host to connect to. @option{host} is
-optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
-
-@option{port} for a listening socket specifies the local port to be bound. For a
-connecting socket specifies the port on the remote host to connect to.
-@option{port} can be given as either a port number or a service name.
-@option{port} is required.
-
-@option{to} is only relevant to listening sockets. If it is specified, and
-@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
-to and including @option{to} until it succeeds. @option{to} must be specified
-as a port number.
-
-@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
-If neither is specified the socket may use either protocol.
-
-@option{nodelay} disables the Nagle algorithm.
-
-@item unix options: path=@var{path}
+The available backends are:
-@option{path} specifies the local path of the unix socket. @option{path} is
-required.
+``-chardev null,id=id``
+ A void device. This device will not emit any data, and will drop any
+ data it receives. The null backend does not take any options.
-@end table
+``-chardev socket,id=id[,TCP options or unix options][,server][,nowait][,telnet][,websocket][,reconnect=seconds][,tls-creds=id][,tls-authz=id]``
+ Create a two-way stream socket, which can be either a TCP or a unix
+ socket. A unix socket will be created if ``path`` is specified.
+ Behaviour is undefined if TCP options are specified for a unix
+ socket.
-@item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6]
+ ``server`` specifies that the socket shall be a listening socket.
-Sends all traffic from the guest to a remote host over UDP.
+ ``nowait`` specifies that QEMU should not block waiting for a client
+ to connect to a listening socket.
-@option{host} specifies the remote host to connect to. If not specified it
-defaults to @code{localhost}.
+ ``telnet`` specifies that traffic on the socket should interpret
+ telnet escape sequences.
-@option{port} specifies the port on the remote host to connect to. @option{port}
-is required.
+ ``websocket`` specifies that the socket uses WebSocket protocol for
+ communication.
-@option{localaddr} specifies the local address to bind to. If not specified it
-defaults to @code{0.0.0.0}.
+ ``reconnect`` sets the timeout for reconnecting on non-server
+ sockets when the remote end goes away. qemu will delay this many
+ seconds and then attempt to reconnect. Zero disables reconnecting,
+ and is the default.
-@option{localport} specifies the local port to bind to. If not specified any
-available local port will be used.
+ ``tls-creds`` requests enablement of the TLS protocol for
+ encryption, and specifies the id of the TLS credentials to use for
+ the handshake. The credentials must be previously created with the
+ ``-object tls-creds`` argument.
-@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
-If neither is specified the device may use either protocol.
+ ``tls-auth`` provides the ID of the QAuthZ authorization object
+ against which the client's x509 distinguished name will be
+ validated. This object is only resolved at time of use, so can be
+ deleted and recreated on the fly while the chardev server is active.
+ If missing, it will default to denying access.
-@item -chardev msmouse,id=@var{id}
+ TCP and unix socket options are given below:
-Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
-take any options.
+ ``TCP options: port=port[,host=host][,to=to][,ipv4][,ipv6][,nodelay]``
+ ``host`` for a listening socket specifies the local address to
+ be bound. For a connecting socket species the remote host to
+ connect to. ``host`` is optional for listening sockets. If not
+ specified it defaults to ``0.0.0.0``.
-@item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]]
+ ``port`` for a listening socket specifies the local port to be
+ bound. For a connecting socket specifies the port on the remote
+ host to connect to. ``port`` can be given as either a port
+ number or a service name. ``port`` is required.
-Connect to a QEMU text console. @option{vc} may optionally be given a specific
-size.
+ ``to`` is only relevant to listening sockets. If it is
+ specified, and ``port`` cannot be bound, QEMU will attempt to
+ bind to subsequent ports up to and including ``to`` until it
+ succeeds. ``to`` must be specified as a port number.
-@option{width} and @option{height} specify the width and height respectively of
-the console, in pixels.
+ ``ipv4`` and ``ipv6`` specify that either IPv4 or IPv6 must be
+ used. If neither is specified the socket may use either
+ protocol.
-@option{cols} and @option{rows} specify that the console be sized to fit a text
-console with the given dimensions.
+ ``nodelay`` disables the Nagle algorithm.
-@item -chardev ringbuf,id=@var{id}[,size=@var{size}]
+ ``unix options: path=path``
+ ``path`` specifies the local path of the unix socket. ``path``
+ is required.
-Create a ring buffer with fixed size @option{size}.
-@var{size} must be a power of two and defaults to @code{64K}.
+``-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr][,localport=localport][,ipv4][,ipv6]``
+ Sends all traffic from the guest to a remote host over UDP.
-@item -chardev file,id=@var{id},path=@var{path}
+ ``host`` specifies the remote host to connect to. If not specified
+ it defaults to ``localhost``.
-Log all traffic received from the guest to a file.
+ ``port`` specifies the port on the remote host to connect to.
+ ``port`` is required.
-@option{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. @option{path}
-is required.
+ ``localaddr`` specifies the local address to bind to. If not
+ specified it defaults to ``0.0.0.0``.
-@item -chardev pipe,id=@var{id},path=@var{path}
+ ``localport`` specifies the local port to bind to. If not specified
+ any available local port will be used.
-Create a two-way connection to the guest. The behaviour differs slightly between
-Windows hosts and other hosts:
+ ``ipv4`` and ``ipv6`` specify that either IPv4 or IPv6 must be used.
+ If neither is specified the device may use either protocol.
-On Windows, a single duplex pipe will be created at
-@file{\\.pipe\@option{path}}.
+``-chardev msmouse,id=id``
+ Forward QEMU's emulated msmouse events to the guest. ``msmouse``
+ does not take any options.
-On other hosts, 2 pipes will be created called @file{@option{path}.in} and
-@file{@option{path}.out}. Data written to @file{@option{path}.in} will be
-received by the guest. Data written by the guest can be read from
-@file{@option{path}.out}. QEMU will not create these fifos, and requires them to
-be present.
+``-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]``
+ Connect to a QEMU text console. ``vc`` may optionally be given a
+ specific size.
-@option{path} forms part of the pipe path as described above. @option{path} is
-required.
+ ``width`` and ``height`` specify the width and height respectively
+ of the console, in pixels.
-@item -chardev console,id=@var{id}
+ ``cols`` and ``rows`` specify that the console be sized to fit a
+ text console with the given dimensions.
-Send traffic from the guest to QEMU's standard output. @option{console} does not
-take any options.
+``-chardev ringbuf,id=id[,size=size]``
+ Create a ring buffer with fixed size ``size``. size must be a power
+ of two and defaults to ``64K``.
-@option{console} is only available on Windows hosts.
+``-chardev file,id=id,path=path``
+ Log all traffic received from the guest to a file.
-@item -chardev serial,id=@var{id},path=@option{path}
+ ``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.
-Send traffic from the guest to a serial device on the host.
+``-chardev pipe,id=id,path=path``
+ Create a two-way connection to the guest. The behaviour differs
+ slightly between Windows hosts and other hosts:
-On Unix hosts serial will actually accept any tty device,
-not only serial lines.
+ On Windows, a single duplex pipe will be created at
+ ``\\.pipe\path``.
-@option{path} specifies the name of the serial device to open.
+ On other hosts, 2 pipes will be created called ``path.in`` and
+ ``path.out``. Data written to ``path.in`` will be received by the
+ guest. Data written by the guest can be read from ``path.out``. QEMU
+ will not create these fifos, and requires them to be present.
-@item -chardev pty,id=@var{id}
+ ``path`` forms part of the pipe path as described above. ``path`` is
+ required.
-Create a new pseudo-terminal on the host and connect to it. @option{pty} does
-not take any options.
+``-chardev console,id=id``
+ Send traffic from the guest to QEMU's standard output. ``console``
+ does not take any options.
-@option{pty} is not available on Windows hosts.
+ ``console`` is only available on Windows hosts.
-@item -chardev stdio,id=@var{id}[,signal=on|off]
-Connect to standard input and standard output of the QEMU process.
+``-chardev serial,id=id,path=path``
+ Send traffic from the guest to a serial device on the host.
-@option{signal} controls if signals are enabled on the terminal, that includes
-exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
-default, use @option{signal=off} to disable it.
+ On Unix hosts serial will actually accept any tty device, not only
+ serial lines.
-@item -chardev braille,id=@var{id}
+ ``path`` specifies the name of the serial device to open.
-Connect to a local BrlAPI server. @option{braille} does not take any options.
+``-chardev pty,id=id``
+ Create a new pseudo-terminal on the host and connect to it. ``pty``
+ does not take any options.
-@item -chardev tty,id=@var{id},path=@var{path}
+ ``pty`` is not available on Windows hosts.
-@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
-DragonFlyBSD hosts. It is an alias for @option{serial}.
+``-chardev stdio,id=id[,signal=on|off]``
+ Connect to standard input and standard output of the QEMU process.
-@option{path} specifies the path to the tty. @option{path} is required.
+ ``signal`` controls if signals are enabled on the terminal, that
+ includes exiting QEMU with the key sequence Control-c. This option
+ is enabled by default, use ``signal=off`` to disable it.
-@item -chardev parallel,id=@var{id},path=@var{path}
-@itemx -chardev parport,id=@var{id},path=@var{path}
+``-chardev braille,id=id``
+ Connect to a local BrlAPI server. ``braille`` does not take any
+ options.
-@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
+``-chardev tty,id=id,path=path``
+ ``tty`` is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD
+ and DragonFlyBSD hosts. It is an alias for ``serial``.
-Connect to a local parallel port.
+ ``path`` specifies the path to the tty. ``path`` is required.
-@option{path} specifies the path to the parallel port device. @option{path} is
-required.
+``-chardev parallel,id=id,path=path``
+ \
+``-chardev parport,id=id,path=path``
+ ``parallel`` is only available on Linux, FreeBSD and DragonFlyBSD
+ hosts.
-@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name}
+ Connect to a local parallel port.
-@option{spicevmc} is only available when spice support is built in.
+ ``path`` specifies the path to the parallel port device. ``path`` is
+ required.
-@option{debug} debug level for spicevmc
+``-chardev spicevmc,id=id,debug=debug,name=name``
+ ``spicevmc`` is only available when spice support is built in.
-@option{name} name of spice channel to connect to
+ ``debug`` debug level for spicevmc
-Connect to a spice virtual machine channel, such as vdiport.
+ ``name`` name of spice channel to connect to
-@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name}
+ Connect to a spice virtual machine channel, such as vdiport.
-@option{spiceport} is only available when spice support is built in.
+``-chardev spiceport,id=id,debug=debug,name=name``
+ ``spiceport`` is only available when spice support is built in.
-@option{debug} debug level for spicevmc
+ ``debug`` debug level for spicevmc
-@option{name} name of spice port to connect to
+ ``name`` name of spice port to connect to
-Connect to a spice port, allowing a Spice client to handle the traffic
-identified by a name (preferably a fqdn).
-ETEXI
+ Connect to a spice port, allowing a Spice client to handle the
+ traffic identified by a name (preferably a fqdn).
+ERST
-STEXI
-@end table
-ETEXI
DEFHEADING()
#ifdef CONFIG_TPM
"-tpmdev emulator,id=id,chardev=dev\n"
" configure the TPM device using chardev backend\n",
QEMU_ARCH_ALL)
-STEXI
-
+SRST
The general form of a TPM device option is:
-@table @option
-
-@item -tpmdev @var{backend},id=@var{id}[,@var{options}]
-@findex -tpmdev
-The specific backend type will determine the applicable options.
-The @code{-tpmdev} option creates the TPM backend and requires a
-@code{-device} option that specifies the TPM frontend interface model.
+``-tpmdev backend,id=id[,options]``
+ The specific backend type will determine the applicable options. The
+ ``-tpmdev`` option creates the TPM backend and requires a
+ ``-device`` option that specifies the TPM frontend interface model.
-Use @code{-tpmdev help} to print all available TPM backend types.
-
-@end table
+ Use ``-tpmdev help`` to print all available TPM backend types.
The available backends are:
-@table @option
-
-@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path}
+``-tpmdev passthrough,id=id,path=path,cancel-path=cancel-path``
+ (Linux-host only) Enable access to the host's TPM using the
+ passthrough driver.
-(Linux-host only) Enable access to the host's TPM using the passthrough
-driver.
+ ``path`` specifies the path to the host's TPM device, i.e., on a
+ Linux host this would be ``/dev/tpm0``. ``path`` is optional and by
+ default ``/dev/tpm0`` is used.
-@option{path} specifies the path to the host's TPM device, i.e., on
-a Linux host this would be @code{/dev/tpm0}.
-@option{path} is optional and by default @code{/dev/tpm0} is used.
+ ``cancel-path`` specifies the path to the host TPM device's sysfs
+ entry allowing for cancellation of an ongoing TPM command.
+ ``cancel-path`` is optional and by default QEMU will search for the
+ sysfs entry to use.
-@option{cancel-path} specifies the path to the host TPM device's sysfs
-entry allowing for cancellation of an ongoing TPM command.
-@option{cancel-path} is optional and by default QEMU will search for the
-sysfs entry to use.
+ Some notes about using the host's TPM with the passthrough driver:
-Some notes about using the host's TPM with the passthrough driver:
+ The TPM device accessed by the passthrough driver must not be used
+ by any other application on the host.
-The TPM device accessed by the passthrough driver must not be
-used by any other application on the host.
+ Since the host's firmware (BIOS/UEFI) has already initialized the
+ TPM, the VM's firmware (BIOS/UEFI) will not be able to initialize
+ the TPM again and may therefore not show a TPM-specific menu that
+ would otherwise allow the user to configure the TPM, e.g., allow the
+ user to enable/disable or activate/deactivate the TPM. Further, if
+ TPM ownership is released from within a VM then the host's TPM will
+ get disabled and deactivated. To enable and activate the TPM again
+ afterwards, the host has to be rebooted and the user is required to
+ enter the firmware's menu to enable and activate the TPM. If the TPM
+ is left disabled and/or deactivated most TPM commands will fail.
-Since the host's firmware (BIOS/UEFI) has already initialized the TPM,
-the VM's firmware (BIOS/UEFI) will not be able to initialize the
-TPM again and may therefore not show a TPM-specific menu that would
-otherwise allow the user to configure the TPM, e.g., allow the user to
-enable/disable or activate/deactivate the TPM.
-Further, if TPM ownership is released from within a VM then the host's TPM
-will get disabled and deactivated. To enable and activate the
-TPM again afterwards, the host has to be rebooted and the user is
-required to enter the firmware's menu to enable and activate the TPM.
-If the TPM is left disabled and/or deactivated most TPM commands will fail.
+ To create a passthrough TPM use the following two options:
-To create a passthrough TPM use the following two options:
-@example
--tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
-@end example
-Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
-@code{tpmdev=tpm0} in the device option.
+ ::
-@item -tpmdev emulator,id=@var{id},chardev=@var{dev}
+ -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
-(Linux-host only) Enable access to a TPM emulator using Unix domain socket based
-chardev backend.
+ Note that the ``-tpmdev`` id is ``tpm0`` and is referenced by
+ ``tpmdev=tpm0`` in the device option.
-@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server.
+``-tpmdev emulator,id=id,chardev=dev``
+ (Linux-host only) Enable access to a TPM emulator using Unix domain
+ socket based chardev backend.
-To create a TPM emulator backend device with chardev socket backend:
-@example
+ ``chardev`` specifies the unique ID of a character device backend
+ that provides connection to the software TPM server.
--chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
+ To create a TPM emulator backend device with chardev socket backend:
-@end example
+ ::
-ETEXI
+ -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
+ERST
-STEXI
-@end table
-ETEXI
DEFHEADING()
#endif
DEFHEADING(Linux/Multiboot boot specific:)
-STEXI
+SRST
+When using these options, you can use a given Linux or Multiboot kernel
+without installing it in the disk image. It can be useful for easier
+testing of various kernels.
-When using these options, you can use a given Linux or Multiboot
-kernel without installing it in the disk image. It can be useful
-for easier testing of various kernels.
-@table @option
-ETEXI
+ERST
DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
"-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
-STEXI
-@item -kernel @var{bzImage}
-@findex -kernel
-Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
-or in multiboot format.
-ETEXI
+SRST
+``-kernel bzImage``
+ Use bzImage as kernel image. The kernel can be either a Linux kernel
+ or in multiboot format.
+ERST
DEF("append", HAS_ARG, QEMU_OPTION_append, \
"-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
-STEXI
-@item -append @var{cmdline}
-@findex -append
-Use @var{cmdline} as kernel command line
-ETEXI
+SRST
+``-append cmdline``
+ Use cmdline as kernel command line
+ERST
DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
"-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
-STEXI
-@item -initrd @var{file}
-@findex -initrd
-Use @var{file} as initial ram disk.
+SRST
+``-initrd file``
+ Use file as initial ram disk.
-@item -initrd "@var{file1} arg=foo,@var{file2}"
+``-initrd "file1 arg=foo,file2"``
+ This syntax is only available with multiboot.
-This syntax is only available with multiboot.
-
-Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
-first module.
-ETEXI
+ Use file1 and file2 as modules and pass arg=foo as parameter to the
+ first module.
+ERST
DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
"-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL)
-STEXI
-@item -dtb @var{file}
-@findex -dtb
-Use @var{file} as a device tree binary (dtb) image and pass it to the kernel
-on boot.
-ETEXI
-
-STEXI
-@end table
-ETEXI
+SRST
+``-dtb file``
+ Use file as a device tree binary (dtb) image and pass it to the
+ kernel on boot.
+ERST
+
DEFHEADING()
DEFHEADING(Debug/Expert options:)
-STEXI
-@table @option
-ETEXI
DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
"-fw_cfg [name=]<name>,file=<file>\n"
"-fw_cfg [name=]<name>,string=<str>\n"
" add named fw_cfg entry with contents from string\n",
QEMU_ARCH_ALL)
-STEXI
+SRST
+``-fw_cfg [name=]name,file=file``
+ Add named fw\_cfg entry with contents from file file.
+
+``-fw_cfg [name=]name,string=str``
+ Add named fw\_cfg entry with contents from string str.
-@item -fw_cfg [name=]@var{name},file=@var{file}
-@findex -fw_cfg
-Add named fw_cfg entry with contents from file @var{file}.
+ The terminating NUL character of the contents of str will not be
+ included as part of the fw\_cfg item data. To insert contents with
+ embedded NUL characters, you have to use the file parameter.
-@item -fw_cfg [name=]@var{name},string=@var{str}
-Add named fw_cfg entry with contents from string @var{str}.
+ The fw\_cfg entries are passed by QEMU through to the guest.
-The terminating NUL character of the contents of @var{str} will not be
-included as part of the fw_cfg item data. To insert contents with
-embedded NUL characters, you have to use the @var{file} parameter.
+ Example:
-The fw_cfg entries are passed by QEMU through to the guest.
+ ::
-Example:
-@example
- -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
-@end example
-creates an fw_cfg entry named opt/com.mycompany/blob with contents
-from ./my_blob.bin.
+ -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
-ETEXI
+ creates an fw\_cfg entry named opt/com.mycompany/blob with contents
+ from ./my\_blob.bin.
+ERST
DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
"-serial dev redirect the serial port to char device 'dev'\n",
QEMU_ARCH_ALL)
-STEXI
-@item -serial @var{dev}
-@findex -serial
-Redirect the virtual serial port to host character device
-@var{dev}. The default device is @code{vc} in graphical mode and
-@code{stdio} in non graphical mode.
-
-This option can be used several times to simulate up to 4 serial
-ports.
-
-Use @code{-serial none} to disable all serial ports.
-
-Available character devices are:
-@table @option
-@item vc[:@var{W}x@var{H}]
-Virtual console. Optionally, a width and height can be given in pixel with
-@example
-vc:800x600
-@end example
-It is also possible to specify width or height in characters:
-@example
-vc:80Cx24C
-@end example
-@item pty
-[Linux only] Pseudo TTY (a new PTY is automatically allocated)
-@item none
-No device is allocated.
-@item null
-void device
-@item chardev:@var{id}
-Use a named character device defined with the @code{-chardev} option.
-@item /dev/XXX
-[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
-parameters are set according to the emulated ones.
-@item /dev/parport@var{N}
-[Linux only, parallel port only] Use host parallel port
-@var{N}. Currently SPP and EPP parallel port features can be used.
-@item file:@var{filename}
-Write output to @var{filename}. No character can be read.
-@item stdio
-[Unix only] standard input/output
-@item pipe:@var{filename}
-name pipe @var{filename}
-@item COM@var{n}
-[Windows only] Use host serial port @var{n}
-@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
-This implements UDP Net Console.
-When @var{remote_host} or @var{src_ip} are not specified
-they default to @code{0.0.0.0}.
-When not using a specified @var{src_port} a random port is automatically chosen.
-
-If you just want a simple readonly console you can use @code{netcat} or
-@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as:
-@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it
-will appear in the netconsole session.
-
-If you plan to send characters back via netconsole or you want to stop
-and start QEMU a lot of times, you should have QEMU use the same
-source port each time by using something like @code{-serial
-udp::4555@@:4556} to QEMU. Another approach is to use a patched
-version of netcat which can listen to a TCP port and send and receive
-characters via udp. If you have a patched version of netcat which
-activates telnet remote echo and single char transfer, then you can
-use the following options to set up a netcat redirector to allow
-telnet on port 5555 to access the QEMU port.
-@table @code
-@item QEMU Options:
--serial udp::4555@@:4556
-@item netcat options:
--u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
-@item telnet options:
-localhost 5555
-@end table
-
-@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}]
-The TCP Net Console has two modes of operation. It can send the serial
-I/O to a location or wait for a connection from a location. By default
-the TCP Net Console is sent to @var{host} at the @var{port}. If you use
-the @var{server} option QEMU will wait for a client socket application
-to connect to the port before continuing, unless the @code{nowait}
-option was specified. The @code{nodelay} option disables the Nagle buffering
-algorithm. The @code{reconnect} option only applies if @var{noserver} is
-set, if the connection goes down it will attempt to reconnect at the
-given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only
-one TCP connection at a time is accepted. You can use @code{telnet} to
-connect to the corresponding character device.
-@table @code
-@item Example to send tcp console to 192.168.0.2 port 4444
--serial tcp:192.168.0.2:4444
-@item Example to listen and wait on port 4444 for connection
--serial tcp::4444,server
-@item Example to not wait and listen on ip 192.168.0.100 port 4444
--serial tcp:192.168.0.100:4444,server,nowait
-@end table
-
-@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
-The telnet protocol is used instead of raw tcp sockets. The options
-work the same as if you had specified @code{-serial tcp}. The
-difference is that the port acts like a telnet server or client using
-telnet option negotiation. This will also allow you to send the
-MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
-sequence. Typically in unix telnet you do it with Control-] and then
-type "send break" followed by pressing the enter key.
-
-@item websocket:@var{host}:@var{port},server[,nowait][,nodelay]
-The WebSocket protocol is used instead of raw tcp socket. The port acts as
-a WebSocket server. Client mode is not supported.
-
-@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}]
-A unix domain socket is used instead of a tcp socket. The option works the
-same as if you had specified @code{-serial tcp} except the unix domain socket
-@var{path} is used for connections.
-
-@item mon:@var{dev_string}
-This is a special option to allow the monitor to be multiplexed onto
-another serial port. The monitor is accessed with key sequence of
-@key{Control-a} and then pressing @key{c}.
-@var{dev_string} should be any one of the serial devices specified
-above. An example to multiplex the monitor onto a telnet server
-listening on port 4444 would be:
-@table @code
-@item -serial mon:telnet::4444,server,nowait
-@end table
-When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate
-QEMU any more but will be passed to the guest instead.
-
-@item braille
-Braille device. This will use BrlAPI to display the braille output on a real
-or fake device.
-
-@item msmouse
-Three button serial mouse. Configure the guest to use Microsoft protocol.
-@end table
-ETEXI
+SRST
+``-serial dev``
+ Redirect the virtual serial port to host character device dev. The
+ default device is ``vc`` in graphical mode and ``stdio`` in non
+ graphical mode.
+
+ This option can be used several times to simulate up to 4 serial
+ ports.
+
+ Use ``-serial none`` to disable all serial ports.
+
+ Available character devices are:
+
+ ``vc[:WxH]``
+ Virtual console. Optionally, a width and height can be given in
+ pixel with
+
+ ::
+
+ vc:800x600
+
+ It is also possible to specify width or height in characters:
+
+ ::
+
+ vc:80Cx24C
+
+ ``pty``
+ [Linux only] Pseudo TTY (a new PTY is automatically allocated)
+
+ ``none``
+ No device is allocated.
+
+ ``null``
+ void device
+
+ ``chardev:id``
+ Use a named character device defined with the ``-chardev``
+ option.
+
+ ``/dev/XXX``
+ [Linux only] Use host tty, e.g. ``/dev/ttyS0``. The host serial
+ port parameters are set according to the emulated ones.
+
+ ``/dev/parportN``
+ [Linux only, parallel port only] Use host parallel port N.
+ Currently SPP and EPP parallel port features can be used.
+
+ ``file:filename``
+ Write output to filename. No character can be read.
+
+ ``stdio``
+ [Unix only] standard input/output
+
+ ``pipe:filename``
+ name pipe filename
+
+ ``COMn``
+ [Windows only] Use host serial port n
+
+ ``udp:[remote_host]:remote_port[@[src_ip]:src_port]``
+ This implements UDP Net Console. When remote\_host or src\_ip
+ are not specified they default to ``0.0.0.0``. When not using a
+ specified src\_port a random port is automatically chosen.
+
+ If you just want a simple readonly console you can use
+ ``netcat`` or ``nc``, by starting QEMU with:
+ ``-serial udp::4555`` and nc as: ``nc -u -l -p 4555``. Any time
+ QEMU writes something to that port it will appear in the
+ netconsole session.
+
+ If you plan to send characters back via netconsole or you want
+ to stop and start QEMU a lot of times, you should have QEMU use
+ the same source port each time by using something like ``-serial
+ udp::4555@:4556`` to QEMU. Another approach is to use a patched
+ version of netcat which can listen to a TCP port and send and
+ receive characters via udp. If you have a patched version of
+ netcat which activates telnet remote echo and single char
+ transfer, then you can use the following options to set up a
+ netcat redirector to allow telnet on port 5555 to access the
+ QEMU port.
+
+ ``QEMU Options:``
+ -serial udp::4555@:4556
+
+ ``netcat options:``
+ -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
+
+ ``telnet options:``
+ localhost 5555
+
+ ``tcp:[host]:port[,server][,nowait][,nodelay][,reconnect=seconds]``
+ The TCP Net Console has two modes of operation. It can send the
+ serial I/O to a location or wait for a connection from a
+ location. By default the TCP Net Console is sent to host at the
+ port. If you use the server option QEMU will wait for a client
+ socket application to connect to the port before continuing,
+ unless the ``nowait`` option was specified. The ``nodelay``
+ option disables the Nagle buffering algorithm. The ``reconnect``
+ option only applies if noserver is set, if the connection goes
+ down it will attempt to reconnect at the given interval. If host
+ is omitted, 0.0.0.0 is assumed. Only one TCP connection at a
+ time is accepted. You can use ``telnet`` to connect to the
+ corresponding character device.
+
+ ``Example to send tcp console to 192.168.0.2 port 4444``
+ -serial tcp:192.168.0.2:4444
+
+ ``Example to listen and wait on port 4444 for connection``
+ -serial tcp::4444,server
+
+ ``Example to not wait and listen on ip 192.168.0.100 port 4444``
+ -serial tcp:192.168.0.100:4444,server,nowait
+
+ ``telnet:host:port[,server][,nowait][,nodelay]``
+ The telnet protocol is used instead of raw tcp sockets. The
+ options work the same as if you had specified ``-serial tcp``.
+ The difference is that the port acts like a telnet server or
+ client using telnet option negotiation. This will also allow you
+ to send the MAGIC\_SYSRQ sequence if you use a telnet that
+ supports sending the break sequence. Typically in unix telnet
+ you do it with Control-] and then type "send break" followed by
+ pressing the enter key.
+
+ ``websocket:host:port,server[,nowait][,nodelay]``
+ The WebSocket protocol is used instead of raw tcp socket. The
+ port acts as a WebSocket server. Client mode is not supported.
+
+ ``unix:path[,server][,nowait][,reconnect=seconds]``
+ A unix domain socket is used instead of a tcp socket. The option
+ works the same as if you had specified ``-serial tcp`` except
+ the unix domain socket path is used for connections.
+
+ ``mon:dev_string``
+ This is a special option to allow the monitor to be multiplexed
+ onto another serial port. The monitor is accessed with key
+ sequence of Control-a and then pressing c. dev\_string should be
+ any one of the serial devices specified above. An example to
+ multiplex the monitor onto a telnet server listening on port
+ 4444 would be:
+
+ ``-serial mon:telnet::4444,server,nowait``
+
+ When the monitor is multiplexed to stdio in this way, Ctrl+C
+ will not terminate QEMU any more but will be passed to the guest
+ instead.
+
+ ``braille``
+ Braille device. This will use BrlAPI to display the braille
+ output on a real or fake device.
+
+ ``msmouse``
+ Three button serial mouse. Configure the guest to use Microsoft
+ protocol.
+ERST
DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
"-parallel dev redirect the parallel port to char device 'dev'\n",
QEMU_ARCH_ALL)
-STEXI
-@item -parallel @var{dev}
-@findex -parallel
-Redirect the virtual parallel port to host device @var{dev} (same
-devices as the serial port). On Linux hosts, @file{/dev/parportN} can
-be used to use hardware devices connected on the corresponding host
-parallel port.
+SRST
+``-parallel dev``
+ Redirect the virtual parallel port to host device dev (same devices
+ as the serial port). On Linux hosts, ``/dev/parportN`` can be used
+ to use hardware devices connected on the corresponding host parallel
+ port.
-This option can be used several times to simulate up to 3 parallel
-ports.
+ This option can be used several times to simulate up to 3 parallel
+ ports.
-Use @code{-parallel none} to disable all parallel ports.
-ETEXI
+ Use ``-parallel none`` to disable all parallel ports.
+ERST
DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
"-monitor dev redirect the monitor to char device 'dev'\n",
QEMU_ARCH_ALL)
-STEXI
-@item -monitor @var{dev}
-@findex -monitor
-Redirect the monitor to host device @var{dev} (same devices as the
-serial port).
-The default device is @code{vc} in graphical mode and @code{stdio} in
-non graphical mode.
-Use @code{-monitor none} to disable the default monitor.
-ETEXI
+SRST
+``-monitor dev``
+ Redirect the monitor to host device dev (same devices as the serial
+ port). The default device is ``vc`` in graphical mode and ``stdio``
+ in non graphical mode. Use ``-monitor none`` to disable the default
+ monitor.
+ERST
DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
"-qmp dev like -monitor but opens in 'control' mode\n",
QEMU_ARCH_ALL)
-STEXI
-@item -qmp @var{dev}
-@findex -qmp
-Like -monitor but opens in 'control' mode.
-ETEXI
+SRST
+``-qmp dev``
+ Like -monitor but opens in 'control' mode.
+ERST
DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
"-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
QEMU_ARCH_ALL)
-STEXI
-@item -qmp-pretty @var{dev}
-@findex -qmp-pretty
-Like -qmp but uses pretty JSON formatting.
-ETEXI
+SRST
+``-qmp-pretty dev``
+ 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)
-STEXI
-@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
-@findex -mon
-Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing
-easing human reading and debugging.
-ETEXI
+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.
+ERST
DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
"-debugcon dev redirect the debug console to char device 'dev'\n",
QEMU_ARCH_ALL)
-STEXI
-@item -debugcon @var{dev}
-@findex -debugcon
-Redirect the debug console to host device @var{dev} (same devices as the
-serial port). The debug console is an I/O port which is typically port
-0xe9; writing to that I/O port sends output to this device.
-The default device is @code{vc} in graphical mode and @code{stdio} in
-non graphical mode.
-ETEXI
+SRST
+``-debugcon dev``
+ Redirect the debug console to host device dev (same devices as the
+ serial port). The debug console is an I/O port which is typically
+ port 0xe9; writing to that I/O port sends output to this device. The
+ default device is ``vc`` in graphical mode and ``stdio`` in non
+ graphical mode.
+ERST
DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
"-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
-STEXI
-@item -pidfile @var{file}
-@findex -pidfile
-Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
-from a script.
-ETEXI
+SRST
+``-pidfile file``
+ Store the QEMU process PID in file. It is useful if you launch QEMU
+ from a script.
+ERST
DEF("singlestep", 0, QEMU_OPTION_singlestep, \
"-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
-STEXI
-@item -singlestep
-@findex -singlestep
-Run the emulation in single step mode.
-ETEXI
+SRST
+``-singlestep``
+ Run the emulation in single step mode.
+ERST
DEF("preconfig", 0, QEMU_OPTION_preconfig, \
"--preconfig pause QEMU before machine is initialized (experimental)\n",
QEMU_ARCH_ALL)
-STEXI
-@item --preconfig
-@findex --preconfig
-Pause QEMU for interactive configuration before the machine is created,
-which allows querying and configuring properties that will affect
-machine initialization. Use QMP command 'x-exit-preconfig' to exit
-the preconfig state and move to the next state (i.e. run guest if -S
-isn't used or pause the second time if -S is used). This option is
-experimental.
-ETEXI
+SRST
+``--preconfig``
+ Pause QEMU for interactive configuration before the machine is
+ created, which allows querying and configuring properties that will
+ affect machine initialization. Use QMP command 'x-exit-preconfig' to
+ exit the preconfig state and move to the next state (i.e. run guest
+ if -S isn't used or pause the second time if -S is used). This
+ option is experimental.
+ERST
DEF("S", 0, QEMU_OPTION_S, \
"-S freeze CPU at startup (use 'c' to start execution)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -S
-@findex -S
-Do not start CPU at startup (you must type 'c' in the monitor).
-ETEXI
+SRST
+``-S``
+ Do not start CPU at startup (you must type 'c' in the monitor).
+ERST
DEF("realtime", HAS_ARG, QEMU_OPTION_realtime,
"-realtime [mlock=on|off]\n"
" run qemu with realtime features\n"
" mlock=on|off controls mlock support (default: on)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -realtime mlock=on|off
-@findex -realtime
-Run qemu with realtime features.
-mlocking qemu and guest memory can be enabled via @option{mlock=on}
-(enabled by default).
-ETEXI
+SRST
+``-realtime mlock=on|off``
+ Run qemu with realtime features. mlocking qemu and guest memory can
+ be enabled via ``mlock=on`` (enabled by default).
+ERST
DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
"-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
" mem-lock=on|off controls memory lock support (default: off)\n"
" cpu-pm=on|off controls cpu power management (default: off)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -overcommit mem-lock=on|off
-@item -overcommit cpu-pm=on|off
-@findex -overcommit
-Run qemu with hints about host resource overcommit. The default is
-to assume that host overcommits all resources.
-
-Locking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled
-by default). This works when host memory is not overcommitted and reduces the
-worst-case latency for guest. This is equivalent to @option{realtime}.
-
-Guest ability to manage power state of host cpus (increasing latency for other
-processes on the same host cpu, but decreasing latency for guest) can be
-enabled via @option{cpu-pm=on} (disabled by default). This works best when
-host CPU is not overcommitted. When used, host estimates of CPU cycle and power
-utilization will be incorrect, not taking into account guest idle time.
-ETEXI
+SRST
+``-overcommit mem-lock=on|off``
+ \
+``-overcommit cpu-pm=on|off``
+ Run qemu with hints about host resource overcommit. The default is
+ to assume that host overcommits all resources.
+
+ Locking qemu and guest memory can be enabled via ``mem-lock=on``
+ (disabled by default). This works when host memory is not
+ overcommitted and reduces the worst-case latency for guest. This is
+ equivalent to ``realtime``.
+
+ Guest ability to manage power state of host cpus (increasing latency
+ for other processes on the same host cpu, but decreasing latency for
+ guest) can be enabled via ``cpu-pm=on`` (disabled by default). This
+ works best when host CPU is not overcommitted. When used, host
+ estimates of CPU cycle and power utilization will be incorrect, not
+ taking into account guest idle time.
+ERST
DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
"-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
-STEXI
-@item -gdb @var{dev}
-@findex -gdb
-Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
-connections will likely be TCP-based, but also UDP, pseudo TTY, or even
-stdio are reasonable use case. The latter is allowing to start QEMU from
-within gdb and establish the connection via a pipe:
-@example
-(gdb) target remote | exec @value{qemu_system} -gdb stdio ...
-@end example
-ETEXI
+SRST
+``-gdb dev``
+ Wait for gdb connection on device dev (see
+ :ref:`gdb_005fusage`). Typical connections will likely be
+ TCP-based, but also UDP, pseudo TTY, or even stdio are reasonable
+ use case. The latter is allowing to start QEMU from within gdb and
+ establish the connection via a pipe:
+
+ .. parsed-literal::
+
+ (gdb) target remote | exec |qemu_system| -gdb stdio ...
+ERST
DEF("s", 0, QEMU_OPTION_s, \
"-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
QEMU_ARCH_ALL)
-STEXI
-@item -s
-@findex -s
-Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
-(@pxref{gdb_usage}).
-ETEXI
+SRST
+``-s``
+ Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
+ (see :ref:`gdb_005fusage`).
+ERST
DEF("d", HAS_ARG, QEMU_OPTION_d, \
"-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -d @var{item1}[,...]
-@findex -d
-Enable logging of specified items. Use '-d help' for a list of log items.
-ETEXI
+SRST
+``-d item1[,...]``
+ Enable logging of specified items. Use '-d help' for a list of log
+ items.
+ERST
DEF("D", HAS_ARG, QEMU_OPTION_D, \
"-D logfile output log to logfile (default stderr)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -D @var{logfile}
-@findex -D
-Output log in @var{logfile} instead of to stderr
-ETEXI
+SRST
+``-D logfile``
+ Output log in logfile instead of to stderr
+ERST
DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \
"-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -dfilter @var{range1}[,...]
-@findex -dfilter
-Filter debug output to that relevant to a range of target addresses. The filter
-spec can be either @var{start}+@var{size}, @var{start}-@var{size} or
-@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the
-addresses and sizes required. For example:
-@example
- -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
-@end example
-Will dump output for any code in the 0x1000 sized block starting at 0x8000 and
-the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized
-block starting at 0xffffffc00005f000.
-ETEXI
+SRST
+``-dfilter range1[,...]``
+ Filter debug output to that relevant to a range of target addresses.
+ The filter spec can be either start+size, start-size or start..end
+ where start end and size are the addresses and sizes required. For
+ example:
+
+ ::
+
+ -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
+
+ Will dump output for any code in the 0x1000 sized block starting at
+ 0x8000 and the 0x200 sized block starting at 0xffffffc000080000 and
+ another 0x1000 sized block starting at 0xffffffc00005f000.
+ERST
DEF("seed", HAS_ARG, QEMU_OPTION_seed, \
"-seed number seed the pseudo-random number generator\n",
QEMU_ARCH_ALL)
-STEXI
-@item -seed @var{number}
-@findex -seed
-Force the guest to use a deterministic pseudo-random number generator, seeded
-with @var{number}. This does not affect crypto routines within the host.
-ETEXI
+SRST
+``-seed number``
+ Force the guest to use a deterministic pseudo-random number
+ generator, seeded with number. This does not affect crypto routines
+ within the host.
+ERST
DEF("L", HAS_ARG, QEMU_OPTION_L, \
"-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
QEMU_ARCH_ALL)
-STEXI
-@item -L @var{path}
-@findex -L
-Set the directory for the BIOS, VGA BIOS and keymaps.
+SRST
+``-L path``
+ Set the directory for the BIOS, VGA BIOS and keymaps.
-To list all the data directories, use @code{-L help}.
-ETEXI
+ To list all the data directories, use ``-L help``.
+ERST
DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
"-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
-STEXI
-@item -bios @var{file}
-@findex -bios
-Set the filename for the BIOS.
-ETEXI
+SRST
+``-bios file``
+ Set the filename for the BIOS.
+ERST
DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
"-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
-STEXI
-@item -enable-kvm
-@findex -enable-kvm
-Enable KVM full virtualization support. This option is only available
-if KVM support is enabled when compiling.
-ETEXI
+SRST
+``-enable-kvm``
+ Enable KVM full virtualization support. This option is only
+ available if KVM support is enabled when compiling.
+ERST
DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
"-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
" to specified domain id. (Does not affect\n"
" xenpv machine type).\n",
QEMU_ARCH_ALL)
-STEXI
-@item -xen-domid @var{id}
-@findex -xen-domid
-Specify xen guest domain @var{id} (XEN only).
-@item -xen-attach
-@findex -xen-attach
-Attach to existing xen domain.
-libxl will use this when starting QEMU (XEN only).
-@findex -xen-domid-restrict
-Restrict set of available xen operations to specified domain id (XEN only).
-ETEXI
+SRST
+``-xen-domid id``
+ Specify xen guest domain id (XEN only).
+
+``-xen-attach``
+ Attach to existing xen domain. libxl will use this when starting
+ QEMU (XEN only). Restrict set of available xen operations to
+ specified domain id (XEN only).
+ERST
DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
"-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
-STEXI
-@item -no-reboot
-@findex -no-reboot
-Exit instead of rebooting.
-ETEXI
+SRST
+``-no-reboot``
+ Exit instead of rebooting.
+ERST
DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
"-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
-STEXI
-@item -no-shutdown
-@findex -no-shutdown
-Don't exit QEMU on guest shutdown, but instead only stop the emulation.
-This allows for instance switching to monitor to commit changes to the
-disk image.
-ETEXI
+SRST
+``-no-shutdown``
+ Don't exit QEMU on guest shutdown, but instead only stop the
+ emulation. This allows for instance switching to monitor to commit
+ changes to the disk image.
+ERST
DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
"-loadvm [tag|id]\n" \
" start right away with a saved state (loadvm in monitor)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -loadvm @var{file}
-@findex -loadvm
-Start right away with a saved state (@code{loadvm} in monitor)
-ETEXI
+SRST
+``-loadvm file``
+ Start right away with a saved state (``loadvm`` in monitor)
+ERST
#ifndef _WIN32
DEF("daemonize", 0, QEMU_OPTION_daemonize, \
"-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
#endif
-STEXI
-@item -daemonize
-@findex -daemonize
-Daemonize the QEMU process after initialization. QEMU will not detach from
-standard IO until it is ready to receive connections on any of its devices.
-This option is a useful way for external programs to launch QEMU without having
-to cope with initialization race conditions.
-ETEXI
+SRST
+``-daemonize``
+ Daemonize the QEMU process after initialization. QEMU will not
+ detach from standard IO until it is ready to receive connections on
+ any of its devices. This option is a useful way for external
+ programs to launch QEMU without having to cope with initialization
+ race conditions.
+ERST
DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
"-option-rom rom load a file, rom, into the option ROM space\n",
QEMU_ARCH_ALL)
-STEXI
-@item -option-rom @var{file}
-@findex -option-rom
-Load the contents of @var{file} as an option ROM.
-This option is useful to load things like EtherBoot.
-ETEXI
+SRST
+``-option-rom file``
+ Load the contents of file as an option ROM. This option is useful to
+ load things like EtherBoot.
+ERST
DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
"-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \
" set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
QEMU_ARCH_ALL)
-STEXI
-
-@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew]
-@findex -rtc
-Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
-UTC or local time, respectively. @code{localtime} is required for correct date in
-MS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the
-format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
-
-By default the RTC is driven by the host system time. This allows using of the
-RTC as accurate reference clock inside the guest, specifically if the host
-time is smoothly following an accurate external reference clock, e.g. via NTP.
-If you want to isolate the guest time from the host, you can set @option{clock}
-to @code{rt} instead, which provides a host monotonic clock if host support it.
-To even prevent the RTC from progressing during suspension, you can set @option{clock}
-to @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in
-icount mode in order to preserve determinism; however, note that in icount mode
-the speed of the virtual clock is variable and can in general differ from the
-host clock.
-
-Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
-specifically with Windows' ACPI HAL. This option will try to figure out how
-many timer interrupts were not processed by the Windows guest and will
-re-inject them.
-ETEXI
+SRST
+``-rtc [base=utc|localtime|datetime][,clock=host|rt|vm][,driftfix=none|slew]``
+ Specify ``base`` as ``utc`` or ``localtime`` to let the RTC start at
+ the current UTC or local time, respectively. ``localtime`` is
+ required for correct date in MS-DOS or Windows. To start at a
+ specific point in time, provide datetime in the format
+ ``2006-06-17T16:01:21`` or ``2006-06-17``. The default base is UTC.
+
+ By default the RTC is driven by the host system time. This allows
+ using of the RTC as accurate reference clock inside the guest,
+ specifically if the host time is smoothly following an accurate
+ external reference clock, e.g. via NTP. If you want to isolate the
+ guest time from the host, you can set ``clock`` to ``rt`` instead,
+ which provides a host monotonic clock if host support it. To even
+ prevent the RTC from progressing during suspension, you can set
+ ``clock`` to ``vm`` (virtual clock). '\ ``clock=vm``\ ' is
+ recommended especially in icount mode in order to preserve
+ determinism; however, note that in icount mode the speed of the
+ virtual clock is variable and can in general differ from the host
+ clock.
+
+ Enable ``driftfix`` (i386 targets only) if you experience time drift
+ problems, specifically with Windows' ACPI HAL. This option will try
+ to figure out how many timer interrupts were not processed by the
+ Windows guest and will re-inject them.
+ERST
DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
"-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \
" enable virtual instruction counter with 2^N clock ticks per\n" \
" instruction, enable aligning the host and virtual clocks\n" \
" or disable real time cpu sleeping\n", QEMU_ARCH_ALL)
-STEXI
-@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}]
-@findex -icount
-Enable virtual instruction counter. The virtual cpu will execute one
-instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
-then the virtual cpu speed will be automatically adjusted to keep virtual
-time within a few seconds of real time.
-
-When the virtual cpu is sleeping, the virtual time will advance at default
-speed unless @option{sleep=on|off} is specified.
-With @option{sleep=on|off}, the virtual time will jump to the next timer deadline
-instantly whenever the virtual cpu goes to sleep mode and will not advance
-if no timer is enabled. This behavior give deterministic execution times from
-the guest point of view.
-
-Note that while this option can give deterministic behavior, it does not
-provide cycle accurate emulation. Modern CPUs contain superscalar out of
-order cores with complex cache hierarchies. The number of instructions
-executed often has little or no correlation with actual performance.
-
-@option{align=on} will activate the delay algorithm which will try
-to synchronise the host clock and the virtual clock. The goal is to
-have a guest running at the real frequency imposed by the shift option.
-Whenever the guest clock is behind the host clock and if
-@option{align=on} is specified then we print a message to the user
-to inform about the delay.
-Currently this option does not work when @option{shift} is @code{auto}.
-Note: The sync algorithm will work for those shift values for which
-the guest clock runs ahead of the host clock. Typically this happens
-when the shift value is high (how high depends on the host machine).
-
-When @option{rr} option is specified deterministic record/replay is enabled.
-Replay log is written into @var{filename} file in record mode and
-read from this file in replay mode.
-
-Option rrsnapshot is used to create new vm snapshot named @var{snapshot}
-at the start of execution recording. In replay mode this option is used
-to load the initial VM state.
-ETEXI
+SRST
+``-icount [shift=N|auto][,rr=record|replay,rrfile=filename,rrsnapshot=snapshot]``
+ Enable virtual instruction counter. The virtual cpu will execute one
+ instruction every 2^N ns of virtual time. If ``auto`` is specified
+ then the virtual cpu speed will be automatically adjusted to keep
+ virtual time within a few seconds of real time.
+
+ When the virtual cpu is sleeping, the virtual time will advance at
+ default speed unless ``sleep=on|off`` is specified. With
+ ``sleep=on|off``, the virtual time will jump to the next timer
+ deadline instantly whenever the virtual cpu goes to sleep mode and
+ will not advance if no timer is enabled. This behavior give
+ deterministic execution times from the guest point of view.
+
+ Note that while this option can give deterministic behavior, it does
+ not provide cycle accurate emulation. Modern CPUs contain
+ superscalar out of order cores with complex cache hierarchies. The
+ number of instructions executed often has little or no correlation
+ with actual performance.
+
+ ``align=on`` will activate the delay algorithm which will try to
+ synchronise the host clock and the virtual clock. The goal is to
+ have a guest running at the real frequency imposed by the shift
+ option. Whenever the guest clock is behind the host clock and if
+ ``align=on`` is specified then we print a message to the user to
+ inform about the delay. Currently this option does not work when
+ ``shift`` is ``auto``. Note: The sync algorithm will work for those
+ shift values for which the guest clock runs ahead of the host clock.
+ Typically this happens when the shift value is high (how high
+ depends on the host machine).
+
+ When ``rr`` option is specified deterministic record/replay is
+ enabled. Replay log is written into filename file in record mode and
+ read from this file in replay mode.
+
+ Option rrsnapshot is used to create new vm snapshot named snapshot
+ at the start of execution recording. In replay mode this option is
+ used to load the initial VM state.
+ERST
DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
"-watchdog model\n" \
" enable virtual hardware watchdog [default=none]\n",
QEMU_ARCH_ALL)
-STEXI
-@item -watchdog @var{model}
-@findex -watchdog
-Create a virtual hardware watchdog device. Once enabled (by a guest
-action), the watchdog must be periodically polled by an agent inside
-the guest or else the guest will be restarted. Choose a model for
-which your guest has drivers.
-
-The @var{model} is the model of hardware watchdog to emulate. Use
-@code{-watchdog help} to list available hardware models. Only one
-watchdog can be enabled for a guest.
-
-The following models may be available:
-@table @option
-@item ib700
-iBASE 700 is a very simple ISA watchdog with a single timer.
-@item i6300esb
-Intel 6300ESB I/O controller hub is a much more featureful PCI-based
-dual-timer watchdog.
-@item diag288
-A virtual watchdog for s390x backed by the diagnose 288 hypercall
-(currently KVM only).
-@end table
-ETEXI
+SRST
+``-watchdog model``
+ Create a virtual hardware watchdog device. Once enabled (by a guest
+ action), the watchdog must be periodically polled by an agent inside
+ the guest or else the guest will be restarted. Choose a model for
+ which your guest has drivers.
+
+ The model is the model of hardware watchdog to emulate. Use
+ ``-watchdog help`` to list available hardware models. Only one
+ watchdog can be enabled for a guest.
+
+ The following models may be available:
+
+ ``ib700``
+ iBASE 700 is a very simple ISA watchdog with a single timer.
+
+ ``i6300esb``
+ Intel 6300ESB I/O controller hub is a much more featureful
+ PCI-based dual-timer watchdog.
+
+ ``diag288``
+ A virtual watchdog for s390x backed by the diagnose 288
+ hypercall (currently KVM only).
+ERST
DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
"-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
" action when watchdog fires [default=reset]\n",
QEMU_ARCH_ALL)
-STEXI
-@item -watchdog-action @var{action}
-@findex -watchdog-action
-
-The @var{action} controls what QEMU will do when the watchdog timer
-expires.
-The default is
-@code{reset} (forcefully reset the guest).
-Other possible actions are:
-@code{shutdown} (attempt to gracefully shutdown the guest),
-@code{poweroff} (forcefully poweroff the guest),
-@code{inject-nmi} (inject a NMI into the guest),
-@code{pause} (pause the guest),
-@code{debug} (print a debug message and continue), or
-@code{none} (do nothing).
-
-Note that the @code{shutdown} action requires that the guest responds
-to ACPI signals, which it may not be able to do in the sort of
-situations where the watchdog would have expired, and thus
-@code{-watchdog-action shutdown} is not recommended for production use.
-
-Examples:
-
-@table @code
-@item -watchdog i6300esb -watchdog-action pause
-@itemx -watchdog ib700
-@end table
-ETEXI
+SRST
+``-watchdog-action action``
+ The action controls what QEMU will do when the watchdog timer
+ expires. The default is ``reset`` (forcefully reset the guest).
+ Other possible actions are: ``shutdown`` (attempt to gracefully
+ shutdown the guest), ``poweroff`` (forcefully poweroff the guest),
+ ``inject-nmi`` (inject a NMI into the guest), ``pause`` (pause the
+ guest), ``debug`` (print a debug message and continue), or ``none``
+ (do nothing).
+
+ Note that the ``shutdown`` action requires that the guest responds
+ to ACPI signals, which it may not be able to do in the sort of
+ situations where the watchdog would have expired, and thus
+ ``-watchdog-action shutdown`` is not recommended for production use.
+
+ Examples:
+
+ ``-watchdog i6300esb -watchdog-action pause``; \ ``-watchdog ib700``
+
+ERST
DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
"-echr chr set terminal escape character instead of ctrl-a\n",
QEMU_ARCH_ALL)
-STEXI
-
-@item -echr @var{numeric_ascii_value}
-@findex -echr
-Change the escape character used for switching to the monitor when using
-monitor and serial sharing. The default is @code{0x01} when using the
-@code{-nographic} option. @code{0x01} is equal to pressing
-@code{Control-a}. You can select a different character from the ascii
-control keys where 1 through 26 map to Control-a through Control-z. For
-instance you could use the either of the following to change the escape
-character to Control-t.
-@table @code
-@item -echr 0x14
-@itemx -echr 20
-@end table
-ETEXI
+SRST
+``-echr numeric_ascii_value``
+ Change the escape character used for switching to the monitor when
+ using monitor and serial sharing. The default is ``0x01`` when using
+ the ``-nographic`` option. ``0x01`` is equal to pressing
+ ``Control-a``. You can select a different character from the ascii
+ control keys where 1 through 26 map to Control-a through Control-z.
+ For instance you could use the either of the following to change the
+ escape character to Control-t.
+
+ ``-echr 0x14``; \ ``-echr 20``
+
+ERST
DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
"-show-cursor show cursor\n", QEMU_ARCH_ALL)
-STEXI
-@item -show-cursor
-@findex -show-cursor
-Show cursor.
-ETEXI
+SRST
+``-show-cursor``
+ Show cursor.
+ERST
DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
"-tb-size n set TB size\n", QEMU_ARCH_ALL)
-STEXI
-@item -tb-size @var{n}
-@findex -tb-size
-Set TCG translation block cache size. Deprecated, use @samp{-accel tcg,tb-size=@var{n}}
-instead.
-ETEXI
+SRST
+``-tb-size n``
+ Set TCG translation block cache size. Deprecated, use
+ '\ ``-accel tcg,tb-size=n``\ ' instead.
+ERST
DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
"-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \
"-incoming defer\n" \
" wait for the URI to be specified via migrate_incoming\n",
QEMU_ARCH_ALL)
-STEXI
-@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
-@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6]
-@findex -incoming
-Prepare for incoming migration, listen on a given tcp port.
+SRST
+``-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]``
+ \
+``-incoming rdma:host:port[,ipv4][,ipv6]``
+ Prepare for incoming migration, listen on a given tcp port.
-@item -incoming unix:@var{socketpath}
-Prepare for incoming migration, listen on a given unix socket.
+``-incoming unix:socketpath``
+ Prepare for incoming migration, listen on a given unix socket.
-@item -incoming fd:@var{fd}
-Accept incoming migration from a given filedescriptor.
+``-incoming fd:fd``
+ Accept incoming migration from a given filedescriptor.
-@item -incoming exec:@var{cmdline}
-Accept incoming migration as an output from specified external command.
+``-incoming exec:cmdline``
+ Accept incoming migration as an output from specified external
+ command.
-@item -incoming defer
-Wait for the URI to be specified via migrate_incoming. The monitor can
-be used to change settings (such as migration parameters) prior to issuing
-the migrate_incoming to allow the migration to begin.
-ETEXI
+``-incoming defer``
+ Wait for the URI to be specified via migrate\_incoming. The monitor
+ can be used to change settings (such as migration parameters) prior
+ to issuing the migrate\_incoming to allow the migration to begin.
+ERST
DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \
"-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL)
-STEXI
-@item -only-migratable
-@findex -only-migratable
-Only allow migratable devices. Devices will not be allowed to enter an
-unmigratable state.
-ETEXI
+SRST
+``-only-migratable``
+ Only allow migratable devices. Devices will not be allowed to enter
+ an unmigratable state.
+ERST
DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
"-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
-STEXI
-@item -nodefaults
-@findex -nodefaults
-Don't create default devices. Normally, QEMU sets the default devices like serial
-port, parallel port, virtual console, monitor device, VGA adapter, floppy and
-CD-ROM drive and others. The @code{-nodefaults} option will disable all those
-default devices.
-ETEXI
+SRST
+``-nodefaults``
+ Don't create default devices. Normally, QEMU sets the default
+ devices like serial port, parallel port, virtual console, monitor
+ device, VGA adapter, floppy and CD-ROM drive and others. The
+ ``-nodefaults`` option will disable all those default devices.
+ERST
#ifndef _WIN32
DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
"-chroot dir chroot to dir just before starting the VM\n",
QEMU_ARCH_ALL)
#endif
-STEXI
-@item -chroot @var{dir}
-@findex -chroot
-Immediately before starting guest execution, chroot to the specified
-directory. Especially useful in combination with -runas.
-ETEXI
+SRST
+``-chroot dir``
+ Immediately before starting guest execution, chroot to the specified
+ directory. Especially useful in combination with -runas.
+ERST
#ifndef _WIN32
DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
" user can be numeric uid:gid instead\n",
QEMU_ARCH_ALL)
#endif
-STEXI
-@item -runas @var{user}
-@findex -runas
-Immediately before starting guest execution, drop root privileges, switching
-to the specified user.
-ETEXI
+SRST
+``-runas user``
+ Immediately before starting guest execution, drop root privileges,
+ switching to the specified user.
+ERST
DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
"-prom-env variable=value\n"
" set OpenBIOS nvram variables\n",
QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
-STEXI
-@item -prom-env @var{variable}=@var{value}
-@findex -prom-env
-Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
-ETEXI
+SRST
+``-prom-env variable=value``
+ Set OpenBIOS nvram variable to given value (PPC, SPARC only).
+
+ ::
+
+ qemu-system-sparc -prom-env 'auto-boot?=false' \
+ -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
+
+ ::
+
+ qemu-system-ppc -prom-env 'auto-boot?=false' \
+ -prom-env 'boot-device=hd:2,\yaboot' \
+ -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
+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_MIPS | QEMU_ARCH_NIOS2)
-STEXI
-@item -semihosting
-@findex -semihosting
-Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only).
-ETEXI
+SRST
+``-semihosting``
+ Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only).
+
+ 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.
+ERST
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_MIPS | QEMU_ARCH_NIOS2)
-STEXI
-@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]
-@findex -semihosting-config
-Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II only).
-@table @option
-@item target=@code{native|gdb|auto}
-Defines where the semihosting calls will be addressed, to QEMU (@code{native})
-or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb}
-during debug sessions and @code{native} otherwise.
-@item chardev=@var{str1}
-Send the output to a chardev backend output for native or auto output when not in gdb
-@item arg=@var{str1},arg=@var{str2},...
-Allows the user to pass input arguments, and can be used multiple times to build
-up a list. The old-style @code{-kernel}/@code{-append} method of passing a
-command line is still supported for backward compatibility. If both the
-@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are
-specified, the former is passed to semihosting as it always takes precedence.
-@end table
-ETEXI
+SRST
+``-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]``
+ Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II
+ 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.
+
+ ``target=native|gdb|auto``
+ Defines where the semihosting calls will be addressed, to QEMU
+ (``native``) or to GDB (``gdb``). The default is ``auto``, which
+ means ``gdb`` during debug sessions and ``native`` otherwise.
+
+ ``chardev=str1``
+ Send the output to a chardev backend output for native or auto
+ output when not in gdb
+
+ ``arg=str1,arg=str2,...``
+ Allows the user to pass input arguments, and can be used
+ multiple times to build up a list. The old-style
+ ``-kernel``/``-append`` method of passing a command line is
+ still supported for backward compatibility. If both the
+ ``--semihosting-config arg`` and the ``-kernel``/``-append`` are
+ specified, the former is passed to semihosting as it always
+ takes precedence.
+ERST
DEF("old-param", 0, QEMU_OPTION_old_param,
"-old-param old param mode\n", QEMU_ARCH_ARM)
-STEXI
-@item -old-param
-@findex -old-param (ARM)
-Old param mode (ARM only).
-ETEXI
+SRST
+``-old-param``
+ Old param mode (ARM only).
+ERST
DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \
"-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \
" blacklisting *fork and execve\n" \
" use 'resourcecontrol' to disable process affinity and schedular priority\n",
QEMU_ARCH_ALL)
-STEXI
-@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}]
-@findex -sandbox
-Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will
-disable it. The default is 'off'.
-@table @option
-@item obsolete=@var{string}
-Enable Obsolete system calls
-@item elevateprivileges=@var{string}
-Disable set*uid|gid system calls
-@item spawn=@var{string}
-Disable *fork and execve
-@item resourcecontrol=@var{string}
-Disable process affinity and schedular priority
-@end table
-ETEXI
+SRST
+``-sandbox arg[,obsolete=string][,elevateprivileges=string][,spawn=string][,resourcecontrol=string]``
+ Enable Seccomp mode 2 system call filter. 'on' will enable syscall
+ filtering and 'off' will disable it. The default is 'off'.
+
+ ``obsolete=string``
+ Enable Obsolete system calls
+
+ ``elevateprivileges=string``
+ Disable set\*uid\|gid system calls
+
+ ``spawn=string``
+ Disable \*fork and execve
+
+ ``resourcecontrol=string``
+ Disable process affinity and schedular priority
+ERST
DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
"-readconfig <file>\n", QEMU_ARCH_ALL)
-STEXI
-@item -readconfig @var{file}
-@findex -readconfig
-Read device configuration from @var{file}. This approach is useful when you want to spawn
-QEMU process with many command line options but you don't want to exceed the command line
-character limit.
-ETEXI
+SRST
+``-readconfig file``
+ Read device configuration from file. This approach is useful when
+ you want to spawn QEMU process with many command line options but
+ you don't want to exceed the command line character limit.
+ERST
DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
"-writeconfig <file>\n"
" read/write config file\n", QEMU_ARCH_ALL)
-STEXI
-@item -writeconfig @var{file}
-@findex -writeconfig
-Write device configuration to @var{file}. The @var{file} can be either filename to save
-command line and device configuration into file or dash @code{-}) character to print the
-output to stdout. This can be later used as input file for @code{-readconfig} option.
-ETEXI
+SRST
+``-writeconfig file``
+ Write device configuration to file. The file can be either filename
+ to save command line and device configuration into file or dash
+ ``-``) character to print the output to stdout. This can be later
+ used as input file for ``-readconfig`` option.
+ERST
DEF("no-user-config", 0, QEMU_OPTION_nouserconfig,
"-no-user-config\n"
" do not load default user-provided config files at startup\n",
QEMU_ARCH_ALL)
-STEXI
-@item -no-user-config
-@findex -no-user-config
-The @code{-no-user-config} option makes QEMU not load any of the user-provided
-config files on @var{sysconfdir}.
-ETEXI
+SRST
+``-no-user-config``
+ The ``-no-user-config`` option makes QEMU not load any of the
+ user-provided config files on sysconfdir.
+ERST
DEF("trace", HAS_ARG, QEMU_OPTION_trace,
"-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n"
" specify tracing options\n",
QEMU_ARCH_ALL)
-STEXI
-HXCOMM This line is not accurate, as some sub-options are backend-specific but
-HXCOMM HX does not support conditional compilation of text.
-@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
-@findex -trace
-@include qemu-option-trace.texi
-ETEXI
+SRST
+``-trace [[enable=]pattern][,events=file][,file=file]``
+ .. include:: ../qemu-option-trace.rst.inc
+
+ERST
DEF("plugin", HAS_ARG, QEMU_OPTION_plugin,
"-plugin [file=]<file>[,arg=<string>]\n"
" load a plugin\n",
QEMU_ARCH_ALL)
-STEXI
-@item -plugin file=@var{file}[,arg=@var{string}]
-@findex -plugin
+SRST
+``-plugin file=file[,arg=string]``
+ Load a plugin.
-Load a plugin.
+ ``file=file``
+ Load the given plugin from a shared library file.
-@table @option
-@item file=@var{file}
-Load the given plugin from a shared library file.
-@item arg=@var{string}
-Argument string passed to the plugin. (Can be given multiple times.)
-@end table
-ETEXI
+ ``arg=string``
+ Argument string passed to the plugin. (Can be given multiple
+ times.)
+ERST
HXCOMM Internal use
DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL)
"-enable-fips enable FIPS 140-2 compliance\n",
QEMU_ARCH_ALL)
#endif
-STEXI
-@item -enable-fips
-@findex -enable-fips
-Enable FIPS 140-2 compliance mode.
-ETEXI
+SRST
+``-enable-fips``
+ Enable FIPS 140-2 compliance mode.
+ERST
HXCOMM Deprecated by -accel tcg
DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386)
" control error message format\n"
" timestamp=on enables timestamps (default: off)\n",
QEMU_ARCH_ALL)
-STEXI
-@item -msg timestamp[=on|off]
-@findex -msg
-Control error message format.
-@table @option
-@item timestamp=on|off
-Prefix messages with a timestamp. Default is off.
-@end table
-ETEXI
+SRST
+``-msg timestamp[=on|off]``
+ Control error message format.
+
+ ``timestamp=on|off``
+ Prefix messages with a timestamp. Default is off.
+ERST
DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate,
"-dump-vmstate <file>\n"
" check for possible regressions in migration code\n"
" by comparing two such vmstate dumps.\n",
QEMU_ARCH_ALL)
-STEXI
-@item -dump-vmstate @var{file}
-@findex -dump-vmstate
-Dump json-encoded vmstate information for current machine type to file
-in @var{file}
-ETEXI
+SRST
+``-dump-vmstate file``
+ Dump json-encoded vmstate information for current machine type to
+ file in file
+ERST
DEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile,
"-enable-sync-profile\n"
" enable synchronization profiling\n",
QEMU_ARCH_ALL)
-STEXI
-@item -enable-sync-profile
-@findex -enable-sync-profile
-Enable synchronization profiling.
-ETEXI
-
-STEXI
-@end table
-ETEXI
+SRST
+``-enable-sync-profile``
+ Enable synchronization profiling.
+ERST
+
DEFHEADING()
DEFHEADING(Generic object creation:)
-STEXI
-@table @option
-ETEXI
DEF("object", HAS_ARG, QEMU_OPTION_object,
"-object TYPENAME[,PROP1=VALUE1,...]\n"
" property must be set. These objects are placed in the\n"
" '/objects' path.\n",
QEMU_ARCH_ALL)
-STEXI
-@item -object @var{typename}[,@var{prop1}=@var{value1},...]
-@findex -object
-Create a new object of type @var{typename} setting properties
-in the order they are specified. Note that the 'id'
-property must be set. These objects are placed in the
-'/objects' path.
-
-@table @option
-
-@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off},discard-data=@var{on|off},merge=@var{on|off},dump=@var{on|off},prealloc=@var{on|off},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},align=@var{align}
-
-Creates a memory file backend object, which can be used to back
-the guest RAM with huge pages.
-
-The @option{id} parameter is a unique ID that will be used to reference this
-memory region when configuring the @option{-numa} argument.
+SRST
+``-object typename[,prop1=value1,...]``
+ Create a new object of type typename setting properties in the order
+ 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``
+ Creates a memory file backend object, which can be used to back
+ 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.
+
+ The ``size`` option provides the size of the memory region, and
+ accepts common suffixes, eg ``500M``.
+
+ The ``mem-path`` provides the path to either a shared memory or
+ huge page filesystem mount.
+
+ The ``share`` boolean option determines whether the memory
+ region is marked as private to QEMU, or shared. The latter
+ allows a co-operating external process to access the QEMU memory
+ region.
+
+ The ``share`` is also required for pvrdma devices due to
+ limitations in the RDMA API provided by Linux.
+
+ Setting share=on might affect the ability to configure NUMA
+ bindings for the memory backend under some circumstances, see
+ Documentation/vm/numa\_memory\_policy.txt on the Linux kernel
+ source tree for additional details.
+
+ Setting the ``discard-data`` boolean option to on indicates that
+ file contents can be destroyed when QEMU exits, to avoid
+ unnecessarily flushing data to the backing file. Note that
+ ``discard-data`` is only an optimization, and QEMU might not
+ discard file contents if it aborts unexpectedly or is terminated
+ using SIGKILL.
+
+ The ``merge`` boolean option enables memory merge, also known as
+ MADV\_MERGEABLE, so that Kernel Samepage Merging will consider
+ the pages for memory deduplication.
+
+ Setting the ``dump`` boolean option to off excludes the memory
+ from core dumps. This feature is also known as MADV\_DONTDUMP.
+
+ The ``prealloc`` boolean option enables memory preallocation.
+
+ The ``host-nodes`` option binds the memory range to a list of
+ NUMA host nodes.
+
+ The ``policy`` option sets the NUMA policy to one of the
+ following values:
+
+ ``default``
+ default host policy
+
+ ``preferred``
+ prefer the given host node list for allocation
+
+ ``bind``
+ restrict memory allocation to the given host node list
+
+ ``interleave``
+ interleave memory allocations across the given host node
+ list
+
+ The ``align`` option specifies the base address alignment when
+ QEMU mmap(2) ``mem-path``, and accepts common suffixes, eg
+ ``2M``. Some backend store specified by ``mem-path`` requires an
+ alignment different than the default one used by QEMU, eg the
+ device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In
+ such cases, users can specify the required alignment via this
+ option.
+
+ 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
+ NVDIMM). If ``pmem`` is set to 'on', QEMU will take necessary
+ operations to guarantee the persistence of its own writes to
+ ``mem-path`` (e.g. in vNVDIMM label emulation and live
+ migration). Also, we will map the backend-file with MAP\_SYNC
+ flag, which ensures the file metadata is in sync for
+ ``mem-path`` in case of host crash or a power failure. MAP\_SYNC
+ requires support from both the host kernel (since Linux kernel
+ 4.15) and the filesystem of ``mem-path`` mounted with DAX
+ option.
+
+ ``-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
+ ``-m`` option that is traditionally used to define guest RAM.
+ Please refer to ``memory-backend-file`` for a description of the
+ options.
+
+ ``-object memory-backend-memfd,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,seal=on|off,hugetlb=on|off,hugetlbsize=size``
+ Creates an anonymous memory file backend object, which allows
+ QEMU to share the memory with an external process (e.g. when
+ using vhost-user). The memory is allocated with memfd and
+ optional sealing. (Linux only)
+
+ The ``seal`` option creates a sealed-file, that will block
+ further resizing the memory ('on' by default).
+
+ The ``hugetlb`` option specify the file to be created resides in
+ the hugetlbfs filesystem (since Linux 4.14). Used in conjunction
+ with the ``hugetlb`` option, the ``hugetlbsize`` option specify
+ the hugetlb page size on systems that support multiple hugetlb
+ page sizes (it must be a power of 2 value supported by the
+ system).
+
+ In some versions of Linux, the ``hugetlb`` option is
+ incompatible with the ``seal`` option (requires at least Linux
+ 4.16).
+
+ Please refer to ``memory-backend-file`` for a description of the
+ other options.
+
+ The ``share`` boolean option is on by default with memfd.
+
+ ``-object rng-builtin,id=id``
+ Creates a random number generator backend which obtains entropy
+ from QEMU builtin functions. The ``id`` parameter is a unique ID
+ that will be used to reference this entropy backend from the
+ ``virtio-rng`` device. By default, the ``virtio-rng`` device
+ uses this RNG backend.
+
+ ``-object rng-random,id=id,filename=/dev/random``
+ Creates a random number generator backend which obtains entropy
+ from a device on the host. The ``id`` parameter is a unique ID
+ that will be used to reference this entropy backend from the
+ ``virtio-rng`` device. The ``filename`` parameter specifies
+ which file to obtain entropy from and if omitted defaults to
+ ``/dev/urandom``.
+
+ ``-object rng-egd,id=id,chardev=chardevid``
+ Creates a random number generator backend which obtains entropy
+ from an external daemon running on the host. The ``id``
+ parameter is a unique ID that will be used to reference this
+ entropy backend from the ``virtio-rng`` device. The ``chardev``
+ parameter is the unique ID of a character device backend that
+ provides the connection to the RNG daemon.
+
+ ``-object tls-creds-anon,id=id,endpoint=endpoint,dir=/path/to/cred/dir,verify-peer=on|off``
+ Creates a TLS anonymous credentials object, which can be used to
+ provide TLS support on network backends. The ``id`` parameter is
+ a unique ID which network backends will use to access the
+ credentials. The ``endpoint`` is either ``server`` or ``client``
+ depending on whether the QEMU network backend that uses the
+ credentials will be acting as a client or as a server. If
+ ``verify-peer`` is enabled (the default) then once the handshake
+ is completed, the peer credentials will be verified, though this
+ is a no-op for anonymous credentials.
+
+ The dir parameter tells QEMU where to find the credential files.
+ For server endpoints, this directory may contain a file
+ dh-params.pem providing diffie-hellman parameters to use for the
+ TLS server. If the file is missing, QEMU will generate a set of
+ DH parameters at startup. This is a computationally expensive
+ operation that consumes random pool entropy, so it is
+ recommended that a persistent set of parameters be generated
+ upfront and saved.
+
+ ``-object tls-creds-psk,id=id,endpoint=endpoint,dir=/path/to/keys/dir[,username=username]``
+ Creates a TLS Pre-Shared Keys (PSK) credentials object, which
+ can be used to provide TLS support on network backends. The
+ ``id`` parameter is a unique ID which network backends will use
+ to access the credentials. The ``endpoint`` is either ``server``
+ or ``client`` depending on whether the QEMU network backend that
+ uses the credentials will be acting as a client or as a server.
+ For clients only, ``username`` is the username which will be
+ sent to the server. If omitted it defaults to "qemu".
+
+ The dir parameter tells QEMU where to find the keys file. It is
+ called "dir/keys.psk" and contains "username:key" pairs. This
+ file can most easily be created using the GnuTLS ``psktool``
+ program.
+
+ For server endpoints, dir may also contain a file dh-params.pem
+ providing diffie-hellman parameters to use for the TLS server.
+ If the file is missing, QEMU will generate a set of DH
+ parameters at startup. This is a computationally expensive
+ operation that consumes random pool entropy, so it is
+ recommended that a persistent set of parameters be generated up
+ front and saved.
+
+ ``-object tls-creds-x509,id=id,endpoint=endpoint,dir=/path/to/cred/dir,priority=priority,verify-peer=on|off,passwordid=id``
+ Creates a TLS anonymous credentials object, which can be used to
+ provide TLS support on network backends. The ``id`` parameter is
+ a unique ID which network backends will use to access the
+ credentials. The ``endpoint`` is either ``server`` or ``client``
+ depending on whether the QEMU network backend that uses the
+ credentials will be acting as a client or as a server. If
+ ``verify-peer`` is enabled (the default) then once the handshake
+ is completed, the peer credentials will be verified. With x509
+ certificates, this implies that the clients must be provided
+ with valid client certificates too.
+
+ The dir parameter tells QEMU where to find the credential files.
+ For server endpoints, this directory may contain a file
+ dh-params.pem providing diffie-hellman parameters to use for the
+ TLS server. If the file is missing, QEMU will generate a set of
+ DH parameters at startup. This is a computationally expensive
+ operation that consumes random pool entropy, so it is
+ recommended that a persistent set of parameters be generated
+ upfront and saved.
+
+ For x509 certificate credentials the directory will contain
+ further files providing the x509 certificates. The certificates
+ must be stored in PEM format, in filenames ca-cert.pem,
+ ca-crl.pem (optional), server-cert.pem (only servers),
+ server-key.pem (only servers), client-cert.pem (only clients),
+ and client-key.pem (only clients).
+
+ For the server-key.pem and client-key.pem files which contain
+ sensitive private keys, it is possible to use an encrypted
+ version by providing the passwordid parameter. This provides the
+ ID of a previously created ``secret`` object containing the
+ password for decryption.
+
+ The priority parameter allows to override the global default
+ priority used by gnutls. This can be useful if the system
+ administrator needs to use a weaker set of crypto priorities for
+ QEMU without potentially forcing the weakness onto all
+ applications. Or conversely if one wants wants a stronger
+ default for QEMU than for all other applications, they can do
+ this through this parameter. Its format is a gnutls priority
+ string as described at
+ https://gnutls.org/manual/html_node/Priority-Strings.html.
+
+ ``-object filter-buffer,id=id,netdev=netdevid,interval=t[,queue=all|rx|tx][,status=on|off][,position=head|tail|id=<id>][,insert=behind|before]``
+ Interval t can't be 0, this filter batches the packet delivery:
+ all packets arriving in a given interval on netdev netdevid are
+ delayed until the end of the interval. Interval is in
+ microseconds. ``status`` is optional that indicate whether the
+ netfilter is on (enabled) or off (disabled), the default status
+ for netfilter will be 'on'.
+
+ queue all\|rx\|tx is an option that can be applied to any
+ netfilter.
+
+ ``all``: the filter is attached both to the receive and the
+ transmit queue of the netdev (default).
+
+ ``rx``: the filter is attached to the receive queue of the
+ netdev, where it will receive packets sent to the netdev.
+
+ ``tx``: the filter is attached to the transmit queue of the
+ netdev, where it will receive packets sent by the netdev.
+
+ position head\|tail\|id=<id> is an option to specify where the
+ filter should be inserted in the filter list. It can be applied
+ to any netfilter.
+
+ ``head``: the filter is inserted at the head of the filter list,
+ before any existing filters.
+
+ ``tail``: the filter is inserted at the tail of the filter list,
+ behind any existing filters (default).
+
+ ``id=<id>``: the filter is inserted before or behind the filter
+ specified by <id>, see the insert option below.
+
+ insert behind\|before is an option to specify where to insert
+ the new filter relative to the one specified with
+ position=id=<id>. It can be applied to any netfilter.
+
+ ``before``: insert before the specified filter.
+
+ ``behind``: insert behind the specified filter (default).
+
+ ``-object filter-mirror,id=id,netdev=netdevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support][,position=head|tail|id=<id>][,insert=behind|before]``
+ filter-mirror on netdev netdevid,mirror net packet to
+ chardevchardevid, if it has the vnet\_hdr\_support flag,
+ filter-mirror will mirror packet with vnet\_hdr\_len.
+
+ ``-object filter-redirector,id=id,netdev=netdevid,indev=chardevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support][,position=head|tail|id=<id>][,insert=behind|before]``
+ filter-redirector on netdev netdevid,redirect filter's net
+ packet to chardev chardevid,and redirect indev's packet to
+ filter.if it has the vnet\_hdr\_support flag, filter-redirector
+ will redirect packet with vnet\_hdr\_len. Create a
+ filter-redirector we need to differ outdev id from indev id, id
+ can not be the same. we can just use indev or outdev, but at
+ least one of indev or outdev need to be specified.
+
+ ``-object filter-rewriter,id=id,netdev=netdevid,queue=all|rx|tx,[vnet_hdr_support][,position=head|tail|id=<id>][,insert=behind|before]``
+ Filter-rewriter is a part of COLO project.It will rewrite tcp
+ packet to secondary from primary to keep secondary tcp
+ connection,and rewrite tcp packet to primary from secondary make
+ tcp packet can be handled by client.if it has the
+ vnet\_hdr\_support flag, we can parse packet with vnet header.
+
+ usage: colo secondary: -object
+ filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 -object
+ filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 -object
+ filter-rewriter,id=rew0,netdev=hn0,queue=all
+
+ ``-object filter-dump,id=id,netdev=dev[,file=filename][,maxlen=len][,position=head|tail|id=<id>][,insert=behind|before]``
+ Dump the network traffic on netdev dev to the file specified by
+ filename. At most len bytes (64k by default) per packet are
+ stored. The file format is libpcap, so it can be analyzed with
+ tools such as tcpdump or Wireshark.
+
+ ``-object colo-compare,id=id,primary_in=chardevid,secondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_support][,notify_dev=id]``
+ Colo-compare gets packet from primary\_inchardevid and
+ secondary\_inchardevid, than compare primary packet with
+ secondary packet. If the packets are same, we will output
+ primary packet to outdevchardevid, else we will notify
+ colo-frame do checkpoint and send primary packet to
+ outdevchardevid. In order to improve efficiency, we need to put
+ the task of comparison in another thread. If it has the
+ vnet\_hdr\_support flag, colo compare will send/recv packet with
+ vnet\_hdr\_len. If you want to use Xen COLO, will need the
+ notify\_dev to notify Xen colo-frame to do checkpoint.
+
+ we must use it with the help of filter-mirror and
+ filter-redirector.
+
+ ::
+
+ KVM COLO
+
+ primary:
+ -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
+ -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
+ -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
+ -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
+ -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
+ -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
+ -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
+ -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
+ -object iothread,id=iothread1
+ -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
+ -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
+ -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
+ -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1
+
+ secondary:
+ -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
+ -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
+ -chardev socket,id=red0,host=3.3.3.3,port=9003
+ -chardev socket,id=red1,host=3.3.3.3,port=9004
+ -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
+ -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
+
+
+ Xen COLO
+
+ primary:
+ -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
+ -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
+ -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
+ -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
+ -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
+ -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
+ -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
+ -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
+ -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait
+ -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
+ -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
+ -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
+ -object iothread,id=iothread1
+ -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1
+
+ secondary:
+ -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
+ -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
+ -chardev socket,id=red0,host=3.3.3.3,port=9003
+ -chardev socket,id=red1,host=3.3.3.3,port=9004
+ -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
+ -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
+
+ If you want to know the detail of above command line, you can
+ read the colo-compare git log.
+
+ ``-object cryptodev-backend-builtin,id=id[,queues=queues]``
+ Creates a cryptodev backend which executes crypto opreation from
+ the QEMU cipher APIS. The id parameter is a unique ID that will
+ be used to reference this cryptodev backend from the
+ ``virtio-crypto`` device. The queues parameter is optional,
+ which specify the queue number of cryptodev backend, the default
+ of queues is 1.
+
+ .. parsed-literal::
+
+ # |qemu_system| \
+ [...] \
+ -object cryptodev-backend-builtin,id=cryptodev0 \
+ -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
+ [...]
+
+ ``-object cryptodev-vhost-user,id=id,chardev=chardevid[,queues=queues]``
+ Creates a vhost-user cryptodev backend, backed by a chardev
+ chardevid. The id parameter is a unique ID that will be used to
+ reference this cryptodev backend from the ``virtio-crypto``
+ device. The chardev should be a unix domain socket backed one.
+ The vhost-user uses a specifically defined protocol to pass
+ vhost ioctl replacement messages to an application on the other
+ end of the socket. The queues parameter is optional, which
+ specify the queue number of cryptodev backend for multiqueue
+ vhost-user, the default of queues is 1.
+
+ .. parsed-literal::
+
+ # |qemu_system| \
+ [...] \
+ -chardev socket,id=chardev0,path=/path/to/socket \
+ -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
+ -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
+ [...]
+
+ ``-object secret,id=id,data=string,format=raw|base64[,keyid=secretid,iv=string]``
+ \
+ ``-object secret,id=id,file=filename,format=raw|base64[,keyid=secretid,iv=string]``
+ Defines a secret to store a password, encryption key, or some
+ other sensitive data. The sensitive data can either be passed
+ directly via the data parameter, or indirectly via the file
+ parameter. Using the data parameter is insecure unless the
+ sensitive data is encrypted.
+
+ The sensitive data can be provided in raw format (the default),
+ or base64. When encoded as JSON, the raw format only supports
+ valid UTF-8 characters, so base64 is recommended for sending
+ binary data. QEMU will convert from which ever format is
+ provided to the format it needs internally. eg, an RBD password
+ can be provided in raw format, even though it will be base64
+ encoded when passed onto the RBD sever.
+
+ For added protection, it is possible to encrypt the data
+ associated with a secret using the AES-256-CBC cipher. Use of
+ encryption is indicated by providing the keyid and iv
+ parameters. The keyid parameter provides the ID of a previously
+ defined secret that contains the AES-256 decryption key. This
+ key should be 32-bytes long and be base64 encoded. The iv
+ parameter provides the random initialization vector used for
+ encryption of this particular secret and should be a base64
+ encrypted string of the 16-byte IV.
+
+ The simplest (insecure) usage is to provide the secret inline
+
+ .. parsed-literal::
+
+ # |qemu_system| -object secret,id=sec0,data=letmein,format=raw
+
+ The simplest secure usage is to provide the secret via a file
+
+ # printf "letmein" > mypasswd.txt # QEMU\_SYSTEM\_MACRO -object
+ secret,id=sec0,file=mypasswd.txt,format=raw
+
+ For greater security, AES-256-CBC should be used. To illustrate
+ usage, consider the openssl command line tool which can encrypt
+ the data. Note that when encrypting, the plaintext must be
+ padded to the cipher block size (32 bytes) using the standard
+ PKCS#5/6 compatible padding algorithm.
+
+ First a master key needs to be created in base64 encoding:
+
+ ::
+
+ # openssl rand -base64 32 > key.b64
+ # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
+
+ Each secret to be encrypted needs to have a random
+ initialization vector generated. These do not need to be kept
+ secret
+
+ ::
+
+ # openssl rand -base64 16 > iv.b64
+ # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
+
+ The secret to be defined can now be encrypted, in this case
+ we're telling openssl to base64 encode the result, but it could
+ be left as raw bytes if desired.
+
+ ::
+
+ # SECRET=$(printf "letmein" |
+ openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
+
+ When launching QEMU, create a master secret pointing to
+ ``key.b64`` and specify that to be used to decrypt the user
+ password. Pass the contents of ``iv.b64`` to the second secret
+
+ .. parsed-literal::
+
+ # |qemu_system| \
+ -object secret,id=secmaster0,format=base64,file=key.b64 \
+ -object secret,id=sec0,keyid=secmaster0,format=base64,\
+ data=$SECRET,iv=$(<iv.b64)
+
+ ``-object sev-guest,id=id,cbitpos=cbitpos,reduced-phys-bits=val,[sev-device=string,policy=policy,handle=handle,dh-cert-file=file,session-file=file]``
+ Create a Secure Encrypted Virtualization (SEV) guest object,
+ which can be used to provide the guest memory encryption support
+ on AMD processors.
+
+ When memory encryption is enabled, one of the physical address
+ bit (aka the C-bit) is utilized to mark if a memory page is
+ protected. The ``cbitpos`` is used to provide the C-bit
+ position. The C-bit position is Host family dependent hence user
+ must provide this value. On EPYC, the value should be 47.
+
+ When memory encryption is enabled, we loose certain bits in
+ 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.
+
+ The ``sev-device`` provides the device file to use for
+ communicating with the SEV firmware running inside AMD Secure
+ Processor. The default device is '/dev/sev'. If hardware
+ supports memory encryption then /dev/sev devices are created by
+ CCP driver.
+
+ The ``policy`` provides the guest policy to be enforced by the
+ SEV firmware and restrict what configuration and operational
+ commands can be performed on this guest by the hypervisor. The
+ policy should be provided by the guest owner and is bound to the
+ guest and cannot be changed throughout the lifetime of the
+ guest. The default is 0.
-The @option{size} option provides the size of the memory region, and accepts
-common suffixes, eg @option{500M}.
+ If guest ``policy`` allows sharing the key with another SEV
+ guest then ``handle`` can be use to provide handle of the guest
+ from which to share the key.
-The @option{mem-path} provides the path to either a shared memory or huge page
-filesystem mount.
+ The ``dh-cert-file`` and ``session-file`` provides the guest
+ owner's Public Diffie-Hillman key defined in SEV spec. The PDH
+ and session parameters are used for establishing a cryptographic
+ session with the guest owner to negotiate keys used for
+ attestation. The file must be encoded in base64.
-The @option{share} boolean option determines whether the memory
-region is marked as private to QEMU, or shared. The latter allows
-a co-operating external process to access the QEMU memory region.
+ e.g to launch a SEV guest
-The @option{share} is also required for pvrdma devices due to
-limitations in the RDMA API provided by Linux.
+ .. parsed-literal::
-Setting share=on might affect the ability to configure NUMA
-bindings for the memory backend under some circumstances, see
-Documentation/vm/numa_memory_policy.txt on the Linux kernel
-source tree for additional details.
+ # |qemu_system_x86| \
+ ......
+ -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
+ -machine ...,memory-encryption=sev0
+ .....
-Setting the @option{discard-data} boolean option to @var{on}
-indicates that file contents can be destroyed when QEMU exits,
-to avoid unnecessarily flushing data to the backing file. Note
-that @option{discard-data} is only an optimization, and QEMU
-might not discard file contents if it aborts unexpectedly or is
-terminated using SIGKILL.
+ ``-object authz-simple,id=id,identity=string``
+ Create an authorization object that will control access to
+ network services.
-The @option{merge} boolean option enables memory merge, also known as
-MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for
-memory deduplication.
+ The ``identity`` parameter is identifies the user and its format
+ depends on the network service that authorization object is
+ associated with. For authorizing based on TLS x509 certificates,
+ the identity must be the x509 distinguished name. Note that care
+ must be taken to escape any commas in the distinguished name.
-Setting the @option{dump} boolean option to @var{off} excludes the memory from
-core dumps. This feature is also known as MADV_DONTDUMP.
+ An example authorization object to validate a x509 distinguished
+ name would look like:
-The @option{prealloc} boolean option enables memory preallocation.
+ .. parsed-literal::
-The @option{host-nodes} option binds the memory range to a list of NUMA host
-nodes.
+ # |qemu_system| \
+ ...
+ -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
+ ...
-The @option{policy} option sets the NUMA policy to one of the following values:
+ Note the use of quotes due to the x509 distinguished name
+ containing whitespace, and escaping of ','.
-@table @option
-@item @var{default}
-default host policy
-
-@item @var{preferred}
-prefer the given host node list for allocation
-
-@item @var{bind}
-restrict memory allocation to the given host node list
+ ``-object authz-listfile,id=id,filename=path,refresh=yes|no``
+ Create an authorization object that will control access to
+ network services.
-@item @var{interleave}
-interleave memory allocations across the given host node list
-@end table
-
-The @option{align} option specifies the base address alignment when
-QEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg
-@option{2M}. Some backend store specified by @option{mem-path}
-requires an alignment different than the default one used by QEMU, eg
-the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In
-such cases, users can specify the required alignment via this option.
-
-The @option{pmem} option specifies whether the backing file specified
-by @option{mem-path} is in host persistent memory that can be accessed
-using the SNIA NVM programming model (e.g. Intel NVDIMM).
-If @option{pmem} is set to 'on', QEMU will take necessary operations to
-guarantee the persistence of its own writes to @option{mem-path}
-(e.g. in vNVDIMM label emulation and live migration).
-Also, we will map the backend-file with MAP_SYNC flag, which ensures the
-file metadata is in sync for @option{mem-path} in case of host crash
-or a power failure. MAP_SYNC requires support from both the host kernel
-(since Linux kernel 4.15) and the filesystem of @option{mem-path} mounted
-with DAX option.
-
-@item -object memory-backend-ram,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{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 @option{-m} option that is
-traditionally used to define guest RAM. Please refer to
-@option{memory-backend-file} for a description of the options.
-
-@item -object memory-backend-memfd,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},seal=@var{on|off},hugetlb=@var{on|off},hugetlbsize=@var{size}
-
-Creates an anonymous memory file backend object, which allows QEMU to
-share the memory with an external process (e.g. when using
-vhost-user). The memory is allocated with memfd and optional
-sealing. (Linux only)
-
-The @option{seal} option creates a sealed-file, that will block
-further resizing the memory ('on' by default).
-
-The @option{hugetlb} option specify the file to be created resides in
-the hugetlbfs filesystem (since Linux 4.14). Used in conjunction with
-the @option{hugetlb} option, the @option{hugetlbsize} option specify
-the hugetlb page size on systems that support multiple hugetlb page
-sizes (it must be a power of 2 value supported by the system).
-
-In some versions of Linux, the @option{hugetlb} option is incompatible
-with the @option{seal} option (requires at least Linux 4.16).
-
-Please refer to @option{memory-backend-file} for a description of the
-other options.
-
-The @option{share} boolean option is @var{on} by default with memfd.
-
-@item -object rng-builtin,id=@var{id}
-
-Creates a random number generator backend which obtains entropy from
-QEMU builtin functions. The @option{id} parameter is a unique ID that
-will be used to reference this entropy backend from the @option{virtio-rng}
-device. By default, the @option{virtio-rng} device uses this RNG backend.
-
-@item -object rng-random,id=@var{id},filename=@var{/dev/random}
-
-Creates a random number generator backend which obtains entropy from
-a device on the host. The @option{id} parameter is a unique ID that
-will be used to reference this entropy backend from the @option{virtio-rng}
-device. The @option{filename} parameter specifies which file to obtain
-entropy from and if omitted defaults to @option{/dev/urandom}.
-
-@item -object rng-egd,id=@var{id},chardev=@var{chardevid}
-
-Creates a random number generator backend which obtains entropy from
-an external daemon running on the host. The @option{id} parameter is
-a unique ID that will be used to reference this entropy backend from
-the @option{virtio-rng} device. The @option{chardev} parameter is
-the unique ID of a character device backend that provides the connection
-to the RNG daemon.
-
-@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off}
-
-Creates a TLS anonymous credentials object, which can be used to provide
-TLS support on network backends. The @option{id} parameter is a unique
-ID which network backends will use to access the credentials. The
-@option{endpoint} is either @option{server} or @option{client} depending
-on whether the QEMU network backend that uses the credentials will be
-acting as a client or as a server. If @option{verify-peer} is enabled
-(the default) then once the handshake is completed, the peer credentials
-will be verified, though this is a no-op for anonymous credentials.
-
-The @var{dir} parameter tells QEMU where to find the credential
-files. For server endpoints, this directory may contain a file
-@var{dh-params.pem} providing diffie-hellman parameters to use
-for the TLS server. If the file is missing, QEMU will generate
-a set of DH parameters at startup. This is a computationally
-expensive operation that consumes random pool entropy, so it is
-recommended that a persistent set of parameters be generated
-upfront and saved.
-
-@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}]
-
-Creates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide
-TLS support on network backends. The @option{id} parameter is a unique
-ID which network backends will use to access the credentials. The
-@option{endpoint} is either @option{server} or @option{client} depending
-on whether the QEMU network backend that uses the credentials will be
-acting as a client or as a server. For clients only, @option{username}
-is the username which will be sent to the server. If omitted
-it defaults to ``qemu''.
-
-The @var{dir} parameter tells QEMU where to find the keys file.
-It is called ``@var{dir}/keys.psk'' and contains ``username:key''
-pairs. This file can most easily be created using the GnuTLS
-@code{psktool} program.
-
-For server endpoints, @var{dir} may also contain a file
-@var{dh-params.pem} providing diffie-hellman parameters to use
-for the TLS server. If the file is missing, QEMU will generate
-a set of DH parameters at startup. This is a computationally
-expensive operation that consumes random pool entropy, so it is
-recommended that a persistent set of parameters be generated
-up front and saved.
-
-@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},priority=@var{priority},verify-peer=@var{on|off},passwordid=@var{id}
-
-Creates a TLS anonymous credentials object, which can be used to provide
-TLS support on network backends. The @option{id} parameter is a unique
-ID which network backends will use to access the credentials. The
-@option{endpoint} is either @option{server} or @option{client} depending
-on whether the QEMU network backend that uses the credentials will be
-acting as a client or as a server. If @option{verify-peer} is enabled
-(the default) then once the handshake is completed, the peer credentials
-will be verified. With x509 certificates, this implies that the clients
-must be provided with valid client certificates too.
-
-The @var{dir} parameter tells QEMU where to find the credential
-files. For server endpoints, this directory may contain a file
-@var{dh-params.pem} providing diffie-hellman parameters to use
-for the TLS server. If the file is missing, QEMU will generate
-a set of DH parameters at startup. This is a computationally
-expensive operation that consumes random pool entropy, so it is
-recommended that a persistent set of parameters be generated
-upfront and saved.
-
-For x509 certificate credentials the directory will contain further files
-providing the x509 certificates. The certificates must be stored
-in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional),
-@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers),
-@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients).
-
-For the @var{server-key.pem} and @var{client-key.pem} files which
-contain sensitive private keys, it is possible to use an encrypted
-version by providing the @var{passwordid} parameter. This provides
-the ID of a previously created @code{secret} object containing the
-password for decryption.
-
-The @var{priority} parameter allows to override the global default
-priority used by gnutls. This can be useful if the system administrator
-needs to use a weaker set of crypto priorities for QEMU without
-potentially forcing the weakness onto all applications. Or conversely
-if one wants wants a stronger default for QEMU than for all other
-applications, they can do this through this parameter. Its format is
-a gnutls priority string as described at
-@url{https://gnutls.org/manual/html_node/Priority-Strings.html}.
-
-@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}]
-
-Interval @var{t} can't be 0, this filter batches the packet delivery: all
-packets arriving in a given interval on netdev @var{netdevid} are delayed
-until the end of the interval. Interval is in microseconds.
-@option{status} is optional that indicate whether the netfilter is
-on (enabled) or off (disabled), the default status for netfilter will be 'on'.
-
-queue @var{all|rx|tx} is an option that can be applied to any netfilter.
-
-@option{all}: the filter is attached both to the receive and the transmit
- queue of the netdev (default).
-
-@option{rx}: the filter is attached to the receive queue of the netdev,
- where it will receive packets sent to the netdev.
-
-@option{tx}: the filter is attached to the transmit queue of the netdev,
- where it will receive packets sent by the netdev.
-
-@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support]
-
-filter-mirror on netdev @var{netdevid},mirror net packet to chardev@var{chardevid}, if it has the vnet_hdr_support flag, filter-mirror will mirror packet with vnet_hdr_len.
-
-@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support]
-
-filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev
-@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag,
-filter-redirector will redirect packet with vnet_hdr_len.
-Create a filter-redirector we need to differ outdev id from indev id, id can not
-be the same. we can just use indev or outdev, but at least one of indev or outdev
-need to be specified.
-
-@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support]
-
-Filter-rewriter is a part of COLO project.It will rewrite tcp packet to
-secondary from primary to keep secondary tcp connection,and rewrite
-tcp packet to primary from secondary make tcp packet can be handled by
-client.if it has the vnet_hdr_support flag, we can parse packet with vnet header.
-
-usage:
-colo secondary:
--object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
--object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
--object filter-rewriter,id=rew0,netdev=hn0,queue=all
-
-@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}]
-
-Dump the network traffic on netdev @var{dev} to the file specified by
-@var{filename}. At most @var{len} bytes (64k by default) per packet are stored.
-The file format is libpcap, so it can be analyzed with tools such as tcpdump
-or Wireshark.
-
-@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid},iothread=@var{id}[,vnet_hdr_support][,notify_dev=@var{id}]
-
-Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with
-secondary packet. If the packets are same, we will output primary
-packet to outdev@var{chardevid}, else we will notify colo-frame
-do checkpoint and send primary packet to outdev@var{chardevid}.
-In order to improve efficiency, we need to put the task of comparison
-in another thread. If it has the vnet_hdr_support flag, colo compare
-will send/recv packet with vnet_hdr_len.
-If you want to use Xen COLO, will need the notify_dev to notify Xen
-colo-frame to do checkpoint.
-
-we must use it with the help of filter-mirror and filter-redirector.
-
-@example
-
-KVM COLO
-
-primary:
--netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
--device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
--chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
--chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
--chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
--chardev socket,id=compare0-0,host=3.3.3.3,port=9001
--chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
--chardev socket,id=compare_out0,host=3.3.3.3,port=9005
--object iothread,id=iothread1
--object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
--object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
--object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
--object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1
-
-secondary:
--netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
--device e1000,netdev=hn0,mac=52:a4:00:12:78:66
--chardev socket,id=red0,host=3.3.3.3,port=9003
--chardev socket,id=red1,host=3.3.3.3,port=9004
--object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
--object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
-
-
-Xen COLO
-
-primary:
--netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
--device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
--chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
--chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
--chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
--chardev socket,id=compare0-0,host=3.3.3.3,port=9001
--chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
--chardev socket,id=compare_out0,host=3.3.3.3,port=9005
--chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait
--object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
--object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
--object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
--object iothread,id=iothread1
--object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1
-
-secondary:
--netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
--device e1000,netdev=hn0,mac=52:a4:00:12:78:66
--chardev socket,id=red0,host=3.3.3.3,port=9003
--chardev socket,id=red1,host=3.3.3.3,port=9004
--object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
--object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
-
-@end example
-
-If you want to know the detail of above command line, you can read
-the colo-compare git log.
-
-@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}]
-
-Creates a cryptodev backend which executes crypto opreation from
-the QEMU cipher APIS. The @var{id} parameter is
-a unique ID that will be used to reference this cryptodev backend from
-the @option{virtio-crypto} device. The @var{queues} parameter is optional,
-which specify the queue number of cryptodev backend, the default of
-@var{queues} is 1.
-
-@example
-
- # @value{qemu_system} \
- [...] \
- -object cryptodev-backend-builtin,id=cryptodev0 \
- -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
- [...]
-@end example
-
-@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}]
-
-Creates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}.
-The @var{id} parameter is a unique ID that will be used to reference this
-cryptodev backend from the @option{virtio-crypto} device.
-The chardev should be a unix domain socket backed one. The vhost-user uses
-a specifically defined protocol to pass vhost ioctl replacement messages
-to an application on the other end of the socket.
-The @var{queues} parameter is optional, which specify the queue number
-of cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1.
-
-@example
-
- # @value{qemu_system} \
- [...] \
- -chardev socket,id=chardev0,path=/path/to/socket \
- -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
- -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
- [...]
-@end example
-
-@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
-@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}]
-
-Defines a secret to store a password, encryption key, or some other sensitive
-data. The sensitive data can either be passed directly via the @var{data}
-parameter, or indirectly via the @var{file} parameter. Using the @var{data}
-parameter is insecure unless the sensitive data is encrypted.
-
-The sensitive data can be provided in raw format (the default), or base64.
-When encoded as JSON, the raw format only supports valid UTF-8 characters,
-so base64 is recommended for sending binary data. QEMU will convert from
-which ever format is provided to the format it needs internally. eg, an
-RBD password can be provided in raw format, even though it will be base64
-encoded when passed onto the RBD sever.
-
-For added protection, it is possible to encrypt the data associated with
-a secret using the AES-256-CBC cipher. Use of encryption is indicated
-by providing the @var{keyid} and @var{iv} parameters. The @var{keyid}
-parameter provides the ID of a previously defined secret that contains
-the AES-256 decryption key. This key should be 32-bytes long and be
-base64 encoded. The @var{iv} parameter provides the random initialization
-vector used for encryption of this particular secret and should be a
-base64 encrypted string of the 16-byte IV.
-
-The simplest (insecure) usage is to provide the secret inline
-
-@example
-
- # @value{qemu_system} -object secret,id=sec0,data=letmein,format=raw
-
-@end example
-
-The simplest secure usage is to provide the secret via a file
-
- # printf "letmein" > mypasswd.txt
- # @value{qemu_system} -object secret,id=sec0,file=mypasswd.txt,format=raw
-
-For greater security, AES-256-CBC should be used. To illustrate usage,
-consider the openssl command line tool which can encrypt the data. Note
-that when encrypting, the plaintext must be padded to the cipher block
-size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm.
-
-First a master key needs to be created in base64 encoding:
-
-@example
- # openssl rand -base64 32 > key.b64
- # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
-@end example
-
-Each secret to be encrypted needs to have a random initialization vector
-generated. These do not need to be kept secret
-
-@example
- # openssl rand -base64 16 > iv.b64
- # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
-@end example
-
-The secret to be defined can now be encrypted, in this case we're
-telling openssl to base64 encode the result, but it could be left
-as raw bytes if desired.
-
-@example
- # SECRET=$(printf "letmein" |
- openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
-@end example
-
-When launching QEMU, create a master secret pointing to @code{key.b64}
-and specify that to be used to decrypt the user password. Pass the
-contents of @code{iv.b64} to the second secret
-
-@example
- # @value{qemu_system} \
- -object secret,id=secmaster0,format=base64,file=key.b64 \
- -object secret,id=sec0,keyid=secmaster0,format=base64,\
- data=$SECRET,iv=$(<iv.b64)
-@end example
-
-@item -object sev-guest,id=@var{id},cbitpos=@var{cbitpos},reduced-phys-bits=@var{val},[sev-device=@var{string},policy=@var{policy},handle=@var{handle},dh-cert-file=@var{file},session-file=@var{file}]
-
-Create a Secure Encrypted Virtualization (SEV) guest object, which can be used
-to provide the guest memory encryption support on AMD processors.
-
-When memory encryption is enabled, one of the physical address bit (aka the
-C-bit) is utilized to mark if a memory page is protected. The @option{cbitpos}
-is used to provide the C-bit position. The C-bit position is Host family dependent
-hence user must provide this value. On EPYC, the value should be 47.
-
-When memory encryption is enabled, we loose certain bits in physical address space.
-The @option{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.
-
-The @option{sev-device} provides the device file to use for communicating with
-the SEV firmware running inside AMD Secure Processor. The default device is
-'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are
-created by CCP driver.
-
-The @option{policy} provides the guest policy to be enforced by the SEV firmware
-and restrict what configuration and operational commands can be performed on this
-guest by the hypervisor. The policy should be provided by the guest owner and is
-bound to the guest and cannot be changed throughout the lifetime of the guest.
-The default is 0.
-
-If guest @option{policy} allows sharing the key with another SEV guest then
-@option{handle} can be use to provide handle of the guest from which to share
-the key.
-
-The @option{dh-cert-file} and @option{session-file} provides the guest owner's
-Public Diffie-Hillman key defined in SEV spec. The PDH and session parameters
-are used for establishing a cryptographic session with the guest owner to
-negotiate keys used for attestation. The file must be encoded in base64.
-
-e.g to launch a SEV guest
-@example
- # @value{qemu_system_x86} \
- ......
- -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
- -machine ...,memory-encryption=sev0
- .....
-
-@end example
+ The ``filename`` parameter is the fully qualified path to a file
+ containing the access control list rules in JSON format.
+ An example set of rules that match against SASL usernames might
+ look like:
-@item -object authz-simple,id=@var{id},identity=@var{string}
+ ::
+
+ {
+ "rules": [
+ { "match": "fred", "policy": "allow", "format": "exact" },
+ { "match": "bob", "policy": "allow", "format": "exact" },
+ { "match": "danb", "policy": "deny", "format": "glob" },
+ { "match": "dan*", "policy": "allow", "format": "exact" },
+ ],
+ "policy": "deny"
+ }
+
+ When checking access the object will iterate over all the rules
+ and the first rule to match will have its ``policy`` value
+ returned as the result. If no rules match, then the default
+ ``policy`` value is returned.
-Create an authorization object that will control access to network services.
+ The rules can either be an exact string match, or they can use
+ the simple UNIX glob pattern matching to allow wildcards to be
+ used.
-The @option{identity} parameter is identifies the user and its format
-depends on the network service that authorization object is associated
-with. For authorizing based on TLS x509 certificates, the identity must
-be the x509 distinguished name. Note that care must be taken to escape
-any commas in the distinguished name.
-
-An example authorization object to validate a x509 distinguished name
-would look like:
-@example
- # @value{qemu_system} \
- ...
- -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
- ...
-@end example
-
-Note the use of quotes due to the x509 distinguished name containing
-whitespace, and escaping of ','.
-
-@item -object authz-listfile,id=@var{id},filename=@var{path},refresh=@var{yes|no}
-
-Create an authorization object that will control access to network services.
-
-The @option{filename} parameter is the fully qualified path to a file
-containing the access control list rules in JSON format.
-
-An example set of rules that match against SASL usernames might look
-like:
-
-@example
- @{
- "rules": [
- @{ "match": "fred", "policy": "allow", "format": "exact" @},
- @{ "match": "bob", "policy": "allow", "format": "exact" @},
- @{ "match": "danb", "policy": "deny", "format": "glob" @},
- @{ "match": "dan*", "policy": "allow", "format": "exact" @},
- ],
- "policy": "deny"
- @}
-@end example
-
-When checking access the object will iterate over all the rules and
-the first rule to match will have its @option{policy} value returned
-as the result. If no rules match, then the default @option{policy}
-value is returned.
+ If ``refresh`` is set to true the file will be monitored and
+ automatically reloaded whenever its content changes.
-The rules can either be an exact string match, or they can use the
-simple UNIX glob pattern matching to allow wildcards to be used.
+ As with the ``authz-simple`` object, the format of the identity
+ strings being matched depends on the network service, but is
+ usually a TLS x509 distinguished name, or a SASL username.
-If @option{refresh} is set to true the file will be monitored
-and automatically reloaded whenever its content changes.
+ An example authorization object to validate a SASL username
+ would look like:
-As with the @code{authz-simple} object, the format of the identity
-strings being matched depends on the network service, but is usually
-a TLS x509 distinguished name, or a SASL username.
+ .. parsed-literal::
-An example authorization object to validate a SASL username
-would look like:
-@example
- # @value{qemu_system} \
- ...
- -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes
- ...
-@end example
+ # |qemu_system| \
+ ...
+ -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes
+ ...
-@item -object authz-pam,id=@var{id},service=@var{string}
+ ``-object authz-pam,id=id,service=string``
+ Create an authorization object that will control access to
+ network services.
-Create an authorization object that will control access to network services.
+ The ``service`` parameter provides the name of a PAM service to
+ use for authorization. It requires that a file
+ ``/etc/pam.d/service`` exist to provide the configuration for
+ the ``account`` subsystem.
-The @option{service} parameter provides the name of a PAM service to use
-for authorization. It requires that a file @code{/etc/pam.d/@var{service}}
-exist to provide the configuration for the @code{account} subsystem.
+ An example authorization object to validate a TLS x509
+ distinguished name would look like:
-An example authorization object to validate a TLS x509 distinguished
-name would look like:
+ .. parsed-literal::
-@example
- # @value{qemu_system} \
- ...
- -object authz-pam,id=auth0,service=qemu-vnc
- ...
-@end example
+ # |qemu_system| \
+ ...
+ -object authz-pam,id=auth0,service=qemu-vnc
+ ...
-There would then be a corresponding config file for PAM at
-@code{/etc/pam.d/qemu-vnc} that contains:
+ There would then be a corresponding config file for PAM at
+ ``/etc/pam.d/qemu-vnc`` that contains:
-@example
-account requisite pam_listfile.so item=user sense=allow \
- file=/etc/qemu/vnc.allow
-@end example
+ ::
-Finally the @code{/etc/qemu/vnc.allow} file would contain
-the list of x509 distingished names that are permitted
-access
+ account requisite pam_listfile.so item=user sense=allow \
+ file=/etc/qemu/vnc.allow
-@example
-CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
-@end example
+ Finally the ``/etc/qemu/vnc.allow`` file would contain the list
+ of x509 distingished names that are permitted access
-@item -object iothread,id=@var{id},poll-max-ns=@var{poll-max-ns},poll-grow=@var{poll-grow},poll-shrink=@var{poll-shrink}
+ ::
-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. This can become a scalability bottleneck.
-IOThreads allow device emulation and I/O to run on other host CPUs.
+ CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
-The @option{id} parameter is a unique ID that will be used to reference this
-IOThread from @option{-device ...,iothread=@var{id}}. Multiple devices can be
-assigned to an IOThread. Note that not all devices support an
-@option{iothread} parameter.
+ ``-object iothread,id=id,poll-max-ns=poll-max-ns,poll-grow=poll-grow,poll-shrink=poll-shrink``
+ 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.
+ This can become a scalability bottleneck. IOThreads allow device
+ emulation and I/O to run on other host CPUs.
-The @code{query-iothreads} QMP command lists IOThreads and reports their thread
-IDs so that the user can configure host CPU pinning/affinity.
+ The ``id`` parameter is a unique ID that will be used to
+ reference this IOThread from ``-device ...,iothread=id``.
+ Multiple devices can be assigned to an IOThread. Note that not
+ all devices support an ``iothread`` parameter.
-IOThreads use an adaptive polling algorithm to reduce event loop latency.
-Instead of entering a blocking system call to monitor file descriptors and then
-pay the cost of being woken up when an event occurs, the polling algorithm
-spins waiting for events for a short time. The algorithm's default parameters
-are suitable for many cases but can be adjusted based on knowledge of the
-workload and/or host device latency.
+ The ``query-iothreads`` QMP command lists IOThreads and reports
+ their thread IDs so that the user can configure host CPU
+ pinning/affinity.
-The @option{poll-max-ns} parameter is the maximum number of nanoseconds to busy
-wait for events. Polling can be disabled by setting this value to 0.
+ IOThreads use an adaptive polling algorithm to reduce event loop
+ latency. Instead of entering a blocking system call to monitor
+ file descriptors and then pay the cost of being woken up when an
+ event occurs, the polling algorithm spins waiting for events for
+ a short time. The algorithm's default parameters are suitable
+ for many cases but can be adjusted based on knowledge of the
+ workload and/or host device latency.
-The @option{poll-grow} parameter is the multiplier used to increase the polling
-time when the algorithm detects it is missing events due to not polling long
-enough.
+ The ``poll-max-ns`` parameter is the maximum number of
+ nanoseconds to busy wait for events. Polling can be disabled by
+ setting this value to 0.
-The @option{poll-shrink} parameter is the divisor used to decrease the polling
-time when the algorithm detects it is spending too long polling without
-encountering events.
+ The ``poll-grow`` parameter is the multiplier used to increase
+ the polling time when the algorithm detects it is missing events
+ due to not polling long enough.
-The polling parameters can be modified at run-time using the @code{qom-set} command (where @code{iothread1} is the IOThread's @code{id}):
+ The ``poll-shrink`` parameter is the divisor used to decrease
+ the polling time when the algorithm detects it is spending too
+ long polling without encountering events.
-@example
-(qemu) qom-set /objects/iothread1 poll-max-ns 100000
-@end example
+ The polling parameters can be modified at run-time using the
+ ``qom-set`` command (where ``iothread1`` is the IOThread's
+ ``id``):
-@end table
+ ::
-ETEXI
+ (qemu) qom-set /objects/iothread1 poll-max-ns 100000
+ERST
HXCOMM This is the last statement. Insert new options before this line!
-STEXI
-@end table
-ETEXI
projects / thirdparty / qemu.git / blobdiff