vga: improve documentation
[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][,helper=helper][,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' \n"
1227     "                use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1228     "                to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1229     "                to deconfigure it\n"
1230     "                use '[down]script=no' to disable script execution\n"
1231     "                use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1232     "                configure it\n"
1233     "                use 'fd=h' to connect to an already opened TAP interface\n"
1234     "                use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
1235     "                default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
1236     "                use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1237     "                use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
1238     "                use vhost=on to enable experimental in kernel accelerator\n"
1239     "                    (only has effect for virtio guests which use MSIX)\n"
1240     "                use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
1241     "                use 'vhostfd=h' to connect to an already opened vhost net device\n"
1242     "-net bridge[,vlan=n][,name=str][,br=bridge][,helper=helper]\n"
1243     "                connects a host TAP network interface to a host bridge device 'br'\n"
1244     "                (default=" DEFAULT_BRIDGE_INTERFACE ") using the program 'helper'\n"
1245     "                (default=" DEFAULT_BRIDGE_HELPER ")\n"
1246 #endif
1247     "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
1248     "                connect the vlan 'n' to another VLAN using a socket connection\n"
1249     "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1250     "                connect the vlan 'n' to multicast maddr and port\n"
1251     "                use 'localaddr=addr' to specify the host address to send packets from\n"
1252     "-net socket[,vlan=n][,name=str][,fd=h][,udp=host:port][,localaddr=host:port]\n"
1253     "                connect the vlan 'n' to another VLAN using an UDP tunnel\n"
1254 #ifdef CONFIG_VDE
1255     "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1256     "                connect the vlan 'n' to port 'n' of a vde switch running\n"
1257     "                on host and listening for incoming connections on 'socketpath'.\n"
1258     "                Use group 'groupname' and mode 'octalmode' to change default\n"
1259     "                ownership and permissions for communication port.\n"
1260 #endif
1261     "-net dump[,vlan=n][,file=f][,len=n]\n"
1262     "                dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
1263     "-net none       use it alone to have zero network devices. If no -net option\n"
1264     "                is provided, the default is '-net nic -net user'\n", QEMU_ARCH_ALL)
1265 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
1266     "-netdev ["
1267 #ifdef CONFIG_SLIRP
1268     "user|"
1269 #endif
1270     "tap|"
1271     "bridge|"
1272 #ifdef CONFIG_VDE
1273     "vde|"
1274 #endif
1275     "socket],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
1276 STEXI
1277 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
1278 @findex -net
1279 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
1280 = 0 is the default). The NIC is an e1000 by default on the PC
1281 target. Optionally, the MAC address can be changed to @var{mac}, the
1282 device address set to @var{addr} (PCI cards only),
1283 and a @var{name} can be assigned for use in monitor commands.
1284 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1285 that the card should have; this option currently only affects virtio cards; set
1286 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
1287 NIC is created.  Qemu can emulate several different models of network card.
1288 Valid values for @var{type} are
1289 @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
1290 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1291 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
1292 Not all devices are supported on all targets.  Use -net nic,model=?
1293 for a list of available devices for your target.
1294
1295 @item -net user[,@var{option}][,@var{option}][,...]
1296 Use the user mode network stack which requires no administrator
1297 privilege to run. Valid options are:
1298
1299 @table @option
1300 @item vlan=@var{n}
1301 Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1302
1303 @item name=@var{name}
1304 Assign symbolic name for use in monitor commands.
1305
1306 @item net=@var{addr}[/@var{mask}]
1307 Set IP network address the guest will see. Optionally specify the netmask,
1308 either in the form a.b.c.d or as number of valid top-most bits. Default is
1309 10.0.2.0/24.
1310
1311 @item host=@var{addr}
1312 Specify the guest-visible address of the host. Default is the 2nd IP in the
1313 guest network, i.e. x.x.x.2.
1314
1315 @item restrict=on|off
1316 If this option is enabled, the guest will be isolated, i.e. it will not be
1317 able to contact the host and no guest IP packets will be routed over the host
1318 to the outside. This option does not affect any explicitly set forwarding rules.
1319
1320 @item hostname=@var{name}
1321 Specifies the client hostname reported by the builtin DHCP server.
1322
1323 @item dhcpstart=@var{addr}
1324 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
1325 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
1326
1327 @item dns=@var{addr}
1328 Specify the guest-visible address of the virtual nameserver. The address must
1329 be different from the host address. Default is the 3rd IP in the guest network,
1330 i.e. x.x.x.3.
1331
1332 @item tftp=@var{dir}
1333 When using the user mode network stack, activate a built-in TFTP
1334 server. The files in @var{dir} will be exposed as the root of a TFTP server.
1335 The TFTP client on the guest must be configured in binary mode (use the command
1336 @code{bin} of the Unix TFTP client).
1337
1338 @item bootfile=@var{file}
1339 When using the user mode network stack, broadcast @var{file} as the BOOTP
1340 filename. In conjunction with @option{tftp}, this can be used to network boot
1341 a guest from a local directory.
1342
1343 Example (using pxelinux):
1344 @example
1345 qemu -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1346 @end example
1347
1348 @item smb=@var{dir}[,smbserver=@var{addr}]
1349 When using the user mode network stack, activate a built-in SMB
1350 server so that Windows OSes can access to the host files in @file{@var{dir}}
1351 transparently. The IP address of the SMB server can be set to @var{addr}. By
1352 default the 4th IP in the guest network is used, i.e. x.x.x.4.
1353
1354 In the guest Windows OS, the line:
1355 @example
1356 10.0.2.4 smbserver
1357 @end example
1358 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1359 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1360
1361 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1362
1363 Note that a SAMBA server must be installed on the host OS.
1364 QEMU was tested successfully with smbd versions from Red Hat 9,
1365 Fedora Core 3 and OpenSUSE 11.x.
1366
1367 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
1368 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1369 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1370 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
1371 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1372 be bound to a specific host interface. If no connection type is set, TCP is
1373 used. This option can be given multiple times.
1374
1375 For example, to redirect host X11 connection from screen 1 to guest
1376 screen 0, use the following:
1377
1378 @example
1379 # on the host
1380 qemu -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
1381 # this host xterm should open in the guest X11 server
1382 xterm -display :1
1383 @end example
1384
1385 To redirect telnet connections from host port 5555 to telnet port on
1386 the guest, use the following:
1387
1388 @example
1389 # on the host
1390 qemu -net user,hostfwd=tcp::5555-:23 [...]
1391 telnet localhost 5555
1392 @end example
1393
1394 Then when you use on the host @code{telnet localhost 5555}, you
1395 connect to the guest telnet server.
1396
1397 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
1398 Forward guest TCP connections to the IP address @var{server} on port @var{port}
1399 to the character device @var{dev}. This option can be given multiple times.
1400
1401 @end table
1402
1403 Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
1404 processed and applied to -net user. Mixing them with the new configuration
1405 syntax gives undefined results. Their use for new applications is discouraged
1406 as they will be removed from future versions.
1407
1408 @item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1409 Connect the host TAP network interface @var{name} to VLAN @var{n}.
1410
1411 Use the network script @var{file} to configure it and the network script
1412 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
1413 automatically provides one. The default network configure script is
1414 @file{/etc/qemu-ifup} and the default network deconfigure script is
1415 @file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
1416 to disable script execution.
1417
1418 If running QEMU as an unprivileged user, use the network helper
1419 @var{helper} to configure the TAP interface. The default network
1420 helper executable is @file{/usr/local/libexec/qemu-bridge-helper}.
1421
1422 @option{fd}=@var{h} can be used to specify the handle of an already
1423 opened host TAP interface.
1424
1425 Examples:
1426
1427 @example
1428 #launch a QEMU instance with the default network script
1429 qemu linux.img -net nic -net tap
1430 @end example
1431
1432 @example
1433 #launch a QEMU instance with two NICs, each one connected
1434 #to a TAP device
1435 qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1436                -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
1437 @end example
1438
1439 @example
1440 #launch a QEMU instance with the default network helper to
1441 #connect a TAP device to bridge br0
1442 qemu linux.img -net nic -net tap,"helper=/usr/local/libexec/qemu-bridge-helper"
1443 @end example
1444
1445 @item -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
1446 Connect a host TAP network interface to a host bridge device.
1447
1448 Use the network helper @var{helper} to configure the TAP interface and
1449 attach it to the bridge. The default network helper executable is
1450 @file{/usr/local/libexec/qemu-bridge-helper} and the default bridge
1451 device is @file{br0}.
1452
1453 Examples:
1454
1455 @example
1456 #launch a QEMU instance with the default network helper to
1457 #connect a TAP device to bridge br0
1458 qemu linux.img -net bridge -net nic,model=virtio
1459 @end example
1460
1461 @example
1462 #launch a QEMU instance with the default network helper to
1463 #connect a TAP device to bridge qemubr0
1464 qemu linux.img -net bridge,br=qemubr0 -net nic,model=virtio
1465 @end example
1466
1467 @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1468
1469 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1470 machine using a TCP socket connection. If @option{listen} is
1471 specified, QEMU waits for incoming connections on @var{port}
1472 (@var{host} is optional). @option{connect} is used to connect to
1473 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1474 specifies an already opened TCP socket.
1475
1476 Example:
1477 @example
1478 # launch a first QEMU instance
1479 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1480                -net socket,listen=:1234
1481 # connect the VLAN 0 of this instance to the VLAN 0
1482 # of the first instance
1483 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1484                -net socket,connect=127.0.0.1:1234
1485 @end example
1486
1487 @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1488
1489 Create a VLAN @var{n} shared with another QEMU virtual
1490 machines using a UDP multicast socket, effectively making a bus for
1491 every QEMU with same multicast address @var{maddr} and @var{port}.
1492 NOTES:
1493 @enumerate
1494 @item
1495 Several QEMU can be running on different hosts and share same bus (assuming
1496 correct multicast setup for these hosts).
1497 @item
1498 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1499 @url{http://user-mode-linux.sf.net}.
1500 @item
1501 Use @option{fd=h} to specify an already opened UDP multicast socket.
1502 @end enumerate
1503
1504 Example:
1505 @example
1506 # launch one QEMU instance
1507 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1508                -net socket,mcast=230.0.0.1:1234
1509 # launch another QEMU instance on same "bus"
1510 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1511                -net socket,mcast=230.0.0.1:1234
1512 # launch yet another QEMU instance on same "bus"
1513 qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
1514                -net socket,mcast=230.0.0.1:1234
1515 @end example
1516
1517 Example (User Mode Linux compat.):
1518 @example
1519 # launch QEMU instance (note mcast address selected
1520 # is UML's default)
1521 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1522                -net socket,mcast=239.192.168.1:1102
1523 # launch UML
1524 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
1525 @end example
1526
1527 Example (send packets from host's 1.2.3.4):
1528 @example
1529 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1530                -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
1531 @end example
1532
1533 @item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
1534 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
1535 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
1536 and MODE @var{octalmode} to change default ownership and permissions for
1537 communication port. This option is only available if QEMU has been compiled
1538 with vde support enabled.
1539
1540 Example:
1541 @example
1542 # launch vde switch
1543 vde_switch -F -sock /tmp/myswitch
1544 # launch QEMU instance
1545 qemu linux.img -net nic -net vde,sock=/tmp/myswitch
1546 @end example
1547
1548 @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
1549 Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
1550 At most @var{len} bytes (64k by default) per packet are stored. The file format is
1551 libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
1552
1553 @item -net none
1554 Indicate that no network devices should be configured. It is used to
1555 override the default configuration (@option{-net nic -net user}) which
1556 is activated if no @option{-net} options are provided.
1557
1558 @end table
1559 ETEXI
1560
1561 DEFHEADING()
1562
1563 DEFHEADING(Character device options:)
1564
1565 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
1566     "-chardev null,id=id[,mux=on|off]\n"
1567     "-chardev socket,id=id[,host=host],port=host[,to=to][,ipv4][,ipv6][,nodelay]\n"
1568     "         [,server][,nowait][,telnet][,mux=on|off] (tcp)\n"
1569     "-chardev socket,id=id,path=path[,server][,nowait][,telnet],[mux=on|off] (unix)\n"
1570     "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
1571     "         [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
1572     "-chardev msmouse,id=id[,mux=on|off]\n"
1573     "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
1574     "         [,mux=on|off]\n"
1575     "-chardev file,id=id,path=path[,mux=on|off]\n"
1576     "-chardev pipe,id=id,path=path[,mux=on|off]\n"
1577 #ifdef _WIN32
1578     "-chardev console,id=id[,mux=on|off]\n"
1579     "-chardev serial,id=id,path=path[,mux=on|off]\n"
1580 #else
1581     "-chardev pty,id=id[,mux=on|off]\n"
1582     "-chardev stdio,id=id[,mux=on|off][,signal=on|off]\n"
1583 #endif
1584 #ifdef CONFIG_BRLAPI
1585     "-chardev braille,id=id[,mux=on|off]\n"
1586 #endif
1587 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
1588         || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
1589     "-chardev tty,id=id,path=path[,mux=on|off]\n"
1590 #endif
1591 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
1592     "-chardev parport,id=id,path=path[,mux=on|off]\n"
1593 #endif
1594 #if defined(CONFIG_SPICE)
1595     "-chardev spicevmc,id=id,name=name[,debug=debug]\n"
1596 #endif
1597     , QEMU_ARCH_ALL
1598 )
1599
1600 STEXI
1601
1602 The general form of a character device option is:
1603 @table @option
1604
1605 @item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
1606 @findex -chardev
1607 Backend is one of:
1608 @option{null},
1609 @option{socket},
1610 @option{udp},
1611 @option{msmouse},
1612 @option{vc},
1613 @option{file},
1614 @option{pipe},
1615 @option{console},
1616 @option{serial},
1617 @option{pty},
1618 @option{stdio},
1619 @option{braille},
1620 @option{tty},
1621 @option{parport},
1622 @option{spicevmc}.
1623 The specific backend will determine the applicable options.
1624
1625 All devices must have an id, which can be any string up to 127 characters long.
1626 It is used to uniquely identify this device in other command line directives.
1627
1628 A character device may be used in multiplexing mode by multiple front-ends.
1629 The key sequence of @key{Control-a} and @key{c} will rotate the input focus
1630 between attached front-ends. Specify @option{mux=on} to enable this mode.
1631
1632 Options to each backend are described below.
1633
1634 @item -chardev null ,id=@var{id}
1635 A void device. This device will not emit any data, and will drop any data it
1636 receives. The null backend does not take any options.
1637
1638 @item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet]
1639
1640 Create a two-way stream socket, which can be either a TCP or a unix socket. A
1641 unix socket will be created if @option{path} is specified. Behaviour is
1642 undefined if TCP options are specified for a unix socket.
1643
1644 @option{server} specifies that the socket shall be a listening socket.
1645
1646 @option{nowait} specifies that QEMU should not block waiting for a client to
1647 connect to a listening socket.
1648
1649 @option{telnet} specifies that traffic on the socket should interpret telnet
1650 escape sequences.
1651
1652 TCP and unix socket options are given below:
1653
1654 @table @option
1655
1656 @item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
1657
1658 @option{host} for a listening socket specifies the local address to be bound.
1659 For a connecting socket species the remote host to connect to. @option{host} is
1660 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
1661
1662 @option{port} for a listening socket specifies the local port to be bound. For a
1663 connecting socket specifies the port on the remote host to connect to.
1664 @option{port} can be given as either a port number or a service name.
1665 @option{port} is required.
1666
1667 @option{to} is only relevant to listening sockets. If it is specified, and
1668 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
1669 to and including @option{to} until it succeeds. @option{to} must be specified
1670 as a port number.
1671
1672 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
1673 If neither is specified the socket may use either protocol.
1674
1675 @option{nodelay} disables the Nagle algorithm.
1676
1677 @item unix options: path=@var{path}
1678
1679 @option{path} specifies the local path of the unix socket. @option{path} is
1680 required.
1681
1682 @end table
1683
1684 @item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
1685
1686 Sends all traffic from the guest to a remote host over UDP.
1687
1688 @option{host} specifies the remote host to connect to. If not specified it
1689 defaults to @code{localhost}.
1690
1691 @option{port} specifies the port on the remote host to connect to. @option{port}
1692 is required.
1693
1694 @option{localaddr} specifies the local address to bind to. If not specified it
1695 defaults to @code{0.0.0.0}.
1696
1697 @option{localport} specifies the local port to bind to. If not specified any
1698 available local port will be used.
1699
1700 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
1701 If neither is specified the device may use either protocol.
1702
1703 @item -chardev msmouse ,id=@var{id}
1704
1705 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
1706 take any options.
1707
1708 @item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
1709
1710 Connect to a QEMU text console. @option{vc} may optionally be given a specific
1711 size.
1712
1713 @option{width} and @option{height} specify the width and height respectively of
1714 the console, in pixels.
1715
1716 @option{cols} and @option{rows} specify that the console be sized to fit a text
1717 console with the given dimensions.
1718
1719 @item -chardev file ,id=@var{id} ,path=@var{path}
1720
1721 Log all traffic received from the guest to a file.
1722
1723 @option{path} specifies the path of the file to be opened. This file will be
1724 created if it does not already exist, and overwritten if it does. @option{path}
1725 is required.
1726
1727 @item -chardev pipe ,id=@var{id} ,path=@var{path}
1728
1729 Create a two-way connection to the guest. The behaviour differs slightly between
1730 Windows hosts and other hosts:
1731
1732 On Windows, a single duplex pipe will be created at
1733 @file{\\.pipe\@option{path}}.
1734
1735 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
1736 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
1737 received by the guest. Data written by the guest can be read from
1738 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
1739 be present.
1740
1741 @option{path} forms part of the pipe path as described above. @option{path} is
1742 required.
1743
1744 @item -chardev console ,id=@var{id}
1745
1746 Send traffic from the guest to QEMU's standard output. @option{console} does not
1747 take any options.
1748
1749 @option{console} is only available on Windows hosts.
1750
1751 @item -chardev serial ,id=@var{id} ,path=@option{path}
1752
1753 Send traffic from the guest to a serial device on the host.
1754
1755 @option{serial} is
1756 only available on Windows hosts.
1757
1758 @option{path} specifies the name of the serial device to open.
1759
1760 @item -chardev pty ,id=@var{id}
1761
1762 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
1763 not take any options.
1764
1765 @option{pty} is not available on Windows hosts.
1766
1767 @item -chardev stdio ,id=@var{id} [,signal=on|off]
1768 Connect to standard input and standard output of the qemu process.
1769
1770 @option{signal} controls if signals are enabled on the terminal, that includes
1771 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
1772 default, use @option{signal=off} to disable it.
1773
1774 @option{stdio} is not available on Windows hosts.
1775
1776 @item -chardev braille ,id=@var{id}
1777
1778 Connect to a local BrlAPI server. @option{braille} does not take any options.
1779
1780 @item -chardev tty ,id=@var{id} ,path=@var{path}
1781
1782 Connect to a local tty device.
1783
1784 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
1785 DragonFlyBSD hosts.
1786
1787 @option{path} specifies the path to the tty. @option{path} is required.
1788
1789 @item -chardev parport ,id=@var{id} ,path=@var{path}
1790
1791 @option{parport} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
1792
1793 Connect to a local parallel port.
1794
1795 @option{path} specifies the path to the parallel port device. @option{path} is
1796 required.
1797
1798 @item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
1799
1800 @option{spicevmc} is only available when spice support is built in.
1801
1802 @option{debug} debug level for spicevmc
1803
1804 @option{name} name of spice channel to connect to
1805
1806 Connect to a spice virtual machine channel, such as vdiport.
1807
1808 @end table
1809 ETEXI
1810
1811 DEFHEADING()
1812
1813 STEXI
1814 DEFHEADING(Device URL Syntax:)
1815
1816 In addition to using normal file images for the emulated storage devices,
1817 QEMU can also use networked resources such as iSCSI devices. These are
1818 specified using a special URL syntax.
1819
1820 @table @option
1821 @item iSCSI
1822 iSCSI support allows QEMU to access iSCSI resources directly and use as
1823 images for the guest storage. Both disk and cdrom images are supported.
1824
1825 Syntax for specifying iSCSI LUNs is
1826 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
1827
1828 Example (without authentication):
1829 @example
1830 qemu -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
1831 --drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
1832 @end example
1833
1834 Example (CHAP username/password via URL):
1835 @example
1836 qemu --drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
1837 @end example
1838
1839 Example (CHAP username/password via environment variables):
1840 @example
1841 LIBISCSI_CHAP_USERNAME="user" \
1842 LIBISCSI_CHAP_PASSWORD="password" \
1843 qemu --drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
1844 @end example
1845
1846 iSCSI support is an optional feature of QEMU and only available when
1847 compiled and linked against libiscsi.
1848
1849 @item NBD
1850 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
1851 as Unix Domain Sockets.
1852
1853 Syntax for specifying a NBD device using TCP
1854 ``nbd:<server-ip>:<port>[:exportname=<export>]''
1855
1856 Syntax for specifying a NBD device using Unix Domain Sockets
1857 ``nbd:unix:<domain-socket>[:exportname=<export>]''
1858
1859
1860 Example for TCP
1861 @example
1862 qemu --drive file=nbd:192.0.2.1:30000
1863 @end example
1864
1865 Example for Unix Domain Sockets
1866 @example
1867 qemu --drive file=nbd:unix:/tmp/nbd-socket
1868 @end example
1869
1870 @item Sheepdog
1871 Sheepdog is a distributed storage system for QEMU.
1872 QEMU supports using either local sheepdog devices or remote networked
1873 devices.
1874
1875 Syntax for specifying a sheepdog device
1876 @table @list
1877 ``sheepdog:<vdiname>''
1878
1879 ``sheepdog:<vdiname>:<snapid>''
1880
1881 ``sheepdog:<vdiname>:<tag>''
1882
1883 ``sheepdog:<host>:<port>:<vdiname>''
1884
1885 ``sheepdog:<host>:<port>:<vdiname>:<snapid>''
1886
1887 ``sheepdog:<host>:<port>:<vdiname>:<tag>''
1888 @end table
1889
1890 Example
1891 @example
1892 qemu --drive file=sheepdog:192.0.2.1:30000:MyVirtualMachine
1893 @end example
1894
1895 See also @url{http://http://www.osrg.net/sheepdog/}.
1896
1897 @end table
1898 ETEXI
1899
1900 DEFHEADING(Bluetooth(R) options:)
1901
1902 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
1903     "-bt hci,null    dumb bluetooth HCI - doesn't respond to commands\n" \
1904     "-bt hci,host[:id]\n" \
1905     "                use host's HCI with the given name\n" \
1906     "-bt hci[,vlan=n]\n" \
1907     "                emulate a standard HCI in virtual scatternet 'n'\n" \
1908     "-bt vhci[,vlan=n]\n" \
1909     "                add host computer to virtual scatternet 'n' using VHCI\n" \
1910     "-bt device:dev[,vlan=n]\n" \
1911     "                emulate a bluetooth device 'dev' in scatternet 'n'\n",
1912     QEMU_ARCH_ALL)
1913 STEXI
1914 @table @option
1915
1916 @item -bt hci[...]
1917 @findex -bt
1918 Defines the function of the corresponding Bluetooth HCI.  -bt options
1919 are matched with the HCIs present in the chosen machine type.  For
1920 example when emulating a machine with only one HCI built into it, only
1921 the first @code{-bt hci[...]} option is valid and defines the HCI's
1922 logic.  The Transport Layer is decided by the machine type.  Currently
1923 the machines @code{n800} and @code{n810} have one HCI and all other
1924 machines have none.
1925
1926 @anchor{bt-hcis}
1927 The following three types are recognized:
1928
1929 @table @option
1930 @item -bt hci,null
1931 (default) The corresponding Bluetooth HCI assumes no internal logic
1932 and will not respond to any HCI commands or emit events.
1933
1934 @item -bt hci,host[:@var{id}]
1935 (@code{bluez} only) The corresponding HCI passes commands / events
1936 to / from the physical HCI identified by the name @var{id} (default:
1937 @code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
1938 capable systems like Linux.
1939
1940 @item -bt hci[,vlan=@var{n}]
1941 Add a virtual, standard HCI that will participate in the Bluetooth
1942 scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
1943 VLANs, devices inside a bluetooth network @var{n} can only communicate
1944 with other devices in the same network (scatternet).
1945 @end table
1946
1947 @item -bt vhci[,vlan=@var{n}]
1948 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
1949 to the host bluetooth stack instead of to the emulated target.  This
1950 allows the host and target machines to participate in a common scatternet
1951 and communicate.  Requires the Linux @code{vhci} driver installed.  Can
1952 be used as following:
1953
1954 @example
1955 qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
1956 @end example
1957
1958 @item -bt device:@var{dev}[,vlan=@var{n}]
1959 Emulate a bluetooth device @var{dev} and place it in network @var{n}
1960 (default @code{0}).  QEMU can only emulate one type of bluetooth devices
1961 currently:
1962
1963 @table @option
1964 @item keyboard
1965 Virtual wireless keyboard implementing the HIDP bluetooth profile.
1966 @end table
1967 @end table
1968 ETEXI
1969
1970 DEFHEADING()
1971
1972 DEFHEADING(Linux/Multiboot boot specific:)
1973 STEXI
1974
1975 When using these options, you can use a given Linux or Multiboot
1976 kernel without installing it in the disk image. It can be useful
1977 for easier testing of various kernels.
1978
1979 @table @option
1980 ETEXI
1981
1982 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
1983     "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
1984 STEXI
1985 @item -kernel @var{bzImage}
1986 @findex -kernel
1987 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
1988 or in multiboot format.
1989 ETEXI
1990
1991 DEF("append", HAS_ARG, QEMU_OPTION_append, \
1992     "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
1993 STEXI
1994 @item -append @var{cmdline}
1995 @findex -append
1996 Use @var{cmdline} as kernel command line
1997 ETEXI
1998
1999 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
2000            "-initrd file    use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
2001 STEXI
2002 @item -initrd @var{file}
2003 @findex -initrd
2004 Use @var{file} as initial ram disk.
2005
2006 @item -initrd "@var{file1} arg=foo,@var{file2}"
2007
2008 This syntax is only available with multiboot.
2009
2010 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
2011 first module.
2012 ETEXI
2013
2014 STEXI
2015 @end table
2016 ETEXI
2017
2018 DEFHEADING()
2019
2020 DEFHEADING(Debug/Expert options:)
2021
2022 STEXI
2023 @table @option
2024 ETEXI
2025
2026 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
2027     "-serial dev     redirect the serial port to char device 'dev'\n",
2028     QEMU_ARCH_ALL)
2029 STEXI
2030 @item -serial @var{dev}
2031 @findex -serial
2032 Redirect the virtual serial port to host character device
2033 @var{dev}. The default device is @code{vc} in graphical mode and
2034 @code{stdio} in non graphical mode.
2035
2036 This option can be used several times to simulate up to 4 serial
2037 ports.
2038
2039 Use @code{-serial none} to disable all serial ports.
2040
2041 Available character devices are:
2042 @table @option
2043 @item vc[:@var{W}x@var{H}]
2044 Virtual console. Optionally, a width and height can be given in pixel with
2045 @example
2046 vc:800x600
2047 @end example
2048 It is also possible to specify width or height in characters:
2049 @example
2050 vc:80Cx24C
2051 @end example
2052 @item pty
2053 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
2054 @item none
2055 No device is allocated.
2056 @item null
2057 void device
2058 @item /dev/XXX
2059 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
2060 parameters are set according to the emulated ones.
2061 @item /dev/parport@var{N}
2062 [Linux only, parallel port only] Use host parallel port
2063 @var{N}. Currently SPP and EPP parallel port features can be used.
2064 @item file:@var{filename}
2065 Write output to @var{filename}. No character can be read.
2066 @item stdio
2067 [Unix only] standard input/output
2068 @item pipe:@var{filename}
2069 name pipe @var{filename}
2070 @item COM@var{n}
2071 [Windows only] Use host serial port @var{n}
2072 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
2073 This implements UDP Net Console.
2074 When @var{remote_host} or @var{src_ip} are not specified
2075 they default to @code{0.0.0.0}.
2076 When not using a specified @var{src_port} a random port is automatically chosen.
2077
2078 If you just want a simple readonly console you can use @code{netcat} or
2079 @code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
2080 @code{nc -u -l -p 4555}. Any time qemu writes something to that port it
2081 will appear in the netconsole session.
2082
2083 If you plan to send characters back via netconsole or you want to stop
2084 and start qemu a lot of times, you should have qemu use the same
2085 source port each time by using something like @code{-serial
2086 udp::4555@@:4556} to qemu. Another approach is to use a patched
2087 version of netcat which can listen to a TCP port and send and receive
2088 characters via udp.  If you have a patched version of netcat which
2089 activates telnet remote echo and single char transfer, then you can
2090 use the following options to step up a netcat redirector to allow
2091 telnet on port 5555 to access the qemu port.
2092 @table @code
2093 @item Qemu Options:
2094 -serial udp::4555@@:4556
2095 @item netcat options:
2096 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2097 @item telnet options:
2098 localhost 5555
2099 @end table
2100
2101 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
2102 The TCP Net Console has two modes of operation.  It can send the serial
2103 I/O to a location or wait for a connection from a location.  By default
2104 the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
2105 the @var{server} option QEMU will wait for a client socket application
2106 to connect to the port before continuing, unless the @code{nowait}
2107 option was specified.  The @code{nodelay} option disables the Nagle buffering
2108 algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
2109 one TCP connection at a time is accepted. You can use @code{telnet} to
2110 connect to the corresponding character device.
2111 @table @code
2112 @item Example to send tcp console to 192.168.0.2 port 4444
2113 -serial tcp:192.168.0.2:4444
2114 @item Example to listen and wait on port 4444 for connection
2115 -serial tcp::4444,server
2116 @item Example to not wait and listen on ip 192.168.0.100 port 4444
2117 -serial tcp:192.168.0.100:4444,server,nowait
2118 @end table
2119
2120 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
2121 The telnet protocol is used instead of raw tcp sockets.  The options
2122 work the same as if you had specified @code{-serial tcp}.  The
2123 difference is that the port acts like a telnet server or client using
2124 telnet option negotiation.  This will also allow you to send the
2125 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
2126 sequence.  Typically in unix telnet you do it with Control-] and then
2127 type "send break" followed by pressing the enter key.
2128
2129 @item unix:@var{path}[,server][,nowait]
2130 A unix domain socket is used instead of a tcp socket.  The option works the
2131 same as if you had specified @code{-serial tcp} except the unix domain socket
2132 @var{path} is used for connections.
2133
2134 @item mon:@var{dev_string}
2135 This is a special option to allow the monitor to be multiplexed onto
2136 another serial port.  The monitor is accessed with key sequence of
2137 @key{Control-a} and then pressing @key{c}. See monitor access
2138 @ref{pcsys_keys} in the -nographic section for more keys.
2139 @var{dev_string} should be any one of the serial devices specified
2140 above.  An example to multiplex the monitor onto a telnet server
2141 listening on port 4444 would be:
2142 @table @code
2143 @item -serial mon:telnet::4444,server,nowait
2144 @end table
2145
2146 @item braille
2147 Braille device.  This will use BrlAPI to display the braille output on a real
2148 or fake device.
2149
2150 @item msmouse
2151 Three button serial mouse. Configure the guest to use Microsoft protocol.
2152 @end table
2153 ETEXI
2154
2155 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
2156     "-parallel dev   redirect the parallel port to char device 'dev'\n",
2157     QEMU_ARCH_ALL)
2158 STEXI
2159 @item -parallel @var{dev}
2160 @findex -parallel
2161 Redirect the virtual parallel port to host device @var{dev} (same
2162 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
2163 be used to use hardware devices connected on the corresponding host
2164 parallel port.
2165
2166 This option can be used several times to simulate up to 3 parallel
2167 ports.
2168
2169 Use @code{-parallel none} to disable all parallel ports.
2170 ETEXI
2171
2172 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
2173     "-monitor dev    redirect the monitor to char device 'dev'\n",
2174     QEMU_ARCH_ALL)
2175 STEXI
2176 @item -monitor @var{dev}
2177 @findex -monitor
2178 Redirect the monitor to host device @var{dev} (same devices as the
2179 serial port).
2180 The default device is @code{vc} in graphical mode and @code{stdio} in
2181 non graphical mode.
2182 ETEXI
2183 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
2184     "-qmp dev        like -monitor but opens in 'control' mode\n",
2185     QEMU_ARCH_ALL)
2186 STEXI
2187 @item -qmp @var{dev}
2188 @findex -qmp
2189 Like -monitor but opens in 'control' mode.
2190 ETEXI
2191
2192 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
2193     "-mon chardev=[name][,mode=readline|control][,default]\n", QEMU_ARCH_ALL)
2194 STEXI
2195 @item -mon chardev=[name][,mode=readline|control][,default]
2196 @findex -mon
2197 Setup monitor on chardev @var{name}.
2198 ETEXI
2199
2200 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
2201     "-debugcon dev   redirect the debug console to char device 'dev'\n",
2202     QEMU_ARCH_ALL)
2203 STEXI
2204 @item -debugcon @var{dev}
2205 @findex -debugcon
2206 Redirect the debug console to host device @var{dev} (same devices as the
2207 serial port).  The debug console is an I/O port which is typically port
2208 0xe9; writing to that I/O port sends output to this device.
2209 The default device is @code{vc} in graphical mode and @code{stdio} in
2210 non graphical mode.
2211 ETEXI
2212
2213 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
2214     "-pidfile file   write PID to 'file'\n", QEMU_ARCH_ALL)
2215 STEXI
2216 @item -pidfile @var{file}
2217 @findex -pidfile
2218 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
2219 from a script.
2220 ETEXI
2221
2222 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
2223     "-singlestep     always run in singlestep mode\n", QEMU_ARCH_ALL)
2224 STEXI
2225 @item -singlestep
2226 @findex -singlestep
2227 Run the emulation in single step mode.
2228 ETEXI
2229
2230 DEF("S", 0, QEMU_OPTION_S, \
2231     "-S              freeze CPU at startup (use 'c' to start execution)\n",
2232     QEMU_ARCH_ALL)
2233 STEXI
2234 @item -S
2235 @findex -S
2236 Do not start CPU at startup (you must type 'c' in the monitor).
2237 ETEXI
2238
2239 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
2240     "-gdb dev        wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
2241 STEXI
2242 @item -gdb @var{dev}
2243 @findex -gdb
2244 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
2245 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
2246 stdio are reasonable use case. The latter is allowing to start qemu from
2247 within gdb and establish the connection via a pipe:
2248 @example
2249 (gdb) target remote | exec qemu -gdb stdio ...
2250 @end example
2251 ETEXI
2252
2253 DEF("s", 0, QEMU_OPTION_s, \
2254     "-s              shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
2255     QEMU_ARCH_ALL)
2256 STEXI
2257 @item -s
2258 @findex -s
2259 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
2260 (@pxref{gdb_usage}).
2261 ETEXI
2262
2263 DEF("d", HAS_ARG, QEMU_OPTION_d, \
2264     "-d item1,...    output log to /tmp/qemu.log (use -d ? for a list of log items)\n",
2265     QEMU_ARCH_ALL)
2266 STEXI
2267 @item -d
2268 @findex -d
2269 Output log in /tmp/qemu.log
2270 ETEXI
2271
2272 DEF("D", HAS_ARG, QEMU_OPTION_D, \
2273     "-D logfile      output log to logfile (instead of the default /tmp/qemu.log)\n",
2274     QEMU_ARCH_ALL)
2275 STEXI
2276 @item -D
2277 @findex -D
2278 Output log in logfile instead of /tmp/qemu.log
2279 ETEXI
2280
2281 DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
2282     "-hdachs c,h,s[,t]\n" \
2283     "                force hard disk 0 physical geometry and the optional BIOS\n" \
2284     "                translation (t=none or lba) (usually qemu can guess them)\n",
2285     QEMU_ARCH_ALL)
2286 STEXI
2287 @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
2288 @findex -hdachs
2289 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
2290 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
2291 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
2292 all those parameters. This option is useful for old MS-DOS disk
2293 images.
2294 ETEXI
2295
2296 DEF("L", HAS_ARG, QEMU_OPTION_L, \
2297     "-L path         set the directory for the BIOS, VGA BIOS and keymaps\n",
2298     QEMU_ARCH_ALL)
2299 STEXI
2300 @item -L  @var{path}
2301 @findex -L
2302 Set the directory for the BIOS, VGA BIOS and keymaps.
2303 ETEXI
2304
2305 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
2306     "-bios file      set the filename for the BIOS\n", QEMU_ARCH_ALL)
2307 STEXI
2308 @item -bios @var{file}
2309 @findex -bios
2310 Set the filename for the BIOS.
2311 ETEXI
2312
2313 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
2314     "-enable-kvm     enable KVM full virtualization support\n", QEMU_ARCH_ALL)
2315 STEXI
2316 @item -enable-kvm
2317 @findex -enable-kvm
2318 Enable KVM full virtualization support. This option is only available
2319 if KVM support is enabled when compiling.
2320 ETEXI
2321
2322 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
2323     "-xen-domid id   specify xen guest domain id\n", QEMU_ARCH_ALL)
2324 DEF("xen-create", 0, QEMU_OPTION_xen_create,
2325     "-xen-create     create domain using xen hypercalls, bypassing xend\n"
2326     "                warning: should not be used when xend is in use\n",
2327     QEMU_ARCH_ALL)
2328 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
2329     "-xen-attach     attach to existing xen domain\n"
2330     "                xend will use this when starting qemu\n",
2331     QEMU_ARCH_ALL)
2332 STEXI
2333 @item -xen-domid @var{id}
2334 @findex -xen-domid
2335 Specify xen guest domain @var{id} (XEN only).
2336 @item -xen-create
2337 @findex -xen-create
2338 Create domain using xen hypercalls, bypassing xend.
2339 Warning: should not be used when xend is in use (XEN only).
2340 @item -xen-attach
2341 @findex -xen-attach
2342 Attach to existing xen domain.
2343 xend will use this when starting qemu (XEN only).
2344 ETEXI
2345
2346 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
2347     "-no-reboot      exit instead of rebooting\n", QEMU_ARCH_ALL)
2348 STEXI
2349 @item -no-reboot
2350 @findex -no-reboot
2351 Exit instead of rebooting.
2352 ETEXI
2353
2354 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
2355     "-no-shutdown    stop before shutdown\n", QEMU_ARCH_ALL)
2356 STEXI
2357 @item -no-shutdown
2358 @findex -no-shutdown
2359 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
2360 This allows for instance switching to monitor to commit changes to the
2361 disk image.
2362 ETEXI
2363
2364 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
2365     "-loadvm [tag|id]\n" \
2366     "                start right away with a saved state (loadvm in monitor)\n",
2367     QEMU_ARCH_ALL)
2368 STEXI
2369 @item -loadvm @var{file}
2370 @findex -loadvm
2371 Start right away with a saved state (@code{loadvm} in monitor)
2372 ETEXI
2373
2374 #ifndef _WIN32
2375 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
2376     "-daemonize      daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
2377 #endif
2378 STEXI
2379 @item -daemonize
2380 @findex -daemonize
2381 Daemonize the QEMU process after initialization.  QEMU will not detach from
2382 standard IO until it is ready to receive connections on any of its devices.
2383 This option is a useful way for external programs to launch QEMU without having
2384 to cope with initialization race conditions.
2385 ETEXI
2386
2387 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
2388     "-option-rom rom load a file, rom, into the option ROM space\n",
2389     QEMU_ARCH_ALL)
2390 STEXI
2391 @item -option-rom @var{file}
2392 @findex -option-rom
2393 Load the contents of @var{file} as an option ROM.
2394 This option is useful to load things like EtherBoot.
2395 ETEXI
2396
2397 DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
2398     "-clock          force the use of the given methods for timer alarm.\n" \
2399     "                To see what timers are available use -clock ?\n",
2400     QEMU_ARCH_ALL)
2401 STEXI
2402 @item -clock @var{method}
2403 @findex -clock
2404 Force the use of the given methods for timer alarm. To see what timers
2405 are available use -clock ?.
2406 ETEXI
2407
2408 HXCOMM Options deprecated by -rtc
2409 DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
2410 DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
2411
2412 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
2413     "-rtc [base=utc|localtime|date][,clock=host|vm][,driftfix=none|slew]\n" \
2414     "                set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
2415     QEMU_ARCH_ALL)
2416
2417 STEXI
2418
2419 @item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
2420 @findex -rtc
2421 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
2422 UTC or local time, respectively. @code{localtime} is required for correct date in
2423 MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
2424 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
2425
2426 By default the RTC is driven by the host system time. This allows to use the
2427 RTC as accurate reference clock inside the guest, specifically if the host
2428 time is smoothly following an accurate external reference clock, e.g. via NTP.
2429 If you want to isolate the guest time from the host, even prevent it from
2430 progressing during suspension, you can set @option{clock} to @code{vm} instead.
2431
2432 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
2433 specifically with Windows' ACPI HAL. This option will try to figure out how
2434 many timer interrupts were not processed by the Windows guest and will
2435 re-inject them.
2436 ETEXI
2437
2438 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
2439     "-icount [N|auto]\n" \
2440     "                enable virtual instruction counter with 2^N clock ticks per\n" \
2441     "                instruction\n", QEMU_ARCH_ALL)
2442 STEXI
2443 @item -icount [@var{N}|auto]
2444 @findex -icount
2445 Enable virtual instruction counter.  The virtual cpu will execute one
2446 instruction every 2^@var{N} ns of virtual time.  If @code{auto} is specified
2447 then the virtual cpu speed will be automatically adjusted to keep virtual
2448 time within a few seconds of real time.
2449
2450 Note that while this option can give deterministic behavior, it does not
2451 provide cycle accurate emulation.  Modern CPUs contain superscalar out of
2452 order cores with complex cache hierarchies.  The number of instructions
2453 executed often has little or no correlation with actual performance.
2454 ETEXI
2455
2456 DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
2457     "-watchdog i6300esb|ib700\n" \
2458     "                enable virtual hardware watchdog [default=none]\n",
2459     QEMU_ARCH_ALL)
2460 STEXI
2461 @item -watchdog @var{model}
2462 @findex -watchdog
2463 Create a virtual hardware watchdog device.  Once enabled (by a guest
2464 action), the watchdog must be periodically polled by an agent inside
2465 the guest or else the guest will be restarted.
2466
2467 The @var{model} is the model of hardware watchdog to emulate.  Choices
2468 for model are: @code{ib700} (iBASE 700) which is a very simple ISA
2469 watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O
2470 controller hub) which is a much more featureful PCI-based dual-timer
2471 watchdog.  Choose a model for which your guest has drivers.
2472
2473 Use @code{-watchdog ?} to list available hardware models.  Only one
2474 watchdog can be enabled for a guest.
2475 ETEXI
2476
2477 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
2478     "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
2479     "                action when watchdog fires [default=reset]\n",
2480     QEMU_ARCH_ALL)
2481 STEXI
2482 @item -watchdog-action @var{action}
2483
2484 The @var{action} controls what QEMU will do when the watchdog timer
2485 expires.
2486 The default is
2487 @code{reset} (forcefully reset the guest).
2488 Other possible actions are:
2489 @code{shutdown} (attempt to gracefully shutdown the guest),
2490 @code{poweroff} (forcefully poweroff the guest),
2491 @code{pause} (pause the guest),
2492 @code{debug} (print a debug message and continue), or
2493 @code{none} (do nothing).
2494
2495 Note that the @code{shutdown} action requires that the guest responds
2496 to ACPI signals, which it may not be able to do in the sort of
2497 situations where the watchdog would have expired, and thus
2498 @code{-watchdog-action shutdown} is not recommended for production use.
2499
2500 Examples:
2501
2502 @table @code
2503 @item -watchdog i6300esb -watchdog-action pause
2504 @item -watchdog ib700
2505 @end table
2506 ETEXI
2507
2508 DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
2509     "-echr chr       set terminal escape character instead of ctrl-a\n",
2510     QEMU_ARCH_ALL)
2511 STEXI
2512
2513 @item -echr @var{numeric_ascii_value}
2514 @findex -echr
2515 Change the escape character used for switching to the monitor when using
2516 monitor and serial sharing.  The default is @code{0x01} when using the
2517 @code{-nographic} option.  @code{0x01} is equal to pressing
2518 @code{Control-a}.  You can select a different character from the ascii
2519 control keys where 1 through 26 map to Control-a through Control-z.  For
2520 instance you could use the either of the following to change the escape
2521 character to Control-t.
2522 @table @code
2523 @item -echr 0x14
2524 @item -echr 20
2525 @end table
2526 ETEXI
2527
2528 DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
2529     "-virtioconsole c\n" \
2530     "                set virtio console\n", QEMU_ARCH_ALL)
2531 STEXI
2532 @item -virtioconsole @var{c}
2533 @findex -virtioconsole
2534 Set virtio console.
2535
2536 This option is maintained for backward compatibility.
2537
2538 Please use @code{-device virtconsole} for the new way of invocation.
2539 ETEXI
2540
2541 DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
2542     "-show-cursor    show cursor\n", QEMU_ARCH_ALL)
2543 STEXI
2544 @item -show-cursor
2545 @findex -show-cursor
2546 Show cursor.
2547 ETEXI
2548
2549 DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
2550     "-tb-size n      set TB size\n", QEMU_ARCH_ALL)
2551 STEXI
2552 @item -tb-size @var{n}
2553 @findex -tb-size
2554 Set TB size.
2555 ETEXI
2556
2557 DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
2558     "-incoming p     prepare for incoming migration, listen on port p\n",
2559     QEMU_ARCH_ALL)
2560 STEXI
2561 @item -incoming @var{port}
2562 @findex -incoming
2563 Prepare for incoming migration, listen on @var{port}.
2564 ETEXI
2565
2566 DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
2567     "-nodefaults     don't create default devices\n", QEMU_ARCH_ALL)
2568 STEXI
2569 @item -nodefaults
2570 @findex -nodefaults
2571 Don't create default devices.
2572 ETEXI
2573
2574 #ifndef _WIN32
2575 DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
2576     "-chroot dir     chroot to dir just before starting the VM\n",
2577     QEMU_ARCH_ALL)
2578 #endif
2579 STEXI
2580 @item -chroot @var{dir}
2581 @findex -chroot
2582 Immediately before starting guest execution, chroot to the specified
2583 directory.  Especially useful in combination with -runas.
2584 ETEXI
2585
2586 #ifndef _WIN32
2587 DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
2588     "-runas user     change to user id user just before starting the VM\n",
2589     QEMU_ARCH_ALL)
2590 #endif
2591 STEXI
2592 @item -runas @var{user}
2593 @findex -runas
2594 Immediately before starting guest execution, drop root privileges, switching
2595 to the specified user.
2596 ETEXI
2597
2598 DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
2599     "-prom-env variable=value\n"
2600     "                set OpenBIOS nvram variables\n",
2601     QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
2602 STEXI
2603 @item -prom-env @var{variable}=@var{value}
2604 @findex -prom-env
2605 Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
2606 ETEXI
2607 DEF("semihosting", 0, QEMU_OPTION_semihosting,
2608     "-semihosting    semihosting mode\n", QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA)
2609 STEXI
2610 @item -semihosting
2611 @findex -semihosting
2612 Semihosting mode (ARM, M68K, Xtensa only).
2613 ETEXI
2614 DEF("old-param", 0, QEMU_OPTION_old_param,
2615     "-old-param      old param mode\n", QEMU_ARCH_ARM)
2616 STEXI
2617 @item -old-param
2618 @findex -old-param (ARM)
2619 Old param mode (ARM only).
2620 ETEXI
2621
2622 DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
2623     "-readconfig <file>\n", QEMU_ARCH_ALL)
2624 STEXI
2625 @item -readconfig @var{file}
2626 @findex -readconfig
2627 Read device configuration from @var{file}.
2628 ETEXI
2629 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
2630     "-writeconfig <file>\n"
2631     "                read/write config file\n", QEMU_ARCH_ALL)
2632 STEXI
2633 @item -writeconfig @var{file}
2634 @findex -writeconfig
2635 Write device configuration to @var{file}.
2636 ETEXI
2637 DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
2638     "-nodefconfig\n"
2639     "                do not load default config files at startup\n",
2640     QEMU_ARCH_ALL)
2641 STEXI
2642 @item -nodefconfig
2643 @findex -nodefconfig
2644 Normally QEMU loads a configuration file from @var{sysconfdir}/qemu.conf and
2645 @var{sysconfdir}/target-@var{ARCH}.conf on startup.  The @code{-nodefconfig}
2646 option will prevent QEMU from loading these configuration files at startup.
2647 ETEXI
2648 DEF("trace", HAS_ARG, QEMU_OPTION_trace,
2649     "-trace [events=<file>][,file=<file>]\n"
2650     "                specify tracing options\n",
2651     QEMU_ARCH_ALL)
2652 STEXI
2653 HXCOMM This line is not accurate, as some sub-options are backend-specific but
2654 HXCOMM HX does not support conditional compilation of text.
2655 @item -trace [events=@var{file}][,file=@var{file}]
2656 @findex -trace
2657
2658 Specify tracing options.
2659
2660 @table @option
2661 @item events=@var{file}
2662 Immediately enable events listed in @var{file}.
2663 The file must contain one event name (as listed in the @var{trace-events} file)
2664 per line.
2665 This option is only available if QEMU has been compiled with
2666 either @var{simple} or @var{stderr} tracing backend.
2667 @item file=@var{file}
2668 Log output traces to @var{file}.
2669
2670 This option is only available if QEMU has been compiled with
2671 the @var{simple} tracing backend.
2672 @end table
2673 ETEXI
2674
2675 HXCOMM This is the last statement. Insert new options before this line!
2676 STEXI
2677 @end table
2678 ETEXI