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 2497128×64 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