qemu/qemu-doc.texi
<<
>>
Prefs
   1\input texinfo @c -*- texinfo -*-
   2@c %**start of header
   3@setfilename qemu-doc.info
   4
   5@documentlanguage en
   6@documentencoding UTF-8
   7
   8@settitle QEMU Emulator User Documentation
   9@exampleindent 0
  10@paragraphindent 0
  11@c %**end of header
  12
  13@ifinfo
  14@direntry
  15* QEMU: (qemu-doc).    The QEMU Emulator User Documentation.
  16@end direntry
  17@end ifinfo
  18
  19@iftex
  20@titlepage
  21@sp 7
  22@center @titlefont{QEMU Emulator}
  23@sp 1
  24@center @titlefont{User Documentation}
  25@sp 3
  26@end titlepage
  27@end iftex
  28
  29@ifnottex
  30@node Top
  31@top
  32
  33@menu
  34* Introduction::
  35* Installation::
  36* QEMU PC System emulator::
  37* QEMU System emulator for non PC targets::
  38* QEMU User space emulator::
  39* compilation:: Compilation from the sources
  40* License::
  41* Index::
  42@end menu
  43@end ifnottex
  44
  45@contents
  46
  47@node Introduction
  48@chapter Introduction
  49
  50@menu
  51* intro_features:: Features
  52@end menu
  53
  54@node intro_features
  55@section Features
  56
  57QEMU is a FAST! processor emulator using dynamic translation to
  58achieve good emulation speed.
  59
  60QEMU has two operating modes:
  61
  62@itemize
  63@cindex operating modes
  64
  65@item
  66@cindex system emulation
  67Full system emulation. In this mode, QEMU emulates a full system (for
  68example a PC), including one or several processors and various
  69peripherals. It can be used to launch different Operating Systems
  70without rebooting the PC or to debug system code.
  71
  72@item
  73@cindex user mode emulation
  74User mode emulation. In this mode, QEMU can launch
  75processes compiled for one CPU on another CPU. It can be used to
  76launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
  77to ease cross-compilation and cross-debugging.
  78
  79@end itemize
  80
  81QEMU can run without a host kernel driver and yet gives acceptable
  82performance.
  83
  84For system emulation, the following hardware targets are supported:
  85@itemize
  86@cindex emulated target systems
  87@cindex supported target systems
  88@item PC (x86 or x86_64 processor)
  89@item ISA PC (old style PC without PCI bus)
  90@item PREP (PowerPC processor)
  91@item G3 Beige PowerMac (PowerPC processor)
  92@item Mac99 PowerMac (PowerPC processor, in progress)
  93@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
  94@item Sun4u/Sun4v (64-bit Sparc processor, in progress)
  95@item Malta board (32-bit and 64-bit MIPS processors)
  96@item MIPS Magnum (64-bit MIPS processor)
  97@item ARM Integrator/CP (ARM)
  98@item ARM Versatile baseboard (ARM)
  99@item ARM RealView Emulation/Platform baseboard (ARM)
 100@item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
 101@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
 102@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
 103@item Freescale MCF5208EVB (ColdFire V2).
 104@item Arnewsh MCF5206 evaluation board (ColdFire V2).
 105@item Palm Tungsten|E PDA (OMAP310 processor)
 106@item N800 and N810 tablets (OMAP2420 processor)
 107@item MusicPal (MV88W8618 ARM processor)
 108@item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
 109@item Siemens SX1 smartphone (OMAP310 processor)
 110@item AXIS-Devboard88 (CRISv32 ETRAX-FS).
 111@item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).
 112@item Avnet LX60/LX110/LX200 boards (Xtensa)
 113@end itemize
 114
 115@cindex supported user mode targets
 116For user emulation, x86 (32 and 64 bit), PowerPC (32 and 64 bit),
 117ARM, MIPS (32 bit only), Sparc (32 and 64 bit),
 118Alpha, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
 119
 120@node Installation
 121@chapter Installation
 122
 123If you want to compile QEMU yourself, see @ref{compilation}.
 124
 125@menu
 126* install_linux::   Linux
 127* install_windows:: Windows
 128* install_mac::     Macintosh
 129@end menu
 130
 131@node install_linux
 132@section Linux
 133@cindex installation (Linux)
 134
 135If a precompiled package is available for your distribution - you just
 136have to install it. Otherwise, see @ref{compilation}.
 137
 138@node install_windows
 139@section Windows
 140@cindex installation (Windows)
 141
 142Download the experimental binary installer at
 143@url{http://www.free.oszoo.org/@/download.html}.
 144TODO (no longer available)
 145
 146@node install_mac
 147@section Mac OS X
 148
 149Download the experimental binary installer at
 150@url{http://www.free.oszoo.org/@/download.html}.
 151TODO (no longer available)
 152
 153@node QEMU PC System emulator
 154@chapter QEMU PC System emulator
 155@cindex system emulation (PC)
 156
 157@menu
 158* pcsys_introduction:: Introduction
 159* pcsys_quickstart::   Quick Start
 160* sec_invocation::     Invocation
 161* pcsys_keys::         Keys in the graphical frontends
 162* mux_keys::           Keys in the character backend multiplexer
 163* pcsys_monitor::      QEMU Monitor
 164* disk_images::        Disk Images
 165* pcsys_network::      Network emulation
 166* pcsys_other_devs::   Other Devices
 167* direct_linux_boot::  Direct Linux Boot
 168* pcsys_usb::          USB emulation
 169* vnc_security::       VNC security
 170* gdb_usage::          GDB usage
 171* pcsys_os_specific::  Target OS specific information
 172@end menu
 173
 174@node pcsys_introduction
 175@section Introduction
 176
 177@c man begin DESCRIPTION
 178
 179The QEMU PC System emulator simulates the
 180following peripherals:
 181
 182@itemize @minus
 183@item
 184i440FX host PCI bridge and PIIX3 PCI to ISA bridge
 185@item
 186Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
 187extensions (hardware level, including all non standard modes).
 188@item
 189PS/2 mouse and keyboard
 190@item
 1912 PCI IDE interfaces with hard disk and CD-ROM support
 192@item
 193Floppy disk
 194@item
 195PCI and ISA network adapters
 196@item
 197Serial ports
 198@item
 199IPMI BMC, either and internal or external one
 200@item
 201Creative SoundBlaster 16 sound card
 202@item
 203ENSONIQ AudioPCI ES1370 sound card
 204@item
 205Intel 82801AA AC97 Audio compatible sound card
 206@item
 207Intel HD Audio Controller and HDA codec
 208@item
 209Adlib (OPL2) - Yamaha YM3812 compatible chip
 210@item
 211Gravis Ultrasound GF1 sound card
 212@item
 213CS4231A compatible sound card
 214@item
 215PCI UHCI USB controller and a virtual USB hub.
 216@end itemize
 217
 218SMP is supported with up to 255 CPUs.
 219
 220QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
 221VGA BIOS.
 222
 223QEMU uses YM3812 emulation by Tatsuyuki Satoh.
 224
 225QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
 226by Tibor "TS" Schütz.
 227
 228Note that, by default, GUS shares IRQ(7) with parallel ports and so
 229QEMU must be told to not have parallel ports to have working GUS.
 230
 231@example
 232qemu-system-i386 dos.img -soundhw gus -parallel none
 233@end example
 234
 235Alternatively:
 236@example
 237qemu-system-i386 dos.img -device gus,irq=5
 238@end example
 239
 240Or some other unclaimed IRQ.
 241
 242CS4231A is the chip used in Windows Sound System and GUSMAX products
 243
 244@c man end
 245
 246@node pcsys_quickstart
 247@section Quick Start
 248@cindex quick start
 249
 250Download and uncompress the linux image (@file{linux.img}) and type:
 251
 252@example
 253qemu-system-i386 linux.img
 254@end example
 255
 256Linux should boot and give you a prompt.
 257
 258@node sec_invocation
 259@section Invocation
 260
 261@example
 262@c man begin SYNOPSIS
 263@command{qemu-system-i386} [@var{options}] [@var{disk_image}]
 264@c man end
 265@end example
 266
 267@c man begin OPTIONS
 268@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
 269targets do not need a disk image.
 270
 271@include qemu-options.texi
 272
 273@c man end
 274
 275@node pcsys_keys
 276@section Keys in the graphical frontends
 277
 278@c man begin OPTIONS
 279
 280During the graphical emulation, you can use special key combinations to change
 281modes. The default key mappings are shown below, but if you use @code{-alt-grab}
 282then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
 283@code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
 284
 285@table @key
 286@item Ctrl-Alt-f
 287@kindex Ctrl-Alt-f
 288Toggle full screen
 289
 290@item Ctrl-Alt-+
 291@kindex Ctrl-Alt-+
 292Enlarge the screen
 293
 294@item Ctrl-Alt--
 295@kindex Ctrl-Alt--
 296Shrink the screen
 297
 298@item Ctrl-Alt-u
 299@kindex Ctrl-Alt-u
 300Restore the screen's un-scaled dimensions
 301
 302@item Ctrl-Alt-n
 303@kindex Ctrl-Alt-n
 304Switch to virtual console 'n'. Standard console mappings are:
 305@table @emph
 306@item 1
 307Target system display
 308@item 2
 309Monitor
 310@item 3
 311Serial port
 312@end table
 313
 314@item Ctrl-Alt
 315@kindex Ctrl-Alt
 316Toggle mouse and keyboard grab.
 317@end table
 318
 319@kindex Ctrl-Up
 320@kindex Ctrl-Down
 321@kindex Ctrl-PageUp
 322@kindex Ctrl-PageDown
 323In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
 324@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
 325
 326@c man end
 327
 328@node mux_keys
 329@section Keys in the character backend multiplexer
 330
 331@c man begin OPTIONS
 332
 333During emulation, if you are using a character backend multiplexer
 334(which is the default if you are using @option{-nographic}) then
 335several commands are available via an escape sequence. These
 336key sequences all start with an escape character, which is @key{Ctrl-a}
 337by default, but can be changed with @option{-echr}. The list below assumes
 338you're using the default.
 339
 340@table @key
 341@item Ctrl-a h
 342@kindex Ctrl-a h
 343Print this help
 344@item Ctrl-a x
 345@kindex Ctrl-a x
 346Exit emulator
 347@item Ctrl-a s
 348@kindex Ctrl-a s
 349Save disk data back to file (if -snapshot)
 350@item Ctrl-a t
 351@kindex Ctrl-a t
 352Toggle console timestamps
 353@item Ctrl-a b
 354@kindex Ctrl-a b
 355Send break (magic sysrq in Linux)
 356@item Ctrl-a c
 357@kindex Ctrl-a c
 358Rotate between the frontends connected to the multiplexer (usually
 359this switches between the monitor and the console)
 360@item Ctrl-a Ctrl-a
 361@kindex Ctrl-a Ctrl-a
 362Send the escape character to the frontend
 363@end table
 364@c man end
 365
 366@ignore
 367
 368@c man begin SEEALSO
 369The HTML documentation of QEMU for more precise information and Linux
 370user mode emulator invocation.
 371@c man end
 372
 373@c man begin AUTHOR
 374Fabrice Bellard
 375@c man end
 376
 377@end ignore
 378
 379@node pcsys_monitor
 380@section QEMU Monitor
 381@cindex QEMU monitor
 382
 383The QEMU monitor is used to give complex commands to the QEMU
 384emulator. You can use it to:
 385
 386@itemize @minus
 387
 388@item
 389Remove or insert removable media images
 390(such as CD-ROM or floppies).
 391
 392@item
 393Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
 394from a disk file.
 395
 396@item Inspect the VM state without an external debugger.
 397
 398@end itemize
 399
 400@subsection Commands
 401
 402The following commands are available:
 403
 404@include qemu-monitor.texi
 405
 406@include qemu-monitor-info.texi
 407
 408@subsection Integer expressions
 409
 410The monitor understands integers expressions for every integer
 411argument. You can use register names to get the value of specifics
 412CPU registers by prefixing them with @emph{$}.
 413
 414@node disk_images
 415@section Disk Images
 416
 417Since version 0.6.1, QEMU supports many disk image formats, including
 418growable disk images (their size increase as non empty sectors are
 419written), compressed and encrypted disk images. Version 0.8.3 added
 420the new qcow2 disk image format which is essential to support VM
 421snapshots.
 422
 423@menu
 424* disk_images_quickstart::    Quick start for disk image creation
 425* disk_images_snapshot_mode:: Snapshot mode
 426* vm_snapshots::              VM snapshots
 427* qemu_img_invocation::       qemu-img Invocation
 428* qemu_nbd_invocation::       qemu-nbd Invocation
 429* qemu_ga_invocation::        qemu-ga Invocation
 430* disk_images_formats::       Disk image file formats
 431* host_drives::               Using host drives
 432* disk_images_fat_images::    Virtual FAT disk images
 433* disk_images_nbd::           NBD access
 434* disk_images_sheepdog::      Sheepdog disk images
 435* disk_images_iscsi::         iSCSI LUNs
 436* disk_images_gluster::       GlusterFS disk images
 437* disk_images_ssh::           Secure Shell (ssh) disk images
 438@end menu
 439
 440@node disk_images_quickstart
 441@subsection Quick start for disk image creation
 442
 443You can create a disk image with the command:
 444@example
 445qemu-img create myimage.img mysize
 446@end example
 447where @var{myimage.img} is the disk image filename and @var{mysize} is its
 448size in kilobytes. You can add an @code{M} suffix to give the size in
 449megabytes and a @code{G} suffix for gigabytes.
 450
 451See @ref{qemu_img_invocation} for more information.
 452
 453@node disk_images_snapshot_mode
 454@subsection Snapshot mode
 455
 456If you use the option @option{-snapshot}, all disk images are
 457considered as read only. When sectors in written, they are written in
 458a temporary file created in @file{/tmp}. You can however force the
 459write back to the raw disk images by using the @code{commit} monitor
 460command (or @key{C-a s} in the serial console).
 461
 462@node vm_snapshots
 463@subsection VM snapshots
 464
 465VM snapshots are snapshots of the complete virtual machine including
 466CPU state, RAM, device state and the content of all the writable
 467disks. In order to use VM snapshots, you must have at least one non
 468removable and writable block device using the @code{qcow2} disk image
 469format. Normally this device is the first virtual hard drive.
 470
 471Use the monitor command @code{savevm} to create a new VM snapshot or
 472replace an existing one. A human readable name can be assigned to each
 473snapshot in addition to its numerical ID.
 474
 475Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
 476a VM snapshot. @code{info snapshots} lists the available snapshots
 477with their associated information:
 478
 479@example
 480(qemu) info snapshots
 481Snapshot devices: hda
 482Snapshot list (from hda):
 483ID        TAG                 VM SIZE                DATE       VM CLOCK
 4841         start                   41M 2006-08-06 12:38:02   00:00:14.954
 4852                                 40M 2006-08-06 12:43:29   00:00:18.633
 4863         msys                    40M 2006-08-06 12:44:04   00:00:23.514
 487@end example
 488
 489A VM snapshot is made of a VM state info (its size is shown in
 490@code{info snapshots}) and a snapshot of every writable disk image.
 491The VM state info is stored in the first @code{qcow2} non removable
 492and writable block device. The disk image snapshots are stored in
 493every disk image. The size of a snapshot in a disk image is difficult
 494to evaluate and is not shown by @code{info snapshots} because the
 495associated disk sectors are shared among all the snapshots to save
 496disk space (otherwise each snapshot would need a full copy of all the
 497disk images).
 498
 499When using the (unrelated) @code{-snapshot} option
 500(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
 501but they are deleted as soon as you exit QEMU.
 502
 503VM snapshots currently have the following known limitations:
 504@itemize
 505@item
 506They cannot cope with removable devices if they are removed or
 507inserted after a snapshot is done.
 508@item
 509A few device drivers still have incomplete snapshot support so their
 510state is not saved or restored properly (in particular USB).
 511@end itemize
 512
 513@node qemu_img_invocation
 514@subsection @code{qemu-img} Invocation
 515
 516@include qemu-img.texi
 517
 518@node qemu_nbd_invocation
 519@subsection @code{qemu-nbd} Invocation
 520
 521@include qemu-nbd.texi
 522
 523@node qemu_ga_invocation
 524@subsection @code{qemu-ga} Invocation
 525
 526@include qemu-ga.texi
 527
 528@node disk_images_formats
 529@subsection Disk image file formats
 530
 531QEMU supports many image file formats that can be used with VMs as well as with
 532any of the tools (like @code{qemu-img}). This includes the preferred formats
 533raw and qcow2 as well as formats that are supported for compatibility with
 534older QEMU versions or other hypervisors.
 535
 536Depending on the image format, different options can be passed to
 537@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.
 538This section describes each format and the options that are supported for it.
 539
 540@table @option
 541@item raw
 542
 543Raw disk image format. This format has the advantage of
 544being simple and easily exportable to all other emulators. If your
 545file system supports @emph{holes} (for example in ext2 or ext3 on
 546Linux or NTFS on Windows), then only the written sectors will reserve
 547space. Use @code{qemu-img info} to know the real size used by the
 548image or @code{ls -ls} on Unix/Linux.
 549
 550Supported options:
 551@table @code
 552@item preallocation
 553Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
 554@code{falloc} mode preallocates space for image by calling posix_fallocate().
 555@code{full} mode preallocates space for image by writing zeros to underlying
 556storage.
 557@end table
 558
 559@item qcow2
 560QEMU image format, the most versatile format. Use it to have smaller
 561images (useful if your filesystem does not supports holes, for example
 562on Windows), zlib based compression and support of multiple VM
 563snapshots.
 564
 565Supported options:
 566@table @code
 567@item compat
 568Determines the qcow2 version to use. @code{compat=0.10} uses the
 569traditional image format that can be read by any QEMU since 0.10.
 570@code{compat=1.1} enables image format extensions that only QEMU 1.1 and
 571newer understand (this is the default). Amongst others, this includes
 572zero clusters, which allow efficient copy-on-read for sparse images.
 573
 574@item backing_file
 575File name of a base image (see @option{create} subcommand)
 576@item backing_fmt
 577Image format of the base image
 578@item encryption
 579If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC.
 580
 581The use of encryption in qcow and qcow2 images is considered to be flawed by
 582modern cryptography standards, suffering from a number of design problems:
 583
 584@itemize @minus
 585@item The AES-CBC cipher is used with predictable initialization vectors based
 586on the sector number. This makes it vulnerable to chosen plaintext attacks
 587which can reveal the existence of encrypted data.
 588@item The user passphrase is directly used as the encryption key. A poorly
 589chosen or short passphrase will compromise the security of the encryption.
 590@item In the event of the passphrase being compromised there is no way to
 591change the passphrase to protect data in any qcow images. The files must
 592be cloned, using a different encryption passphrase in the new file. The
 593original file must then be securely erased using a program like shred,
 594though even this is ineffective with many modern storage technologies.
 595@end itemize
 596
 597Use of qcow / qcow2 encryption with QEMU is deprecated, and support for
 598it will go away in a future release.  Users are recommended to use an
 599alternative encryption technology such as the Linux dm-crypt / LUKS
 600system.
 601
 602@item cluster_size
 603Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
 604sizes can improve the image file size whereas larger cluster sizes generally
 605provide better performance.
 606
 607@item preallocation
 608Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},
 609@code{full}). An image with preallocated metadata is initially larger but can
 610improve performance when the image needs to grow. @code{falloc} and @code{full}
 611preallocations are like the same options of @code{raw} format, but sets up
 612metadata also.
 613
 614@item lazy_refcounts
 615If this option is set to @code{on}, reference count updates are postponed with
 616the goal of avoiding metadata I/O and improving performance. This is
 617particularly interesting with @option{cache=writethrough} which doesn't batch
 618metadata updates. The tradeoff is that after a host crash, the reference count
 619tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
 620check -r all} is required, which may take some time.
 621
 622This option can only be enabled if @code{compat=1.1} is specified.
 623
 624@item nocow
 625If this option is set to @code{on}, it will turn off COW of the file. It's only
 626valid on btrfs, no effect on other file systems.
 627
 628Btrfs has low performance when hosting a VM image file, even more when the guest
 629on the VM also using btrfs as file system. Turning off COW is a way to mitigate
 630this bad performance. Generally there are two ways to turn off COW on btrfs:
 631a) Disable it by mounting with nodatacow, then all newly created files will be
 632NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option
 633does.
 634
 635Note: this option is only valid to new or empty files. If there is an existing
 636file which is COW and has data blocks already, it couldn't be changed to NOCOW
 637by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if
 638the NOCOW flag is set or not (Capital 'C' is NOCOW flag).
 639
 640@end table
 641
 642@item qed
 643Old QEMU image format with support for backing files and compact image files
 644(when your filesystem or transport medium does not support holes).
 645
 646When converting QED images to qcow2, you might want to consider using the
 647@code{lazy_refcounts=on} option to get a more QED-like behaviour.
 648
 649Supported options:
 650@table @code
 651@item backing_file
 652File name of a base image (see @option{create} subcommand).
 653@item backing_fmt
 654Image file format of backing file (optional).  Useful if the format cannot be
 655autodetected because it has no header, like some vhd/vpc files.
 656@item cluster_size
 657Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
 658cluster sizes can improve the image file size whereas larger cluster sizes
 659generally provide better performance.
 660@item table_size
 661Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
 662and 16).  There is normally no need to change this value but this option can be
 663used for performance benchmarking.
 664@end table
 665
 666@item qcow
 667Old QEMU image format with support for backing files, compact image files,
 668encryption and compression.
 669
 670Supported options:
 671@table @code
 672@item backing_file
 673File name of a base image (see @option{create} subcommand)
 674@item encryption
 675If this option is set to @code{on}, the image is encrypted.
 676@end table
 677
 678@item vdi
 679VirtualBox 1.1 compatible image format.
 680Supported options:
 681@table @code
 682@item static
 683If this option is set to @code{on}, the image is created with metadata
 684preallocation.
 685@end table
 686
 687@item vmdk
 688VMware 3 and 4 compatible image format.
 689
 690Supported options:
 691@table @code
 692@item backing_file
 693File name of a base image (see @option{create} subcommand).
 694@item compat6
 695Create a VMDK version 6 image (instead of version 4)
 696@item hwversion
 697Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
 698if hwversion is specified.
 699@item subformat
 700Specifies which VMDK subformat to use. Valid options are
 701@code{monolithicSparse} (default),
 702@code{monolithicFlat},
 703@code{twoGbMaxExtentSparse},
 704@code{twoGbMaxExtentFlat} and
 705@code{streamOptimized}.
 706@end table
 707
 708@item vpc
 709VirtualPC compatible image format (VHD).
 710Supported options:
 711@table @code
 712@item subformat
 713Specifies which VHD subformat to use. Valid options are
 714@code{dynamic} (default) and @code{fixed}.
 715@end table
 716
 717@item VHDX
 718Hyper-V compatible image format (VHDX).
 719Supported options:
 720@table @code
 721@item subformat
 722Specifies which VHDX subformat to use. Valid options are
 723@code{dynamic} (default) and @code{fixed}.
 724@item block_state_zero
 725Force use of payload blocks of type 'ZERO'.  Can be set to @code{on} (default)
 726or @code{off}.  When set to @code{off}, new blocks will be created as
 727@code{PAYLOAD_BLOCK_NOT_PRESENT}, which means parsers are free to return
 728arbitrary data for those blocks.  Do not set to @code{off} when using
 729@code{qemu-img convert} with @code{subformat=dynamic}.
 730@item block_size
 731Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on image size.
 732@item log_size
 733Log size; min 1 MB.
 734@end table
 735@end table
 736
 737@subsubsection Read-only formats
 738More disk image file formats are supported in a read-only mode.
 739@table @option
 740@item bochs
 741Bochs images of @code{growing} type.
 742@item cloop
 743Linux Compressed Loop image, useful only to reuse directly compressed
 744CD-ROM images present for example in the Knoppix CD-ROMs.
 745@item dmg
 746Apple disk image.
 747@item parallels
 748Parallels disk image format.
 749@end table
 750
 751
 752@node host_drives
 753@subsection Using host drives
 754
 755In addition to disk image files, QEMU can directly access host
 756devices. We describe here the usage for QEMU version >= 0.8.3.
 757
 758@subsubsection Linux
 759
 760On Linux, you can directly use the host device filename instead of a
 761disk image filename provided you have enough privileges to access
 762it. For example, use @file{/dev/cdrom} to access to the CDROM.
 763
 764@table @code
 765@item CD
 766You can specify a CDROM device even if no CDROM is loaded. QEMU has
 767specific code to detect CDROM insertion or removal. CDROM ejection by
 768the guest OS is supported. Currently only data CDs are supported.
 769@item Floppy
 770You can specify a floppy device even if no floppy is loaded. Floppy
 771removal is currently not detected accurately (if you change floppy
 772without doing floppy access while the floppy is not loaded, the guest
 773OS will think that the same floppy is loaded).
 774Use of the host's floppy device is deprecated, and support for it will
 775be removed in a future release.
 776@item Hard disks
 777Hard disks can be used. Normally you must specify the whole disk
 778(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
 779see it as a partitioned disk. WARNING: unless you know what you do, it
 780is better to only make READ-ONLY accesses to the hard disk otherwise
 781you may corrupt your host data (use the @option{-snapshot} command
 782line option or modify the device permissions accordingly).
 783@end table
 784
 785@subsubsection Windows
 786
 787@table @code
 788@item CD
 789The preferred syntax is the drive letter (e.g. @file{d:}). The
 790alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
 791supported as an alias to the first CDROM drive.
 792
 793Currently there is no specific code to handle removable media, so it
 794is better to use the @code{change} or @code{eject} monitor commands to
 795change or eject media.
 796@item Hard disks
 797Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
 798where @var{N} is the drive number (0 is the first hard disk).
 799
 800WARNING: unless you know what you do, it is better to only make
 801READ-ONLY accesses to the hard disk otherwise you may corrupt your
 802host data (use the @option{-snapshot} command line so that the
 803modifications are written in a temporary file).
 804@end table
 805
 806
 807@subsubsection Mac OS X
 808
 809@file{/dev/cdrom} is an alias to the first CDROM.
 810
 811Currently there is no specific code to handle removable media, so it
 812is better to use the @code{change} or @code{eject} monitor commands to
 813change or eject media.
 814
 815@node disk_images_fat_images
 816@subsection Virtual FAT disk images
 817
 818QEMU can automatically create a virtual FAT disk image from a
 819directory tree. In order to use it, just type:
 820
 821@example
 822qemu-system-i386 linux.img -hdb fat:/my_directory
 823@end example
 824
 825Then you access access to all the files in the @file{/my_directory}
 826directory without having to copy them in a disk image or to export
 827them via SAMBA or NFS. The default access is @emph{read-only}.
 828
 829Floppies can be emulated with the @code{:floppy:} option:
 830
 831@example
 832qemu-system-i386 linux.img -fda fat:floppy:/my_directory
 833@end example
 834
 835A read/write support is available for testing (beta stage) with the
 836@code{:rw:} option:
 837
 838@example
 839qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
 840@end example
 841
 842What you should @emph{never} do:
 843@itemize
 844@item use non-ASCII filenames ;
 845@item use "-snapshot" together with ":rw:" ;
 846@item expect it to work when loadvm'ing ;
 847@item write to the FAT directory on the host system while accessing it with the guest system.
 848@end itemize
 849
 850@node disk_images_nbd
 851@subsection NBD access
 852
 853QEMU can access directly to block device exported using the Network Block Device
 854protocol.
 855
 856@example
 857qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
 858@end example
 859
 860If the NBD server is located on the same host, you can use an unix socket instead
 861of an inet socket:
 862
 863@example
 864qemu-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket
 865@end example
 866
 867In this case, the block device must be exported using qemu-nbd:
 868
 869@example
 870qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
 871@end example
 872
 873The use of qemu-nbd allows sharing of a disk between several guests:
 874@example
 875qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
 876@end example
 877
 878@noindent
 879and then you can use it with two guests:
 880@example
 881qemu-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
 882qemu-system-i386 linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
 883@end example
 884
 885If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
 886own embedded NBD server), you must specify an export name in the URI:
 887@example
 888qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst
 889qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
 890@end example
 891
 892The URI syntax for NBD is supported since QEMU 1.3.  An alternative syntax is
 893also available.  Here are some example of the older syntax:
 894@example
 895qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
 896qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket
 897qemu-system-i386 -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
 898@end example
 899
 900@node disk_images_sheepdog
 901@subsection Sheepdog disk images
 902
 903Sheepdog is a distributed storage system for QEMU.  It provides highly
 904available block level storage volumes that can be attached to
 905QEMU-based virtual machines.
 906
 907You can create a Sheepdog disk image with the command:
 908@example
 909qemu-img create sheepdog:///@var{image} @var{size}
 910@end example
 911where @var{image} is the Sheepdog image name and @var{size} is its
 912size.
 913
 914To import the existing @var{filename} to Sheepdog, you can use a
 915convert command.
 916@example
 917qemu-img convert @var{filename} sheepdog:///@var{image}
 918@end example
 919
 920You can boot from the Sheepdog disk image with the command:
 921@example
 922qemu-system-i386 sheepdog:///@var{image}
 923@end example
 924
 925You can also create a snapshot of the Sheepdog image like qcow2.
 926@example
 927qemu-img snapshot -c @var{tag} sheepdog:///@var{image}
 928@end example
 929where @var{tag} is a tag name of the newly created snapshot.
 930
 931To boot from the Sheepdog snapshot, specify the tag name of the
 932snapshot.
 933@example
 934qemu-system-i386 sheepdog:///@var{image}#@var{tag}
 935@end example
 936
 937You can create a cloned image from the existing snapshot.
 938@example
 939qemu-img create -b sheepdog:///@var{base}#@var{tag} sheepdog:///@var{image}
 940@end example
 941where @var{base} is a image name of the source snapshot and @var{tag}
 942is its tag name.
 943
 944You can use an unix socket instead of an inet socket:
 945
 946@example
 947qemu-system-i386 sheepdog+unix:///@var{image}?socket=@var{path}
 948@end example
 949
 950If the Sheepdog daemon doesn't run on the local host, you need to
 951specify one of the Sheepdog servers to connect to.
 952@example
 953qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size}
 954qemu-system-i386 sheepdog://@var{hostname}:@var{port}/@var{image}
 955@end example
 956
 957@node disk_images_iscsi
 958@subsection iSCSI LUNs
 959
 960iSCSI is a popular protocol used to access SCSI devices across a computer
 961network.
 962
 963There are two different ways iSCSI devices can be used by QEMU.
 964
 965The first method is to mount the iSCSI LUN on the host, and make it appear as
 966any other ordinary SCSI device on the host and then to access this device as a
 967/dev/sd device from QEMU. How to do this differs between host OSes.
 968
 969The second method involves using the iSCSI initiator that is built into
 970QEMU. This provides a mechanism that works the same way regardless of which
 971host OS you are running QEMU on. This section will describe this second method
 972of using iSCSI together with QEMU.
 973
 974In QEMU, iSCSI devices are described using special iSCSI URLs
 975
 976@example
 977URL syntax:
 978iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
 979@end example
 980
 981Username and password are optional and only used if your target is set up
 982using CHAP authentication for access control.
 983Alternatively the username and password can also be set via environment
 984variables to have these not show up in the process list
 985
 986@example
 987export LIBISCSI_CHAP_USERNAME=<username>
 988export LIBISCSI_CHAP_PASSWORD=<password>
 989iscsi://<host>/<target-iqn-name>/<lun>
 990@end example
 991
 992Various session related parameters can be set via special options, either
 993in a configuration file provided via '-readconfig' or directly on the
 994command line.
 995
 996If the initiator-name is not specified qemu will use a default name
 997of 'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
 998virtual machine.
 999
