Merge tag 'pull-testing-gdbstub-plugins-gitdm-061022-3' of https://github.com/stsquad...
[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("pflash", HAS_ARG, QEMU_OPTION_pflash,
1589     "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
1590 SRST
1591 ``-pflash file``
1592     Use file as a parallel flash image.
1593 ERST
1594
1595 DEF("snapshot", 0, QEMU_OPTION_snapshot,
1596     "-snapshot       write to temporary files instead of disk image files\n",
1597     QEMU_ARCH_ALL)
1598 SRST
1599 ``-snapshot``
1600     Write to temporary files instead of disk image files. In this case,
1601     the raw disk image you use is not written back. You can however
1602     force the write back by pressing C-a s (see the :ref:`disk images`
1603     chapter in the System Emulation Users Guide).
1604 ERST
1605
1606 DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
1607     "-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none\n"
1608     " [,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode]\n"
1609     " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n"
1610     " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n"
1611     " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n"
1612     " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n"
1613     " [[,throttling.iops-size=is]]\n"
1614     "-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly=on]\n"
1615     "-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly=on]\n"
1616     "-fsdev synth,id=id\n",
1617     QEMU_ARCH_ALL)
1618
1619 SRST
1620 ``-fsdev local,id=id,path=path,security_model=security_model [,writeout=writeout][,readonly=on][,fmode=fmode][,dmode=dmode] [,throttling.option=value[,throttling.option=value[,...]]]``
1621   \ 
1622 ``-fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly=on]``
1623   \
1624 ``-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly=on]``
1625   \
1626 ``-fsdev synth,id=id[,readonly=on]``
1627     Define a new file system device. Valid options are:
1628
1629     ``local``
1630         Accesses to the filesystem are done by QEMU.
1631
1632     ``proxy``
1633         Accesses to the filesystem are done by virtfs-proxy-helper(1).
1634
1635     ``synth``
1636         Synthetic filesystem, only used by QTests.
1637
1638     ``id=id``
1639         Specifies identifier for this device.
1640
1641     ``path=path``
1642         Specifies the export path for the file system device. Files
1643         under this path will be available to the 9p client on the guest.
1644
1645     ``security_model=security_model``
1646         Specifies the security model to be used for this export path.
1647         Supported security models are "passthrough", "mapped-xattr",
1648         "mapped-file" and "none". In "passthrough" security model, files
1649         are stored using the same credentials as they are created on the
1650         guest. This requires QEMU to run as root. In "mapped-xattr"
1651         security model, some of the file attributes like uid, gid, mode
1652         bits and link target are stored as file attributes. For
1653         "mapped-file" these attributes are stored in the hidden
1654         .virtfs\_metadata directory. Directories exported by this
1655         security model cannot interact with other unix tools. "none"
1656         security model is same as passthrough except the sever won't
1657         report failures if it fails to set file attributes like
1658         ownership. Security model is mandatory only for local fsdriver.
1659         Other fsdrivers (like proxy) don't take security model as a
1660         parameter.
1661
1662     ``writeout=writeout``
1663         This is an optional argument. The only supported value is
1664         "immediate". This means that host page cache will be used to
1665         read and write data but write notification will be sent to the
1666         guest only when the data has been reported as written by the
1667         storage subsystem.
1668
1669     ``readonly=on``
1670         Enables exporting 9p share as a readonly mount for guests. By
1671         default read-write access is given.
1672
1673     ``socket=socket``
1674         Enables proxy filesystem driver to use passed socket file for
1675         communicating with virtfs-proxy-helper(1).
1676
1677     ``sock_fd=sock_fd``
1678         Enables proxy filesystem driver to use passed socket descriptor
1679         for communicating with virtfs-proxy-helper(1). Usually a helper
1680         like libvirt will create socketpair and pass one of the fds as
1681         sock\_fd.
1682
1683     ``fmode=fmode``
1684         Specifies the default mode for newly created files on the host.
1685         Works only with security models "mapped-xattr" and
1686         "mapped-file".
1687
1688     ``dmode=dmode``
1689         Specifies the default mode for newly created directories on the
1690         host. Works only with security models "mapped-xattr" and
1691         "mapped-file".
1692
1693     ``throttling.bps-total=b,throttling.bps-read=r,throttling.bps-write=w``
1694         Specify bandwidth throttling limits in bytes per second, either
1695         for all request types or for reads or writes only.
1696
1697     ``throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm``
1698         Specify bursts in bytes per second, either for all request types
1699         or for reads or writes only. Bursts allow the guest I/O to spike
1700         above the limit temporarily.
1701
1702     ``throttling.iops-total=i,throttling.iops-read=r, throttling.iops-write=w``
1703         Specify request rate limits in requests per second, either for
1704         all request types or for reads or writes only.
1705
1706     ``throttling.iops-total-max=im,throttling.iops-read-max=irm, throttling.iops-write-max=iwm``
1707         Specify bursts in requests per second, either for all request
1708         types or for reads or writes only. Bursts allow the guest I/O to
1709         spike above the limit temporarily.
1710
1711     ``throttling.iops-size=is``
1712         Let every is bytes of a request count as a new request for iops
1713         throttling purposes.
1714
1715     -fsdev option is used along with -device driver "virtio-9p-...".
1716
1717 ``-device virtio-9p-type,fsdev=id,mount_tag=mount_tag``
1718     Options for virtio-9p-... driver are:
1719
1720     ``type``
1721         Specifies the variant to be used. Supported values are "pci",
1722         "ccw" or "device", depending on the machine type.
1723
1724     ``fsdev=id``
1725         Specifies the id value specified along with -fsdev option.
1726
1727     ``mount_tag=mount_tag``
1728         Specifies the tag name to be used by the guest to mount this
1729         export point.
1730 ERST
1731
1732 DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
1733     "-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none\n"
1734     "        [,id=id][,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]\n"
1735     "-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly=on]\n"
1736     "-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly=on]\n"
1737     "-virtfs synth,mount_tag=tag[,id=id][,readonly=on]\n",
1738     QEMU_ARCH_ALL)
1739
1740 SRST
1741 ``-virtfs local,path=path,mount_tag=mount_tag ,security_model=security_model[,writeout=writeout][,readonly=on] [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]``
1742   \ 
1743 ``-virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=writeout][,readonly=on]``
1744   \ 
1745 ``-virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=writeout][,readonly=on]``
1746   \
1747 ``-virtfs synth,mount_tag=mount_tag``
1748     Define a new virtual filesystem device and expose it to the guest using
1749     a virtio-9p-device (a.k.a. 9pfs), which essentially means that a certain
1750     directory on host is made directly accessible by guest as a pass-through
1751     file system by using the 9P network protocol for communication between
1752     host and guests, if desired even accessible, shared by several guests
1753     simultaniously.
1754
1755     Note that ``-virtfs`` is actually just a convenience shortcut for its
1756     generalized form ``-fsdev -device virtio-9p-pci``.
1757
1758     The general form of pass-through file system options are:
1759
1760     ``local``
1761         Accesses to the filesystem are done by QEMU.
1762
1763     ``proxy``
1764         Accesses to the filesystem are done by virtfs-proxy-helper(1).
1765
1766     ``synth``
1767         Synthetic filesystem, only used by QTests.
1768
1769     ``id=id``
1770         Specifies identifier for the filesystem device
1771
1772     ``path=path``
1773         Specifies the export path for the file system device. Files
1774         under this path will be available to the 9p client on the guest.
1775
1776     ``security_model=security_model``
1777         Specifies the security model to be used for this export path.
1778         Supported security models are "passthrough", "mapped-xattr",
1779         "mapped-file" and "none". In "passthrough" security model, files
1780         are stored using the same credentials as they are created on the
1781         guest. This requires QEMU to run as root. In "mapped-xattr"
1782         security model, some of the file attributes like uid, gid, mode
1783         bits and link target are stored as file attributes. For
1784         "mapped-file" these attributes are stored in the hidden
1785         .virtfs\_metadata directory. Directories exported by this
1786         security model cannot interact with other unix tools. "none"
1787         security model is same as passthrough except the sever won't
1788         report failures if it fails to set file attributes like
1789         ownership. Security model is mandatory only for local fsdriver.
1790         Other fsdrivers (like proxy) don't take security model as a
1791         parameter.
1792
1793     ``writeout=writeout``
1794         This is an optional argument. The only supported value is
1795         "immediate". This means that host page cache will be used to
1796         read and write data but write notification will be sent to the
1797         guest only when the data has been reported as written by the
1798         storage subsystem.
1799
1800     ``readonly=on``
1801         Enables exporting 9p share as a readonly mount for guests. By
1802         default read-write access is given.
1803
1804     ``socket=socket``
1805         Enables proxy filesystem driver to use passed socket file for
1806         communicating with virtfs-proxy-helper(1). Usually a helper like
1807         libvirt will create socketpair and pass one of the fds as
1808         sock\_fd.
1809
1810     ``sock_fd``
1811         Enables proxy filesystem driver to use passed 'sock\_fd' as the
1812         socket descriptor for interfacing with virtfs-proxy-helper(1).
1813
1814     ``fmode=fmode``
1815         Specifies the default mode for newly created files on the host.
1816         Works only with security models "mapped-xattr" and
1817         "mapped-file".
1818
1819     ``dmode=dmode``
1820         Specifies the default mode for newly created directories on the
1821         host. Works only with security models "mapped-xattr" and
1822         "mapped-file".
1823
1824     ``mount_tag=mount_tag``
1825         Specifies the tag name to be used by the guest to mount this
1826         export point.
1827
1828     ``multidevs=multidevs``
1829         Specifies how to deal with multiple devices being shared with a
1830         9p export. Supported behaviours are either "remap", "forbid" or
1831         "warn". The latter is the default behaviour on which virtfs 9p
1832         expects only one device to be shared with the same export, and
1833         if more than one device is shared and accessed via the same 9p
1834         export then only a warning message is logged (once) by qemu on
1835         host side. In order to avoid file ID collisions on guest you
1836         should either create a separate virtfs export for each device to
1837         be shared with guests (recommended way) or you might use "remap"
1838         instead which allows you to share multiple devices with only one
1839         export instead, which is achieved by remapping the original
1840         inode numbers from host to guest in a way that would prevent
1841         such collisions. Remapping inodes in such use cases is required
1842         because the original device IDs from host are never passed and
1843         exposed on guest. Instead all files of an export shared with
1844         virtfs always share the same device id on guest. So two files
1845         with identical inode numbers but from actually different devices
1846         on host would otherwise cause a file ID collision and hence
1847         potential misbehaviours on guest. "forbid" on the other hand
1848         assumes like "warn" that only one device is shared by the same
1849         export, however it will not only log a warning message but also
1850         deny access to additional devices on guest. Note though that
1851         "forbid" does currently not block all possible file access
1852         operations (e.g. readdir() would still return entries from other
1853         devices).
1854 ERST
1855
1856 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1857     "-iscsi [user=user][,password=password]\n"
1858     "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
1859     "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
1860     "       [,timeout=timeout]\n"
1861     "                iSCSI session parameters\n", QEMU_ARCH_ALL)
1862
1863 SRST
1864 ``-iscsi``
1865     Configure iSCSI session parameters.
1866 ERST
1867
1868 DEFHEADING()
1869
1870 DEFHEADING(USB convenience options:)
1871
1872 DEF("usb", 0, QEMU_OPTION_usb,
1873     "-usb            enable on-board USB host controller (if not enabled by default)\n",
1874     QEMU_ARCH_ALL)
1875 SRST
1876 ``-usb``
1877     Enable USB emulation on machine types with an on-board USB host
1878     controller (if not enabled by default). Note that on-board USB host
1879     controllers may not support USB 3.0. In this case
1880     ``-device qemu-xhci`` can be used instead on machines with PCI.
1881 ERST
1882
1883 DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
1884     "-usbdevice name add the host or guest USB device 'name'\n",
1885     QEMU_ARCH_ALL)
1886 SRST
1887 ``-usbdevice devname``
1888     Add the USB device devname, and enable an on-board USB controller
1889     if possible and necessary (just like it can be done via
1890     ``-machine usb=on``). Note that this option is mainly intended for
1891     the user's convenience only. More fine-grained control can be
1892     achieved by selecting a USB host controller (if necessary) and the
1893     desired USB device via the ``-device`` option instead. For example,
1894     instead of using ``-usbdevice mouse`` it is possible to use
1895     ``-device qemu-xhci -device usb-mouse`` to connect the USB mouse
1896     to a USB 3.0 controller instead (at least on machines that support
1897     PCI and do not have an USB controller enabled by default yet).
1898     For more details, see the chapter about
1899     :ref:`Connecting USB devices` in the System Emulation Users Guide.
1900     Possible devices for devname are:
1901
1902     ``braille``
1903         Braille device. This will use BrlAPI to display the braille
1904         output on a real or fake device (i.e. it also creates a
1905         corresponding ``braille`` chardev automatically beside the
1906         ``usb-braille`` USB device).
1907
1908     ``keyboard``
1909         Standard USB keyboard. Will override the PS/2 keyboard (if present).
1910
1911     ``mouse``
1912         Virtual Mouse. This will override the PS/2 mouse emulation when
1913         activated.
1914
1915     ``tablet``
1916         Pointer device that uses absolute coordinates (like a
1917         touchscreen). This means QEMU is able to report the mouse
1918         position without having to grab the mouse. Also overrides the
1919         PS/2 mouse emulation when activated.
1920
1921     ``wacom-tablet``
1922         Wacom PenPartner USB tablet.
1923
1924
1925 ERST
1926
1927 DEFHEADING()
1928
1929 DEFHEADING(Display options:)
1930
1931 DEF("display", HAS_ARG, QEMU_OPTION_display,
1932 #if defined(CONFIG_SPICE)
1933     "-display spice-app[,gl=on|off]\n"
1934 #endif
1935 #if defined(CONFIG_SDL)
1936     "-display sdl[,gl=on|core|es|off][,grab-mod=<mod>][,show-cursor=on|off]\n"
1937     "            [,window-close=on|off]\n"
1938 #endif
1939 #if defined(CONFIG_GTK)
1940     "-display gtk[,full-screen=on|off][,gl=on|off][,grab-on-hover=on|off]\n"
1941     "            [,show-cursor=on|off][,window-close=on|off]\n"
1942 #endif
1943 #if defined(CONFIG_VNC)
1944     "-display vnc=<display>[,<optargs>]\n"
1945 #endif
1946 #if defined(CONFIG_CURSES)
1947     "-display curses[,charset=<encoding>]\n"
1948 #endif
1949 #if defined(CONFIG_COCOA)
1950     "-display cocoa[,full-grab=on|off][,swap-opt-cmd=on|off]\n"
1951 #endif
1952 #if defined(CONFIG_OPENGL)
1953     "-display egl-headless[,rendernode=<file>]\n"
1954 #endif
1955 #if defined(CONFIG_DBUS_DISPLAY)
1956     "-display dbus[,addr=<dbusaddr>]\n"
1957     "             [,gl=on|core|es|off][,rendernode=<file>]\n"
1958 #endif
1959 #if defined(CONFIG_COCOA)
1960     "-display cocoa[,show-cursor=on|off][,left-command-key=on|off]\n"
1961 #endif
1962     "-display none\n"
1963     "                select display backend type\n"
1964     "                The default display is equivalent to\n                "
1965 #if defined(CONFIG_GTK)
1966             "\"-display gtk\"\n"
1967 #elif defined(CONFIG_SDL)
1968             "\"-display sdl\"\n"
1969 #elif defined(CONFIG_COCOA)
1970             "\"-display cocoa\"\n"
1971 #elif defined(CONFIG_VNC)
1972             "\"-vnc localhost:0,to=99,id=default\"\n"
1973 #else
1974             "\"-display none\"\n"
1975 #endif
1976     , QEMU_ARCH_ALL)
1977 SRST
1978 ``-display type``
1979     Select type of display to use. Use ``-display help`` to list the available
1980     display types. Valid values for type are
1981
1982     ``spice-app[,gl=on|off]``
1983         Start QEMU as a Spice server and launch the default Spice client
1984         application. The Spice server will redirect the serial consoles
1985         and QEMU monitors. (Since 4.0)
1986
1987     ``dbus``
1988         Export the display over D-Bus interfaces. (Since 7.0)
1989
1990         The connection is registered with the "org.qemu" name (and queued when
1991         already owned).
1992
1993         ``addr=<dbusaddr>`` : D-Bus bus address to connect to.
1994
1995         ``p2p=yes|no`` : Use peer-to-peer connection, accepted via QMP ``add_client``.
1996
1997         ``gl=on|off|core|es`` : Use OpenGL for rendering (the D-Bus interface
1998         will share framebuffers with DMABUF file descriptors).
1999
2000     ``sdl``
2001         Display video output via SDL (usually in a separate graphics
2002         window; see the SDL documentation for other possibilities).
2003         Valid parameters are:
2004
2005         ``grab-mod=<mods>`` : Used to select the modifier keys for toggling
2006         the mouse grabbing in conjunction with the "g" key. ``<mods>`` can be
2007         either ``lshift-lctrl-lalt`` or ``rctrl``.
2008
2009         ``gl=on|off|core|es`` : Use OpenGL for displaying
2010
2011         ``show-cursor=on|off`` :  Force showing the mouse cursor
2012
2013         ``window-close=on|off`` : Allow to quit qemu with window close button
2014
2015     ``gtk``
2016         Display video output in a GTK window. This interface provides
2017         drop-down menus and other UI elements to configure and control
2018         the VM during runtime. Valid parameters are:
2019
2020         ``full-screen=on|off`` : Start in fullscreen mode
2021
2022         ``gl=on|off`` : Use OpenGL for displaying
2023
2024         ``grab-on-hover=on|off`` : Grab keyboard input on mouse hover
2025
2026         ``show-cursor=on|off`` :  Force showing the mouse cursor
2027
2028         ``window-close=on|off`` : Allow to quit qemu with window close button
2029
2030     ``curses[,charset=<encoding>]``
2031         Display video output via curses. For graphics device models
2032         which support a text mode, QEMU can display this output using a
2033         curses/ncurses interface. Nothing is displayed when the graphics
2034         device is in graphical mode or if the graphics device does not
2035         support a text mode. Generally only the VGA device models
2036         support text mode. The font charset used by the guest can be
2037         specified with the ``charset`` option, for example
2038         ``charset=CP850`` for IBM CP850 encoding. The default is
2039         ``CP437``.
2040
2041     ``cocoa``
2042         Display video output in a Cocoa window. Mac only. This interface
2043         provides drop-down menus and other UI elements to configure and
2044         control the VM during runtime. Valid parameters are:
2045
2046         ``show-cursor=on|off`` :  Force showing the mouse cursor
2047
2048         ``left-command-key=on|off`` : Disable forwarding left command key to host
2049
2050     ``egl-headless[,rendernode=<file>]``
2051         Offload all OpenGL operations to a local DRI device. For any
2052         graphical display, this display needs to be paired with either
2053         VNC or SPICE displays.
2054
2055     ``vnc=<display>``
2056         Start a VNC server on display <display>
2057
2058     ``none``
2059         Do not display video output. The guest will still see an
2060         emulated graphics card, but its output will not be displayed to
2061         the QEMU user. This option differs from the -nographic option in
2062         that it only affects what is done with video output; -nographic
2063         also changes the destination of the serial and parallel port
2064         data.
2065 ERST
2066
2067 DEF("nographic", 0, QEMU_OPTION_nographic,
2068     "-nographic      disable graphical output and redirect serial I/Os to console\n",
2069     QEMU_ARCH_ALL)
2070 SRST
2071 ``-nographic``
2072     Normally, if QEMU is compiled with graphical window support, it
2073     displays output such as guest graphics, guest console, and the QEMU
2074     monitor in a window. With this option, you can totally disable
2075     graphical output so that QEMU is a simple command line application.
2076     The emulated serial port is redirected on the console and muxed with
2077     the monitor (unless redirected elsewhere explicitly). Therefore, you
2078     can still use QEMU to debug a Linux kernel with a serial console.
2079     Use C-a h for help on switching between the console and monitor.
2080 ERST
2081
2082 #ifdef CONFIG_SPICE
2083 DEF("spice", HAS_ARG, QEMU_OPTION_spice,
2084     "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n"
2085     "       [,x509-key-file=<file>][,x509-key-password=<file>]\n"
2086     "       [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n"
2087     "       [,x509-dh-key-file=<file>][,addr=addr]\n"
2088     "       [,ipv4=on|off][,ipv6=on|off][,unix=on|off]\n"
2089     "       [,tls-ciphers=<list>]\n"
2090     "       [,tls-channel=[main|display|cursor|inputs|record|playback]]\n"
2091     "       [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n"
2092     "       [,sasl=on|off][,disable-ticketing=on|off]\n"
2093     "       [,password=<string>][,password-secret=<secret-id>]\n"
2094     "       [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n"
2095     "       [,jpeg-wan-compression=[auto|never|always]]\n"
2096     "       [,zlib-glz-wan-compression=[auto|never|always]]\n"
2097     "       [,streaming-video=[off|all|filter]][,disable-copy-paste=on|off]\n"
2098     "       [,disable-agent-file-xfer=on|off][,agent-mouse=[on|off]]\n"
2099     "       [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n"
2100     "       [,gl=[on|off]][,rendernode=<file>]\n"
2101     "   enable spice\n"
2102     "   at least one of {port, tls-port} is mandatory\n",
2103     QEMU_ARCH_ALL)
2104 #endif
2105 SRST
2106 ``-spice option[,option[,...]]``
2107     Enable the spice remote desktop protocol. Valid options are
2108
2109     ``port=<nr>``
2110         Set the TCP port spice is listening on for plaintext channels.
2111
2112     ``addr=<addr>``
2113         Set the IP address spice is listening on. Default is any
2114         address.
2115
2116     ``ipv4=on|off``; \ ``ipv6=on|off``; \ ``unix=on|off``
2117         Force using the specified IP version.
2118
2119     ``password=<string>``
2120         Set the password you need to authenticate.
2121
2122         This option is deprecated and insecure because it leaves the
2123         password visible in the process listing. Use ``password-secret``
2124         instead.
2125
2126     ``password-secret=<secret-id>``
2127         Set the ID of the ``secret`` object containing the password
2128         you need to authenticate.
2129
2130     ``sasl=on|off``
2131         Require that the client use SASL to authenticate with the spice.
2132         The exact choice of authentication method used is controlled
2133         from the system / user's SASL configuration file for the 'qemu'
2134         service. This is typically found in /etc/sasl2/qemu.conf. If
2135         running QEMU as an unprivileged user, an environment variable
2136         SASL\_CONF\_PATH can be used to make it search alternate
2137         locations for the service config. While some SASL auth methods
2138         can also provide data encryption (eg GSSAPI), it is recommended
2139         that SASL always be combined with the 'tls' and 'x509' settings
2140         to enable use of SSL and server certificates. This ensures a
2141         data encryption preventing compromise of authentication
2142         credentials.
2143
2144     ``disable-ticketing=on|off``
2145         Allow client connects without authentication.
2146
2147     ``disable-copy-paste=on|off``
2148         Disable copy paste between the client and the guest.
2149
2150     ``disable-agent-file-xfer=on|off``
2151         Disable spice-vdagent based file-xfer between the client and the
2152         guest.
2153
2154     ``tls-port=<nr>``
2155         Set the TCP port spice is listening on for encrypted channels.
2156
2157     ``x509-dir=<dir>``
2158         Set the x509 file directory. Expects same filenames as -vnc
2159         $display,x509=$dir
2160
2161     ``x509-key-file=<file>``; \ ``x509-key-password=<file>``; \ ``x509-cert-file=<file>``; \ ``x509-cacert-file=<file>``; \ ``x509-dh-key-file=<file>``
2162         The x509 file names can also be configured individually.
2163
2164     ``tls-ciphers=<list>``
2165         Specify which ciphers to use.
2166
2167     ``tls-channel=[main|display|cursor|inputs|record|playback]``; \ ``plaintext-channel=[main|display|cursor|inputs|record|playback]``
2168         Force specific channel to be used with or without TLS
2169         encryption. The options can be specified multiple times to
2170         configure multiple channels. The special name "default" can be
2171         used to set the default mode. For channels which are not
2172         explicitly forced into one mode the spice client is allowed to
2173         pick tls/plaintext as he pleases.
2174
2175     ``image-compression=[auto_glz|auto_lz|quic|glz|lz|off]``
2176         Configure image compression (lossless). Default is auto\_glz.
2177
2178     ``jpeg-wan-compression=[auto|never|always]``; \ ``zlib-glz-wan-compression=[auto|never|always]``
2179         Configure wan image compression (lossy for slow links). Default
2180         is auto.
2181
2182     ``streaming-video=[off|all|filter]``
2183         Configure video stream detection. Default is off.
2184
2185     ``agent-mouse=[on|off]``
2186         Enable/disable passing mouse events via vdagent. Default is on.
2187
2188     ``playback-compression=[on|off]``
2189         Enable/disable audio stream compression (using celt 0.5.1).
2190         Default is on.
2191
2192     ``seamless-migration=[on|off]``
2193         Enable/disable spice seamless migration. Default is off.
2194
2195     ``gl=[on|off]``
2196         Enable/disable OpenGL context. Default is off.
2197
2198     ``rendernode=<file>``
2199         DRM render node for OpenGL rendering. If not specified, it will
2200         pick the first available. (Since 2.9)
2201 ERST
2202
2203 DEF("portrait", 0, QEMU_OPTION_portrait,
2204     "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n",
2205     QEMU_ARCH_ALL)
2206 SRST
2207 ``-portrait``
2208     Rotate graphical output 90 deg left (only PXA LCD).
2209 ERST
2210
2211 DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
2212     "-rotate <deg>   rotate graphical output some deg left (only PXA LCD)\n",
2213     QEMU_ARCH_ALL)
2214 SRST
2215 ``-rotate deg``
2216     Rotate graphical output some deg left (only PXA LCD).
2217 ERST
2218
2219 DEF("vga", HAS_ARG, QEMU_OPTION_vga,
2220     "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n"
2221     "                select video card type\n", QEMU_ARCH_ALL)
2222 SRST
2223 ``-vga type``
2224     Select type of VGA card to emulate. Valid values for type are
2225
2226     ``cirrus``
2227         Cirrus Logic GD5446 Video card. All Windows versions starting
2228         from Windows 95 should recognize and use this graphic card. For
2229         optimal performances, use 16 bit color depth in the guest and
2230         the host OS. (This card was the default before QEMU 2.2)
2231
2232     ``std``
2233         Standard VGA card with Bochs VBE extensions. If your guest OS
2234         supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if
2235         you want to use high resolution modes (>= 1280x1024x16) then you
2236         should use this option. (This card is the default since QEMU
2237         2.2)
2238
2239     ``vmware``
2240         VMWare SVGA-II compatible adapter. Use it if you have
2241         sufficiently recent XFree86/XOrg server or Windows guest with a
2242         driver for this card.
2243
2244     ``qxl``
2245         QXL paravirtual graphic card. It is VGA compatible (including
2246         VESA 2.0 VBE support). Works best with qxl guest drivers
2247         installed though. Recommended choice when using the spice
2248         protocol.
2249
2250     ``tcx``
2251         (sun4m only) Sun TCX framebuffer. This is the default
2252         framebuffer for sun4m machines and offers both 8-bit and 24-bit
2253         colour depths at a fixed resolution of 1024x768.
2254
2255     ``cg3``
2256         (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit
2257         framebuffer for sun4m machines available in both 1024x768
2258         (OpenBIOS) and 1152x900 (OBP) resolutions aimed at people
2259         wishing to run older Solaris versions.
2260
2261     ``virtio``
2262         Virtio VGA card.
2263
2264     ``none``
2265         Disable VGA card.
2266 ERST
2267
2268 DEF("full-screen", 0, QEMU_OPTION_full_screen,
2269     "-full-screen    start in full screen\n", QEMU_ARCH_ALL)
2270 SRST
2271 ``-full-screen``
2272     Start in full screen.
2273 ERST
2274
2275 DEF("g", HAS_ARG, QEMU_OPTION_g ,
2276     "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n",
2277     QEMU_ARCH_PPC | QEMU_ARCH_SPARC | QEMU_ARCH_M68K)
2278 SRST
2279 ``-g`` *width*\ ``x``\ *height*\ ``[x``\ *depth*\ ``]``
2280     Set the initial graphical resolution and depth (PPC, SPARC only).
2281
2282     For PPC the default is 800x600x32.
2283
2284     For SPARC with the TCX graphics device, the default is 1024x768x8
2285     with the option of 1024x768x24. For cgthree, the default is
2286     1024x768x8 with the option of 1152x900x8 for people who wish to use
2287     OBP.
2288 ERST
2289
2290 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
2291     "-vnc <display>  shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL)
2292 SRST
2293 ``-vnc display[,option[,option[,...]]]``
2294     Normally, if QEMU is compiled with graphical window support, it
2295     displays output such as guest graphics, guest console, and the QEMU
2296     monitor in a window. With this option, you can have QEMU listen on
2297     VNC display display and redirect the VGA display over the VNC
2298     session. It is very useful to enable the usb tablet device when
2299     using this option (option ``-device usb-tablet``). When using the
2300     VNC display, you must use the ``-k`` parameter to set the keyboard
2301     layout if you are not using en-us. Valid syntax for the display is
2302
2303     ``to=L``
2304         With this option, QEMU will try next available VNC displays,
2305         until the number L, if the origianlly defined "-vnc display" is
2306         not available, e.g. port 5900+display is already used by another
2307         application. By default, to=0.
2308
2309     ``host:d``
2310         TCP connections will only be allowed from host on display d. By
2311         convention the TCP port is 5900+d. Optionally, host can be
2312         omitted in which case the server will accept connections from
2313         any host.
2314
2315     ``unix:path``
2316         Connections will be allowed over UNIX domain sockets where path
2317         is the location of a unix socket to listen for connections on.
2318
2319     ``none``
2320         VNC is initialized but not started. The monitor ``change``
2321         command can be used to later start the VNC server.
2322
2323     Following the display value there may be one or more option flags
2324     separated by commas. Valid options are
2325
2326     ``reverse=on|off``
2327         Connect to a listening VNC client via a "reverse" connection.
2328         The client is specified by the display. For reverse network
2329         connections (host:d,``reverse``), the d argument is a TCP port
2330         number, not a display number.
2331
2332     ``websocket=on|off``
2333         Opens an additional TCP listening port dedicated to VNC
2334         Websocket connections. If a bare websocket option is given, the
2335         Websocket port is 5700+display. An alternative port can be
2336         specified with the syntax ``websocket``\ =port.
2337
2338         If host is specified connections will only be allowed from this
2339         host. It is possible to control the websocket listen address
2340         independently, using the syntax ``websocket``\ =host:port.
2341
2342         If no TLS credentials are provided, the websocket connection
2343         runs in unencrypted mode. If TLS credentials are provided, the
2344         websocket connection requires encrypted client connections.
2345
2346     ``password=on|off``
2347         Require that password based authentication is used for client
2348         connections.
2349
2350         The password must be set separately using the ``set_password``
2351         command in the :ref:`QEMU monitor`. The
2352         syntax to change your password is:
2353         ``set_password <protocol> <password>`` where <protocol> could be
2354         either "vnc" or "spice".
2355
2356         If you would like to change <protocol> password expiration, you
2357         should use ``expire_password <protocol> <expiration-time>``
2358         where expiration time could be one of the following options:
2359         now, never, +seconds or UNIX time of expiration, e.g. +60 to
2360         make password expire in 60 seconds, or 1335196800 to make
2361         password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for
2362         this date and time).
2363
2364         You can also use keywords "now" or "never" for the expiration
2365         time to allow <protocol> password to expire immediately or never
2366         expire.
2367
2368     ``password-secret=<secret-id>``
2369         Require that password based authentication is used for client
2370         connections, using the password provided by the ``secret``
2371         object identified by ``secret-id``.
2372
2373     ``tls-creds=ID``
2374         Provides the ID of a set of TLS credentials to use to secure the
2375         VNC server. They will apply to both the normal VNC server socket
2376         and the websocket socket (if enabled). Setting TLS credentials
2377         will cause the VNC server socket to enable the VeNCrypt auth
2378         mechanism. The credentials should have been previously created
2379         using the ``-object tls-creds`` argument.
2380
2381     ``tls-authz=ID``
2382         Provides the ID of the QAuthZ authorization object against which
2383         the client's x509 distinguished name will validated. This object
2384         is only resolved at time of use, so can be deleted and recreated
2385         on the fly while the VNC server is active. If missing, it will
2386         default to denying access.
2387
2388     ``sasl=on|off``
2389         Require that the client use SASL to authenticate with the VNC
2390         server. The exact choice of authentication method used is
2391         controlled from the system / user's SASL configuration file for
2392         the 'qemu' service. This is typically found in
2393         /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user,
2394         an environment variable SASL\_CONF\_PATH can be used to make it
2395         search alternate locations for the service config. While some
2396         SASL auth methods can also provide data encryption (eg GSSAPI),
2397         it is recommended that SASL always be combined with the 'tls'
2398         and 'x509' settings to enable use of SSL and server
2399         certificates. This ensures a data encryption preventing
2400         compromise of authentication credentials. See the
2401         :ref:`VNC security` section in the System Emulation Users Guide
2402         for details on using SASL authentication.
2403
2404     ``sasl-authz=ID``
2405         Provides the ID of the QAuthZ authorization object against which
2406         the client's SASL username will validated. This object is only
2407         resolved at time of use, so can be deleted and recreated on the
2408         fly while the VNC server is active. If missing, it will default
2409         to denying access.
2410
2411     ``acl=on|off``
2412         Legacy method for enabling authorization of clients against the
2413         x509 distinguished name and SASL username. It results in the
2414         creation of two ``authz-list`` objects with IDs of
2415         ``vnc.username`` and ``vnc.x509dname``. The rules for these
2416         objects must be configured with the HMP ACL commands.
2417
2418         This option is deprecated and should no longer be used. The new
2419         ``sasl-authz`` and ``tls-authz`` options are a replacement.
2420
2421     ``lossy=on|off``
2422         Enable lossy compression methods (gradient, JPEG, ...). If this
2423         option is set, VNC client may receive lossy framebuffer updates
2424         depending on its encoding settings. Enabling this option can
2425         save a lot of bandwidth at the expense of quality.
2426
2427     ``non-adaptive=on|off``
2428         Disable adaptive encodings. Adaptive encodings are enabled by
2429         default. An adaptive encoding will try to detect frequently
2430         updated screen regions, and send updates in these regions using
2431         a lossy encoding (like JPEG). This can be really helpful to save
2432         bandwidth when playing videos. Disabling adaptive encodings
2433         restores the original static behavior of encodings like Tight.
2434
2435     ``share=[allow-exclusive|force-shared|ignore]``
2436         Set display sharing policy. 'allow-exclusive' allows clients to
2437         ask for exclusive access. As suggested by the rfb spec this is
2438         implemented by dropping other connections. Connecting multiple
2439         clients in parallel requires all clients asking for a shared
2440         session (vncviewer: -shared switch). This is the default.
2441         'force-shared' disables exclusive client access. Useful for
2442         shared desktop sessions, where you don't want someone forgetting
2443         specify -shared disconnect everybody else. 'ignore' completely
2444         ignores the shared flag and allows everybody connect
2445         unconditionally. Doesn't conform to the rfb spec but is
2446         traditional QEMU behavior.
2447
2448     ``key-delay-ms``
2449         Set keyboard delay, for key down and key up events, in
2450         milliseconds. Default is 10. Keyboards are low-bandwidth
2451         devices, so this slowdown can help the device and guest to keep
2452         up and not lose events in case events are arriving in bulk.
2453         Possible causes for the latter are flaky network connections, or
2454         scripts for automated testing.
2455
2456     ``audiodev=audiodev``
2457         Use the specified audiodev when the VNC client requests audio
2458         transmission. When not using an -audiodev argument, this option
2459         must be omitted, otherwise is must be present and specify a
2460         valid audiodev.
2461
2462     ``power-control=on|off``
2463         Permit the remote client to issue shutdown, reboot or reset power
2464         control requests.
2465 ERST
2466
2467 ARCHHEADING(, QEMU_ARCH_I386)
2468
2469 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
2470
2471 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
2472     "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n",
2473     QEMU_ARCH_I386)
2474 SRST
2475 ``-win2k-hack``
2476     Use it when installing Windows 2000 to avoid a disk full bug. After
2477     Windows 2000 is installed, you no longer need this option (this
2478     option slows down the IDE transfers).
2479 ERST
2480
2481 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
2482     "-no-fd-bootchk  disable boot signature checking for floppy disks\n",
2483     QEMU_ARCH_I386)
2484 SRST
2485 ``-no-fd-bootchk``
2486     Disable boot signature checking for floppy disks in BIOS. May be
2487     needed to boot from old floppy disks.
2488 ERST
2489
2490 DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
2491            "-no-acpi        disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM)
2492 SRST
2493 ``-no-acpi``
2494     Disable ACPI (Advanced Configuration and Power Interface) support.
2495     Use it if your guest OS complains about ACPI problems (PC target
2496     machine only).
2497 ERST
2498
2499 DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
2500     "-no-hpet        disable HPET\n", QEMU_ARCH_I386)
2501 SRST
2502 ``-no-hpet``
2503     Disable HPET support.
2504 ERST
2505
2506 DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
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|file}=file1[:file2]...]\n"
2508     "                ACPI table description\n", QEMU_ARCH_I386)
2509 SRST
2510 ``-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]...]``
2511     Add ACPI table with specified header fields and context from
2512     specified files. For file=, take whole ACPI table from the specified
2513     files, including all ACPI headers (possible overridden by other
2514     options). For data=, only data portion of the table is used, all
2515     header information is specified in the command line. If a SLIC table
2516     is supplied to QEMU, then the SLIC's oem\_id and oem\_table\_id
2517     fields will override the same in the RSDT and the FADT (a.k.a.
2518     FACP), in order to ensure the field matches required by the
2519     Microsoft SLIC spec and the ACPI spec.
2520 ERST
2521
2522 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
2523     "-smbios file=binary\n"
2524     "                load SMBIOS entry from binary file\n"
2525     "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
2526     "              [,uefi=on|off]\n"
2527     "                specify SMBIOS type 0 fields\n"
2528     "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2529     "              [,uuid=uuid][,sku=str][,family=str]\n"
2530     "                specify SMBIOS type 1 fields\n"
2531     "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
2532     "              [,asset=str][,location=str]\n"
2533     "                specify SMBIOS type 2 fields\n"
2534     "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n"
2535     "              [,sku=str]\n"
2536     "                specify SMBIOS type 3 fields\n"
2537     "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n"
2538     "              [,asset=str][,part=str][,max-speed=%d][,current-speed=%d]\n"
2539     "              [,processor-id=%d]\n"
2540     "                specify SMBIOS type 4 fields\n"
2541     "-smbios type=11[,value=str][,path=filename]\n"
2542     "                specify SMBIOS type 11 fields\n"
2543     "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n"
2544     "               [,asset=str][,part=str][,speed=%d]\n"
2545     "                specify SMBIOS type 17 fields\n"
2546     "-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]\n"
2547     "                specify SMBIOS type 41 fields\n",
2548     QEMU_ARCH_I386 | QEMU_ARCH_ARM)
2549 SRST
2550 ``-smbios file=binary``
2551     Load SMBIOS entry from binary file.
2552
2553 ``-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]``
2554     Specify SMBIOS type 0 fields
2555
2556 ``-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str][,uuid=uuid][,sku=str][,family=str]``
2557     Specify SMBIOS type 1 fields
2558
2559 ``-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str]``
2560     Specify SMBIOS type 2 fields
2561
2562 ``-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str]``
2563     Specify SMBIOS type 3 fields
2564
2565 ``-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str][,processor-id=%d]``
2566     Specify SMBIOS type 4 fields
2567
2568 ``-smbios type=11[,value=str][,path=filename]``
2569     Specify SMBIOS type 11 fields
2570
2571     This argument can be repeated multiple times, and values are added in the order they are parsed.
2572     Applications intending to use OEM strings data are encouraged to use their application name as
2573     a prefix for the value string. This facilitates passing information for multiple applications
2574     concurrently.
2575
2576     The ``value=str`` syntax provides the string data inline, while the ``path=filename`` syntax
2577     loads data from a file on disk. Note that the file is not permitted to contain any NUL bytes.
2578
2579     Both the ``value`` and ``path`` options can be repeated multiple times and will be added to
2580     the SMBIOS table in the order in which they appear.
2581
2582     Note that on the x86 architecture, the total size of all SMBIOS tables is limited to 65535
2583     bytes. Thus the OEM strings data is not suitable for passing large amounts of data into the
2584     guest. Instead it should be used as a indicator to inform the guest where to locate the real
2585     data set, for example, by specifying the serial ID of a block device.
2586
2587     An example passing three strings is
2588
2589     .. parsed-literal::
2590
2591         -smbios type=11,value=cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/,\\
2592                         value=anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os,\\
2593                         path=/some/file/with/oemstringsdata.txt
2594
2595     In the guest OS this is visible with the ``dmidecode`` command
2596
2597      .. parsed-literal::
2598
2599          $ dmidecode -t 11
2600          Handle 0x0E00, DMI type 11, 5 bytes
2601          OEM Strings
2602               String 1: cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/
2603               String 2: anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os
2604               String 3: myapp:some extra data
2605
2606
2607 ``-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]``
2608     Specify SMBIOS type 17 fields
2609
2610 ``-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]``
2611     Specify SMBIOS type 41 fields
2612
2613     This argument can be repeated multiple times.  Its main use is to allow network interfaces be created
2614     as ``enoX`` on Linux, with X being the instance number, instead of the name depending on the interface
2615     position on the PCI bus.
2616
2617     Here is an example of use:
2618
2619     .. parsed-literal::
2620
2621         -netdev user,id=internet \\
2622         -device virtio-net-pci,mac=50:54:00:00:00:42,netdev=internet,id=internet-dev \\
2623         -smbios type=41,designation='Onboard LAN',instance=1,kind=ethernet,pcidev=internet-dev
2624
2625     In the guest OS, the device should then appear as ``eno1``:
2626
2627     ..parsed-literal::
2628
2629          $ ip -brief l
2630          lo               UNKNOWN        00:00:00:00:00:00 <LOOPBACK,UP,LOWER_UP>
2631          eno1             UP             50:54:00:00:00:42 <BROADCAST,MULTICAST,UP,LOWER_UP>
2632
2633     Currently, the PCI device has to be attached to the root bus.
2634
2635 ERST
2636
2637 DEFHEADING()
2638
2639 DEFHEADING(Network options:)
2640
2641 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
2642 #ifdef CONFIG_SLIRP
2643     "-netdev user,id=str[,ipv4=on|off][,net=addr[/mask]][,host=addr]\n"
2644     "         [,ipv6=on|off][,ipv6-net=addr[/int]][,ipv6-host=addr]\n"
2645     "         [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n"
2646     "         [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n"
2647     "         [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]"
2648 #ifndef _WIN32
2649                                              "[,smb=dir[,smbserver=addr]]\n"
2650 #endif
2651     "                configure a user mode network backend with ID 'str',\n"
2652     "                its DHCP server and optional services\n"
2653 #endif
2654 #ifdef _WIN32
2655     "-netdev tap,id=str,ifname=name\n"
2656     "                configure a host TAP network backend with ID 'str'\n"
2657 #else
2658     "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n"
2659     "         [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n"
2660     "         [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n"
2661     "         [,poll-us=n]\n"
2662     "                configure a host TAP network backend with ID 'str'\n"
2663     "                connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2664     "                use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
2665     "                to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
2666     "                to deconfigure it\n"
2667     "                use '[down]script=no' to disable script execution\n"
2668     "                use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
2669     "                configure it\n"
2670     "                use 'fd=h' to connect to an already opened TAP interface\n"
2671     "                use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n"
2672     "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
2673     "                default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
2674     "                use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
2675     "                use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
2676     "                use vhost=on to enable experimental in kernel accelerator\n"
2677     "                    (only has effect for virtio guests which use MSIX)\n"
2678     "                use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
2679     "                use 'vhostfd=h' to connect to an already opened vhost net device\n"
2680     "                use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n"
2681     "                use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n"
2682     "                use 'poll-us=n' to specify the maximum number of microseconds that could be\n"
2683     "                spent on busy polling for vhost net\n"
2684     "-netdev bridge,id=str[,br=bridge][,helper=helper]\n"
2685     "                configure a host TAP network backend with ID 'str' that is\n"
2686     "                connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n"
2687     "                using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n"
2688 #endif
2689 #ifdef __linux__
2690     "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n"
2691     "         [,rxsession=rxsession],txsession=txsession[,ipv6=on|off][,udp=on|off]\n"
2692     "         [,cookie64=on|off][,counter][,pincounter][,txcookie=txcookie]\n"
2693     "         [,rxcookie=rxcookie][,offset=offset]\n"
2694     "                configure a network backend with ID 'str' connected to\n"
2695     "                an Ethernet over L2TPv3 pseudowire.\n"
2696     "                Linux kernel 3.3+ as well as most routers can talk\n"
2697     "                L2TPv3. This transport allows connecting a VM to a VM,\n"
2698     "                VM to a router and even VM to Host. It is a nearly-universal\n"
2699     "                standard (RFC3931). Note - this implementation uses static\n"
2700     "                pre-configured tunnels (same as the Linux kernel).\n"
2701     "                use 'src=' to specify source address\n"
2702     "                use 'dst=' to specify destination address\n"
2703     "                use 'udp=on' to specify udp encapsulation\n"
2704     "                use 'srcport=' to specify source udp port\n"
2705     "                use 'dstport=' to specify destination udp port\n"
2706     "                use 'ipv6=on' to force v6\n"
2707     "                L2TPv3 uses cookies to prevent misconfiguration as\n"
2708     "                well as a weak security measure\n"
2709     "                use 'rxcookie=0x012345678' to specify a rxcookie\n"
2710     "                use 'txcookie=0x012345678' to specify a txcookie\n"
2711     "                use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n"
2712     "                use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n"
2713     "                use 'pincounter=on' to work around broken counter handling in peer\n"
2714     "                use 'offset=X' to add an extra offset between header and data\n"
2715 #endif
2716     "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n"
2717     "                configure a network backend to connect to another network\n"
2718     "                using a socket connection\n"
2719     "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
2720     "                configure a network backend to connect to a multicast maddr and port\n"
2721     "                use 'localaddr=addr' to specify the host address to send packets from\n"
2722     "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n"
2723     "                configure a network backend to connect to another network\n"
2724     "                using an UDP tunnel\n"
2725 #ifdef CONFIG_VDE
2726     "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
2727     "                configure a network backend to connect to port 'n' of a vde switch\n"
2728     "                running on host and listening for incoming connections on 'socketpath'.\n"
2729     "                Use group 'groupname' and mode 'octalmode' to change default\n"
2730     "                ownership and permissions for communication port.\n"
2731 #endif
2732 #ifdef CONFIG_NETMAP
2733     "-netdev netmap,id=str,ifname=name[,devname=nmname]\n"
2734     "                attach to the existing netmap-enabled network interface 'name', or to a\n"
2735     "                VALE port (created on the fly) called 'name' ('nmname' is name of the \n"
2736     "                netmap device, defaults to '/dev/netmap')\n"
2737 #endif
2738 #ifdef CONFIG_POSIX
2739     "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n"
2740     "                configure a vhost-user network, backed by a chardev 'dev'\n"
2741 #endif
2742 #ifdef __linux__
2743     "-netdev vhost-vdpa,id=str,vhostdev=/path/to/dev\n"
2744     "                configure a vhost-vdpa network,Establish a vhost-vdpa netdev\n"
2745 #endif
2746 #ifdef CONFIG_VMNET
2747     "-netdev vmnet-host,id=str[,isolated=on|off][,net-uuid=uuid]\n"
2748     "         [,start-address=addr,end-address=addr,subnet-mask=mask]\n"
2749     "                configure a vmnet network backend in host mode with ID 'str',\n"
2750     "                isolate this interface from others with 'isolated',\n"
2751     "                configure the address range and choose a subnet mask,\n"
2752     "                specify network UUID 'uuid' to disable DHCP and interact with\n"
2753     "                vmnet-host interfaces within this isolated network\n"
2754     "-netdev vmnet-shared,id=str[,isolated=on|off][,nat66-prefix=addr]\n"
2755     "         [,start-address=addr,end-address=addr,subnet-mask=mask]\n"
2756     "                configure a vmnet network backend in shared mode with ID 'str',\n"
2757     "                configure the address range and choose a subnet mask,\n"
2758     "                set IPv6 ULA prefix (of length 64) to use for internal network,\n"
2759     "                isolate this interface from others with 'isolated'\n"
2760     "-netdev vmnet-bridged,id=str,ifname=name[,isolated=on|off]\n"
2761     "                configure a vmnet network backend in bridged mode with ID 'str',\n"
2762     "                use 'ifname=name' to select a physical network interface to be bridged,\n"
2763     "                isolate this interface from others with 'isolated'\n"
2764 #endif
2765     "-netdev hubport,id=str,hubid=n[,netdev=nd]\n"
2766     "                configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL)
2767 DEF("nic", HAS_ARG, QEMU_OPTION_nic,
2768     "-nic [tap|bridge|"
2769 #ifdef CONFIG_SLIRP
2770     "user|"
2771 #endif
2772 #ifdef __linux__
2773     "l2tpv3|"
2774 #endif
2775 #ifdef CONFIG_VDE
2776     "vde|"
2777 #endif
2778 #ifdef CONFIG_NETMAP
2779     "netmap|"
2780 #endif
2781 #ifdef CONFIG_POSIX
2782     "vhost-user|"
2783 #endif
2784 #ifdef CONFIG_VMNET
2785     "vmnet-host|vmnet-shared|vmnet-bridged|"
2786 #endif
2787     "socket][,option][,...][mac=macaddr]\n"
2788     "                initialize an on-board / default host NIC (using MAC address\n"
2789     "                macaddr) and connect it to the given host network backend\n"
2790     "-nic none       use it alone to have zero network devices (the default is to\n"
2791     "                provided a 'user' network connection)\n",
2792     QEMU_ARCH_ALL)
2793 DEF("net", HAS_ARG, QEMU_OPTION_net,
2794     "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
2795     "                configure or create an on-board (or machine default) NIC and\n"
2796     "                connect it to hub 0 (please use -nic unless you need a hub)\n"
2797     "-net ["
2798 #ifdef CONFIG_SLIRP
2799     "user|"
2800 #endif
2801     "tap|"
2802     "bridge|"
2803 #ifdef CONFIG_VDE
2804     "vde|"
2805 #endif
2806 #ifdef CONFIG_NETMAP
2807     "netmap|"
2808 #endif
2809 #ifdef CONFIG_VMNET
2810     "vmnet-host|vmnet-shared|vmnet-bridged|"
2811 #endif
2812     "socket][,option][,option][,...]\n"
2813     "                old way to initialize a host network interface\n"
2814     "                (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL)
2815 SRST
2816 ``-nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]``
2817     This option is a shortcut for configuring both the on-board
2818     (default) guest NIC hardware and the host network backend in one go.
2819     The host backend options are the same as with the corresponding
2820     ``-netdev`` options below. The guest NIC model can be set with
2821     ``model=modelname``. Use ``model=help`` to list the available device
2822     types. The hardware MAC address can be set with ``mac=macaddr``.
2823
2824     The following two example do exactly the same, to show how ``-nic``
2825     can be used to shorten the command line length:
2826
2827     .. parsed-literal::
2828
2829         |qemu_system| -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2830         |qemu_system| -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2831
2832 ``-nic none``
2833     Indicate that no network devices should be configured. It is used to
2834     override the default configuration (default NIC with "user" host
2835     network backend) which is activated if no other networking options
2836     are provided.
2837
2838 ``-netdev user,id=id[,option][,option][,...]``
2839     Configure user mode host network backend which requires no
2840     administrator privilege to run. Valid options are:
2841
2842     ``id=id``
2843         Assign symbolic name for use in monitor commands.
2844
2845     ``ipv4=on|off and ipv6=on|off``
2846         Specify that either IPv4 or IPv6 must be enabled. If neither is
2847         specified both protocols are enabled.
2848
2849     ``net=addr[/mask]``
2850         Set IP network address the guest will see. Optionally specify
2851         the netmask, either in the form a.b.c.d or as number of valid
2852         top-most bits. Default is 10.0.2.0/24.
2853
2854     ``host=addr``
2855         Specify the guest-visible address of the host. Default is the
2856         2nd IP in the guest network, i.e. x.x.x.2.
2857
2858     ``ipv6-net=addr[/int]``
2859         Set IPv6 network address the guest will see (default is
2860         fec0::/64). The network prefix is given in the usual hexadecimal
2861         IPv6 address notation. The prefix size is optional, and is given
2862         as the number of valid top-most bits (default is 64).
2863
2864     ``ipv6-host=addr``
2865         Specify the guest-visible IPv6 address of the host. Default is
2866         the 2nd IPv6 in the guest network, i.e. xxxx::2.
2867
2868     ``restrict=on|off``
2869         If this option is enabled, the guest will be isolated, i.e. it
2870         will not be able to contact the host and no guest IP packets
2871         will be routed over the host to the outside. This option does
2872         not affect any explicitly set forwarding rules.
2873
2874     ``hostname=name``
2875         Specifies the client hostname reported by the built-in DHCP
2876         server.
2877
2878     ``dhcpstart=addr``
2879         Specify the first of the 16 IPs the built-in DHCP server can
2880         assign. Default is the 15th to 31st IP in the guest network,
2881         i.e. x.x.x.15 to x.x.x.31.
2882
2883     ``dns=addr``
2884         Specify the guest-visible address of the virtual nameserver. The
2885         address must be different from the host address. Default is the
2886         3rd IP in the guest network, i.e. x.x.x.3.
2887
2888     ``ipv6-dns=addr``
2889         Specify the guest-visible address of the IPv6 virtual
2890         nameserver. The address must be different from the host address.
2891         Default is the 3rd IP in the guest network, i.e. xxxx::3.
2892
2893     ``dnssearch=domain``
2894         Provides an entry for the domain-search list sent by the
2895         built-in DHCP server. More than one domain suffix can be
2896         transmitted by specifying this option multiple times. If
2897         supported, this will cause the guest to automatically try to
2898         append the given domain suffix(es) in case a domain name can not
2899         be resolved.
2900
2901         Example:
2902
2903         .. parsed-literal::
2904
2905             |qemu_system| -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
2906
2907     ``domainname=domain``
2908         Specifies the client domain name reported by the built-in DHCP
2909         server.
2910
2911     ``tftp=dir``
2912         When using the user mode network stack, activate a built-in TFTP
2913         server. The files in dir will be exposed as the root of a TFTP
2914         server. The TFTP client on the guest must be configured in
2915         binary mode (use the command ``bin`` of the Unix TFTP client).
2916
2917     ``tftp-server-name=name``
2918         In BOOTP reply, broadcast name as the "TFTP server name"
2919         (RFC2132 option 66). This can be used to advise the guest to
2920         load boot files or configurations from a different server than
2921         the host address.
2922
2923     ``bootfile=file``
2924         When using the user mode network stack, broadcast file as the
2925         BOOTP filename. In conjunction with ``tftp``, this can be used
2926         to network boot a guest from a local directory.
2927
2928         Example (using pxelinux):
2929
2930         .. parsed-literal::
2931
2932             |qemu_system| -hda linux.img -boot n -device e1000,netdev=n1 \\
2933                 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
2934
2935     ``smb=dir[,smbserver=addr]``
2936         When using the user mode network stack, activate a built-in SMB
2937         server so that Windows OSes can access to the host files in
2938         ``dir`` transparently. The IP address of the SMB server can be
2939         set to addr. By default the 4th IP in the guest network is used,
2940         i.e. x.x.x.4.
2941
2942         In the guest Windows OS, the line:
2943
2944         ::
2945
2946             10.0.2.4 smbserver
2947
2948         must be added in the file ``C:\WINDOWS\LMHOSTS`` (for windows
2949         9x/Me) or ``C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS`` (Windows
2950         NT/2000).
2951
2952         Then ``dir`` can be accessed in ``\\smbserver\qemu``.
2953
2954         Note that a SAMBA server must be installed on the host OS.
2955
2956     ``hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport``
2957         Redirect incoming TCP or UDP connections to the host port
2958         hostport to the guest IP address guestaddr on guest port
2959         guestport. If guestaddr is not specified, its value is x.x.x.15
2960         (default first address given by the built-in DHCP server). By
2961         specifying hostaddr, the rule can be bound to a specific host
2962         interface. If no connection type is set, TCP is used. This
2963         option can be given multiple times.
2964
2965         For example, to redirect host X11 connection from screen 1 to
2966         guest screen 0, use the following:
2967
2968         .. parsed-literal::
2969
2970             # on the host
2971             |qemu_system| -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
2972             # this host xterm should open in the guest X11 server
2973             xterm -display :1
2974
2975         To redirect telnet connections from host port 5555 to telnet
2976         port on the guest, use the following:
2977
2978         .. parsed-literal::
2979
2980             # on the host
2981             |qemu_system| -nic user,hostfwd=tcp::5555-:23
2982             telnet localhost 5555
2983
2984         Then when you use on the host ``telnet localhost 5555``, you
2985         connect to the guest telnet server.
2986
2987     ``guestfwd=[tcp]:server:port-dev``; \ ``guestfwd=[tcp]:server:port-cmd:command``
2988         Forward guest TCP connections to the IP address server on port
2989         port to the character device dev or to a program executed by
2990         cmd:command which gets spawned for each connection. This option
2991         can be given multiple times.
2992
2993         You can either use a chardev directly and have that one used
2994         throughout QEMU's lifetime, like in the following example:
2995
2996         .. parsed-literal::
2997
2998             # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2999             # the guest accesses it
3000             |qemu_system| -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
3001
3002         Or you can execute a command on every TCP connection established
3003         by the guest, so that QEMU behaves similar to an inetd process
3004         for that virtual server:
3005
3006         .. parsed-literal::
3007
3008             # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
3009             # and connect the TCP stream to its stdin/stdout
3010             |qemu_system| -nic  'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
3011
3012 ``-netdev tap,id=id[,fd=h][,ifname=name][,script=file][,downscript=dfile][,br=bridge][,helper=helper]``
3013     Configure a host TAP network backend with ID id.
3014
3015     Use the network script file to configure it and the network script
3016     dfile to deconfigure it. If name is not provided, the OS
3017     automatically provides one. The default network configure script is
3018     ``/etc/qemu-ifup`` and the default network deconfigure script is
3019     ``/etc/qemu-ifdown``. Use ``script=no`` or ``downscript=no`` to
3020     disable script execution.
3021
3022     If running QEMU as an unprivileged user, use the network helper
3023     to configure the TAP interface and attach it to the bridge.
3024     The default network helper executable is
3025     ``/path/to/qemu-bridge-helper`` and the default bridge device is
3026     ``br0``.
3027
3028     ``fd``\ =h can be used to specify the handle of an already opened
3029     host TAP interface.
3030
3031     Examples:
3032
3033     .. parsed-literal::
3034
3035         #launch a QEMU instance with the default network script
3036         |qemu_system| linux.img -nic tap
3037
3038     .. parsed-literal::
3039
3040         #launch a QEMU instance with two NICs, each one connected
3041         #to a TAP device
3042         |qemu_system| linux.img \\
3043                 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \\
3044                 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
3045
3046     .. parsed-literal::
3047
3048         #launch a QEMU instance with the default network helper to
3049         #connect a TAP device to bridge br0
3050         |qemu_system| linux.img -device virtio-net-pci,netdev=n1 \\
3051                 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
3052
3053 ``-netdev bridge,id=id[,br=bridge][,helper=helper]``
3054     Connect a host TAP network interface to a host bridge device.
3055
3056     Use the network helper helper to configure the TAP interface and
3057     attach it to the bridge. The default network helper executable is
3058     ``/path/to/qemu-bridge-helper`` and the default bridge device is
3059     ``br0``.
3060
3061     Examples:
3062
3063     .. parsed-literal::
3064
3065         #launch a QEMU instance with the default network helper to
3066         #connect a TAP device to bridge br0
3067         |qemu_system| linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
3068
3069     .. parsed-literal::
3070
3071         #launch a QEMU instance with the default network helper to
3072         #connect a TAP device to bridge qemubr0
3073         |qemu_system| linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
3074
3075 ``-netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]``
3076     This host network backend can be used to connect the guest's network
3077     to another QEMU virtual machine using a TCP socket connection. If
3078     ``listen`` is specified, QEMU waits for incoming connections on port
3079     (host is optional). ``connect`` is used to connect to another QEMU
3080     instance using the ``listen`` option. ``fd``\ =h specifies an
3081     already opened TCP socket.
3082
3083     Example:
3084
3085     .. parsed-literal::
3086
3087         # launch a first QEMU instance
3088         |qemu_system| linux.img \\
3089                          -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
3090                          -netdev socket,id=n1,listen=:1234
3091         # connect the network of this instance to the network of the first instance
3092         |qemu_system| linux.img \\
3093                          -device e1000,netdev=n2,mac=52:54:00:12:34:57 \\
3094                          -netdev socket,id=n2,connect=127.0.0.1:1234
3095
3096 ``-netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]``
3097     Configure a socket host network backend to share the guest's network
3098     traffic with another QEMU virtual machines using a UDP multicast
3099     socket, effectively making a bus for every QEMU with same multicast
3100     address maddr and port. NOTES:
3101
3102     1. Several QEMU can be running on different hosts and share same bus
3103        (assuming correct multicast setup for these hosts).
3104
3105     2. mcast support is compatible with User Mode Linux (argument
3106        ``ethN=mcast``), see http://user-mode-linux.sf.net.
3107
3108     3. Use ``fd=h`` to specify an already opened UDP multicast socket.
3109
3110     Example:
3111
3112     .. parsed-literal::
3113
3114         # launch one QEMU instance
3115         |qemu_system| linux.img \\
3116                          -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
3117                          -netdev socket,id=n1,mcast=230.0.0.1:1234
3118         # launch another QEMU instance on same "bus"
3119         |qemu_system| linux.img \\
3120                          -device e1000,netdev=n2,mac=52:54:00:12:34:57 \\
3121                          -netdev socket,id=n2,mcast=230.0.0.1:1234
3122         # launch yet another QEMU instance on same "bus"
3123         |qemu_system| linux.img \\
3124                          -device e1000,netdev=n3,mac=52:54:00:12:34:58 \\
3125                          -netdev socket,id=n3,mcast=230.0.0.1:1234
3126
3127     Example (User Mode Linux compat.):
3128
3129     .. parsed-literal::
3130
3131         # launch QEMU instance (note mcast address selected is UML's default)
3132         |qemu_system| linux.img \\
3133                          -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
3134                          -netdev socket,id=n1,mcast=239.192.168.1:1102
3135         # launch UML
3136         /path/to/linux ubd0=/path/to/root_fs eth0=mcast
3137
3138     Example (send packets from host's 1.2.3.4):
3139
3140     .. parsed-literal::
3141
3142         |qemu_system| linux.img \\
3143                          -device e1000,netdev=n1,mac=52:54:00:12:34:56 \\
3144                          -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
3145
3146 ``-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]``
3147     Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3931)
3148     is a popular protocol to transport Ethernet (and other Layer 2) data
3149     frames between two systems. It is present in routers, firewalls and
3150     the Linux kernel (from version 3.3 onwards).
3151
3152     This transport allows a VM to communicate to another VM, router or
3153     firewall directly.
3154
3155     ``src=srcaddr``
3156         source address (mandatory)
3157
3158     ``dst=dstaddr``
3159         destination address (mandatory)
3160
3161     ``udp``
3162         select udp encapsulation (default is ip).
3163
3164     ``srcport=srcport``
3165         source udp port.
3166
3167     ``dstport=dstport``
3168         destination udp port.
3169
3170     ``ipv6``
3171         force v6, otherwise defaults to v4.
3172
3173     ``rxcookie=rxcookie``; \ ``txcookie=txcookie``
3174         Cookies are a weak form of security in the l2tpv3 specification.
3175         Their function is mostly to prevent misconfiguration. By default
3176         they are 32 bit.
3177
3178     ``cookie64``
3179         Set cookie size to 64 bit instead of the default 32
3180
3181     ``counter=off``
3182         Force a 'cut-down' L2TPv3 with no counter as in
3183         draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
3184
3185     ``pincounter=on``
3186         Work around broken counter handling in peer. This may also help
3187         on networks which have packet reorder.
3188
3189     ``offset=offset``
3190         Add an extra offset between header and data
3191
3192     For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to
3193     the bridge br-lan on the remote Linux host 1.2.3.4:
3194
3195     .. parsed-literal::
3196
3197         # Setup tunnel on linux host using raw ip as encapsulation
3198         # on 1.2.3.4
3199         ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \\
3200             encap udp udp_sport 16384 udp_dport 16384
3201         ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \\
3202             0xFFFFFFFF peer_session_id 0xFFFFFFFF
3203         ifconfig vmtunnel0 mtu 1500
3204         ifconfig vmtunnel0 up
3205         brctl addif br-lan vmtunnel0
3206
3207
3208         # on 4.3.2.1
3209         # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
3210
3211         |qemu_system| linux.img -device e1000,netdev=n1 \\
3212             -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
3213
3214 ``-netdev vde,id=id[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]``
3215     Configure VDE backend to connect to PORT n of a vde switch running
3216     on host and listening for incoming connections on socketpath. Use
3217     GROUP groupname and MODE octalmode to change default ownership and
3218     permissions for communication port. This option is only available if
3219     QEMU has been compiled with vde support enabled.
3220
3221     Example:
3222
3223     .. parsed-literal::
3224
3225         # launch vde switch
3226         vde_switch -F -sock /tmp/myswitch
3227         # launch QEMU instance
3228         |qemu_system| linux.img -nic vde,sock=/tmp/myswitch
3229
3230 ``-netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]``
3231     Establish a vhost-user netdev, backed by a chardev id. The chardev
3232     should be a unix domain socket backed one. The vhost-user uses a
3233     specifically defined protocol to pass vhost ioctl replacement
3234     messages to an application on the other end of the socket. On
3235     non-MSIX guests, the feature can be forced with vhostforce. Use
3236     'queues=n' to specify the number of queues to be created for
3237     multiqueue vhost-user.
3238
3239     Example:
3240
3241     ::
3242
3243         qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
3244              -numa node,memdev=mem \
3245              -chardev socket,id=chr0,path=/path/to/socket \
3246              -netdev type=vhost-user,id=net0,chardev=chr0 \
3247              -device virtio-net-pci,netdev=net0
3248
3249 ``-netdev vhost-vdpa,vhostdev=/path/to/dev``
3250     Establish a vhost-vdpa netdev.
3251
3252     vDPA device is a device that uses a datapath which complies with
3253     the virtio specifications with a vendor specific control path.
3254     vDPA devices can be both physically located on the hardware or
3255     emulated by software.
3256
3257 ``-netdev hubport,id=id,hubid=hubid[,netdev=nd]``
3258     Create a hub port on the emulated hub with ID hubid.
3259
3260     The hubport netdev lets you connect a NIC to a QEMU emulated hub
3261     instead of a single netdev. Alternatively, you can also connect the
3262     hubport to another netdev with ID nd by using the ``netdev=nd``
3263     option.
3264
3265 ``-net nic[,netdev=nd][,macaddr=mac][,model=type] [,name=name][,addr=addr][,vectors=v]``
3266     Legacy option to configure or create an on-board (or machine
3267     default) Network Interface Card(NIC) and connect it either to the
3268     emulated hub with ID 0 (i.e. the default hub), or to the netdev nd.
3269     If model is omitted, then the default NIC model associated with the
3270     machine type is used. Note that the default NIC model may change in
3271     future QEMU releases, so it is highly recommended to always specify
3272     a model. Optionally, the MAC address can be changed to mac, the
3273     device address set to addr (PCI cards only), and a name can be
3274     assigned for use in monitor commands. Optionally, for PCI cards, you
3275     can specify the number v of MSI-X vectors that the card should have;
3276     this option currently only affects virtio cards; set v = 0 to
3277     disable MSI-X. If no ``-net`` option is specified, a single NIC is
3278     created. QEMU can emulate several different models of network card.
3279     Use ``-net nic,model=help`` for a list of available devices for your
3280     target.
3281
3282 ``-net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]``
3283     Configure a host network backend (with the options corresponding to
3284     the same ``-netdev`` option) and connect it to the emulated hub 0
3285     (the default hub). Use name to specify the name of the hub port.
3286 ERST
3287
3288 DEFHEADING()
3289
3290 DEFHEADING(Character device options:)
3291
3292 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
3293     "-chardev help\n"
3294     "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3295     "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]\n"
3296     "         [,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds][,mux=on|off]\n"
3297     "         [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n"
3298     "-chardev socket,id=id,path=path[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds]\n"
3299     "         [,mux=on|off][,logfile=PATH][,logappend=on|off][,abstract=on|off][,tight=on|off] (unix)\n"
3300     "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
3301     "         [,localport=localport][,ipv4=on|off][,ipv6=on|off][,mux=on|off]\n"
3302     "         [,logfile=PATH][,logappend=on|off]\n"
3303     "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3304     "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
3305     "         [,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3306     "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n"
3307     "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3308     "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3309 #ifdef _WIN32
3310     "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3311     "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3312 #else
3313     "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3314     "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n"
3315 #endif
3316 #ifdef CONFIG_BRLAPI
3317     "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3318 #endif
3319 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
3320         || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
3321     "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3322     "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3323 #endif
3324 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
3325     "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3326     "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n"
3327 #endif
3328 #if defined(CONFIG_SPICE)
3329     "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
3330     "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n"
3331 #endif
3332     , QEMU_ARCH_ALL
3333 )
3334
3335 SRST
3336 The general form of a character device option is:
3337
3338 ``-chardev backend,id=id[,mux=on|off][,options]``
3339     Backend is one of: ``null``, ``socket``, ``udp``, ``msmouse``,
3340     ``vc``, ``ringbuf``, ``file``, ``pipe``, ``console``, ``serial``,
3341     ``pty``, ``stdio``, ``braille``, ``tty``, ``parallel``, ``parport``,
3342     ``spicevmc``, ``spiceport``. The specific backend will determine the
3343     applicable options.
3344
3345     Use ``-chardev help`` to print all available chardev backend types.
3346
3347     All devices must have an id, which can be any string up to 127
3348     characters long. It is used to uniquely identify this device in
3349     other command line directives.
3350
3351     A character device may be used in multiplexing mode by multiple
3352     front-ends. Specify ``mux=on`` to enable this mode. A multiplexer is
3353     a "1:N" device, and here the "1" end is your specified chardev
3354     backend, and the "N" end is the various parts of QEMU that can talk
3355     to a chardev. If you create a chardev with ``id=myid`` and
3356     ``mux=on``, QEMU will create a multiplexer with your specified ID,
3357     and you can then configure multiple front ends to use that chardev
3358     ID for their input/output. Up to four different front ends can be
3359     connected to a single multiplexed chardev. (Without multiplexing
3360     enabled, a chardev can only be used by a single front end.) For
3361     instance you could use this to allow a single stdio chardev to be
3362     used by two serial ports and the QEMU monitor:
3363
3364     ::
3365
3366         -chardev stdio,mux=on,id=char0 \
3367         -mon chardev=char0,mode=readline \
3368         -serial chardev:char0 \
3369         -serial chardev:char0
3370
3371     You can have more than one multiplexer in a system configuration;
3372     for instance you could have a TCP port multiplexed between UART 0
3373     and UART 1, and stdio multiplexed between the QEMU monitor and a
3374     parallel port:
3375
3376     ::
3377
3378         -chardev stdio,mux=on,id=char0 \
3379         -mon chardev=char0,mode=readline \
3380         -parallel chardev:char0 \
3381         -chardev tcp,...,mux=on,id=char1 \
3382         -serial chardev:char1 \
3383         -serial chardev:char1
3384
3385     When you're using a multiplexed character device, some escape
3386     sequences are interpreted in the input. See the chapter about
3387     :ref:`keys in the character backend multiplexer` in the
3388     System Emulation Users Guide for more details.
3389
3390     Note that some other command line options may implicitly create
3391     multiplexed character backends; for instance ``-serial mon:stdio``
3392     creates a multiplexed stdio backend connected to the serial port and
3393     the QEMU monitor, and ``-nographic`` also multiplexes the console
3394     and the monitor to stdio.
3395
3396     There is currently no support for multiplexing in the other
3397     direction (where a single QEMU front end takes input and output from
3398     multiple chardevs).
3399
3400     Every backend supports the ``logfile`` option, which supplies the
3401     path to a file to record all data transmitted via the backend. The
3402     ``logappend`` option controls whether the log file will be truncated
3403     or appended to when opened.
3404
3405 The available backends are:
3406
3407 ``-chardev null,id=id``
3408     A void device. This device will not emit any data, and will drop any
3409     data it receives. The null backend does not take any options.
3410
3411 ``-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]``
3412     Create a two-way stream socket, which can be either a TCP or a unix
3413     socket. A unix socket will be created if ``path`` is specified.
3414     Behaviour is undefined if TCP options are specified for a unix
3415     socket.
3416
3417     ``server=on|off`` specifies that the socket shall be a listening socket.
3418
3419     ``wait=on|off`` specifies that QEMU should not block waiting for a client
3420     to connect to a listening socket.
3421
3422     ``telnet=on|off`` specifies that traffic on the socket should interpret
3423     telnet escape sequences.
3424
3425     ``websocket=on|off`` specifies that the socket uses WebSocket protocol for
3426     communication.
3427
3428     ``reconnect`` sets the timeout for reconnecting on non-server
3429     sockets when the remote end goes away. qemu will delay this many
3430     seconds and then attempt to reconnect. Zero disables reconnecting,
3431     and is the default.
3432
3433     ``tls-creds`` requests enablement of the TLS protocol for
3434     encryption, and specifies the id of the TLS credentials to use for
3435     the handshake. The credentials must be previously created with the
3436     ``-object tls-creds`` argument.
3437
3438     ``tls-auth`` provides the ID of the QAuthZ authorization object
3439     against which the client's x509 distinguished name will be
3440     validated. This object is only resolved at time of use, so can be
3441     deleted and recreated on the fly while the chardev server is active.
3442     If missing, it will default to denying access.
3443
3444     TCP and unix socket options are given below:
3445
3446     ``TCP options: port=port[,host=host][,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]``
3447         ``host`` for a listening socket specifies the local address to
3448         be bound. For a connecting socket species the remote host to
3449         connect to. ``host`` is optional for listening sockets. If not
3450         specified it defaults to ``0.0.0.0``.
3451
3452         ``port`` for a listening socket specifies the local port to be
3453         bound. For a connecting socket specifies the port on the remote
3454         host to connect to. ``port`` can be given as either a port
3455         number or a service name. ``port`` is required.
3456
3457         ``to`` is only relevant to listening sockets. If it is
3458         specified, and ``port`` cannot be bound, QEMU will attempt to
3459         bind to subsequent ports up to and including ``to`` until it
3460         succeeds. ``to`` must be specified as a port number.
3461
3462         ``ipv4=on|off`` and ``ipv6=on|off`` specify that either IPv4
3463         or IPv6 must be used. If neither is specified the socket may
3464         use either protocol.
3465
3466         ``nodelay=on|off`` disables the Nagle algorithm.
3467
3468     ``unix options: path=path[,abstract=on|off][,tight=on|off]``
3469         ``path`` specifies the local path of the unix socket. ``path``
3470         is required.
3471         ``abstract=on|off`` specifies the use of the abstract socket namespace,
3472         rather than the filesystem.  Optional, defaults to false.
3473         ``tight=on|off`` sets the socket length of abstract sockets to their minimum,
3474         rather than the full sun_path length.  Optional, defaults to true.
3475
3476 ``-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr][,localport=localport][,ipv4=on|off][,ipv6=on|off]``
3477     Sends all traffic from the guest to a remote host over UDP.
3478
3479     ``host`` specifies the remote host to connect to. If not specified
3480     it defaults to ``localhost``.
3481
3482     ``port`` specifies the port on the remote host to connect to.
3483     ``port`` is required.
3484
3485     ``localaddr`` specifies the local address to bind to. If not
3486     specified it defaults to ``0.0.0.0``.
3487
3488     ``localport`` specifies the local port to bind to. If not specified
3489     any available local port will be used.
3490
3491     ``ipv4=on|off`` and ``ipv6=on|off`` specify that either IPv4 or IPv6 must be used.
3492     If neither is specified the device may use either protocol.
3493
3494 ``-chardev msmouse,id=id``
3495     Forward QEMU's emulated msmouse events to the guest. ``msmouse``
3496     does not take any options.
3497
3498 ``-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]``
3499     Connect to a QEMU text console. ``vc`` may optionally be given a
3500     specific size.
3501
3502     ``width`` and ``height`` specify the width and height respectively
3503     of the console, in pixels.
3504
3505     ``cols`` and ``rows`` specify that the console be sized to fit a
3506     text console with the given dimensions.
3507
3508 ``-chardev ringbuf,id=id[,size=size]``
3509     Create a ring buffer with fixed size ``size``. size must be a power
3510     of two and defaults to ``64K``.
3511
3512 ``-chardev file,id=id,path=path``
3513     Log all traffic received from the guest to a file.
3514
3515     ``path`` specifies the path of the file to be opened. This file will
3516     be created if it does not already exist, and overwritten if it does.
3517     ``path`` is required.
3518
3519 ``-chardev pipe,id=id,path=path``
3520     Create a two-way connection to the guest. The behaviour differs
3521     slightly between Windows hosts and other hosts:
3522
3523     On Windows, a single duplex pipe will be created at
3524     ``\\.pipe\path``.
3525
3526     On other hosts, 2 pipes will be created called ``path.in`` and
3527     ``path.out``. Data written to ``path.in`` will be received by the
3528     guest. Data written by the guest can be read from ``path.out``. QEMU
3529     will not create these fifos, and requires them to be present.
3530
3531     ``path`` forms part of the pipe path as described above. ``path`` is
3532     required.
3533
3534 ``-chardev console,id=id``
3535     Send traffic from the guest to QEMU's standard output. ``console``
3536     does not take any options.
3537
3538     ``console`` is only available on Windows hosts.
3539
3540 ``-chardev serial,id=id,path=path``
3541     Send traffic from the guest to a serial device on the host.
3542
3543     On Unix hosts serial will actually accept any tty device, not only
3544     serial lines.
3545
3546     ``path`` specifies the name of the serial device to open.
3547
3548 ``-chardev pty,id=id``
3549     Create a new pseudo-terminal on the host and connect to it. ``pty``
3550     does not take any options.
3551
3552     ``pty`` is not available on Windows hosts.
3553
3554 ``-chardev stdio,id=id[,signal=on|off]``
3555     Connect to standard input and standard output of the QEMU process.
3556
3557     ``signal`` controls if signals are enabled on the terminal, that
3558     includes exiting QEMU with the key sequence Control-c. This option
3559     is enabled by default, use ``signal=off`` to disable it.
3560
3561 ``-chardev braille,id=id``
3562     Connect to a local BrlAPI server. ``braille`` does not take any
3563     options.
3564
3565 ``-chardev tty,id=id,path=path``
3566     ``tty`` is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD
3567     and DragonFlyBSD hosts. It is an alias for ``serial``.
3568
3569     ``path`` specifies the path to the tty. ``path`` is required.
3570
3571 ``-chardev parallel,id=id,path=path``
3572   \
3573 ``-chardev parport,id=id,path=path``
3574     ``parallel`` is only available on Linux, FreeBSD and DragonFlyBSD
3575     hosts.
3576
3577     Connect to a local parallel port.
3578
3579     ``path`` specifies the path to the parallel port device. ``path`` is
3580     required.
3581
3582 ``-chardev spicevmc,id=id,debug=debug,name=name``
3583     ``spicevmc`` is only available when spice support is built in.
3584
3585     ``debug`` debug level for spicevmc
3586
3587     ``name`` name of spice channel to connect to
3588
3589     Connect to a spice virtual machine channel, such as vdiport.
3590
3591 ``-chardev spiceport,id=id,debug=debug,name=name``
3592     ``spiceport`` is only available when spice support is built in.
3593
3594     ``debug`` debug level for spicevmc
3595
3596     ``name`` name of spice port to connect to
3597
3598     Connect to a spice port, allowing a Spice client to handle the
3599     traffic identified by a name (preferably a fqdn).
3600 ERST
3601
3602 DEFHEADING()
3603
3604 #ifdef CONFIG_TPM
3605 DEFHEADING(TPM device options:)
3606
3607 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
3608     "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
3609     "                use path to provide path to a character device; default is /dev/tpm0\n"
3610     "                use cancel-path to provide path to TPM's cancel sysfs entry; if\n"
3611     "                not provided it will be searched for in /sys/class/misc/tpm?/device\n"
3612     "-tpmdev emulator,id=id,chardev=dev\n"
3613     "                configure the TPM device using chardev backend\n",
3614     QEMU_ARCH_ALL)
3615 SRST
3616 The general form of a TPM device option is:
3617
3618 ``-tpmdev backend,id=id[,options]``
3619     The specific backend type will determine the applicable options. The
3620     ``-tpmdev`` option creates the TPM backend and requires a
3621     ``-device`` option that specifies the TPM frontend interface model.
3622
3623     Use ``-tpmdev help`` to print all available TPM backend types.
3624
3625 The available backends are:
3626
3627 ``-tpmdev passthrough,id=id,path=path,cancel-path=cancel-path``
3628     (Linux-host only) Enable access to the host's TPM using the
3629     passthrough driver.
3630
3631     ``path`` specifies the path to the host's TPM device, i.e., on a
3632     Linux host this would be ``/dev/tpm0``. ``path`` is optional and by
3633     default ``/dev/tpm0`` is used.
3634
3635     ``cancel-path`` specifies the path to the host TPM device's sysfs
3636     entry allowing for cancellation of an ongoing TPM command.
3637     ``cancel-path`` is optional and by default QEMU will search for the
3638     sysfs entry to use.
3639
3640     Some notes about using the host's TPM with the passthrough driver:
3641
3642     The TPM device accessed by the passthrough driver must not be used
3643     by any other application on the host.
3644
3645     Since the host's firmware (BIOS/UEFI) has already initialized the
3646     TPM, the VM's firmware (BIOS/UEFI) will not be able to initialize
3647     the TPM again and may therefore not show a TPM-specific menu that
3648     would otherwise allow the user to configure the TPM, e.g., allow the
3649     user to enable/disable or activate/deactivate the TPM. Further, if
3650     TPM ownership is released from within a VM then the host's TPM will
3651     get disabled and deactivated. To enable and activate the TPM again
3652     afterwards, the host has to be rebooted and the user is required to
3653     enter the firmware's menu to enable and activate the TPM. If the TPM
3654     is left disabled and/or deactivated most TPM commands will fail.
3655
3656     To create a passthrough TPM use the following two options:
3657
3658     ::
3659
3660         -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
3661
3662     Note that the ``-tpmdev`` id is ``tpm0`` and is referenced by
3663     ``tpmdev=tpm0`` in the device option.
3664
3665 ``-tpmdev emulator,id=id,chardev=dev``
3666     (Linux-host only) Enable access to a TPM emulator using Unix domain
3667     socket based chardev backend.
3668
3669     ``chardev`` specifies the unique ID of a character device backend
3670     that provides connection to the software TPM server.
3671
3672     To create a TPM emulator backend device with chardev socket backend:
3673
3674     ::
3675
3676         -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
3677 ERST
3678
3679 DEFHEADING()
3680
3681 #endif
3682
3683 DEFHEADING(Linux/Multiboot boot specific:)
3684 SRST
3685 When using these options, you can use a given Linux or Multiboot kernel
3686 without installing it in the disk image. It can be useful for easier
3687 testing of various kernels.
3688
3689
3690 ERST
3691
3692 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
3693     "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
3694 SRST
3695 ``-kernel bzImage``
3696     Use bzImage as kernel image. The kernel can be either a Linux kernel
3697     or in multiboot format.
3698 ERST
3699
3700 DEF("append", HAS_ARG, QEMU_OPTION_append, \
3701     "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
3702 SRST
3703 ``-append cmdline``
3704     Use cmdline as kernel command line
3705 ERST
3706
3707 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
3708            "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
3709 SRST
3710 ``-initrd file``
3711     Use file as initial ram disk.
3712
3713 ``-initrd "file1 arg=foo,file2"``
3714     This syntax is only available with multiboot.
3715
3716     Use file1 and file2 as modules and pass arg=foo as parameter to the
3717     first module.
3718 ERST
3719
3720 DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \
3721     "-dtb    file    use 'file' as device tree image\n", QEMU_ARCH_ALL)
3722 SRST
3723 ``-dtb file``
3724     Use file as a device tree binary (dtb) image and pass it to the
3725     kernel on boot.
3726 ERST
3727
3728 DEFHEADING()
3729
3730 DEFHEADING(Debug/Expert options:)
3731
3732 DEF("compat", HAS_ARG, QEMU_OPTION_compat,
3733     "-compat [deprecated-input=accept|reject|crash][,deprecated-output=accept|hide]\n"
3734     "                Policy for handling deprecated management interfaces\n"
3735     "-compat [unstable-input=accept|reject|crash][,unstable-output=accept|hide]\n"
3736     "                Policy for handling unstable management interfaces\n",
3737     QEMU_ARCH_ALL)
3738 SRST
3739 ``-compat [deprecated-input=@var{input-policy}][,deprecated-output=@var{output-policy}]``
3740     Set policy for handling deprecated management interfaces (experimental):
3741
3742     ``deprecated-input=accept`` (default)
3743         Accept deprecated commands and arguments
3744     ``deprecated-input=reject``
3745         Reject deprecated commands and arguments
3746     ``deprecated-input=crash``
3747         Crash on deprecated commands and arguments
3748     ``deprecated-output=accept`` (default)
3749         Emit deprecated command results and events
3750     ``deprecated-output=hide``
3751         Suppress deprecated command results and events
3752
3753     Limitation: covers only syntactic aspects of QMP.
3754
3755 ``-compat [unstable-input=@var{input-policy}][,unstable-output=@var{output-policy}]``
3756     Set policy for handling unstable management interfaces (experimental):
3757
3758     ``unstable-input=accept`` (default)
3759         Accept unstable commands and arguments
3760     ``unstable-input=reject``
3761         Reject unstable commands and arguments
3762     ``unstable-input=crash``
3763         Crash on unstable commands and arguments
3764     ``unstable-output=accept`` (default)
3765         Emit unstable command results and events
3766     ``unstable-output=hide``
3767         Suppress unstable command results and events
3768
3769     Limitation: covers only syntactic aspects of QMP.
3770 ERST
3771
3772 DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg,
3773     "-fw_cfg [name=]<name>,file=<file>\n"
3774     "                add named fw_cfg entry with contents from file\n"
3775     "-fw_cfg [name=]<name>,string=<str>\n"
3776     "                add named fw_cfg entry with contents from string\n",
3777     QEMU_ARCH_ALL)
3778 SRST
3779 ``-fw_cfg [name=]name,file=file``
3780     Add named fw\_cfg entry with contents from file file.
3781
3782 ``-fw_cfg [name=]name,string=str``
3783     Add named fw\_cfg entry with contents from string str.
3784
3785     The terminating NUL character of the contents of str will not be
3786     included as part of the fw\_cfg item data. To insert contents with
3787     embedded NUL characters, you have to use the file parameter.
3788
3789     The fw\_cfg entries are passed by QEMU through to the guest.
3790
3791     Example:
3792
3793     ::
3794
3795             -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3796
3797     creates an fw\_cfg entry named opt/com.mycompany/blob with contents
3798     from ./my\_blob.bin.
3799 ERST
3800
3801 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
3802     "-serial dev     redirect the serial port to char device 'dev'\n",
3803     QEMU_ARCH_ALL)
3804 SRST
3805 ``-serial dev``
3806     Redirect the virtual serial port to host character device dev. The
3807     default device is ``vc`` in graphical mode and ``stdio`` in non
3808     graphical mode.
3809
3810     This option can be used several times to simulate up to 4 serial
3811     ports.
3812
3813     Use ``-serial none`` to disable all serial ports.
3814
3815     Available character devices are:
3816
3817     ``vc[:WxH]``
3818         Virtual console. Optionally, a width and height can be given in
3819         pixel with
3820
3821         ::
3822
3823             vc:800x600
3824
3825         It is also possible to specify width or height in characters:
3826
3827         ::
3828
3829             vc:80Cx24C
3830
3831     ``pty``
3832         [Linux only] Pseudo TTY (a new PTY is automatically allocated)
3833
3834     ``none``
3835         No device is allocated.
3836
3837     ``null``
3838         void device
3839
3840     ``chardev:id``
3841         Use a named character device defined with the ``-chardev``
3842         option.
3843
3844     ``/dev/XXX``
3845         [Linux only] Use host tty, e.g. ``/dev/ttyS0``. The host serial
3846         port parameters are set according to the emulated ones.
3847
3848     ``/dev/parportN``
3849         [Linux only, parallel port only] Use host parallel port N.
3850         Currently SPP and EPP parallel port features can be used.
3851
3852     ``file:filename``
3853         Write output to filename. No character can be read.
3854
3855     ``stdio``
3856         [Unix only] standard input/output
3857
3858     ``pipe:filename``
3859         name pipe filename
3860
3861     ``COMn``
3862         [Windows only] Use host serial port n
3863
3864     ``udp:[remote_host]:remote_port[@[src_ip]:src_port]``
3865         This implements UDP Net Console. When remote\_host or src\_ip
3866         are not specified they default to ``0.0.0.0``. When not using a
3867         specified src\_port a random port is automatically chosen.
3868
3869         If you just want a simple readonly console you can use
3870         ``netcat`` or ``nc``, by starting QEMU with:
3871         ``-serial udp::4555`` and nc as: ``nc -u -l -p 4555``. Any time
3872         QEMU writes something to that port it will appear in the
3873         netconsole session.
3874
3875         If you plan to send characters back via netconsole or you want
3876         to stop and start QEMU a lot of times, you should have QEMU use
3877         the same source port each time by using something like ``-serial
3878         udp::4555@:4556`` to QEMU. Another approach is to use a patched
3879         version of netcat which can listen to a TCP port and send and
3880         receive characters via udp. If you have a patched version of
3881         netcat which activates telnet remote echo and single char
3882         transfer, then you can use the following options to set up a
3883         netcat redirector to allow telnet on port 5555 to access the
3884         QEMU port.
3885
3886         ``QEMU Options:``
3887             -serial udp::4555@:4556
3888
3889         ``netcat options:``
3890             -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3891
3892         ``telnet options:``
3893             localhost 5555
3894
3895     ``tcp:[host]:port[,server=on|off][,wait=on|off][,nodelay=on|off][,reconnect=seconds]``
3896         The TCP Net Console has two modes of operation. It can send the
3897         serial I/O to a location or wait for a connection from a
3898         location. By default the TCP Net Console is sent to host at the
3899         port. If you use the ``server=on`` option QEMU will wait for a client
3900         socket application to connect to the port before continuing,
3901         unless the ``wait=on|off`` option was specified. The ``nodelay=on|off``
3902         option disables the Nagle buffering algorithm. The ``reconnect=on``
3903         option only applies if ``server=no`` is set, if the connection goes
3904         down it will attempt to reconnect at the given interval. If host
3905         is omitted, 0.0.0.0 is assumed. Only one TCP connection at a
3906         time is accepted. You can use ``telnet=on`` to connect to the
3907         corresponding character device.
3908
3909         ``Example to send tcp console to 192.168.0.2 port 4444``
3910             -serial tcp:192.168.0.2:4444
3911
3912         ``Example to listen and wait on port 4444 for connection``
3913             -serial tcp::4444,server=on
3914
3915         ``Example to not wait and listen on ip 192.168.0.100 port 4444``
3916             -serial tcp:192.168.0.100:4444,server=on,wait=off
3917
3918     ``telnet:host:port[,server=on|off][,wait=on|off][,nodelay=on|off]``
3919         The telnet protocol is used instead of raw tcp sockets. The
3920         options work the same as if you had specified ``-serial tcp``.
3921         The difference is that the port acts like a telnet server or
3922         client using telnet option negotiation. This will also allow you
3923         to send the MAGIC\_SYSRQ sequence if you use a telnet that
3924         supports sending the break sequence. Typically in unix telnet
3925         you do it with Control-] and then type "send break" followed by
3926         pressing the enter key.
3927
3928     ``websocket:host:port,server=on[,wait=on|off][,nodelay=on|off]``
3929         The WebSocket protocol is used instead of raw tcp socket. The
3930         port acts as a WebSocket server. Client mode is not supported.
3931
3932     ``unix:path[,server=on|off][,wait=on|off][,reconnect=seconds]``
3933         A unix domain socket is used instead of a tcp socket. The option
3934         works the same as if you had specified ``-serial tcp`` except
3935         the unix domain socket path is used for connections.
3936
3937     ``mon:dev_string``
3938         This is a special option to allow the monitor to be multiplexed
3939         onto another serial port. The monitor is accessed with key
3940         sequence of Control-a and then pressing c. dev\_string should be
3941         any one of the serial devices specified above. An example to
3942         multiplex the monitor onto a telnet server listening on port
3943         4444 would be:
3944
3945         ``-serial mon:telnet::4444,server=on,wait=off``
3946
3947         When the monitor is multiplexed to stdio in this way, Ctrl+C
3948         will not terminate QEMU any more but will be passed to the guest
3949         instead.
3950
3951     ``braille``
3952         Braille device. This will use BrlAPI to display the braille
3953         output on a real or fake device.
3954
3955     ``msmouse``
3956         Three button serial mouse. Configure the guest to use Microsoft
3957         protocol.
3958 ERST
3959
3960 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
3961     "-parallel dev   redirect the parallel port to char device 'dev'\n",
3962     QEMU_ARCH_ALL)
3963 SRST
3964 ``-parallel dev``
3965     Redirect the virtual parallel port to host device dev (same devices
3966     as the serial port). On Linux hosts, ``/dev/parportN`` can be used
3967     to use hardware devices connected on the corresponding host parallel
3968     port.
3969
3970     This option can be used several times to simulate up to 3 parallel
3971     ports.
3972
3973     Use ``-parallel none`` to disable all parallel ports.
3974 ERST
3975
3976 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
3977     "-monitor dev    redirect the monitor to char device 'dev'\n",
3978     QEMU_ARCH_ALL)
3979 SRST
3980 ``-monitor dev``
3981     Redirect the monitor to host device dev (same devices as the serial
3982     port). The default device is ``vc`` in graphical mode and ``stdio``
3983     in non graphical mode. Use ``-monitor none`` to disable the default
3984     monitor.
3985 ERST
3986 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
3987     "-qmp dev        like -monitor but opens in 'control' mode\n",
3988     QEMU_ARCH_ALL)
3989 SRST
3990 ``-qmp dev``
3991     Like -monitor but opens in 'control' mode.
3992 ERST
3993 DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \
3994     "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n",
3995     QEMU_ARCH_ALL)
3996 SRST
3997 ``-qmp-pretty dev``
3998     Like -qmp but uses pretty JSON formatting.
3999 ERST
4000
4001 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
4002     "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL)
4003 SRST
4004 ``-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]``
4005     Setup monitor on chardev name. ``mode=control`` configures 
4006     a QMP monitor (a JSON RPC-style protocol) and it is not the
4007     same as HMP, the human monitor that has a "(qemu)" prompt.
4008     ``pretty`` is only valid when ``mode=control``, 
4009     turning on JSON pretty printing to ease
4010     human reading and debugging.
4011 ERST
4012
4013 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
4014     "-debugcon dev   redirect the debug console to char device 'dev'\n",
4015     QEMU_ARCH_ALL)
4016 SRST
4017 ``-debugcon dev``
4018     Redirect the debug console to host device dev (same devices as the
4019     serial port). The debug console is an I/O port which is typically
4020     port 0xe9; writing to that I/O port sends output to this device. The
4021     default device is ``vc`` in graphical mode and ``stdio`` in non
4022     graphical mode.
4023 ERST
4024
4025 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
4026     "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
4027 SRST
4028 ``-pidfile file``
4029     Store the QEMU process PID in file. It is useful if you launch QEMU
4030     from a script.
4031 ERST
4032
4033 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
4034     "-singlestep     always run in singlestep mode\n", QEMU_ARCH_ALL)
4035 SRST
4036 ``-singlestep``
4037     Run the emulation in single step mode.
4038 ERST
4039
4040 DEF("preconfig", 0, QEMU_OPTION_preconfig, \
4041     "--preconfig     pause QEMU before machine is initialized (experimental)\n",
4042     QEMU_ARCH_ALL)
4043 SRST
4044 ``--preconfig``
4045     Pause QEMU for interactive configuration before the machine is
4046     created, which allows querying and configuring properties that will
4047     affect machine initialization. Use QMP command 'x-exit-preconfig' to
4048     exit the preconfig state and move to the next state (i.e. run guest
4049     if -S isn't used or pause the second time if -S is used). This
4050     option is experimental.
4051 ERST
4052
4053 DEF("S", 0, QEMU_OPTION_S, \
4054     "-S              freeze CPU at startup (use 'c' to start execution)\n",
4055     QEMU_ARCH_ALL)
4056 SRST
4057 ``-S``
4058     Do not start CPU at startup (you must type 'c' in the monitor).
4059 ERST
4060
4061 DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit,
4062     "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n"
4063     "                run qemu with overcommit hints\n"
4064     "                mem-lock=on|off controls memory lock support (default: off)\n"
4065     "                cpu-pm=on|off controls cpu power management (default: off)\n",
4066     QEMU_ARCH_ALL)
4067 SRST
4068 ``-overcommit mem-lock=on|off``
4069   \ 
4070 ``-overcommit cpu-pm=on|off``
4071     Run qemu with hints about host resource overcommit. The default is
4072     to assume that host overcommits all resources.
4073
4074     Locking qemu and guest memory can be enabled via ``mem-lock=on``
4075     (disabled by default). This works when host memory is not
4076     overcommitted and reduces the worst-case latency for guest.
4077
4078     Guest ability to manage power state of host cpus (increasing latency
4079     for other processes on the same host cpu, but decreasing latency for
4080     guest) can be enabled via ``cpu-pm=on`` (disabled by default). This
4081     works best when host CPU is not overcommitted. When used, host
4082     estimates of CPU cycle and power utilization will be incorrect, not
4083     taking into account guest idle time.
4084 ERST
4085
4086 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
4087     "-gdb dev        accept gdb connection on 'dev'. (QEMU defaults to starting\n"
4088     "                the guest without waiting for gdb to connect; use -S too\n"
4089     "                if you want it to not start execution.)\n",
4090     QEMU_ARCH_ALL)
4091 SRST
4092 ``-gdb dev``
4093     Accept a gdb connection on device dev (see the :ref:`GDB usage` chapter
4094     in the System Emulation Users Guide). Note that this option does not pause QEMU
4095     execution -- if you want QEMU to not start the guest until you
4096     connect with gdb and issue a ``continue`` command, you will need to
4097     also pass the ``-S`` option to QEMU.
4098
4099     The most usual configuration is to listen on a local TCP socket::
4100
4101         -gdb tcp::3117
4102
4103     but you can specify other backends; UDP, pseudo TTY, or even stdio
4104     are all reasonable use cases. For example, a stdio connection
4105     allows you to start QEMU from within gdb and establish the
4106     connection via a pipe:
4107
4108     .. parsed-literal::
4109
4110         (gdb) target remote | exec |qemu_system| -gdb stdio ...
4111 ERST
4112
4113 DEF("s", 0, QEMU_OPTION_s, \
4114     "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
4115     QEMU_ARCH_ALL)
4116 SRST
4117 ``-s``
4118     Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
4119     (see the :ref:`GDB usage` chapter in the System Emulation Users Guide).
4120 ERST
4121
4122 DEF("d", HAS_ARG, QEMU_OPTION_d, \
4123     "-d item1,...    enable logging of specified items (use '-d help' for a list of log items)\n",
4124     QEMU_ARCH_ALL)
4125 SRST
4126 ``-d item1[,...]``
4127     Enable logging of specified items. Use '-d help' for a list of log
4128     items.
4129 ERST
4130
4131 DEF("D", HAS_ARG, QEMU_OPTION_D, \