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