qemu-options.hx: Fix up the autogenerated rST
[qemu.git] / qemu-options.hx
1 HXCOMM Use DEFHEADING() to define headings in both help text and texi
2 HXCOMM Text between STEXI and ETEXI are copied to texi version and
3 HXCOMM discarded from C version
4 HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
5 HXCOMM construct option structures, enums and help message for specified
6 HXCOMM architectures.
7 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
8
9 DEFHEADING(Standard options:)
10 STEXI
11 @table @option
12 ETEXI
13
14 DEF("help", 0, QEMU_OPTION_h,
15     "-h or -help     display this help and exit\n", QEMU_ARCH_ALL)
16 STEXI
17 @item -h
18 @findex -h
19 Display help and exit
20 ETEXI
21 SRST
22 ``-h``
23     Display help and exit
24 ERST
25
26 DEF("version", 0, QEMU_OPTION_version,
27     "-version        display version information and exit\n", QEMU_ARCH_ALL)
28 STEXI
29 @item -version
30 @findex -version
31 Display version information and exit
32 ETEXI
33 SRST
34 ``-version``
35     Display version information and exit
36 ERST
37
38 DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
39     "-machine [type=]name[,prop[=value][,...]]\n"
40     "                selects emulated machine ('-machine help' for list)\n"
41     "                property accel=accel1[:accel2[:...]] selects accelerator\n"
42     "                supported accelerators are kvm, xen, hax, hvf, whpx or tcg (default: tcg)\n"
43     "                vmport=on|off|auto controls emulation of vmport (default: auto)\n"
44     "                dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
45     "                mem-merge=on|off controls memory merge support (default: on)\n"
46     "                aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
47     "                dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
48     "                suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
49     "                nvdimm=on|off controls NVDIMM support (default=off)\n"
50     "                enforce-config-section=on|off enforce configuration section migration (default=off)\n"
51     "                memory-encryption=@var{} memory encryption object to use (default=none)\n"
52     "                hmat=on|off controls ACPI HMAT support (default=off)\n",
53     QEMU_ARCH_ALL)
54 STEXI
55 @item -machine [type=]@var{name}[,prop=@var{value}[,...]]
56 @findex -machine
57 Select the emulated machine by @var{name}. Use @code{-machine help} to list
58 available machines.
59
60 For architectures which aim to support live migration compatibility
61 across releases, each release will introduce a new versioned machine
62 type. For example, the 2.8.0 release introduced machine types
63 ``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures.
64
65 To allow live migration of guests from QEMU version 2.8.0, to QEMU
66 version 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8''
67 and ``pc-q35-2.8'' machines too. To allow users live migrating VMs
68 to skip multiple intermediate releases when upgrading, new releases
69 of QEMU will support machine types from many previous versions.
70
71 Supported machine properties are:
72 @table @option
73 @item accel=@var{accels1}[:@var{accels2}[:...]]
74 This is used to enable an accelerator. Depending on the target architecture,
75 kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
76 more than one accelerator specified, the next one is used if the previous one
77 fails to initialize.
78 @item vmport=on|off|auto
79 Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the
80 value based on accel. For accel=xen the default is off otherwise the default
81 is on.
82 @item dump-guest-core=on|off
83 Include guest memory in a core dump. The default is on.
84 @item mem-merge=on|off
85 Enables or disables memory merge support. This feature, when supported by
86 the host, de-duplicates identical memory pages among VMs instances
87 (enabled by default).
88 @item aes-key-wrap=on|off
89 Enables or disables AES key wrapping support on s390-ccw hosts. This feature
90 controls whether AES wrapping keys will be created to allow
91 execution of AES cryptographic functions.  The default is on.
92 @item dea-key-wrap=on|off
93 Enables or disables DEA key wrapping support on s390-ccw hosts. This feature
94 controls whether DEA wrapping keys will be created to allow
95 execution of DEA cryptographic functions.  The default is on.
96 @item nvdimm=on|off
97 Enables or disables NVDIMM support. The default is off.
98 @item enforce-config-section=on|off
99 If @option{enforce-config-section} is set to @var{on}, force migration
100 code to send configuration section even if the machine-type sets the
101 @option{migration.send-configuration} property to @var{off}.
102 NOTE: this parameter is deprecated. Please use @option{-global}
103 @option{migration.send-configuration}=@var{on|off} instead.
104 @item memory-encryption=@var{}
105 Memory encryption object to use. The default is none.
106 @item hmat=on|off
107 Enables or disables ACPI Heterogeneous Memory Attribute Table (HMAT) support.
108 The default is off.
109 @end table
110 ETEXI
111 SRST
112 ``-machine [type=]name[,prop=value[,...]]``
113     Select the emulated machine by name. Use ``-machine help`` to list
114     available machines.
115
116     For architectures which aim to support live migration compatibility
117     across releases, each release will introduce a new versioned machine
118     type. For example, the 2.8.0 release introduced machine types
119     "pc-i440fx-2.8" and "pc-q35-2.8" for the x86\_64/i686 architectures.
120
121     To allow live migration of guests from QEMU version 2.8.0, to QEMU
122     version 2.9.0, the 2.9.0 version must support the "pc-i440fx-2.8"
123     and "pc-q35-2.8" machines too. To allow users live migrating VMs to
124     skip multiple intermediate releases when upgrading, new releases of
125     QEMU will support machine types from many previous versions.
126
127     Supported machine properties are:
128
129     ``accel=accels1[:accels2[:...]]``
130         This is used to enable an accelerator. Depending on the target
131         architecture, kvm, xen, hax, hvf, whpx or tcg can be available.
132         By default, tcg is used. If there is more than one accelerator
133         specified, the next one is used if the previous one fails to
134         initialize.
135
136     ``vmport=on|off|auto``
137         Enables emulation of VMWare IO port, for vmmouse etc. auto says
138         to select the value based on accel. For accel=xen the default is
139         off otherwise the default is on.
140
141     ``dump-guest-core=on|off``
142         Include guest memory in a core dump. The default is on.
143
144     ``mem-merge=on|off``
145         Enables or disables memory merge support. This feature, when
146         supported by the host, de-duplicates identical memory pages
147         among VMs instances (enabled by default).
148
149     ``aes-key-wrap=on|off``
150         Enables or disables AES key wrapping support on s390-ccw hosts.
151         This feature controls whether AES wrapping keys will be created
152         to allow execution of AES cryptographic functions. The default
153         is on.
154
155     ``dea-key-wrap=on|off``
156         Enables or disables DEA key wrapping support on s390-ccw hosts.
157         This feature controls whether DEA wrapping keys will be created
158         to allow execution of DEA cryptographic functions. The default
159         is on.
160
161     ``nvdimm=on|off``
162         Enables or disables NVDIMM support. The default is off.
163
164     ``enforce-config-section=on|off``
165         If ``enforce-config-section`` is set to on, force migration code
166         to send configuration section even if the machine-type sets the
167         ``migration.send-configuration`` property to off. NOTE: this
168         parameter is deprecated. Please use ``-global``
169         ``migration.send-configuration``\ =on\|off instead.
170
171     ``memory-encryption=``
172         Memory encryption object to use. The default is none.
173
174     ``hmat=on|off``
175         Enables or disables ACPI Heterogeneous Memory Attribute Table
176         (HMAT) support. The default is off.
177 ERST
178
179 HXCOMM Deprecated by -machine
180 DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
181
182 DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
183     "-cpu cpu        select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
184 STEXI
185 @item -cpu @var{model}
186 @findex -cpu
187 Select CPU model (@code{-cpu help} for list and additional feature selection)
188 ETEXI
189 SRST
190 ``-cpu model``
191     Select CPU model (``-cpu help`` for list and additional feature
192     selection)
193 ERST
194
195 DEF("accel", HAS_ARG, QEMU_OPTION_accel,
196     "-accel [accel=]accelerator[,prop[=value][,...]]\n"
197     "                select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n"
198     "                igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)\n"
199     "                kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)\n"
200     "                kvm-shadow-mem=size of KVM shadow MMU in bytes\n"
201     "                tb-size=n (TCG translation block cache size)\n"
202     "                thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
203 STEXI
204 @item -accel @var{name}[,prop=@var{value}[,...]]
205 @findex -accel
206 This is used to enable an accelerator. Depending on the target architecture,
207 kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is
208 more than one accelerator specified, the next one is used if the previous one
209 fails to initialize.
210 @table @option
211 @item igd-passthru=on|off
212 When Xen is in use, this option controls whether Intel integrated graphics
213 devices can be passed through to the guest (default=off)
214 @item kernel-irqchip=on|off|split
215 Controls KVM in-kernel irqchip support.  The default is full acceleration of the
216 interrupt controllers.  On x86, split irqchip reduces the kernel attack
217 surface, at a performance cost for non-MSI interrupts.  Disabling the in-kernel
218 irqchip completely is not recommended except for debugging purposes.
219 @item kvm-shadow-mem=size
220 Defines the size of the KVM shadow MMU.
221 @item tb-size=@var{n}
222 Controls the size (in MiB) of the TCG translation block cache.
223 @item thread=single|multi
224 Controls number of TCG threads. When the TCG is multi-threaded there will be one
225 thread per vCPU therefor taking advantage of additional host cores. The default
226 is to enable multi-threading where both the back-end and front-ends support it and
227 no incompatible TCG features have been enabled (e.g. icount/replay).
228 @end table
229 ETEXI
230 SRST
231 ``-accel name[,prop=value[,...]]``
232     This is used to enable an accelerator. Depending on the target
233     architecture, kvm, xen, hax, hvf, whpx or tcg can be available. By
234     default, tcg is used. If there is more than one accelerator
235     specified, the next one is used if the previous one fails to
236     initialize.
237
238     ``igd-passthru=on|off``
239         When Xen is in use, this option controls whether Intel
240         integrated graphics devices can be passed through to the guest
241         (default=off)
242
243     ``kernel-irqchip=on|off|split``
244         Controls KVM in-kernel irqchip support. The default is full
245         acceleration of the interrupt controllers. On x86, split irqchip
246         reduces the kernel attack surface, at a performance cost for
247         non-MSI interrupts. Disabling the in-kernel irqchip completely
248         is not recommended except for debugging purposes.
249
250     ``kvm-shadow-mem=size``
251         Defines the size of the KVM shadow MMU.
252
253     ``tb-size=n``
254         Controls the size (in MiB) of the TCG translation block cache.
255
256     ``thread=single|multi``
257         Controls number of TCG threads. When the TCG is multi-threaded
258         there will be one thread per vCPU therefor taking advantage of
259         additional host cores. The default is to enable multi-threading
260         where both the back-end and front-ends support it and no
261         incompatible TCG features have been enabled (e.g.
262         icount/replay).
263 ERST
264
265 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
266     "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
267     "                set the number of CPUs to 'n' [default=1]\n"
268     "                maxcpus= maximum number of total cpus, including\n"
269     "                offline CPUs for hotplug, etc\n"
270     "                cores= number of CPU cores on one socket (for PC, it's on one die)\n"
271     "                threads= number of threads on one CPU core\n"
272     "                dies= number of CPU dies on one socket (for PC only)\n"
273     "                sockets= number of discrete sockets in the system\n",
274         QEMU_ARCH_ALL)
275 STEXI
276 @item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,dies=dies][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
277 @findex -smp
278 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
279 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
280 to 4.
281 For the PC target, the number of @var{cores} per die, the number of @var{threads}
282 per cores, the number of @var{dies} per packages and the total number of
283 @var{sockets} can be specified. Missing values will be computed.
284 If any on the three values is given, the total number of CPUs @var{n} can be omitted.
285 @var{maxcpus} specifies the maximum number of hotpluggable CPUs.
286 ETEXI
287 SRST
288 ``-smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]``
289     Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
290     are supported. On Sparc32 target, Linux limits the number of usable
291     CPUs to 4. For the PC target, the number of cores per die, the
292     number of threads per cores, the number of dies per packages and the
293     total number of sockets can be specified. Missing values will be
294     computed. If any on the three values is given, the total number of
295     CPUs n can be omitted. maxcpus specifies the maximum number of
296     hotpluggable CPUs.
297 ERST
298
299 DEF("numa", HAS_ARG, QEMU_OPTION_numa,
300     "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
301     "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
302     "-numa dist,src=source,dst=destination,val=distance\n"
303     "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n"
304     "-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"
305     "-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]\n",
306     QEMU_ARCH_ALL)
307 STEXI
308 @item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}][,initiator=@var{initiator}]
309 @itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}][,initiator=@var{initiator}]
310 @itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance}
311 @itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}]
312 @itemx -numa hmat-lb,initiator=@var{node},target=@var{node},hierarchy=@var{hierarchy},data-type=@var{tpye}[,latency=@var{lat}][,bandwidth=@var{bw}]
313 @itemx -numa hmat-cache,node-id=@var{node},size=@var{size},level=@var{level}[,associativity=@var{str}][,policy=@var{str}][,line=@var{size}]
314 @findex -numa
315 Define a NUMA node and assign RAM and VCPUs to it.
316 Set the NUMA distance from a source node to a destination node.
317 Set the ACPI Heterogeneous Memory Attributes for the given nodes.
318
319 Legacy VCPU assignment uses @samp{cpus} option where
320 @var{firstcpu} and @var{lastcpu} are CPU indexes. Each
321 @samp{cpus} option represent a contiguous range of CPU indexes
322 (or a single VCPU if @var{lastcpu} is omitted). A non-contiguous
323 set of VCPUs can be represented by providing multiple @samp{cpus}
324 options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically
325 split between them.
326
327 For example, the following option assigns VCPUs 0, 1, 2 and 5 to
328 a NUMA node:
329 @example
330 -numa node,cpus=0-2,cpus=5
331 @end example
332
333 @samp{cpu} option is a new alternative to @samp{cpus} option
334 which uses @samp{socket-id|core-id|thread-id} properties to assign
335 CPU objects to a @var{node} using topology layout properties of CPU.
336 The set of properties is machine specific, and depends on used
337 machine type/@samp{smp} options. It could be queried with
338 @samp{hotpluggable-cpus} monitor command.
339 @samp{node-id} property specifies @var{node} to which CPU object
340 will be assigned, it's required for @var{node} to be declared
341 with @samp{node} option before it's used with @samp{cpu} option.
342
343 For example:
344 @example
345 -M pc \
346 -smp 1,sockets=2,maxcpus=2 \
347 -numa node,nodeid=0 -numa node,nodeid=1 \
348 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
349 @end example
350
351 @samp{mem} assigns a given RAM amount to a node. @samp{memdev}
352 assigns RAM from a given memory backend device to a node. If
353 @samp{mem} and @samp{memdev} are omitted in all nodes, RAM is
354 split equally between them.
355
356 @samp{mem} and @samp{memdev} are mutually exclusive. Furthermore,
357 if one node uses @samp{memdev}, all of them have to use it.
358
359 @samp{initiator} is an additional option that points to an @var{initiator}
360 NUMA node that has best performance (the lowest latency or largest bandwidth)
361 to this NUMA @var{node}. Note that this option can be set only when
362 the machine property 'hmat' is set to 'on'.
363
364 Following example creates a machine with 2 NUMA nodes, node 0 has CPU.
365 node 1 has only memory, and its initiator is node 0. Note that because
366 node 0 has CPU, by default the initiator of node 0 is itself and must be
367 itself.
368 @example
369 -machine hmat=on \
370 -m 2G,slots=2,maxmem=4G \
371 -object memory-backend-ram,size=1G,id=m0 \
372 -object memory-backend-ram,size=1G,id=m1 \
373 -numa node,nodeid=0,memdev=m0 \
374 -numa node,nodeid=1,memdev=m1,initiator=0 \
375 -smp 2,sockets=2,maxcpus=2  \
376 -numa cpu,node-id=0,socket-id=0 \
377 -numa cpu,node-id=0,socket-id=1
378 @end example
379
380 @var{source} and @var{destination} are NUMA node IDs.
381 @var{distance} is the NUMA distance from @var{source} to @var{destination}.
382 The distance from a node to itself is always 10. If any pair of nodes is
383 given a distance, then all pairs must be given distances. Although, when
384 distances are only given in one direction for each pair of nodes, then
385 the distances in the opposite directions are assumed to be the same. If,
386 however, an asymmetrical pair of distances is given for even one node
387 pair, then all node pairs must be provided distance values for both
388 directions, even when they are symmetrical. When a node is unreachable
389 from another node, set the pair's distance to 255.
390
391 Note that the -@option{numa} option doesn't allocate any of the
392 specified resources, it just assigns existing resources to NUMA
393 nodes. This means that one still has to use the @option{-m},
394 @option{-smp} options to allocate RAM and VCPUs respectively.
395
396 Use @samp{hmat-lb} to set System Locality Latency and Bandwidth Information
397 between initiator and target NUMA nodes in ACPI Heterogeneous Attribute Memory Table (HMAT).
398 Initiator NUMA node can create memory requests, usually it has one or more processors.
399 Target NUMA node contains addressable memory.
400
401 In @samp{hmat-lb} option, @var{node} are NUMA node IDs. @var{hierarchy} is the memory
402 hierarchy of the target NUMA node: if @var{hierarchy} is 'memory', the structure
403 represents the memory performance; if @var{hierarchy} is 'first-level|second-level|third-level',
404 this structure represents aggregated performance of memory side caches for each domain.
405 @var{type} of 'data-type' is type of data represented by this structure instance:
406 if 'hierarchy' is 'memory', 'data-type' is 'access|read|write' latency or 'access|read|write'
407 bandwidth of the target memory; if 'hierarchy' is 'first-level|second-level|third-level',
408 'data-type' is 'access|read|write' hit latency or 'access|read|write' hit bandwidth of the
409 target memory side cache.
410
411 @var{lat} is latency value in nanoseconds. @var{bw} is bandwidth value,
412 the possible value and units are NUM[M|G|T], mean that the bandwidth value are
413 NUM byte per second (or MB/s, GB/s or TB/s depending on used suffix).
414 Note that if latency or bandwidth value is 0, means the corresponding latency or
415 bandwidth information is not provided.
416
417 In @samp{hmat-cache} option, @var{node-id} is the NUMA-id of the memory belongs.
418 @var{size} is the size of memory side cache in bytes. @var{level} is the cache
419 level described in this structure, note that the cache level 0 should not be used
420 with @samp{hmat-cache} option. @var{associativity} is the cache associativity,
421 the possible value is 'none/direct(direct-mapped)/complex(complex cache indexing)'.
422 @var{policy} is the write policy. @var{line} is the cache Line size in bytes.
423
424 For example, the following options describe 2 NUMA nodes. Node 0 has 2 cpus and
425 a ram, node 1 has only a ram. The processors in node 0 access memory in node
426 0 with access-latency 5 nanoseconds, access-bandwidth is 200 MB/s;
427 The processors in NUMA node 0 access memory in NUMA node 1 with access-latency 10
428 nanoseconds, access-bandwidth is 100 MB/s.
429 And for memory side cache information, NUMA node 0 and 1 both have 1 level memory
430 cache, size is 10KB, policy is write-back, the cache Line size is 8 bytes:
431 @example
432 -machine hmat=on \
433 -m 2G \
434 -object memory-backend-ram,size=1G,id=m0 \
435 -object memory-backend-ram,size=1G,id=m1 \
436 -smp 2 \
437 -numa node,nodeid=0,memdev=m0 \
438 -numa node,nodeid=1,memdev=m1,initiator=0 \
439 -numa cpu,node-id=0,socket-id=0 \
440 -numa cpu,node-id=0,socket-id=1 \
441 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
442 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
443 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
444 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
445 -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
446 -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
447 @end example
448
449 ETEXI
450 SRST
451 ``-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
452   \ 
453 ``-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
454   \
455 ``-numa dist,src=source,dst=destination,val=distance``
456   \ 
457 ``-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]``
458   \ 
459 ``-numa hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=tpye[,latency=lat][,bandwidth=bw]``
460   \ 
461 ``-numa hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]``
462     Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
463     distance from a source node to a destination node. Set the ACPI
464     Heterogeneous Memory Attributes for the given nodes.
465
466     Legacy VCPU assignment uses '\ ``cpus``\ ' option where firstcpu and
467     lastcpu are CPU indexes. Each '\ ``cpus``\ ' option represent a
468     contiguous range of CPU indexes (or a single VCPU if lastcpu is
469     omitted). A non-contiguous set of VCPUs can be represented by
470     providing multiple '\ ``cpus``\ ' options. If '\ ``cpus``\ ' is
471     omitted on all nodes, VCPUs are automatically split between them.
472
473     For example, the following option assigns VCPUs 0, 1, 2 and 5 to a
474     NUMA node:
475
476     ::
477
478         -numa node,cpus=0-2,cpus=5
479
480     '\ ``cpu``\ ' option is a new alternative to '\ ``cpus``\ ' option
481     which uses '\ ``socket-id|core-id|thread-id``\ ' properties to
482     assign CPU objects to a node using topology layout properties of
483     CPU. The set of properties is machine specific, and depends on used
484     machine type/'\ ``smp``\ ' options. It could be queried with
485     '\ ``hotpluggable-cpus``\ ' monitor command. '\ ``node-id``\ '
486     property specifies node to which CPU object will be assigned, it's
487     required for node to be declared with '\ ``node``\ ' option before
488     it's used with '\ ``cpu``\ ' option.
489
490     For example:
491
492     ::
493
494         -M pc \
495         -smp 1,sockets=2,maxcpus=2 \
496         -numa node,nodeid=0 -numa node,nodeid=1 \
497         -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
498
499     '\ ``mem``\ ' assigns a given RAM amount to a node. '\ ``memdev``\ '
500     assigns RAM from a given memory backend device to a node. If
501     '\ ``mem``\ ' and '\ ``memdev``\ ' are omitted in all nodes, RAM is
502     split equally between them.
503
504     '\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive.
505     Furthermore, if one node uses '\ ``memdev``\ ', all of them have to
506     use it.
507
508     '\ ``initiator``\ ' is an additional option that points to an
509     initiator NUMA node that has best performance (the lowest latency or
510     largest bandwidth) to this NUMA node. Note that this option can be
511     set only when the machine property 'hmat' is set to 'on'.
512
513     Following example creates a machine with 2 NUMA nodes, node 0 has
514     CPU. node 1 has only memory, and its initiator is node 0. Note that
515     because node 0 has CPU, by default the initiator of node 0 is itself
516     and must be itself.
517
518     ::
519
520         -machine hmat=on \
521         -m 2G,slots=2,maxmem=4G \
522         -object memory-backend-ram,size=1G,id=m0 \
523         -object memory-backend-ram,size=1G,id=m1 \
524         -numa node,nodeid=0,memdev=m0 \
525         -numa node,nodeid=1,memdev=m1,initiator=0 \
526         -smp 2,sockets=2,maxcpus=2  \
527         -numa cpu,node-id=0,socket-id=0 \
528         -numa cpu,node-id=0,socket-id=1
529
530     source and destination are NUMA node IDs. distance is the NUMA
531     distance from source to destination. The distance from a node to
532     itself is always 10. If any pair of nodes is given a distance, then
533     all pairs must be given distances. Although, when distances are only
534     given in one direction for each pair of nodes, then the distances in
535     the opposite directions are assumed to be the same. If, however, an
536     asymmetrical pair of distances is given for even one node pair, then
537     all node pairs must be provided distance values for both directions,
538     even when they are symmetrical. When a node is unreachable from
539     another node, set the pair's distance to 255.
540
541     Note that the -``numa`` option doesn't allocate any of the specified
542     resources, it just assigns existing resources to NUMA nodes. This
543     means that one still has to use the ``-m``, ``-smp`` options to
544     allocate RAM and VCPUs respectively.
545
546     Use '\ ``hmat-lb``\ ' to set System Locality Latency and Bandwidth
547     Information between initiator and target NUMA nodes in ACPI
548     Heterogeneous Attribute Memory Table (HMAT). Initiator NUMA node can
549     create memory requests, usually it has one or more processors.
550     Target NUMA node contains addressable memory.
551
552     In '\ ``hmat-lb``\ ' option, node are NUMA node IDs. hierarchy is
553     the memory hierarchy of the target NUMA node: if hierarchy is
554     'memory', the structure represents the memory performance; if
555     hierarchy is 'first-level\|second-level\|third-level', this
556     structure represents aggregated performance of memory side caches
557     for each domain. type of 'data-type' is type of data represented by
558     this structure instance: if 'hierarchy' is 'memory', 'data-type' is
559     'access\|read\|write' latency or 'access\|read\|write' bandwidth of
560     the target memory; if 'hierarchy' is
561     'first-level\|second-level\|third-level', 'data-type' is
562     'access\|read\|write' hit latency or 'access\|read\|write' hit
563     bandwidth of the target memory side cache.
564
565     lat is latency value in nanoseconds. bw is bandwidth value, the
566     possible value and units are NUM[M\|G\|T], mean that the bandwidth
567     value are NUM byte per second (or MB/s, GB/s or TB/s depending on
568     used suffix). Note that if latency or bandwidth value is 0, means
569     the corresponding latency or bandwidth information is not provided.
570
571     In '\ ``hmat-cache``\ ' option, node-id is the NUMA-id of the memory
572     belongs. size is the size of memory side cache in bytes. level is
573     the cache level described in this structure, note that the cache
574     level 0 should not be used with '\ ``hmat-cache``\ ' option.
575     associativity is the cache associativity, the possible value is
576     'none/direct(direct-mapped)/complex(complex cache indexing)'. policy
577     is the write policy. line is the cache Line size in bytes.
578
579     For example, the following options describe 2 NUMA nodes. Node 0 has
580     2 cpus and a ram, node 1 has only a ram. The processors in node 0
581     access memory in node 0 with access-latency 5 nanoseconds,
582     access-bandwidth is 200 MB/s; The processors in NUMA node 0 access
583     memory in NUMA node 1 with access-latency 10 nanoseconds,
584     access-bandwidth is 100 MB/s. And for memory side cache information,
585     NUMA node 0 and 1 both have 1 level memory cache, size is 10KB,
586     policy is write-back, the cache Line size is 8 bytes:
587
588     ::
589
590         -machine hmat=on \
591         -m 2G \
592         -object memory-backend-ram,size=1G,id=m0 \
593         -object memory-backend-ram,size=1G,id=m1 \
594         -smp 2 \
595         -numa node,nodeid=0,memdev=m0 \
596         -numa node,nodeid=1,memdev=m1,initiator=0 \
597         -numa cpu,node-id=0,socket-id=0 \
598         -numa cpu,node-id=0,socket-id=1 \
599         -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
600         -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
601         -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
602         -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
603         -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
604         -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
605 ERST
606
607 DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
608     "-add-fd fd=fd,set=set[,opaque=opaque]\n"
609     "                Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
610 STEXI
611 @item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}]
612 @findex -add-fd
613
614 Add a file descriptor to an fd set.  Valid options are:
615
616 @table @option
617 @item fd=@var{fd}
618 This option defines the file descriptor of which a duplicate is added to fd set.
619 The file descriptor cannot be stdin, stdout, or stderr.
620 @item set=@var{set}
621 This option defines the ID of the fd set to add the file descriptor to.
622 @item opaque=@var{opaque}
623 This option defines a free-form string that can be used to describe @var{fd}.
624 @end table
625
626 You can open an image using pre-opened file descriptors from an fd set:
627 @example
628 @value{qemu_system} \
629  -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
630  -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
631  -drive file=/dev/fdset/2,index=0,media=disk
632 @end example
633 ETEXI
634 SRST
635 ``-add-fd fd=fd,set=set[,opaque=opaque]``
636     Add a file descriptor to an fd set. Valid options are:
637
638     ``fd=fd``
639         This option defines the file descriptor of which a duplicate is
640         added to fd set. The file descriptor cannot be stdin, stdout, or
641         stderr.
642
643     ``set=set``
644         This option defines the ID of the fd set to add the file
645         descriptor to.
646
647     ``opaque=opaque``
648         This option defines a free-form string that can be used to
649         describe fd.
650
651     You can open an image using pre-opened file descriptors from an fd
652     set:
653
654     .. parsed-literal::
655
656         |qemu_system| \
657          -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
658          -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
659          -drive file=/dev/fdset/2,index=0,media=disk
660 ERST
661
662 DEF("set", HAS_ARG, QEMU_OPTION_set,
663     "-set group.id.arg=value\n"
664     "                set <arg> parameter for item <id> of type <group>\n"
665     "                i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
666 STEXI
667 @item -set @var{group}.@var{id}.@var{arg}=@var{value}
668 @findex -set
669 Set parameter @var{arg} for item @var{id} of type @var{group}
670 ETEXI
671 SRST
672 ``-set group.id.arg=value``
673     Set parameter arg for item id of type group
674 ERST
675
676 DEF("global", HAS_ARG, QEMU_OPTION_global,
677     "-global driver.property=value\n"
678     "-global driver=driver,property=property,value=value\n"
679     "                set a global default for a driver property\n",
680     QEMU_ARCH_ALL)
681 STEXI
682 @item -global @var{driver}.@var{prop}=@var{value}
683 @itemx -global driver=@var{driver},property=@var{property},value=@var{value}
684 @findex -global
685 Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.:
686
687 @example
688 @value{qemu_system_x86} -global ide-hd.physical_block_size=4096 disk-image.img
689 @end example
690
691 In particular, you can use this to set driver properties for devices which are
692 created automatically by the machine model. To create a device which is not
693 created automatically and set properties on it, use -@option{device}.
694
695 -global @var{driver}.@var{prop}=@var{value} is shorthand for -global
696 driver=@var{driver},property=@var{prop},value=@var{value}.  The
697 longhand syntax works even when @var{driver} contains a dot.
698 ETEXI
699 SRST
700 ``-global driver.prop=value``
701   \ 
702 ``-global driver=driver,property=property,value=value``
703     Set default value of driver's property prop to value, e.g.:
704
705     .. parsed-literal::
706
707         |qemu_system_x86| -global ide-hd.physical_block_size=4096 disk-image.img
708
709     In particular, you can use this to set driver properties for devices
710     which are created automatically by the machine model. To create a
711     device which is not created automatically and set properties on it,
712     use -``device``.
713
714     -global driver.prop=value is shorthand for -global
715     driver=driver,property=prop,value=value. The longhand syntax works
716     even when driver contains a dot.
717 ERST
718
719 DEF("boot", HAS_ARG, QEMU_OPTION_boot,
720     "-boot [order=drives][,once=drives][,menu=on|off]\n"
721     "      [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
722     "                'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
723     "                'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
724     "                'sp_time': the period that splash picture last if menu=on, unit is ms\n"
725     "                'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
726     QEMU_ARCH_ALL)
727 STEXI
728 @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]
729 @findex -boot
730 Specify boot order @var{drives} as a string of drive letters. Valid
731 drive letters depend on the target architecture. The x86 PC uses: a, b
732 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
733 from network adapter 1-4), hard disk boot is the default. To apply a
734 particular boot order only on the first startup, specify it via
735 @option{once}. Note that the @option{order} or @option{once} parameter
736 should not be used together with the @option{bootindex} property of
737 devices, since the firmware implementations normally do not support both
738 at the same time.
739
740 Interactive boot menus/prompts can be enabled via @option{menu=on} as far
741 as firmware/BIOS supports them. The default is non-interactive boot.
742
743 A splash picture could be passed to bios, enabling user to show it as logo,
744 when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
745 supports them. Currently Seabios for X86 system support it.
746 limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
747 format(true color). The resolution should be supported by the SVGA mode, so
748 the recommended is 320x240, 640x480, 800x640.
749
750 A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms
751 when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not
752 reboot, qemu passes '-1' to bios by default. Currently Seabios for X86
753 system support it.
754
755 Do strict boot via @option{strict=on} as far as firmware/BIOS
756 supports it. This only effects when boot priority is changed by
757 bootindex options. The default is non-strict boot.
758
759 @example
760 # try to boot from network first, then from hard disk
761 @value{qemu_system_x86} -boot order=nc
762 # boot from CD-ROM first, switch back to default order after reboot
763 @value{qemu_system_x86} -boot once=d
764 # boot with a splash picture for 5 seconds.
765 @value{qemu_system_x86} -boot menu=on,splash=/root/boot.bmp,splash-time=5000
766 @end example
767
768 Note: The legacy format '-boot @var{drives}' is still supported but its
769 use is discouraged as it may be removed from future versions.
770 ETEXI
771 SRST
772 ``-boot [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off]``
773     Specify boot order drives as a string of drive letters. Valid drive
774     letters depend on the target architecture. The x86 PC uses: a, b
775     (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p
776     (Etherboot from network adapter 1-4), hard disk boot is the default.
777     To apply a particular boot order only on the first startup, specify
778     it via ``once``. Note that the ``order`` or ``once`` parameter
779     should not be used together with the ``bootindex`` property of
780     devices, since the firmware implementations normally do not support
781     both at the same time.
782
783     Interactive boot menus/prompts can be enabled via ``menu=on`` as far
784     as firmware/BIOS supports them. The default is non-interactive boot.
785
786     A splash picture could be passed to bios, enabling user to show it
787     as logo, when option splash=sp\_name is given and menu=on, If
788     firmware/BIOS supports them. Currently Seabios for X86 system
789     support it. limitation: The splash file could be a jpeg file or a
790     BMP file in 24 BPP format(true color). The resolution should be
791     supported by the SVGA mode, so the recommended is 320x240, 640x480,
792     800x640.
793
794     A timeout could be passed to bios, guest will pause for rb\_timeout
795     ms when boot failed, then reboot. If rb\_timeout is '-1', guest will
796     not reboot, qemu passes '-1' to bios by default. Currently Seabios
797     for X86 system support it.
798
799     Do strict boot via ``strict=on`` as far as firmware/BIOS supports
800     it. This only effects when boot priority is changed by bootindex
801     options. The default is non-strict boot.
802
803     .. parsed-literal::
804
805         # try to boot from network first, then from hard disk
806         |qemu_system_x86| -boot order=nc
807         # boot from CD-ROM first, switch back to default order after reboot
808         |qemu_system_x86| -boot once=d
809         # boot with a splash picture for 5 seconds.
810         |qemu_system_x86| -boot menu=on,splash=/root/boot.bmp,splash-time=5000
811
812     Note: The legacy format '-boot drives' is still supported but its
813     use is discouraged as it may be removed from future versions.
814 ERST
815
816 DEF("m", HAS_ARG, QEMU_OPTION_m,
817     "-m [size=]megs[,slots=n,maxmem=size]\n"
818     "                configure guest RAM\n"
819     "                size: initial amount of guest memory\n"
820     "                slots: number of hotplug slots (default: none)\n"
821     "                maxmem: maximum amount of guest memory (default: none)\n"
822     "NOTE: Some architectures might enforce a specific granularity\n",
823     QEMU_ARCH_ALL)
824 STEXI
825 @item -m [size=]@var{megs}[,slots=n,maxmem=size]
826 @findex -m
827 Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB.
828 Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in
829 megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem}
830 could be used to set amount of hotpluggable memory slots and maximum amount of
831 memory. Note that @var{maxmem} must be aligned to the page size.
832
833 For example, the following command-line sets the guest startup RAM size to
834 1GB, creates 3 slots to hotplug additional memory and sets the maximum
835 memory the guest can reach to 4GB:
836
837 @example
838 @value{qemu_system} -m 1G,slots=3,maxmem=4G
839 @end example
840
841 If @var{slots} and @var{maxmem} are not specified, memory hotplug won't
842 be enabled and the guest startup RAM will never increase.
843 ETEXI
844 SRST
845 ``-m [size=]megs[,slots=n,maxmem=size]``
846     Sets guest startup RAM size to megs megabytes. Default is 128 MiB.
847     Optionally, a suffix of "M" or "G" can be used to signify a value in
848     megabytes or gigabytes respectively. Optional pair slots, maxmem
849     could be used to set amount of hotpluggable memory slots and maximum
850     amount of memory. Note that maxmem must be aligned to the page size.
851
852     For example, the following command-line sets the guest startup RAM
853     size to 1GB, creates 3 slots to hotplug additional memory and sets
854     the maximum memory the guest can reach to 4GB:
855
856     .. parsed-literal::
857
858         |qemu_system| -m 1G,slots=3,maxmem=4G
859
860     If slots and maxmem are not specified, memory hotplug won't be
861     enabled and the guest startup RAM will never increase.
862 ERST
863
864 DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
865     "-mem-path FILE  provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
866 STEXI
867 @item -mem-path @var{path}
868 @findex -mem-path
869 Allocate guest RAM from a temporarily created file in @var{path}.
870 ETEXI
871 SRST
872 ``-mem-path path``
873     Allocate guest RAM from a temporarily created file in path.
874 ERST
875
876 DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
877     "-mem-prealloc   preallocate guest memory (use with -mem-path)\n",
878     QEMU_ARCH_ALL)
879 STEXI
880 @item -mem-prealloc
881 @findex -mem-prealloc
882 Preallocate memory when using -mem-path.
883 ETEXI
884 SRST
885 ``-mem-prealloc``
886     Preallocate memory when using -mem-path.
887 ERST
888
889 DEF("k", HAS_ARG, QEMU_OPTION_k,
890     "-k language     use keyboard layout (for example 'fr' for French)\n",
891     QEMU_ARCH_ALL)
892 STEXI
893 @item -k @var{language}
894 @findex -k
895 Use keyboard layout @var{language} (for example @code{fr} for
896 French). This option is only needed where it is not easy to get raw PC
897 keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses
898 display). You don't normally need to use it on PC/Linux or PC/Windows
899 hosts.
900
901 The available layouts are:
902 @example
903 ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
904 da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
905 de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
906 @end example
907
908 The default is @code{en-us}.
909 ETEXI
910 SRST
911 ``-k language``
912     Use keyboard layout language (for example ``fr`` for French). This
913     option is only needed where it is not easy to get raw PC keycodes
914     (e.g. on Macs, with some X11 servers or with a VNC or curses
915     display). You don't normally need to use it on PC/Linux or
916     PC/Windows hosts.
917
918     The available layouts are:
919
920     ::
921
922         ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
923         da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
924         de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
925
926     The default is ``en-us``.
927 ERST
928
929
930 HXCOMM Deprecated by -audiodev
931 DEF("audio-help", 0, QEMU_OPTION_audio_help,
932     "-audio-help     show -audiodev equivalent of the currently specified audio settings\n",
933     QEMU_ARCH_ALL)
934 STEXI
935 @item -audio-help
936 @findex -audio-help
937 Will show the -audiodev equivalent of the currently specified
938 (deprecated) environment variables.
939 ETEXI
940 SRST
941 ``-audio-help``
942     Will show the -audiodev equivalent of the currently specified
943     (deprecated) environment variables.
944 ERST
945
946 DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
947     "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
948     "                specifies the audio backend to use\n"
949     "                id= identifier of the backend\n"
950     "                timer-period= timer period in microseconds\n"
951     "                in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n"
952     "                in|out.fixed-settings= use fixed settings for host audio\n"
953     "                in|out.frequency= frequency to use with fixed settings\n"
954     "                in|out.channels= number of channels to use with fixed settings\n"
955     "                in|out.format= sample format to use with fixed settings\n"
956     "                valid values: s8, s16, s32, u8, u16, u32\n"
957     "                in|out.voices= number of voices to use\n"
958     "                in|out.buffer-length= length of buffer in microseconds\n"
959     "-audiodev none,id=id,[,prop[=value][,...]]\n"
960     "                dummy driver that discards all output\n"
961 #ifdef CONFIG_AUDIO_ALSA
962     "-audiodev alsa,id=id[,prop[=value][,...]]\n"
963     "                in|out.dev= name of the audio device to use\n"
964     "                in|out.period-length= length of period in microseconds\n"
965     "                in|out.try-poll= attempt to use poll mode\n"
966     "                threshold= threshold (in microseconds) when playback starts\n"
967 #endif
968 #ifdef CONFIG_AUDIO_COREAUDIO
969     "-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
970     "                in|out.buffer-count= number of buffers\n"
971 #endif
972 #ifdef CONFIG_AUDIO_DSOUND
973     "-audiodev dsound,id=id[,prop[=value][,...]]\n"
974     "                latency= add extra latency to playback in microseconds\n"
975 #endif
976 #ifdef CONFIG_AUDIO_OSS
977     "-audiodev oss,id=id[,prop[=value][,...]]\n"
978     "                in|out.dev= path of the audio device to use\n"
979     "                in|out.buffer-count= number of buffers\n"
980     "                in|out.try-poll= attempt to use poll mode\n"
981     "                try-mmap= try using memory mapped access\n"
982     "                exclusive= open device in exclusive mode\n"
983     "                dsp-policy= set timing policy (0..10), -1 to use fragment mode\n"
984 #endif
985 #ifdef CONFIG_AUDIO_PA
986     "-audiodev pa,id=id[,prop[=value][,...]]\n"
987     "                server= PulseAudio server address\n"
988     "                in|out.name= source/sink device name\n"
989     "                in|out.latency= desired latency in microseconds\n"
990 #endif
991 #ifdef CONFIG_AUDIO_SDL
992     "-audiodev sdl,id=id[,prop[=value][,...]]\n"
993 #endif
994 #ifdef CONFIG_SPICE
995     "-audiodev spice,id=id[,prop[=value][,...]]\n"
996 #endif
997     "-audiodev wav,id=id[,prop[=value][,...]]\n"
998     "                path= path of wav file to record\n",
999     QEMU_ARCH_ALL)
1000 STEXI
1001 @item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]]
1002 @findex -audiodev
1003 Adds a new audio backend @var{driver} identified by @var{id}.  There are
1004 global and driver specific properties.  Some values can be set
1005 differently for input and output, they're marked with @code{in|out.}.
1006 You can set the input's property with @code{in.@var{prop}} and the
1007 output's property with @code{out.@var{prop}}. For example:
1008 @example
1009 -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
1010 -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
1011 @end example
1012
1013 NOTE: parameter validation is known to be incomplete, in many cases
1014 specifying an invalid option causes QEMU to print an error message and
1015 continue emulation without sound.
1016
1017 Valid global options are:
1018
1019 @table @option
1020 @item id=@var{identifier}
1021 Identifies the audio backend.
1022
1023 @item timer-period=@var{period}
1024 Sets the timer @var{period} used by the audio subsystem in microseconds.
1025 Default is 10000 (10 ms).
1026
1027 @item in|out.mixing-engine=on|off
1028 Use QEMU's mixing engine to mix all streams inside QEMU and convert
1029 audio formats when not supported by the backend.  When off,
1030 @var{fixed-settings} must be off too.  Note that disabling this option
1031 means that the selected backend must support multiple streams and the
1032 audio formats used by the virtual cards, otherwise you'll get no sound.
1033 It's not recommended to disable this option unless you want to use 5.1
1034 or 7.1 audio, as mixing engine only supports mono and stereo audio.
1035 Default is on.
1036
1037 @item in|out.fixed-settings=on|off
1038 Use fixed settings for host audio.  When off, it will change based on
1039 how the guest opens the sound card.  In this case you must not specify
1040 @var{frequency}, @var{channels} or @var{format}.  Default is on.
1041
1042 @item in|out.frequency=@var{frequency}
1043 Specify the @var{frequency} to use when using @var{fixed-settings}.
1044 Default is 44100Hz.
1045
1046 @item in|out.channels=@var{channels}
1047 Specify the number of @var{channels} to use when using
1048 @var{fixed-settings}. Default is 2 (stereo).
1049
1050 @item in|out.format=@var{format}
1051 Specify the sample @var{format} to use when using @var{fixed-settings}.
1052 Valid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8},
1053 @code{u16}, @code{u32}. Default is @code{s16}.
1054
1055 @item in|out.voices=@var{voices}
1056 Specify the number of @var{voices} to use.  Default is 1.
1057
1058 @item in|out.buffer-length=@var{usecs}
1059 Sets the size of the buffer in microseconds.
1060
1061 @end table
1062
1063 @item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]]
1064 Creates a dummy backend that discards all outputs.  This backend has no
1065 backend specific properties.
1066
1067 @item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
1068 Creates backend using the ALSA.  This backend is only available on
1069 Linux.
1070
1071 ALSA specific options are:
1072
1073 @table @option
1074
1075 @item in|out.dev=@var{device}
1076 Specify the ALSA @var{device} to use for input and/or output.  Default
1077 is @code{default}.
1078
1079 @item in|out.period-length=@var{usecs}
1080 Sets the period length in microseconds.
1081
1082 @item in|out.try-poll=on|off
1083 Attempt to use poll mode with the device.  Default is on.
1084
1085 @item threshold=@var{threshold}
1086 Threshold (in microseconds) when playback starts.  Default is 0.
1087
1088 @end table
1089
1090 @item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]]
1091 Creates a backend using Apple's Core Audio.  This backend is only
1092 available on Mac OS and only supports playback.
1093
1094 Core Audio specific options are:
1095
1096 @table @option
1097
1098 @item in|out.buffer-count=@var{count}
1099 Sets the @var{count} of the buffers.
1100
1101 @end table
1102
1103 @item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]]
1104 Creates a backend using Microsoft's DirectSound.  This backend is only
1105 available on Windows and only supports playback.
1106
1107 DirectSound specific options are:
1108
1109 @table @option
1110
1111 @item latency=@var{usecs}
1112 Add extra @var{usecs} microseconds latency to playback.  Default is
1113 10000 (10 ms).
1114
1115 @end table
1116
1117 @item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]]
1118 Creates a backend using OSS.  This backend is available on most
1119 Unix-like systems.
1120
1121 OSS specific options are:
1122
1123 @table @option
1124
1125 @item in|out.dev=@var{device}
1126 Specify the file name of the OSS @var{device} to use.  Default is
1127 @code{/dev/dsp}.
1128
1129 @item in|out.buffer-count=@var{count}
1130 Sets the @var{count} of the buffers.
1131
1132 @item in|out.try-poll=on|of
1133 Attempt to use poll mode with the device.  Default is on.
1134
1135 @item try-mmap=on|off
1136 Try using memory mapped device access.  Default is off.
1137
1138 @item exclusive=on|off
1139 Open the device in exclusive mode (vmix won't work in this case).
1140 Default is off.
1141
1142 @item dsp-policy=@var{policy}
1143 Sets the timing policy (between 0 and 10, where smaller number means
1144 smaller latency but higher CPU usage).  Use -1 to use buffer sizes
1145 specified by @code{buffer} and @code{buffer-count}.  This option is
1146 ignored if you do not have OSS 4. Default is 5.
1147
1148 @end table
1149
1150 @item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]]
1151 Creates a backend using PulseAudio.  This backend is available on most
1152 systems.
1153
1154 PulseAudio specific options are:
1155
1156 @table @option
1157
1158 @item server=@var{server}
1159 Sets the PulseAudio @var{server} to connect to.
1160
1161 @item in|out.name=@var{sink}
1162 Use the specified source/sink for recording/playback.
1163
1164 @item in|out.latency=@var{usecs}
1165 Desired latency in microseconds.  The PulseAudio server will try to honor this
1166 value but actual latencies may be lower or higher.
1167
1168 @end table
1169
1170 @item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]]
1171 Creates a backend using SDL.  This backend is available on most systems,
1172 but you should use your platform's native backend if possible.  This
1173 backend has no backend specific properties.
1174
1175 @item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]]
1176 Creates a backend that sends audio through SPICE.  This backend requires
1177 @code{-spice} and automatically selected in that case, so usually you
1178 can ignore this option.  This backend has no backend specific
1179 properties.
1180
1181 @item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]]
1182 Creates a backend that writes audio to a WAV file.
1183
1184 Backend specific options are:
1185
1186 @table @option
1187
1188 @item path=@var{path}
1189 Write recorded audio into the specified file.  Default is
1190 @code{qemu.wav}.
1191
1192 @end table
1193 ETEXI
1194 SRST
1195 ``-audiodev [driver=]driver,id=id[,prop[=value][,...]]``
1196     Adds a new audio backend driver identified by id. There are global
1197     and driver specific properties. Some values can be set differently
1198     for input and output, they're marked with ``in|out.``. You can set
1199     the input's property with ``in.prop`` and the output's property with
1200     ``out.prop``. For example:
1201
1202     ::
1203
1204         -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
1205         -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
1206
1207     NOTE: parameter validation is known to be incomplete, in many cases
1208     specifying an invalid option causes QEMU to print an error message
1209     and continue emulation without sound.
1210
1211     Valid global options are:
1212
1213     ``id=identifier``
1214         Identifies the audio backend.
1215
1216     ``timer-period=period``
1217         Sets the timer period used by the audio subsystem in
1218         microseconds. Default is 10000 (10 ms).
1219
1220     ``in|out.mixing-engine=on|off``
1221         Use QEMU's mixing engine to mix all streams inside QEMU and
1222         convert audio formats when not supported by the backend. When
1223         off, fixed-settings must be off too. Note that disabling this
1224         option means that the selected backend must support multiple
1225         streams and the audio formats used by the virtual cards,
1226         otherwise you'll get no sound. It's not recommended to disable
1227         this option unless you want to use 5.1 or 7.1 audio, as mixing
1228         engine only supports mono and stereo audio. Default is on.
1229
1230     ``in|out.fixed-settings=on|off``
1231         Use fixed settings for host audio. When off, it will change
1232         based on how the guest opens the sound card. In this case you
1233         must not specify frequency, channels or format. Default is on.
1234
1235     ``in|out.frequency=frequency``
1236         Specify the frequency to use when using fixed-settings. Default
1237         is 44100Hz.
1238
1239     ``in|out.channels=channels``
1240         Specify the number of channels to use when using fixed-settings.
1241         Default is 2 (stereo).
1242
1243     ``in|out.format=format``
1244         Specify the sample format to use when using fixed-settings.
1245         Valid values are: ``s8``, ``s16``, ``s32``, ``u8``, ``u16``,
1246         ``u32``. Default is ``s16``.
1247
1248     ``in|out.voices=voices``
1249         Specify the number of voices to use. Default is 1.
1250
1251     ``in|out.buffer-length=usecs``
1252         Sets the size of the buffer in microseconds.
1253
1254 ``-audiodev none,id=id[,prop[=value][,...]]``
1255     Creates a dummy backend that discards all outputs. This backend has
1256     no backend specific properties.
1257
1258 ``-audiodev alsa,id=id[,prop[=value][,...]]``
1259     Creates backend using the ALSA. This backend is only available on
1260     Linux.
1261
1262     ALSA specific options are:
1263
1264     ``in|out.dev=device``
1265         Specify the ALSA device to use for input and/or output. Default
1266         is ``default``.
1267
1268     ``in|out.period-length=usecs``
1269         Sets the period length in microseconds.
1270
1271     ``in|out.try-poll=on|off``
1272         Attempt to use poll mode with the device. Default is on.
1273
1274     ``threshold=threshold``
1275         Threshold (in microseconds) when playback starts. Default is 0.
1276
1277 ``-audiodev coreaudio,id=id[,prop[=value][,...]]``
1278     Creates a backend using Apple's Core Audio. This backend is only
1279     available on Mac OS and only supports playback.
1280
1281     Core Audio specific options are:
1282
1283     ``in|out.buffer-count=count``
1284         Sets the count of the buffers.
1285
1286 ``-audiodev dsound,id=id[,prop[=value][,...]]``
1287     Creates a backend using Microsoft's DirectSound. This backend is
1288     only available on Windows and only supports playback.
1289
1290     DirectSound specific options are:
1291
1292     ``latency=usecs``
1293         Add extra usecs microseconds latency to playback. Default is
1294         10000 (10 ms).
1295
1296 ``-audiodev oss,id=id[,prop[=value][,...]]``
1297     Creates a backend using OSS. This backend is available on most
1298     Unix-like systems.
1299
1300     OSS specific options are:
1301
1302     ``in|out.dev=device``
1303         Specify the file name of the OSS device to use. Default is
1304         ``/dev/dsp``.
1305
1306     ``in|out.buffer-count=count``
1307         Sets the count of the buffers.
1308
1309     ``in|out.try-poll=on|of``
1310         Attempt to use poll mode with the device. Default is on.
1311
1312     ``try-mmap=on|off``
1313         Try using memory mapped device access. Default is off.
1314
1315     ``exclusive=on|off``
1316         Open the device in exclusive mode (vmix won't work in this
1317         case). Default is off.
1318
1319     ``dsp-policy=policy``
1320         Sets the timing policy (between 0 and 10, where smaller number
1321         means smaller latency but higher CPU usage). Use -1 to use
1322         buffer sizes specified by ``buffer`` and ``buffer-count``. This
1323         option is ignored if you do not have OSS 4. Default is 5.
1324
1325 ``-audiodev pa,id=id[,prop[=value][,...]]``
1326     Creates a backend using PulseAudio. This backend is available on
1327     most systems.
1328
1329     PulseAudio specific options are:
1330
1331     ``server=server``
1332         Sets the PulseAudio server to connect to.
1333
1334     ``in|out.name=sink``
1335         Use the specified source/sink for recording/playback.
1336
1337     ``in|out.latency=usecs``
1338         Desired latency in microseconds. The PulseAudio server will try
1339         to honor this value but actual latencies may be lower or higher.
1340
1341 ``-audiodev sdl,id=id[,prop[=value][,...]]``
1342     Creates a backend using SDL. This backend is available on most
1343     systems, but you should use your platform's native backend if
1344     possible. This backend has no backend specific properties.
1345
1346 ``-audiodev spice,id=id[,prop[=value][,...]]``
1347     Creates a backend that sends audio through SPICE. This backend
1348     requires ``-spice`` and automatically selected in that case, so
1349     usually you can ignore this option. This backend has no backend
1350     specific properties.
1351
1352 ``-audiodev wav,id=id[,prop[=value][,...]]``
1353     Creates a backend that writes audio to a WAV file.
1354
1355     Backend specific options are:
1356
1357     ``path=path``
1358         Write recorded audio into the specified file. Default is
1359         ``qemu.wav``.
1360 ERST
1361
1362 DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
1363     "-soundhw c1,... enable audio support\n"
1364     "                and only specified sound cards (comma separated list)\n"
1365     "                use '-soundhw help' to get the list of supported cards\n"
1366     "                use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
1367 STEXI
1368 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
1369 @findex -soundhw
1370 Enable audio and selected sound hardware. Use 'help' to print all
1371 available sound hardware. For example:
1372
1373 @example
1374 @value{qemu_system_x86} -soundhw sb16,adlib disk.img
1375 @value{qemu_system_x86} -soundhw es1370 disk.img
1376 @value{qemu_system_x86} -soundhw ac97 disk.img
1377 @value{qemu_system_x86} -soundhw hda disk.img
1378 @value{qemu_system_x86} -soundhw all disk.img
1379 @value{qemu_system_x86} -soundhw help
1380 @end example
1381
1382 Note that Linux's i810_audio OSS kernel (for AC97) module might
1383 require manually specifying clocking.
1384
1385 @example
1386 modprobe i810_audio clocking=48000
1387 @end example
1388 ETEXI
1389 SRST
1390 ``-soundhw card1[,card2,...] or -soundhw all``
1391     Enable audio and selected sound hardware. Use 'help' to print all
1392     available sound hardware. For example:
1393
1394     .. parsed-literal::
1395
1396         |qemu_system_x86| -soundhw sb16,adlib disk.img
1397         |qemu_system_x86| -soundhw es1370 disk.img
1398         |qemu_system_x86| -soundhw ac97 disk.img
1399         |qemu_system_x86| -soundhw hda disk.img
1400         |qemu_system_x86| -soundhw all disk.img
1401         |qemu_system_x86| -soundhw help
1402
1403     Note that Linux's i810\_audio OSS kernel (for AC97) module might
1404     require manually specifying clocking.
1405
1406     ::
1407
1408         modprobe i810_audio clocking=48000
1409 ERST
1410
1411 DEF("device", HAS_ARG, QEMU_OPTION_device,
1412     "-device driver[,prop[=value][,...]]\n"
1413     "                add device (based on driver)\n"
1414     "                prop=value,... sets driver properties\n"
1415     "                use '-device help' to print all possible drivers\n"
1416     "                use '-device driver,help' to print all possible properties\n",
1417     QEMU_ARCH_ALL)
1418 STEXI
1419 @item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
1420 @findex -device
1421 Add device @var{driver}.  @var{prop}=@var{value} sets driver
1422 properties.  Valid properties depend on the driver.  To get help on
1423 possible drivers and properties, use @code{-device help} and
1424 @code{-device @var{driver},help}.
1425
1426 Some drivers are:
1427 @item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}][,guid=@var{uuid}]
1428
1429 Add an IPMI BMC.  This is a simulation of a hardware management
1430 interface processor that normally sits on a system.  It provides
1431 a watchdog and the ability to reset and power control the system.
1432 You need to connect this to an IPMI interface to make it useful
1433
1434 The IPMI slave address to use for the BMC.  The default is 0x20.
1435 This address is the BMC's address on the I2C network of management
1436 controllers.  If you don't know what this means, it is safe to ignore
1437 it.
1438
1439 @table @option
1440 @item id=@var{id}
1441 The BMC id for interfaces to use this device.
1442 @item slave_addr=@var{val}
1443 Define slave address to use for the BMC.  The default is 0x20.
1444 @item sdrfile=@var{file}
1445 file containing raw Sensor Data Records (SDR) data. The default is none.
1446 @item fruareasize=@var{val}
1447 size of a Field Replaceable Unit (FRU) area.  The default is 1024.
1448 @item frudatafile=@var{file}
1449 file containing raw Field Replaceable Unit (FRU) inventory data. The default is none.
1450 @item guid=@var{uuid}
1451 value for the GUID for the BMC, in standard UUID format.  If this is set,
1452 get "Get GUID" command to the BMC will return it.  Otherwise "Get GUID"
1453 will return an error.
1454 @end table
1455
1456 @item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}]
1457
1458 Add a connection to an external IPMI BMC simulator.  Instead of
1459 locally emulating the BMC like the above item, instead connect
1460 to an external entity that provides the IPMI services.
1461
1462 A connection is made to an external BMC simulator.  If you do this, it
1463 is strongly recommended that you use the "reconnect=" chardev option
1464 to reconnect to the simulator if the connection is lost.  Note that if
1465 this is not used carefully, it can be a security issue, as the
1466 interface has the ability to send resets, NMIs, and power off the VM.
1467 It's best if QEMU makes a connection to an external simulator running
1468 on a secure port on localhost, so neither the simulator nor QEMU is
1469 exposed to any outside network.
1470
1471 See the "lanserv/README.vm" file in the OpenIPMI library for more
1472 details on the external interface.
1473
1474 @item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
1475
1476 Add a KCS IPMI interafce on the ISA bus.  This also adds a
1477 corresponding ACPI and SMBIOS entries, if appropriate.
1478
1479 @table @option
1480 @item bmc=@var{id}
1481 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
1482 @item ioport=@var{val}
1483 Define the I/O address of the interface.  The default is 0xca0 for KCS.
1484 @item irq=@var{val}
1485 Define the interrupt to use.  The default is 5.  To disable interrupts,
1486 set this to 0.
1487 @end table
1488
1489 @item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}]
1490
1491 Like the KCS interface, but defines a BT interface.  The default port is
1492 0xe4 and the default interrupt is 5.
1493
1494 ETEXI
1495 SRST
1496 ``-device driver[,prop[=value][,...]]``
1497     Add device driver. prop=value sets driver properties. Valid
1498     properties depend on the driver. To get help on possible drivers and
1499     properties, use ``-device help`` and ``-device driver,help``.
1500
1501     Some drivers are:
1502
1503 ``-device ipmi-bmc-sim,id=id[,slave_addr=val][,sdrfile=file][,furareasize=val][,furdatafile=file][,guid=uuid]``
1504     Add an IPMI BMC. This is a simulation of a hardware management
1505     interface processor that normally sits on a system. It provides a
1506     watchdog and the ability to reset and power control the system. You
1507     need to connect this to an IPMI interface to make it useful
1508
1509     The IPMI slave address to use for the BMC. The default is 0x20. This
1510     address is the BMC's address on the I2C network of management
1511     controllers. If you don't know what this means, it is safe to ignore
1512     it.
1513
1514     ``id=id``
1515         The BMC id for interfaces to use this device.
1516
1517     ``slave_addr=val``
1518         Define slave address to use for the BMC. The default is 0x20.
1519
1520     ``sdrfile=file``
1521         file containing raw Sensor Data Records (SDR) data. The default
1522         is none.
1523
1524     ``fruareasize=val``
1525         size of a Field Replaceable Unit (FRU) area. The default is
1526         1024.
1527
1528     ``frudatafile=file``
1529         file containing raw Field Replaceable Unit (FRU) inventory data.
1530         The default is none.
1531
1532     ``guid=uuid``
1533         value for the GUID for the BMC, in standard UUID format. If this
1534         is set, get "Get GUID" command to the BMC will return it.
1535         Otherwise "Get GUID" will return an error.
1536
1537 ``-device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]``
1538     Add a connection to an external IPMI BMC simulator. Instead of
1539     locally emulating the BMC like the above item, instead connect to an
1540     external entity that provides the IPMI services.
1541
1542     A connection is made to an external BMC simulator. If you do this,
1543     it is strongly recommended that you use the "reconnect=" chardev
1544     option to reconnect to the simulator if the connection is lost. Note
1545     that if this is not used carefully, it can be a security issue, as
1546     the interface has the ability to send resets, NMIs, and power off
1547     the VM. It's best if QEMU makes a connection to an external
1548     simulator running on a secure port on localhost, so neither the
1549     simulator nor QEMU is exposed to any outside network.
1550
1551     See the "lanserv/README.vm" file in the OpenIPMI library for more
1552     details on the external interface.
1553
1554 ``-device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]``
1555     Add a KCS IPMI interafce on the ISA bus. This also adds a
1556     corresponding ACPI and SMBIOS entries, if appropriate.
1557
1558     ``bmc=id``
1559         The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern
1560         above.
1561
1562     ``ioport=val``
1563         Define the I/O address of the interface. The default is 0xca0
1564         for KCS.
1565
1566     ``irq=val``
1567         Define the interrupt to use. The default is 5. To disable
1568         interrupts, set this to 0.
1569
1570 ``-device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]``
1571     Like the KCS interface, but defines a BT interface. The default port
1572     is 0xe4 and the default interrupt is 5.
1573 ERST
1574
1575 DEF("name", HAS_ARG, QEMU_OPTION_name,
1576     "-name string1[,process=string2][,debug-threads=on|off]\n"
1577     "                set the name of the guest\n"
1578     "                string1 sets the window title and string2 the process name\n"
1579     "                When debug-threads is enabled, individual threads are given a separate name\n"
1580     "                NOTE: The thread names are for debugging and not a stable API.\n",
1581     QEMU_ARCH_ALL)
1582 STEXI
1583 @item -name @var{name}
1584 @findex -name
1585 Sets the @var{name} of the guest.
1586 This name will be displayed in the SDL window caption.
1587 The @var{name} will also be used for the VNC server.
1588 Also optionally set the top visible process name in Linux.
1589 Naming of individual threads can also be enabled on Linux to aid debugging.
1590 ETEXI
1591 SRST
1592 ``-name name``
1593     Sets the name of the guest. This name will be displayed in the SDL
1594     window caption. The name will also be used for the VNC server. Also
1595     optionally set the top visible process name in Linux. Naming of
1596     individual threads can also be enabled on Linux to aid debugging.
1597 ERST
1598
1599 DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
1600     "-uuid %08x-%04x-%04x-%04x-%012x\n"
1601     "                specify machine UUID\n", QEMU_ARCH_ALL)
1602 STEXI
1603 @item -uuid @var{uuid}
1604 @findex -uuid
1605 Set system UUID.
1606 ETEXI
1607 SRST
1608 ``-uuid uuid``
1609     Set system UUID.
1610 ERST
1611
1612 STEXI
1613 @end table
1614 ETEXI
1615 DEFHEADING()
1616
1617 DEFHEADING(Block device options:)
1618 STEXI
1619 @table @option
1620 ETEXI
1621
1622 DEF("fda", HAS_ARG, QEMU_OPTION_fda,
1623     "-fda/-fdb file  use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
1624 DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
1625 STEXI
1626 @item -fda @var{file}
1627 @itemx -fdb @var{file}
1628 @findex -fda
1629 @findex -fdb
1630 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}).
1631 ETEXI
1632 SRST
1633 ``-fda file``
1634   \
1635 ``-fdb file``
1636     Use file as floppy disk 0/1 image (see
1637     :ref:`disk_005fimages`).
1638 ERST
1639
1640 DEF("hda", HAS_ARG, QEMU_OPTION_hda,
1641     "-hda/-hdb file  use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
1642 DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
1643 DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
1644     "-hdc/-hdd file  use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
1645 DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
1646 STEXI
1647 @item -hda @var{file}
1648 @itemx -hdb @var{file}
1649 @itemx -hdc @var{file}
1650 @itemx -hdd @var{file}
1651 @findex -hda
1652 @findex -hdb
1653 @findex -hdc
1654 @findex -hdd
1655 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
1656 ETEXI
1657 SRST
1658 ``-hda file``
1659   \
1660 ``-hdb file``
1661   \ 
1662 ``-hdc file``
1663   \ 
1664 ``-hdd file``
1665     Use file as hard disk 0, 1, 2 or 3 image (see
1666     :ref:`disk_005fimages`).
1667 ERST
1668
1669 DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
1670     "-cdrom file     use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
1671     QEMU_ARCH_ALL)
1672 STEXI
1673 @item -cdrom @var{file}
1674 @findex -cdrom
1675 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
1676 @option{-cdrom} at the same time). You can use the host CD-ROM by
1677 using @file{/dev/cdrom} as filename.
1678 ETEXI
1679 SRST
1680 ``-cdrom file``
1681     Use file as CD-ROM image (you cannot use ``-hdc`` and ``-cdrom`` at
1682     the same time). You can use the host CD-ROM by using ``/dev/cdrom``
1683     as filename.
1684 ERST
1685
1686 DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
1687     "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
1688     "          [,cache.direct=on|off][,cache.no-flush=on|off]\n"
1689     "          [,read-only=on|off][,auto-read-only=on|off]\n"
1690     "          [,force-share=on|off][,detect-zeroes=on|off|unmap]\n"
1691     "          [,driver specific parameters...]\n"
1692     "                configure a block backend\n", QEMU_ARCH_ALL)
1693 STEXI
1694 @item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]]
1695 @findex -blockdev
1696
1697 Define a new block driver node. Some of the options apply to all block drivers,
1698 other options are only accepted for a specific block driver. See below for a
1699 list of generic options and options for the most common block drivers.
1700
1701 Options that expect a reference to another node (e.g. @code{file}) can be
1702 given in two ways. Either you specify the node name of an already existing node
1703 (file=@var{node-name}), or you define a new node inline, adding options
1704 for the referenced node after a dot (file.filename=@var{path},file.aio=native).
1705
1706 A block driver node created with @option{-blockdev} can be used for a guest
1707 device by specifying its node name for the @code{drive} property in a
1708 @option{-device} argument that defines a block device.
1709
1710 @table @option
1711 @item Valid options for any block driver node:
1712
1713 @table @code
1714 @item driver
1715 Specifies the block driver to use for the given node.
1716 @item node-name
1717 This defines the name of the block driver node by which it will be referenced
1718 later. The name must be unique, i.e. it must not match the name of a different
1719 block driver node, or (if you use @option{-drive} as well) the ID of a drive.
1720
1721 If no node name is specified, it is automatically generated. The generated node
1722 name is not intended to be predictable and changes between QEMU invocations.
1723 For the top level, an explicit node name must be specified.
1724 @item read-only
1725 Open the node read-only. Guest write attempts will fail.
1726
1727 Note that some block drivers support only read-only access, either generally or
1728 in certain configurations. In this case, the default value
1729 @option{read-only=off} does not work and the option must be specified
1730 explicitly.
1731 @item auto-read-only
1732 If @option{auto-read-only=on} is set, QEMU may fall back to read-only usage
1733 even when @option{read-only=off} is requested, or even switch between modes as
1734 needed, e.g. depending on whether the image file is writable or whether a
1735 writing user is attached to the node.
1736 @item force-share
1737 Override the image locking system of QEMU by forcing the node to utilize
1738 weaker shared access for permissions where it would normally request exclusive
1739 access.  When there is the potential for multiple instances to have the same
1740 file open (whether this invocation of QEMU is the first or the second
1741 instance), both instances must permit shared access for the second instance to
1742 succeed at opening the file.
1743
1744 Enabling @option{force-share=on} requires @option{read-only=on}.
1745 @item cache.direct
1746 The host page cache can be avoided with @option{cache.direct=on}. This will
1747 attempt to do disk IO directly to the guest's memory. QEMU may still perform an
1748 internal copy of the data.
1749 @item cache.no-flush
1750 In case you don't care about data integrity over host failures, you can use
1751 @option{cache.no-flush=on}. This option tells QEMU that it never needs to write
1752 any data to the disk but can instead keep things in cache. If anything goes
1753 wrong, like your host losing power, the disk storage getting disconnected
1754 accidentally, etc. your image will most probably be rendered unusable.
1755 @item discard=@var{discard}
1756 @var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls
1757 whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are
1758 ignored or passed to the filesystem. Some machine types may not support
1759 discard requests.
1760 @item detect-zeroes=@var{detect-zeroes}
1761 @var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic
1762 conversion of plain zero writes by the OS to driver specific optimized
1763 zero write commands. You may even choose "unmap" if @var{discard} is set
1764 to "unmap" to allow a zero write to be converted to an @code{unmap} operation.
1765 @end table
1766
1767 @item Driver-specific options for @code{file}
1768
1769 This is the protocol-level block driver for accessing regular files.
1770
1771 @table @code
1772 @item filename
1773 The path to the image file in the local filesystem
1774 @item aio
1775 Specifies the AIO backend (threads/native, default: threads)
1776 @item locking
1777 Specifies whether the image file is protected with Linux OFD / POSIX locks. The
1778 default is to use the Linux Open File Descriptor API if available, otherwise no
1779 lock is applied.  (auto/on/off, default: auto)
1780 @end table
1781 Example:
1782 @example
1783 -blockdev driver=file,node-name=disk,filename=disk.img
1784 @end example
1785
1786 @item Driver-specific options for @code{raw}
1787
1788 This is the image format block driver for raw images. It is usually
1789 stacked on top of a protocol level block driver such as @code{file}.
1790
1791 @table @code
1792 @item file
1793 Reference to or definition of the data source block driver node
1794 (e.g. a @code{file} driver node)
1795 @end table
1796 Example 1:
1797 @example
1798 -blockdev driver=file,node-name=disk_file,filename=disk.img
1799 -blockdev driver=raw,node-name=disk,file=disk_file
1800 @end example
1801 Example 2:
1802 @example
1803 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
1804 @end example
1805
1806 @item Driver-specific options for @code{qcow2}
1807
1808 This is the image format block driver for qcow2 images. It is usually
1809 stacked on top of a protocol level block driver such as @code{file}.
1810
1811 @table @code
1812 @item file
1813 Reference to or definition of the data source block driver node
1814 (e.g. a @code{file} driver node)
1815
1816 @item backing
1817 Reference to or definition of the backing file block device (default is taken
1818 from the image file). It is allowed to pass @code{null} here in order to disable
1819 the default backing file.
1820
1821 @item lazy-refcounts
1822 Whether to enable the lazy refcounts feature (on/off; default is taken from the
1823 image file)
1824
1825 @item cache-size
1826 The maximum total size of the L2 table and refcount block caches in bytes
1827 (default: the sum of l2-cache-size and refcount-cache-size)
1828
1829 @item l2-cache-size
1830 The maximum size of the L2 table cache in bytes
1831 (default: if cache-size is not specified - 32M on Linux platforms, and 8M on
1832 non-Linux platforms; otherwise, as large as possible within the cache-size,
1833 while permitting the requested or the minimal refcount cache size)
1834
1835 @item refcount-cache-size
1836 The maximum size of the refcount block cache in bytes
1837 (default: 4 times the cluster size; or if cache-size is specified, the part of
1838 it which is not used for the L2 cache)
1839
1840 @item cache-clean-interval
1841 Clean unused entries in the L2 and refcount caches. The interval is in seconds.
1842 The default value is 600 on supporting platforms, and 0 on other platforms.
1843 Setting it to 0 disables this feature.
1844
1845 @item pass-discard-request
1846 Whether discard requests to the qcow2 device should be forwarded to the data
1847 source (on/off; default: on if discard=unmap is specified, off otherwise)
1848
1849 @item pass-discard-snapshot
1850 Whether discard requests for the data source should be issued when a snapshot
1851 operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off;
1852 default: on)
1853
1854 @item pass-discard-other
1855 Whether discard requests for the data source should be issued on other
1856 occasions where a cluster gets freed (on/off; default: off)
1857
1858 @item overlap-check
1859 Which overlap checks to perform for writes to the image
1860 (none/constant/cached/all; default: cached). For details or finer
1861 granularity control refer to the QAPI documentation of @code{blockdev-add}.
1862 @end table
1863
1864 Example 1:
1865 @example
1866 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1867 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1868 @end example
1869 Example 2:
1870 @example
1871 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1872 @end example
1873
1874 @item Driver-specific options for other drivers
1875 Please refer to the QAPI documentation of the @code{blockdev-add} QMP command.
1876
1877 @end table
1878
1879 ETEXI
1880 SRST
1881 ``-blockdev option[,option[,option[,...]]]``
1882     Define a new block driver node. Some of the options apply to all
1883     block drivers, other options are only accepted for a specific block
1884     driver. See below for a list of generic options and options for the
1885     most common block drivers.
1886
1887     Options that expect a reference to another node (e.g. ``file``) can
1888     be given in two ways. Either you specify the node name of an already
1889     existing node (file=node-name), or you define a new node inline,
1890     adding options for the referenced node after a dot
1891     (file.filename=path,file.aio=native).
1892
1893     A block driver node created with ``-blockdev`` can be used for a
1894     guest device by specifying its node name for the ``drive`` property
1895     in a ``-device`` argument that defines a block device.
1896
1897     ``Valid options for any block driver node:``
1898         ``driver``
1899             Specifies the block driver to use for the given node.
1900
1901         ``node-name``
1902             This defines the name of the block driver node by which it
1903             will be referenced later. The name must be unique, i.e. it
1904             must not match the name of a different block driver node, or
1905             (if you use ``-drive`` as well) the ID of a drive.
1906
1907             If no node name is specified, it is automatically generated.
1908             The generated node name is not intended to be predictable
1909             and changes between QEMU invocations. For the top level, an
1910             explicit node name must be specified.
1911
1912         ``read-only``
1913             Open the node read-only. Guest write attempts will fail.
1914
1915             Note that some block drivers support only read-only access,
1916             either generally or in certain configurations. In this case,
1917             the default value ``read-only=off`` does not work and the
1918             option must be specified explicitly.
1919
1920         ``auto-read-only``
1921             If ``auto-read-only=on`` is set, QEMU may fall back to
1922             read-only usage even when ``read-only=off`` is requested, or
1923             even switch between modes as needed, e.g. depending on
1924             whether the image file is writable or whether a writing user
1925             is attached to the node.
1926
1927         ``force-share``
1928             Override the image locking system of QEMU by forcing the
1929             node to utilize weaker shared access for permissions where
1930             it would normally request exclusive access. When there is
1931             the potential for multiple instances to have the same file
1932             open (whether this invocation of QEMU is the first or the
1933             second instance), both instances must permit shared access
1934             for the second instance to succeed at opening the file.
1935
1936             Enabling ``force-share=on`` requires ``read-only=on``.
1937
1938         ``cache.direct``
1939             The host page cache can be avoided with ``cache.direct=on``.
1940             This will attempt to do disk IO directly to the guest's
1941             memory. QEMU may still perform an internal copy of the data.
1942
1943         ``cache.no-flush``
1944             In case you don't care about data integrity over host
1945             failures, you can use ``cache.no-flush=on``. This option
1946             tells QEMU that it never needs to write any data to the disk
1947             but can instead keep things in cache. If anything goes
1948             wrong, like your host losing power, the disk storage getting
1949             disconnected accidentally, etc. your image will most
1950             probably be rendered unusable.
1951
1952         ``discard=discard``
1953             discard is one of "ignore" (or "off") or "unmap" (or "on")
1954             and controls whether ``discard`` (also known as ``trim`` or
1955             ``unmap``) requests are ignored or passed to the filesystem.
1956             Some machine types may not support discard requests.
1957
1958         ``detect-zeroes=detect-zeroes``
1959             detect-zeroes is "off", "on" or "unmap" and enables the
1960             automatic conversion of plain zero writes by the OS to
1961             driver specific optimized zero write commands. You may even
1962             choose "unmap" if discard is set to "unmap" to allow a zero
1963             write to be converted to an ``unmap`` operation.
1964
1965     ``Driver-specific options for file``
1966         This is the protocol-level block driver for accessing regular
1967         files.
1968
1969         ``filename``
1970             The path to the image file in the local filesystem
1971
1972         ``aio``
1973             Specifies the AIO backend (threads/native, default: threads)
1974
1975         ``locking``
1976             Specifies whether the image file is protected with Linux OFD
1977             / POSIX locks. The default is to use the Linux Open File
1978             Descriptor API if available, otherwise no lock is applied.
1979             (auto/on/off, default: auto)
1980
1981         Example:
1982
1983         ::
1984
1985             -blockdev driver=file,node-name=disk,filename=disk.img
1986
1987     ``Driver-specific options for raw``
1988         This is the image format block driver for raw images. It is
1989         usually stacked on top of a protocol level block driver such as
1990         ``file``.
1991
1992         ``file``
1993             Reference to or definition of the data source block driver
1994             node (e.g. a ``file`` driver node)
1995
1996         Example 1:
1997
1998         ::
1999
2000             -blockdev driver=file,node-name=disk_file,filename=disk.img
2001             -blockdev driver=raw,node-name=disk,file=disk_file
2002
2003         Example 2:
2004
2005         ::
2006
2007             -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
2008
2009     ``Driver-specific options for qcow2``
2010         This is the image format block driver for qcow2 images. It is
2011         usually stacked on top of a protocol level block driver such as
2012         ``file``.
2013
2014         ``file``
2015             Reference to or definition of the data source block driver
2016             node (e.g. a ``file`` driver node)
2017
2018         ``backing``
2019             Reference to or definition of the backing file block device
2020             (default is taken from the image file). It is allowed to
2021             pass ``null`` here in order to disable the default backing
2022             file.
2023
2024         ``lazy-refcounts``
2025             Whether to enable the lazy refcounts feature (on/off;
2026             default is taken from the image file)
2027
2028         ``cache-size``
2029             The maximum total size of the L2 table and refcount block
2030             caches in bytes (default: the sum of l2-cache-size and
2031             refcount-cache-size)
2032
2033         ``l2-cache-size``
2034             The maximum size of the L2 table cache in bytes (default: if
2035             cache-size is not specified - 32M on Linux platforms, and 8M
2036             on non-Linux platforms; otherwise, as large as possible
2037             within the cache-size, while permitting the requested or the
2038             minimal refcount cache size)
2039
2040         ``refcount-cache-size``
2041             The maximum size of the refcount block cache in bytes
2042             (default: 4 times the cluster size; or if cache-size is
2043             specified, the part of it which is not used for the L2
2044             cache)
2045
2046         ``cache-clean-interval``
2047             Clean unused entries in the L2 and refcount caches. The
2048             interval is in seconds. The default value is 600 on
2049             supporting platforms, and 0 on other platforms. Setting it
2050             to 0 disables this feature.
2051
2052         ``pass-discard-request``
2053             Whether discard requests to the qcow2 device should be
2054             forwarded to the data source (on/off; default: on if
2055             discard=unmap is specified, off otherwise)
2056
2057         ``pass-discard-snapshot``
2058             Whether discard requests for the data source should be
2059             issued when a snapshot operation (e.g. deleting a snapshot)
2060             frees clusters in the qcow2 file (on/off; default: on)
2061
2062         ``pass-discard-other``
2063             Whether discard requests for the data source should be
2064             issued on other occasions where a cluster gets freed
2065             (on/off; default: off)
2066
2067         ``overlap-check``
2068             Which overlap checks to perform for writes to the image
2069             (none/constant/cached/all; default: cached). For details or
2070             finer granularity control refer to the QAPI documentation of
2071             ``blockdev-add``.
2072
2073         Example 1:
2074
2075         ::
2076
2077             -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
2078             -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
2079
2080         Example 2:
2081
2082         ::
2083
2084             -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
2085
2086     ``Driver-specific options for other drivers``
2087         Please refer to the QAPI documentation of the ``blockdev-add``
2088         QMP command.
2089 ERST
2090
2091 DEF("drive", HAS_ARG, QEMU_OPTION_drive,
2092     "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
2093     "       [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
2094     "       [,snapshot=on|off][,rerror=ignore|stop|report]\n"
2095     "       [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n"
2096     "       [,readonly=on|off][,copy-on-read=on|off]\n"
2097     "       [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n"
2098     "       [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n"
2099     "       [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n"
2100     "       [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n"
2101     "       [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n"
2102     "       [[,iops_size=is]]\n"
2103     "       [[,group=g]]\n"
2104     "                use 'file' as a drive image\n", QEMU_ARCH_ALL)
2105 STEXI
2106 @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
2107 @findex -drive
2108
2109 Define a new drive. This includes creating a block driver node (the backend) as
2110 well as a guest device, and is mostly a shortcut for defining the corresponding
2111 @option{-blockdev} and @option{-device} options.
2112
2113 @option{-drive} accepts all options that are accepted by @option{-blockdev}. In
2114 addition, it knows the following options:
2115
2116 @table @option
2117 @item file=@var{file}
2118 This option defines which disk image (@pxref{disk_images}) to use with
2119 this drive. If the filename contains comma, you must double it
2120 (for instance, "file=my,,file" to use file "my,file").
2121
2122 Special files such as iSCSI devices can be specified using protocol
2123 specific URLs. See the section for "Device URL Syntax" for more information.
2124 @item if=@var{interface}
2125 This option defines on which type on interface the drive is connected.
2126 Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
2127 @item bus=@var{bus},unit=@var{unit}
2128 These options define where is connected the drive by defining the bus number and
2129 the unit id.
2130 @item index=@var{index}
2131 This option defines where is connected the drive by using an index in the list
2132 of available connectors of a given interface type.
2133 @item media=@var{media}
2134 This option defines the type of the media: disk or cdrom.
2135 @item snapshot=@var{snapshot}
2136 @var{snapshot} is "on" or "off" and controls snapshot mode for the given drive
2137 (see @option{-snapshot}).
2138 @item cache=@var{cache}
2139 @var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough"
2140 and controls how the host cache is used to access block data. This is a
2141 shortcut that sets the @option{cache.direct} and @option{cache.no-flush}
2142 options (as in @option{-blockdev}), and additionally @option{cache.writeback},
2143 which provides a default for the @option{write-cache} option of block guest
2144 devices (as in @option{-device}). The modes correspond to the following
2145 settings:
2146
2147 @c Our texi2pod.pl script doesn't support @multitable, so fall back to using
2148 @c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage
2149 @c and the HTML output.
2150 @example
2151 @             │ cache.writeback   cache.direct   cache.no-flush
2152 ─────────────┼─────────────────────────────────────────────────
2153 writeback    │ on                off            off
2154 none         │ on                on             off
2155 writethrough │ off               off            off
2156 directsync   │ off               on             off
2157 unsafe       │ on                off            on
2158 @end example
2159
2160 The default mode is @option{cache=writeback}.
2161
2162 @item aio=@var{aio}
2163 @var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
2164 @item format=@var{format}
2165 Specify which disk @var{format} will be used rather than detecting
2166 the format.  Can be used to specify format=raw to avoid interpreting
2167 an untrusted format header.
2168 @item werror=@var{action},rerror=@var{action}
2169 Specify which @var{action} to take on write and read errors. Valid actions are:
2170 "ignore" (ignore the error and try to continue), "stop" (pause QEMU),
2171 "report" (report the error to the guest), "enospc" (pause QEMU only if the
2172 host disk is full; report the error to the guest otherwise).
2173 The default setting is @option{werror=enospc} and @option{rerror=report}.
2174 @item copy-on-read=@var{copy-on-read}
2175 @var{copy-on-read} is "on" or "off" and enables whether to copy read backing
2176 file sectors into the image file.
2177 @item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w}
2178 Specify bandwidth throttling limits in bytes per second, either for all request
2179 types or for reads or writes only.  Small values can lead to timeouts or hangs
2180 inside the guest.  A safe minimum for disks is 2 MB/s.
2181 @item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm}
2182 Specify bursts in bytes per second, either for all request types or for reads
2183 or writes only.  Bursts allow the guest I/O to spike above the limit
2184 temporarily.
2185 @item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w}
2186 Specify request rate limits in requests per second, either for all request
2187 types or for reads or writes only.
2188 @item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm}
2189 Specify bursts in requests per second, either for all request types or for reads
2190 or writes only.  Bursts allow the guest I/O to spike above the limit
2191 temporarily.
2192 @item iops_size=@var{is}
2193 Let every @var{is} bytes of a request count as a new request for iops
2194 throttling purposes.  Use this option to prevent guests from circumventing iops
2195 limits by sending fewer but larger requests.
2196 @item group=@var{g}
2197 Join a throttling quota group with given name @var{g}.  All drives that are
2198 members of the same group are accounted for together.  Use this option to
2199 prevent guests from circumventing throttling limits by using many small disks
2200 instead of a single larger disk.
2201 @end table
2202
2203 By default, the @option{cache.writeback=on} mode is used. It will report data
2204 writes as completed as soon as the data is present in the host page cache.
2205 This is safe as long as your guest OS makes sure to correctly flush disk caches
2206 where needed. If your guest OS does not handle volatile disk write caches
2207 correctly and your host crashes or loses power, then the guest may experience
2208 data corruption.
2209
2210 For such guests, you should consider using @option{cache.writeback=off}. This
2211 means that the host page cache will be used to read and write data, but write
2212 notification will be sent to the guest only after QEMU has made sure to flush
2213 each write to the disk. Be aware that this has a major impact on performance.
2214
2215 When using the @option{-snapshot} option, unsafe caching is always used.
2216
2217 Copy-on-read avoids accessing the same backing file sectors repeatedly and is
2218 useful when the backing file is over a slow network.  By default copy-on-read
2219 is off.
2220
2221 Instead of @option{-cdrom} you can use:
2222 @example
2223 @value{qemu_system} -drive file=file,index=2,media=cdrom
2224 @end example
2225
2226 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
2227 use:
2228 @example
2229 @value{qemu_system} -drive file=file,index=0,media=disk
2230 @value{qemu_system} -drive file=file,index=1,media=disk
2231 @value{qemu_system} -drive file=file,index=2,media=disk
2232 @value{qemu_system} -drive file=file,index=3,media=disk
2233 @end example
2234
2235 You can open an image using pre-opened file descriptors from an fd set:
2236 @example
2237 @value{qemu_system} \
2238  -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
2239  -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
2240  -drive file=/dev/fdset/2,index=0,media=disk
2241 @end example
2242
2243 You can connect a CDROM to the slave of ide0:
2244 @example
2245 @value{qemu_system_x86} -drive file=file,if=ide,index=1,media=cdrom
2246 @end example
2247
2248 If you don't specify the "file=" argument, you define an empty drive:
2249 @example
2250 @value{qemu_system_x86} -drive if=ide,index=1,media=cdrom
2251 @end example
2252
2253 Instead of @option{-fda}, @option{-fdb}, you can use:
2254 @example
2255 @value{qemu_system_x86} -drive file=file,index=0,if=floppy
2256 @value{qemu_system_x86} -drive file=file,index=1,if=floppy
2257 @end example
2258
2259 By default, @var{interface} is "ide" and @var{index} is automatically
2260 incremented:
2261 @example
2262 @value{qemu_system_x86} -drive file=a -drive file=b"
2263 @end example
2264 is interpreted like:
2265 @example
2266 @value{qemu_system_x86} -hda a -hdb b
2267 @end example
2268 ETEXI
2269 SRST
2270 ``-drive option[,option[,option[,...]]]``
2271     Define a new drive. This includes creating a block driver node (the
2272     backend) as well as a guest device, and is mostly a shortcut for
2273     defining the corresponding ``-blockdev`` and ``-device`` options.
2274
2275     ``-drive`` accepts all options that are accepted by ``-blockdev``.
2276     In addition, it knows the following options:
2277
2278     ``file=file``
2279         This option defines which disk image (see
2280         :ref:`disk_005fimages`) to use with this drive. If
2281         the filename contains comma, you must double it (for instance,
2282         "file=my,,file" to use file "my,file").
2283
2284         Special files such as iSCSI devices can be specified using
2285         protocol specific URLs. See the section for "Device URL Syntax"
2286         for more information.
2287
2288     ``if=interface``
2289         This option defines on which type on interface the drive is
2290         connected. Available types are: ide, scsi, sd, mtd, floppy,
2291         pflash, virtio, none.
2292
2293     ``bus=bus,unit=unit``
2294         These options define where is connected the drive by defining
2295         the bus number and the unit id.
2296
2297     ``index=index``
2298         This option defines where is connected the drive by using an
2299         index in the list of available connectors of a given interface
2300         type.
2301
2302     ``media=media``
2303         This option defines the type of the media: disk or cdrom.
2304
2305     ``snapshot=snapshot``
2306         snapshot is "on" or "off" and controls snapshot mode for the
2307         given drive (see ``-snapshot``).
2308
2309     ``cache=cache``
2310         cache is "none", "writeback", "unsafe", "directsync" or
2311         "writethrough" and controls how the host cache is used to access
2312         block data. This is a shortcut that sets the ``cache.direct``
2313         and ``cache.no-flush`` options (as in ``-blockdev``), and
2314         additionally ``cache.writeback``, which provides a default for
2315         the ``write-cache`` option of block guest devices (as in
2316         ``-device``). The modes correspond to the following settings:
2317
2318         =============  ===============   ============   ==============
2319         \              cache.writeback   cache.direct   cache.no-flush
2320         =============  ===============   ============   ==============
2321         writeback      on                off            off
2322         none           on                on             off
2323         writethrough   off               off            off
2324         directsync     off               on             off
2325         unsafe         on                off            on
2326         =============  ===============   ============   ==============
2327
2328         The default mode is ``cache=writeback``.
2329
2330     ``aio=aio``
2331         aio is "threads", or "native" and selects between pthread based
2332         disk I/O and native Linux AIO.
2333
2334     ``format=format``
2335         Specify which disk format will be used rather than detecting the
2336         format. Can be used to specify format=raw to avoid interpreting
2337         an untrusted format header.
2338
2339     ``werror=action,rerror=action``
2340         Specify which action to take on write and read errors. Valid
2341         actions are: "ignore" (ignore the error and try to continue),
2342         "stop" (pause QEMU), "report" (report the error to the guest),
2343         "enospc" (pause QEMU only if the host disk is full; report the
2344         error to the guest otherwise). The default setting is
2345         ``werror=enospc`` and ``rerror=report``.
2346
2347     ``copy-on-read=copy-on-read``
2348         copy-on-read is "on" or "off" and enables whether to copy read
2349         backing file sectors into the image file.
2350
2351     ``bps=b,bps_rd=r,bps_wr=w``
2352         Specify bandwidth throttling limits in bytes per second, either
2353         for all request types or for reads or writes only. Small values
2354         can lead to timeouts or hangs inside the guest. A safe minimum
2355         for disks is 2 MB/s.
2356
2357     ``bps_max=bm,bps_rd_max=rm,bps_wr_max=wm``
2358         Specify bursts in bytes per second, either for all request types
2359         or for reads or writes only. Bursts allow the guest I/O to spike
2360         above the limit temporarily.
2361
2362     ``iops=i,iops_rd=r,iops_wr=w``
2363         Specify request rate limits in requests per second, either for
2364         all request types or for reads or writes only.
2365
2366     ``iops_max=bm,iops_rd_max=rm,iops_wr_max=wm``
2367         Specify bursts in requests per second, either for all request
2368         types or for reads or writes only. Bursts allow the guest I/O to
2369         spike above the limit temporarily.
2370
2371     ``iops_size=is``
2372         Let every is bytes of a request count as a new request for iops
2373         throttling purposes. Use this option to prevent guests from
2374         circumventing iops limits by sending fewer but larger requests.
2375
2376     ``group=g``
2377         Join a throttling quota group with given name g. All drives that
2378         are members of the same group are accounted for together. Use
2379         this option to prevent guests from circumventing throttling
2380         limits by using many small disks instead of a single larger
2381         disk.
2382
2383     By default, the ``cache.writeback=on`` mode is used. It will report
2384     data writes as completed as soon as the data is present in the host
2385     page cache. This is safe as long as your guest OS makes sure to
2386     correctly flush disk caches where needed. If your guest OS does not
2387     handle volatile disk write caches correctly and your host crashes or
2388     loses power, then the guest may experience data corruption.
2389
2390     For such guests, you should consider using ``cache.writeback=off``.
2391     This means that the host page cache will be used to read and write
2392     data, but write notification will be sent to the guest only after
2393     QEMU has made sure to flush each write to the disk. Be aware that
2394     this has a major impact on performance.
2395
2396     When using the ``-snapshot`` option, unsafe caching is always used.
2397
2398     Copy-on-read avoids accessing the same backing file sectors
2399     repeatedly and is useful when the backing file is over a slow
2400     network. By default copy-on-read is off.
2401
2402     Instead of ``-cdrom`` you can use:
2403
2404     .. parsed-literal::
2405
2406         |qemu_system| -drive file=file,index=2,media=cdrom
2407
2408     Instead of ``-hda``, ``-hdb``, ``-hdc``, ``-hdd``, you can use:
2409
2410     .. parsed-literal::
2411
2412         |qemu_system| -drive file=file,index=0,media=disk
2413         |qemu_system| -drive file=file,index=1,media=disk
2414         |qemu_system| -drive file=file,index=2,media=disk
2415         |qemu_system| -drive file=file,index=3,media=disk
2416
2417     You can open an image using pre-opened file descriptors from an fd
2418     set:
2419
2420     .. parsed-literal::
2421
2422         |qemu_system| \
2423          -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
2424          -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
2425          -drive file=/dev/fdset/2,index=0,media=disk
2426
2427     You can connect a CDROM to the slave of ide0:
2428
2429     .. parsed-literal::
2430
2431         |qemu_system_x86| -drive file=file,if=ide,index=1,media=cdrom
2432
2433     If you don't specify the "file=" argument, you define an empty
2434     drive:
2435
2436     .. parsed-literal::
2437
2438         |qemu_system_x86| -drive if=ide,index=1,media=cdrom
2439
2440     Instead of ``-fda``, ``-fdb``, you can use:
2441
2442     .. parsed-literal::
2443
2444         |qemu_system_x86| -drive file=file,index=0,if=floppy
2445         |qemu_system_x86| -drive file=file,index=1,if=floppy
2446
2447     By default, interface is "ide" and index is automatically
2448     incremented:
2449
2450     .. parsed-literal::
2451
2452         |qemu_system_x86| -drive file=a -drive file=b"
2453
2454     is interpreted like:
2455
2456     .. parsed-literal::
2457
2458         |qemu_system_x86| -hda a -hdb b
2459 ERST
2460
2461 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
2462     "-mtdblock file  use 'file' as on-board Flash memory image\n",
2463     QEMU_ARCH_ALL)
2464 STEXI
2465 @item -mtdblock @var{file}
2466 @findex -mtdblock
2467 Use @var{file} as on-board Flash memory image.
2468 ETEXI
2469 SRST
2470 ``-mtdblock file``
2471     Use file as on-board Flash memory image.
2472 ERST
2473
2474 DEF("sd", HAS_ARG, QEMU_OPTION_sd,
2475     "-sd file        use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
2476 STEXI
2477 @item -sd @var{file}
2478 @findex -sd
2479 Use @var{file} as SecureDigital card image.
2480 ETEXI
2481 SRST
2482 ``-sd file``
2483     Use file as SecureDigital card image.
2484 ERST
2485
2486 DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
2487     "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
2488 STEXI
2489 @item -pflash @var{file}
2490 @findex -pflash
2491 Use @var{file} as a parallel flash image.
2492 ETEXI
2493 SRST
2494 ``-pflash file``
2495     Use file as a parallel flash image.
2496 ERST
2497
2498 DEF("snapshot", 0, QEMU_OPTION_snapshot,
2499     "-snapshot       write to temporary files instead of disk image files\n",
2500     QEMU_ARCH_ALL)
2501 STEXI
2502 @item -snapshot
2503 @findex -snapshot
2504 Write to temporary files instead of disk image files. In this case,
2505 the raw disk image you use is not written back. You can however force
2506 the write back by pressing @key{C-a s} (@pxref{disk_images}).
2507 ETEXI
2508 SRST
2509 ``-snapshot``
2510     Write to temporary files instead of disk image files. In this case,
2511     the raw disk image you use is not written back. You can however
2512     force the write back by pressing C-a s (see
2513     :ref:`disk_005fimages`).
2514 ERST
2515
2516 DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
2517     "-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n"
2518     " [,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode]\n"
2519     " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
2520     " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
2521     " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
2522     " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
2523     " [[,throttling.iops-size=is]]\n"
2524     "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly]\n"
2525     "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly]\n"
2526     "-fsdev synth,id=id\n",
2527     QEMU_ARCH_ALL)
2528
2529 STEXI
2530
2531 @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}[,...]]]
2532 @itemx -fsdev proxy,id=@var{id},socket=@var{socket}[,writeout=@var{writeout}][,readonly]
2533 @itemx -fsdev proxy,id=@var{id},sock_fd=@var{sock_fd}[,writeout=@var{writeout}][,readonly]
2534 @itemx -fsdev synth,id=@var{id}[,readonly]
2535 @findex -fsdev
2536 Define a new file system device. Valid options are:
2537 @table @option
2538 @item local
2539 Accesses to the filesystem are done by QEMU.
2540 @item proxy
2541 Accesses to the filesystem are done by virtfs-proxy-helper(1).
2542 @item synth
2543 Synthetic filesystem, only used by QTests.
2544 @item id=@var{id}
2545 Specifies identifier for this device.
2546 @item path=@var{path}
2547 Specifies the export path for the file system device. Files under
2548 this path will be available to the 9p client on the guest.
2549 @item security_model=@var{security_model}
2550 Specifies the security model to be used for this export path.
2551 Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
2552 In "passthrough" security model, files are stored using the same
2553 credentials as they are created on the guest. This requires QEMU
2554 to run as root. In "mapped-xattr" security model, some of the file
2555 attributes like uid, gid, mode bits and link target are stored as
2556 file attributes. For "mapped-file" these attributes are stored in the
2557 hidden .virtfs_metadata directory. Directories exported by this security model cannot
2558 interact with other unix tools. "none" security model is same as
2559 passthrough except the sever won't report failures if it fails to
2560 set file attributes like ownership. Security model is mandatory
2561 only for local fsdriver. Other fsdrivers (like proxy) don't take
2562 security model as a parameter.
2563 @item writeout=@var{writeout}
2564 This is an optional argument. The only supported value is "immediate".
2565 This means that host page cache will be used to read and write data but
2566 write notification will be sent to the guest only when the data has been
2567 reported as written by the storage subsystem.
2568 @item readonly
2569 Enables exporting 9p share as a readonly mount for guests. By default
2570 read-write access is given.
2571 @item socket=@var{socket}
2572 Enables proxy filesystem driver to use passed socket file for communicating
2573 with virtfs-proxy-helper(1).
2574 @item sock_fd=@var{sock_fd}
2575 Enables proxy filesystem driver to use passed socket descriptor for
2576 communicating with virtfs-proxy-helper(1). Usually a helper like libvirt
2577 will create socketpair and pass one of the fds as sock_fd.
2578 @item fmode=@var{fmode}
2579 Specifies the default mode for newly created files on the host. Works only
2580 with security models "mapped-xattr" and "mapped-file".
2581 @item dmode=@var{dmode}
2582 Specifies the default mode for newly created directories on the host. Works
2583 only with security models "mapped-xattr" and "mapped-file".
2584 @item throttling.bps-total=@var{b},throttling.bps-read=@var{r},throttling.bps-write=@var{w}
2585 Specify bandwidth throttling limits in bytes per second, either for all request
2586 types or for reads or writes only.
2587 @item throttling.bps-total-max=@var{bm},bps-read-max=@var{rm},bps-write-max=@var{wm}
2588 Specify bursts in bytes per second, either for all request types or for reads
2589 or writes only.  Bursts allow the guest I/O to spike above the limit
2590 temporarily.
2591 @item throttling.iops-total=@var{i},throttling.iops-read=@var{r}, throttling.iops-write=@var{w}
2592 Specify request rate limits in requests per second, either for all request
2593 types or for reads or writes only.
2594 @item throttling.iops-total-max=@var{im},throttling.iops-read-max=@var{irm}, throttling.iops-write-max=@var{iwm}
2595 Specify bursts in requests per second, either for all request types or for reads
2596 or writes only.  Bursts allow the guest I/O to spike above the limit temporarily.
2597 @item throttling.iops-size=@var{is}
2598 Let every @var{is} bytes of a request count as a new request for iops
2599 throttling purposes.
2600 @end table
2601
2602 -fsdev option is used along with -device driver "virtio-9p-...".
2603 @item -device virtio-9p-@var{type},fsdev=@var{id},mount_tag=@var{mount_tag}
2604 Options for virtio-9p-... driver are:
2605 @table @option
2606 @item @var{type}
2607 Specifies the variant to be used. Supported values are "pci", "ccw" or "device",
2608 depending on the machine type.
2609 @item fsdev=@var{id}
2610 Specifies the id value specified along with -fsdev option.
2611 @item mount_tag=@var{mount_tag}
2612 Specifies the tag name to be used by the guest to mount this export point.
2613 @end table
2614
2615 ETEXI
2616 SRST
2617 ``-fsdev local,id=id,path=path,security_model=security_model [,writeout=writeout][,readonly][,fmode=fmode][,dmode=dmode] [,throttling.option=value[,throttling.option=value[,...]]]``
2618   \ 
2619 ``-fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly]``
2620   \
2621 ``-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly]``
2622   \
2623 ``-fsdev synth,id=id[,readonly]``
2624     Define a new file system device. Valid options are:
2625
2626     ``local``
2627         Accesses to the filesystem are done by QEMU.
2628
2629     ``proxy``
2630         Accesses to the filesystem are done by virtfs-proxy-helper(1).
2631
2632     ``synth``
2633         Synthetic filesystem, only used by QTests.
2634
2635     ``id=id``
2636         Specifies identifier for this device.
2637
2638     ``path=path``
2639         Specifies the export path for the file system device. Files
2640         under this path will be available to the 9p client on the guest.
2641
2642     ``security_model=security_model``
2643         Specifies the security model to be used for this export path.
2644         Supported security models are "passthrough", "mapped-xattr",
2645         "mapped-file" and "none". In "passthrough" security model, files
2646         are stored using the same credentials as they are created on the
2647         guest. This requires QEMU to run as root. In "mapped-xattr"
2648         security model, some of the file attributes like uid, gid, mode
2649         bits and link target are stored as file attributes. For
2650         "mapped-file" these attributes are stored in the hidden
2651         .virtfs\_metadata directory. Directories exported by this
2652         security model cannot interact with other unix tools. "none"
2653         security model is same as passthrough except the sever won't
2654         report failures if it fails to set file attributes like
2655         ownership. Security model is mandatory only for local fsdriver.
2656         Other fsdrivers (like proxy) don't take security model as a
2657         parameter.
2658
2659     ``writeout=writeout``
2660         This is an optional argument. The only supported value is
2661         "immediate". This means that host page cache will be used to
2662         read and write data but write notification will be sent to the
2663         guest only when the data has been reported as written by the
2664         storage subsystem.
2665
2666     ``readonly``
2667         Enables exporting 9p share as a readonly mount for guests. By
2668         default read-write access is given.
2669
2670     ``socket=socket``
2671         Enables proxy filesystem driver to use passed socket file for
2672         communicating with virtfs-proxy-helper(1).
2673
2674     ``sock_fd=sock_fd``
2675         Enables proxy filesystem driver to use passed socket descriptor
2676         for communicating with virtfs-proxy-helper(1). Usually a helper
2677         like libvirt will create socketpair and pass one of the fds as
2678         sock\_fd.
2679
2680     ``fmode=fmode``
2681         Specifies the default mode for newly created files on the host.
2682         Works only with security models "mapped-xattr" and
2683         "mapped-file".
2684
2685     ``dmode=dmode``
2686         Specifies the default mode for newly created directories on the
2687         host. Works only with security models "mapped-xattr" and
2688         "mapped-file".
2689
2690     ``throttling.bps-total=b,throttling.bps-read=r,throttling.bps-write=w``
2691         Specify bandwidth throttling limits in bytes per second, either
2692         for all request types or for reads or writes only.
2693
2694     ``throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm``
2695         Specify bursts in bytes per second, either for all request types
2696         or for reads or writes only. Bursts allow the guest I/O to spike
2697         above the limit temporarily.
2698
2699     ``throttling.iops-total=i,throttling.iops-read=r, throttling.iops-write=w``
2700         Specify request rate limits in requests per second, either for
2701         all request types or for reads or writes only.
2702
2703     ``throttling.iops-total-max=im,throttling.iops-read-max=irm, throttling.iops-write-max=iwm``
2704         Specify bursts in requests per second, either for all request
2705         types or for reads or writes only. Bursts allow the guest I/O to
2706         spike above the limit temporarily.
2707
2708     ``throttling.iops-size=is``
2709         Let every is bytes of a request count as a new request for iops
2710         throttling purposes.
2711
2712     -fsdev option is used along with -device driver "virtio-9p-...".
2713
2714 ``-device virtio-9p-type,fsdev=id,mount_tag=mount_tag``
2715     Options for virtio-9p-... driver are:
2716
2717     ``type``
2718         Specifies the variant to be used. Supported values are "pci",
2719         "ccw" or "device", depending on the machine type.
2720
2721     ``fsdev=id``
2722         Specifies the id value specified along with -fsdev option.
2723
2724     ``mount_tag=mount_tag``
2725         Specifies the tag name to be used by the guest to mount this
2726         export point.
2727 ERST
2728
2729 DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
2730     "-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n"
2731     "        [,id=id][,writeout=immediate][,readonly][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n"
2732     "-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly]\n"
2733     "-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly]\n"
2734     "-virtfs synth,mount_tag=tag[,id=id][,readonly]\n",
2735     QEMU_ARCH_ALL)
2736
2737 STEXI
2738
2739 @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}]
2740 @itemx -virtfs proxy,socket=@var{socket},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly]
2741 @itemx -virtfs proxy,sock_fd=@var{sock_fd},mount_tag=@var{mount_tag} [,writeout=@var{writeout}][,readonly]
2742 @itemx -virtfs synth,mount_tag=@var{mount_tag}
2743 @findex -virtfs
2744
2745 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:
2746 @table @option
2747 @item local
2748 Accesses to the filesystem are done by QEMU.
2749 @item proxy
2750 Accesses to the filesystem are done by virtfs-proxy-helper(1).
2751 @item synth
2752 Synthetic filesystem, only used by QTests.
2753 @item id=@var{id}
2754 Specifies identifier for the filesystem device
2755 @item path=@var{path}
2756 Specifies the export path for the file system device. Files under
2757 this path will be available to the 9p client on the guest.
2758 @item security_model=@var{security_model}
2759 Specifies the security model to be used for this export path.
2760 Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
2761 In "passthrough" security model, files are stored using the same
2762 credentials as they are created on the guest. This requires QEMU
2763 to run as root. In "mapped-xattr" security model, some of the file
2764 attributes like uid, gid, mode bits and link target are stored as
2765 file attributes. For "mapped-file" these attributes are stored in the
2766 hidden .virtfs_metadata directory. Directories exported by this security model cannot
2767 interact with other unix tools. "none" security model is same as
2768 passthrough except the sever won't report failures if it fails to
2769 set file attributes like ownership. Security model is mandatory only
2770 for local fsdriver. Other fsdrivers (like proxy) don't take security
2771 model as a parameter.
2772 @item writeout=@var{writeout}
2773 This is an optional argument. The only supported value is "immediate".
2774 This means that host page cache will be used to read and write data but
2775 write notification will be sent to the guest only when the data has been
2776 reported as written by the storage subsystem.
2777 @item readonly
2778 Enables exporting 9p share as a readonly mount for guests. By default
2779 read-write access is given.
2780 @item socket=@var{socket}
2781 Enables proxy filesystem driver to use passed socket file for
2782 communicating with virtfs-proxy-helper(1). Usually a helper like libvirt
2783 will create socketpair and pass one of the fds as sock_fd.
2784 @item sock_fd
2785 Enables proxy filesystem driver to use passed 'sock_fd' as the socket
2786 descriptor for interfacing with virtfs-proxy-helper(1).
2787 @item fmode=@var{fmode}
2788 Specifies the default mode for newly created files on the host. Works only
2789 with security models "mapped-xattr" and "mapped-file".
2790 @item dmode=@var{dmode}
2791 Specifies the default mode for newly created directories on the host. Works
2792 only with security models "mapped-xattr" and "mapped-file".
2793 @item mount_tag=@var{mount_tag}
2794 Specifies the tag name to be used by the guest to mount this export point.
2795 @item multidevs=@var{multidevs}
2796 Specifies how to deal with multiple devices being shared with a 9p export.
2797 Supported behaviours are either "remap", "forbid" or "warn". The latter is
2798 the default behaviour on which virtfs 9p expects only one device to be
2799 shared with the same export, and if more than one device is shared and
2800 accessed via the same 9p export then only a warning message is logged
2801 (once) by qemu on host side. In order to avoid file ID collisions on guest
2802 you should either create a separate virtfs export for each device to be
2803 shared with guests (recommended way) or you might use "remap" instead which
2804 allows you to share multiple devices with only one export instead, which is
2805 achieved by remapping the original inode numbers from host to guest in a
2806 way that would prevent such collisions. Remapping inodes in such use cases
2807 is required because the original device IDs from host are never passed and
2808 exposed on guest. Instead all files of an export shared with virtfs always
2809 share the same device id on guest. So two files with identical inode
2810 numbers but from actually different devices on host would otherwise cause a
2811 file ID collision and hence potential misbehaviours on guest. "forbid" on
2812 the other hand assumes like "warn" that only one device is shared by the
2813 same export, however it will not only log a warning message but also
2814 deny access to additional devices on guest. Note though that "forbid" does
2815 currently not block all possible file access operations (e.g. readdir()
2816 would still return entries from other devices).
2817 @end table
2818 ETEXI
2819 SRST
2820 ``-virtfs local,path=path,mount_tag=mount_tag ,security_model=security_model[,writeout=writeout][,readonly] [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]``
2821   \ 
2822 ``-virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=writeout][,readonly]``
2823   \ 
2824 ``-virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=writeout][,readonly]``
2825   \
2826 ``-virtfs synth,mount_tag=mount_tag``
2827     Define a new filesystem device and expose it to the guest using a
2828     virtio-9p-device. The general form of a Virtual File system
2829     pass-through options are:
2830
2831     ``local``
2832         Accesses to the filesystem are done by QEMU.
2833
2834     ``proxy``
2835         Accesses to the filesystem are done by virtfs-proxy-helper(1).
2836
2837     ``synth``
2838         Synthetic filesystem, only used by QTests.
2839
2840     ``id=id``
2841         Specifies identifier for the filesystem device
2842
2843     ``path=path``
2844         Specifies the export path for the file system device. Files
2845         under this path will be available to the 9p client on the guest.
2846
2847     ``security_model=security_model``
2848         Specifies the security model to be used for this export path.
2849         Supported security models are "passthrough", "mapped-xattr",
2850         "mapped-file" and "none". In "passthrough" security model, files
2851         are stored using the same credentials as they are created on the
2852         guest. This requires QEMU to run as root. In "mapped-xattr"
2853         security model, some of the file attributes like uid, gid, mode
2854         bits and link target are stored as file attributes. For
2855         "mapped-file" these attributes are stored in the hidden
2856         .virtfs\_metadata directory. Directories exported by this
2857         security model cannot interact with other unix tools. "none"
2858         security model is same as passthrough except the sever won't
2859         report failures if it fails to set file attributes like
2860         ownership. Security model is mandatory only for local fsdriver.
2861         Other fsdrivers (like proxy) don't take security model as a
2862         parameter.
2863
2864     ``writeout=writeout``
2865         This is an optional argument. The only supported value is
2866         "immediate". This means that host page cache will be used to
2867         read and write data but write notification will be sent to the
2868         guest only when the data has been reported as written by the
2869         storage subsystem.
2870
2871     ``readonly``
2872         Enables exporting 9p share as a readonly mount for guests. By
2873         default read-write access is given.
2874
2875     ``socket=socket``
2876         Enables proxy filesystem driver to use passed socket file for
2877         communicating with virtfs-proxy-helper(1). Usually a helper like
2878         libvirt will create socketpair and pass one of the fds as
2879         sock\_fd.
2880
2881     ``sock_fd``
2882         Enables proxy filesystem driver to use passed 'sock\_fd' as the
2883         socket descriptor for interfacing with virtfs-proxy-helper(1).
2884
2885     ``fmode=fmode``
2886         Specifies the default mode for newly created files on the host.
2887         Works only with security models "mapped-xattr" and
2888         "mapped-file".
2889
2890     ``dmode=dmode``
2891         Specifies the default mode for newly created directories on the
2892         host. Works only with security models "mapped-xattr" and
2893         "mapped-file".
2894
2895     ``mount_tag=mount_tag``
2896         Specifies the tag name to be used by the guest to mount this
2897         export point.
2898
2899     ``multidevs=multidevs``
2900         Specifies how to deal with multiple devices being shared with a
2901         9p export. Supported behaviours are either "remap", "forbid" or
2902         "warn". The latter is the default behaviour on which virtfs 9p
2903         expects only one device to be shared with the same export, and
2904         if more than one device is shared and accessed via the same 9p
2905         export then only a warning message is logged (once) by qemu on
2906         host side. In order to avoid file ID collisions on guest you
2907         should either create a separate virtfs export for each device to
2908         be shared with guests (recommended way) or you might use "remap"
2909         instead which allows you to share multiple devices with only one
2910         export instead, which is achieved by remapping the original
2911         inode numbers from host to guest in a way that would prevent
2912         such collisions. Remapping inodes in such use cases is required
2913         because the original device IDs from host are never passed and
2914         exposed on guest. Instead all files of an export shared with
2915         virtfs always share the same device id on guest. So two files
2916         with identical inode numbers but from actually different devices
2917         on host would otherwise cause a file ID collision and hence
2918         potential misbehaviours on guest. "forbid" on the other hand
2919         assumes like "warn" that only one device is shared by the same
2920         export, however it will not only log a warning message but also
2921         deny access to additional devices on guest. Note though that
2922         "forbid" does currently not block all possible file access
2923         operations (e.g. readdir() would still return entries from other
2924         devices).
2925 ERST
2926
2927 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
2928     "-iscsi [user=user][,password=password]\n"
2929     "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
2930     "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
2931     "       [,timeout=timeout]\n"
2932     "                iSCSI session parameters\n", QEMU_ARCH_ALL)
2933
2934 STEXI
2935 @item -iscsi
2936 @findex -iscsi
2937 Configure iSCSI session parameters.
2938 ETEXI
2939 SRST
2940 ``-iscsi``
2941     Configure iSCSI session parameters.
2942 ERST
2943
2944 STEXI
2945 @end table
2946 ETEXI
2947 DEFHEADING()
2948
2949 DEFHEADING(USB options:)
2950 STEXI
2951 @table @option
2952 ETEXI
2953
2954 DEF("usb", 0, QEMU_OPTION_usb,
2955     "-usb            enable on-board USB host controller (if not enabled by default)\n",
2956     QEMU_ARCH_ALL)
2957 STEXI
2958 @item -usb
2959 @findex -usb
2960 Enable USB emulation on machine types with an on-board USB host controller (if
2961 not enabled by default).  Note that on-board USB host controllers may not
2962 support USB 3.0.  In this case @option{-device qemu-xhci} can be used instead
2963 on machines with PCI.
2964 ETEXI
2965 SRST
2966 ``-usb``
2967     Enable USB emulation on machine types with an on-board USB host
2968     controller (if not enabled by default). Note that on-board USB host
2969     controllers may not support USB 3.0. In this case
2970     ``-device qemu-xhci`` can be used instead on machines with PCI.
2971 ERST
2972
2973 DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
2974     "-usbdevice name add the host or guest USB device 'name'\n",
2975     QEMU_ARCH_ALL)
2976 STEXI
2977
2978 @item -usbdevice @var{devname}
2979 @findex -usbdevice
2980 Add the USB device @var{devname}. Note that this option is deprecated,
2981 please use @code{-device usb-...} instead. @xref{usb_devices}.
2982
2983 @table @option
2984
2985 @item mouse
2986 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
2987
2988 @item tablet
2989 Pointer device that uses absolute coordinates (like a touchscreen). This
2990 means QEMU is able to report the mouse position without having to grab the
2991 mouse. Also overrides the PS/2 mouse emulation when activated.
2992
2993 @item braille
2994 Braille device.  This will use BrlAPI to display the braille output on a real
2995 or fake device.
2996
2997 @end table
2998 ETEXI
2999 SRST
3000 ``-usbdevice devname``
3001     Add the USB device devname. Note that this option is deprecated,
3002     please use ``-device usb-...`` instead. See
3003     :ref:`usb_005fdevices`.
3004
3005     ``mouse``
3006         Virtual Mouse. This will override the PS/2 mouse emulation when
3007         activated.
3008
3009     ``tablet``
3010         Pointer device that uses absolute coordinates (like a
3011         touchscreen). This means QEMU is able to report the mouse
3012         position without having to grab the mouse. Also overrides the
3013         PS/2 mouse emulation when activated.
3014
3015     ``braille``
3016         Braille device. This will use BrlAPI to display the braille
3017         output on a real or fake device.
3018 ERST
3019
3020 STEXI
3021 @end table
3022 ETEXI
3023 DEFHEADING()
3024
3025 DEFHEADING(Display options:)
3026 STEXI
3027 @table @option
3028 ETEXI
3029
3030 DEF("display", HAS_ARG, QEMU_OPTION_display,
3031 #if defined(CONFIG_SPICE)
3032     "-display spice-app[,gl=on|off]\n"
3033 #endif
3034 #if defined(CONFIG_SDL)
3035     "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n"
3036     "            [,window_close=on|off][,gl=on|core|es|off]\n"
3037 #endif
3038 #if defined(CONFIG_GTK)
3039     "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
3040 #endif
3041 #if defined(CONFIG_VNC)
3042     "-display vnc=<display>[,<optargs>]\n"
3043 #endif
3044 #if defined(CONFIG_CURSES)
3045     "-display curses[,charset=<encoding>]\n"
3046 #endif
3047 #if defined(CONFIG_OPENGL)
3048     "-display egl-headless[,rendernode=<file>]\n"
3049 #endif
3050     "-display none\n"
3051     "                select display backend type\n"
3052     "                The default display is equivalent to\n                "
3053 #if defined(CONFIG_GTK)
3054             "\"-display gtk\"\n"
3055 #elif defined(CONFIG_SDL)
3056             "\"-display sdl\"\n"
3057 #elif defined(CONFIG_COCOA)
3058             "\"-display cocoa\"\n"
3059 #elif defined(CONFIG_VNC)
3060             "\"-vnc localhost:0,to=99,id=default\"\n"
3061 #else
3062             "\"-display none\"\n"
3063 #endif
3064     , QEMU_ARCH_ALL)
3065 STEXI
3066 @item -display @var{type}
3067 @findex -display
3068 Select type of display to use. This option is a replacement for the
3069 old style -sdl/-curses/... options. Use @code{-display help} to list
3070 the available display types. Valid values for @var{type} are
3071 @table @option
3072 @item sdl
3073 Display video output via SDL (usually in a separate graphics
3074 window; see the SDL documentation for other possibilities).
3075 @item curses
3076 Display video output via curses. For graphics device models which
3077 support a text mode, QEMU can display this output using a
3078 curses/ncurses interface. Nothing is displayed when the graphics
3079 device is in graphical mode or if the graphics device does not support
3080 a text mode. Generally only the VGA device models support text mode.
3081 The font charset used by the guest can be specified with the
3082 @code{charset} option, for example @code{charset=CP850} for IBM CP850
3083 encoding. The default is @code{CP437}.
3084 @item none
3085 Do not display video output. The guest will still see an emulated
3086 graphics card, but its output will not be displayed to the QEMU
3087 user. This option differs from the -nographic option in that it
3088 only affects what is done with video output; -nographic also changes
3089 the destination of the serial and parallel port data.
3090 @item gtk
3091 Display video output in a GTK window. This interface provides drop-down
3092 menus and other UI elements to configure and control the VM during
3093 runtime.
3094 @item vnc
3095 Start a VNC server on display <arg>
3096 @item egl-headless
3097 Offload all OpenGL operations to a local DRI device. For any graphical display,
3098 this display needs to be paired with either VNC or SPICE displays.
3099 @item spice-app
3100 Start QEMU as a Spice server and launch the default Spice client
3101 application. The Spice server will redirect the serial consoles and
3102 QEMU monitors. (Since 4.0)
3103 @end table
3104 ETEXI
3105 SRST
3106 ``-display type``
3107     Select type of display to use. This option is a replacement for the
3108     old style -sdl/-curses/... options. Use ``-display help`` to list
3109     the available display types. Valid values for type are
3110
3111     ``sdl``
3112         Display video output via SDL (usually in a separate graphics
3113         window; see the SDL documentation for other possibilities).
3114
3115     ``curses``
3116         Display video output via curses. For graphics device models
3117         which support a text mode, QEMU can display this output using a
3118         curses/ncurses interface. Nothing is displayed when the graphics
3119         device is in graphical mode or if the graphics device does not
3120         support a text mode. Generally only the VGA device models
3121         support text mode. The font charset used by the guest can be
3122         specified with the ``charset`` option, for example
3123         ``charset=CP850`` for IBM CP850 encoding. The default is
3124         ``CP437``.
3125
3126     ``none``
3127         Do not display video output. The guest will still see an
3128         emulated graphics card, but its output will not be displayed to
3129         the QEMU user. This option differs from the -nographic option in
3130         that it only affects what is done with video output; -nographic
3131         also changes the destination of the serial and parallel port
3132         data.
3133
3134     ``gtk``
3135         Display video output in a GTK window. This interface provides
3136         drop-down menus and other UI elements to configure and control
3137         the VM during runtime.
3138
3139     ``vnc``
3140         Start a VNC server on display <arg>
3141
3142     ``egl-headless``
3143         Offload all OpenGL operations to a local DRI device. For any
3144         graphical display, this display needs to be paired with either
3145         VNC or SPICE displays.
3146
3147     ``spice-app``
3148         Start QEMU as a Spice server and launch the default Spice client
3149         application. The Spice server will redirect the serial consoles
3150         and QEMU monitors. (Since 4.0)
3151 ERST
3152
3153 DEF("nographic", 0, QEMU_OPTION_nographic,
3154     "-nographic      disable graphical output and redirect serial I/Os to console\n",
3155     QEMU_ARCH_ALL)
3156 STEXI
3157 @item -nographic
3158 @findex -nographic
3159 Normally, if QEMU is compiled with graphical window support, it displays
3160 output such as guest graphics, guest console, and the QEMU monitor in a
3161 window. With this option, you can totally disable graphical output so
3162 that QEMU is a simple command line application. The emulated serial port
3163 is redirected on the console and muxed with the monitor (unless
3164 redirected elsewhere explicitly). Therefore, you can still use QEMU to
3165 debug a Linux kernel with a serial console. Use @key{C-a h} for help on
3166 switching between the console and monitor.
3167 ETEXI
3168 SRST
3169 ``-nographic``
3170     Normally, if QEMU is compiled with graphical window support, it
3171     displays output such as guest graphics, guest console, and the QEMU
3172     monitor in a window. With this option, you can totally disable
3173     graphical output so that QEMU is a simple command line application.
3174     The emulated serial port is redirected on the console and muxed with
3175     the monitor (unless redirected elsewhere explicitly). Therefore, you
3176     can still use QEMU to debug a Linux kernel with a serial console.
3177     Use C-a h for help on switching between the console and monitor.
3178 ERST
3179
3180 DEF("curses", 0, QEMU_OPTION_curses,
3181     "-curses         shorthand for -display curses\n",
3182     QEMU_ARCH_ALL)
3183 STEXI
3184 @item -curses
3185 @findex -curses
3186 Normally, if QEMU is compiled with graphical window support, it displays
3187 output such as guest graphics, guest console, and the QEMU monitor in a
3188 window. With this option, QEMU can display the VGA output when in text
3189 mode using a curses/ncurses interface. Nothing is displayed in graphical
3190 mode.
3191 ETEXI
3192 SRST
3193 ``-curses``
3194     Normally, if QEMU is compiled with graphical window support, it
3195     displays output such as guest graphics, guest console, and the QEMU
3196     monitor in a window. With this option, QEMU can display the VGA
3197     output when in text mode using a curses/ncurses interface. Nothing
3198     is displayed in graphical mode.
3199 ERST
3200
3201 DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
3202     "-alt-grab       use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
3203     QEMU_ARCH_ALL)
3204 STEXI
3205 @item -alt-grab
3206 @findex -alt-grab
3207 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
3208 affects the special keys (for fullscreen, monitor-mode switching, etc).
3209 ETEXI
3210 SRST
3211 ``-alt-grab``
3212     Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that
3213     this also affects the special keys (for fullscreen, monitor-mode
3214     switching, etc).
3215 ERST
3216
3217 DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
3218     "-ctrl-grab      use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
3219     QEMU_ARCH_ALL)
3220 STEXI
3221 @item -ctrl-grab
3222 @findex -ctrl-grab
3223 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
3224 affects the special keys (for fullscreen, monitor-mode switching, etc).
3225 ETEXI
3226 SRST
3227 ``-ctrl-grab``
3228     Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this
3229     also affects the special keys (for fullscreen, monitor-mode
3230     switching, etc).
3231 ERST
3232
3233 DEF("no-quit", 0, QEMU_OPTION_no_quit,
3234     "-no-quit        disable SDL window close capability\n", QEMU_ARCH_ALL)
3235 STEXI
3236 @item -no-quit
3237 @findex -no-quit
3238 Disable SDL window close capability.
3239 ETEXI
3240 SRST
3241 ``-no-quit``
3242     Disable SDL window close capability.
3243 ERST
3244
3245 DEF("sdl", 0, QEMU_OPTION_sdl,
3246     "-sdl            shorthand for -display sdl\n", QEMU_ARCH_ALL)
3247 STEXI
3248 @item -sdl
3249 @findex -sdl
3250 Enable SDL.
3251 ETEXI
3252 SRST
3253 ``-sdl``
3254     Enable SDL.
3255 ERST
3256
3257 DEF("spice", HAS_ARG, QEMU_OPTION_spice,
3258     "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
3259     "       [,x509-key-file=<file>][,x509-key-password=<file>]\n"
3260     "       [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
3261     "       [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n"
3262     "       [,tls-ciphers=<list>]\n"
3263     "       [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
3264     "       [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
3265     "       [,sasl][,password=<secret>][,disable-ticketing]\n"
3266     "       [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
3267     "       [,jpeg-wan-compression=[auto|never|always]]\n"
3268     "       [,zlib-glz-wan-compression=[auto|never|always]]\n"
3269     "       [,streaming-video=[off|all|filter]][,disable-copy-paste]\n"
3270     "       [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n"
3271     "       [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
3272     "       [,gl=[on|off]][,rendernode=<file>]\n"
3273     "   enable spice\n"
3274     "   at least one of {port, tls-port} is mandatory\n",
3275     QEMU_ARCH_ALL)
3276 STEXI
3277 @item -spice @var{option}[,@var{option}[,...]]
3278 @findex -spice
3279 Enable the spice remote desktop protocol. Valid options are
3280
3281 @table @option
3282
3283 @item port=<nr>
3284 Set the TCP port spice is listening on for plaintext channels.
3285
3286 @item addr=<addr>
3287 Set the IP address spice is listening on.  Default is any address.
3288
3289 @item ipv4
3290 @itemx ipv6
3291 @itemx unix
3292 Force using the specified IP version.
3293
3294 @item password=<secret>
3295 Set the password you need to authenticate.
3296
3297 @item sasl
3298 Require that the client use SASL to authenticate with the spice.
3299 The exact choice of authentication method used is controlled from the
3300 system / user's SASL configuration file for the 'qemu' service. This
3301 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
3302 unprivileged user, an environment variable SASL_CONF_PATH can be used
3303 to make it search alternate locations for the service config.
3304 While some SASL auth methods can also provide data encryption (eg GSSAPI),
3305 it is recommended that SASL always be combined with the 'tls' and
3306 'x509' settings to enable use of SSL and server certificates. This
3307 ensures a data encryption preventing compromise of authentication
3308 credentials.
3309
3310 @item disable-ticketing
3311 Allow client connects without authentication.
3312
3313 @item disable-copy-paste
3314 Disable copy paste between the client and the guest.
3315
3316 @item disable-agent-file-xfer
3317 Disable spice-vdagent based file-xfer between the client and the guest.
3318
3319 @item tls-port=<nr>
3320 Set the TCP port spice is listening on for encrypted channels.
3321
3322 @item x509-dir=<dir>
3323 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
3324
3325 @item x509-key-file=<file>
3326 @itemx x509-key-password=<file>
3327 @itemx x509-cert-file=<file>
3328 @itemx x509-cacert-file=<file>
3329 @itemx x509-dh-key-file=<file>
3330 The x509 file names can also be configured individually.
3331
3332 @item tls-ciphers=<list>
3333 Specify which ciphers to use.
3334
3335 @item tls-channel=[main|display|cursor|inputs|record|playback]
3336 @itemx plaintext-channel=[main|display|cursor|inputs|record|playback]
3337 Force specific channel to be used with or without TLS encryption.  The
3338 options can be specified multiple times to configure multiple
3339 channels.  The special name "default" can be used to set the default
3340 mode.  For channels which are not explicitly forced into one mode the
3341 spice client is allowed to pick tls/plaintext as he pleases.
3342
3343 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
3344 Configure image compression (lossless).
3345 Default is auto_glz.
3346
3347 @item jpeg-wan-compression=[auto|never|always]
3348 @itemx zlib-glz-wan-compression=[auto|never|always]
3349 Configure wan image compression (lossy for slow links).
3350 Default is auto.
3351
3352 @item streaming-video=[off|all|filter]
3353 Configure video stream detection.  Default is off.
3354
3355 @item agent-mouse=[on|off]
3356 Enable/disable passing mouse events via vdagent.  Default is on.
3357
3358 @item playback-compression=[on|off]
3359 Enable/disable audio stream compression (using celt 0.5.1).  Default is on.
3360
3361 @item seamless-migration=[on|off]
3362 Enable/disable spice seamless migration. Default is off.
3363
3364 @item gl=[on|off]
3365 Enable/disable OpenGL context. Default is off.
3366
3367 @item rendernode=<file>
3368 DRM render node for OpenGL rendering. If not specified, it will pick
3369 the first available. (Since 2.9)
3370
3371 @end table
3372 ETEXI
3373 SRST
3374 ``-spice option[,option[,...]]``
3375     Enable the spice remote desktop protocol. Valid options are
3376
3377     ``port=<nr>``
3378         Set the TCP port spice is listening on for plaintext channels.
3379
3380     ``addr=<addr>``
3381         Set the IP address spice is listening on. Default is any
3382         address.
3383
3384     ``ipv4``; \ ``ipv6``; \ ``unix``
3385         Force using the specified IP version.
3386
3387     ``password=<secret>``
3388         Set the password you need to authenticate.
3389
3390     ``sasl``
3391         Require that the client use SASL to authenticate with the spice.
3392         The exact choice of authentication method used is controlled
3393         from the system / user's SASL configuration file for the 'qemu'
3394         service. This is typically found in /etc/sasl2/qemu.conf. If
3395         running QEMU as an unprivileged user, an environment variable
3396         SASL\_CONF\_PATH can be used to make it search alternate
3397         locations for the service config. While some SASL auth methods
3398         can also provide data encryption (eg GSSAPI), it is recommended
3399         that SASL always be combined with the 'tls' and 'x509' settings
3400         to enable use of SSL and server certificates. This ensures a
3401         data encryption preventing compromise of authentication
3402         credentials.
3403
3404     ``disable-ticketing``
3405         Allow client connects without authentication.
3406
3407     ``disable-copy-paste``
3408         Disable copy paste between the client and the guest.
3409
3410     ``disable-agent-file-xfer``
3411         Disable spice-vdagent based file-xfer between the client and the
3412         guest.
3413
3414     ``tls-port=<nr>``
3415         Set the TCP port spice is listening on for encrypted channels.
3416
3417     ``x509-dir=<dir>``
3418         Set the x509 file directory. Expects same filenames as -vnc
3419         $display,x509=$dir
3420
3421     ``x509-key-file=<file>``; \ ``x509-key-password=<file>``; \ ``x509-cert-file=<file>``; \ ``x509-cacert-file=<file>``; \ ``x509-dh-key-file=<file>``
3422         The x509 file names can also be configured individually.
3423
3424     ``tls-ciphers=<list>``
3425         Specify which ciphers to use.
3426
3427     ``tls-channel=[main|display|cursor|inputs|record|playback]``; \ ``plaintext-channel=[main|display|cursor|inputs|record|playback]``
3428         Force specific channel to be used with or without TLS
3429         encryption. The options can be specified multiple times to
3430         configure multiple channels. The special name "default" can be
3431         used to set the default mode. For channels which are not
3432         explicitly forced into one mode the spice client is allowed to
3433         pick tls/plaintext as he pleases.
3434
3435     ``image-compression=[auto_glz|auto_lz|quic|glz|lz|off]``
3436         Configure image compression (lossless). Default is auto\_glz.
3437
3438     ``jpeg-wan-compression=[auto|never|always]``; \ ``zlib-glz-wan-compression=[auto|never|always]``
3439         Configure wan image compression (lossy for slow links). Default
3440         is auto.
3441
3442     ``streaming-video=[off|all|filter]``
3443         Configure video stream detection. Default is off.
3444
3445     ``agent-mouse=[on|off]``
3446         Enable/disable passing mouse events via vdagent. Default is on.
3447
3448     ``playback-compression=[on|off]``
3449         Enable/disable audio stream compression (using celt 0.5.1).
3450         Default is on.
3451
3452     ``seamless-migration=[on|off]``
3453         Enable/disable spice seamless migration. Default is off.
3454
3455     ``gl=[on|off]``
3456         Enable/disable OpenGL context. Default is off.
3457
3458     ``rendernode=<file>``
3459         DRM render node for OpenGL rendering. If not specified, it will
3460         pick the first available. (Since 2.9)
3461 ERST
3462
3463 DEF("portrait", 0, QEMU_OPTION_portrait,
3464     "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n",
3465     QEMU_ARCH_ALL)
3466 STEXI
3467 @item -portrait
3468 @findex -portrait
3469 Rotate graphical output 90 deg left (only PXA LCD).
3470 ETEXI
3471 SRST
3472 ``-portrait``
3473     Rotate graphical output 90 deg left (only PXA LCD).
3474 ERST
3475
3476 DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
3477     "-rotate <deg>   rotate graphical output some deg left (only PXA LCD)\n",
3478     QEMU_ARCH_ALL)
3479 STEXI
3480 @item -rotate @var{deg}
3481 @findex -rotate
3482 Rotate graphical output some deg left (only PXA LCD).
3483 ETEXI
3484 SRST
3485 ``-rotate deg``
3486     Rotate graphical output some deg left (only PXA LCD).
3487 ERST
3488
3489 DEF("vga", HAS_ARG, QEMU_OPTION_vga,
3490     "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
3491     "                select video card type\n", QEMU_ARCH_ALL)
3492 STEXI
3493 @item -vga @var{type}
3494 @findex -vga
3495 Select type of VGA card to emulate. Valid values for @var{type} are
3496 @table @option
3497 @item cirrus
3498 Cirrus Logic GD5446 Video card. All Windows versions starting from
3499 Windows 95 should recognize and use this graphic card. For optimal
3500 performances, use 16 bit color depth in the guest and the host OS.
3501 (This card was the default before QEMU 2.2)
3502 @item std
3503 Standard VGA card with Bochs VBE extensions.  If your guest OS
3504 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
3505 to use high resolution modes (>= 1280x1024x16) then you should use
3506 this option. (This card is the default since QEMU 2.2)
3507 @item vmware
3508 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
3509 recent XFree86/XOrg server or Windows guest with a driver for this
3510 card.
3511 @item qxl
3512 QXL paravirtual graphic card.  It is VGA compatible (including VESA
3513 2.0 VBE support).  Works best with qxl guest drivers installed though.
3514 Recommended choice when using the spice protocol.
3515 @item tcx
3516 (sun4m only) Sun TCX framebuffer. This is the default framebuffer for
3517 sun4m machines and offers both 8-bit and 24-bit colour depths at a
3518 fixed resolution of 1024x768.
3519 @item cg3
3520 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer
3521 for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP)
3522 resolutions aimed at people wishing to run older Solaris versions.
3523 @item virtio
3524 Virtio VGA card.
3525 @item none
3526 Disable VGA card.
3527 @end table
3528 ETEXI
3529 SRST
3530 ``-vga type``
3531     Select type of VGA card to emulate. Valid values for type are
3532
3533     ``cirrus``
3534         Cirrus Logic GD5446 Video card. All Windows versions starting
3535         from Windows 95 should recognize and use this graphic card. For
3536         optimal performances, use 16 bit color depth in the guest and
3537         the host OS. (This card was the default before QEMU 2.2)
3538
3539     ``std``
3540         Standard VGA card with Bochs VBE extensions. If your guest OS
3541         supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if
3542         you want to use high resolution modes (>= 1280x1024x16) then you
3543         should use this option. (This card is the default since QEMU
3544         2.2)
3545
3546     ``vmware``
3547         VMWare SVGA-II compatible adapter. Use it if you have
3548         sufficiently recent XFree86/XOrg server or Windows guest with a
3549         driver for this card.
3550
3551     ``qxl``
3552         QXL paravirtual graphic card. It is VGA compatible (including
3553         VESA 2.0 VBE support). Works best with qxl guest drivers
3554         installed though. Recommended choice when using the spice
3555         protocol.
3556
3557     ``tcx``
3558         (sun4m only) Sun TCX framebuffer. This is the default
3559         framebuffer for sun4m machines and offers both 8-bit and 24-bit
3560         colour depths at a fixed resolution of 1024x768.
3561
3562     ``cg3``
3563         (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit
3564         framebuffer for sun4m machines available in both 1024x768
3565         (OpenBIOS) and 1152x900 (OBP) resolutions aimed at people
3566         wishing to run older Solaris versions.
3567
3568     ``virtio``
3569         Virtio VGA card.
3570
3571     ``none``
3572         Disable VGA card.
3573 ERST
3574
3575 DEF("full-screen", 0, QEMU_OPTION_full_screen,
3576     "-full-screen    start in full screen\n", QEMU_ARCH_ALL)
3577 STEXI
3578 @item -full-screen
3579 @findex -full-screen
3580 Start in full screen.
3581 ETEXI
3582 SRST
3583 ``-full-screen``
3584     Start in full screen.
3585 ERST
3586
3587 DEF("g", HAS_ARG, QEMU_OPTION_g ,
3588     "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n",
3589     QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K)
3590 STEXI
3591 @item -g @var{width}x@var{height}[x@var{depth}]
3592 @findex -g
3593 Set the initial graphical resolution and depth (PPC, SPARC only).
3594
3595 For PPC the default is 800x600x32.
3596
3597 For SPARC with the TCX graphics device, the default is 1024x768x8 with the
3598 option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
3599 of 1152x900x8 for people who wish to use OBP.
3600
3601 ETEXI
3602 SRST
3603 ``-g`` *width*\ ``x``\ *height*\ ``[x``\ *depth*\ ``]``
3604     Set the initial graphical resolution and depth (PPC, SPARC only).
3605
3606     For PPC the default is 800x600x32.
3607
3608     For SPARC with the TCX graphics device, the default is 1024x768x8
3609     with the option of 1024x768x24. For cgthree, the default is
3610     1024x768x8 with the option of 1152x900x8 for people who wish to use
3611     OBP.
3612 ERST
3613
3614 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
3615     "-vnc <display>  shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
3616 STEXI
3617 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
3618 @findex -vnc
3619 Normally, if QEMU is compiled with graphical window support, it displays
3620 output such as guest graphics, guest console, and the QEMU monitor in a
3621 window. With this option, you can have QEMU listen on VNC display
3622 @var{display} and redirect the VGA display over the VNC session. It is
3623 very useful to enable the usb tablet device when using this option
3624 (option @option{-device usb-tablet}). When using the VNC display, you
3625 must use the @option{-k} parameter to set the keyboard layout if you are
3626 not using en-us. Valid syntax for the @var{display} is
3627
3628 @table @option
3629
3630 @item to=@var{L}
3631
3632 With this option, QEMU will try next available VNC @var{display}s, until the
3633 number @var{L}, if the origianlly defined "-vnc @var{display}" is not
3634 available, e.g. port 5900+@var{display} is already used by another
3635 application. By default, to=0.
3636
3637 @item @var{host}:@var{d}
3638
3639 TCP connections will only be allowed from @var{host} on display @var{d}.
3640 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
3641 be omitted in which case the server will accept connections from any host.
3642
3643 @item unix:@var{path}
3644
3645 Connections will be allowed over UNIX domain sockets where @var{path} is the
3646 location of a unix socket to listen for connections on.
3647
3648 @item none
3649
3650 VNC is initialized but not started. The monitor @code{change} command
3651 can be used to later start the VNC server.
3652
3653 @end table
3654
3655 Following the @var{display} value there may be one or more @var{option} flags
3656 separated by commas. Valid options are
3657
3658 @table @option
3659
3660 @item reverse
3661
3662 Connect to a listening VNC client via a ``reverse'' connection. The
3663 client is specified by the @var{display}. For reverse network
3664 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
3665 is a TCP port number, not a display number.
3666
3667 @item websocket
3668
3669 Opens an additional TCP listening port dedicated to VNC Websocket connections.
3670 If a bare @var{websocket} option is given, the Websocket port is
3671 5700+@var{display}. An alternative port can be specified with the
3672 syntax @code{websocket}=@var{port}.
3673
3674 If @var{host} is specified connections will only be allowed from this host.
3675 It is possible to control the websocket listen address independently, using
3676 the syntax @code{websocket}=@var{host}:@var{port}.
3677
3678 If no TLS credentials are provided, the websocket connection runs in
3679 unencrypted mode. If TLS credentials are provided, the websocket connection
3680 requires encrypted client connections.
3681
3682 @item password
3683
3684 Require that password based authentication is used for client connections.
3685
3686 The password must be set separately using the @code{set_password} command in
3687 the @ref{pcsys_monitor}. The syntax to change your password is:
3688 @code{set_password <protocol> <password>} where <protocol> could be either
3689 "vnc" or "spice".
3690
3691 If you would like to change <protocol> password expiration, you should use
3692 @code{expire_password <protocol> <expiration-time>} where expiration time could
3693 be one of the following options: now, never, +seconds or UNIX time of
3694 expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800
3695 to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
3696 date and time).
3697
3698 You can also use keywords "now" or "never" for the expiration time to
3699 allow <protocol> password to expire immediately or never expire.
3700
3701 @item tls-creds=@var{ID}
3702
3703 Provides the ID of a set of TLS credentials to use to secure the
3704 VNC server. They will apply to both the normal VNC server socket
3705 and the websocket socket (if enabled). Setting TLS credentials
3706 will cause the VNC server socket to enable the VeNCrypt auth
3707 mechanism.  The credentials should have been previously created
3708 using the @option{-object tls-creds} argument.
3709
3710 @item tls-authz=@var{ID}
3711
3712 Provides the ID of the QAuthZ authorization object against which
3713 the client's x509 distinguished name will validated. This object is
3714 only resolved at time of use, so can be deleted and recreated on the
3715 fly while the VNC server is active. If missing, it will default
3716 to denying access.
3717
3718 @item sasl
3719
3720 Require that the client use SASL to authenticate with the VNC server.
3721 The exact choice of authentication method used is controlled from the
3722 system / user's SASL configuration file for the 'qemu' service. This
3723 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
3724 unprivileged user, an environment variable SASL_CONF_PATH can be used
3725 to make it search alternate locations for the service config.
3726 While some SASL auth methods can also provide data encryption (eg GSSAPI),
3727 it is recommended that SASL always be combined with the 'tls' and
3728 'x509' settings to enable use of SSL and server certificates. This
3729 ensures a data encryption preventing compromise of authentication
3730 credentials. See the @ref{vnc_security} section for details on using
3731 SASL authentication.
3732
3733 @item sasl-authz=@var{ID}
3734
3735 Provides the ID of the QAuthZ authorization object against which
3736 the client's SASL username will validated. This object is
3737 only resolved at time of use, so can be deleted and recreated on the
3738 fly while the VNC server is active. If missing, it will default
3739 to denying access.
3740
3741 @item acl
3742
3743 Legacy method for enabling authorization of clients against the
3744 x509 distinguished name and SASL username. It results in the creation
3745 of two @code{authz-list} objects with IDs of @code{vnc.username} and
3746 @code{vnc.x509dname}. The rules for these objects must be configured
3747 with the HMP ACL commands.
3748
3749 This option is deprecated and should no longer be used. The new
3750 @option{sasl-authz} and @option{tls-authz} options are a
3751 replacement.
3752
3753 @item lossy
3754
3755 Enable lossy compression methods (gradient, JPEG, ...). If this
3756 option is set, VNC client may receive lossy framebuffer updates
3757 depending on its encoding settings. Enabling this option can save
3758 a lot of bandwidth at the expense of quality.
3759
3760 @item non-adaptive
3761
3762 Disable adaptive encodings. Adaptive encodings are enabled by default.
3763 An adaptive encoding will try to detect frequently updated screen regions,
3764 and send updates in these regions using a lossy encoding (like JPEG).
3765 This can be really helpful to save bandwidth when playing videos. Disabling
3766 adaptive encodings restores the original static behavior of encodings
3767 like Tight.
3768
3769 @item share=[allow-exclusive|force-shared|ignore]
3770
3771 Set display sharing policy.  'allow-exclusive' allows clients to ask
3772 for exclusive access.  As suggested by the rfb spec this is
3773 implemented by dropping other connections.  Connecting multiple
3774 clients in parallel requires all clients asking for a shared session
3775 (vncviewer: -shared switch).  This is the default.  'force-shared'
3776 disables exclusive client access.  Useful for shared desktop sessions,
3777 where you don't want someone forgetting specify -shared disconnect
3778 everybody else.  'ignore' completely ignores the shared flag and