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