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