@item Self-modifying code support.
-@item Precise exception support.
+@item Precise exceptions support.
@item The virtual CPU is a library (@code{libqemu}) which can be used
in other projects.
@end itemize
-@chapter QEMU User space emulation invocation
+@chapter QEMU User space emulator invocation
@section Quick Start
@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{vl-test-xxx.tar.gz} containing a Linux
+kernel and a disk image. The archive also contains a precompiled
+version of @file{vl}, the QEMU System emulator.
@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
> ./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
+Linux version 2.4.20 (fabrice@localhost.localdomain) (gcc version 2.96 20000731 (Red Hat Linux 7.3 2.96-110)) #22 lun jui 7 13:37:41 CEST 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 ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
+ide_setup: ide1=noprobe
+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 501.285 MHz processor.
+Calibrating delay loop... 989.59 BogoMIPS
+Memory: 29268k/32768k available (907k kernel code, 3112k reserved, 212k data, 52k 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)
Initializing RT netlink socket
apm: BIOS not found.
Starting kswapd
+Journalled Block Device driver loaded
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
+Uniform Multi-Platform E-IDE driver Revision: 6.31
+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: 12288 sectors (6 MB) w/256KiB Cache, CHS=12/16/63
+Partition check:
+ hda: unknown partition table
ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com)
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
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
+Freeing unused kernel memory: 52k freed
sh: can't access tty; job control turned off
#
@end example
Then you can play with the kernel inside the virtual serial console. You
can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help
about the keys you can type inside the virtual serial console. In
-particular @key{Ctrl-a b} is the Magic SysRq key.
+particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as
+the Magic SysRq key.
@item
If the network is enabled, launch the script @file{/etc/linuxrc} in the
@end enumerate
-NOTE: the example initrd is a modified version of the one made by Kevin
+NOTES:
+@enumerate
+@item
+A 2.5.74 kernel is also included in the vl-test archive. Just
+replace the bzImage in vl.sh to try it.
+
+@item
+vl creates a temporary file in @var{$VLTMPDIR} (@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
+In order to exit cleanly for vl, you can do a @emph{shutdown} inside
+vl. vl 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}).
-@section Kernel Compilation
+@end enumerate
+
+@section Invocation
+
+@example
+usage: vl [options] bzImage [kernel parameters...]
+@end example
+
+@file{bzImage} is a Linux kernel image.
+
+General options:
+@table @option
+@item -hda file
+@item -hdb file
+Use 'file' as hard disk 0 or 1 image (@xref{disk_images}).
+
+@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/vl-ifup]. This script is
+launched to configure the host network interface (usually tun0)
+corresponding to the virtual NE2000 card.
+
+@item -initrd file
+Use 'file' as initial ram disk.
+@end table
+
+Debug options:
+@table @option
+@item -s
+Wait gdb connection to port 1234.
+@item -p port
+Change gdb connection port.
+@item -d
+Output log in /tmp/vl.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
+
+@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
+vlmkcow -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{vlmkcow}. 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.
-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:
+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:
-In asm/page.h, replace
+@example
+vlmkcow 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
+
+@section Linux Kernel Compilation
+
+You should be able to use any kernel with QEMU provided you make the
+following changes (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.
+@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
+#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.
+
+@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
+@file{include/asm/param.h}, replace:
+
+@example
+# define HZ 1000 /* Internal kernel timer frequency */
+@end example
+by
+@example
+# define HZ 100 /* Internal kernel timer frequency */
+@end example
+
+@end enumerate
+
+The file config-2.x.x gives the configuration of the example kernels.
Just type
@example
@item
CMOS memory
@item
+Dumb VGA (to print the @code{Uncompressing Linux} message)
+@item
Serial port (port=0x3f8, irq=4)
@item
NE2000 network adapter (port=0x300, irq=9)
-@item
-Dumb VGA (to print the @code{uncompressing Linux kernel} message)
+@item
+IDE disk interface (port=0x1f0, irq=14)
@end itemize
+@section GDB usage
+
+QEMU has a primitive support to work with gdb, so that you can do
+'Ctrl-C' while the kernel is running and inspect its state.
+
+In order to use gdb, launch vl with the '-s' option. It will wait for a
+gdb connection:
+@example
+> vl -s arch/i386/boot/bzImage -hda root-2.4.20.img 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 locahost:1234
+@end example
+
+Then you can use gdb normally. For example, type 'c' to launch the kernel:
+@example
+(gdb) c
+@end example
+
+WARNING: breakpoints and single stepping are not yet supported.
+
@chapter QEMU Internals
@section QEMU compared to other emulators
translation. Valgrind is mainly a memory debugger while QEMU has no
support for it (QEMU could be used to detect out of bound memory
accesses as Valgrind, but it has no support to track uninitialised data
-as Valgrind does). Valgrind dynamic translator generates better code
+as Valgrind does). The Valgrind dynamic translator generates better code
than QEMU (in particular it does register allocation) but it is closely
-tied to an x86 host and target and has no support for precise exception
+tied to an x86 host and target and has no support for precise exceptions
and system emulation.
EM86 [4] is the closest project to user space QEMU (and QEMU still uses
launch the same kernel on your PC), but the patches are really small. As
it is a PC virtualizer (no emulation is done except for some priveledged
instructions), it has the potential of being faster than QEMU. The
-downside is that a complicated (and potentially unsafe) kernel patch is
-needed.
+downside is that a complicated (and potentially unsafe) host kernel
+patch is needed.
@section Portable dynamic translation
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.