Fix non-ACPI Timer Interrupt Routing - v3
[qemu.git] / qemu-options.hx
bloba58287cbff43a0520e9ac79363506a79bafe76d8
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) is used to construct
5 HXCOMM option structures, enums and help message.
6 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
8 DEFHEADING(Standard options:)
9 STEXI
10 @table @option
11 ETEXI
13 DEF("help", 0, QEMU_OPTION_h,
14 "-h or -help display this help and exit\n")
15 STEXI
16 @item -h
17 Display help and exit
18 ETEXI
20 DEF("version", 0, QEMU_OPTION_version,
21 "-version display version information and exit\n")
22 STEXI
23 @item -version
24 Display version information and exit
25 ETEXI
27 DEF("M", HAS_ARG, QEMU_OPTION_M,
28 "-M machine select emulated machine (-M ? for list)\n")
29 STEXI
30 @item -M @var{machine}
31 Select the emulated @var{machine} (@code{-M ?} for list)
32 ETEXI
34 DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
35 "-cpu cpu select CPU (-cpu ? for list)\n")
36 STEXI
37 @item -cpu @var{model}
38 Select CPU model (-cpu ? for list and additional feature selection)
39 ETEXI
41 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
42 "-smp n set the number of CPUs to 'n' [default=1]\n")
43 STEXI
44 @item -smp @var{n}
45 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
46 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
47 to 4.
48 ETEXI
50 DEF("numa", HAS_ARG, QEMU_OPTION_numa,
51 "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n")
52 STEXI
53 @item -numa @var{opts}
54 Simulate a multi node NUMA system. If mem and cpus are omitted, resources
55 are split equally.
56 ETEXI
58 DEF("fda", HAS_ARG, QEMU_OPTION_fda,
59 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n")
60 DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "")
61 STEXI
62 @item -fda @var{file}
63 @item -fdb @var{file}
64 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
65 use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
66 ETEXI
68 DEF("hda", HAS_ARG, QEMU_OPTION_hda,
69 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n")
70 DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "")
71 DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
72 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n")
73 DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "")
74 STEXI
75 @item -hda @var{file}
76 @item -hdb @var{file}
77 @item -hdc @var{file}
78 @item -hdd @var{file}
79 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
80 ETEXI
82 DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
83 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n")
84 STEXI
85 @item -cdrom @var{file}
86 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
87 @option{-cdrom} at the same time). You can use the host CD-ROM by
88 using @file{/dev/cdrom} as filename (@pxref{host_drives}).
89 ETEXI
91 DEF("drive", HAS_ARG, QEMU_OPTION_drive,
92 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
93 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
94 " [,cache=writethrough|writeback|none][,format=f][,serial=s]\n"
95 " [,addr=A]\n"
96 " use 'file' as a drive image\n")
97 STEXI
98 @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
100 Define a new drive. Valid options are:
102 @table @code
103 @item file=@var{file}
104 This option defines which disk image (@pxref{disk_images}) to use with
105 this drive. If the filename contains comma, you must double it
106 (for instance, "file=my,,file" to use file "my,file").
107 @item if=@var{interface}
108 This option defines on which type on interface the drive is connected.
109 Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
110 @item bus=@var{bus},unit=@var{unit}
111 These options define where is connected the drive by defining the bus number and
112 the unit id.
113 @item index=@var{index}
114 This option defines where is connected the drive by using an index in the list
115 of available connectors of a given interface type.
116 @item media=@var{media}
117 This option defines the type of the media: disk or cdrom.
118 @item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
119 These options have the same definition as they have in @option{-hdachs}.
120 @item snapshot=@var{snapshot}
121 @var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
122 @item cache=@var{cache}
123 @var{cache} is "none", "writeback", or "writethrough" and controls how the host cache is used to access block data.
124 @item format=@var{format}
125 Specify which disk @var{format} will be used rather than detecting
126 the format. Can be used to specifiy format=raw to avoid interpreting
127 an untrusted format header.
128 @item serial=@var{serial}
129 This option specifies the serial number to assign to the device.
130 @item addr=@var{addr}
131 Specify the controller's PCI address (if=virtio only).
132 @end table
134 By default, writethrough caching is used for all block device. This means that
135 the host page cache will be used to read and write data but write notification
136 will be sent to the guest only when the data has been reported as written by
137 the storage subsystem.
139 Writeback caching will report data writes as completed as soon as the data is
140 present in the host page cache. This is safe as long as you trust your host.
141 If your host crashes or loses power, then the guest may experience data
142 corruption. When using the @option{-snapshot} option, writeback caching is
143 used by default.
145 The host page cache can be avoided entirely with @option{cache=none}. This will
146 attempt to do disk IO directly to the guests memory. QEMU may still perform
147 an internal copy of the data.
149 Some block drivers perform badly with @option{cache=writethrough}, most notably,
150 qcow2. If performance is more important than correctness,
151 @option{cache=writeback} should be used with qcow2.
153 Instead of @option{-cdrom} you can use:
154 @example
155 qemu -drive file=file,index=2,media=cdrom
156 @end example
158 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
159 use:
160 @example
161 qemu -drive file=file,index=0,media=disk
162 qemu -drive file=file,index=1,media=disk
163 qemu -drive file=file,index=2,media=disk
164 qemu -drive file=file,index=3,media=disk
165 @end example
167 You can connect a CDROM to the slave of ide0:
168 @example
169 qemu -drive file=file,if=ide,index=1,media=cdrom
170 @end example
172 If you don't specify the "file=" argument, you define an empty drive:
173 @example
174 qemu -drive if=ide,index=1,media=cdrom
175 @end example
177 You can connect a SCSI disk with unit ID 6 on the bus #0:
178 @example
179 qemu -drive file=file,if=scsi,bus=0,unit=6
180 @end example
182 Instead of @option{-fda}, @option{-fdb}, you can use:
183 @example
184 qemu -drive file=file,index=0,if=floppy
185 qemu -drive file=file,index=1,if=floppy
186 @end example
188 By default, @var{interface} is "ide" and @var{index} is automatically
189 incremented:
190 @example
191 qemu -drive file=a -drive file=b"
192 @end example
193 is interpreted like:
194 @example
195 qemu -hda a -hdb b
196 @end example
197 ETEXI
199 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
200 "-mtdblock file use 'file' as on-board Flash memory image\n")
201 STEXI
203 @item -mtdblock file
204 Use 'file' as on-board Flash memory image.
205 ETEXI
207 DEF("sd", HAS_ARG, QEMU_OPTION_sd,
208 "-sd file use 'file' as SecureDigital card image\n")
209 STEXI
210 @item -sd file
211 Use 'file' as SecureDigital card image.
212 ETEXI
214 DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
215 "-pflash file use 'file' as a parallel flash image\n")
216 STEXI
217 @item -pflash file
218 Use 'file' as a parallel flash image.
219 ETEXI
221 DEF("boot", HAS_ARG, QEMU_OPTION_boot,
222 "-boot [order=drives][,once=drives][,menu=on|off]\n"
223 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n")
224 STEXI
225 @item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off]
227 Specify boot order @var{drives} as a string of drive letters. Valid
228 drive letters depend on the target achitecture. The x86 PC uses: a, b
229 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
230 from network adapter 1-4), hard disk boot is the default. To apply a
231 particular boot order only on the first startup, specify it via
232 @option{once}.
234 Interactive boot menus/prompts can be enabled via @option{menu=on} as far
235 as firmware/BIOS supports them. The default is non-interactive boot.
237 @example
238 # try to boot from network first, then from hard disk
239 qemu -boot order=nc
240 # boot from CD-ROM first, switch back to default order after reboot
241 qemu -boot once=d
242 @end example
244 Note: The legacy format '-boot @var{drives}' is still supported but its
245 use is discouraged as it may be removed from future versions.
246 ETEXI
248 DEF("snapshot", 0, QEMU_OPTION_snapshot,
249 "-snapshot write to temporary files instead of disk image files\n")
250 STEXI
251 @item -snapshot
252 Write to temporary files instead of disk image files. In this case,
253 the raw disk image you use is not written back. You can however force
254 the write back by pressing @key{C-a s} (@pxref{disk_images}).
255 ETEXI
257 DEF("m", HAS_ARG, QEMU_OPTION_m,
258 "-m megs set virtual RAM size to megs MB [default=%d]\n")
259 STEXI
260 @item -m @var{megs}
261 Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB. Optionally,
262 a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
263 gigabytes respectively.
264 ETEXI
266 DEF("k", HAS_ARG, QEMU_OPTION_k,
267 "-k language use keyboard layout (for example 'fr' for French)\n")
268 STEXI
269 @item -k @var{language}
271 Use keyboard layout @var{language} (for example @code{fr} for
272 French). This option is only needed where it is not easy to get raw PC
273 keycodes (e.g. on Macs, with some X11 servers or with a VNC
274 display). You don't normally need to use it on PC/Linux or PC/Windows
275 hosts.
277 The available layouts are:
278 @example
279 ar de-ch es fo fr-ca hu ja mk no pt-br sv
280 da en-gb et fr fr-ch is lt nl pl ru th
281 de en-us fi fr-be hr it lv nl-be pt sl tr
282 @end example
284 The default is @code{en-us}.
285 ETEXI
288 #ifdef HAS_AUDIO
289 DEF("audio-help", 0, QEMU_OPTION_audio_help,
290 "-audio-help print list of audio drivers and their options\n")
291 #endif
292 STEXI
293 @item -audio-help
295 Will show the audio subsystem help: list of drivers, tunable
296 parameters.
297 ETEXI
299 #ifdef HAS_AUDIO
300 DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
301 "-soundhw c1,... enable audio support\n"
302 " and only specified sound cards (comma separated list)\n"
303 " use -soundhw ? to get the list of supported cards\n"
304 " use -soundhw all to enable all of them\n")
305 #endif
306 STEXI
307 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
309 Enable audio and selected sound hardware. Use ? to print all
310 available sound hardware.
312 @example
313 qemu -soundhw sb16,adlib disk.img
314 qemu -soundhw es1370 disk.img
315 qemu -soundhw ac97 disk.img
316 qemu -soundhw all disk.img
317 qemu -soundhw ?
318 @end example
320 Note that Linux's i810_audio OSS kernel (for AC97) module might
321 require manually specifying clocking.
323 @example
324 modprobe i810_audio clocking=48000
325 @end example
326 ETEXI
328 STEXI
329 @end table
330 ETEXI
332 DEF("usb", 0, QEMU_OPTION_usb,
333 "-usb enable the USB driver (will be the default soon)\n")
334 STEXI
335 USB options:
336 @table @option
338 @item -usb
339 Enable the USB driver (will be the default soon)
340 ETEXI
342 DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
343 "-usbdevice name add the host or guest USB device 'name'\n")
344 STEXI
346 @item -usbdevice @var{devname}
347 Add the USB device @var{devname}. @xref{usb_devices}.
349 @table @code
351 @item mouse
352 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
354 @item tablet
355 Pointer device that uses absolute coordinates (like a touchscreen). This
356 means qemu is able to report the mouse position without having to grab the
357 mouse. Also overrides the PS/2 mouse emulation when activated.
359 @item disk:[format=@var{format}]:file
360 Mass storage device based on file. The optional @var{format} argument
361 will be used rather than detecting the format. Can be used to specifiy
362 format=raw to avoid interpreting an untrusted format header.
364 @item host:bus.addr
365 Pass through the host device identified by bus.addr (Linux only).
367 @item host:vendor_id:product_id
368 Pass through the host device identified by vendor_id:product_id (Linux only).
370 @item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
371 Serial converter to host character device @var{dev}, see @code{-serial} for the
372 available devices.
374 @item braille
375 Braille device. This will use BrlAPI to display the braille output on a real
376 or fake device.
378 @item net:options
379 Network adapter that supports CDC ethernet and RNDIS protocols.
381 @end table
382 ETEXI
384 DEF("name", HAS_ARG, QEMU_OPTION_name,
385 "-name string1[,process=string2] set the name of the guest\n"
386 " string1 sets the window title and string2 the process name (on Linux)\n")
387 STEXI
388 @item -name @var{name}
389 Sets the @var{name} of the guest.
390 This name will be displayed in the SDL window caption.
391 The @var{name} will also be used for the VNC server.
392 Also optionally set the top visible process name in Linux.
393 ETEXI
395 DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
396 "-uuid %%08x-%%04x-%%04x-%%04x-%%012x\n"
397 " specify machine UUID\n")
398 STEXI
399 @item -uuid @var{uuid}
400 Set system UUID.
401 ETEXI
403 STEXI
404 @end table
405 ETEXI
407 DEFHEADING()
409 DEFHEADING(Display options:)
411 STEXI
412 @table @option
413 ETEXI
415 DEF("nographic", 0, QEMU_OPTION_nographic,
416 "-nographic disable graphical output and redirect serial I/Os to console\n")
417 STEXI
418 @item -nographic
420 Normally, QEMU uses SDL to display the VGA output. With this option,
421 you can totally disable graphical output so that QEMU is a simple
422 command line application. The emulated serial port is redirected on
423 the console. Therefore, you can still use QEMU to debug a Linux kernel
424 with a serial console.
425 ETEXI
427 #ifdef CONFIG_CURSES
428 DEF("curses", 0, QEMU_OPTION_curses,
429 "-curses use a curses/ncurses interface instead of SDL\n")
430 #endif
431 STEXI
432 @item -curses
434 Normally, QEMU uses SDL to display the VGA output. With this option,
435 QEMU can display the VGA output when in text mode using a
436 curses/ncurses interface. Nothing is displayed in graphical mode.
437 ETEXI
439 #ifdef CONFIG_SDL
440 DEF("no-frame", 0, QEMU_OPTION_no_frame,
441 "-no-frame open SDL window without a frame and window decorations\n")
442 #endif
443 STEXI
444 @item -no-frame
446 Do not use decorations for SDL windows and start them using the whole
447 available screen space. This makes the using QEMU in a dedicated desktop
448 workspace more convenient.
449 ETEXI
451 #ifdef CONFIG_SDL
452 DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
453 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n")
454 #endif
455 STEXI
456 @item -alt-grab
458 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt).
459 ETEXI
461 #ifdef CONFIG_SDL
462 DEF("no-quit", 0, QEMU_OPTION_no_quit,
463 "-no-quit disable SDL window close capability\n")
464 #endif
465 STEXI
466 @item -no-quit
468 Disable SDL window close capability.
469 ETEXI
471 #ifdef CONFIG_SDL
472 DEF("sdl", 0, QEMU_OPTION_sdl,
473 "-sdl enable SDL\n")
474 #endif
475 STEXI
476 @item -sdl
478 Enable SDL.
479 ETEXI
481 DEF("portrait", 0, QEMU_OPTION_portrait,
482 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n")
483 STEXI
484 @item -portrait
486 Rotate graphical output 90 deg left (only PXA LCD).
487 ETEXI
489 DEF("vga", HAS_ARG, QEMU_OPTION_vga,
490 "-vga [std|cirrus|vmware|xenfb|none]\n"
491 " select video card type\n")
492 STEXI
493 @item -vga @var{type}
494 Select type of VGA card to emulate. Valid values for @var{type} are
495 @table @code
496 @item cirrus
497 Cirrus Logic GD5446 Video card. All Windows versions starting from
498 Windows 95 should recognize and use this graphic card. For optimal
499 performances, use 16 bit color depth in the guest and the host OS.
500 (This one is the default)
501 @item std
502 Standard VGA card with Bochs VBE extensions. If your guest OS
503 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
504 to use high resolution modes (>= 1280x1024x16) then you should use
505 this option.
506 @item vmware
507 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
508 recent XFree86/XOrg server or Windows guest with a driver for this
509 card.
510 @item none
511 Disable VGA card.
512 @end table
513 ETEXI
515 DEF("full-screen", 0, QEMU_OPTION_full_screen,
516 "-full-screen start in full screen\n")
517 STEXI
518 @item -full-screen
519 Start in full screen.
520 ETEXI
522 #if defined(TARGET_PPC) || defined(TARGET_SPARC)
523 DEF("g", 1, QEMU_OPTION_g ,
524 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n")
525 #endif
526 STEXI
527 ETEXI
529 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
530 "-vnc display start a VNC server on display\n")
531 STEXI
532 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
534 Normally, QEMU uses SDL to display the VGA output. With this option,
535 you can have QEMU listen on VNC display @var{display} and redirect the VGA
536 display over the VNC session. It is very useful to enable the usb
537 tablet device when using this option (option @option{-usbdevice
538 tablet}). When using the VNC display, you must use the @option{-k}
539 parameter to set the keyboard layout if you are not using en-us. Valid
540 syntax for the @var{display} is
542 @table @code
544 @item @var{host}:@var{d}
546 TCP connections will only be allowed from @var{host} on display @var{d}.
547 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
548 be omitted in which case the server will accept connections from any host.
550 @item @code{unix}:@var{path}
552 Connections will be allowed over UNIX domain sockets where @var{path} is the
553 location of a unix socket to listen for connections on.
555 @item none
557 VNC is initialized but not started. The monitor @code{change} command
558 can be used to later start the VNC server.
560 @end table
562 Following the @var{display} value there may be one or more @var{option} flags
563 separated by commas. Valid options are
565 @table @code
567 @item reverse
569 Connect to a listening VNC client via a ``reverse'' connection. The
570 client is specified by the @var{display}. For reverse network
571 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
572 is a TCP port number, not a display number.
574 @item password
576 Require that password based authentication is used for client connections.
577 The password must be set separately using the @code{change} command in the
578 @ref{pcsys_monitor}
580 @item tls
582 Require that client use TLS when communicating with the VNC server. This
583 uses anonymous TLS credentials so is susceptible to a man-in-the-middle
584 attack. It is recommended that this option be combined with either the
585 @var{x509} or @var{x509verify} options.
587 @item x509=@var{/path/to/certificate/dir}
589 Valid if @option{tls} is specified. Require that x509 credentials are used
590 for negotiating the TLS session. The server will send its x509 certificate
591 to the client. It is recommended that a password be set on the VNC server
592 to provide authentication of the client when this is used. The path following
593 this option specifies where the x509 certificates are to be loaded from.
594 See the @ref{vnc_security} section for details on generating certificates.
596 @item x509verify=@var{/path/to/certificate/dir}
598 Valid if @option{tls} is specified. Require that x509 credentials are used
599 for negotiating the TLS session. The server will send its x509 certificate
600 to the client, and request that the client send its own x509 certificate.
601 The server will validate the client's certificate against the CA certificate,
602 and reject clients when validation fails. If the certificate authority is
603 trusted, this is a sufficient authentication mechanism. You may still wish
604 to set a password on the VNC server as a second authentication layer. The
605 path following this option specifies where the x509 certificates are to
606 be loaded from. See the @ref{vnc_security} section for details on generating
607 certificates.
609 @item sasl
611 Require that the client use SASL to authenticate with the VNC server.
612 The exact choice of authentication method used is controlled from the
613 system / user's SASL configuration file for the 'qemu' service. This
614 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
615 unprivileged user, an environment variable SASL_CONF_PATH can be used
616 to make it search alternate locations for the service config.
617 While some SASL auth methods can also provide data encryption (eg GSSAPI),
618 it is recommended that SASL always be combined with the 'tls' and
619 'x509' settings to enable use of SSL and server certificates. This
620 ensures a data encryption preventing compromise of authentication
621 credentials. See the @ref{vnc_security} section for details on using
622 SASL authentication.
624 @item acl
626 Turn on access control lists for checking of the x509 client certificate
627 and SASL party. For x509 certs, the ACL check is made against the
628 certificate's distinguished name. This is something that looks like
629 @code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
630 made against the username, which depending on the SASL plugin, may
631 include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
632 When the @option{acl} flag is set, the initial access list will be
633 empty, with a @code{deny} policy. Thus no one will be allowed to
634 use the VNC server until the ACLs have been loaded. This can be
635 achieved using the @code{acl} monitor command.
637 @end table
638 ETEXI
640 STEXI
641 @end table
642 ETEXI
644 DEFHEADING()
646 #ifdef TARGET_I386
647 DEFHEADING(i386 target only:)
648 #endif
649 STEXI
650 @table @option
651 ETEXI
653 #ifdef TARGET_I386
654 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
655 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n")
656 #endif
657 STEXI
658 @item -win2k-hack
659 Use it when installing Windows 2000 to avoid a disk full bug. After
660 Windows 2000 is installed, you no longer need this option (this option
661 slows down the IDE transfers).
662 ETEXI
664 #ifdef TARGET_I386
665 DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack,
666 "-rtc-td-hack use it to fix time drift in Windows ACPI HAL\n")
667 #endif
668 STEXI
669 @item -rtc-td-hack
670 Use it if you experience time drift problem in Windows with ACPI HAL.
671 This option will try to figure out how many timer interrupts were not
672 processed by the Windows guest and will re-inject them.
673 ETEXI
675 #ifdef TARGET_I386
676 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
677 "-no-fd-bootchk disable boot signature checking for floppy disks\n")
678 #endif
679 STEXI
680 @item -no-fd-bootchk
681 Disable boot signature checking for floppy disks in Bochs BIOS. It may
682 be needed to boot from old floppy disks.
683 ETEXI
685 #ifdef TARGET_I386
686 DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
687 "-no-acpi disable ACPI\n")
688 #endif
689 STEXI
690 @item -no-acpi
691 Disable ACPI (Advanced Configuration and Power Interface) support. Use
692 it if your guest OS complains about ACPI problems (PC target machine
693 only).
694 ETEXI
696 #ifdef TARGET_I386
697 DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
698 "-no-hpet disable HPET\n")
699 #endif
700 STEXI
701 @item -no-hpet
702 Disable HPET support.
703 ETEXI
705 #ifdef TARGET_I386
706 DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
707 "-balloon none disable balloon device\n"
708 "-balloon virtio[,addr=str]\n"
709 " enable virtio balloon device (default)\n")
710 #endif
711 STEXI
712 @item -balloon none
713 Disable balloon device.
714 @item -balloon virtio[,addr=@var{addr}]
715 Enable virtio balloon device (default), optionally with PCI address
716 @var{addr}.
717 ETEXI
719 #ifdef TARGET_I386
720 DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
721 "-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n][,asl_compiler_id=str][,asl_compiler_rev=n][,data=file1[:file2]...]\n"
722 " ACPI table description\n")
723 #endif
724 STEXI
725 @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}]...]
726 Add ACPI table with specified header fields and context from specified files.
727 ETEXI
729 #ifdef TARGET_I386
730 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
731 "-smbios file=binary\n"
732 " Load SMBIOS entry from binary file\n"
733 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%%d.%%d]\n"
734 " Specify SMBIOS type 0 fields\n"
735 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
736 " [,uuid=uuid][,sku=str][,family=str]\n"
737 " Specify SMBIOS type 1 fields\n")
738 #endif
739 STEXI
740 @item -smbios file=@var{binary}
741 Load SMBIOS entry from binary file.
743 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}]
744 Specify SMBIOS type 0 fields
746 @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}]
747 Specify SMBIOS type 1 fields
748 ETEXI
750 #ifdef TARGET_I386
751 DEFHEADING()
752 #endif
753 STEXI
754 @end table
755 ETEXI
757 DEFHEADING(Network options:)
758 STEXI
759 @table @option
760 ETEXI
762 HXCOMM Legacy slirp options (now moved to -net user):
763 #ifdef CONFIG_SLIRP
764 DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "")
765 DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "")
766 DEF("redir", HAS_ARG, QEMU_OPTION_redir, "")
767 #ifndef _WIN32
768 DEF("smb", HAS_ARG, QEMU_OPTION_smb, "")
769 #endif
770 #endif
772 DEF("net", HAS_ARG, QEMU_OPTION_net,
773 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
774 " create a new Network Interface Card and connect it to VLAN 'n'\n"
775 #ifdef CONFIG_SLIRP
776 "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=y|n]\n"
777 " [,hostname=host][,dhcpstart=addr][,dns=addr][,tftp=dir][,bootfile=f]\n"
778 " [,hostfwd=rule][,guestfwd=rule]"
779 #ifndef _WIN32
780 "[,smb=dir[,smbserver=addr]]\n"
781 #endif
782 " connect the user mode network stack to VLAN 'n', configure its\n"
783 " DHCP server and enabled optional services\n"
784 #endif
785 #ifdef _WIN32
786 "-net tap[,vlan=n][,name=str],ifname=name\n"
787 " connect the host TAP network interface to VLAN 'n'\n"
788 #else
789 "-net tap[,vlan=n][,name=str][,fd=h][,ifname=name][,script=file][,downscript=dfile]"
790 #ifdef TUNSETSNDBUF
791 "[,sndbuf=nbytes]"
792 #endif
793 "\n"
794 " connect the host TAP network interface to VLAN 'n' and use the\n"
795 " network scripts 'file' (default=%s)\n"
796 " and 'dfile' (default=%s);\n"
797 " use '[down]script=no' to disable script execution;\n"
798 " use 'fd=h' to connect to an already opened TAP interface\n"
799 #ifdef TUNSETSNDBUF
800 " use 'sndbuf=nbytes' to limit the size of the send buffer; the\n"
801 " default of 'sndbuf=1048576' can be disabled using 'sndbuf=0'\n"
802 #endif
803 #endif
804 "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
805 " connect the vlan 'n' to another VLAN using a socket connection\n"
806 "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port]\n"
807 " connect the vlan 'n' to multicast maddr and port\n"
808 #ifdef CONFIG_VDE
809 "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
810 " connect the vlan 'n' to port 'n' of a vde switch running\n"
811 " on host and listening for incoming connections on 'socketpath'.\n"
812 " Use group 'groupname' and mode 'octalmode' to change default\n"
813 " ownership and permissions for communication port.\n"
814 #endif
815 "-net dump[,vlan=n][,file=f][,len=n]\n"
816 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
817 "-net none use it alone to have zero network devices; if no -net option\n"
818 " is provided, the default is '-net nic -net user'\n")
819 STEXI
820 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}][,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
821 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
822 = 0 is the default). The NIC is an ne2k_pci by default on the PC
823 target. Optionally, the MAC address can be changed to @var{mac}, the
824 device address set to @var{addr} (PCI cards only),
825 and a @var{name} can be assigned for use in monitor commands.
826 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
827 that the card should have; this option currently only affects virtio cards; set
828 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
829 NIC is created. Qemu can emulate several different models of network card.
830 Valid values for @var{type} are
831 @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
832 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
833 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
834 Not all devices are supported on all targets. Use -net nic,model=?
835 for a list of available devices for your target.
837 @item -net user[,@var{option}][,@var{option}][,...]
838 Use the user mode network stack which requires no administrator
839 privilege to run. Valid options are:
841 @table @code
842 @item vlan=@var{n}
843 Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
845 @item name=@var{name}
846 Assign symbolic name for use in monitor commands.
848 @item net=@var{addr}[/@var{mask}]
849 Set IP network address the guest will see. Optionally specify the netmask,
850 either in the form a.b.c.d or as number of valid top-most bits. Default is
851 10.0.2.0/8.
853 @item host=@var{addr}
854 Specify the guest-visible address of the host. Default is the 2nd IP in the
855 guest network, i.e. x.x.x.2.
857 @item restrict=y|yes|n|no
858 If this options is enabled, the guest will be isolated, i.e. it will not be
859 able to contact the host and no guest IP packets will be routed over the host
860 to the outside. This option does not affect explicitly set forwarding rule.
862 @item hostname=@var{name}
863 Specifies the client hostname reported by the builtin DHCP server.
865 @item dhcpstart=@var{addr}
866 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
867 is the 16th to 31st IP in the guest network, i.e. x.x.x.16 to x.x.x.31.
869 @item dns=@var{addr}
870 Specify the guest-visible address of the virtual nameserver. The address must
871 be different from the host address. Default is the 3rd IP in the guest network,
872 i.e. x.x.x.3.
874 @item tftp=@var{dir}
875 When using the user mode network stack, activate a built-in TFTP
876 server. The files in @var{dir} will be exposed as the root of a TFTP server.
877 The TFTP client on the guest must be configured in binary mode (use the command
878 @code{bin} of the Unix TFTP client).
880 @item bootfile=@var{file}
881 When using the user mode network stack, broadcast @var{file} as the BOOTP
882 filename. In conjunction with @option{tftp}, this can be used to network boot
883 a guest from a local directory.
885 Example (using pxelinux):
886 @example
887 qemu -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
888 @end example
890 @item smb=@var{dir}[,smbserver=@var{addr}]
891 When using the user mode network stack, activate a built-in SMB
892 server so that Windows OSes can access to the host files in @file{@var{dir}}
893 transparently. The IP address of the SMB server can be set to @var{addr}. By
894 default the 4th IP in the guest network is used, i.e. x.x.x.4.
896 In the guest Windows OS, the line:
897 @example
898 10.0.2.4 smbserver
899 @end example
900 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
901 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
903 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
905 Note that a SAMBA server must be installed on the host OS in
906 @file{/usr/sbin/smbd}. QEMU was tested successfully with smbd versions from
907 Red Hat 9, Fedora Core 3 and OpenSUSE 11.x.
909 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
910 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
911 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
912 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
913 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
914 be bound to a specific host interface. If no connection type is set, TCP is
915 used. This option can be given multiple times.
917 For example, to redirect host X11 connection from screen 1 to guest
918 screen 0, use the following:
920 @example
921 # on the host
922 qemu -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
923 # this host xterm should open in the guest X11 server
924 xterm -display :1
925 @end example
927 To redirect telnet connections from host port 5555 to telnet port on
928 the guest, use the following:
930 @example
931 # on the host
932 qemu -net user,hostfwd=tcp:5555::23 [...]
933 telnet localhost 5555
934 @end example
936 Then when you use on the host @code{telnet localhost 5555}, you
937 connect to the guest telnet server.
939 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
940 Forward guest TCP connections to the IP address @var{server} on port @var{port}
941 to the character device @var{dev}. This option can be given multiple times.
943 @end table
945 Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
946 processed and applied to -net user. Mixing them with the new configuration
947 syntax gives undefined results. Their use for new applications is discouraged
948 as they will be removed from future versions.
950 @item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}]
951 Connect the host TAP network interface @var{name} to VLAN @var{n}, use
952 the network script @var{file} to configure it and the network script
953 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
954 automatically provides one. @option{fd}=@var{h} can be used to specify
955 the handle of an already opened host TAP interface. The default network
956 configure script is @file{/etc/qemu-ifup} and the default network
957 deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no}
958 or @option{downscript=no} to disable script execution. Example:
960 @example
961 qemu linux.img -net nic -net tap
962 @end example
964 More complicated example (two NICs, each one connected to a TAP device)
965 @example
966 qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
967 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
968 @end example
970 @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
972 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
973 machine using a TCP socket connection. If @option{listen} is
974 specified, QEMU waits for incoming connections on @var{port}
975 (@var{host} is optional). @option{connect} is used to connect to
976 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
977 specifies an already opened TCP socket.
979 Example:
980 @example
981 # launch a first QEMU instance
982 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
983 -net socket,listen=:1234
984 # connect the VLAN 0 of this instance to the VLAN 0
985 # of the first instance
986 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
987 -net socket,connect=127.0.0.1:1234
988 @end example
990 @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
992 Create a VLAN @var{n} shared with another QEMU virtual
993 machines using a UDP multicast socket, effectively making a bus for
994 every QEMU with same multicast address @var{maddr} and @var{port}.
995 NOTES:
996 @enumerate
997 @item
998 Several QEMU can be running on different hosts and share same bus (assuming
999 correct multicast setup for these hosts).
1000 @item
1001 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1002 @url{http://user-mode-linux.sf.net}.
1003 @item
1004 Use @option{fd=h} to specify an already opened UDP multicast socket.
1005 @end enumerate
1007 Example:
1008 @example
1009 # launch one QEMU instance
1010 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1011 -net socket,mcast=230.0.0.1:1234
1012 # launch another QEMU instance on same "bus"
1013 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1014 -net socket,mcast=230.0.0.1:1234
1015 # launch yet another QEMU instance on same "bus"
1016 qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
1017 -net socket,mcast=230.0.0.1:1234
1018 @end example
1020 Example (User Mode Linux compat.):
1021 @example
1022 # launch QEMU instance (note mcast address selected
1023 # is UML's default)
1024 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1025 -net socket,mcast=239.192.168.1:1102
1026 # launch UML
1027 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
1028 @end example
1030 @item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
1031 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
1032 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
1033 and MODE @var{octalmode} to change default ownership and permissions for
1034 communication port. This option is available only if QEMU has been compiled
1035 with vde support enabled.
1037 Example:
1038 @example
1039 # launch vde switch
1040 vde_switch -F -sock /tmp/myswitch
1041 # launch QEMU instance
1042 qemu linux.img -net nic -net vde,sock=/tmp/myswitch
1043 @end example
1045 @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
1046 Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
1047 At most @var{len} bytes (64k by default) per packet are stored. The file format is
1048 libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
1050 @item -net none
1051 Indicate that no network devices should be configured. It is used to
1052 override the default configuration (@option{-net nic -net user}) which
1053 is activated if no @option{-net} options are provided.
1055 @end table
1056 ETEXI
1058 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
1059 "\n" \
1060 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
1061 "-bt hci,host[:id]\n" \
1062 " use host's HCI with the given name\n" \
1063 "-bt hci[,vlan=n]\n" \
1064 " emulate a standard HCI in virtual scatternet 'n'\n" \
1065 "-bt vhci[,vlan=n]\n" \
1066 " add host computer to virtual scatternet 'n' using VHCI\n" \
1067 "-bt device:dev[,vlan=n]\n" \
1068 " emulate a bluetooth device 'dev' in scatternet 'n'\n")
1069 STEXI
1070 Bluetooth(R) options:
1071 @table @option
1073 @item -bt hci[...]
1074 Defines the function of the corresponding Bluetooth HCI. -bt options
1075 are matched with the HCIs present in the chosen machine type. For
1076 example when emulating a machine with only one HCI built into it, only
1077 the first @code{-bt hci[...]} option is valid and defines the HCI's
1078 logic. The Transport Layer is decided by the machine type. Currently
1079 the machines @code{n800} and @code{n810} have one HCI and all other
1080 machines have none.
1082 @anchor{bt-hcis}
1083 The following three types are recognized:
1085 @table @code
1086 @item -bt hci,null
1087 (default) The corresponding Bluetooth HCI assumes no internal logic
1088 and will not respond to any HCI commands or emit events.
1090 @item -bt hci,host[:@var{id}]
1091 (@code{bluez} only) The corresponding HCI passes commands / events
1092 to / from the physical HCI identified by the name @var{id} (default:
1093 @code{hci0}) on the computer running QEMU. Only available on @code{bluez}
1094 capable systems like Linux.
1096 @item -bt hci[,vlan=@var{n}]
1097 Add a virtual, standard HCI that will participate in the Bluetooth
1098 scatternet @var{n} (default @code{0}). Similarly to @option{-net}
1099 VLANs, devices inside a bluetooth network @var{n} can only communicate
1100 with other devices in the same network (scatternet).
1101 @end table
1103 @item -bt vhci[,vlan=@var{n}]
1104 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
1105 to the host bluetooth stack instead of to the emulated target. This
1106 allows the host and target machines to participate in a common scatternet
1107 and communicate. Requires the Linux @code{vhci} driver installed. Can
1108 be used as following:
1110 @example
1111 qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
1112 @end example
1114 @item -bt device:@var{dev}[,vlan=@var{n}]
1115 Emulate a bluetooth device @var{dev} and place it in network @var{n}
1116 (default @code{0}). QEMU can only emulate one type of bluetooth devices
1117 currently:
1119 @table @code
1120 @item keyboard
1121 Virtual wireless keyboard implementing the HIDP bluetooth profile.
1122 @end table
1123 @end table
1124 ETEXI
1126 DEFHEADING()
1128 DEFHEADING(Linux/Multiboot boot specific:)
1129 STEXI
1131 When using these options, you can use a given Linux or Multiboot
1132 kernel without installing it in the disk image. It can be useful
1133 for easier testing of various kernels.
1135 @table @option
1136 ETEXI
1138 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
1139 "-kernel bzImage use 'bzImage' as kernel image\n")
1140 STEXI
1141 @item -kernel @var{bzImage}
1142 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
1143 or in multiboot format.
1144 ETEXI
1146 DEF("append", HAS_ARG, QEMU_OPTION_append, \
1147 "-append cmdline use 'cmdline' as kernel command line\n")
1148 STEXI
1149 @item -append @var{cmdline}
1150 Use @var{cmdline} as kernel command line
1151 ETEXI
1153 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
1154 "-initrd file use 'file' as initial ram disk\n")
1155 STEXI
1156 @item -initrd @var{file}
1157 Use @var{file} as initial ram disk.
1159 @item -initrd "@var{file1} arg=foo,@var{file2}"
1161 This syntax is only available with multiboot.
1163 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
1164 first module.
1165 ETEXI
1167 STEXI
1168 @end table
1169 ETEXI
1171 DEFHEADING()
1173 DEFHEADING(Debug/Expert options:)
1175 STEXI
1176 @table @option
1177 ETEXI
1179 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
1180 "-serial dev redirect the serial port to char device 'dev'\n")
1181 STEXI
1182 @item -serial @var{dev}
1183 Redirect the virtual serial port to host character device
1184 @var{dev}. The default device is @code{vc} in graphical mode and
1185 @code{stdio} in non graphical mode.
1187 This option can be used several times to simulate up to 4 serial
1188 ports.
1190 Use @code{-serial none} to disable all serial ports.
1192 Available character devices are:
1193 @table @code
1194 @item vc[:WxH]
1195 Virtual console. Optionally, a width and height can be given in pixel with
1196 @example
1197 vc:800x600
1198 @end example
1199 It is also possible to specify width or height in characters:
1200 @example
1201 vc:80Cx24C
1202 @end example
1203 @item pty
1204 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
1205 @item none
1206 No device is allocated.
1207 @item null
1208 void device
1209 @item /dev/XXX
1210 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
1211 parameters are set according to the emulated ones.
1212 @item /dev/parport@var{N}
1213 [Linux only, parallel port only] Use host parallel port
1214 @var{N}. Currently SPP and EPP parallel port features can be used.
1215 @item file:@var{filename}
1216 Write output to @var{filename}. No character can be read.
1217 @item stdio
1218 [Unix only] standard input/output
1219 @item pipe:@var{filename}
1220 name pipe @var{filename}
1221 @item COM@var{n}
1222 [Windows only] Use host serial port @var{n}
1223 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
1224 This implements UDP Net Console.
1225 When @var{remote_host} or @var{src_ip} are not specified
1226 they default to @code{0.0.0.0}.
1227 When not using a specified @var{src_port} a random port is automatically chosen.
1228 @item msmouse
1229 Three button serial mouse. Configure the guest to use Microsoft protocol.
1231 If you just want a simple readonly console you can use @code{netcat} or
1232 @code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
1233 @code{nc -u -l -p 4555}. Any time qemu writes something to that port it
1234 will appear in the netconsole session.
1236 If you plan to send characters back via netconsole or you want to stop
1237 and start qemu a lot of times, you should have qemu use the same
1238 source port each time by using something like @code{-serial
1239 udp::4555@@:4556} to qemu. Another approach is to use a patched
1240 version of netcat which can listen to a TCP port and send and receive
1241 characters via udp. If you have a patched version of netcat which
1242 activates telnet remote echo and single char transfer, then you can
1243 use the following options to step up a netcat redirector to allow
1244 telnet on port 5555 to access the qemu port.
1245 @table @code
1246 @item Qemu Options:
1247 -serial udp::4555@@:4556
1248 @item netcat options:
1249 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
1250 @item telnet options:
1251 localhost 5555
1252 @end table
1254 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
1255 The TCP Net Console has two modes of operation. It can send the serial
1256 I/O to a location or wait for a connection from a location. By default
1257 the TCP Net Console is sent to @var{host} at the @var{port}. If you use
1258 the @var{server} option QEMU will wait for a client socket application
1259 to connect to the port before continuing, unless the @code{nowait}
1260 option was specified. The @code{nodelay} option disables the Nagle buffering
1261 algorithm. If @var{host} is omitted, 0.0.0.0 is assumed. Only
1262 one TCP connection at a time is accepted. You can use @code{telnet} to
1263 connect to the corresponding character device.
1264 @table @code
1265 @item Example to send tcp console to 192.168.0.2 port 4444
1266 -serial tcp:192.168.0.2:4444
1267 @item Example to listen and wait on port 4444 for connection
1268 -serial tcp::4444,server
1269 @item Example to not wait and listen on ip 192.168.0.100 port 4444
1270 -serial tcp:192.168.0.100:4444,server,nowait
1271 @end table
1273 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
1274 The telnet protocol is used instead of raw tcp sockets. The options
1275 work the same as if you had specified @code{-serial tcp}. The
1276 difference is that the port acts like a telnet server or client using
1277 telnet option negotiation. This will also allow you to send the
1278 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
1279 sequence. Typically in unix telnet you do it with Control-] and then
1280 type "send break" followed by pressing the enter key.
1282 @item unix:@var{path}[,server][,nowait]
1283 A unix domain socket is used instead of a tcp socket. The option works the
1284 same as if you had specified @code{-serial tcp} except the unix domain socket
1285 @var{path} is used for connections.
1287 @item mon:@var{dev_string}
1288 This is a special option to allow the monitor to be multiplexed onto
1289 another serial port. The monitor is accessed with key sequence of
1290 @key{Control-a} and then pressing @key{c}. See monitor access
1291 @ref{pcsys_keys} in the -nographic section for more keys.
1292 @var{dev_string} should be any one of the serial devices specified
1293 above. An example to multiplex the monitor onto a telnet server
1294 listening on port 4444 would be:
1295 @table @code
1296 @item -serial mon:telnet::4444,server,nowait
1297 @end table
1299 @item braille
1300 Braille device. This will use BrlAPI to display the braille output on a real
1301 or fake device.
1303 @end table
1304 ETEXI
1306 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
1307 "-parallel dev redirect the parallel port to char device 'dev'\n")
1308 STEXI
1309 @item -parallel @var{dev}
1310 Redirect the virtual parallel port to host device @var{dev} (same
1311 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
1312 be used to use hardware devices connected on the corresponding host
1313 parallel port.
1315 This option can be used several times to simulate up to 3 parallel
1316 ports.
1318 Use @code{-parallel none} to disable all parallel ports.
1319 ETEXI
1321 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
1322 "-monitor dev redirect the monitor to char device 'dev'\n")
1323 STEXI
1324 @item -monitor @var{dev}
1325 Redirect the monitor to host device @var{dev} (same devices as the
1326 serial port).
1327 The default device is @code{vc} in graphical mode and @code{stdio} in
1328 non graphical mode.
1329 ETEXI
1331 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
1332 "-pidfile file write PID to 'file'\n")
1333 STEXI
1334 @item -pidfile @var{file}
1335 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
1336 from a script.
1337 ETEXI
1339 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
1340 "-singlestep always run in singlestep mode\n")
1341 STEXI
1342 @item -singlestep
1343 Run the emulation in single step mode.
1344 ETEXI
1346 DEF("S", 0, QEMU_OPTION_S, \
1347 "-S freeze CPU at startup (use 'c' to start execution)\n")
1348 STEXI
1349 @item -S
1350 Do not start CPU at startup (you must type 'c' in the monitor).
1351 ETEXI
1353 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
1354 "-gdb dev wait for gdb connection on 'dev'\n")
1355 STEXI
1356 @item -gdb @var{dev}
1357 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
1358 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
1359 stdio are reasonable use case. The latter is allowing to start qemu from
1360 within gdb and establish the connection via a pipe:
1361 @example
1362 (gdb) target remote | exec qemu -gdb stdio ...
1363 @end example
1364 ETEXI
1366 DEF("s", 0, QEMU_OPTION_s, \
1367 "-s shorthand for -gdb tcp::%s\n")
1368 STEXI
1369 @item -s
1370 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
1371 (@pxref{gdb_usage}).
1372 ETEXI
1374 DEF("d", HAS_ARG, QEMU_OPTION_d, \
1375 "-d item1,... output log to %s (use -d ? for a list of log items)\n")
1376 STEXI
1377 @item -d
1378 Output log in /tmp/qemu.log
1379 ETEXI
1381 DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
1382 "-hdachs c,h,s[,t]\n" \
1383 " force hard disk 0 physical geometry and the optional BIOS\n" \
1384 " translation (t=none or lba) (usually qemu can guess them)\n")
1385 STEXI
1386 @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
1387 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
1388 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
1389 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
1390 all those parameters. This option is useful for old MS-DOS disk
1391 images.
1392 ETEXI
1394 DEF("L", HAS_ARG, QEMU_OPTION_L, \
1395 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n")
1396 STEXI
1397 @item -L @var{path}
1398 Set the directory for the BIOS, VGA BIOS and keymaps.
1399 ETEXI
1401 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
1402 "-bios file set the filename for the BIOS\n")
1403 STEXI
1404 @item -bios @var{file}
1405 Set the filename for the BIOS.
1406 ETEXI
1408 #ifdef CONFIG_KQEMU
1409 DEF("kernel-kqemu", 0, QEMU_OPTION_kernel_kqemu, \
1410 "-kernel-kqemu enable KQEMU full virtualization (default is user mode only)\n")
1411 #endif
1412 STEXI
1413 @item -kernel-kqemu
1414 Enable KQEMU full virtualization (default is user mode only).
1415 ETEXI
1417 #ifdef CONFIG_KQEMU
1418 DEF("enable-kqemu", 0, QEMU_OPTION_enable_kqemu, \
1419 "-enable-kqemu enable KQEMU kernel module usage\n")
1420 #endif
1421 STEXI
1422 @item -enable-kqemu
1423 Enable KQEMU kernel module usage. KQEMU options are only available if
1424 KQEMU support is enabled when compiling.
1425 ETEXI
1427 #ifdef CONFIG_KVM
1428 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
1429 "-enable-kvm enable KVM full virtualization support\n")
1430 #endif
1431 STEXI
1432 @item -enable-kvm
1433 Enable KVM full virtualization support. This option is only available
1434 if KVM support is enabled when compiling.
1435 ETEXI
1437 #ifdef CONFIG_XEN
1438 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
1439 "-xen-domid id specify xen guest domain id\n")
1440 DEF("xen-create", 0, QEMU_OPTION_xen_create,
1441 "-xen-create create domain using xen hypercalls, bypassing xend\n"
1442 " warning: should not be used when xend is in use\n")
1443 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
1444 "-xen-attach attach to existing xen domain\n"
1445 " xend will use this when starting qemu\n")
1446 #endif
1448 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
1449 "-no-reboot exit instead of rebooting\n")
1450 STEXI
1451 @item -no-reboot
1452 Exit instead of rebooting.
1453 ETEXI
1455 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
1456 "-no-shutdown stop before shutdown\n")
1457 STEXI
1458 @item -no-shutdown
1459 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
1460 This allows for instance switching to monitor to commit changes to the
1461 disk image.
1462 ETEXI
1464 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
1465 "-loadvm [tag|id]\n" \
1466 " start right away with a saved state (loadvm in monitor)\n")
1467 STEXI
1468 @item -loadvm @var{file}
1469 Start right away with a saved state (@code{loadvm} in monitor)
1470 ETEXI
1472 #ifndef _WIN32
1473 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
1474 "-daemonize daemonize QEMU after initializing\n")
1475 #endif
1476 STEXI
1477 @item -daemonize
1478 Daemonize the QEMU process after initialization. QEMU will not detach from
1479 standard IO until it is ready to receive connections on any of its devices.
1480 This option is a useful way for external programs to launch QEMU without having
1481 to cope with initialization race conditions.
1482 ETEXI
1484 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
1485 "-option-rom rom load a file, rom, into the option ROM space\n")
1486 STEXI
1487 @item -option-rom @var{file}
1488 Load the contents of @var{file} as an option ROM.
1489 This option is useful to load things like EtherBoot.
1490 ETEXI
1492 DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
1493 "-clock force the use of the given methods for timer alarm.\n" \
1494 " To see what timers are available use -clock ?\n")
1495 STEXI
1496 @item -clock @var{method}
1497 Force the use of the given methods for timer alarm. To see what timers
1498 are available use -clock ?.
1499 ETEXI
1501 DEF("localtime", 0, QEMU_OPTION_localtime, \
1502 "-localtime set the real time clock to local time [default=utc]\n")
1503 STEXI
1504 @item -localtime
1505 Set the real time clock to local time (the default is to UTC
1506 time). This option is needed to have correct date in MS-DOS or
1507 Windows.
1508 ETEXI
1510 DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, \
1511 "-startdate select initial date of the clock\n")
1512 STEXI
1514 @item -startdate @var{date}
1515 Set the initial date of the real time clock. Valid formats for
1516 @var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
1517 @code{2006-06-17}. The default value is @code{now}.
1518 ETEXI
1520 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
1521 "-icount [N|auto]\n" \
1522 " enable virtual instruction counter with 2^N clock ticks per\n" \
1523 " instruction\n")
1524 STEXI
1525 @item -icount [N|auto]
1526 Enable virtual instruction counter. The virtual cpu will execute one
1527 instruction every 2^N ns of virtual time. If @code{auto} is specified
1528 then the virtual cpu speed will be automatically adjusted to keep virtual
1529 time within a few seconds of real time.
1531 Note that while this option can give deterministic behavior, it does not
1532 provide cycle accurate emulation. Modern CPUs contain superscalar out of
1533 order cores with complex cache hierarchies. The number of instructions
1534 executed often has little or no correlation with actual performance.
1535 ETEXI
1537 DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
1538 "-watchdog i6300esb|ib700\n" \
1539 " enable virtual hardware watchdog [default=none]\n")
1540 STEXI
1541 @item -watchdog @var{model}
1542 Create a virtual hardware watchdog device. Once enabled (by a guest
1543 action), the watchdog must be periodically polled by an agent inside
1544 the guest or else the guest will be restarted.
1546 The @var{model} is the model of hardware watchdog to emulate. Choices
1547 for model are: @code{ib700} (iBASE 700) which is a very simple ISA
1548 watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O
1549 controller hub) which is a much more featureful PCI-based dual-timer
1550 watchdog. Choose a model for which your guest has drivers.
1552 Use @code{-watchdog ?} to list available hardware models. Only one
1553 watchdog can be enabled for a guest.
1554 ETEXI
1556 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
1557 "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
1558 " action when watchdog fires [default=reset]\n")
1559 STEXI
1560 @item -watchdog-action @var{action}
1562 The @var{action} controls what QEMU will do when the watchdog timer
1563 expires.
1564 The default is
1565 @code{reset} (forcefully reset the guest).
1566 Other possible actions are:
1567 @code{shutdown} (attempt to gracefully shutdown the guest),
1568 @code{poweroff} (forcefully poweroff the guest),
1569 @code{pause} (pause the guest),
1570 @code{debug} (print a debug message and continue), or
1571 @code{none} (do nothing).
1573 Note that the @code{shutdown} action requires that the guest responds
1574 to ACPI signals, which it may not be able to do in the sort of
1575 situations where the watchdog would have expired, and thus
1576 @code{-watchdog-action shutdown} is not recommended for production use.
1578 Examples:
1580 @table @code
1581 @item -watchdog i6300esb -watchdog-action pause
1582 @item -watchdog ib700
1583 @end table
1584 ETEXI
1586 DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
1587 "-echr chr set terminal escape character instead of ctrl-a\n")
1588 STEXI
1590 @item -echr numeric_ascii_value
1591 Change the escape character used for switching to the monitor when using
1592 monitor and serial sharing. The default is @code{0x01} when using the
1593 @code{-nographic} option. @code{0x01} is equal to pressing
1594 @code{Control-a}. You can select a different character from the ascii
1595 control keys where 1 through 26 map to Control-a through Control-z. For
1596 instance you could use the either of the following to change the escape
1597 character to Control-t.
1598 @table @code
1599 @item -echr 0x14
1600 @item -echr 20
1601 @end table
1602 ETEXI
1604 DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
1605 "-virtioconsole c\n" \
1606 " set virtio console\n")
1607 STEXI
1608 @item -virtioconsole @var{c}
1609 Set virtio console.
1610 ETEXI
1612 DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
1613 "-show-cursor show cursor\n")
1614 STEXI
1615 ETEXI
1617 DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
1618 "-tb-size n set TB size\n")
1619 STEXI
1620 ETEXI
1622 DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
1623 "-incoming p prepare for incoming migration, listen on port p\n")
1624 STEXI
1625 ETEXI
1627 #ifndef _WIN32
1628 DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
1629 "-chroot dir Chroot to dir just before starting the VM.\n")
1630 #endif
1631 STEXI
1632 @item -chroot dir
1633 Immediately before starting guest execution, chroot to the specified
1634 directory. Especially useful in combination with -runas.
1635 ETEXI
1637 #ifndef _WIN32
1638 DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
1639 "-runas user Change to user id user just before starting the VM.\n")
1640 #endif
1641 STEXI
1642 @item -runas user
1643 Immediately before starting guest execution, drop root privileges, switching
1644 to the specified user.
1645 ETEXI
1647 STEXI
1648 @end table
1649 ETEXI
1651 #if defined(TARGET_SPARC) || defined(TARGET_PPC)
1652 DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
1653 "-prom-env variable=value\n"
1654 " set OpenBIOS nvram variables\n")
1655 #endif
1656 #if defined(TARGET_ARM) || defined(TARGET_M68K)
1657 DEF("semihosting", 0, QEMU_OPTION_semihosting,
1658 "-semihosting semihosting mode\n")
1659 #endif
1660 #if defined(TARGET_ARM)
1661 DEF("old-param", 0, QEMU_OPTION_old_param,
1662 "-old-param old param mode\n")
1663 #endif