qemu-doc.texi

qemu虚拟机代码

@item write to the FAT directory on the host system while accessing it with the guest system.
@end itemize

@node pcsys_network
@section Network emulation

QEMU can simulate several networks cards (NE2000 boards on the PC
target) and can connect them to an arbitrary number of Virtual Local
Area Networks (VLANs). Host TAP devices can be connected to any QEMU
VLAN. VLAN can be connected between separate instances of QEMU to
simulate large networks. For simpler usage, a non priviledged user mode
network stack can replace the TAP device to have a basic network
connection.

@subsection VLANs

QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
connection between several network devices. These devices can be for
example QEMU virtual Ethernet cards or virtual Host ethernet devices
(TAP devices).

@subsection Using TAP network interfaces

This is the standard way to connect QEMU to a real network. QEMU adds
a virtual network device on your host (called @code{tapN}), and you
can then configure it as if it was a real ethernet card.

As an example, you can download the @file{linux-test-xxx.tar.gz}
archive and copy the script @file{qemu-ifup} in @file{/etc} and
configure properly @code{sudo} so that the command @code{ifconfig}
contained in @file{qemu-ifup} can be executed as root. You must verify
that your host kernel supports the TAP network interfaces: the
device @file{/dev/net/tun} must be present.

See @ref{direct_linux_boot} to have an example of network use with a
Linux distribution and @ref{sec_invocation} to have examples of
command lines using the TAP network interfaces.

@subsection Using the user mode network stack

By using the option @option{-net user} (default configuration if no
@option{-net} option is specified), QEMU uses a completely user mode
network stack (you don't need root priviledge to use the virtual
network). The virtual network configuration is the following:

@example

         QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
                           |          (10.0.2.2)
                           |
                           ---->  DNS server (10.0.2.3)
                           |     
                           ---->  SMB server (10.0.2.4)
@end example

The QEMU VM behaves as if it was behind a firewall which blocks all
incoming connections. You can use a DHCP client to automatically
configure the network in the QEMU VM. The DHCP server assign addresses
to the hosts starting from 10.0.2.15.

In order to check that the user mode network is working, you can ping
the address 10.0.2.2 and verify that you got an address in the range
10.0.2.x from the QEMU virtual DHCP server.

Note that @code{ping} is not supported reliably to the internet as it
would require root priviledges. It means you can only ping the local
router (10.0.2.2).

When using the built-in TFTP server, the router is also the TFTP
server.

When using the @option{-redir} option, TCP or UDP connections can be
redirected from the host to the guest. It allows for example to
redirect X11, telnet or SSH connections.

@subsection Connecting VLANs between QEMU instances

Using the @option{-net socket} option, it is possible to make VLANs
that span several QEMU instances. See @ref{sec_invocation} to have a
basic example.

@node direct_linux_boot
@section Direct Linux Boot

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{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{qemu-ifup} in @file{/etc} and configure
properly @code{sudo} so that the command @code{ifconfig} contained in
@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.

When network is enabled, there is a virtual network connection between
the host kernel and the emulated kernel. The emulated kernel is seen
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{qemu.sh}. You should have the following output:

@smallexample
> ./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-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/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 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)
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
Checking 'hlt' instruction... OK.
POSIX conformance testing by UNIFIX
Linux NET4.0 for Linux 2.4
Based upon Swansea University Computer Society NET3.039
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
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 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 4096)
NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
VFS: Mounted root (ext2 filesystem).
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 smallexample

