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