\input texinfo @c -*- texinfo -*-
+@iftex
@settitle QEMU CPU Emulator Reference Documentation
@titlepage
@sp 7
@center @titlefont{QEMU CPU Emulator Reference Documentation}
@sp 3
@end titlepage
+@end iftex
@chapter Introduction
CPUs.
QEMU has two operating modes:
-@itemize
-@item User mode emulation. In this mode, QEMU can launch Linux processes
+
+@itemize @minus
+
+@item
+User mode emulation. In this mode, QEMU can launch Linux processes
compiled for one CPU on another CPU. Linux system calls are converted
because of endianness and 32/64 bit mismatches. The Wine Windows API
emulator (@url{http://www.winehq.org}) and the DOSEMU DOS emulator
-(@url{www.dosemu.org}) are the main targets for QEMU.
+(@url{http://www.dosemu.org}) are the main targets for QEMU.
-@item Full system emulation. In this mode, QEMU emulates a full
+@item
+Full system emulation. In this mode, QEMU emulates a full
system, including a processor and various peripherials. Currently, it
is only used to launch an x86 Linux kernel on an x86 Linux system. It
enables easier testing and debugging of system code. It can also be
QEMU full system emulation features:
@itemize
-@item Using mmap() system calls to simulate the MMU
+@item QEMU can either use a full software MMU for maximum portability or use the host system call mmap() to simulate the target MMU.
@end itemize
@section x86 emulation
10 byte @code{long double}s of x86 for floating point emulation to get
maximum performances.
-@item Full system emulation only works if no data are mapped above the virtual address
-0xc0000000 (yet).
-
-@item Some priviledged instructions or behaviors are missing. Only the ones
-needed for proper Linux kernel operation are emulated.
-
-@item No memory separation between the kernel and the user processes is done.
-It will be implemented very soon.
+@item Some priviledged instructions or behaviors are missing, especially for segment protection testing (yet).
@end itemize
@end itemize
+@section SPARC emulation
+
+The SPARC emulation is currently in development.
+
+@chapter Installation
+
+If you want to compile QEMU, please read the @file{README} which gives
+the related information. Otherwise just download the binary
+distribution (@file{qemu-XXX-i386.tar.gz}) and untar it as root in
+@file{/}:
+
+@example
+su
+cd /
+tar zxvf /tmp/qemu-XXX-i386.tar.gz
+@end example
+
@chapter QEMU User space emulator invocation
@section Quick Start
-If you need to compile QEMU, please read the @file{README} which gives
-the related information.
-
In order to launch a Linux process, QEMU needs the process executable
itself and all the target (x86) dynamic libraries used by it.
libraries:
@example
-qemu -L / /bin/ls
+qemu-i386 -L / /bin/ls
@end example
@code{-L /} tells that the x86 dynamic linker must be searched with a
@file{/} prefix.
-@item Since QEMU is also a linux process, you can launch qemu with qemu:
+@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):
@example
-qemu -L / qemu -L / /bin/ls
+qemu-i386 -L / qemu-i386 -L / /bin/ls
@end example
@item On non x86 CPUs, you need first to download at least an x86 glibc
-(@file{qemu-XXX-i386-glibc21.tar.gz} on the QEMU web page). Ensure that
+(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
@code{LD_LIBRARY_PATH} is not set:
@example
Then you can launch the precompiled @file{ls} x86 executable:
@example
-qemu /usr/local/qemu-i386/bin/ls-i386
+qemu-i386 tests/i386/ls
@end example
-You can look at @file{/usr/local/qemu-i386/bin/qemu-conf.sh} so that
+You can look at @file{qemu-binfmt-conf.sh} so that
QEMU is automatically launched by the Linux kernel when you try to
launch x86 executables. It requires the @code{binfmt_misc} module in the
Linux kernel.
@item The x86 version of QEMU is also included. You can try weird things such as:
@example
-qemu /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
+qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
@end example
@end itemize
able to do:
@example
-qemu /usr/local/qemu-i386/bin/ls-i386
+qemu-i386 /usr/local/qemu-i386/bin/ls-i386
@end example
@item Download the binary x86 Wine install
@item Then you can try the example @file{putty.exe}:
@example
-qemu /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
+qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
@end example
@end itemize
@section Command line options
@example
-usage: qemu [-h] [-d] [-L path] [-s size] program [arguments...]
+usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
@end example
@table @option
@chapter QEMU System emulator invocation
+@section Introduction
+
+@c man begin DESCRIPTION
+
+The QEMU System emulator simulates a complete PC. It can either boot
+directly a Linux kernel (without any BIOS or boot loader) or boot like a
+real PC with the included BIOS.
+
+In order to meet specific user needs, two versions of QEMU are
+available:
+
+@enumerate
+
+@item
+@code{qemu-fast} uses the host Memory Management Unit (MMU) to simulate
+the x86 MMU. It is @emph{fast} but has limitations because the whole 4 GB
+address space cannot be used and some memory mapped peripherials
+cannot be emulated accurately yet. Therefore, a specific Linux kernel
+must be used (@xref{linux_compile}).
+
+@item
+@code{qemu} uses a software MMU. It is about @emph{two times
+slower} but gives a more accurate emulation.
+
+@end enumerate
+
+QEMU emulates the following PC peripherials:
+
+@itemize @minus
+@item
+VGA (hardware level, including all non standard modes)
+@item
+PS/2 mouse and keyboard
+@item
+2 IDE interfaces with hard disk and CD-ROM support
+@item
+NE2000 network adapter (port=0x300, irq=9)
+@item
+Serial port
+@item
+Soundblaster 16 card
+@item
+PIC (interrupt controler)
+@item
+PIT (timers)
+@item
+CMOS memory
+@end itemize
+
+@c man end
+
@section Quick Start
-This section explains how to launch a Linux kernel inside QEMU.
+Download and uncompress the linux image (@file{linux.img}) and type:
+
+@example
+qemu linux.img
+@end example
+
+Linux should boot and give you a prompt.
+
+@section Direct Linux Boot and Network emulation
+
+This section explains how to launch a Linux kernel inside QEMU without
+having to make a full bootable image. It is very useful for fast Linux
+kernel testing. The QEMU network configuration is also explained.
@enumerate
@item
-Download the archive @file{vl-test-xxx.tar.gz} containing a Linux kernel
-and an initrd (initial Ram Disk). The archive also contains a
-precompiled version of @file{vl}, the QEMU System emulator.
+Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
+kernel and a disk image.
@item Optional: If you want network support (for example to launch X11 examples), you
-must copy the script @file{vl-ifup} in @file{/etc} and configure
+must copy the script @file{qemu-ifup} in @file{/etc} and configure
properly @code{sudo} so that the command @code{ifconfig} contained in
-@file{vl-ifup} can be executed as root. You must verify that your host
+@file{qemu-ifup} can be executed as root. You must verify that your host
kernel supports the TUN/TAP network interfaces: the device
@file{/dev/net/tun} must be present.
from the host kernel at IP address 172.20.0.2 and the host kernel is
seen from the emulated kernel at IP address 172.20.0.1.
-@item Launch @code{vl.sh}. You should have the following output:
+@item Launch @code{qemu.sh}. You should have the following output:
@example
-> ./vl.sh
-connected to host network interface: tun0
-Uncompressing Linux... Ok, booting the kernel.
-Linux version 2.4.20 (bellard@voyager) (gcc version 2.95.2 20000220 (Debian GNU/Linux)) #42 Wed Jun 25 14:16:12 CEST 2003
+> ./qemu.sh
+Connected to host network interface: tun0
+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
BIOS-provided physical RAM map:
- BIOS-88: 0000000000000000 - 000000000009f000 (usable)
- BIOS-88: 0000000000100000 - 0000000002000000 (usable)
+ BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
+ BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
32MB LOWMEM available.
On node 0 totalpages: 8192
zone(0): 4096 pages.
zone(1): 4096 pages.
zone(2): 0 pages.
-Kernel command line: root=/dev/ram ramdisk_size=6144
+Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0
+ide_setup: ide2=noprobe
+ide_setup: ide3=noprobe
+ide_setup: ide4=noprobe
+ide_setup: ide5=noprobe
Initializing CPU#0
-Detected 501.785 MHz processor.
-Calibrating delay loop... 973.20 BogoMIPS
-Memory: 24776k/32768k available (725k kernel code, 7604k reserved, 151k data, 48k init, 0k highmem)
+Detected 2399.621 MHz processor.
+Console: colour EGA 80x25
+Calibrating delay loop... 4744.80 BogoMIPS
+Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem)
Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
-Mount-cache hash table entries: 512 (order: 0, 4096 bytes)
+Mount cache hash table entries: 512 (order: 0, 4096 bytes)
Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
CPU: Intel Pentium Pro stepping 03
Initializing RT netlink socket
apm: BIOS not found.
Starting kswapd
+Journalled Block Device driver loaded
+Detected PS/2 Mouse Port.
pty: 256 Unix98 ptys configured
Serial driver version 5.05c (2001-07-08) with no serial options enabled
ttyS00 at 0x03f8 (irq = 4) is a 16450
Last modified Nov 1, 2000 by Paul Gortmaker
NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
eth0: NE2000 found at 0x300, using IRQ 9.
-RAMDISK driver initialized: 16 RAM disks of 6144K size 1024 blocksize
+RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
+Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
+ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
+hda: QEMU HARDDISK, ATA DISK drive
+ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
+hda: attached ide-disk driver.
+hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
+Partition check:
+ hda:
+Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
NET4: Linux TCP/IP 1.0 for NET4.0
IP Protocols: ICMP, UDP, TCP, IGMP
IP: routing cache hash table of 512 buckets, 4Kbytes
-TCP: Hash tables configured (established 2048 bind 2048)
+TCP: Hash tables configured (established 2048 bind 4096)
NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
-RAMDISK: ext2 filesystem found at block 0
-RAMDISK: Loading 6144 blocks [1 disk] into ram disk... done.
-Freeing initrd memory: 6144k freed
+EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
VFS: Mounted root (ext2 filesystem).
-Freeing unused kernel memory: 48k freed
-sh: can't access tty; job control turned off
-#
+Freeing unused kernel memory: 64k freed
+
+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
+
+QEMU Linux test distribution (based on Redhat 9)
+
+Type 'exit' to halt the system
+
+sh-2.05b#
@end example
@item
NOTES:
@enumerate
@item
-A 2.5.66 kernel is also included in the vl-test archive. Just
-replace the bzImage in vl.sh to try it.
+A 2.5.74 kernel is also included in the archive. Just
+replace the bzImage in qemu.sh to try it.
@item
-vl creates a temporary file in @var{$VLTMPDIR} (@file{/tmp} is the
+qemu creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the
default) containing all the simulated PC memory. If possible, try to use
a temporary directory using the tmpfs filesystem to avoid too many
unnecessary disk accesses.
@item
-The example initrd is a modified version of the one made by Kevin
+In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
+qemu. qemu will automatically exit when the Linux shutdown is done.
+
+@item
+You can boot slightly faster by disabling the probe of non present IDE
+interfaces. To do so, add the following options on the kernel command
+line:
+@example
+ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
+@end example
+
+@item
+The example disk image is a modified version of the one made by Kevin
Lawton for the plex86 Project (@url{www.plex86.org}).
@end enumerate
-@section Kernel Compilation
+@section Invocation
+
+@example
+@c man begin SYNOPSIS
+usage: qemu [options] [disk_image]
+@c man end
+@end example
+
+@c man begin OPTIONS
+@var{disk_image} is a raw hard disk image for IDE hard disk 0.
-You can use any Linux kernel within QEMU provided it is mapped at
-address 0x90000000 (the default is 0xc0000000). You must modify only two
-lines in the kernel source:
+General options:
+@table @option
+@item -fda file
+@item -fdb file
+Use @var{file} as floppy disk 0/1 image (@xref{disk_images}).
+
+@item -hda file
+@item -hdb file
+@item -hdc file
+@item -hdd file
+Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}).
+
+@item -cdrom file
+Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
+@option{-cdrom} at the same time).
+
+@item -boot [a|b|c|d]
+Boot on floppy (a, b), hard disk (c) or CD-ROM (d). Hard disk boot is
+the default.
+
+@item -snapshot
+Write to temporary files instead of disk image files. In this case,
+the raw disk image you use is not written back. You can however force
+the write back by pressing @key{C-a s} (@xref{disk_images}).
+
+@item -m megs
+Set virtual RAM size to @var{megs} megabytes.
+
+@item -n script
+Set network init script [default=/etc/qemu-ifup]. This script is
+launched to configure the host network interface (usually tun0)
+corresponding to the virtual NE2000 card.
+
+@item -initrd file
+Use @var{file} as initial ram disk.
+
+@item -tun-fd fd
+Assumes @var{fd} talks to tap/tun and use it. Read
+@url{http://bellard.org/qemu/tetrinet.html} to have an example of its
+use.
+
+@item -nographic
+
+Normally, QEMU uses SDL to display the VGA output. With this option,
+you can totally disable graphical output so that QEMU is a simple
+command line application. The emulated serial port is redirected on
+the console. Therefore, you can still use QEMU to debug a Linux kernel
+with a serial console.
+
+@end table
-In asm/page.h, replace
+Linux boot specific (does not require a full PC boot with a BIOS):
+@table @option
+
+@item -kernel bzImage
+Use @var{bzImage} as kernel image.
+
+@item -append cmdline
+Use @var{cmdline} as kernel command line
+
+@item -initrd file
+Use @var{file} as initial ram disk.
+
+@end table
+
+Debug options:
+@table @option
+@item -s
+Wait gdb connection to port 1234 (@xref{gdb_usage}).
+@item -p port
+Change gdb connection port.
+@item -d
+Output log in /tmp/qemu.log
+@end table
+
+During emulation, use @key{C-a h} to get terminal commands:
+
+@table @key
+@item C-a h
+Print this help
+@item C-a x
+Exit emulatior
+@item C-a s
+Save disk data back to file (if -snapshot)
+@item C-a b
+Send break (magic sysrq)
+@item C-a C-a
+Send C-a
+@end table
+@c man end
+
+@ignore
+
+@setfilename qemu
+@settitle QEMU System Emulator
+
+@c man begin SEEALSO
+The HTML documentation of QEMU for more precise information and Linux
+user mode emulator invocation.
+@c man end
+
+@c man begin AUTHOR
+Fabrice Bellard
+@c man end
+
+@end ignore
+
+@end ignore
+@node disk_images
+@section Disk Images
+
+@subsection Raw disk images
+
+The disk images can simply be raw images of the hard disk. You can
+create them with the command:
+@example
+dd if=/dev/zero of=myimage bs=1024 count=mysize
+@end example
+where @var{myimage} is the image filename and @var{mysize} is its size
+in kilobytes.
+
+@subsection Snapshot mode
+
+If you use the option @option{-snapshot}, all disk images are
+considered as read only. When sectors in written, they are written in
+a temporary file created in @file{/tmp}. You can however force the
+write back to the raw disk images by pressing @key{C-a s}.
+
+NOTE: The snapshot mode only works with raw disk images.
+
+@subsection Copy On Write disk images
+
+QEMU also supports user mode Linux
+(@url{http://user-mode-linux.sourceforge.net/}) Copy On Write (COW)
+disk images. The COW disk images are much smaller than normal images
+as they store only modified sectors. They also permit the use of the
+same disk image template for many users.
+
+To create a COW disk images, use the command:
+
+@example
+qemu-mkcow -f myrawimage.bin mycowimage.cow
+@end example
+
+@file{myrawimage.bin} is a raw image you want to use as original disk
+image. It will never be written to.
+
+@file{mycowimage.cow} is the COW disk image which is created by
+@code{qemu-mkcow}. You can use it directly with the @option{-hdx}
+options. You must not modify the original raw disk image if you use
+COW images, as COW images only store the modified sectors from the raw
+disk image. QEMU stores the original raw disk image name and its
+modified time in the COW disk image so that chances of mistakes are
+reduced.
+
+If the raw disk image is not read-only, by pressing @key{C-a s} you
+can flush the COW disk image back into the raw disk image, as in
+snapshot mode.
+
+COW disk images can also be created without a corresponding raw disk
+image. It is useful to have a big initial virtual disk image without
+using much disk space. Use:
+
+@example
+qemu-mkcow mycowimage.cow 1024
+@end example
+
+to create a 1 gigabyte empty COW disk image.
+
+NOTES:
+@enumerate
+@item
+COW disk images must be created on file systems supporting
+@emph{holes} such as ext2 or ext3.
+@item
+Since holes are used, the displayed size of the COW disk image is not
+the real one. To know it, use the @code{ls -ls} command.
+@end enumerate
+
+@node linux_compile
+@section Linux Kernel Compilation
+
+You can use any linux kernel with QEMU. However, if you want to use
+@code{qemu-fast} to get maximum performances, you should make the
+following changes to the Linux kernel (only 2.4.x and 2.5.x were
+tested):
+
+@enumerate
+@item
+The kernel must be mapped at 0x90000000 (the default is
+0xc0000000). You must modify only two lines in the kernel source:
+
+In @file{include/asm/page.h}, replace
@example
#define __PAGE_OFFSET (0xc0000000)
@end example
#define __PAGE_OFFSET (0x90000000)
@end example
-And in arch/i386/vmlinux.lds, replace
+And in @file{arch/i386/vmlinux.lds}, replace
@example
. = 0xc0000000 + 0x100000;
@end example
. = 0x90000000 + 0x100000;
@end example
-The file config-2.4.20 gives the configuration of the example kernel.
-
-Just type
+@item
+If you want to enable SMP (Symmetric Multi-Processing) support, you
+must make the following change in @file{include/asm/fixmap.h}. Replace
@example
-make bzImage
+#define FIXADDR_TOP (0xffffX000UL)
@end example
+by
+@example
+#define FIXADDR_TOP (0xa7ffX000UL)
+@end example
+(X is 'e' or 'f' depending on the kernel version). Although you can
+use an SMP kernel with QEMU, it only supports one CPU.
-As you would do to make a real kernel. Then you can use with QEMU
-exactly the same kernel as you would boot on your PC (in
-@file{arch/i386/boot/bzImage}).
-
+@item
If you are not using a 2.5 kernel as host kernel but if you use a target
2.5 kernel, you must also ensure that the 'HZ' define is set to 100
(1000 is the default) as QEMU cannot currently emulate timers at
frequencies greater than 100 Hz on host Linux systems < 2.5. In
-asm/param.h, replace:
+@file{include/asm/param.h}, replace:
@example
# define HZ 1000 /* Internal kernel timer frequency */
# define HZ 100 /* Internal kernel timer frequency */
@end example
-@section PC Emulation
+@end enumerate
-QEMU emulates the following PC peripherials:
+The file config-2.x.x gives the configuration of the example kernels.
-@itemize
-@item
-PIC (interrupt controler)
+Just type
+@example
+make bzImage
+@end example
+
+As you would do to make a real kernel. Then you can use with QEMU
+exactly the same kernel as you would boot on your PC (in
+@file{arch/i386/boot/bzImage}).
+
+@node gdb_usage
+@section GDB usage
+
+QEMU has a primitive support to work with gdb, so that you can do
+'Ctrl-C' while the virtual machine is running and inspect its state.
+
+In order to use gdb, launch qemu with the '-s' option. It will wait for a
+gdb connection:
+@example
+> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
+Connected to host network interface: tun0
+Waiting gdb connection on port 1234
+@end example
+
+Then launch gdb on the 'vmlinux' executable:
+@example
+> gdb vmlinux
+@end example
+
+In gdb, connect to QEMU:
+@example
+(gdb) target remote localhost:1234
+@end example
+
+Then you can use gdb normally. For example, type 'c' to launch the kernel:
+@example
+(gdb) c
+@end example
+
+Here are some useful tips in order to use gdb on system code:
+
+@enumerate
@item
-PIT (timers)
-@item
-CMOS memory
+Use @code{info reg} to display all the CPU registers.
@item
-Serial port (port=0x3f8, irq=4)
-@item
-NE2000 network adapter (port=0x300, irq=9)
+Use @code{x/10i $eip} to display the code at the PC position.
@item
-Dumb VGA (to print the @code{Uncompressing Linux} message)
-@end itemize
+Use @code{set architecture i8086} to dump 16 bit code. Then use
+@code{x/10i $cs*16+*eip} to dump the code at the PC position.
+@end enumerate
@chapter QEMU Internals
a linked list of every translated block contained in a given page. Other
linked lists are also maintained to undo direct block chaining.
-Althought the overhead of doing @code{mprotect()} calls is important,
+Although the overhead of doing @code{mprotect()} calls is important,
most MSDOS programs can be emulated at reasonnable speed with QEMU and
DOSEMU.
@section Self-virtualization
-QEMU was conceived so that ultimately it can emulate itself. Althought
+QEMU was conceived so that ultimately it can emulate itself. Although
it is not very useful, it is an important test to show the power of the
emulator.
In the directory @file{tests/}, various interesting testing programs
are available. There are used for regression testing.
-@section @file{hello-i386}
-
-Very simple statically linked x86 program, just to test QEMU during a
-port to a new host CPU.
-
-@section @file{hello-arm}
-
-Very simple statically linked ARM program, just to test QEMU during a
-port to a new host CPU.
-
@section @file{test-i386}
This program executes most of the 16 bit and 32 bit x86 instructions and
Various exceptions are raised to test most of the x86 user space
exception reporting.
+@section @file{linux-test}
+
+This program tests various Linux system calls. It is used to verify
+that the system call parameters are correctly converted between target
+and host CPUs.
+
+@section @file{hello-i386}
+
+Very simple statically linked x86 program, just to test QEMU during a
+port to a new host CPU.
+
+@section @file{hello-arm}
+
+Very simple statically linked ARM program, just to test QEMU during a
+port to a new host CPU.
+
@section @file{sha1}
It is a simple benchmark. Care must be taken to interpret the results