1 \input texinfo @c -*- texinfo -*-
4 @settitle QEMU CPU Emulator User Documentation
7 @center @titlefont{QEMU CPU Emulator User Documentation}
16 QEMU is a FAST! processor emulator using dynamic translation to
17 achieve good emulation speed.
19 QEMU has two operating modes:
24 Full system emulation. In this mode, QEMU emulates a full system (for
25 example a PC), including a processor and various peripherials. It can
26 be used to launch different Operating Systems without rebooting the
27 PC or to debug system code.
30 User mode emulation (Linux host only). In this mode, QEMU can launch
31 Linux processes compiled for one CPU on another CPU. It can be used to
32 launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
33 to ease cross-compilation and cross-debugging.
37 QEMU can run without an host kernel driver and yet gives acceptable
38 performance. On an x86 host, if you want the highest performance for
39 the x86 target, the @emph{QEMU Accelerator Module} (KQEMU) allows QEMU
40 to reach near native performances. KQEMU is currently only supported
41 for an x86 Linux 2.4 or 2.6 host system, but more host OSes will be
42 supported in the future.
44 For system emulation, the following hardware targets are supported:
46 @item PC (x86 processor)
47 @item PREP (PowerPC processor)
48 @item PowerMac (PowerPC processor, in progress)
51 For user emulation, x86, PowerPC, ARM, and SPARC CPUs are supported.
55 If you want to compile QEMU yourself, see @ref{compilation}.
59 If a precompiled package is available for your distribution - you just
60 have to install it. Otherwise, see @ref{compilation}.
64 Download the experimental binary installer at
65 @url{http://www.freeoszoo.org/download.php}.
69 Download the experimental binary installer at
70 @url{http://www.freeoszoo.org/download.php}.
72 @chapter QEMU PC System emulator invocation
76 @c man begin DESCRIPTION
78 The QEMU System emulator simulates the
79 following PC peripherials:
83 i440FX host PCI bridge and PIIX3 PCI to ISA bridge
85 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
86 extensions (hardware level, including all non standard modes).
88 PS/2 mouse and keyboard
90 2 PCI IDE interfaces with hard disk and CD-ROM support
94 NE2000 PCI network adapters
101 QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
108 Download and uncompress the linux image (@file{linux.img}) and type:
114 Linux should boot and give you a prompt.
119 @c man begin SYNOPSIS
120 usage: qemu [options] [disk_image]
125 @var{disk_image} is a raw hard disk image for IDE hard disk 0.
131 Use @var{file} as floppy disk 0/1 image (@xref{disk_images}). You can
132 use the host floppy by using @file{/dev/fd0} as filename.
138 Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}).
141 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
142 @option{-cdrom} at the same time). You can use the host CD-ROM by
143 using @file{/dev/cdrom} as filename.
146 Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
150 Write to temporary files instead of disk image files. In this case,
151 the raw disk image you use is not written back. You can however force
152 the write back by pressing @key{C-a s} (@xref{disk_images}).
155 Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
159 Normally, QEMU uses SDL to display the VGA output. With this option,
160 you can totally disable graphical output so that QEMU is a simple
161 command line application. The emulated serial port is redirected on
162 the console. Therefore, you can still use QEMU to debug a Linux kernel
163 with a serial console.
167 Use keyboard layout @var{language} (for example @code{fr} for
168 French). This option is only needed where it is not easy to get raw PC
169 keycodes (e.g. on Macs or with some X11 servers). You don't need to
170 use it on PC/Linux or PC/Windows hosts.
172 The available layouts are:
174 ar de-ch es fo fr-ca hu ja mk no pt-br sv
175 da en-gb et fr fr-ch is lt nl pl ru th
176 de en-us fi fr-be hr it lv nl-be pt sl tr
179 The default is @code{en-us}.
183 The SB16 emulation is disabled by default as it may give problems with
184 Windows. You can enable it manually with this option.
187 Set the real time clock to local time (the default is to UTC
188 time). This option is needed to have correct date in MS-DOS or
192 Start in full screen.
195 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
205 Set TUN/TAP network init script [default=/etc/qemu-ifup]. This script
206 is launched to configure the host network interface (usually tun0)
207 corresponding to the virtual NE2000 card.
211 Set the mac address of the first interface (the format is
212 aa:bb:cc:dd:ee:ff in hexa). The mac address is incremented for each
213 new network interface.
216 Assumes @var{fd} talks to a tap/tun host network interface and use
217 it. Read @url{http://bellard.org/qemu/tetrinet.html} to have an
221 Use the user mode network stack. This is the default if no tun/tap
222 network init script is found.
225 When using the user mode network stack, activate a built-in TFTP
226 server. All filenames beginning with @var{prefix} can be downloaded
227 from the host to the guest using a TFTP client. The TFTP client on the
228 guest must be configured in binary mode (use the command @code{bin} of
229 the Unix TFTP client). The host IP address on the guest is as usual
233 When using the user mode network stack, activate a built-in SMB
234 server so that Windows OSes can access to the host files in @file{dir}
237 In the guest Windows OS, the line:
241 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
242 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
244 Then @file{dir} can be accessed in @file{\\smbserver\qemu}.
246 Note that a SAMBA server must be installed on the host OS in
247 @file{/usr/sbin/smbd}. QEMU was tested succesfully with smbd version
248 2.2.7a from the Red Hat 9.
250 @item -redir [tcp|udp]:host-port:[guest-host]:guest-port
252 When using the user mode network stack, redirect incoming TCP or UDP
253 connections to the host port @var{host-port} to the guest
254 @var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
255 is not specified, its value is 10.0.2.15 (default address given by the
256 built-in DHCP server).
258 For example, to redirect host X11 connection from screen 1 to guest
259 screen 0, use the following:
263 qemu -redir tcp:6001::6000 [...]
264 # this host xterm should open in the guest X11 server
268 To redirect telnet connections from host port 5555 to telnet port on
269 the guest, use the following:
273 qemu -redir tcp:5555::23 [...]
274 telnet localhost 5555
277 Then when you use on the host @code{telnet localhost 5555}, you
278 connect to the guest telnet server.
281 Use the dummy network stack: no packet will be received by the network
286 Linux boot specific. When using this options, you can use a given
287 Linux kernel without installing it in the disk image. It can be useful
288 for easier testing of various kernels.
292 @item -kernel bzImage
293 Use @var{bzImage} as kernel image.
295 @item -append cmdline
296 Use @var{cmdline} as kernel command line
299 Use @var{file} as initial ram disk.
303 Debug/Expert options:
307 Redirect the virtual serial port to host device @var{dev}. Available
313 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
317 [Unix only] standard input/output
319 The default device is @code{vc} in graphical mode and @code{stdio} in
322 This option can be used several times to simulate up to 4 serials
326 Redirect the monitor to host device @var{dev} (same devices as the
328 The default device is @code{vc} in graphical mode and @code{stdio} in
332 Wait gdb connection to port 1234 (@xref{gdb_usage}).
334 Change gdb connection port.
336 Do not start CPU at startup (you must type 'c' in the monitor).
338 Output log in /tmp/qemu.log
339 @item -hdachs c,h,s,[,t]
340 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
341 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
342 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
343 all thoses parameters. This option is useful for old MS-DOS disk
347 Disable the usage of the QEMU Accelerator module (KQEMU). QEMU will work as
348 usual but will be slower. This option can be useful to determine if
349 emulation problems are coming from KQEMU.
352 Simulate an ISA-only system (default is PCI system).
354 Simulate a standard VGA card with Bochs VBE extensions (default is
355 Cirrus Logic GD5446 PCI VGA)
357 Start right away with a saved state (@code{loadvm} in monitor)
366 During the graphical emulation, you can use the following keys:
372 Switch to virtual console 'n'. Standard console mappings are:
375 Target system display
383 Toggle mouse and keyboard grab.
386 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
387 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
389 During emulation, if you are using the @option{-nographic} option, use
390 @key{Ctrl-a h} to get terminal commands:
398 Save disk data back to file (if -snapshot)
400 Send break (magic sysrq in Linux)
402 Switch between console and monitor
411 @settitle QEMU System Emulator
414 The HTML documentation of QEMU for more precise information and Linux
415 user mode emulator invocation.
426 @section QEMU Accelerator Module
428 The QEMU Accelerator Module (KQEMU) is an optional part of QEMU currently only
429 available for Linux 2.4 or 2.6 x86 hosts. It enables QEMU to run x86
430 code much faster. Provided it is installed on your PC (see
431 @ref{kqemu_install}), QEMU will automatically use it.
433 WARNING: as with any alpha stage kernel driver, KQEMU may cause
434 arbitrary data loss on your PC, so you'd better backup your sensitive
435 data before using it.
437 When using KQEMU, QEMU will create a big hidden file containing the
438 RAM of the virtual machine. For best performance, it is important that
439 this file is kept in RAM and not on the hard disk. QEMU uses the
440 @file{/dev/shm} directory to create this file because @code{tmpfs} is
441 usually mounted on it (check with the shell command
442 @code{df}). Otherwise @file{/tmp} is used as fallback. You can use the
443 @var{QEMU_TMPDIR} shell variable to set a new directory for the QEMU
446 KQEMU has only been tested with Linux 2.4, Linux 2.6 and Windows 2000
447 as guest OSes. If your guest OS do not work with KQEMU, you can
448 dynamically disable KQEMU with the @option{-no-kqemu} option.
450 @section QEMU Monitor
452 The QEMU monitor is used to give complex commands to the QEMU
453 emulator. You can use it to:
458 Remove or insert removable medias images
459 (such as CD-ROM or floppies)
462 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
465 @item Inspect the VM state without an external debugger.
471 The following commands are available:
475 @item help or ? [cmd]
476 Show the help for all commands or just for command @var{cmd}.
479 Commit changes to the disk images (if -snapshot is used)
481 @item info subcommand
482 show various information about the system state
486 show the network state
488 show the block devices
490 show the cpu registers
492 show the command line history
498 @item eject [-f] device
499 Eject a removable media (use -f to force it).
501 @item change device filename
502 Change a removable media.
504 @item screendump filename
505 Save screen into PPM image @var{filename}.
507 @item log item1[,...]
508 Activate logging of the specified items to @file{/tmp/qemu.log}.
510 @item savevm filename
511 Save the whole virtual machine state to @var{filename}.
513 @item loadvm filename
514 Restore the whole virtual machine state from @var{filename}.
522 @item gdbserver [port]
523 Start gdbserver session (default port=1234)
526 Virtual memory dump starting at @var{addr}.
529 Physical memory dump starting at @var{addr}.
531 @var{fmt} is a format which tells the command how to format the
532 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
536 is the number of items to be dumped.
539 can be x (hexa), d (signed decimal), u (unsigned decimal), o (octal),
540 c (char) or i (asm instruction).
543 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
544 @code{h} or @code{w} can be specified with the @code{i} format to
545 respectively select 16 or 32 bit code instruction size.
552 Dump 10 instructions at the current instruction pointer:
557 0x90107065: lea 0x0(%esi,1),%esi
558 0x90107069: lea 0x0(%edi,1),%edi
560 0x90107071: jmp 0x90107080
568 Dump 80 16 bit values at the start of the video memory.
570 (qemu) xp/80hx 0xb8000
571 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
572 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
573 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
574 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
575 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
576 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
577 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
578 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
579 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
580 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
584 @item p or print/fmt expr
586 Print expression value. Only the @var{format} part of @var{fmt} is
591 Send @var{keys} to the emulator. Use @code{-} to press several keys
592 simultaneously. Example:
597 This command is useful to send keys that your graphical user interface
598 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
606 @subsection Integer expressions
608 The monitor understands integers expressions for every integer
609 argument. You can use register names to get the value of specifics
610 CPU registers by prefixing them with @emph{$}.
615 Since version 0.6.1, QEMU supports many disk image formats, including
616 growable disk images (their size increase as non empty sectors are
617 written), compressed and encrypted disk images.
619 @subsection Quick start for disk image creation
621 You can create a disk image with the command:
623 qemu-img create myimage.img mysize
625 where @var{myimage.img} is the disk image filename and @var{mysize} is its
626 size in kilobytes. You can add an @code{M} suffix to give the size in
627 megabytes and a @code{G} suffix for gigabytes.
629 @xref{qemu_img_invocation} for more information.
631 @subsection Snapshot mode
633 If you use the option @option{-snapshot}, all disk images are
634 considered as read only. When sectors in written, they are written in
635 a temporary file created in @file{/tmp}. You can however force the
636 write back to the raw disk images by using the @code{commit} monitor
637 command (or @key{C-a s} in the serial console).
639 @node qemu_img_invocation
640 @subsection @code{qemu-img} Invocation
642 @include qemu-img.texi
644 @section Network emulation
646 QEMU simulates up to 6 networks cards (NE2000 boards). Each card can
647 be connected to a specific host network interface.
649 @subsection Using tun/tap network interface
651 This is the standard way to emulate network. QEMU adds a virtual
652 network device on your host (called @code{tun0}), and you can then
653 configure it as if it was a real ethernet card.
655 As an example, you can download the @file{linux-test-xxx.tar.gz}
656 archive and copy the script @file{qemu-ifup} in @file{/etc} and
657 configure properly @code{sudo} so that the command @code{ifconfig}
658 contained in @file{qemu-ifup} can be executed as root. You must verify
659 that your host kernel supports the TUN/TAP network interfaces: the
660 device @file{/dev/net/tun} must be present.
662 See @ref{direct_linux_boot} to have an example of network use with a
665 @subsection Using the user mode network stack
667 By using the option @option{-user-net} or if you have no tun/tap init
668 script, QEMU uses a completely user mode network stack (you don't need
669 root priviledge to use the virtual network). The virtual network
670 configuration is the following:
674 QEMU Virtual Machine <------> Firewall/DHCP server <-----> Internet
675 (10.0.2.x) | (10.0.2.2)
677 ----> DNS server (10.0.2.3)
679 ----> SMB server (10.0.2.4)
682 The QEMU VM behaves as if it was behind a firewall which blocks all
683 incoming connections. You can use a DHCP client to automatically
684 configure the network in the QEMU VM.
686 In order to check that the user mode network is working, you can ping
687 the address 10.0.2.2 and verify that you got an address in the range
688 10.0.2.x from the QEMU virtual DHCP server.
690 Note that @code{ping} is not supported reliably to the internet as it
691 would require root priviledges. It means you can only ping the local
694 When using the built-in TFTP server, the router is also the TFTP
697 When using the @option{-redir} option, TCP or UDP connections can be
698 redirected from the host to the guest. It allows for example to
699 redirect X11, telnet or SSH connections.
701 @node direct_linux_boot
702 @section Direct Linux Boot
704 This section explains how to launch a Linux kernel inside QEMU without
705 having to make a full bootable image. It is very useful for fast Linux
706 kernel testing. The QEMU network configuration is also explained.
710 Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
711 kernel and a disk image.
713 @item Optional: If you want network support (for example to launch X11 examples), you
714 must copy the script @file{qemu-ifup} in @file{/etc} and configure
715 properly @code{sudo} so that the command @code{ifconfig} contained in
716 @file{qemu-ifup} can be executed as root. You must verify that your host
717 kernel supports the TUN/TAP network interfaces: the device
718 @file{/dev/net/tun} must be present.
720 When network is enabled, there is a virtual network connection between
721 the host kernel and the emulated kernel. The emulated kernel is seen
722 from the host kernel at IP address 172.20.0.2 and the host kernel is
723 seen from the emulated kernel at IP address 172.20.0.1.
725 @item Launch @code{qemu.sh}. You should have the following output:
729 Connected to host network interface: tun0
730 Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
731 BIOS-provided physical RAM map:
732 BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
733 BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
734 32MB LOWMEM available.
735 On node 0 totalpages: 8192
739 Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0
740 ide_setup: ide2=noprobe
741 ide_setup: ide3=noprobe
742 ide_setup: ide4=noprobe
743 ide_setup: ide5=noprobe
745 Detected 2399.621 MHz processor.
746 Console: colour EGA 80x25
747 Calibrating delay loop... 4744.80 BogoMIPS
748 Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem)
749 Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
750 Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
751 Mount cache hash table entries: 512 (order: 0, 4096 bytes)
752 Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
753 Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
754 CPU: Intel Pentium Pro stepping 03
755 Checking 'hlt' instruction... OK.
756 POSIX conformance testing by UNIFIX
757 Linux NET4.0 for Linux 2.4
758 Based upon Swansea University Computer Society NET3.039
759 Initializing RT netlink socket
762 Journalled Block Device driver loaded
763 Detected PS/2 Mouse Port.
764 pty: 256 Unix98 ptys configured
765 Serial driver version 5.05c (2001-07-08) with no serial options enabled
766 ttyS00 at 0x03f8 (irq = 4) is a 16450
767 ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com)
768 Last modified Nov 1, 2000 by Paul Gortmaker
769 NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
770 eth0: NE2000 found at 0x300, using IRQ 9.
771 RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
772 Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
773 ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
774 hda: QEMU HARDDISK, ATA DISK drive
775 ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
776 hda: attached ide-disk driver.
777 hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
780 Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
781 NET4: Linux TCP/IP 1.0 for NET4.0
782 IP Protocols: ICMP, UDP, TCP, IGMP
783 IP: routing cache hash table of 512 buckets, 4Kbytes
784 TCP: Hash tables configured (established 2048 bind 4096)
785 NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
786 EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
787 VFS: Mounted root (ext2 filesystem).
788 Freeing unused kernel memory: 64k freed
790 Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
792 QEMU Linux test distribution (based on Redhat 9)
794 Type 'exit' to halt the system
800 Then you can play with the kernel inside the virtual serial console. You
801 can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help
802 about the keys you can type inside the virtual serial console. In
803 particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as
807 If the network is enabled, launch the script @file{/etc/linuxrc} in the
808 emulator (don't forget the leading dot):
813 Then enable X11 connections on your PC from the emulated Linux:
818 You can now launch @file{xterm} or @file{xlogo} and verify that you have
819 a real Virtual Linux system !
826 A 2.5.74 kernel is also included in the archive. Just
827 replace the bzImage in qemu.sh to try it.
830 In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
831 qemu. qemu will automatically exit when the Linux shutdown is done.
834 You can boot slightly faster by disabling the probe of non present IDE
835 interfaces. To do so, add the following options on the kernel command
838 ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
842 The example disk image is a modified version of the one made by Kevin
843 Lawton for the plex86 Project (@url{www.plex86.org}).
850 QEMU has a primitive support to work with gdb, so that you can do
851 'Ctrl-C' while the virtual machine is running and inspect its state.
853 In order to use gdb, launch qemu with the '-s' option. It will wait for a
856 > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
857 Connected to host network interface: tun0
858 Waiting gdb connection on port 1234
861 Then launch gdb on the 'vmlinux' executable:
866 In gdb, connect to QEMU:
868 (gdb) target remote localhost:1234
871 Then you can use gdb normally. For example, type 'c' to launch the kernel:
876 Here are some useful tips in order to use gdb on system code:
880 Use @code{info reg} to display all the CPU registers.
882 Use @code{x/10i $eip} to display the code at the PC position.
884 Use @code{set architecture i8086} to dump 16 bit code. Then use
885 @code{x/10i $cs*16+*eip} to dump the code at the PC position.
888 @section Target OS specific information
892 To have access to SVGA graphic modes under X11, use the @code{vesa} or
893 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
894 color depth in the guest and the host OS.
896 When using a 2.6 guest Linux kernel, you should add the option
897 @code{clock=pit} on the kernel command line because the 2.6 Linux
898 kernels make very strict real time clock checks by default that QEMU
899 cannot simulate exactly.
901 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
902 not activated because QEMU is slower with this patch. The QEMU
903 Accelerator Module is also much slower in this case. Earlier Fedora
904 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this
905 patch by default. Newer kernels don't have it.
909 If you have a slow host, using Windows 95 is better as it gives the
910 best speed. Windows 2000 is also a good choice.
912 @subsubsection SVGA graphic modes support
914 QEMU emulates a Cirrus Logic GD5446 Video
915 card. All Windows versions starting from Windows 95 should recognize
916 and use this graphic card. For optimal performances, use 16 bit color
917 depth in the guest and the host OS.
919 @subsubsection CPU usage reduction
921 Windows 9x does not correctly use the CPU HLT
922 instruction. The result is that it takes host CPU cycles even when
923 idle. You can install the utility from
924 @url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
925 problem. Note that no such tool is needed for NT, 2000 or XP.
927 @subsubsection Windows 2000 disk full problems
929 Currently (release 0.6.0) QEMU has a bug which gives a @code{disk
930 full} error during installation of some releases of Windows 2000. The
931 workaround is to stop QEMU as soon as you notice that your disk image
932 size is growing too fast (monitor it with @code{ls -ls}). Then
933 relaunch QEMU to continue the installation. If you still experience
934 the problem, relaunch QEMU again.
936 Future QEMU releases are likely to correct this bug.
938 @subsubsection Windows XP security problems
940 Some releases of Windows XP install correctly but give a security
943 A problem is preventing Windows from accurately checking the
944 license for this computer. Error code: 0x800703e6.
946 The only known workaround is to boot in Safe mode
947 without networking support.
949 Future QEMU releases are likely to correct this bug.
951 @subsection MS-DOS and FreeDOS
953 @subsubsection CPU usage reduction
955 DOS does not correctly use the CPU HLT instruction. The result is that
956 it takes host CPU cycles even when idle. You can install the utility
957 from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
960 @chapter QEMU PowerPC System emulator invocation
962 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
963 or PowerMac PowerPC system.
965 QEMU emulates the following PowerMac peripherials:
971 PCI VGA compatible card with VESA Bochs Extensions
973 2 PMAC IDE interfaces with hard disk and CD-ROM support
979 VIA-CUDA with ADB keyboard and mouse.
982 QEMU emulates the following PREP peripherials:
988 PCI VGA compatible card with VESA Bochs Extensions
990 2 IDE interfaces with hard disk and CD-ROM support
994 NE2000 network adapters
998 PREP Non Volatile RAM
1000 PC compatible keyboard and mouse.
1003 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1004 @url{http://site.voila.fr/jmayer/OpenHackWare/index.htm}.
1006 You can read the qemu PC system emulation chapter to have more
1007 informations about QEMU usage.
1009 @c man begin OPTIONS
1011 The following options are specific to the PowerPC emulation:
1016 Simulate a PREP system (default is PowerMAC)
1018 @item -g WxH[xDEPTH]
1020 Set the initial VGA graphic mode. The default is 800x600x15.
1027 More information is available at
1028 @url{http://jocelyn.mayer.free.fr/qemu-ppc/}.
1030 @chapter Sparc System emulator invocation
1032 Use the executable @file{qemu-system-sparc} to simulate a JavaStation
1033 (sun4m architecture). The emulation is far from complete.
1035 QEMU emulates the following sun4m peripherials:
1043 Lance (Am7990) Ethernet
1045 Non Volatile RAM M48T08
1047 Slave I/O: timers, interrupt controllers, Zilog serial ports
1050 QEMU uses the Proll, a PROM replacement available at
1051 @url{http://people.redhat.com/zaitcev/linux/}.
1053 @chapter QEMU User space emulator invocation
1055 @section Quick Start
1057 In order to launch a Linux process, QEMU needs the process executable
1058 itself and all the target (x86) dynamic libraries used by it.
1062 @item On x86, you can just try to launch any process by using the native
1066 qemu-i386 -L / /bin/ls
1069 @code{-L /} tells that the x86 dynamic linker must be searched with a
1072 @item Since QEMU is also a linux process, you can launch qemu with qemu (NOTE: you can only do that if you compiled QEMU from the sources):
1075 qemu-i386 -L / qemu-i386 -L / /bin/ls
1078 @item On non x86 CPUs, you need first to download at least an x86 glibc
1079 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
1080 @code{LD_LIBRARY_PATH} is not set:
1083 unset LD_LIBRARY_PATH
1086 Then you can launch the precompiled @file{ls} x86 executable:
1089 qemu-i386 tests/i386/ls
1091 You can look at @file{qemu-binfmt-conf.sh} so that
1092 QEMU is automatically launched by the Linux kernel when you try to
1093 launch x86 executables. It requires the @code{binfmt_misc} module in the
1096 @item The x86 version of QEMU is also included. You can try weird things such as:
1098 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1103 @section Wine launch
1107 @item Ensure that you have a working QEMU with the x86 glibc
1108 distribution (see previous section). In order to verify it, you must be
1112 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1115 @item Download the binary x86 Wine install
1116 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
1118 @item Configure Wine on your account. Look at the provided script
1119 @file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous
1120 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
1122 @item Then you can try the example @file{putty.exe}:
1125 qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
1130 @section Command line options
1133 usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
1140 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
1142 Set the x86 stack size in bytes (default=524288)
1149 Activate log (logfile=/tmp/qemu.log)
1151 Act as if the host page size was 'pagesize' bytes
1155 @chapter Compilation from the sources
1159 @subsection Compilation
1161 First you must decompress the sources:
1164 tar zxvf qemu-x.y.z.tar.gz
1168 If you want to use the optional QEMU Accelerator Module, then download
1169 it and install it in qemu-x.y.z/:
1171 tar zxvf /tmp/kqemu-x.y.z.tar.gz
1174 Then you configure QEMU and build it (usually no options are needed):
1180 Then type as root user:
1184 to install QEMU in @file{/usr/local}.
1187 @subsection QEMU Accelerator Installation
1189 If you use x86 Linux, the compilation of the QEMU Accelerator Kernel
1190 Module (KQEMU) is automatically activated provided you have the
1191 necessary kernel headers. If nonetheless the compilation fails, you
1192 can disable its compilation with the @option{--disable-kqemu} option.
1194 If you are using a 2.6 host kernel, then all the necessary kernel
1195 headers should be already installed. If you are using a 2.4 kernel,
1196 then you should verify that properly configured kernel sources are
1197 installed and compiled. On a Redhat 9 distribution for example, the
1198 following must be done:
1200 1) Install the kernel-source-xxx package
1201 2) cd /usr/src/linux-xxx
1203 4) Copy /boot/config-vvv in .config (use uname -r to know your configuration name 'vvv')
1204 5) Edit the Makefile to change the EXTRAVERSION line to match your
1205 current configuration name:
1206 EXTRAVERSION = -custom
1208 EXTRAVERSION = -8 # This is an example, it can be -8smp too
1209 5) make menuconfig # Just save the configuration
1213 The installation of KQEMU is not fully automatic because it is highly
1214 distribution dependent. When launching
1219 KQEMU is installed in /lib/modules/@var{kernel_version}/misc. The
1220 device @file{/dev/kqemu} is created with read/write access rights for
1221 everyone. If you fear security issues, you can restrict the access
1222 rights of @file{/dev/kqemu}.
1224 If you want that KQEMU is installed automatically at boot time, you can add
1227 # Load the KQEMU kernel module
1228 /sbin/modprobe kqemu
1231 in @file{/etc/rc.d/rc.local}.
1233 If your distribution uses udev (like Fedora), the @file{/dev/kqemu} is
1234 not created automatically (yet) at every reboot. You can add the
1235 following in @file{/etc/rc.d/rc.local}:
1238 # Create the KQEMU device
1239 mknod /dev/kqemu c 250 0
1240 chmod 666 /dev/kqemu
1243 @subsection Tested tool versions
1245 In order to compile QEMU succesfully, it is very important that you
1246 have the right tools. The most important one is gcc. I cannot guaranty
1247 that QEMU works if you do not use a tested gcc version. Look at
1248 'configure' and 'Makefile' if you want to make a different gcc
1252 host gcc binutils glibc linux distribution
1253 ----------------------------------------------------------------------
1254 x86 3.2 2.13.2 2.1.3 2.4.18
1255 2.96 2.11.93.0.2 2.2.5 2.4.18 Red Hat 7.3
1256 3.2.2 2.13.90.0.18 2.3.2 2.4.20 Red Hat 9
1258 PowerPC 3.3 [4] 2.13.90.0.18 2.3.1 2.4.20briq
1261 Alpha 3.3 [1] 2.14.90.0.4 2.2.5 2.2.20 [2] Debian 3.0
1263 Sparc32 2.95.4 2.12.90.0.1 2.2.5 2.4.18 Debian 3.0
1265 ARM 2.95.4 2.12.90.0.1 2.2.5 2.4.9 [3] Debian 3.0
1267 [1] On Alpha, QEMU needs the gcc 'visibility' attribute only available
1268 for gcc version >= 3.3.
1269 [2] Linux >= 2.4.20 is necessary for precise exception support
1271 [3] 2.4.9-ac10-rmk2-np1-cerf2
1273 [4] gcc 2.95.x generates invalid code when using too many register
1274 variables. You must use gcc 3.x on PowerPC.
1280 @item Install the current versions of MSYS and MinGW from
1281 @url{http://www.mingw.org/}. You can find detailed installation
1282 instructions in the download section and the FAQ.
1285 the MinGW development library of SDL 1.2.x
1286 (@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
1287 @url{http://www.libsdl.org}. Unpack it in a temporary place, and
1288 unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
1289 directory. Edit the @file{sdl-config} script so that it gives the
1290 correct SDL directory when invoked.
1292 @item Extract the current version of QEMU.
1294 @item Start the MSYS shell (file @file{msys.bat}).
1296 @item Change to the QEMU directory. Launch @file{./configure} and
1297 @file{make}. If you have problems using SDL, verify that
1298 @file{sdl-config} can be launched from the MSYS command line.
1300 @item You can install QEMU in @file{Program Files/Qemu} by typing
1301 @file{make install}. Don't forget to copy @file{SDL.dll} in
1302 @file{Program Files/Qemu}.
1306 @section Cross compilation for Windows with Linux
1310 Install the MinGW cross compilation tools available at
1311 @url{http://www.mingw.org/}.
1314 Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
1315 unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
1316 variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
1317 the QEMU configuration script.
1320 Configure QEMU for Windows cross compilation:
1322 ./configure --enable-mingw32
1324 If necessary, you can change the cross-prefix according to the prefix
1325 choosen for the MinGW tools with --cross-prefix. You can also use
1326 --prefix to set the Win32 install path.
1328 @item You can install QEMU in the installation directory by typing
1329 @file{make install}. Don't forget to copy @file{SDL.dll} in the
1330 installation directory.
1334 Note: Currently, Wine does not seem able to launch
1339 The Mac OS X patches are not fully merged in QEMU, so you should look
1340 at the QEMU mailing list archive to have all the necessary