@item
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, 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
emulator (don't forget the leading dot):
@example
. /etc/linuxrc
@end example

Then enable X11 connections on your PC from the emulated Linux: 
@example
xhost +172.20.0.2
@end example

You can now launch @file{xterm} or @file{xlogo} and verify that you have
a real Virtual Linux system !

@end enumerate

NOTES:
@enumerate
@item 
A 2.5.74 kernel is also included in the archive. Just
replace the bzImage in qemu.sh to try it.

@item 
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

@node pcsys_usb
@section USB emulation

QEMU emulates a PCI UHCI USB controller and a 8 port USB hub connected
to it. You can virtually plug to the hub virtual USB devices or real
host USB devices (experimental, works only on Linux hosts).

@subsection Using virtual USB devices

A virtual USB mouse device is available for testing in QEMU.

You can try it with the following monitor commands:

@example
# add the mouse device
(qemu) usb_add mouse 

# show the virtual USB devices plugged on the QEMU Virtual USB hub
(qemu) info usb
  Device 0.3, speed 12 Mb/s

# after some time you can try to remove the mouse
(qemu) usb_del 0.3
@end example

The option @option{-usbdevice} is similar to the monitor command
@code{usb_add}.

@subsection Using host USB devices on a Linux host

WARNING: this is an experimental feature. QEMU will slow down when
using it. USB devices requiring real time streaming (i.e. USB Video
Cameras) are not supported yet.

@enumerate
@item If you use an early Linux 2.4 kernel, verify that no Linux driver 
is actually using the USB device. A simple way to do that is simply to
disable the corresponding kernel module by renaming it from @file{mydriver.o}
to @file{mydriver.o.disabled}.

@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
@example
ls /proc/bus/usb
001  devices  drivers
@end example

@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:
@example
chown -R myuid /proc/bus/usb
@end example

@item Launch QEMU and do in the monitor:
@example 
info usbhost
  Device 1.2, speed 480 Mb/s
    Class 00: USB device 1234:5678, USB DISK
@end example
You should see the list of the devices you can use (Never try to use
hubs, it won't work).

@item Add the device in QEMU by using:
@example 
usb_add host:1234:5678
@end example

Normally the guest OS should report that a new USB device is
plugged. You can use the option @option{-usbdevice} to do the same.

@item Now you can try to use the host USB device in QEMU.

@end enumerate

When relaunching QEMU, you may have to unplug and plug again the USB
device to make it work again (this is a bug).

@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
Use @code{info reg} to display all the CPU registers.
@item
Use @code{x/10i $eip} to display the code at the PC position.
@item
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

@node pcsys_os_specific
@section Target OS specific information

@subsection Linux

To have access to SVGA graphic modes under X11, use the @code{vesa} or
the @code{cirrus} X11 driver. For optimal performances, use 16 bit
color depth in the guest and the host OS.

When using a 2.6 guest Linux kernel, you should add the option
@code{clock=pit} on the kernel command line because the 2.6 Linux
kernels make very strict real time clock checks by default that QEMU
cannot simulate exactly.

When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
not activated because QEMU is slower with this patch. The QEMU
Accelerator Module is also much slower in this case. Earlier Fedora
Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this
patch by default. Newer kernels don't have it.

@subsection Windows

If you have a slow host, using Windows 95 is better as it gives the
best speed. Windows 2000 is also a good choice.

@subsubsection SVGA graphic modes support

QEMU emulates a Cirrus Logic GD5446 Video
card. All Windows versions starting from Windows 95 should recognize
and use this graphic card. For optimal performances, use 16 bit color
depth in the guest and the host OS.

@subsubsection CPU usage reduction

Windows 9x does not correctly use the CPU HLT
instruction. The result is that it takes host CPU cycles even when
idle. You can install the utility from
@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
problem. Note that no such tool is needed for NT, 2000 or XP.

@subsubsection Windows 2000 disk full problem

Windows 2000 has a bug which gives a disk full problem during its
installation. When installing it, use the @option{-win2k-hack} QEMU
option to enable a specific workaround. After Windows 2000 is
installed, you no longer need this option (this option slows down the
IDE transfers).

@subsubsection Windows 2000 shutdown

Windows 2000 cannot automatically shutdown in QEMU although Windows 98
can. It comes from the fact that Windows 2000 does not automatically
use the APM driver provided by the BIOS.

In order to correct that, do the following (thanks to Struan
Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
Add/Troubleshoot a device => Add a new device & Next => No, select the
hardware from a list & Next => NT Apm/Legacy Support & Next => Next
(again) a few times. Now the driver is installed and Windows 2000 now
correctly instructs QEMU to shutdown at the appropriate moment. 

@subsubsection Share a directory between Unix and Windows

See @ref{sec_invocation} about the help of the option @option{-smb}.

@subsubsection Windows XP security problems

Some releases of Windows XP install correctly but give a security
error when booting:
@example
A problem is preventing Windows from accurately checking the
license for this computer. Error code: 0x800703e6.
@end example
The only known workaround is to boot in Safe mode
without networking support. 

Future QEMU releases are likely to correct this bug.

@subsection MS-DOS and FreeDOS

@subsubsection CPU usage reduction

DOS does not correctly use the CPU HLT instruction. The result is that
it takes host CPU cycles even when idle. You can install the utility
from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
problem.

@node QEMU System emulator for non PC targets
@chapter QEMU System emulator for non PC targets

QEMU is a generic emulator and it emulates many non PC
machines. Most of the options are similar to the PC emulator. The
differences are mentionned in the following sections.