1000
1001@example
1002Setting a specific initiator name to use when logging in to the target
1003-iscsi initiator-name=iqn.qemu.test:my-initiator
1004@end example
1005
1006@example
1007Controlling which type of header digest to negotiate with the target
1008-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
1009@end example
1010
1011These can also be set via a configuration file
1012@example
1013[iscsi]
1014  user = "CHAP username"
1015  password = "CHAP password"
1016  initiator-name = "iqn.qemu.test:my-initiator"
1017  # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
1018  header-digest = "CRC32C"
1019@end example
1020
1021
1022Setting the target name allows different options for different targets
1023@example
1024[iscsi "iqn.target.name"]
1025  user = "CHAP username"
1026  password = "CHAP password"
1027  initiator-name = "iqn.qemu.test:my-initiator"
1028  # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
1029  header-digest = "CRC32C"
1030@end example
1031
1032
1033Howto use a configuration file to set iSCSI configuration options:
1034@example
1035cat >iscsi.conf <<EOF
1036[iscsi]
1037  user = "me"
1038  password = "my password"
1039  initiator-name = "iqn.qemu.test:my-initiator"
1040  header-digest = "CRC32C"
1041EOF
1042
1043qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
1044    -readconfig iscsi.conf
1045@end example
1046
1047
1048Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
1049@example
1050This example shows how to set up an iSCSI target with one CDROM and one DISK
1051using the Linux STGT software target. This target is available on Red Hat based
1052systems as the package 'scsi-target-utils'.
1053
1054tgtd --iscsi portal=127.0.0.1:3260
1055tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
1056tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
1057    -b /IMAGES/disk.img --device-type=disk
1058tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
1059    -b /IMAGES/cd.iso --device-type=cd
1060tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
1061
1062qemu-system-i386 -iscsi initiator-name=iqn.qemu.test:my-initiator \
1063    -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
1064    -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
1065@end example
1066
1067@node disk_images_gluster
1068@subsection GlusterFS disk images
1069
1070GlusterFS is an user space distributed file system.
1071
1072You can boot from the GlusterFS disk image with the command:
1073@example
1074qemu-system-x86_64 -drive file=gluster[+@var{transport}]://[@var{server}[:@var{port}]]/@var{volname}/@var{image}[?socket=...]
1075@end example
1076
1077@var{gluster} is the protocol.
1078
1079@var{transport} specifies the transport type used to connect to gluster
1080management daemon (glusterd). Valid transport types are
1081tcp, unix and rdma. If a transport type isn't specified, then tcp
1082type is assumed.
1083
1084@var{server} specifies the server where the volume file specification for
1085the given volume resides. This can be either hostname, ipv4 address
1086or ipv6 address. ipv6 address needs to be within square brackets [ ].
1087If transport type is unix, then @var{server} field should not be specified.
1088Instead @var{socket} field needs to be populated with the path to unix domain
1089socket.
1090
1091@var{port} is the port number on which glusterd is listening. This is optional
1092and if not specified, QEMU will send 0 which will make gluster to use the
1093default port. If the transport type is unix, then @var{port} should not be
1094specified.
1095
1096@var{volname} is the name of the gluster volume which contains the disk image.
1097
1098@var{image} is the path to the actual disk image that resides on gluster volume.
1099
1100You can create a GlusterFS disk image with the command:
1101@example
1102qemu-img create gluster://@var{server}/@var{volname}/@var{image} @var{size}
1103@end example
1104
1105Examples
1106@example
1107qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img
1108qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4/testvol/a.img
1109qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
1110qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
1111qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
1112qemu-system-x86_64 -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
1113qemu-system-x86_64 -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
1114qemu-system-x86_64 -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
1115@end example
1116
1117@node disk_images_ssh
1118@subsection Secure Shell (ssh) disk images
1119
1120You can access disk images located on a remote ssh server
1121by using the ssh protocol:
1122
1123@example
1124qemu-system-x86_64 -drive file=ssh://[@var{user}@@]@var{server}[:@var{port}]/@var{path}[?host_key_check=@var{host_key_check}]
1125@end example
1126
1127Alternative syntax using properties:
1128
1129@example
1130qemu-system-x86_64 -drive file.driver=ssh[,file.user=@var{user}],file.host=@var{server}[,file.port=@var{port}],file.path=@var{path}[,file.host_key_check=@var{host_key_check}]
1131@end example
1132
1133@var{ssh} is the protocol.
1134
1135@var{user} is the remote user.  If not specified, then the local
1136username is tried.
1137
1138@var{server} specifies the remote ssh server.  Any ssh server can be
1139used, but it must implement the sftp-server protocol.  Most Unix/Linux
1140systems should work without requiring any extra configuration.
1141
1142@var{port} is the port number on which sshd is listening.  By default
1143the standard ssh port (22) is used.
1144
1145@var{path} is the path to the disk image.
1146
1147The optional @var{host_key_check} parameter controls how the remote
1148host's key is checked.  The default is @code{yes} which means to use
1149the local @file{.ssh/known_hosts} file.  Setting this to @code{no}
1150turns off known-hosts checking.  Or you can check that the host key
1151matches a specific fingerprint:
1152@code{host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8}
1153(@code{sha1:} can also be used as a prefix, but note that OpenSSH
1154tools only use MD5 to print fingerprints).
1155
1156Currently authentication must be done using ssh-agent.  Other
1157authentication methods may be supported in future.
1158
1159Note: Many ssh servers do not support an @code{fsync}-style operation.
1160The ssh driver cannot guarantee that disk flush requests are
1161obeyed, and this causes a risk of disk corruption if the remote
1162server or network goes down during writes.  The driver will
1163print a warning when @code{fsync} is not supported:
1164
1165warning: ssh server @code{ssh.example.com:22} does not support fsync
1166
1167With sufficiently new versions of libssh2 and OpenSSH, @code{fsync} is
1168supported.
1169
1170@node pcsys_network
1171@section Network emulation
1172
1173QEMU can simulate several network cards (PCI or ISA cards on the PC
1174target) and can connect them to an arbitrary number of Virtual Local
1175Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1176VLAN. VLAN can be connected between separate instances of QEMU to
1177simulate large networks. For simpler usage, a non privileged user mode
1178network stack can replace the TAP device to have a basic network
1179connection.
1180
1181@subsection VLANs
1182
1183QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1184connection between several network devices. These devices can be for
1185example QEMU virtual Ethernet cards or virtual Host ethernet devices
1186(TAP devices).
1187
1188@subsection Using TAP network interfaces
1189
1190This is the standard way to connect QEMU to a real network. QEMU adds
1191a virtual network device on your host (called @code{tapN}), and you
1192can then configure it as if it was a real ethernet card.
1193
1194@subsubsection Linux host
1195
1196As an example, you can download the @file{linux-test-xxx.tar.gz}
1197archive and copy the script @file{qemu-ifup} in @file{/etc} and
1198configure properly @code{sudo} so that the command @code{ifconfig}
1199contained in @file{qemu-ifup} can be executed as root. You must verify
1200that your host kernel supports the TAP network interfaces: the
1201device @file{/dev/net/tun} must be present.
1202
1203See @ref{sec_invocation} to have examples of command lines using the
1204TAP network interfaces.
1205
1206@subsubsection Windows host
1207
1208There is a virtual ethernet driver for Windows 2000/XP systems, called
1209TAP-Win32. But it is not included in standard QEMU for Windows,
1210so you will need to get it separately. It is part of OpenVPN package,
1211so download OpenVPN from : @url{http://openvpn.net/}.
1212
1213@subsection Using the user mode network stack
1214
1215By using the option @option{-net user} (default configuration if no
1216@option{-net} option is specified), QEMU uses a completely user mode
1217network stack (you don't need root privilege to use the virtual
1218network). The virtual network configuration is the following:
1219
1220@example
1221
1222         QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
1223                           |          (10.0.2.2)
1224                           |
1225                           ---->  DNS server (10.0.2.3)
1226                           |
1227                           ---->  SMB server (10.0.2.4)
1228@end example
1229
1230The QEMU VM behaves as if it was behind a firewall which blocks all
1231incoming connections. You can use a DHCP client to automatically
1232configure the network in the QEMU VM. The DHCP server assign addresses
1233to the hosts starting from 10.0.2.15.
1234
1235In order to check that the user mode network is working, you can ping
1236the address 10.0.2.2 and verify that you got an address in the range
123710.0.2.x from the QEMU virtual DHCP server.
1238
1239Note that ICMP traffic in general does not work with user mode networking.
1240@code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
1241however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
1242ping sockets to allow @code{ping} to the Internet. The host admin has to set
1243the ping_group_range in order to grant access to those sockets. To allow ping
1244for GID 100 (usually users group):
1245
1246@example
1247echo 100 100 > /proc/sys/net/ipv4/ping_group_range
1248@end example
1249
1250When using the built-in TFTP server, the router is also the TFTP
1251server.
1252
1253When using the @option{'-netdev user,hostfwd=...'} option, TCP or UDP
1254connections can be redirected from the host to the guest. It allows for
1255example to redirect X11, telnet or SSH connections.
1256
1257@subsection Connecting VLANs between QEMU instances
1258
1259Using the @option{-net socket} option, it is possible to make VLANs
1260that span several QEMU instances. See @ref{sec_invocation} to have a
1261basic example.
1262
1263@node pcsys_other_devs
1264@section Other Devices
1265
1266@subsection Inter-VM Shared Memory device
1267
1268On Linux hosts, a shared memory device is available.  The basic syntax
1269is:
1270
1271@example
1272qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem}
1273@end example
1274
1275where @var{hostmem} names a host memory backend.  For a POSIX shared
1276memory backend, use something like
1277
1278@example
1279-object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
1280@end example
1281
1282If desired, interrupts can be sent between guest VMs accessing the same shared
1283memory region.  Interrupt support requires using a shared memory server and
1284using a chardev socket to connect to it.  The code for the shared memory server
1285is qemu.git/contrib/ivshmem-server.  An example syntax when using the shared
1286memory server is:
1287
1288@example
1289# First start the ivshmem server once and for all
1290ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}
1291
1292# Then start your qemu instances with matching arguments
1293qemu-system-x86_64 -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
1294                 -chardev socket,path=@var{path},id=@var{id}
1295@end example
1296
1297When using the server, the guest will be assigned a VM ID (>=0) that allows guests
1298using the same server to communicate via interrupts.  Guests can read their
1299VM ID from a device register (see ivshmem-spec.txt).
1300
1301@subsubsection Migration with ivshmem
1302
1303With device property @option{master=on}, the guest will copy the shared
1304memory on migration to the destination host.  With @option{master=off},
1305the guest will not be able to migrate with the device attached.  In the
1306latter case, the device should be detached and then reattached after
1307migration using the PCI hotplug support.
1308
1309At most one of the devices sharing the same memory can be master.  The
1310master must complete migration before you plug back the other devices.
1311
1312@subsubsection ivshmem and hugepages
1313
1314Instead of specifying the <shm size> using POSIX shm, you may specify
1315a memory backend that has hugepage support:
1316
1317@example
1318qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
1319                 -device ivshmem-plain,memdev=mb1
1320@end example
1321
1322ivshmem-server also supports hugepages mount points with the
1323@option{-m} memory path argument.
1324
1325@node direct_linux_boot
1326@section Direct Linux Boot
1327
1328This section explains how to launch a Linux kernel inside QEMU without
1329having to make a full bootable image. It is very useful for fast Linux
1330kernel testing.
1331
1332The syntax is:
1333@example
1334qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1335@end example
1336
1337Use @option{-kernel} to provide the Linux kernel image and
1338@option{-append} to give the kernel command line arguments. The
1339@option{-initrd} option can be used to provide an INITRD image.
1340
1341When using the direct Linux boot, a disk image for the first hard disk
1342@file{hda} is required because its boot sector is used to launch the
1343Linux kernel.
1344
1345If you do not need graphical output, you can disable it and redirect
1346the virtual serial port and the QEMU monitor to the console with the
1347@option{-nographic} option. The typical command line is:
1348@example
1349qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1350                 -append "root=/dev/hda console=ttyS0" -nographic
1351@end example
1352
1353Use @key{Ctrl-a c} to switch between the serial console and the
1354monitor (@pxref{pcsys_keys}).
1355
1356@node pcsys_usb
1357@section USB emulation
1358
1359QEMU emulates a PCI UHCI USB controller. You can virtually plug
1360virtual USB devices or real host USB devices (experimental, works only
1361on Linux hosts).  QEMU will automatically create and connect virtual USB hubs
1362as necessary to connect multiple USB devices.
1363
1364@menu
1365* usb_devices::
1366* host_usb_devices::
1367@end menu
1368@node usb_devices
1369@subsection Connecting USB devices
1370
1371USB devices can be connected with the @option{-usbdevice} commandline option
1372or the @code{usb_add} monitor command.  Available devices are:
1373
1374@table @code
1375@item mouse
1376Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
1377@item tablet
1378Pointer device that uses absolute coordinates (like a touchscreen).
1379This means QEMU is able to report the mouse position without having
1380to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
1381@item disk:@var{file}
1382Mass storage device based on @var{file} (@pxref{disk_images})
1383@item host:@var{bus.addr}
1384Pass through the host device identified by @var{bus.addr}
1385(Linux only)
1386@item host:@var{vendor_id:product_id}
1387Pass through the host device identified by @var{vendor_id:product_id}
1388(Linux only)
1389@item wacom-tablet
1390Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
1391above but it can be used with the tslib library because in addition to touch
1392coordinates it reports touch pressure.
1393@item keyboard
1394Standard USB keyboard.  Will override the PS/2 keyboard (if present).
1395@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
1396Serial converter. This emulates an FTDI FT232BM chip connected to host character
1397device @var{dev}. The available character devices are the same as for the
1398@code{-serial} option. The @code{vendorid} and @code{productid} options can be
1399used to override the default 0403:6001. For instance,
1400@example
1401usb_add serial:productid=FA00:tcp:192.168.0.2:4444
1402@end example
1403will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
1404serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
1405@item braille
1406Braille device.  This will use BrlAPI to display the braille output on a real
1407or fake device.
1408@item net:@var{options}
1409Network adapter that supports CDC ethernet and RNDIS protocols.  @var{options}
1410specifies NIC options as with @code{-net nic,}@var{options} (see description).
1411For instance, user-mode networking can be used with
1412@example
1413qemu-system-i386 [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
1414@end example
1415Currently this cannot be used in machines that support PCI NICs.
1416@item bt[:@var{hci-type}]
1417Bluetooth dongle whose type is specified in the same format as with
1418the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
1419no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
1420This USB device implements the USB Transport Layer of HCI.  Example
1421usage:
1422@example
1423@command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3
1424@end example
1425@end table
1426
1427@node host_usb_devices
1428@subsection Using host USB devices on a Linux host
1429
1430WARNING: this is an experimental feature. QEMU will slow down when
1431using it. USB devices requiring real time streaming (i.e. USB Video
1432Cameras) are not supported yet.
1433
1434@enumerate
1435@item If you use an early Linux 2.4 kernel, verify that no Linux driver
1436is actually using the USB device. A simple way to do that is simply to
1437disable the corresponding kernel module by renaming it from @file{mydriver.o}
1438to @file{mydriver.o.disabled}.
1439
1440@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1441@example
1442ls /proc/bus/usb
1443001  devices  drivers
1444@end example
1445
1446@item Since only root can access to the USB devices directly, you can either launch QEMU as root or change the permissions of the USB devices you want to use. For testing, the following suffices:
1447@example
1448chown -R myuid /proc/bus/usb
1449@end example
1450
1451@item Launch QEMU and do in the monitor:
1452@example
1453info usbhost
1454  Device 1.2, speed 480 Mb/s
1455    Class 00: USB device 1234:5678, USB DISK
1456@end example
1457You should see the list of the devices you can use (Never try to use
1458hubs, it won't work).
1459
1460@item Add the device in QEMU by using:
1461@example
1462usb_add host:1234:5678
1463@end example
1464
1465Normally the guest OS should report that a new USB device is
1466plugged. You can use the option @option{-usbdevice} to do the same.
1467
1468@item Now you can try to use the host USB device in QEMU.
1469
1470@end enumerate
1471
1472When relaunching QEMU, you may have to unplug and plug again the USB
1473device to make it work again (this is a bug).
1474
1475@node vnc_security
1476@section VNC security
1477
1478The VNC server capability provides access to the graphical console
1479of the guest VM across the network. This has a number of security
1480considerations depending on the deployment scenarios.
1481
1482@menu
1483* vnc_sec_none::
1484* vnc_sec_password::
1485* vnc_sec_certificate::
1486* vnc_sec_certificate_verify::
1487* vnc_sec_certificate_pw::
1488* vnc_sec_sasl::
1489* vnc_sec_certificate_sasl::
1490* vnc_generate_cert::
1491* vnc_setup_sasl::
1492@end menu
1493@node vnc_sec_none
1494@subsection Without passwords
1495
1496The simplest VNC server setup does not include any form of authentication.
1497For this setup it is recommended to restrict it to listen on a UNIX domain
1498socket only. For example
1499
1500@example
1501qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1502@end example
1503
1504This ensures that only users on local box with read/write access to that
1505path can access the VNC server. To securely access the VNC server from a
1506remote machine, a combination of netcat+ssh can be used to provide a secure
1507tunnel.
1508
1509@node vnc_sec_password
1510@subsection With passwords
1511
1512The VNC protocol has limited support for password based authentication. Since
1513the protocol limits passwords to 8 characters it should not be considered
1514to provide high security. The password can be fairly easily brute-forced by
1515a client making repeat connections. For this reason, a VNC server using password
1516authentication should be restricted to only listen on the loopback interface
1517or UNIX domain sockets. Password authentication is not supported when operating
1518in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
1519authentication is requested with the @code{password} option, and then once QEMU
1520is running the password is set with the monitor. Until the monitor is used to
1521set the password all clients will be rejected.
1522
1523@example
1524qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
1525(qemu) change vnc password
1526Password: ********
1527(qemu)
1528@end example
1529
1530@node vnc_sec_certificate
1531@subsection With x509 certificates
1532
1533The QEMU VNC server also implements the VeNCrypt extension allowing use of
1534TLS for encryption of the session, and x509 certificates for authentication.
1535The use of x509 certificates is strongly recommended, because TLS on its
1536own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1537support provides a secure session, but no authentication. This allows any
1538client to connect, and provides an encrypted session.
1539
1540@example
1541qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1542@end example
1543
1544In the above example @code{/etc/pki/qemu} should contain at least three files,
1545@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1546users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1547NB the @code{server-key.pem} file should be protected with file mode 0600 to
1548only be readable by the user owning it.
1549
1550@node vnc_sec_certificate_verify
1551@subsection With x509 certificates and client verification
1552
1553Certificates can also provide a means to authenticate the client connecting.
1554The server will request that the client provide a certificate, which it will
1555then validate against the CA certificate. This is a good choice if deploying
1556in an environment with a private internal certificate authority.
1557
1558@example
1559qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1560@end example
1561
1562
1563@node vnc_sec_certificate_pw
1564@subsection With x509 certificates, client verification and passwords
1565
1566Finally, the previous method can be combined with VNC password authentication
1567to provide two layers of authentication for clients.
1568
1569@example
1570qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1571(qemu) change vnc password
1572Password: ********
1573(qemu)
1574@end example
1575
1576
1577@node vnc_sec_sasl
1578@subsection With SASL authentication
1579
1580The SASL authentication method is a VNC extension, that provides an
1581easily extendable, pluggable authentication method. This allows for
1582integration with a wide range of authentication mechanisms, such as
1583PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1584The strength of the authentication depends on the exact mechanism
1585configured. If the chosen mechanism also provides a SSF layer, then
1586it will encrypt the datastream as well.
1587
1588Refer to the later docs on how to choose the exact SASL mechanism
1589used for authentication, but assuming use of one supporting SSF,
1590then QEMU can be launched with:
1591
1592@example
1593qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
1594@end example
1595
1596@node vnc_sec_certificate_sasl
1597@subsection With x509 certificates and SASL authentication
1598
1599If the desired SASL authentication mechanism does not supported
1600SSF layers, then it is strongly advised to run it in combination
1601with TLS and x509 certificates. This provides securely encrypted
1602data stream, avoiding risk of compromising of the security
1603credentials. This can be enabled, by combining the 'sasl' option
1604with the aforementioned TLS + x509 options:
1605
1606@example
1607qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
1608@end example
1609
1610
1611@node vnc_generate_cert
1612@subsection Generating certificates for VNC
1613
1614The GNU TLS packages provides a command called @code{certtool} which can
1615be used to generate certificates and keys in PEM format. At a minimum it
1616is necessary to setup a certificate authority, and issue certificates to
1617each server. If using certificates for authentication, then each client
1618will also need to be issued a certificate. The recommendation is for the
1619server to keep its certificates in either @code{/etc/pki/qemu} or for
1620unprivileged users in @code{$HOME/.pki/qemu}.
1621
1622@menu
1623* vnc_generate_ca::
1624* vnc_generate_server::
1625* vnc_generate_client::
1626@end menu
1627@node vnc_generate_ca
1628@subsubsection Setup the Certificate Authority
1629
1630This step only needs to be performed once per organization / organizational
1631unit. First the CA needs a private key. This key must be kept VERY secret
1632and secure. If this key is compromised the entire trust chain of the certificates
1633issued with it is lost.
1634
1635@example
1636# certtool --generate-privkey > ca-key.pem
1637@end example
1638
1639A CA needs to have a public certificate. For simplicity it can be a self-signed
1640certificate, or one issue by a commercial certificate issuing authority. To
1641generate a self-signed certificate requires one core piece of information, the
1642name of the organization.
1643
1644@example
1645# cat > ca.info <<EOF
1646cn = Name of your organization
1647ca
1648cert_signing_key
1649EOF
1650# certtool --generate-self-signed \
1651           --load-privkey ca-key.pem
1652           --template ca.info \
1653           --outfile ca-cert.pem
1654@end example
1655
1656The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1657TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1658
1659@node vnc_generate_server
1660@subsubsection Issuing server certificates
1661
1662Each server (or host) needs to be issued with a key and certificate. When connecting
1663the certificate is sent to the client which validates it against the CA certificate.
1664The core piece of information for a server certificate is the hostname. This should
1665be the fully qualified hostname that the client will connect with, since the client
1666will typically also verify the hostname in the certificate. On the host holding the
1667secure CA private key:
1668
1669@example
1670# cat > server.info <<EOF
1671organization = Name  of your organization
1672cn = server.foo.example.com
1673tls_www_server
1674encryption_key
1675signing_key
1676EOF
1677# certtool --generate-privkey > server-key.pem
1678# certtool --generate-certificate \
1679           --load-ca-certificate ca-cert.pem \
1680           --load-ca-privkey ca-key.pem \
1681           --load-privkey server-key.pem \
1682           --template server.info \
1683           --outfile server-cert.pem
1684@end example
1685
1686The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1687to the server for which they were generated. The @code{server-key.pem} is security
1688sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1689
1690@node vnc_generate_client
1691@subsubsection Issuing client certificates
1692
1693If the QEMU VNC server is to use the @code{x509verify} option to validate client
1694certificates as its authentication mechanism, each client also needs to be issued
1695a certificate. The client certificate contains enough metadata to uniquely identify
1696the client, typically organization, state, city, building, etc. On the host holding
1697the secure CA private key:
1698
1699@example
1700# cat > client.info <<EOF
1701country = GB
1702state = London
1703locality = London
1704organization = Name of your organization
1705cn = client.foo.example.com
1706tls_www_client
1707encryption_key
1708signing_key
1709EOF
1710# certtool --generate-privkey > client-key.pem
1711# certtool --generate-certificate \
1712           --load-ca-certificate ca-cert.pem \
1713           --load-ca-privkey ca-key.pem \
1714           --load-privkey client-key.pem \
1715           --template client.info \
1716           --outfile client-cert.pem
1717@end example
1718
1719The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1720copied to the client for which they were generated.
1721
1722
1723@node vnc_setup_sasl
1724
1725@subsection Configuring SASL mechanisms
1726
1727The following documentation assumes use of the Cyrus SASL implementation on a
1728Linux host, but the principals should apply to any other SASL impl. When SASL
1729is enabled, the mechanism configuration will be loaded from system default
1730SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1731unprivileged user, an environment variable SASL_CONF_PATH can be used
1732to make it search alternate locations for the service config.
1733
1734The default configuration might contain
1735
1736@example
1737mech_list: digest-md5
1738sasldb_path: /etc/qemu/passwd.db
1739@end example
1740
1741This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
1742Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
1743in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
1744command. While this mechanism is easy to configure and use, it is not
1745considered secure by modern standards, so only suitable for developers /
1746ad-hoc testing.
1747
1748A more serious deployment might use Kerberos, which is done with the 'gssapi'
1749mechanism
1750
1751@example
1752mech_list: gssapi
1753keytab: /etc/qemu/krb5.tab
1754@end example
1755
1756For this to work the administrator of your KDC must generate a Kerberos
1757principal for the server, with a name of  'qemu/somehost.example.com@@EXAMPLE.COM'
1758replacing 'somehost.example.com' with the fully qualified host name of the
1759machine running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
1760
1761Other configurations will be left as an exercise for the reader. It should
1762be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
1763encryption. For all other mechanisms, VNC should always be configured to
1764use TLS and x509 certificates to protect security credentials from snooping.
1765
1766@node gdb_usage
1767@section GDB usage
1768
1769QEMU has a primitive support to work with gdb, so that you can do
1770'Ctrl-C' while the virtual machine is running and inspect its state.
1771
1772In order to use gdb, launch QEMU with the '-s' option. It will wait for a
1773gdb connection:
1774@example
1775qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1776                    -append "root=/dev/hda"
1777Connected to host network interface: tun0
1778Waiting gdb connection on port 1234
1779@end example
1780
1781Then launch gdb on the 'vmlinux' executable:
1782@example
1783> gdb vmlinux
1784@end example
1785
1786In gdb, connect to QEMU:
1787@example
1788(gdb) target remote localhost:1234
1789@end example
1790
1791Then you can use gdb normally. For example, type 'c' to launch the kernel:
1792@example
1793(gdb) c
1794@end example
1795
1796Here are some useful tips in order to use gdb on system code:
1797
1798@enumerate
1799@item
1800Use @code{info reg} to display all the CPU registers.
1801@item
1802Use @code{x/10i $eip} to display the code at the PC position.
1803@item
1804Use @code{set architecture i8086} to dump 16 bit code. Then use
1805@code{x/10i $cs*16+$eip} to dump the code at the PC position.
1806@end enumerate
1807
1808Advanced debugging options:
1809
1810The default single stepping behavior is step with the IRQs and timer service routines off.  It is set this way because when gdb executes a single step it expects to advance beyond the current instruction.  With the IRQs and timer service routines on, a single step might jump into the one of the interrupt or exception vectors instead of executing the current instruction. This means you may hit the same breakpoint a number of times before executing the instruction gdb wants to have executed.  Because there are rare circumstances where you want to single step into an interrupt vector the behavior can be controlled from GDB.  There are three commands you can query and set the single step behavior:
1811@table @code
1812@item maintenance packet qqemu.sstepbits
1813
1814This will display the MASK bits used to control the single stepping IE:
1815@example
1816(gdb) maintenance packet qqemu.sstepbits
1817sending: "qqemu.sstepbits"
1818received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1819@end example
1820@item maintenance packet qqemu.sstep
1821
1822This will display the current value of the mask used when single stepping IE:
1823@example
1824(gdb) maintenance packet qqemu.sstep
1825sending: "qqemu.sstep"
1826received: "0x7"
1827@end example
1828@item maintenance packet Qqemu.sstep=HEX_VALUE
1829
1830This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1831@example
1832(gdb) maintenance packet Qqemu.sstep=0x5
1833sending: "qemu.sstep=0x5"
1834received: "OK"
1835@end example
1836@end table
1837
1838@node pcsys_os_specific
1839@section Target OS specific information
1840
1841@subsection Linux
1842
1843To have access to SVGA graphic modes under X11, use the @code{vesa} or
1844the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1845color depth in the guest and the host OS.
1846
1847When using a 2.6 guest Linux kernel, you should add the option
1848@code{clock=pit} on the kernel command line because the 2.6 Linux
1849kernels make very strict real time clock checks by default that QEMU
1850cannot simulate exactly.
1851
1852When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1853not activated because QEMU is slower with this patch. The QEMU
1854Accelerator Module is also much slower in this case. Earlier Fedora
1855Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1856patch by default. Newer kernels don't have it.
1857
1858@subsection Windows
1859
1860If you have a slow host, using Windows 95 is better as it gives the
1861best speed. Windows 2000 is also a good choice.
1862
1863@subsubsection SVGA graphic modes support
1864
1865QEMU emulates a Cirrus Logic GD5446 Video
1866card. All Windows versions starting from Windows 95 should recognize
1867and use this graphic card. For optimal performances, use 16 bit color
1868depth in the guest and the host OS.
1869
1870If you are using Windows XP as guest OS and if you want to use high
1871resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
18721280x1024x16), then you should use the VESA VBE virtual graphic card
1873(option @option{-std-vga}).
1874
1875@subsubsection CPU usage reduction
1876
1877Windows 9x does not correctly use the CPU HLT
1878instruction. The result is that it takes host CPU cycles even when
1879idle. You can install the utility from
1880@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1881problem. Note that no such tool is needed for NT, 2000 or XP.
1882
1883@subsubsection Windows 2000 disk full problem
1884
1885Windows 2000 has a bug which gives a disk full problem during its
1886installation. When installing it, use the @option{-win2k-hack} QEMU
1887option to enable a specific workaround. After Windows 2000 is
1888installed, you no longer need this option (this option slows down the
1889IDE transfers).
1890
1891@subsubsection Windows 2000 shutdown
1892
1893Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1894can. It comes from the fact that Windows 2000 does not automatically
1895use the APM driver provided by the BIOS.
1896
1897In order to correct that, do the following (thanks to Struan
1898Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1899Add/Troubleshoot a device => Add a new device & Next => No, select the
1900hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1901(again) a few times. Now the driver is installed and Windows 2000 now
1902correctly instructs QEMU to shutdown at the appropriate moment.
1903
1904@subsubsection Share a directory between Unix and Windows
1905
1906See @ref{sec_invocation} about the help of the option
1907@option{'-netdev user,smb=...'}.
1908
1909@subsubsection Windows XP security problem
1910
1911Some releases of Windows XP install correctly but give a security
1912error when booting:
1913@example
1914A problem is preventing Windows from accurately checking the
1915license for this computer. Error code: 0x800703e6.
1916@end example
1917
1918The workaround is to install a service pack for XP after a boot in safe
1919mode. Then reboot, and the problem should go away. Since there is no
1920network while in safe mode, its recommended to download the full
1921installation of SP1 or SP2 and transfer that via an ISO or using the
1922vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1923
1924@subsection MS-DOS and FreeDOS
1925
1926@subsubsection CPU usage reduction
1927
1928DOS does not correctly use the CPU HLT instruction. The result is that
1929it takes host CPU cycles even when idle. You can install the utility
1930from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1931problem.
1932
1933@node QEMU System emulator for non PC targets
1934@chapter QEMU System emulator for non PC targets
1935
1936QEMU is a generic emulator and it emulates many non PC
1937machines. Most of the options are similar to the PC emulator. The
1938differences are mentioned in the following sections.
1939
1940@menu
1941* PowerPC System emulator::
1942* Sparc32 System emulator::
1943* Sparc64 System emulator::
1944* MIPS System emulator::
1945* ARM System emulator::
1946* ColdFire System emulator::
1947* Cris System emulator::
1948* Microblaze System emulator::
1949* SH4 System emulator::
1950* Xtensa System emulator::
1951@end menu
1952
1953@node PowerPC System emulator
1954@section PowerPC System emulator
1955@cindex system emulation (PowerPC)
1956
1957Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1958or PowerMac PowerPC system.
1959
1960QEMU emulates the following PowerMac peripherals:
1961
1962@itemize @minus
1963@item
1964UniNorth or Grackle PCI Bridge
1965@item
1966PCI VGA compatible card with VESA Bochs Extensions
1967@item
19682 PMAC IDE interfaces with hard disk and CD-ROM support
1969@item
1970NE2000 PCI adapters
1971@item
1972Non Volatile RAM
1973@item
1974VIA-CUDA with ADB keyboard and mouse.
1975@end itemize
1976
1977QEMU emulates the following PREP peripherals:
1978
1979@itemize @minus
1980@item
1981PCI Bridge
1982@item
1983PCI VGA compatible card with VESA Bochs Extensions
1984@item
19852 IDE interfaces with hard disk and CD-ROM support
1986@item
1987Floppy disk
1988@item
1989NE2000 network adapters
1990@item
1991Serial port
1992@item
1993PREP Non Volatile RAM
1994@item
1995PC compatible keyboard and mouse.
1996@end itemize
1997
1998QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1999@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
2000
2001Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
2002for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
2003v2) portable firmware implementation. The goal is to implement a 100%
2004IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
2005
2006@c man begin OPTIONS
2007
2008The following options are specific to the PowerPC emulation:
2009
2010@table @option
2011
2012@item -g @var{W}x@var{H}[x@var{DEPTH}]
2013
2014Set the initial VGA graphic mode. The default is 800x600x32.
2015
2016@item -prom-env @var{string}
2017
2018Set OpenBIOS variables in NVRAM, for example:
2019
2020@example
2021qemu-system-ppc -prom-env 'auto-boot?=false' \
2022 -prom-env 'boot-device=hd:2,\yaboot' \
2023 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
2024@end example
2025
2026These variables are not used by Open Hack'Ware.
2027
2028@end table
2029
2030@c man end
2031
2032
2033More information is available at
2034@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
2035
2036@node Sparc32 System emulator
2037@section Sparc32 System emulator
2038@cindex system emulation (Sparc32)
2039
2040Use the executable @file{qemu-system-sparc} to simulate the following
2041Sun4m architecture machines:
2042@itemize @minus
2043@item
2044SPARCstation 4
2045@item
2046SPARCstation 5
2047@item
2048SPARCstation 10
2049@item
2050SPARCstation 20
2051@item
2052SPARCserver 600MP
2053@item
2054SPARCstation LX
2055@item
2056SPARCstation Voyager
2057@item
2058SPARCclassic
2059@item
2060SPARCbook
2061@end itemize
2062
2063The emulation is somewhat complete. SMP up to 16 CPUs is supported,
2064but Linux limits the number of usable CPUs to 4.
2065
2066QEMU emulates the following sun4m peripherals:
2067
2068@itemize @minus
2069@item
2070IOMMU
2071@item
2072TCX or cgthree Frame buffer
2073@item
2074Lance (Am7990) Ethernet
2075@item
2076Non Volatile RAM M48T02/M48T08
2077@item
2078Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2079and power/reset logic
2080@item
2081ESP SCSI controller with hard disk and CD-ROM support
2082@item
2083Floppy drive (not on SS-600MP)
2084@item
2085CS4231 sound device (only on SS-5, not working yet)
2086@end itemize
2087
2088The number of peripherals is fixed in the architecture.  Maximum
2089memory size depends on the machine type, for SS-5 it is 256MB and for
2090others 2047MB.
2091
2092Since version 0.8.2, QEMU uses OpenBIOS
2093@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
2094firmware implementation. The goal is to implement a 100% IEEE
20951275-1994 (referred to as Open Firmware) compliant firmware.
2096
2097A sample Linux 2.6 series kernel and ram disk image are available on
2098the QEMU web site. There are still issues with NetBSD and OpenBSD, but
2099most kernel versions work. Please note that currently older Solaris kernels
2100don't work probably due to interface issues between OpenBIOS and
2101Solaris.
2102
2103@c man begin OPTIONS
2104
2105The following options are specific to the Sparc32 emulation:
2106
2107@table @option
2108
2109@item -g @var{W}x@var{H}x[x@var{DEPTH}]
2110
2111Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
2112option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
2113of 1152x900x8 for people who wish to use OBP.
2114
2115@item -prom-env @var{string}
2116
2117Set OpenBIOS variables in NVRAM, for example:
2118
2119@example
2120qemu-system-sparc -prom-env 'auto-boot?=false' \
2121 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2122@end example
2123
2124@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]
2125
2126Set the emulated machine type. Default is SS-5.
2127
2128@end table
2129
2130@c man end
2131
2132@node Sparc64 System emulator
2133@section Sparc64 System emulator
2134@cindex system emulation (Sparc64)
2135
2136Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
2137(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
2138Niagara (T1) machine. The Sun4u emulator is mostly complete, being
2139able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
2140Sun4v and Niagara emulators are still a work in progress.
2141
2142QEMU emulates the following peripherals:
2143
2144@itemize @minus
2145@item
2146UltraSparc IIi APB PCI Bridge
2147@item
2148PCI VGA compatible card with VESA Bochs Extensions
2149@item
2150PS/2 mouse and keyboard
2151@item
2152Non Volatile RAM M48T59
2153@item
2154PC-compatible serial ports
2155@item
21562 PCI IDE interfaces with hard disk and CD-ROM support
2157@item
2158Floppy disk
2159@end itemize
2160
2161@c man begin OPTIONS
2162
2163The following options are specific to the Sparc64 emulation:
2164
2165@table @option
2166
2167@item -prom-env @var{string}
2168
2169Set OpenBIOS variables in NVRAM, for example:
2170
2171@example
2172qemu-system-sparc64 -prom-env 'auto-boot?=false'
2173@end example
2174
2175@item -M [sun4u|sun4v|Niagara]
2176
2177Set the emulated machine type. The default is sun4u.
2178
2179@end table
2180
2181@c man end
2182
2183@node MIPS System emulator
2184@section MIPS System emulator
2185@cindex system emulation (MIPS)
2186
2187Four executables cover simulation of 32 and 64-bit MIPS systems in
2188both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2189@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
2190Five different machine types are emulated:
2191
2192@itemize @minus
2193@item
2194A generic ISA PC-like machine "mips"
2195@item
2196The MIPS Malta prototype board "malta"
2197@item
2198An ACER Pica "pica61". This machine needs the 64-bit emulator.
2199@item
2200MIPS emulator pseudo board "mipssim"
2201@item
2202A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
2203@end itemize
2204
2205The generic emulation is supported by Debian 'Etch' and is able to
2206install Debian into a virtual disk image. The following devices are
2207emulated:
2208
2209@itemize @minus
2210@item
2211A range of MIPS CPUs, default is the 24Kf
2212@item
2213PC style serial port
2214@item
2215PC style IDE disk
2216@item
2217NE2000 network card
2218@end itemize
2219
2220The Malta emulation supports the following devices:
2221
2222@itemize @minus
2223@item
2224Core board with MIPS 24Kf CPU and Galileo system controller
2225@item
2226PIIX4 PCI/USB/SMbus controller
2227@item
2228The Multi-I/O chip's serial device
2229@item
2230PCI network cards (PCnet32 and others)
2231@item
2232Malta FPGA serial device
2233@item
2234Cirrus (default) or any other PCI VGA graphics card
2235@end itemize
2236
2237The ACER Pica emulation supports:
2238
2239@itemize @minus
2240@item
2241MIPS R4000 CPU
2242@item
2243PC-style IRQ and DMA controllers
2244@item
2245PC Keyboard
2246@item
2247IDE controller
2248@end itemize
2249
2250The mipssim pseudo board emulation provides an environment similar
2251to what the proprietary MIPS emulator uses for running Linux.
2252It supports:
2253
2254@itemize @minus
2255@item
2256A range of MIPS CPUs, default is the 24Kf
2257@item
2258PC style serial port
2259@item
2260MIPSnet network emulation
2261@end itemize
2262
2263The MIPS Magnum R4000 emulation supports:
2264
2265@itemize @minus
2266@item
2267MIPS R4000 CPU
2268@item
2269PC-style IRQ controller
2270@item
2271PC Keyboard
2272@item
2273SCSI controller
2274@item
2275G364 framebuffer
2276@end itemize
2277
2278
2279@node ARM System emulator
2280@section ARM System emulator
2281@cindex system emulation (ARM)
2282
2283Use the executable @file{qemu-system-arm} to simulate a ARM
2284machine. The ARM Integrator/CP board is emulated with the following
2285devices:
2286
2287@itemize @minus
2288@item
2289ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
2290@item
2291Two PL011 UARTs
2292@item
2293SMC 91c111 Ethernet adapter
2294@item
2295PL110 LCD controller
2296@item
2297PL050 KMI with PS/2 keyboard and mouse.
2298@item
2299PL181 MultiMedia Card Interface with SD card.
2300@end itemize
2301
2302The ARM Versatile baseboard is emulated with the following devices:
2303
2304@itemize @minus
2305@item
2306ARM926E, ARM1136 or Cortex-A8 CPU
2307@item
2308PL190 Vectored Interrupt Controller
2309@item
2310Four PL011 UARTs
2311@item
2312SMC 91c111 Ethernet adapter
2313@item
2314PL110 LCD controller
2315@item
2316PL050 KMI with PS/2 keyboard and mouse.
2317@item
2318PCI host bridge.  Note the emulated PCI bridge only provides access to
2319PCI memory space.  It does not provide access to PCI IO space.
2320This means some devices (eg. ne2k_pci NIC) are not usable, and others
2321(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
2322mapped control registers.
2323@item
2324PCI OHCI USB controller.
2325@item
2326LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
2327@item
2328PL181 MultiMedia Card Interface with SD card.
2329@end itemize
2330
2331Several variants of the ARM RealView baseboard are emulated,
2332including the EB, PB-A8 and PBX-A9.  Due to interactions with the
2333bootloader, only certain Linux kernel configurations work out
2334of the box on these boards.
2335
2336Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2337enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board
2338should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2339disabled and expect 1024M RAM.
2340
2341The following devices are emulated:
2342
2343@itemize @minus
2344@item
2345ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
2346@item
2347ARM AMBA Generic/Distributed Interrupt Controller
2348@item
2349Four PL011 UARTs
2350@item
2351SMC 91c111 or SMSC LAN9118 Ethernet adapter
2352@item
2353PL110 LCD controller
2354@item
2355PL050 KMI with PS/2 keyboard and mouse
2356@item
2357PCI host bridge
2358@item
2359PCI OHCI USB controller
2360@item
2361LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
2362@item
2363PL181 MultiMedia Card Interface with SD card.
2364@end itemize
2365
2366The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2367and "Terrier") emulation includes the following peripherals:
2368
2369@itemize @minus
2370@item
2371Intel PXA270 System-on-chip (ARM V5TE core)
2372@item
2373NAND Flash memory
2374@item
2375IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2376@item
2377On-chip OHCI USB controller
2378@item
2379On-chip LCD controller
2380@item
2381On-chip Real Time Clock
2382@item
2383TI ADS7846 touchscreen controller on SSP bus
2384@item
2385Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2386@item
2387GPIO-connected keyboard controller and LEDs
2388@item
2389Secure Digital card connected to PXA MMC/SD host
2390@item
2391Three on-chip UARTs
2392@item
2393WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2394@end itemize
2395
2396The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2397following elements:
2398
2399@itemize @minus
2400@item
2401Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2402@item
2403ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2404@item
2405On-chip LCD controller
2406@item
2407On-chip Real Time Clock
2408@item
2409TI TSC2102i touchscreen controller / analog-digital converter / Audio
2410CODEC, connected through MicroWire and I@math{^2}S busses
2411@item
2412GPIO-connected matrix keypad
2413@item
2414Secure Digital card connected to OMAP MMC/SD host
2415@item
2416Three on-chip UARTs
2417@end itemize
2418
2419Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2420emulation supports the following elements:
2421
2422@itemize @minus
2423@item
2424Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2425@item
2426RAM and non-volatile OneNAND Flash memories
2427@item
2428Display connected to EPSON remote framebuffer chip and OMAP on-chip
2429display controller and a LS041y3 MIPI DBI-C controller
2430@item
2431TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2432driven through SPI bus
2433@item
2434National Semiconductor LM8323-controlled qwerty keyboard driven
2435through I@math{^2}C bus
2436@item
2437Secure Digital card connected to OMAP MMC/SD host
2438@item
2439Three OMAP on-chip UARTs and on-chip STI debugging console
2440@item
2441A Bluetooth(R) transceiver and HCI connected to an UART
2442@item
2443Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2444TUSB6010 chip - only USB host mode is supported
2445@item
2446TI TMP105 temperature sensor driven through I@math{^2}C bus
2447@item
2448TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2449@item
2450Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2451through CBUS
2452@end itemize
2453
2454The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2455devices:
2456
2457@itemize @minus
2458@item
2459Cortex-M3 CPU core.
2460@item
246164k Flash and 8k SRAM.
2462@item
2463Timers, UARTs, ADC and I@math{^2}C interface.
2464@item
2465OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2466@end itemize
2467
2468The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2469devices:
2470
2471@itemize @minus
2472@item
2473Cortex-M3 CPU core.
2474@item
2475256k Flash and 64k SRAM.
2476@item
2477Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2478@item
2479OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2480@end itemize
2481
2482The Freecom MusicPal internet radio emulation includes the following
2483elements:
2484
2485@itemize @minus
2486@item
2487Marvell MV88W8618 ARM core.
2488@item
248932 MB RAM, 256 KB SRAM, 8 MB flash.
2490@item
2491Up to 2 16550 UARTs
2492@item
2493MV88W8xx8 Ethernet controller
2494@item
2495MV88W8618 audio controller, WM8750 CODEC and mixer
2496@item
249712864 display with brightness control
2498@item
24992 buttons, 2 navigation wheels with button function
2500@end itemize
2501
2502The Siemens SX1 models v1 and v2 (default) basic emulation.
2503The emulation includes the following elements:
2504
2505@itemize @minus
2506@item
2507Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2508@item
2509ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2510V1
25111 Flash of 16MB and 1 Flash of 8MB
2512V2
25131 Flash of 32MB
2514@item
2515On-chip LCD controller
2516@item
2517On-chip Real Time Clock
2518@item
2519Secure Digital card connected to OMAP MMC/SD host
2520@item
2521Three on-chip UARTs
2522@end itemize
2523
2524A Linux 2.6 test image is available on the QEMU web site. More
2525information is available in the QEMU mailing-list archive.
2526
2527@c man begin OPTIONS
2528
2529The following options are specific to the ARM emulation:
2530
2531@table @option
2532
2533@item -semihosting
2534Enable semihosting syscall emulation.
2535
2536On ARM this implements the "Angel" interface.
2537
2538Note that this allows guest direct access to the host filesystem,
2539so should only be used with trusted guest OS.
2540
2541@end table
2542
2543@node ColdFire System emulator
2544@section ColdFire System emulator
2545@cindex system emulation (ColdFire)
2546@cindex system emulation (M68K)
2547
2548Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2549The emulator is able to boot a uClinux kernel.
2550
2551The M5208EVB emulation includes the following devices:
2552
2553@itemize @minus
2554@item
2555MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2556@item
2557Three Two on-chip UARTs.
2558@item
2559Fast Ethernet Controller (FEC)
2560@end itemize
2561
2562The AN5206 emulation includes the following devices:
2563
2564@itemize @minus
2565@item
2566MCF5206 ColdFire V2 Microprocessor.
2567@item
2568Two on-chip UARTs.
2569@end itemize
2570
2571@c man begin OPTIONS
2572
2573The following options are specific to the ColdFire emulation:
2574
2575@table @option
2576
2577@item -semihosting
2578Enable semihosting syscall emulation.
2579
2580On M68K this implements the "ColdFire GDB" interface used by libgloss.
2581
2582Note that this allows guest direct access to the host filesystem,
2583so should only be used with trusted guest OS.
2584
2585@end table
2586
2587@node Cris System emulator
2588@section Cris System emulator
2589@cindex system emulation (Cris)
2590
2591TODO
2592
2593@node Microblaze System emulator
2594@section Microblaze System emulator
2595@cindex system emulation (Microblaze)
2596
2597TODO
2598
2599@node SH4 System emulator
2600@section SH4 System emulator
2601@cindex system emulation (SH4)
2602
2603TODO
2604
2605@node Xtensa System emulator
2606@section Xtensa System emulator
2607@cindex system emulation (Xtensa)
2608
2609Two executables cover simulation of both Xtensa endian options,
2610@file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
2611Two different machine types are emulated:
2612
2613@itemize @minus
2614@item
2615Xtensa emulator pseudo board "sim"
2616@item
2617Avnet LX60/LX110/LX200 board
2618@end itemize
2619
2620The sim pseudo board emulation provides an environment similar
2621to one provided by the proprietary Tensilica ISS.
2622It supports:
2623
2624@itemize @minus
2625@item
2626A range of Xtensa CPUs, default is the DC232B
2627@item
2628Console and filesystem access via semihosting calls
2629@end itemize
2630
2631The Avnet LX60/LX110/LX200 emulation supports:
2632
2633@itemize @minus
2634@item
2635A range of Xtensa CPUs, default is the DC232B
2636@item
263716550 UART
2638@item
2639OpenCores 10/100 Mbps Ethernet MAC
2640@end itemize
2641
2642@c man begin OPTIONS
2643
2644The following options are specific to the Xtensa emulation:
2645
2646@table @option
2647
2648@item -semihosting
2649Enable semihosting syscall emulation.
2650
2651Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2652Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2653
2654Note that this allows guest direct access to the host filesystem,
2655so should only be used with trusted guest OS.
2656
2657@end table
2658@node QEMU User space emulator
2659@chapter QEMU User space emulator
2660
2661@menu
2662* Supported Operating Systems ::
2663* Linux User space emulator::
2664* BSD User space emulator ::
2665@end menu
2666
2667@node Supported Operating Systems
2668@section Supported Operating Systems
2669
2670The following OS are supported in user space emulation:
2671
2672@itemize @minus
2673@item
2674Linux (referred as qemu-linux-user)
2675@item
2676BSD (referred as qemu-bsd-user)
2677@end itemize
2678
2679@node Linux User space emulator
2680@section Linux User space emulator
2681
2682@menu
2683* Quick Start::
2684* Wine launch::
2685* Command line options::
2686* Other binaries::
2687@end menu
2688
2689@node Quick Start
2690@subsection Quick Start
2691
2692In order to launch a Linux process, QEMU needs the process executable
2693itself and all the target (x86) dynamic libraries used by it.
2694
2695@itemize
2696
2697@item On x86, you can just try to launch any process by using the native
2698libraries:
2699
2700@example
2701qemu-i386 -L / /bin/ls
2702@end example
2703
2704@code{-L /} tells that the x86 dynamic linker must be searched with a
2705@file{/} prefix.
2706
2707@item Since QEMU is also a linux process, you can launch QEMU with
2708QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
2709
2710@example
2711qemu-i386 -L / qemu-i386 -L / /bin/ls
2712@end example
2713
2714@item On non x86 CPUs, you need first to download at least an x86 glibc
2715(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2716@code{LD_LIBRARY_PATH} is not set:
2717
2718@example
2719unset LD_LIBRARY_PATH
2720@end example
2721
2722Then you can launch the precompiled @file{ls} x86 executable:
2723
2724@example
2725qemu-i386 tests/i386/ls
2726@end example
2727You can look at @file{scripts/qemu-binfmt-conf.sh} so that
2728QEMU is automatically launched by the Linux kernel when you try to
2729launch x86 executables. It requires the @code{binfmt_misc} module in the
2730Linux kernel.
2731
2732@item The x86 version of QEMU is also included. You can try weird things such as:
2733@example
2734qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2735          /usr/local/qemu-i386/bin/ls-i386
2736@end example
2737
2738@end itemize
2739
2740@node Wine launch
2741@subsection Wine launch
2742
2743@itemize
2744
2745@item Ensure that you have a working QEMU with the x86 glibc
2746distribution (see previous section). In order to verify it, you must be
2747able to do:
2748
2749@example
2750qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2751@end example
2752
2753@item Download the binary x86 Wine install
2754(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2755
2756@item Configure Wine on your account. Look at the provided script
2757@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2758@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2759
2760@item Then you can try the example @file{putty.exe}:
2761
2762@example
2763qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2764          /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2765@end example
2766
2767@end itemize
2768
2769@node Command line options
2770@subsection Command line options
2771
2772@example
2773@command{qemu-i386} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-cpu} @var{model}] [@option{-g} @var{port}] [@option{-B} @var{offset}] [@option{-R} @var{size}] @var{program} [@var{arguments}...]
2774@end example
2775
2776@table @option
2777@item -h
2778Print the help
2779@item -L path
2780Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2781@item -s size
2782Set the x86 stack size in bytes (default=524288)
2783@item -cpu model
2784Select CPU model (-cpu help for list and additional feature selection)
2785@item -E @var{var}=@var{value}
2786Set environment @var{var} to @var{value}.
2787@item -U @var{var}
2788Remove @var{var} from the environment.
2789@item -B offset
2790Offset guest address by the specified number of bytes.  This is useful when
2791the address region required by guest applications is reserved on the host.
2792This option is currently only supported on some hosts.
2793@item -R size
2794Pre-allocate a guest virtual address space of the given size (in bytes).
2795"G", "M", and "k" suffixes may be used when specifying the size.
2796@end table
2797
2798Debug options:
2799
2800@table @option
2801@item -d item1,...
2802Activate logging of the specified items (use '-d help' for a list of log items)
2803@item -p pagesize
2804Act as if the host page size was 'pagesize' bytes
2805@item -g port
2806Wait gdb connection to port
2807@item -singlestep
2808Run the emulation in single step mode.
2809@end table
2810
2811Environment variables:
2812
2813@table @env
2814@item QEMU_STRACE
2815Print system calls and arguments similar to the 'strace' program
2816(NOTE: the actual 'strace' program will not work because the user
2817space emulator hasn't implemented ptrace).  At the moment this is
2818incomplete.  All system calls that don't have a specific argument
2819format are printed with information for six arguments.  Many
2820flag-style arguments don't have decoders and will show up as numbers.
2821@end table
2822
2823@node Other binaries
2824@subsection Other binaries
2825
2826@cindex user mode (Alpha)
2827@command{qemu-alpha} TODO.
2828
2829@cindex user mode (ARM)
2830@command{qemu-armeb} TODO.
2831
2832@cindex user mode (ARM)
2833@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2834binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2835configurations), and arm-uclinux bFLT format binaries.
2836
2837@cindex user mode (ColdFire)
2838@cindex user mode (M68K)
2839@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2840(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2841coldfire uClinux bFLT format binaries.
2842
2843The binary format is detected automatically.
2844
2845@cindex user mode (Cris)
2846@command{qemu-cris} TODO.
2847
2848@cindex user mode (i386)
2849@command{qemu-i386} TODO.
2850@command{qemu-x86_64} TODO.
2851
2852@cindex user mode (Microblaze)
2853@command{qemu-microblaze} TODO.
2854
2855@cindex user mode (MIPS)
2856@command{qemu-mips} TODO.
2857@command{qemu-mipsel} TODO.
2858
2859@cindex user mode (PowerPC)
2860@command{qemu-ppc64abi32} TODO.
2861@command{qemu-ppc64} TODO.
2862@command{qemu-ppc} TODO.
2863
2864@cindex user mode (SH4)
2865@command{qemu-sh4eb} TODO.
2866@command{qemu-sh4} TODO.
2867
2868@cindex user mode (SPARC)
2869@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2870
2871@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2872(Sparc64 CPU, 32 bit ABI).
2873
2874@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2875SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2876
2877@node BSD User space emulator
2878@section BSD User space emulator
2879
2880@menu
2881* BSD Status::
2882* BSD Quick Start::
2883* BSD Command line options::
2884@end menu
2885
2886@node BSD Status
2887@subsection BSD Status
2888
2889@itemize @minus
2890@item
2891target Sparc64 on Sparc64: Some trivial programs work.
2892@end itemize
2893
2894@node BSD Quick Start
2895@subsection Quick Start
2896
2897In order to launch a BSD process, QEMU needs the process executable
2898itself and all the target dynamic libraries used by it.
2899
2900@itemize
2901
2902@item On Sparc64, you can just try to launch any process by using the native
2903libraries:
2904
2905@example
2906qemu-sparc64 /bin/ls
2907@end example
2908
2909@end itemize
2910
2911@node BSD Command line options
2912@subsection Command line options
2913
2914@example
2915@command{qemu-sparc64} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-bsd} @var{type}] @var{program} [@var{arguments}...]
2916@end example
2917
2918@table @option
2919@item -h
2920Print the help
2921@item -L path
2922Set the library root path (default=/)
2923@item -s size
2924Set the stack size in bytes (default=524288)
2925@item -ignore-environment
2926Start with an empty environment. Without this option,
2927the initial environment is a copy of the caller's environment.
2928@item -E @var{var}=@var{value}
2929Set environment @var{var} to @var{value}.
2930@item -U @var{var}
2931Remove @var{var} from the environment.
2932@item -bsd type
2933Set the type of the emulated BSD Operating system. Valid values are
2934FreeBSD, NetBSD and OpenBSD (default).
2935@end table
2936
2937Debug options:
2938
2939@table @option
2940@item -d item1,...
2941Activate logging of the specified items (use '-d help' for a list of log items)
2942@item -p pagesize
2943Act as if the host page size was 'pagesize' bytes
2944@item -singlestep
2945Run the emulation in single step mode.
2946@end table
2947
2948@node compilation
2949@chapter Compilation from the sources
2950
2951@menu
2952* Linux/Unix::
2953* Windows::
2954* Cross compilation for Windows with Linux::
2955* Mac OS X::
2956* Make targets::
2957@end menu
2958
2959@node Linux/Unix
2960@section Linux/Unix
2961
2962@subsection Compilation
2963
2964First you must decompress the sources:
2965@example
2966cd /tmp
2967tar zxvf qemu-x.y.z.tar.gz
2968cd qemu-x.y.z
2969@end example
2970
2971Then you configure QEMU and build it (usually no options are needed):
2972@example
2973./configure
2974make
2975@end example
2976
2977Then type as root user:
2978@example
2979make install
2980@end example
2981to install QEMU in @file{/usr/local}.
2982
2983@node Windows
2984@section Windows
2985
2986@itemize
2987@item Install the current versions of MSYS and MinGW from
2988@url{http://www.mingw.org/}. You can find detailed installation
2989instructions in the download section and the FAQ.
2990
2991@item Download
2992the MinGW development library of SDL 1.2.x
2993(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
2994@url{http://www.libsdl.org}. Unpack it in a temporary place and
2995edit the @file{sdl-config} script so that it gives the
2996correct SDL directory when invoked.
2997
2998@item Install the MinGW version of zlib and make sure
2999@file{zlib.h} and @file{libz.dll.a} are in
3000MinGW's default header and linker search paths.
3001
3002@item Extract the current version of QEMU.
3003
3004@item Start the MSYS shell (file @file{msys.bat}).
3005
3006@item Change to the QEMU directory. Launch @file{./configure} and
3007@file{make}.  If you have problems using SDL, verify that
3008@file{sdl-config} can be launched from the MSYS command line.
3009
3010@item You can install QEMU in @file{Program Files/QEMU} by typing
3011@file{make install}. Don't forget to copy @file{SDL.dll} in
3012@file{Program Files/QEMU}.
3013
3014@end itemize
3015
3016@node Cross compilation for Windows with Linux
3017@section Cross compilation for Windows with Linux
3018
3019@itemize
3020@item
3021Install the MinGW cross compilation tools available at
3022@url{http://www.mingw.org/}.
3023
3024@item Download
3025the MinGW development library of SDL 1.2.x
3026(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
3027@url{http://www.libsdl.org}. Unpack it in a temporary place and
3028edit the @file{sdl-config} script so that it gives the
3029correct SDL directory when invoked.  Set up the @code{PATH} environment
3030variable so that @file{sdl-config} can be launched by
3031the QEMU configuration script.
3032
3033@item Install the MinGW version of zlib and make sure
3034@file{zlib.h} and @file{libz.dll.a} are in
3035MinGW's default header and linker search paths.
3036
3037@item
3038Configure QEMU for Windows cross compilation:
3039@example
3040PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
3041@end example
3042The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
3043MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
3044We set the @code{PATH} environment variable to ensure the MinGW version of @file{sdl-config} is used and
3045use --cross-prefix to specify the name of the cross compiler.
3046You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/QEMU}.
3047
3048Under Fedora Linux, you can run:
3049@example
3050yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
3051@end example
3052to get a suitable cross compilation environment.
3053
3054@item You can install QEMU in the installation directory by typing
3055@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
3056installation directory.
3057
3058@end itemize
3059
3060Wine can be used to launch the resulting qemu-system-i386.exe
3061and all other qemu-system-@var{target}.exe compiled for Win32.
3062
3063@node Mac OS X
3064@section Mac OS X
3065
3066System Requirements:
3067@itemize
3068@item Mac OS 10.5 or higher
3069@item The clang compiler shipped with Xcode 4.2 or higher,
3070or GCC 4.3 or higher
3071@end itemize
3072
3073Additional Requirements (install in order):
3074@enumerate
3075@item libffi: @uref{https://sourceware.org/libffi/}
3076@item gettext: @uref{http://www.gnu.org/software/gettext/}
3077@item glib: @uref{http://ftp.gnome.org/pub/GNOME/sources/glib/}
3078@item pkg-config: @uref{http://www.freedesktop.org/wiki/Software/pkg-config/}
3079@item autoconf: @uref{http://www.gnu.org/software/autoconf/autoconf.html}
3080@item automake: @uref{http://www.gnu.org/software/automake/}
3081@item pixman: @uref{http://www.pixman.org/}
3082@end enumerate
3083
3084* You may find it easiest to get these from a third-party packager
3085such as Homebrew, Macports, or Fink.
3086
3087After downloading the QEMU source code, double-click it to expand it.
3088
3089Then configure and make QEMU:
3090@example
3091./configure
3092make
3093@end example
3094
3095If you have a recent version of Mac OS X (OSX 10.7 or better
3096with Xcode 4.2 or better) we recommend building QEMU with the
3097default compiler provided by Apple, for your version of Mac OS X
3098(which will be 'clang'). The configure script will
3099automatically pick this.
3100
3101Note: If after the configure step you see a message like this:
3102@example
3103ERROR: Your compiler does not support the __thread specifier for
3104       Thread-Local Storage (TLS). Please upgrade to a version that does.
3105@end example
3106you may have to build your own version of gcc from source. Expect that to take
3107several hours. More information can be found here:
3108@uref{https://gcc.gnu.org/install/} @*
3109
3110These are some of the third party binaries of gcc available for download:
3111@itemize
3112@item Homebrew: @uref{http://brew.sh/}
3113@item @uref{https://www.litebeam.net/gcc/gcc_472.pkg}
3114@item @uref{http://www.macports.org/ports.php?by=name&substr=gcc}
3115@end itemize
3116
3117You can have several versions of GCC on your system. To specify a certain version,
3118use the --cc and --cxx options.
3119@example
3120./configure --cxx=<path of your c++ compiler> --cc=<path of your c compiler> <other options>
3121@end example
3122
3123@node Make targets
3124@section Make targets
3125
3126@table @code
3127
3128@item make
3129@item make all
3130Make everything which is typically needed.
3131
3132@item install
3133TODO
3134
3135@item install-doc
3136TODO
3137
3138@item make clean
3139Remove most files which were built during make.
3140
3141@item make distclean
3142Remove everything which was built during make.
3143
3144@item make dvi
3145@item make html
3146@item make info
3147@item make pdf
3148Create documentation in dvi, html, info or pdf format.
3149
3150@item make cscope
3151TODO
3152
3153@item make defconfig
3154(Re-)create some build configuration files.
3155User made changes will be overwritten.
3156
3157@item tar
3158@item tarbin
3159TODO
3160
3161@end table
3162
3163@node License
3164@appendix License
3165
3166QEMU is a trademark of Fabrice Bellard.
3167
3168QEMU is released under the GNU General Public License (TODO: add link).
3169Parts of QEMU have specific licenses, see file LICENSE.
3170
3171TODO (refer to file LICENSE, include it, include the GPL?)
3172
3173@node Index
3174@appendix Index
3175@menu
3176* Concept Index::
3177* Function Index::
3178* Keystroke Index::
3179* Program Index::
3180* Data Type Index::
3181* Variable Index::
3182@end menu
3183
3184@node Concept Index
3185@section Concept Index
3186This is the main index. Should we combine all keywords in one index? TODO
3187@printindex cp
3188
3189@node Function Index
3190@section Function Index
3191This index could be used for command line options and monitor functions.
3192@printindex fn
3193
3194@node Keystroke Index
3195@section Keystroke Index
3196
3197This is a list of all keystrokes which have a special function
3198in system emulation.
3199
3200@printindex ky
3201
3202@node Program Index
3203@section Program Index
3204@printindex pg
3205
3206@node Data Type Index
3207@section Data Type Index
3208
3209This index could be used for qdev device names and options.
3210
3211@printindex tp
3212
3213@node Variable Index
3214@section Variable Index
3215@printindex vr
3216
3217@bye
3218