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