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