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