PPC: Enable doorbell excp handlers
[qemu.git] / qemu-options.hx
1 HXCOMM Use DEFHEADING() to define headings in both help text and texi
2 HXCOMM Text between STEXI and ETEXI are copied to texi version and
3 HXCOMM discarded from C version
4 HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
5 HXCOMM construct option structures, enums and help message for specified
6 HXCOMM architectures.
7 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
8
9 DEFHEADING(Standard options:)
10 STEXI
11 @table @option
12 ETEXI
13
14 DEF("help", 0, QEMU_OPTION_h,
15     "-h or -help     display this help and exit\n", QEMU_ARCH_ALL)
16 STEXI
17 @item -h
18 @findex -h
19 Display help and exit
20 ETEXI
21
22 DEF("version", 0, QEMU_OPTION_version,
23     "-version        display version information and exit\n", QEMU_ARCH_ALL)
24 STEXI
25 @item -version
26 @findex -version
27 Display version information and exit
28 ETEXI
29
30 DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
31     "-machine [type=]name[,prop[=value][,...]]\n"
32     "                selects emulated machine (-machine ? for list)\n"
33     "                property accel=accel1[:accel2[:...]] selects accelerator\n"
34     "                supported accelerators are kvm, xen, tcg (default: tcg)\n"
35     "                kernel_irqchip=on|off controls accelerated irqchip support\n",
36     QEMU_ARCH_ALL)
37 STEXI
38 @item -machine [type=]@var{name}[,prop=@var{value}[,...]]
39 @findex -machine
40 Select the emulated machine by @var{name}. Use @code{-machine ?} to list
41 available machines. Supported machine properties are:
42 @table @option
43 @item accel=@var{accels1}[:@var{accels2}[:...]]
44 This is used to enable an accelerator. Depending on the target architecture,
45 kvm, xen, or tcg can be available. By default, tcg is used. If there is more
46 than one accelerator specified, the next one is used if the previous one fails
47 to initialize.
48 @item kernel_irqchip=on|off
49 Enables in-kernel irqchip support for the chosen accelerator when available.
50 @end table
51 ETEXI
52
53 HXCOMM Deprecated by -machine
54 DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
55
56 DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
57     "-cpu cpu        select CPU (-cpu ? for list)\n", QEMU_ARCH_ALL)
58 STEXI
59 @item -cpu @var{model}
60 @findex -cpu
61 Select CPU model (-cpu ? for list and additional feature selection)
62 ETEXI
63
64 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
65     "-smp n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
66     "                set the number of CPUs to 'n' [default=1]\n"
67     "                maxcpus= maximum number of total cpus, including\n"
68     "                offline CPUs for hotplug, etc\n"
69     "                cores= number of CPU cores on one socket\n"
70     "                threads= number of threads on one CPU core\n"
71     "                sockets= number of discrete sockets in the system\n",
72         QEMU_ARCH_ALL)
73 STEXI
74 @item -smp @var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
75 @findex -smp
76 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
77 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
78 to 4.
79 For the PC target, the number of @var{cores} per socket, the number
80 of @var{threads} per cores and the total number of @var{sockets} can be
81 specified. Missing values will be computed. If any on the three values is
82 given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
83 specifies the maximum number of hotpluggable CPUs.
84 ETEXI
85
86 DEF("numa", HAS_ARG, QEMU_OPTION_numa,
87     "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
88 STEXI
89 @item -numa @var{opts}
90 @findex -numa
91 Simulate a multi node NUMA system. If mem and cpus are omitted, resources
92 are split equally.
93 ETEXI
94
95 DEF("fda", HAS_ARG, QEMU_OPTION_fda,
96     "-fda/-fdb file  use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
97 DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
98 STEXI
99 @item -fda @var{file}
100 @item -fdb @var{file}
101 @findex -fda
102 @findex -fdb
103 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
104 use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
105 ETEXI
106
107 DEF("hda", HAS_ARG, QEMU_OPTION_hda,
108     "-hda/-hdb file  use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
109 DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
110 DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
111     "-hdc/-hdd file  use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
112 DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
113 STEXI
114 @item -hda @var{file}
115 @item -hdb @var{file}
116 @item -hdc @var{file}
117 @item -hdd @var{file}
118 @findex -hda
119 @findex -hdb
120 @findex -hdc
121 @findex -hdd
122 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
123 ETEXI
124
125 DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
126     "-cdrom file     use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
127     QEMU_ARCH_ALL)
128 STEXI
129 @item -cdrom @var{file}
130 @findex -cdrom
131 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
132 @option{-cdrom} at the same time). You can use the host CD-ROM by
133 using @file{/dev/cdrom} as filename (@pxref{host_drives}).
134 ETEXI
135
136 DEF("drive", HAS_ARG, QEMU_OPTION_drive,
137     "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
138     "       [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
139     "       [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
140     "       [,serial=s][,addr=A][,id=name][,aio=threads|native]\n"
141     "       [,readonly=on|off][,copy-on-read=on|off]\n"
142     "       [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]][[,iops=i]|[[,iops_rd=r][,iops_wr=w]]\n"
143     "                use 'file' as a drive image\n", QEMU_ARCH_ALL)
144 STEXI
145 @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
146 @findex -drive
147
148 Define a new drive. Valid options are:
149
150 @table @option
151 @item file=@var{file}
152 This option defines which disk image (@pxref{disk_images}) to use with
153 this drive. If the filename contains comma, you must double it
154 (for instance, "file=my,,file" to use file "my,file").
155
156 Special files such as iSCSI devices can be specified using protocol
157 specific URLs. See the section for "Device URL Syntax" for more information.
158 @item if=@var{interface}
159 This option defines on which type on interface the drive is connected.
160 Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
161 @item bus=@var{bus},unit=@var{unit}
162 These options define where is connected the drive by defining the bus number and
163 the unit id.
164 @item index=@var{index}
165 This option defines where is connected the drive by using an index in the list
166 of available connectors of a given interface type.
167 @item media=@var{media}
168 This option defines the type of the media: disk or cdrom.
169 @item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
170 These options have the same definition as they have in @option{-hdachs}.
171 @item snapshot=@var{snapshot}
172 @var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
173 @item cache=@var{cache}
174 @var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data.
175 @item aio=@var{aio}
176 @var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
177 @item format=@var{format}
178 Specify which disk @var{format} will be used rather than detecting
179 the format.  Can be used to specifiy format=raw to avoid interpreting
180 an untrusted format header.
181 @item serial=@var{serial}
182 This option specifies the serial number to assign to the device.
183 @item addr=@var{addr}
184 Specify the controller's PCI address (if=virtio only).
185 @item werror=@var{action},rerror=@var{action}
186 Specify which @var{action} to take on write and read errors. Valid actions are:
187 "ignore" (ignore the error and try to continue), "stop" (pause QEMU),
188 "report" (report the error to the guest), "enospc" (pause QEMU only if the
189 host disk is full; report the error to the guest otherwise).
190 The default setting is @option{werror=enospc} and @option{rerror=report}.
191 @item readonly
192 Open drive @option{file} as read-only. Guest write attempts will fail.
193 @item copy-on-read=@var{copy-on-read}
194 @var{copy-on-read} is "on" or "off" and enables whether to copy read backing
195 file sectors into the image file.
196 @end table
197
198 By default, writethrough caching is used for all block device.  This means that
199 the host page cache will be used to read and write data but write notification
200 will be sent to the guest only when the data has been reported as written by
201 the storage subsystem.
202
203 Writeback caching will report data writes as completed as soon as the data is
204 present in the host page cache.  This is safe as long as you trust your host.
205 If your host crashes or loses power, then the guest may experience data
206 corruption.
207
208 The host page cache can be avoided entirely with @option{cache=none}.  This will
209 attempt to do disk IO directly to the guests memory.  QEMU may still perform
210 an internal copy of the data.
211
212 The host page cache can be avoided while only sending write notifications to
213 the guest when the data has been reported as written by the storage subsystem
214 using @option{cache=directsync}.
215
216 Some block drivers perform badly with @option{cache=writethrough}, most notably,
217 qcow2.  If performance is more important than correctness,
218 @option{cache=writeback} should be used with qcow2.
219
220 In case you don't care about data integrity over host failures, use
221 cache=unsafe. This option tells qemu that it never needs to write any data
222 to the disk but can instead keeps things in cache. If anything goes wrong,
223 like your host losing power, the disk storage getting disconnected accidentally,
224 etc. you're image will most probably be rendered unusable.   When using
225 the @option{-snapshot} option, unsafe caching is always used.
226
227 Copy-on-read avoids accessing the same backing file sectors repeatedly and is
228 useful when the backing file is over a slow network.  By default copy-on-read
229 is off.
230
231 Instead of @option{-cdrom} you can use:
232 @example
233 qemu -drive file=file,index=2,media=cdrom
234 @end example
235
236 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
237 use:
238 @example
239 qemu -drive file=file,index=0,media=disk
240 qemu -drive file=file,index=1,media=disk
241 qemu -drive file=file,index=2,media=disk
242 qemu -drive file=file,index=3,media=disk
243 @end example
244
245 You can connect a CDROM to the slave of ide0:
246 @example
247 qemu -drive file=file,if=ide,index=1,media=cdrom
248 @end example
249
250 If you don't specify the "file=" argument, you define an empty drive:
251 @example
252 qemu -drive if=ide,index=1,media=cdrom
253 @end example
254
255 You can connect a SCSI disk with unit ID 6 on the bus #0:
256 @example
257 qemu -drive file=file,if=scsi,bus=0,unit=6
258 @end example
259
260 Instead of @option{-fda}, @option{-fdb}, you can use:
261 @example
262 qemu -drive file=file,index=0,if=floppy
263 qemu -drive file=file,index=1,if=floppy
264 @end example
265
266 By default, @var{interface} is "ide" and @var{index} is automatically
267 incremented:
268 @example
269 qemu -drive file=a -drive file=b"
270 @end example
271 is interpreted like:
272 @example
273 qemu -hda a -hdb b
274 @end example
275 ETEXI
276
277 DEF("set", HAS_ARG, QEMU_OPTION_set,
278     "-set group.id.arg=value\n"
279     "                set <arg> parameter for item <id> of type <group>\n"
280     "                i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
281 STEXI
282 @item -set
283 @findex -set
284 TODO
285 ETEXI
286
287 DEF("global", HAS_ARG, QEMU_OPTION_global,
288     "-global driver.property=value\n"
289     "                set a global default for a driver property\n",
290     QEMU_ARCH_ALL)
291 STEXI
292 @item -global
293 @findex -global
294 TODO
295 ETEXI
296
297 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
298     "-mtdblock file  use 'file' as on-board Flash memory image\n",
299     QEMU_ARCH_ALL)
300 STEXI
301 @item -mtdblock @var{file}
302 @findex -mtdblock
303 Use @var{file} as on-board Flash memory image.
304 ETEXI
305
306 DEF("sd", HAS_ARG, QEMU_OPTION_sd,
307     "-sd file        use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
308 STEXI
309 @item -sd @var{file}
310 @findex -sd
311 Use @var{file} as SecureDigital card image.
312 ETEXI
313
314 DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
315     "-pflash file    use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
316 STEXI
317 @item -pflash @var{file}
318 @findex -pflash
319 Use @var{file} as a parallel flash image.
320 ETEXI
321
322 DEF("boot", HAS_ARG, QEMU_OPTION_boot,
323     "-boot [order=drives][,once=drives][,menu=on|off]\n"
324     "      [,splash=sp_name][,splash-time=sp_time]\n"
325     "                'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
326     "                'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
327     "                'sp_time': the period that splash picture last if menu=on, unit is ms\n",
328     QEMU_ARCH_ALL)
329 STEXI
330 @item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off][,splash=@var{sp_name}][,splash-time=@var{sp_time}]
331 @findex -boot
332 Specify boot order @var{drives} as a string of drive letters. Valid
333 drive letters depend on the target achitecture. The x86 PC uses: a, b
334 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
335 from network adapter 1-4), hard disk boot is the default. To apply a
336 particular boot order only on the first startup, specify it via
337 @option{once}.
338
339 Interactive boot menus/prompts can be enabled via @option{menu=on} as far
340 as firmware/BIOS supports them. The default is non-interactive boot.
341
342 A splash picture could be passed to bios, enabling user to show it as logo,
343 when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
344 supports them. Currently Seabios for X86 system support it.
345 limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
346 format(true color). The resolution should be supported by the SVGA mode, so
347 the recommended is 320x240, 640x480, 800x640.
348
349 @example
350 # try to boot from network first, then from hard disk
351 qemu -boot order=nc
352 # boot from CD-ROM first, switch back to default order after reboot
353 qemu -boot once=d
354 # boot with a splash picture for 5 seconds.
355 qemu -boot menu=on,splash=/root/boot.bmp,splash-time=5000
356 @end example
357
358 Note: The legacy format '-boot @var{drives}' is still supported but its
359 use is discouraged as it may be removed from future versions.
360 ETEXI
361
362 DEF("snapshot", 0, QEMU_OPTION_snapshot,
363     "-snapshot       write to temporary files instead of disk image files\n",
364     QEMU_ARCH_ALL)
365 STEXI
366 @item -snapshot
367 @findex -snapshot
368 Write to temporary files instead of disk image files. In this case,
369 the raw disk image you use is not written back. You can however force
370 the write back by pressing @key{C-a s} (@pxref{disk_images}).
371 ETEXI
372
373 DEF("m", HAS_ARG, QEMU_OPTION_m,
374     "-m megs         set virtual RAM size to megs MB [default="
375     stringify(DEFAULT_RAM_SIZE) "]\n", QEMU_ARCH_ALL)
376 STEXI
377 @item -m @var{megs}
378 @findex -m
379 Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
380 a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
381 gigabytes respectively.
382 ETEXI
383
384 DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
385     "-mem-path FILE  provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
386 STEXI
387 @item -mem-path @var{path}
388 Allocate guest RAM from a temporarily created file in @var{path}.
389 ETEXI
390
391 #ifdef MAP_POPULATE
392 DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
393     "-mem-prealloc   preallocate guest memory (use with -mem-path)\n",
394     QEMU_ARCH_ALL)
395 STEXI
396 @item -mem-prealloc
397 Preallocate memory when using -mem-path.
398 ETEXI
399 #endif
400
401 DEF("k", HAS_ARG, QEMU_OPTION_k,
402     "-k language     use keyboard layout (for example 'fr' for French)\n",
403     QEMU_ARCH_ALL)
404 STEXI
405 @item -k @var{language}
406 @findex -k
407 Use keyboard layout @var{language} (for example @code{fr} for
408 French). This option is only needed where it is not easy to get raw PC
409 keycodes (e.g. on Macs, with some X11 servers or with a VNC
410 display). You don't normally need to use it on PC/Linux or PC/Windows
411 hosts.
412
413 The available layouts are:
414 @example
415 ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
416 da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
417 de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
418 @end example
419
420 The default is @code{en-us}.
421 ETEXI
422
423
424 DEF("audio-help", 0, QEMU_OPTION_audio_help,
425     "-audio-help     print list of audio drivers and their options\n",
426     QEMU_ARCH_ALL)
427 STEXI
428 @item -audio-help
429 @findex -audio-help
430 Will show the audio subsystem help: list of drivers, tunable
431 parameters.
432 ETEXI
433
434 DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
435     "-soundhw c1,... enable audio support\n"
436     "                and only specified sound cards (comma separated list)\n"
437     "                use -soundhw ? to get the list of supported cards\n"
438     "                use -soundhw all to enable all of them\n", QEMU_ARCH_ALL)
439 STEXI
440 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
441 @findex -soundhw
442 Enable audio and selected sound hardware. Use ? to print all
443 available sound hardware.
444
445 @example
446 qemu -soundhw sb16,adlib disk.img
447 qemu -soundhw es1370 disk.img
448 qemu -soundhw ac97 disk.img
449 qemu -soundhw hda disk.img
450 qemu -soundhw all disk.img
451 qemu -soundhw ?
452 @end example
453
454 Note that Linux's i810_audio OSS kernel (for AC97) module might
455 require manually specifying clocking.
456
457 @example
458 modprobe i810_audio clocking=48000
459 @end example
460 ETEXI
461
462 DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
463     "-balloon none   disable balloon device\n"
464     "-balloon virtio[,addr=str]\n"
465     "                enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
466 STEXI
467 @item -balloon none
468 @findex -balloon
469 Disable balloon device.
470 @item -balloon virtio[,addr=@var{addr}]
471 Enable virtio balloon device (default), optionally with PCI address
472 @var{addr}.
473 ETEXI
474
475 STEXI
476 @end table
477 ETEXI
478
479 DEF("usb", 0, QEMU_OPTION_usb,
480     "-usb            enable the USB driver (will be the default soon)\n",
481     QEMU_ARCH_ALL)
482 STEXI
483 USB options:
484 @table @option
485
486 @item -usb
487 @findex -usb
488 Enable the USB driver (will be the default soon)
489 ETEXI
490
491 DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
492     "-usbdevice name add the host or guest USB device 'name'\n",
493     QEMU_ARCH_ALL)
494 STEXI
495
496 @item -usbdevice @var{devname}
497 @findex -usbdevice
498 Add the USB device @var{devname}. @xref{usb_devices}.
499
500 @table @option
501
502 @item mouse
503 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
504
505 @item tablet
506 Pointer device that uses absolute coordinates (like a touchscreen). This
507 means qemu is able to report the mouse position without having to grab the
508 mouse. Also overrides the PS/2 mouse emulation when activated.
509
510 @item disk:[format=@var{format}]:@var{file}
511 Mass storage device based on file. The optional @var{format} argument
512 will be used rather than detecting the format. Can be used to specifiy
513 @code{format=raw} to avoid interpreting an untrusted format header.
514
515 @item host:@var{bus}.@var{addr}
516 Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
517
518 @item host:@var{vendor_id}:@var{product_id}
519 Pass through the host device identified by @var{vendor_id}:@var{product_id}
520 (Linux only).
521
522 @item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
523 Serial converter to host character device @var{dev}, see @code{-serial} for the
524 available devices.
525
526 @item braille
527 Braille device.  This will use BrlAPI to display the braille output on a real
528 or fake device.
529
530 @item net:@var{options}
531 Network adapter that supports CDC ethernet and RNDIS protocols.
532
533 @end table
534 ETEXI
535
536 DEF("device", HAS_ARG, QEMU_OPTION_device,
537     "-device driver[,prop[=value][,...]]\n"
538     "                add device (based on driver)\n"
539     "                prop=value,... sets driver properties\n"
540     "                use -device ? to print all possible drivers\n"
541     "                use -device driver,? to print all possible properties\n",
542     QEMU_ARCH_ALL)
543 STEXI
544 @item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
545 @findex -device
546 Add device @var{driver}.  @var{prop}=@var{value} sets driver
547 properties.  Valid properties depend on the driver.  To get help on
548 possible drivers and properties, use @code{-device ?} and
549 @code{-device @var{driver},?}.
550 ETEXI
551
552 DEFHEADING()
553
554 DEFHEADING(File system options:)
555
556 DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
557     "-fsdev fsdriver,id=id[,path=path,][security_model={mapped|passthrough|none}]\n"
558     " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
559     QEMU_ARCH_ALL)
560
561 STEXI
562
563 @item -fsdev @var{fsdriver},id=@var{id},path=@var{path},[security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}]
564 @findex -fsdev
565 Define a new file system device. Valid options are:
566 @table @option
567 @item @var{fsdriver}
568 This option specifies the fs driver backend to use.
569 Currently "local", "handle" and "proxy" file system drivers are supported.
570 @item id=@var{id}
571 Specifies identifier for this device
572 @item path=@var{path}
573 Specifies the export path for the file system device. Files under
574 this path will be available to the 9p client on the guest.
575 @item security_model=@var{security_model}
576 Specifies the security model to be used for this export path.
577 Supported security models are "passthrough", "mapped" and "none".
578 In "passthrough" security model, files are stored using the same
579 credentials as they are created on the guest. This requires qemu
580 to run as root. In "mapped" security model, some of the file
581 attributes like uid, gid, mode bits and link target are stored as
582 file attributes. Directories exported by this security model cannot
583 interact with other unix tools. "none" security model is same as
584 passthrough except the sever won't report failures if it fails to
585 set file attributes like ownership. Security model is mandatory
586 only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
587 security model as a parameter.
588 @item writeout=@var{writeout}
589 This is an optional argument. The only supported value is "immediate".
590 This means that host page cache will be used to read and write data but
591 write notification will be sent to the guest only when the data has been
592 reported as written by the storage subsystem.
593 @item readonly
594 Enables exporting 9p share as a readonly mount for guests. By default
595 read-write access is given.
596 @item socket=@var{socket}
597 Enables proxy filesystem driver to use passed socket file for communicating
598 with virtfs-proxy-helper
599 @item sock_fd=@var{sock_fd}
600 Enables proxy filesystem driver to use passed socket descriptor for
601 communicating with virtfs-proxy-helper. Usually a helper like libvirt
602 will create socketpair and pass one of the fds as sock_fd
603 @end table
604
605 -fsdev option is used along with -device driver "virtio-9p-pci".
606 @item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
607 Options for virtio-9p-pci driver are:
608 @table @option
609 @item fsdev=@var{id}
610 Specifies the id value specified along with -fsdev option
611 @item mount_tag=@var{mount_tag}
612 Specifies the tag name to be used by the guest to mount this export point
613 @end table
614
615 ETEXI
616
617 DEFHEADING()
618
619 DEFHEADING(Virtual File system pass-through options:)
620
621 DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
622     "-virtfs local,path=path,mount_tag=tag,security_model=[mapped|passthrough|none]\n"
623     "        [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
624     QEMU_ARCH_ALL)
625
626 STEXI
627
628 @item -virtfs @var{fsdriver}[,path=@var{path}],mount_tag=@var{mount_tag}[,security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}]
629 @findex -virtfs
630
631 The general form of a Virtual File system pass-through options are:
632 @table @option
633 @item @var{fsdriver}
634 This option specifies the fs driver backend to use.
635 Currently "local", "handle" and "proxy" file system drivers are supported.
636 @item id=@var{id}
637 Specifies identifier for this device
638 @item path=@var{path}
639 Specifies the export path for the file system device. Files under
640 this path will be available to the 9p client on the guest.
641 @item security_model=@var{security_model}
642 Specifies the security model to be used for this export path.
643 Supported security models are "passthrough", "mapped" and "none".
644 In "passthrough" security model, files are stored using the same
645 credentials as they are created on the guest. This requires qemu
646 to run as root. In "mapped" security model, some of the file
647 attributes like uid, gid, mode bits and link target are stored as
648 file attributes. Directories exported by this security model cannot
649 interact with other unix tools. "none" security model is same as
650 passthrough except the sever won't report failures if it fails to
651 set file attributes like ownership. Security model is mandatory only
652 for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
653 model as a parameter.
654 @item writeout=@var{writeout}
655 This is an optional argument. The only supported value is "immediate".
656 This means that host page cache will be used to read and write data but
657 write notification will be sent to the guest only when the data has been
658 reported as written by the storage subsystem.
659 @item readonly
660 Enables exporting 9p share as a readonly mount for guests. By default
661 read-write access is given.
662 @item socket=@var{socket}
663 Enables proxy filesystem driver to use passed socket file for
664 communicating with virtfs-proxy-helper. Usually a helper like libvirt
665 will create socketpair and pass one of the fds as sock_fd
666 @item sock_fd
667 Enables proxy filesystem driver to use passed 'sock_fd' as the socket
668 descriptor for interfacing with virtfs-proxy-helper
669 @end table
670 ETEXI
671
672 DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
673     "-virtfs_synth Create synthetic file system image\n",
674     QEMU_ARCH_ALL)
675 STEXI
676 @item -virtfs_synth
677 @findex -virtfs_synth
678 Create synthetic file system image
679 ETEXI
680
681 DEFHEADING()
682
683 DEF("name", HAS_ARG, QEMU_OPTION_name,
684     "-name string1[,process=string2]\n"
685     "                set the name of the guest\n"
686     "                string1 sets the window title and string2 the process name (on Linux)\n",
687     QEMU_ARCH_ALL)
688 STEXI
689 @item -name @var{name}
690 @findex -name
691 Sets the @var{name} of the guest.
692 This name will be displayed in the SDL window caption.
693 The @var{name} will also be used for the VNC server.
694 Also optionally set the top visible process name in Linux.
695 ETEXI
696
697 DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
698     "-uuid %08x-%04x-%04x-%04x-%012x\n"
699     "                specify machine UUID\n", QEMU_ARCH_ALL)
700 STEXI
701 @item -uuid @var{uuid}
702 @findex -uuid
703 Set system UUID.
704 ETEXI
705
706 STEXI
707 @end table
708 ETEXI
709
710 DEFHEADING()
711
712 DEFHEADING(Display options:)
713
714 STEXI
715 @table @option
716 ETEXI
717
718 DEF("display", HAS_ARG, QEMU_OPTION_display,
719     "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
720     "            [,window_close=on|off]|curses|none|\n"
721     "            vnc=<display>[,<optargs>]\n"
722     "                select display type\n", QEMU_ARCH_ALL)
723 STEXI
724 @item -display @var{type}
725 @findex -display
726 Select type of display to use. This option is a replacement for the
727 old style -sdl/-curses/... options. Valid values for @var{type} are
728 @table @option
729 @item sdl
730 Display video output via SDL (usually in a separate graphics
731 window; see the SDL documentation for other possibilities).
732 @item curses
733 Display video output via curses. For graphics device models which
734 support a text mode, QEMU can display this output using a
735 curses/ncurses interface. Nothing is displayed when the graphics
736 device is in graphical mode or if the graphics device does not support
737 a text mode. Generally only the VGA device models support text mode.
738 @item none
739 Do not display video output. The guest will still see an emulated
740 graphics card, but its output will not be displayed to the QEMU
741 user. This option differs from the -nographic option in that it
742 only affects what is done with video output; -nographic also changes
743 the destination of the serial and parallel port data.
744 @item vnc
745 Start a VNC server on display <arg>
746 @end table
747 ETEXI
748
749 DEF("nographic", 0, QEMU_OPTION_nographic,
750     "-nographic      disable graphical output and redirect serial I/Os to console\n",
751     QEMU_ARCH_ALL)
752 STEXI
753 @item -nographic
754 @findex -nographic
755 Normally, QEMU uses SDL to display the VGA output. With this option,
756 you can totally disable graphical output so that QEMU is a simple
757 command line application. The emulated serial port is redirected on
758 the console. Therefore, you can still use QEMU to debug a Linux kernel
759 with a serial console.
760 ETEXI
761
762 DEF("curses", 0, QEMU_OPTION_curses,
763     "-curses         use a curses/ncurses interface instead of SDL\n",
764     QEMU_ARCH_ALL)
765 STEXI
766 @item -curses
767 @findex curses
768 Normally, QEMU uses SDL to display the VGA output.  With this option,
769 QEMU can display the VGA output when in text mode using a
770 curses/ncurses interface.  Nothing is displayed in graphical mode.
771 ETEXI
772
773 DEF("no-frame", 0, QEMU_OPTION_no_frame,
774     "-no-frame       open SDL window without a frame and window decorations\n",
775     QEMU_ARCH_ALL)
776 STEXI
777 @item -no-frame
778 @findex -no-frame
779 Do not use decorations for SDL windows and start them using the whole
780 available screen space. This makes the using QEMU in a dedicated desktop
781 workspace more convenient.
782 ETEXI
783
784 DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
785     "-alt-grab       use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
786     QEMU_ARCH_ALL)
787 STEXI
788 @item -alt-grab
789 @findex -alt-grab
790 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
791 affects the special keys (for fullscreen, monitor-mode switching, etc).
792 ETEXI
793
794 DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
795     "-ctrl-grab      use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
796     QEMU_ARCH_ALL)
797 STEXI
798 @item -ctrl-grab
799 @findex -ctrl-grab
800 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
801 affects the special keys (for fullscreen, monitor-mode switching, etc).
802 ETEXI
803
804 DEF("no-quit", 0, QEMU_OPTION_no_quit,
805     "-no-quit        disable SDL window close capability\n", QEMU_ARCH_ALL)
806 STEXI
807 @item -no-quit
808 @findex -no-quit
809 Disable SDL window close capability.
810 ETEXI
811
812 DEF("sdl", 0, QEMU_OPTION_sdl,
813     "-sdl            enable SDL\n", QEMU_ARCH_ALL)
814 STEXI
815 @item -sdl
816 @findex -sdl
817 Enable SDL.
818 ETEXI
819
820 DEF("spice", HAS_ARG, QEMU_OPTION_spice,
821     "-spice <args>   enable spice\n", QEMU_ARCH_ALL)
822 STEXI
823 @item -spice @var{option}[,@var{option}[,...]]
824 @findex -spice
825 Enable the spice remote desktop protocol. Valid options are
826
827 @table @option
828
829 @item port=<nr>
830 Set the TCP port spice is listening on for plaintext channels.
831
832 @item addr=<addr>
833 Set the IP address spice is listening on.  Default is any address.
834
835 @item ipv4
836 @item ipv6
837 Force using the specified IP version.
838
839 @item password=<secret>
840 Set the password you need to authenticate.
841
842 @item sasl
843 Require that the client use SASL to authenticate with the spice.
844 The exact choice of authentication method used is controlled from the
845 system / user's SASL configuration file for the 'qemu' service. This
846 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
847 unprivileged user, an environment variable SASL_CONF_PATH can be used
848 to make it search alternate locations for the service config.
849 While some SASL auth methods can also provide data encryption (eg GSSAPI),
850 it is recommended that SASL always be combined with the 'tls' and
851 'x509' settings to enable use of SSL and server certificates. This
852 ensures a data encryption preventing compromise of authentication
853 credentials.
854
855 @item disable-ticketing
856 Allow client connects without authentication.
857
858 @item disable-copy-paste
859 Disable copy paste between the client and the guest.
860
861 @item tls-port=<nr>
862 Set the TCP port spice is listening on for encrypted channels.
863
864 @item x509-dir=<dir>
865 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
866
867 @item x509-key-file=<file>
868 @item x509-key-password=<file>
869 @item x509-cert-file=<file>
870 @item x509-cacert-file=<file>
871 @item x509-dh-key-file=<file>
872 The x509 file names can also be configured individually.
873
874 @item tls-ciphers=<list>
875 Specify which ciphers to use.
876
877 @item tls-channel=[main|display|cursor|inputs|record|playback]
878 @item plaintext-channel=[main|display|cursor|inputs|record|playback]
879 Force specific channel to be used with or without TLS encryption.  The
880 options can be specified multiple times to configure multiple
881 channels.  The special name "default" can be used to set the default
882 mode.  For channels which are not explicitly forced into one mode the
883 spice client is allowed to pick tls/plaintext as he pleases.
884
885 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
886 Configure image compression (lossless).
887 Default is auto_glz.
888
889 @item jpeg-wan-compression=[auto|never|always]
890 @item zlib-glz-wan-compression=[auto|never|always]
891 Configure wan image compression (lossy for slow links).
892 Default is auto.
893
894 @item streaming-video=[off|all|filter]
895 Configure video stream detection.  Default is filter.
896
897 @item agent-mouse=[on|off]
898 Enable/disable passing mouse events via vdagent.  Default is on.
899
900 @item playback-compression=[on|off]
901 Enable/disable audio stream compression (using celt 0.5.1).  Default is on.
902
903 @end table
904 ETEXI
905
906 DEF("portrait", 0, QEMU_OPTION_portrait,
907     "-portrait       rotate graphical output 90 deg left (only PXA LCD)\n",
908     QEMU_ARCH_ALL)
909 STEXI
910 @item -portrait
911 @findex -portrait
912 Rotate graphical output 90 deg left (only PXA LCD).
913 ETEXI
914
915 DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
916     "-rotate <deg>   rotate graphical output some deg left (only PXA LCD)\n",
917     QEMU_ARCH_ALL)
918 STEXI
919 @item -rotate
920 @findex -rotate
921 Rotate graphical output some deg left (only PXA LCD).
922 ETEXI
923
924 DEF("vga", HAS_ARG, QEMU_OPTION_vga,
925     "-vga [std|cirrus|vmware|qxl|xenfb|none]\n"
926     "                select video card type\n", QEMU_ARCH_ALL)
927 STEXI
928 @item -vga @var{type}
929 @findex -vga
930 Select type of VGA card to emulate. Valid values for @var{type} are
931 @table @option
932 @item cirrus
933 Cirrus Logic GD5446 Video card. All Windows versions starting from
934 Windows 95 should recognize and use this graphic card. For optimal
935 performances, use 16 bit color depth in the guest and the host OS.
936 (This one is the default)
937 @item std
938 Standard VGA card with Bochs VBE extensions.  If your guest OS
939 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
940 to use high resolution modes (>= 1280x1024x16) then you should use
941 this option.
942 @item vmware
943 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
944 recent XFree86/XOrg server or Windows guest with a driver for this
945 card.
946 @item qxl
947 QXL paravirtual graphic card.  It is VGA compatible (including VESA
948 2.0 VBE support).  Works best with qxl guest drivers installed though.
949 Recommended choice when using the spice protocol.
950 @item none
951 Disable VGA card.
952 @end table
953 ETEXI
954
955 DEF("full-screen", 0, QEMU_OPTION_full_screen,
956     "-full-screen    start in full screen\n", QEMU_ARCH_ALL)
957 STEXI
958 @item -full-screen
959 @findex -full-screen
960 Start in full screen.
961 ETEXI
962
963 DEF("g", 1, QEMU_OPTION_g ,
964     "-g WxH[xDEPTH]  Set the initial graphical resolution and depth\n",
965     QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
966 STEXI
967 @item -g @var{width}x@var{height}[x@var{depth}]
968 @findex -g
969 Set the initial graphical resolution and depth (PPC, SPARC only).
970 ETEXI
971
972 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
973     "-vnc display    start a VNC server on display\n", QEMU_ARCH_ALL)
974 STEXI
975 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
976 @findex -vnc
977 Normally, QEMU uses SDL to display the VGA output.  With this option,
978 you can have QEMU listen on VNC display @var{display} and redirect the VGA
979 display over the VNC session.  It is very useful to enable the usb
980 tablet device when using this option (option @option{-usbdevice
981 tablet}). When using the VNC display, you must use the @option{-k}
982 parameter to set the keyboard layout if you are not using en-us. Valid
983 syntax for the @var{display} is
984
985 @table @option
986
987 @item @var{host}:@var{d}
988
989 TCP connections will only be allowed from @var{host} on display @var{d}.
990 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
991 be omitted in which case the server will accept connections from any host.
992
993 @item unix:@var{path}
994
995 Connections will be allowed over UNIX domain sockets where @var{path} is the
996 location of a unix socket to listen for connections on.
997
998 @item none
999
1000 VNC is initialized but not started. The monitor @code{change} command
1001 can be used to later start the VNC server.
1002
1003 @end table
1004
1005 Following the @var{display} value there may be one or more @var{option} flags
1006 separated by commas. Valid options are
1007
1008 @table @option
1009
1010 @item reverse
1011
1012 Connect to a listening VNC client via a ``reverse'' connection. The
1013 client is specified by the @var{display}. For reverse network
1014 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1015 is a TCP port number, not a display number.
1016
1017 @item password
1018
1019 Require that password based authentication is used for client connections.
1020 The password must be set separately using the @code{change} command in the
1021 @ref{pcsys_monitor}
1022
1023 @item tls
1024
1025 Require that client use TLS when communicating with the VNC server. This
1026 uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1027 attack. It is recommended that this option be combined with either the
1028 @option{x509} or @option{x509verify} options.
1029
1030 @item x509=@var{/path/to/certificate/dir}
1031
1032 Valid if @option{tls} is specified. Require that x509 credentials are used
1033 for negotiating the TLS session. The server will send its x509 certificate
1034 to the client. It is recommended that a password be set on the VNC server
1035 to provide authentication of the client when this is used. The path following
1036 this option specifies where the x509 certificates are to be loaded from.
1037 See the @ref{vnc_security} section for details on generating certificates.
1038
1039 @item x509verify=@var{/path/to/certificate/dir}
1040
1041 Valid if @option{tls} is specified. Require that x509 credentials are used
1042 for negotiating the TLS session. The server will send its x509 certificate
1043 to the client, and request that the client send its own x509 certificate.
1044 The server will validate the client's certificate against the CA certificate,
1045 and reject clients when validation fails. If the certificate authority is
1046 trusted, this is a sufficient authentication mechanism. You may still wish
1047 to set a password on the VNC server as a second authentication layer. The
1048 path following this option specifies where the x509 certificates are to
1049 be loaded from. See the @ref{vnc_security} section for details on generating
1050 certificates.
1051
1052 @item sasl
1053
1054 Require that the client use SASL to authenticate with the VNC server.
1055 The exact choice of authentication method used is controlled from the
1056 system / user's SASL configuration file for the 'qemu' service. This
1057 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1058 unprivileged user, an environment variable SASL_CONF_PATH can be used
1059 to make it search alternate locations for the service config.
1060 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1061 it is recommended that SASL always be combined with the 'tls' and
1062 'x509' settings to enable use of SSL and server certificates. This
1063 ensures a data encryption preventing compromise of authentication
1064 credentials. See the @ref{vnc_security} section for details on using
1065 SASL authentication.
1066
1067 @item acl
1068
1069 Turn on access control lists for checking of the x509 client certificate
1070 and SASL party. For x509 certs, the ACL check is made against the
1071 certificate's distinguished name. This is something that looks like
1072 @code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1073 made against the username, which depending on the SASL plugin, may
1074 include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1075 When the @option{acl} flag is set, the initial access list will be
1076 empty, with a @code{deny} policy. Thus no one will be allowed to
1077 use the VNC server until the ACLs have been loaded. This can be
1078 achieved using the @code{acl} monitor command.
1079
1080 @item lossy
1081
1082 Enable lossy compression methods (gradient, JPEG, ...). If this
1083 option is set, VNC client may receive lossy framebuffer updates
1084 depending on its encoding settings. Enabling this option can save
1085 a lot of bandwidth at the expense of quality.
1086
1087 @item non-adaptive
1088
1089 Disable adaptive encodings. Adaptive encodings are enabled by default.
1090 An adaptive encoding will try to detect frequently updated screen regions,
1091 and send updates in these regions using a lossy encoding (like JPEG).
1092 This can be really helpful to save bandwidth when playing videos. Disabling
1093 adaptive encodings allows to restore the original static behavior of encodings
1094 like Tight.
1095
1096 @end table
1097 ETEXI
1098
1099 STEXI
1100 @end table
1101 ETEXI
1102
1103 ARCHHEADING(, QEMU_ARCH_I386)
1104
1105 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
1106 STEXI
1107 @table @option
1108 ETEXI
1109
1110 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
1111     "-win2k-hack     use it when installing Windows 2000 to avoid a disk full bug\n",
1112     QEMU_ARCH_I386)
1113 STEXI
1114 @item -win2k-hack
1115 @findex -win2k-hack
1116 Use it when installing Windows 2000 to avoid a disk full bug. After
1117 Windows 2000 is installed, you no longer need this option (this option
1118 slows down the IDE transfers).
1119 ETEXI
1120
1121 HXCOMM Deprecated by -rtc
1122 DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
1123
1124 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
1125     "-no-fd-bootchk  disable boot signature checking for floppy disks\n",
1126     QEMU_ARCH_I386)
1127 STEXI
1128 @item -no-fd-bootchk
1129 @findex -no-fd-bootchk
1130 Disable boot signature checking for floppy disks in Bochs BIOS. It may
1131 be needed to boot from old floppy disks.
1132 TODO: check reference to Bochs BIOS.
1133 ETEXI
1134
1135 DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
1136            "-no-acpi        disable ACPI\n", QEMU_ARCH_I386)
1137 STEXI
1138 @item -no-acpi
1139 @findex -no-acpi
1140 Disable ACPI (Advanced Configuration and Power Interface) support. Use
1141 it if your guest OS complains about ACPI problems (PC target machine
1142 only).
1143 ETEXI
1144
1145 DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
1146     "-no-hpet        disable HPET\n", QEMU_ARCH_I386)
1147 STEXI
1148 @item -no-hpet
1149 @findex -no-hpet
1150 Disable HPET support.
1151 ETEXI
1152
1153 DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
1154     "-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"
1155     "                ACPI table description\n", QEMU_ARCH_I386)
1156 STEXI
1157 @item -acpitable [sig=@var{str}][,rev=@var{n}][,oem_id=@var{str}][,oem_table_id=@var{str}][,oem_rev=@var{n}] [,asl_compiler_id=@var{str}][,asl_compiler_rev=@var{n}][,data=@var{file1}[:@var{file2}]...]
1158 @findex -acpitable
1159 Add ACPI table with specified header fields and context from specified files.
1160 For file=, take whole ACPI table from the specified files, including all
1161 ACPI headers (possible overridden by other options).
1162 For data=, only data
1163 portion of the table is used, all header information is specified in the
1164 command line.
1165 ETEXI
1166
1167 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1168     "-smbios file=binary\n"
1169     "                load SMBIOS entry from binary file\n"
1170     "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1171     "                specify SMBIOS type 0 fields\n"
1172     "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1173     "              [,uuid=uuid][,sku=str][,family=str]\n"
1174     "                specify SMBIOS type 1 fields\n", QEMU_ARCH_I386)
1175 STEXI
1176 @item -smbios file=@var{binary}
1177 @findex -smbios
1178 Load SMBIOS entry from binary file.
1179
1180 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}]
1181 @findex -smbios
1182 Specify SMBIOS type 0 fields
1183
1184 @item -smbios type=1[,manufacturer=@var{str}][,product=@var{str}] [,version=@var{str}][,serial=@var{str}][,uuid=@var{uuid}][,sku=@var{str}] [,family=@var{str}]
1185 Specify SMBIOS type 1 fields
1186 ETEXI
1187
1188 DEFHEADING()
1189 STEXI
1190 @end table
1191 ETEXI
1192
1193 DEFHEADING(Network options:)
1194 STEXI
1195 @table @option
1196 ETEXI
1197
1198 HXCOMM Legacy slirp options (now moved to -net user):
1199 #ifdef CONFIG_SLIRP
1200 DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1201 DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1202 DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
1203 #ifndef _WIN32
1204 DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
1205 #endif
1206 #endif
1207
1208 DEF("net", HAS_ARG, QEMU_OPTION_net,
1209     "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1210     "                create a new Network Interface Card and connect it to VLAN 'n'\n"
1211 #ifdef CONFIG_SLIRP
1212     "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=on|off]\n"
1213     "         [,hostname=host][,dhcpstart=addr][,dns=addr][,tftp=dir][,bootfile=f]\n"
1214     "         [,hostfwd=rule][,guestfwd=rule]"
1215 #ifndef _WIN32
1216                                              "[,smb=dir[,smbserver=addr]]\n"
1217 #endif
1218     "                connect the user mode network stack to VLAN 'n', configure its\n"
1219     "                DHCP server and enabled optional services\n"
1220 #endif
1221 #ifdef _WIN32
1222     "-net tap[,vlan=n][,name=str],ifname=name\n"
1223     "                connect the host TAP network interface to VLAN 'n'\n"
1224 #else
1225     "-net tap[,vlan=n][,name=str][,fd=h][,ifname=name][,script=file][,downscript=dfile][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostforce=on|off]\n"
1226     "                connect the host TAP network interface to VLAN 'n' and use the\n"
1227     "                network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1228     "                and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1229     "                use '[down]script=no' to disable script execution\n"
1230     "                use 'fd=h' to connect to an already opened TAP interface\n"
1231     "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
1232     "                default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
1233     "                use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1234     "                use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
1235     "                use vhost=on to enable experimental in kernel accelerator\n"
1236     "                    (only has effect for virtio guests which use MSIX)\n"
1237     "                use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
1238     "                use 'vhostfd=h' to connect to an already opened vhost net device\n"
1239 #endif
1240     "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
1241     "                connect the vlan 'n' to another VLAN using a socket connection\n"
1242     "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1243     "                connect the vlan 'n' to multicast maddr and port\n"
1244     "                use 'localaddr=addr' to specify the host address to send packets from\n"
1245     "-net socket[,vlan=n][,name=str][,fd=h][,udp=host:port][,localaddr=host:port]\n"
1246     "                connect the vlan 'n' to another VLAN using an UDP tunnel\n"
1247 #ifdef CONFIG_VDE
1248     "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1249     "                connect the vlan 'n' to port 'n' of a vde switch running\n"
1250     "                on host and listening for incoming connections on 'socketpath'.\n"
1251     "                Use group 'groupname' and mode 'octalmode' to change default\n"
1252     "                ownership and permissions for communication port.\n"
1253 #endif
1254     "-net dump[,vlan=n][,file=f][,len=n]\n"
1255     "                dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
1256     "-net none       use it alone to have zero network devices. If no -net option\n"
1257     "                is provided, the default is '-net nic -net user'\n", QEMU_ARCH_ALL)
1258 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
1259     "-netdev ["
1260 #ifdef CONFIG_SLIRP
1261     "user|"
1262 #endif
1263     "tap|"
1264 #ifdef CONFIG_VDE
1265     "vde|"
1266 #endif
1267     "socket],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
1268 STEXI
1269 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
1270 @findex -net
1271 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
1272 = 0 is the default). The NIC is an e1000 by default on the PC
1273 target. Optionally, the MAC address can be changed to @var{mac}, the
1274 device address set to @var{addr} (PCI cards only),
1275 and a @var{name} can be assigned for use in monitor commands.
1276 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1277 that the card should have; this option currently only affects virtio cards; set
1278 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
1279 NIC is created.  Qemu can emulate several different models of network card.
1280 Valid values for @var{type} are
1281 @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
1282 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1283 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
1284 Not all devices are supported on all targets.  Use -net nic,model=?
1285 for a list of available devices for your target.
1286
1287 @item -net user[,@var{option}][,@var{option}][,...]
1288 Use the user mode network stack which requires no administrator
1289 privilege to run. Valid options are:
1290
1291 @table @option
1292 @item vlan=@var{n}
1293 Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1294
1295 @item name=@var{name}
1296 Assign symbolic name for use in monitor commands.
1297
1298 @item net=@var{addr}[/@var{mask}]
1299 Set IP network address the guest will see. Optionally specify the netmask,
1300 either in the form a.b.c.d or as number of valid top-most bits. Default is
1301 10.0.2.0/24.
1302
1303 @item host=@var{addr}
1304 Specify the guest-visible address of the host. Default is the 2nd IP in the
1305 guest network, i.e. x.x.x.2.
1306
1307 @item restrict=on|off
1308 If this option is enabled, the guest will be isolated, i.e. it will not be
1309 able to contact the host and no guest IP packets will be routed over the host
1310 to the outside. This option does not affect any explicitly set forwarding rules.
1311
1312 @item hostname=@var{name}
1313 Specifies the client hostname reported by the builtin DHCP server.
1314
1315 @item dhcpstart=@var{addr}
1316 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
1317 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
1318
1319 @item dns=@var{addr}
1320 Specify the guest-visible address of the virtual nameserver. The address must
1321 be different from the host address. Default is the 3rd IP in the guest network,
1322 i.e. x.x.x.3.
1323
1324 @item tftp=@var{dir}
1325 When using the user mode network stack, activate a built-in TFTP
1326 server. The files in @var{dir} will be exposed as the root of a TFTP server.
1327 The TFTP client on the guest must be configured in binary mode (use the command
1328 @code{bin} of the Unix TFTP client).
1329
1330 @item bootfile=@var{file}
1331 When using the user mode network stack, broadcast @var{file} as the BOOTP
1332 filename. In conjunction with @option{tftp}, this can be used to network boot
1333 a guest from a local directory.
1334
1335 Example (using pxelinux):
1336 @example
1337 qemu -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1338 @end example
1339
1340 @item smb=@var{dir}[,smbserver=@var{addr}]
1341 When using the user mode network stack, activate a built-in SMB
1342 server so that Windows OSes can access to the host files in @file{@var{dir}}
1343 transparently. The IP address of the SMB server can be set to @var{addr}. By
1344 default the 4th IP in the guest network is used, i.e. x.x.x.4.
1345
1346 In the guest Windows OS, the line:
1347 @example
1348 10.0.2.4 smbserver
1349 @end example
1350 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1351 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1352
1353 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1354
1355 Note that a SAMBA server must be installed on the host OS.
1356 QEMU was tested successfully with smbd versions from Red Hat 9,
1357 Fedora Core 3 and OpenSUSE 11.x.
1358
1359 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
1360 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1361 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1362 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
1363 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1364 be bound to a specific host interface. If no connection type is set, TCP is
1365 used. This option can be given multiple times.
1366
1367 For example, to redirect host X11 connection from screen 1 to guest
1368 screen 0, use the following:
1369
1370 @example
1371 # on the host
1372 qemu -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
1373 # this host xterm should open in the guest X11 server
1374 xterm -display :1
1375 @end example
1376
1377 To redirect telnet connections from host port 5555 to telnet port on
1378 the guest, use the following:
1379
1380 @example
1381 # on the host
1382 qemu -net user,hostfwd=tcp::5555-:23 [...]
1383 telnet localhost 5555
1384 @end example
1385
1386 Then when you use on the host @code{telnet localhost 5555}, you
1387 connect to the guest telnet server.
1388
1389 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
1390 Forward guest TCP connections to the IP address @var{server} on port @var{port}
1391 to the character device @var{dev}. This option can be given multiple times.
1392
1393 @end table
1394
1395 Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
1396 processed and applied to -net user. Mixing them with the new configuration
1397 syntax gives undefined results. Their use for new applications is discouraged
1398 as they will be removed from future versions.
1399
1400 @item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}] [,script=@var{file}][,downscript=@var{dfile}]
1401 Connect the host TAP network interface @var{name} to VLAN @var{n}, use
1402 the network script @var{file} to configure it and the network script
1403 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
1404 automatically provides one. @option{fd}=@var{h} can be used to specify
1405 the handle of an already opened host TAP interface. The default network
1406 configure script is @file{/etc/qemu-ifup} and the default network
1407 deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no}
1408 or @option{downscript=no} to disable script execution. Example:
1409
1410 @example
1411 qemu linux.img -net nic -net tap
1412 @end example
1413
1414 More complicated example (two NICs, each one connected to a TAP device)
1415 @example
1416 qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1417                -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
1418 @end example
1419
1420 @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1421
1422 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1423 machine using a TCP socket connection. If @option{listen} is
1424 specified, QEMU waits for incoming connections on @var{port}
1425 (@var{host} is optional). @option{connect} is used to connect to
1426 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1427 specifies an already opened TCP socket.
1428
1429 Example:
1430 @example
1431 # launch a first QEMU instance
1432 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1433                -net socket,listen=:1234
1434 # connect the VLAN 0 of this instance to the VLAN 0
1435 # of the first instance
1436 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1437                -net socket,connect=127.0.0.1:1234
1438 @end example
1439
1440 @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1441
1442 Create a VLAN @var{n} shared with another QEMU virtual
1443 machines using a UDP multicast socket, effectively making a bus for
1444 every QEMU with same multicast address @var{maddr} and @var{port}.
1445 NOTES:
1446 @enumerate
1447 @item
1448 Several QEMU can be running on different hosts and share same bus (assuming
1449 correct multicast setup for these hosts).
1450 @item
1451 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1452 @url{http://user-mode-linux.sf.net}.
1453 @item
1454 Use @option{fd=h} to specify an already opened UDP multicast socket.
1455 @end enumerate
1456
1457 Example:
1458 @example
1459 # launch one QEMU instance
1460 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1461                -net socket,mcast=230.0.0.1:1234
1462 # launch another QEMU instance on same "bus"
1463 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1464                -net socket,mcast=230.0.0.1:1234
1465 # launch yet another QEMU instance on same "bus"
1466 qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
1467                -net socket,mcast=230.0.0.1:1234
1468 @end example
1469
1470 Example (User Mode Linux compat.):
1471 @example
1472 # launch QEMU instance (note mcast address selected
1473 # is UML's default)
1474 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1475                -net socket,mcast=239.192.168.1:1102
1476 # launch UML
1477 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
1478 @end example
1479
1480 Example (send packets from host's 1.2.3.4):
1481 @example
1482 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1483                -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
1484 @end example
1485
1486 @item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
1487 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
1488 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
1489 and MODE @var{octalmode} to change default ownership and permissions for
1490 communication port. This option is only available if QEMU has been compiled
1491 with vde support enabled.
1492
1493 Example:
1494 @example
1495 # launch vde switch
1496 vde_switch -F -sock /tmp/myswitch
1497 # launch QEMU instance
1498 qemu linux.img -net nic -net vde,sock=/tmp/myswitch
1499 @end example
1500
1501 @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
1502 Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
1503 At most @var{len} bytes (64k by default) per packet are stored. The file format is
1504 libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
1505
1506 @item -net none
1507 Indicate that no network devices should be configured. It is used to
1508 override the default configuration (@option{-net nic -net user}) which
1509 is activated if no @option{-net} options are provided.
1510
1511 @end table
1512 ETEXI
1513
1514 DEFHEADING()
1515
1516 DEFHEADING(Character device options:)
1517
1518 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
1519     "-chardev null,id=id[,mux=on|off]\n"
1520     "-chardev socket,id=id[,host=host],port=host[,to=to][,ipv4][,ipv6][,nodelay]\n"
1521     "         [,server][,nowait][,telnet][,mux=on|off] (tcp)\n"
1522     "-chardev socket,id=id,path=path[,server][,nowait][,telnet],[mux=on|off] (unix)\n"
1523     "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
1524     "         [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
1525     "-chardev msmouse,id=id[,mux=on|off]\n"
1526     "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
1527     "         [,mux=on|off]\n"
1528     "-chardev file,id=id,path=path[,mux=on|off]\n"
1529     "-chardev pipe,id=id,path=path[,mux=on|off]\n"
1530 #ifdef _WIN32
1531     "-chardev console,id=id[,mux=on|off]\n"
1532     "-chardev serial,id=id,path=path[,mux=on|off]\n"
1533 #else
1534     "-chardev pty,id=id[,mux=on|off]\n"
1535     "-chardev stdio,id=id[,mux=on|off][,signal=on|off]\n"
1536 #endif
1537 #ifdef CONFIG_BRLAPI
1538     "-chardev braille,id=id[,mux=on|off]\n"
1539 #endif
1540 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
1541         || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
1542     "-chardev tty,id=id,path=path[,mux=on|off]\n"
1543 #endif
1544 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
1545     "-chardev parport,id=id,path=path[,mux=on|off]\n"
1546 #endif
1547 #if defined(CONFIG_SPICE)
1548     "-chardev spicevmc,id=id,name=name[,debug=debug]\n"
1549 #endif
1550     , QEMU_ARCH_ALL
1551 )
1552
1553 STEXI
1554
1555 The general form of a character device option is:
1556 @table @option
1557
1558 @item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
1559 @findex -chardev
1560 Backend is one of:
1561 @option{null},
1562 @option{socket},
1563 @option{udp},
1564 @option{msmouse},
1565 @option{vc},
1566 @option{file},
1567 @option{pipe},
1568 @option{console},
1569 @option{serial},
1570 @option{pty},
1571 @option{stdio},
1572 @option{braille},
1573 @option{tty},
1574 @option{parport},
1575 @option{spicevmc}.
1576 The specific backend will determine the applicable options.
1577
1578 All devices must have an id, which can be any string up to 127 characters long.
1579 It is used to uniquely identify this device in other command line directives.
1580
1581 A character device may be used in multiplexing mode by multiple front-ends.
1582 The key sequence of @key{Control-a} and @key{c} will rotate the input focus
1583 between attached front-ends. Specify @option{mux=on} to enable this mode.
1584
1585 Options to each backend are described below.
1586
1587 @item -chardev null ,id=@var{id}
1588 A void device. This device will not emit any data, and will drop any data it
1589 receives. The null backend does not take any options.
1590
1591 @item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet]
1592
1593 Create a two-way stream socket, which can be either a TCP or a unix socket. A
1594 unix socket will be created if @option{path} is specified. Behaviour is
1595 undefined if TCP options are specified for a unix socket.
1596
1597 @option{server} specifies that the socket shall be a listening socket.
1598
1599 @option{nowait} specifies that QEMU should not block waiting for a client to
1600 connect to a listening socket.
1601
1602 @option{telnet} specifies that traffic on the socket should interpret telnet
1603 escape sequences.
1604
1605 TCP and unix socket options are given below:
1606
1607 @table @option
1608
1609 @item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
1610
1611 @option{host} for a listening socket specifies the local address to be bound.
1612 For a connecting socket species the remote host to connect to. @option{host} is
1613 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
1614
1615 @option{port} for a listening socket specifies the local port to be bound. For a
1616 connecting socket specifies the port on the remote host to connect to.
1617 @option{port} can be given as either a port number or a service name.
1618 @option{port} is required.
1619
1620 @option{to} is only relevant to listening sockets. If it is specified, and
1621 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
1622 to and including @option{to} until it succeeds. @option{to} must be specified
1623 as a port number.
1624
1625 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
1626 If neither is specified the socket may use either protocol.
1627
1628 @option{nodelay} disables the Nagle algorithm.
1629
1630 @item unix options: path=@var{path}
1631
1632 @option{path} specifies the local path of the unix socket. @option{path} is
1633 required.
1634
1635 @end table
1636
1637 @item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
1638
1639 Sends all traffic from the guest to a remote host over UDP.
1640
1641 @option{host} specifies the remote host to connect to. If not specified it
1642 defaults to @code{localhost}.
1643
1644 @option{port} specifies the port on the remote host to connect to. @option{port}
1645 is required.
1646
1647 @option{localaddr} specifies the local address to bind to. If not specified it
1648 defaults to @code{0.0.0.0}.
1649
1650 @option{localport} specifies the local port to bind to. If not specified any
1651 available local port will be used.
1652
1653 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
1654 If neither is specified the device may use either protocol.
1655
1656 @item -chardev msmouse ,id=@var{id}
1657
1658 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
1659 take any options.
1660
1661 @item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
1662
1663 Connect to a QEMU text console. @option{vc} may optionally be given a specific
1664 size.
1665
1666 @option{width} and @option{height} specify the width and height respectively of
1667 the console, in pixels.
1668
1669 @option{cols} and @option{rows} specify that the console be sized to fit a text
1670 console with the given dimensions.
1671
1672 @item -chardev file ,id=@var{id} ,path=@var{path}
1673
1674 Log all traffic received from the guest to a file.
1675
1676 @option{path} specifies the path of the file to be opened. This file will be
1677 created if it does not already exist, and overwritten if it does. @option{path}
1678 is required.
1679
1680 @item -chardev pipe ,id=@var{id} ,path=@var{path}
1681
1682 Create a two-way connection to the guest. The behaviour differs slightly between
1683 Windows hosts and other hosts:
1684
1685 On Windows, a single duplex pipe will be created at
1686 @file{\\.pipe\@option{path}}.
1687
1688 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
1689 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
1690 received by the guest. Data written by the guest can be read from
1691 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
1692 be present.
1693
1694 @option{path} forms part of the pipe path as described above. @option{path} is
1695 required.
1696
1697 @item -chardev console ,id=@var{id}
1698
1699 Send traffic from the guest to QEMU's standard output. @option{console} does not
1700 take any options.
1701
1702 @option{console} is only available on Windows hosts.
1703
1704 @item -chardev serial ,id=@var{id} ,path=@option{path}
1705
1706 Send traffic from the guest to a serial device on the host.
1707
1708 @option{serial} is
1709 only available on Windows hosts.
1710
1711 @option{path} specifies the name of the serial device to open.
1712
1713 @item -chardev pty ,id=@var{id}
1714
1715 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
1716 not take any options.
1717
1718 @option{pty} is not available on Windows hosts.
1719
1720 @item -chardev stdio ,id=@var{id} [,signal=on|off]
1721 Connect to standard input and standard output of the qemu process.
1722
1723 @option{signal} controls if signals are enabled on the terminal, that includes
1724 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
1725 default, use @option{signal=off} to disable it.
1726
1727 @option{stdio} is not available on Windows hosts.
1728
1729 @item -chardev braille ,id=@var{id}
1730
1731 Connect to a local BrlAPI server. @option{braille} does not take any options.
1732
1733 @item -chardev tty ,id=@var{id} ,path=@var{path}
1734
1735 Connect to a local tty device.
1736
1737 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
1738 DragonFlyBSD hosts.
1739
1740 @option{path} specifies the path to the tty. @option{path} is required.
1741
1742 @item -chardev parport ,id=@var{id} ,path=@var{path}
1743
1744 @option{parport} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
1745
1746 Connect to a local parallel port.
1747
1748 @option{path} specifies the path to the parallel port device. @option{path} is
1749 required.
1750
1751 @item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
1752
1753 @option{spicevmc} is only available when spice support is built in.
1754
1755 @option{debug} debug level for spicevmc
1756
1757 @option{name} name of spice channel to connect to
1758
1759 Connect to a spice virtual machine channel, such as vdiport.
1760
1761 @end table
1762 ETEXI
1763
1764 DEFHEADING()
1765
1766 STEXI
1767 DEFHEADING(Device URL Syntax:)
1768
1769 In addition to using normal file images for the emulated storage devices,
1770 QEMU can also use networked resources such as iSCSI devices. These are
1771 specified using a special URL syntax.
1772
1773 @table @option
1774 @item iSCSI
1775 iSCSI support allows QEMU to access iSCSI resources directly and use as
1776 images for the guest storage. Both disk and cdrom images are supported.
1777
1778 Syntax for specifying iSCSI LUNs is
1779 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
1780
1781 Example (without authentication):
1782 @example
1783 qemu -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
1784 --drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
1785 @end example
1786
1787 Example (CHAP username/password via URL):
1788 @example
1789 qemu --drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
1790 @end example
1791
1792 Example (CHAP username/password via environment variables):
1793 @example
1794 LIBISCSI_CHAP_USERNAME="user" \
1795 LIBISCSI_CHAP_PASSWORD="password" \
1796 qemu --drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
1797 @end example
1798
1799 iSCSI support is an optional feature of QEMU and only available when
1800 compiled and linked against libiscsi.
1801
1802 @item NBD
1803 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
1804 as Unix Domain Sockets.
1805
1806 Syntax for specifying a NBD device using TCP
1807 ``nbd:<server-ip>:<port>[:exportname=<export>]''
1808
1809 Syntax for specifying a NBD device using Unix Domain Sockets
1810 ``nbd:unix:<domain-socket>[:exportname=<export>]''
1811
1812
1813 Example for TCP
1814 @example
1815 qemu --drive file=nbd:192.0.2.1:30000
1816 @end example
1817
1818 Example for Unix Domain Sockets
1819 @example
1820 qemu --drive file=nbd:unix:/tmp/nbd-socket
1821 @end example
1822
1823 @item Sheepdog
1824 Sheepdog is a distributed storage system for QEMU.
1825 QEMU supports using either local sheepdog devices or remote networked
1826 devices.
1827
1828 Syntax for specifying a sheepdog device
1829 @table @list
1830 ``sheepdog:<vdiname>''
1831
1832 ``sheepdog:<vdiname>:<snapid>''
1833
1834 ``sheepdog:<vdiname>:<tag>''
1835
1836 ``sheepdog:<host>:<port>:<vdiname>''
1837
1838 ``sheepdog:<host>:<port>:<vdiname>:<snapid>''
1839
1840 ``sheepdog:<host>:<port>:<vdiname>:<tag>''
1841 @end table
1842
1843 Example
1844 @example
1845 qemu --drive file=sheepdog:192.0.2.1:30000:MyVirtualMachine
1846 @end example
1847
1848 See also @url{http://http://www.osrg.net/sheepdog/}.
1849
1850 @end table
1851 ETEXI
1852
1853 DEFHEADING(Bluetooth(R) options:)
1854
1855 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
1856     "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
1857     "-bt hci,host[:id]\n" \
1858     "                use host's HCI with the given name\n" \
1859     "-bt hci[,vlan=n]\n" \
1860     "                emulate a standard HCI in virtual scatternet 'n'\n" \
1861     "-bt vhci[,vlan=n]\n" \
1862     "                add host computer to virtual scatternet 'n' using VHCI\n" \
1863     "-bt device:dev[,vlan=n]\n" \
1864     "                emulate a bluetooth device 'dev' in scatternet 'n'\n",
1865     QEMU_ARCH_ALL)
1866 STEXI
1867 @table @option
1868
1869 @item -bt hci[...]
1870 @findex -bt
1871 Defines the function of the corresponding Bluetooth HCI.  -bt options
1872 are matched with the HCIs present in the chosen machine type.  For
1873 example when emulating a machine with only one HCI built into it, only
1874 the first @code{-bt hci[...]} option is valid and defines the HCI's
1875 logic.  The Transport Layer is decided by the machine type.  Currently
1876 the machines @code{n800} and @code{n810} have one HCI and all other
1877 machines have none.
1878
1879 @anchor{bt-hcis}
1880 The following three types are recognized:
1881
1882 @table @option
1883 @item -bt hci,null
1884 (default) The corresponding Bluetooth HCI assumes no internal logic
1885 and will not respond to any HCI commands or emit events.
1886
1887 @item -bt hci,host[:@var{id}]
1888 (@code{bluez} only) The corresponding HCI passes commands / events
1889 to / from the physical HCI identified by the name @var{id} (default:
1890 @code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
1891 capable systems like Linux.
1892
1893 @item -bt hci[,vlan=@var{n}]
1894 Add a virtual, standard HCI that will participate in the Bluetooth
1895 scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
1896 VLANs, devices inside a bluetooth network @var{n} can only communicate
1897 with other devices in the same network (scatternet).
1898 @end table
1899
1900 @item -bt vhci[,vlan=@var{n}]
1901 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
1902 to the host bluetooth stack instead of to the emulated target.  This
1903 allows the host and target machines to participate in a common scatternet
1904 and communicate.  Requires the Linux @code{vhci} driver installed.  Can
1905 be used as following:
1906
1907 @example
1908 qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
1909 @end example
1910
1911 @item -bt device:@var{dev}[,vlan=@var{n}]
1912 Emulate a bluetooth device @var{dev} and place it in network @var{n}
1913 (default @code{0}).  QEMU can only emulate one type of bluetooth devices
1914 currently:
1915
1916 @table @option
1917 @item keyboard
1918 Virtual wireless keyboard implementing the HIDP bluetooth profile.
1919 @end table
1920 @end table
1921 ETEXI
1922
1923 DEFHEADING()
1924
1925 DEFHEADING(Linux/Multiboot boot specific:)
1926 STEXI
1927
1928 When using these options, you can use a given Linux or Multiboot
1929 kernel without installing it in the disk image. It can be useful
1930 for easier testing of various kernels.
1931
1932 @table @option
1933 ETEXI
1934
1935 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
1936     "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
1937 STEXI
1938 @item -kernel @var{bzImage}
1939 @findex -kernel
1940 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
1941 or in multiboot format.
1942 ETEXI
1943
1944 DEF("append", HAS_ARG, QEMU_OPTION_append, \
1945     "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
1946 STEXI
1947 @item -append @var{cmdline}
1948 @findex -append
1949 Use @var{cmdline} as kernel command line
1950 ETEXI
1951
1952 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
1953            "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
1954 STEXI
1955 @item -initrd @var{file}
1956 @findex -initrd
1957 Use @var{file} as initial ram disk.
1958
1959 @item -initrd "@var{file1} arg=foo,@var{file2}"
1960
1961 This syntax is only available with multiboot.
1962
1963 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
1964 first module.
1965 ETEXI
1966
1967 STEXI
1968 @end table
1969 ETEXI
1970
1971 DEFHEADING()
1972
1973 DEFHEADING(Debug/Expert options:)
1974
1975 STEXI
1976 @table @option
1977 ETEXI
1978
1979 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
1980     "-serial dev     redirect the serial port to char device 'dev'\n",
1981     QEMU_ARCH_ALL)
1982 STEXI
1983 @item -serial @var{dev}
1984 @findex -serial
1985 Redirect the virtual serial port to host character device
1986 @var{dev}. The default device is @code{vc} in graphical mode and
1987 @code{stdio} in non graphical mode.
1988
1989 This option can be used several times to simulate up to 4 serial
1990 ports.
1991
1992 Use @code{-serial none} to disable all serial ports.
1993
1994 Available character devices are:
1995 @table @option
1996 @item vc[:@var{W}x@var{H}]
1997 Virtual console. Optionally, a width and height can be given in pixel with
1998 @example
1999 vc:800x600
2000 @end example
2001 It is also possible to specify width or height in characters:
2002 @example
2003 vc:80Cx24C
2004 @end example
2005 @item pty
2006 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
2007 @item none
2008 No device is allocated.
2009 @item null
2010 void device
2011 @item /dev/XXX
2012 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
2013 parameters are set according to the emulated ones.
2014 @item /dev/parport@var{N}
2015 [Linux only, parallel port only] Use host parallel port
2016 @var{N}. Currently SPP and EPP parallel port features can be used.
2017 @item file:@var{filename}
2018 Write output to @var{filename}. No character can be read.
2019 @item stdio
2020 [Unix only] standard input/output
2021 @item pipe:@var{filename}
2022 name pipe @var{filename}
2023 @item COM@var{n}
2024 [Windows only] Use host serial port @var{n}
2025 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
2026 This implements UDP Net Console.
2027 When @var{remote_host} or @var{src_ip} are not specified
2028 they default to @code{0.0.0.0}.
2029 When not using a specified @var{src_port} a random port is automatically chosen.
2030
2031 If you just want a simple readonly console you can use @code{netcat} or
2032 @code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
2033 @code{nc -u -l -p 4555}. Any time qemu writes something to that port it
2034 will appear in the netconsole session.
2035
2036 If you plan to send characters back via netconsole or you want to stop
2037 and start qemu a lot of times, you should have qemu use the same
2038 source port each time by using something like @code{-serial
2039 udp::4555@@:4556} to qemu. Another approach is to use a patched
2040 version of netcat which can listen to a TCP port and send and receive
2041 characters via udp.  If you have a patched version of netcat which
2042 activates telnet remote echo and single char transfer, then you can
2043 use the following options to step up a netcat redirector to allow
2044 telnet on port 5555 to access the qemu port.
2045 @table @code
2046 @item Qemu Options:
2047 -serial udp::4555@@:4556
2048 @item netcat options:
2049 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2050 @item telnet options:
2051 localhost 5555
2052 @end table
2053
2054 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
2055 The TCP Net Console has two modes of operation.  It can send the serial
2056 I/O to a location or wait for a connection from a location.  By default
2057 the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
2058 the @var{server} option QEMU will wait for a client socket application
2059 to connect to the port before continuing, unless the @code{nowait}
2060 option was specified.  The @code{nodelay} option disables the Nagle buffering
2061 algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
2062 one TCP connection at a time is accepted. You can use @code{telnet} to
2063 connect to the corresponding character device.
2064 @table @code
2065 @item Example to send tcp console to 192.168.0.2 port 4444
2066 -serial tcp:192.168.0.2:4444
2067 @item Example to listen and wait on port 4444 for connection
2068 -serial tcp::4444,server
2069 @item Example to not wait and listen on ip 192.168.0.100 port 4444
2070 -serial tcp:192.168.0.100:4444,server,nowait
2071 @end table
2072
2073 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
2074 The telnet protocol is used instead of raw tcp sockets.  The options
2075 work the same as if you had specified @code{-serial tcp}.  The
2076 difference is that the port acts like a telnet server or client using
2077 telnet option negotiation.  This will also allow you to send the
2078 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
2079 sequence.  Typically in unix telnet you do it with Control-] and then
2080 type "send break" followed by pressing the enter key.
2081
2082 @item unix:@var{path}[,server][,nowait]
2083 A unix domain socket is used instead of a tcp socket.  The option works the
2084 same as if you had specified @code{-serial tcp} except the unix domain socket
2085 @var{path} is used for connections.
2086
2087 @item mon:@var{dev_string}
2088 This is a special option to allow the monitor to be multiplexed onto
2089 another serial port.  The monitor is accessed with key sequence of
2090 @key{Control-a} and then pressing @key{c}. See monitor access
2091 @ref{pcsys_keys} in the -nographic section for more keys.
2092 @var{dev_string} should be any one of the serial devices specified
2093 above.  An example to multiplex the monitor onto a telnet server
2094 listening on port 4444 would be:
2095 @table @code
2096 @item -serial mon:telnet::4444,server,nowait
2097 @end table
2098
2099 @item braille
2100 Braille device.  This will use BrlAPI to display the braille output on a real
2101 or fake device.
2102
2103 @item msmouse
2104 Three button serial mouse. Configure the guest to use Microsoft protocol.
2105 @end table
2106 ETEXI
2107
2108 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
2109     "-parallel dev   redirect the parallel port to char device 'dev'\n",
2110     QEMU_ARCH_ALL)
2111 STEXI
2112 @item -parallel @var{dev}
2113 @findex -parallel
2114 Redirect the virtual parallel port to host device @var{dev} (same
2115 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
2116 be used to use hardware devices connected on the corresponding host
2117 parallel port.
2118
2119 This option can be used several times to simulate up to 3 parallel
2120 ports.
2121
2122 Use @code{-parallel none} to disable all parallel ports.
2123 ETEXI
2124
2125 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
2126     "-monitor dev    redirect the monitor to char device 'dev'\n",
2127     QEMU_ARCH_ALL)
2128 STEXI
2129 @item -monitor @var{dev}
2130 @findex -monitor
2131 Redirect the monitor to host device @var{dev} (same devices as the
2132 serial port).
2133 The default device is @code{vc} in graphical mode and @code{stdio} in
2134 non graphical mode.
2135 ETEXI
2136 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
2137     "-qmp dev        like -monitor but opens in 'control' mode\n",
2138     QEMU_ARCH_ALL)
2139 STEXI
2140 @item -qmp @var{dev}
2141 @findex -qmp
2142 Like -monitor but opens in 'control' mode.
2143 ETEXI
2144
2145 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
2146     "-mon chardev=[name][,mode=readline|control][,default]\n", QEMU_ARCH_ALL)
2147 STEXI
2148 @item -mon chardev=[name][,mode=readline|control][,default]
2149 @findex -mon
2150 Setup monitor on chardev @var{name}.
2151 ETEXI
2152
2153 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
2154     "-debugcon dev   redirect the debug console to char device 'dev'\n",
2155     QEMU_ARCH_ALL)
2156 STEXI
2157 @item -debugcon @var{dev}
2158 @findex -debugcon
2159 Redirect the debug console to host device @var{dev} (same devices as the
2160 serial port).  The debug console is an I/O port which is typically port
2161 0xe9; writing to that I/O port sends output to this device.
2162 The default device is @code{vc} in graphical mode and @code{stdio} in
2163 non graphical mode.
2164 ETEXI
2165
2166 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
2167     "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
2168 STEXI
2169 @item -pidfile @var{file}
2170 @findex -pidfile
2171 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
2172 from a script.
2173 ETEXI
2174
2175 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
2176     "-singlestep     always run in singlestep mode\n", QEMU_ARCH_ALL)
2177 STEXI
2178 @item -singlestep
2179 @findex -singlestep
2180 Run the emulation in single step mode.
2181 ETEXI
2182
2183 DEF("S", 0, QEMU_OPTION_S, \
2184     "-S              freeze CPU at startup (use 'c' to start execution)\n",
2185     QEMU_ARCH_ALL)
2186 STEXI
2187 @item -S
2188 @findex -S
2189 Do not start CPU at startup (you must type 'c' in the monitor).
2190 ETEXI
2191
2192 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
2193     "-gdb dev        wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
2194 STEXI
2195 @item -gdb @var{dev}
2196 @findex -gdb
2197 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
2198 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
2199 stdio are reasonable use case. The latter is allowing to start qemu from
2200 within gdb and establish the connection via a pipe:
2201 @example
2202 (gdb) target remote | exec qemu -gdb stdio ...
2203 @end example
2204 ETEXI
2205
2206 DEF("s", 0, QEMU_OPTION_s, \
2207     "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
2208     QEMU_ARCH_ALL)
2209 STEXI
2210 @item -s
2211 @findex -s
2212 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
2213 (@pxref{gdb_usage}).
2214 ETEXI
2215
2216 DEF("d", HAS_ARG, QEMU_OPTION_d, \
2217     "-d item1,...    output log to /tmp/qemu.log (use -d ? for a list of log items)\n",
2218     QEMU_ARCH_ALL)
2219 STEXI
2220 @item -d
2221 @findex -d
2222 Output log in /tmp/qemu.log
2223 ETEXI
2224
2225 DEF("D", HAS_ARG, QEMU_OPTION_D, \
2226     "-D logfile      output log to logfile (instead of the default /tmp/qemu.log)\n",
2227     QEMU_ARCH_ALL)
2228 STEXI
2229 @item -D
2230 @findex -D
2231 Output log in logfile instead of /tmp/qemu.log
2232 ETEXI
2233
2234 DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
2235     "-hdachs c,h,s[,t]\n" \
2236     "                force hard disk 0 physical geometry and the optional BIOS\n" \
2237     "                translation (t=none or lba) (usually qemu can guess them)\n",
2238     QEMU_ARCH_ALL)
2239 STEXI
2240 @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
2241 @findex -hdachs
2242 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
2243 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
2244 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
2245 all those parameters. This option is useful for old MS-DOS disk
2246 images.
2247 ETEXI
2248
2249 DEF("L", HAS_ARG, QEMU_OPTION_L, \
2250     "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n",
2251     QEMU_ARCH_ALL)
2252 STEXI
2253 @item -L  @var{path}
2254 @findex -L
2255 Set the directory for the BIOS, VGA BIOS and keymaps.
2256 ETEXI
2257
2258 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
2259     "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
2260 STEXI
2261 @item -bios @var{file}
2262 @findex -bios
2263 Set the filename for the BIOS.
2264 ETEXI
2265
2266 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
2267     "-enable-kvm     enable KVM full virtualization support\n", QEMU_ARCH_ALL)
2268 STEXI
2269 @item -enable-kvm
2270 @findex -enable-kvm
2271 Enable KVM full virtualization support. This option is only available
2272 if KVM support is enabled when compiling.
2273 ETEXI
2274
2275 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
2276     "-xen-domid id   specify xen guest domain id\n", QEMU_ARCH_ALL)
2277 DEF("xen-create", 0, QEMU_OPTION_xen_create,
2278     "-xen-create     create domain using xen hypercalls, bypassing xend\n"
2279     "                warning: should not be used when xend is in use\n",
2280     QEMU_ARCH_ALL)
2281 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
2282     "-xen-attach     attach to existing xen domain\n"
2283     "                xend will use this when starting qemu\n",
2284     QEMU_ARCH_ALL)
2285 STEXI
2286 @item -xen-domid @var{id}
2287 @findex -xen-domid
2288 Specify xen guest domain @var{id} (XEN only).
2289 @item -xen-create
2290 @findex -xen-create
2291 Create domain using xen hypercalls, bypassing xend.
2292 Warning: should not be used when xend is in use (XEN only).
2293 @item -xen-attach
2294 @findex -xen-attach
2295 Attach to existing xen domain.
2296 xend will use this when starting qemu (XEN only).
2297 ETEXI
2298
2299 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
2300     "-no-reboot      exit instead of rebooting\n", QEMU_ARCH_ALL)
2301 STEXI
2302 @item -no-reboot
2303 @findex -no-reboot
2304 Exit instead of rebooting.
2305 ETEXI
2306
2307 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
2308     "-no-shutdown    stop before shutdown\n", QEMU_ARCH_ALL)
2309 STEXI
2310 @item -no-shutdown
2311 @findex -no-shutdown
2312 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
2313 This allows for instance switching to monitor to commit changes to the
2314 disk image.
2315 ETEXI
2316
2317 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
2318     "-loadvm [tag|id]\n" \
2319     "                start right away with a saved state (loadvm in monitor)\n",
2320     QEMU_ARCH_ALL)
2321 STEXI
2322 @item -loadvm @var{file}
2323 @findex -loadvm
2324 Start right away with a saved state (@code{loadvm} in monitor)
2325 ETEXI
2326
2327 #ifndef _WIN32
2328 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
2329     "-daemonize      daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
2330 #endif
2331 STEXI
2332 @item -daemonize
2333 @findex -daemonize
2334 Daemonize the QEMU process after initialization.  QEMU will not detach from
2335 standard IO until it is ready to receive connections on any of its devices.
2336 This option is a useful way for external programs to launch QEMU without having
2337 to cope with initialization race conditions.
2338 ETEXI
2339
2340 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
2341     "-option-rom rom load a file, rom, into the option ROM space\n",
2342     QEMU_ARCH_ALL)
2343 STEXI
2344 @item -option-rom @var{file}
2345 @findex -option-rom
2346 Load the contents of @var{file} as an option ROM.
2347 This option is useful to load things like EtherBoot.
2348 ETEXI
2349
2350 DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
2351     "-clock          force the use of the given methods for timer alarm.\n" \
2352     "                To see what timers are available use -clock ?\n",
2353     QEMU_ARCH_ALL)
2354 STEXI
2355 @item -clock @var{method}
2356 @findex -clock
2357 Force the use of the given methods for timer alarm. To see what timers
2358 are available use -clock ?.
2359 ETEXI
2360
2361 HXCOMM Options deprecated by -rtc
2362 DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
2363 DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
2364
2365 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
2366     "-rtc [base=utc|localtime|date][,clock=host|vm][,driftfix=none|slew]\n" \
2367     "                set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
2368     QEMU_ARCH_ALL)
2369
2370 STEXI
2371
2372 @item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
2373 @findex -rtc
2374 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
2375 UTC or local time, respectively. @code{localtime} is required for correct date in
2376 MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
2377 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
2378
2379 By default the RTC is driven by the host system time. This allows to use the
2380 RTC as accurate reference clock inside the guest, specifically if the host
2381 time is smoothly following an accurate external reference clock, e.g. via NTP.
2382 If you want to isolate the guest time from the host, even prevent it from
2383 progressing during suspension, you can set @option{clock} to @code{vm} instead.
2384
2385 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
2386 specifically with Windows' ACPI HAL. This option will try to figure out how
2387 many timer interrupts were not processed by the Windows guest and will
2388 re-inject them.
2389 ETEXI
2390
2391 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
2392     "-icount [N|auto]\n" \
2393     "                enable virtual instruction counter with 2^N clock ticks per\n" \
2394     "                instruction\n", QEMU_ARCH_ALL)
2395 STEXI
2396 @item -icount [@var{N}|auto]
2397 @findex -icount
2398 Enable virtual instruction counter.  The virtual cpu will execute one
2399 instruction every 2^@var{N} ns of virtual time.  If @code{auto} is specified
2400 then the virtual cpu speed will be automatically adjusted to keep virtual
2401 time within a few seconds of real time.
2402
2403 Note that while this option can give deterministic behavior, it does not
2404 provide cycle accurate emulation.  Modern CPUs contain superscalar out of
2405 order cores with complex cache hierarchies.  The number of instructions
2406 executed often has little or no correlation with actual performance.
2407 ETEXI
2408
2409 DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
2410     "-watchdog i6300esb|ib700\n" \
2411     "                enable virtual hardware watchdog [default=none]\n",
2412     QEMU_ARCH_ALL)
2413 STEXI
2414 @item -watchdog @var{model}
2415 @findex -watchdog
2416 Create a virtual hardware watchdog device.  Once enabled (by a guest
2417 action), the watchdog must be periodically polled by an agent inside
2418 the guest or else the guest will be restarted.
2419
2420 The @var{model} is the model of hardware watchdog to emulate.  Choices
2421 for model are: @code{ib700} (iBASE 700) which is a very simple ISA
2422 watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O
2423 controller hub) which is a much more featureful PCI-based dual-timer
2424 watchdog.  Choose a model for which your guest has drivers.
2425
2426 Use @code{-watchdog ?} to list available hardware models.  Only one
2427 watchdog can be enabled for a guest.
2428 ETEXI
2429
2430 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
2431     "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
2432     "                action when watchdog fires [default=reset]\n",
2433     QEMU_ARCH_ALL)
2434 STEXI
2435 @item -watchdog-action @var{action}
2436
2437 The @var{action} controls what QEMU will do when the watchdog timer
2438 expires.
2439 The default is
2440 @code{reset} (forcefully reset the guest).
2441 Other possible actions are:
2442 @code{shutdown} (attempt to gracefully shutdown the guest),
2443 @code{poweroff} (forcefully poweroff the guest),
2444 @code{pause} (pause the guest),
2445 @code{debug} (print a debug message and continue), or
2446 @code{none} (do nothing).
2447
2448 Note that the @code{shutdown} action requires that the guest responds
2449 to ACPI signals, which it may not be able to do in the sort of
2450 situations where the watchdog would have expired, and thus
2451 @code{-watchdog-action shutdown} is not recommended for production use.
2452
2453 Examples:
2454
2455 @table @code
2456 @item -watchdog i6300esb -watchdog-action pause
2457 @item -watchdog ib700
2458 @end table
2459 ETEXI
2460
2461 DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
2462     "-echr chr       set terminal escape character instead of ctrl-a\n",
2463     QEMU_ARCH_ALL)
2464 STEXI
2465
2466 @item -echr @var{numeric_ascii_value}
2467 @findex -echr
2468 Change the escape character used for switching to the monitor when using
2469 monitor and serial sharing.  The default is @code{0x01} when using the
2470 @code{-nographic} option.  @code{0x01} is equal to pressing
2471 @code{Control-a}.  You can select a different character from the ascii
2472 control keys where 1 through 26 map to Control-a through Control-z.  For
2473 instance you could use the either of the following to change the escape
2474 character to Control-t.
2475 @table @code
2476 @item -echr 0x14
2477 @item -echr 20
2478 @end table
2479 ETEXI
2480
2481 DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
2482     "-virtioconsole c\n" \
2483     "                set virtio console\n", QEMU_ARCH_ALL)
2484 STEXI
2485 @item -virtioconsole @var{c}
2486 @findex -virtioconsole
2487 Set virtio console.
2488
2489 This option is maintained for backward compatibility.
2490
2491 Please use @code{-device virtconsole} for the new way of invocation.
2492 ETEXI
2493
2494 DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
2495     "-show-cursor    show cursor\n", QEMU_ARCH_ALL)
2496 STEXI
2497 @item -show-cursor
2498 @findex -show-cursor
2499 Show cursor.
2500 ETEXI
2501
2502 DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
2503     "-tb-size n      set TB size\n", QEMU_ARCH_ALL)
2504 STEXI
2505 @item -tb-size @var{n}
2506 @findex -tb-size
2507 Set TB size.
2508 ETEXI
2509
2510 DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
2511     "-incoming p     prepare for incoming migration, listen on port p\n",
2512     QEMU_ARCH_ALL)
2513 STEXI
2514 @item -incoming @var{port}
2515 @findex -incoming
2516 Prepare for incoming migration, listen on @var{port}.
2517 ETEXI
2518
2519 DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
2520     "-nodefaults     don't create default devices\n", QEMU_ARCH_ALL)
2521 STEXI
2522 @item -nodefaults
2523 @findex -nodefaults
2524 Don't create default devices.
2525 ETEXI
2526
2527 #ifndef _WIN32
2528 DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
2529     "-chroot dir     chroot to dir just before starting the VM\n",
2530     QEMU_ARCH_ALL)
2531 #endif
2532 STEXI
2533 @item -chroot @var{dir}
2534 @findex -chroot
2535 Immediately before starting guest execution, chroot to the specified
2536 directory.  Especially useful in combination with -runas.
2537 ETEXI
2538
2539 #ifndef _WIN32
2540 DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
2541     "-runas user     change to user id user just before starting the VM\n",
2542     QEMU_ARCH_ALL)
2543 #endif
2544 STEXI
2545 @item -runas @var{user}
2546 @findex -runas
2547 Immediately before starting guest execution, drop root privileges, switching
2548 to the specified user.
2549 ETEXI
2550
2551 DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
2552     "-prom-env variable=value\n"
2553     "                set OpenBIOS nvram variables\n",
2554     QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
2555 STEXI
2556 @item -prom-env @var{variable}=@var{value}
2557 @findex -prom-env
2558 Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
2559 ETEXI
2560 DEF("semihosting", 0, QEMU_OPTION_semihosting,
2561     "-semihosting    semihosting mode\n", QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA)
2562 STEXI
2563 @item -semihosting
2564 @findex -semihosting
2565 Semihosting mode (ARM, M68K, Xtensa only).
2566 ETEXI
2567 DEF("old-param", 0, QEMU_OPTION_old_param,
2568     "-old-param      old param mode\n", QEMU_ARCH_ARM)
2569 STEXI
2570 @item -old-param
2571 @findex -old-param (ARM)
2572 Old param mode (ARM only).
2573 ETEXI
2574
2575 DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
2576     "-readconfig <file>\n", QEMU_ARCH_ALL)
2577 STEXI
2578 @item -readconfig @var{file}
2579 @findex -readconfig
2580 Read device configuration from @var{file}.
2581 ETEXI
2582 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
2583     "-writeconfig <file>\n"
2584     "                read/write config file\n", QEMU_ARCH_ALL)
2585 STEXI
2586 @item -writeconfig @var{file}
2587 @findex -writeconfig
2588 Write device configuration to @var{file}.
2589 ETEXI
2590 DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
2591     "-nodefconfig\n"
2592     "                do not load default config files at startup\n",
2593     QEMU_ARCH_ALL)
2594 STEXI
2595 @item -nodefconfig
2596 @findex -nodefconfig
2597 Normally QEMU loads a configuration file from @var{sysconfdir}/qemu.conf and
2598 @var{sysconfdir}/target-@var{ARCH}.conf on startup.  The @code{-nodefconfig}
2599 option will prevent QEMU from loading these configuration files at startup.
2600 ETEXI
2601 DEF("trace", HAS_ARG, QEMU_OPTION_trace,
2602     "-trace [events=<file>][,file=<file>]\n"
2603     "                specify tracing options\n",
2604     QEMU_ARCH_ALL)
2605 STEXI
2606 HXCOMM This line is not accurate, as some sub-options are backend-specific but
2607 HXCOMM HX does not support conditional compilation of text.
2608 @item -trace [events=@var{file}][,file=@var{file}]
2609 @findex -trace
2610
2611 Specify tracing options.
2612
2613 @table @option
2614 @item events=@var{file}
2615 Immediately enable events listed in @var{file}.
2616 The file must contain one event name (as listed in the @var{trace-events} file)
2617 per line.
2618 This option is only available if QEMU has been compiled with
2619 either @var{simple} or @var{stderr} tracing backend.
2620 @item file=@var{file}
2621 Log output traces to @var{file}.
2622
2623 This option is only available if QEMU has been compiled with
2624 the @var{simple} tracing backend.
2625 @end table
2626 ETEXI
2627
2628 HXCOMM This is the last statement. Insert new options before this line!
2629 STEXI
2630 @end table
2631 ETEXI