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