| 1 |
1 |
\input texinfo @c -*- texinfo -*-
|
| 2 |
2 |
|
| 3 |
3 |
@iftex
|
| 4 |
|
@settitle QEMU CPU Emulator Reference Documentation
|
|
4 |
@settitle QEMU CPU Emulator User Documentation
|
| 5 |
5 |
@titlepage
|
| 6 |
6 |
@sp 7
|
| 7 |
|
@center @titlefont{QEMU CPU Emulator Reference Documentation}
|
|
7 |
@center @titlefont{QEMU CPU Emulator User Documentation}
|
| 8 |
8 |
@sp 3
|
| 9 |
9 |
@end titlepage
|
| 10 |
10 |
@end iftex
|
| ... | ... | |
| 13 |
13 |
|
| 14 |
14 |
@section Features
|
| 15 |
15 |
|
| 16 |
|
QEMU is a FAST! processor emulator. By using dynamic translation it
|
| 17 |
|
achieves a reasonnable speed while being easy to port on new host
|
| 18 |
|
CPUs.
|
|
16 |
QEMU is a FAST! processor emulator using dynamic translation to
|
|
17 |
achieve good emulation speed.
|
| 19 |
18 |
|
| 20 |
19 |
QEMU has two operating modes:
|
| 21 |
20 |
|
| 22 |
21 |
@itemize @minus
|
| 23 |
22 |
|
| 24 |
23 |
@item
|
| 25 |
|
User mode emulation. In this mode, QEMU can launch Linux processes
|
| 26 |
|
compiled for one CPU on another CPU. Linux system calls are converted
|
| 27 |
|
because of endianness and 32/64 bit mismatches. The Wine Windows API
|
| 28 |
|
emulator (@url{http://www.winehq.org}) and the DOSEMU DOS emulator
|
| 29 |
|
(@url{http://www.dosemu.org}) are the main targets for QEMU.
|
|
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 |
28 |
|
| 31 |
29 |
@item
|
| 32 |
|
Full system emulation. In this mode, QEMU emulates a full
|
| 33 |
|
system, including a processor and various peripherials. Currently, it
|
| 34 |
|
is only used to launch an x86 Linux kernel on an x86 Linux system. It
|
| 35 |
|
enables easier testing and debugging of system code. It can also be
|
| 36 |
|
used to provide virtual hosting of several virtual PCs on a single
|
| 37 |
|
server.
|
|
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.
|
| 38 |
34 |
|
| 39 |
35 |
@end itemize
|
| 40 |
36 |
|
| 41 |
|
As QEMU requires no host kernel patches to run, it is very safe and
|
|
37 |
As QEMU requires no host kernel driver to run, it is very safe and
|
| 42 |
38 |
easy to use.
|
| 43 |
39 |
|
| 44 |
|
QEMU generic features:
|
|
40 |
For system emulation, only the x86 PC emulator is currently
|
|
41 |
usable. The PowerPC system emulator is being developped.
|
| 45 |
42 |
|
| 46 |
|
@itemize
|
| 47 |
|
|
| 48 |
|
@item User space only or full system emulation.
|
| 49 |
|
|
| 50 |
|
@item Using dynamic translation to native code for reasonnable speed.
|
| 51 |
|
|
| 52 |
|
@item Working on x86 and PowerPC hosts. Being tested on ARM, Sparc32, Alpha and S390.
|
| 53 |
|
|
| 54 |
|
@item Self-modifying code support.
|
| 55 |
|
|
| 56 |
|
@item Precise exceptions support.
|
| 57 |
|
|
| 58 |
|
@item The virtual CPU is a library (@code{libqemu}) which can be used
|
| 59 |
|
in other projects.
|
| 60 |
|
|
| 61 |
|
@end itemize
|
| 62 |
|
|
| 63 |
|
QEMU user mode emulation features:
|
| 64 |
|
@itemize
|
| 65 |
|
@item Generic Linux system call converter, including most ioctls.
|
| 66 |
|
|
| 67 |
|
@item clone() emulation using native CPU clone() to use Linux scheduler for threads.
|
| 68 |
|
|
| 69 |
|
@item Accurate signal handling by remapping host signals to target signals.
|
| 70 |
|
@end itemize
|
| 71 |
|
@end itemize
|
| 72 |
|
|
| 73 |
|
QEMU full system emulation features:
|
| 74 |
|
@itemize
|
| 75 |
|
@item QEMU can either use a full software MMU for maximum portability or use the host system call mmap() to simulate the target MMU.
|
| 76 |
|
@end itemize
|
| 77 |
|
|
| 78 |
|
@section x86 emulation
|
| 79 |
|
|
| 80 |
|
QEMU x86 target features:
|
| 81 |
|
|
| 82 |
|
@itemize
|
| 83 |
|
|
| 84 |
|
@item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation.
|
| 85 |
|
LDT/GDT and IDT are emulated. VM86 mode is also supported to run DOSEMU.
|
| 86 |
|
|
| 87 |
|
@item Support of host page sizes bigger than 4KB in user mode emulation.
|
| 88 |
|
|
| 89 |
|
@item QEMU can emulate itself on x86.
|
| 90 |
|
|
| 91 |
|
@item An extensive Linux x86 CPU test program is included @file{tests/test-i386}.
|
| 92 |
|
It can be used to test other x86 virtual CPUs.
|
| 93 |
|
|
| 94 |
|
@end itemize
|
| 95 |
|
|
| 96 |
|
Current QEMU limitations:
|
| 97 |
|
|
| 98 |
|
@itemize
|
| 99 |
|
|
| 100 |
|
@item No SSE/MMX support (yet).
|
| 101 |
|
|
| 102 |
|
@item No x86-64 support.
|
| 103 |
|
|
| 104 |
|
@item IPC syscalls are missing.
|
| 105 |
|
|
| 106 |
|
@item The x86 segment limits and access rights are not tested at every
|
| 107 |
|
memory access.
|
| 108 |
|
|
| 109 |
|
@item On non x86 host CPUs, @code{double}s are used instead of the non standard
|
| 110 |
|
10 byte @code{long double}s of x86 for floating point emulation to get
|
| 111 |
|
maximum performances.
|
| 112 |
|
|
| 113 |
|
@item Some priviledged instructions or behaviors are missing, especially for segment protection testing (yet).
|
| 114 |
|
|
| 115 |
|
@end itemize
|
| 116 |
|
|
| 117 |
|
@section ARM emulation
|
| 118 |
|
|
| 119 |
|
@itemize
|
| 120 |
|
|
| 121 |
|
@item ARM emulation can currently launch small programs while using the
|
| 122 |
|
generic dynamic code generation architecture of QEMU.
|
| 123 |
|
|
| 124 |
|
@item No FPU support (yet).
|
| 125 |
|
|
| 126 |
|
@item No automatic regression testing (yet).
|
| 127 |
|
|
| 128 |
|
@end itemize
|
| 129 |
|
|
| 130 |
|
@section SPARC emulation
|
| 131 |
|
|
| 132 |
|
The SPARC emulation is currently in development.
|
|
43 |
For user emulation, x86, PowerPC, ARM, and SPARC CPUs are supported.
|
| 133 |
44 |
|
| 134 |
45 |
@chapter Installation
|
| 135 |
46 |
|
|
47 |
@section Linux
|
|
48 |
|
| 136 |
49 |
If you want to compile QEMU, please read the @file{README} which gives
|
| 137 |
50 |
the related information. Otherwise just download the binary
|
| 138 |
51 |
distribution (@file{qemu-XXX-i386.tar.gz}) and untar it as root in
|
| ... | ... | |
| 144 |
57 |
tar zxvf /tmp/qemu-XXX-i386.tar.gz
|
| 145 |
58 |
@end example
|
| 146 |
59 |
|
| 147 |
|
@chapter QEMU User space emulator invocation
|
| 148 |
|
|
| 149 |
|
@section Quick Start
|
| 150 |
|
|
| 151 |
|
In order to launch a Linux process, QEMU needs the process executable
|
| 152 |
|
itself and all the target (x86) dynamic libraries used by it.
|
| 153 |
|
|
|
60 |
@section Windows
|
|
61 |
w
|
| 154 |
62 |
@itemize
|
|
63 |
@item Install the current versions of MSYS and MinGW from
|
|
64 |
@url{http://www.mingw.org/}. You can find detailed installation
|
|
65 |
instructions in the download section and the FAQ.
|
|
66 |
|
|
67 |
@item Download
|
|
68 |
the MinGW development library of SDL 1.2.x
|
|
69 |
(@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
|
|
70 |
@url{http://www.libsdl.org}. Unpack it in a temporary place, and
|
|
71 |
unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
|
|
72 |
directory. Edit the @file{sdl-config} script so that it gives the
|
|
73 |
correct SDL directory when invoked.
|
|
74 |
|
|
75 |
@item Extract the current version of QEMU.
|
|
76 |
|
|
77 |
@item Start the MSYS shell (file @file{msys.bat}).
|
| 155 |
78 |
|
| 156 |
|
@item On x86, you can just try to launch any process by using the native
|
| 157 |
|
libraries:
|
| 158 |
|
|
| 159 |
|
@example
|
| 160 |
|
qemu-i386 -L / /bin/ls
|
| 161 |
|
@end example
|
| 162 |
|
|
| 163 |
|
@code{-L /} tells that the x86 dynamic linker must be searched with a
|
| 164 |
|
@file{/} prefix.
|
| 165 |
|
|
| 166 |
|
@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):
|
| 167 |
|
|
| 168 |
|
@example
|
| 169 |
|
qemu-i386 -L / qemu-i386 -L / /bin/ls
|
| 170 |
|
@end example
|
| 171 |
|
|
| 172 |
|
@item On non x86 CPUs, you need first to download at least an x86 glibc
|
| 173 |
|
(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
|
| 174 |
|
@code{LD_LIBRARY_PATH} is not set:
|
| 175 |
|
|
| 176 |
|
@example
|
| 177 |
|
unset LD_LIBRARY_PATH
|
| 178 |
|
@end example
|
|
79 |
@item Change to the QEMU directory. Launch @file{./configure} and
|
|
80 |
@file{make}. If you have problems using SDL, verify that
|
|
81 |
@file{sdl-config} can be launched from the MSYS command line.
|
| 179 |
82 |
|
| 180 |
|
Then you can launch the precompiled @file{ls} x86 executable:
|
| 181 |
|
|
| 182 |
|
@example
|
| 183 |
|
qemu-i386 tests/i386/ls
|
| 184 |
|
@end example
|
| 185 |
|
You can look at @file{qemu-binfmt-conf.sh} so that
|
| 186 |
|
QEMU is automatically launched by the Linux kernel when you try to
|
| 187 |
|
launch x86 executables. It requires the @code{binfmt_misc} module in the
|
| 188 |
|
Linux kernel.
|
| 189 |
|
|
| 190 |
|
@item The x86 version of QEMU is also included. You can try weird things such as:
|
| 191 |
|
@example
|
| 192 |
|
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
|
| 193 |
|
@end example
|
|
83 |
@item You can install QEMU in @file{Program Files/Qemu} by typing
|
|
84 |
@file{make install}. Don't forget to copy @file{SDL.dll} in
|
|
85 |
@file{Program Files/Qemu}.
|
| 194 |
86 |
|
| 195 |
87 |
@end itemize
|
| 196 |
88 |
|
| 197 |
|
@section Wine launch
|
|
89 |
@section Cross compilation for Windows with Linux
|
| 198 |
90 |
|
| 199 |
91 |
@itemize
|
|
92 |
@item
|
|
93 |
Install the MinGW cross compilation tools available at
|
|
94 |
@url{http://www.mingw.org/}.
|
| 200 |
95 |
|
| 201 |
|
@item Ensure that you have a working QEMU with the x86 glibc
|
| 202 |
|
distribution (see previous section). In order to verify it, you must be
|
| 203 |
|
able to do:
|
|
96 |
@item
|
|
97 |
Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
|
|
98 |
unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
|
|
99 |
variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
|
|
100 |
the QEMU configuration script.
|
| 204 |
101 |
|
|
102 |
@item
|
|
103 |
Configure QEMU for Windows cross compilation:
|
| 205 |
104 |
@example
|
| 206 |
|
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
|
|
105 |
./configure --enable-mingw32
|
| 207 |
106 |
@end example
|
|
107 |
If necessary, you can change the cross-prefix according to the prefix
|
|
108 |
choosen for the MinGW tools with --cross-prefix. You can also use
|
|
109 |
--prefix to set the Win32 install path.
|
| 208 |
110 |
|
| 209 |
|
@item Download the binary x86 Wine install
|
| 210 |
|
(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
|
| 211 |
|
|
| 212 |
|
@item Configure Wine on your account. Look at the provided script
|
| 213 |
|
@file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous
|
| 214 |
|
@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
|
| 215 |
|
|
| 216 |
|
@item Then you can try the example @file{putty.exe}:
|
| 217 |
|
|
| 218 |
|
@example
|
| 219 |
|
qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
|
| 220 |
|
@end example
|
|
111 |
@item You can install QEMU in the installation directory by typing
|
|
112 |
@file{make install}. Don't forget to copy @file{SDL.dll} in the
|
|
113 |
installation directory.
|
| 221 |
114 |
|
| 222 |
115 |
@end itemize
|
| 223 |
116 |
|
| 224 |
|
@section Command line options
|
|
117 |
Note: Currently, Wine does not seem able to launch
|
|
118 |
QEMU for Win32.
|
| 225 |
119 |
|
| 226 |
|
@example
|
| 227 |
|
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
|
| 228 |
|
@end example
|
|
120 |
@section Mac OS X
|
| 229 |
121 |
|
| 230 |
|
@table @option
|
| 231 |
|
@item -h
|
| 232 |
|
Print the help
|
| 233 |
|
@item -L path
|
| 234 |
|
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
|
| 235 |
|
@item -s size
|
| 236 |
|
Set the x86 stack size in bytes (default=524288)
|
| 237 |
|
@end table
|
| 238 |
|
|
| 239 |
|
Debug options:
|
| 240 |
|
|
| 241 |
|
@table @option
|
| 242 |
|
@item -d
|
| 243 |
|
Activate log (logfile=/tmp/qemu.log)
|
| 244 |
|
@item -p pagesize
|
| 245 |
|
Act as if the host page size was 'pagesize' bytes
|
| 246 |
|
@end table
|
|
122 |
Mac OS X is currently not supported.
|
| 247 |
123 |
|
| 248 |
124 |
@chapter QEMU System emulator invocation
|
| 249 |
125 |
|
| ... | ... | |
| 251 |
127 |
|
| 252 |
128 |
@c man begin DESCRIPTION
|
| 253 |
129 |
|
| 254 |
|
The QEMU System emulator simulates a complete PC. It can either boot
|
| 255 |
|
directly a Linux kernel (without any BIOS or boot loader) or boot like a
|
| 256 |
|
real PC with the included BIOS.
|
|
130 |
The QEMU System emulator simulates a complete PC.
|
| 257 |
131 |
|
| 258 |
132 |
In order to meet specific user needs, two versions of QEMU are
|
| 259 |
133 |
available:
|
| ... | ... | |
| 282 |
156 |
PS/2 mouse and keyboard
|
| 283 |
157 |
@item
|
| 284 |
158 |
2 IDE interfaces with hard disk and CD-ROM support
|
|
159 |
@item
|
|
160 |
Floppy disk
|
| 285 |
161 |
@item
|
| 286 |
|
NE2000 network adapter (port=0x300, irq=9)
|
|
162 |
up to 6 NE2000 network adapters
|
| 287 |
163 |
@item
|
| 288 |
164 |
Serial port
|
| 289 |
165 |
@item
|
| 290 |
166 |
Soundblaster 16 card
|
| 291 |
|
@item
|
| 292 |
|
PIC (interrupt controler)
|
| 293 |
|
@item
|
| 294 |
|
PIT (timers)
|
| 295 |
|
@item
|
| 296 |
|
CMOS memory
|
| 297 |
167 |
@end itemize
|
| 298 |
168 |
|
| 299 |
169 |
@c man end
|
| ... | ... | |
| 308 |
178 |
|
| 309 |
179 |
Linux should boot and give you a prompt.
|
| 310 |
180 |
|
| 311 |
|
@section Direct Linux Boot and Network emulation
|
| 312 |
|
|
| 313 |
|
This section explains how to launch a Linux kernel inside QEMU without
|
| 314 |
|
having to make a full bootable image. It is very useful for fast Linux
|
| 315 |
|
kernel testing. The QEMU network configuration is also explained.
|
| 316 |
|
|
| 317 |
|
@enumerate
|
| 318 |
|
@item
|
| 319 |
|
Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
|
| 320 |
|
kernel and a disk image.
|
| 321 |
|
|
| 322 |
|
@item Optional: If you want network support (for example to launch X11 examples), you
|
| 323 |
|
must copy the script @file{qemu-ifup} in @file{/etc} and configure
|
| 324 |
|
properly @code{sudo} so that the command @code{ifconfig} contained in
|
| 325 |
|
@file{qemu-ifup} can be executed as root. You must verify that your host
|
| 326 |
|
kernel supports the TUN/TAP network interfaces: the device
|
| 327 |
|
@file{/dev/net/tun} must be present.
|
| 328 |
|
|
| 329 |
|
When network is enabled, there is a virtual network connection between
|
| 330 |
|
the host kernel and the emulated kernel. The emulated kernel is seen
|
| 331 |
|
from the host kernel at IP address 172.20.0.2 and the host kernel is
|
| 332 |
|
seen from the emulated kernel at IP address 172.20.0.1.
|
| 333 |
|
|
| 334 |
|
@item Launch @code{qemu.sh}. You should have the following output:
|
| 335 |
|
|
| 336 |
|
@example
|
| 337 |
|
> ./qemu.sh
|
| 338 |
|
Connected to host network interface: tun0
|
| 339 |
|
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
|
| 340 |
|
BIOS-provided physical RAM map:
|
| 341 |
|
BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
|
| 342 |
|
BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
|
| 343 |
|
32MB LOWMEM available.
|
| 344 |
|
On node 0 totalpages: 8192
|
| 345 |
|
zone(0): 4096 pages.
|
| 346 |
|
zone(1): 4096 pages.
|
| 347 |
|
zone(2): 0 pages.
|
| 348 |
|
Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0
|
| 349 |
|
ide_setup: ide2=noprobe
|
| 350 |
|
ide_setup: ide3=noprobe
|
| 351 |
|
ide_setup: ide4=noprobe
|
| 352 |
|
ide_setup: ide5=noprobe
|
| 353 |
|
Initializing CPU#0
|
| 354 |
|
Detected 2399.621 MHz processor.
|
| 355 |
|
Console: colour EGA 80x25
|
| 356 |
|
Calibrating delay loop... 4744.80 BogoMIPS
|
| 357 |
|
Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem)
|
| 358 |
|
Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
|
| 359 |
|
Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
|
| 360 |
|
Mount cache hash table entries: 512 (order: 0, 4096 bytes)
|
| 361 |
|
Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
|
| 362 |
|
Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
|
| 363 |
|
CPU: Intel Pentium Pro stepping 03
|
| 364 |
|
Checking 'hlt' instruction... OK.
|
| 365 |
|
POSIX conformance testing by UNIFIX
|
| 366 |
|
Linux NET4.0 for Linux 2.4
|
| 367 |
|
Based upon Swansea University Computer Society NET3.039
|
| 368 |
|
Initializing RT netlink socket
|
| 369 |
|
apm: BIOS not found.
|
| 370 |
|
Starting kswapd
|
| 371 |
|
Journalled Block Device driver loaded
|
| 372 |
|
Detected PS/2 Mouse Port.
|
| 373 |
|
pty: 256 Unix98 ptys configured
|
| 374 |
|
Serial driver version 5.05c (2001-07-08) with no serial options enabled
|
| 375 |
|
ttyS00 at 0x03f8 (irq = 4) is a 16450
|
| 376 |
|
ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com)
|
| 377 |
|
Last modified Nov 1, 2000 by Paul Gortmaker
|
| 378 |
|
NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
|
| 379 |
|
eth0: NE2000 found at 0x300, using IRQ 9.
|
| 380 |
|
RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
|
| 381 |
|
Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
|
| 382 |
|
ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
|
| 383 |
|
hda: QEMU HARDDISK, ATA DISK drive
|
| 384 |
|
ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
|
| 385 |
|
hda: attached ide-disk driver.
|
| 386 |
|
hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
|
| 387 |
|
Partition check:
|
| 388 |
|
hda:
|
| 389 |
|
Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
|
| 390 |
|
NET4: Linux TCP/IP 1.0 for NET4.0
|
| 391 |
|
IP Protocols: ICMP, UDP, TCP, IGMP
|
| 392 |
|
IP: routing cache hash table of 512 buckets, 4Kbytes
|
| 393 |
|
TCP: Hash tables configured (established 2048 bind 4096)
|
| 394 |
|
NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
|
| 395 |
|
EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
|
| 396 |
|
VFS: Mounted root (ext2 filesystem).
|
| 397 |
|
Freeing unused kernel memory: 64k freed
|
| 398 |
|
|
| 399 |
|
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
|
| 400 |
|
|
| 401 |
|
QEMU Linux test distribution (based on Redhat 9)
|
| 402 |
|
|
| 403 |
|
Type 'exit' to halt the system
|
| 404 |
|
|
| 405 |
|
sh-2.05b#
|
| 406 |
|
@end example
|
| 407 |
|
|
| 408 |
|
@item
|
| 409 |
|
Then you can play with the kernel inside the virtual serial console. You
|
| 410 |
|
can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help
|
| 411 |
|
about the keys you can type inside the virtual serial console. In
|
| 412 |
|
particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as
|
| 413 |
|
the Magic SysRq key.
|
| 414 |
|
|
| 415 |
|
@item
|
| 416 |
|
If the network is enabled, launch the script @file{/etc/linuxrc} in the
|
| 417 |
|
emulator (don't forget the leading dot):
|
| 418 |
|
@example
|
| 419 |
|
. /etc/linuxrc
|
| 420 |
|
@end example
|
| 421 |
|
|
| 422 |
|
Then enable X11 connections on your PC from the emulated Linux:
|
| 423 |
|
@example
|
| 424 |
|
xhost +172.20.0.2
|
| 425 |
|
@end example
|
| 426 |
|
|
| 427 |
|
You can now launch @file{xterm} or @file{xlogo} and verify that you have
|
| 428 |
|
a real Virtual Linux system !
|
| 429 |
|
|
| 430 |
|
@end enumerate
|
| 431 |
|
|
| 432 |
|
NOTES:
|
| 433 |
|
@enumerate
|
| 434 |
|
@item
|
| 435 |
|
A 2.5.74 kernel is also included in the archive. Just
|
| 436 |
|
replace the bzImage in qemu.sh to try it.
|
| 437 |
|
|
| 438 |
|
@item
|
| 439 |
|
qemu creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the
|
| 440 |
|
default) containing all the simulated PC memory. If possible, try to use
|
| 441 |
|
a temporary directory using the tmpfs filesystem to avoid too many
|
| 442 |
|
unnecessary disk accesses.
|
| 443 |
|
|
| 444 |
|
@item
|
| 445 |
|
In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
|
| 446 |
|
qemu. qemu will automatically exit when the Linux shutdown is done.
|
| 447 |
|
|
| 448 |
|
@item
|
| 449 |
|
You can boot slightly faster by disabling the probe of non present IDE
|
| 450 |
|
interfaces. To do so, add the following options on the kernel command
|
| 451 |
|
line:
|
| 452 |
|
@example
|
| 453 |
|
ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
|
| 454 |
|
@end example
|
| 455 |
|
|
| 456 |
|
@item
|
| 457 |
|
The example disk image is a modified version of the one made by Kevin
|
| 458 |
|
Lawton for the plex86 Project (@url{www.plex86.org}).
|
| 459 |
|
|
| 460 |
|
@end enumerate
|
| 461 |
|
|
| 462 |
181 |
@section Invocation
|
| 463 |
182 |
|
| 464 |
183 |
@example
|
| ... | ... | |
| 486 |
205 |
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
|
| 487 |
206 |
@option{-cdrom} at the same time).
|
| 488 |
207 |
|
| 489 |
|
@item -boot [a|b|c|d]
|
| 490 |
|
Boot on floppy (a, b), hard disk (c) or CD-ROM (d). Hard disk boot is
|
|
208 |
@item -boot [a|c|d]
|
|
209 |
Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
|
| 491 |
210 |
the default.
|
| 492 |
211 |
|
| 493 |
212 |
@item -snapshot
|
| ... | ... | |
| 498 |
217 |
@item -m megs
|
| 499 |
218 |
Set virtual RAM size to @var{megs} megabytes.
|
| 500 |
219 |
|
| 501 |
|
@item -n script
|
| 502 |
|
Set network init script [default=/etc/qemu-ifup]. This script is
|
| 503 |
|
launched to configure the host network interface (usually tun0)
|
| 504 |
|
corresponding to the virtual NE2000 card.
|
| 505 |
|
|
| 506 |
220 |
@item -initrd file
|
| 507 |
221 |
Use @var{file} as initial ram disk.
|
| 508 |
222 |
|
| 509 |
|
@item -tun-fd fd
|
| 510 |
|
Assumes @var{fd} talks to tap/tun and use it. Read
|
| 511 |
|
@url{http://bellard.org/qemu/tetrinet.html} to have an example of its
|
| 512 |
|
use.
|
| 513 |
|
|
| 514 |
223 |
@item -nographic
|
| 515 |
224 |
|
| 516 |
225 |
Normally, QEMU uses SDL to display the VGA output. With this option,
|
| ... | ... | |
| 521 |
230 |
|
| 522 |
231 |
@end table
|
| 523 |
232 |
|
| 524 |
|
Linux boot specific (does not require a full PC boot with a BIOS):
|
|
233 |
Network options:
|
|
234 |
|
|
235 |
@table @option
|
|
236 |
|
|
237 |
@item -n script
|
|
238 |
Set network init script [default=/etc/qemu-ifup]. This script is
|
|
239 |
launched to configure the host network interface (usually tun0)
|
|
240 |
corresponding to the virtual NE2000 card.
|
|
241 |
|
|
242 |
@item nics n
|
|
243 |
Simulate @var{n} network interfaces (default=1).
|
|
244 |
|
|
245 |
@item -macaddr addr
|
|
246 |
|
|
247 |
Set the mac address of the first interface (the format is
|
|
248 |
aa:bb:cc:dd:ee:ff in hexa). The mac address is incremented for each
|
|
249 |
new network interface.
|
|
250 |
|
|
251 |
@item -tun-fd fd1,...
|
|
252 |
Assumes @var{fd} talks to tap/tun and use it. Read
|
|
253 |
@url{http://bellard.org/qemu/tetrinet.html} to have an example of its
|
|
254 |
use.
|
|
255 |
|
|
256 |
@end table
|
|
257 |
|
|
258 |
Linux boot specific. When using this options, you can use a given
|
|
259 |
Linux kernel without installing it in the disk image. It can be useful
|
|
260 |
for easier testing of various kernels.
|
|
261 |
|
| 525 |
262 |
@table @option
|
| 526 |
263 |
|
| 527 |
264 |
@item -kernel bzImage
|
| ... | ... | |
| 545 |
282 |
Output log in /tmp/qemu.log
|
| 546 |
283 |
@end table
|
| 547 |
284 |
|
| 548 |
|
During emulation, use @key{C-a h} to get terminal commands:
|
|
285 |
During emulation, if you are using the serial console, use @key{C-a h}
|
|
286 |
to get terminal commands:
|
| 549 |
287 |
|
| 550 |
288 |
@table @key
|
| 551 |
289 |
@item C-a h
|
| ... | ... | |
| 555 |
293 |
@item C-a s
|
| 556 |
294 |
Save disk data back to file (if -snapshot)
|
| 557 |
295 |
@item C-a b
|
| 558 |
|
Send break (magic sysrq)
|
|
296 |
Send break (magic sysrq in Linux)
|
|
297 |
@item C-a c
|
|
298 |
Switch between console and monitor
|
| 559 |
299 |
@item C-a C-a
|
| 560 |
300 |
Send C-a
|
| 561 |
301 |
@end table
|
| ... | ... | |
| 566 |
306 |
@setfilename qemu
|
| 567 |
307 |
@settitle QEMU System Emulator
|
| 568 |
308 |
|
| 569 |
|
@c man begin SEEALSO
|
| 570 |
|
The HTML documentation of QEMU for more precise information and Linux
|
| 571 |
|
user mode emulator invocation.
|
| 572 |
|
@c man end
|
|
309 |
@c man begin SEEALSO
|
|
310 |
The HTML documentation of QEMU for more precise information and Linux
|
|
311 |
user mode emulator invocation.
|
|
312 |
@c man end
|
|
313 |
|
|
314 |
@c man begin AUTHOR
|
|
315 |
Fabrice Bellard
|
|
316 |
@c man end
|
|
317 |
|
|
318 |
@end ignore
|
|
319 |
|
|
320 |
@end ignore
|
|
321 |
|
|
322 |
|
|
323 |
@section QEMU Monitor
|
|
324 |
|
|
325 |
The QEMU monitor is used to give complex commands to the QEMU
|
|
326 |
emulator. You can use it to:
|
|
327 |
|
|
328 |
@itemize @minus
|
|
329 |
|
|
330 |
@item
|
|
331 |
Remove or insert removable medias images
|
|
332 |
(such as CD-ROM or floppies)
|
|
333 |
|
|
334 |
@item
|
|
335 |
Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
|
|
336 |
from a disk file.
|
|
337 |
|
|
338 |
@item Inspect the VM state without an external debugger.
|
|
339 |
|
|
340 |
@end itemize
|
|
341 |
|
|
342 |
@subsection Commands
|
|
343 |
|
|
344 |
The following commands are available:
|
|
345 |
|
|
346 |
@table @option
|
|
347 |
|
|
348 |
@item help or ? [cmd]
|
|
349 |
Show the help for all commands or just for command @var{cmd}.
|
|
350 |
|
|
351 |
@item commit
|
|
352 |
Commit changes to the disk images (if -snapshot is used)
|
|
353 |
|
|
354 |
@item info subcommand
|
|
355 |
show various information about the system state
|
|
356 |
|
|
357 |
@table @option
|
|
358 |
@item info network
|
|
359 |
show the network state
|
|
360 |
@item info block
|
|
361 |
show the block devices
|
|
362 |
@item info registers
|
|
363 |
show the cpu registers
|
|
364 |
@item info history
|
|
365 |
show the command line history
|
|
366 |
@end table
|
|
367 |
|
|
368 |
@item q or quit
|
|
369 |
Quit the emulator.
|
|
370 |
|
|
371 |
@item eject [-f] device
|
|
372 |
Eject a removable media (use -f to force it).
|
|
373 |
|
|
374 |
@item change device filename
|
|
375 |
Change a removable media.
|
|
376 |
|
|
377 |
@item screendump filename
|
|
378 |
Save screen into PPM image @var{filename}.
|
|
379 |
|
|
380 |
@item log item1[,...]
|
|
381 |
Activate logging of the specified items to @file{/tmp/qemu.log}.
|
|
382 |
|
|
383 |
@item savevm filename
|
|
384 |
Save the whole virtual machine state to @var{filename}.
|
|
385 |
|
|
386 |
@item loadvm filename
|
|
387 |
Restore the whole virtual machine state from @var{filename}.
|
|
388 |
|
|
389 |
@item stop
|
|
390 |
Stop emulation.
|
|
391 |
|
|
392 |
@item c or cont
|
|
393 |
Resume emulation.
|
|
394 |
|
|
395 |
@item gdbserver [port]
|
|
396 |
Start gdbserver session (default port=1234)
|
|
397 |
|
|
398 |
@item x/fmt addr
|
|
399 |
Virtual memory dump starting at @var{addr}.
|
|
400 |
|
|
401 |
@item xp /fmt addr
|
|
402 |
Physical memory dump starting at @var{addr}.
|
|
403 |
|
|
404 |
@var{fmt} is a format which tells the command how to format the
|
|
405 |
data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
|
|
406 |
|
|
407 |
@table @var
|
|
408 |
@item count
|
|
409 |
is the number of items to be dumped.
|
|
410 |
|
|
411 |
@item format
|
|
412 |
can be x (hexa), d (signed decimal), u (unsigned decimal), o (octal),
|
|
413 |
c (char) or i (asm instruction).
|
|
414 |
|
|
415 |
@item size
|
|
416 |
can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits)
|
|
417 |
|
|
418 |
@end table
|
|
419 |
|
|
420 |
Examples:
|
|
421 |
@itemize
|
|
422 |
@item
|
|
423 |
Dump 10 instructions at the current instruction pointer:
|
|
424 |
@example
|
|
425 |
(qemu) x/10i $eip
|
|
426 |
0x90107063: ret
|
|
427 |
0x90107064: sti
|
|
428 |
0x90107065: lea 0x0(%esi,1),%esi
|
|
429 |
0x90107069: lea 0x0(%edi,1),%edi
|
|
430 |
0x90107070: ret
|
|
431 |
0x90107071: jmp 0x90107080
|
|
432 |
0x90107073: nop
|
|
433 |
0x90107074: nop
|
|
434 |
0x90107075: nop
|
|
435 |
0x90107076: nop
|
|
436 |
@end example
|
|
437 |
|
|
438 |
@item
|
|
439 |
Dump 80 16 bit values at the start of the video memory.
|
|
440 |
@example
|
|
441 |
(qemu) xp/80hx 0xb8000
|
|
442 |
0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
|
|
443 |
0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
|
|
444 |
0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
|
|
445 |
0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
|
|
446 |
0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
|
|
447 |
0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
|
|
448 |
0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
|
|
449 |
0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
|
|
450 |
0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
|
|
451 |
0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
|
|
452 |
@end example
|
|
453 |
@end itemize
|
|
454 |
|
|
455 |
@item p or print/fmt expr
|
|
456 |
|
|
457 |
Print expression value. Only the @var{format} part of @var{fmt} is
|
|
458 |
used.
|
| 573 |
459 |
|
| 574 |
|
@c man begin AUTHOR
|
| 575 |
|
Fabrice Bellard
|
| 576 |
|
@c man end
|
|
460 |
@end table
|
| 577 |
461 |
|
| 578 |
|
@end ignore
|
|
462 |
@subsection Integer expressions
|
|
463 |
|
|
464 |
The monitor understands integers expressions for every integer
|
|
465 |
argument. You can use register names to get the value of specifics
|
|
466 |
CPU registers by prefixing them with @emph{$}.
|
| 579 |
467 |
|
| 580 |
|
@end ignore
|
| 581 |
468 |
@node disk_images
|
| 582 |
469 |
@section Disk Images
|
| 583 |
470 |
|
| ... | ... | |
| 649 |
536 |
the real one. To know it, use the @code{ls -ls} command.
|
| 650 |
537 |
@end enumerate
|
| 651 |
538 |
|
|
539 |
@section Direct Linux Boot and Network emulation
|
|
540 |
|
|
541 |
This section explains how to launch a Linux kernel inside QEMU without
|
|
542 |
having to make a full bootable image. It is very useful for fast Linux
|
|
543 |
kernel testing. The QEMU network configuration is also explained.
|
|
544 |
|
|
545 |
@enumerate
|
|
546 |
@item
|
|
547 |
Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
|
|
548 |
kernel and a disk image.
|
|
549 |
|
|
550 |
@item Optional: If you want network support (for example to launch X11 examples), you
|
|
551 |
must copy the script @file{qemu-ifup} in @file{/etc} and configure
|
|
552 |
properly @code{sudo} so that the command @code{ifconfig} contained in
|
|
553 |
@file{qemu-ifup} can be executed as root. You must verify that your host
|
|
554 |
kernel supports the TUN/TAP network interfaces: the device
|
|
555 |
@file{/dev/net/tun} must be present.
|
|
556 |
|
|
557 |
When network is enabled, there is a virtual network connection between
|
|
558 |
the host kernel and the emulated kernel. The emulated kernel is seen
|
|
559 |
from the host kernel at IP address 172.20.0.2 and the host kernel is
|
|
560 |
seen from the emulated kernel at IP address 172.20.0.1.
|
|
561 |
|
|
562 |
@item Launch @code{qemu.sh}. You should have the following output:
|
|
563 |
|
|
564 |
@example
|
|
565 |
> ./qemu.sh
|
|
566 |
Connected to host network interface: tun0
|
|
567 |
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
|
|
568 |
BIOS-provided physical RAM map:
|
|
569 |
BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
|
|
570 |
BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
|
|
571 |
32MB LOWMEM available.
|
|
572 |
On node 0 totalpages: 8192
|
|
573 |
zone(0): 4096 pages.
|
|
574 |
zone(1): 4096 pages.
|
|
575 |
zone(2): 0 pages.
|
|
576 |
Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0
|
|
577 |
ide_setup: ide2=noprobe
|
|
578 |
ide_setup: ide3=noprobe
|
|
579 |
ide_setup: ide4=noprobe
|
|
580 |
ide_setup: ide5=noprobe
|
|
581 |
Initializing CPU#0
|
|
582 |
Detected 2399.621 MHz processor.
|
|
583 |
Console: colour EGA 80x25
|
|
584 |
Calibrating delay loop... 4744.80 BogoMIPS
|
|
585 |
Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem)
|
|
586 |
Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
|
|
587 |
Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
|
|
588 |
Mount cache hash table entries: 512 (order: 0, 4096 bytes)
|
|
589 |
Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
|
|
590 |
Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
|
|
591 |
CPU: Intel Pentium Pro stepping 03
|
|
592 |
Checking 'hlt' instruction... OK.
|
|
593 |
POSIX conformance testing by UNIFIX
|
|
594 |
Linux NET4.0 for Linux 2.4
|
|
595 |
Based upon Swansea University Computer Society NET3.039
|
|
596 |
Initializing RT netlink socket
|
|
597 |
apm: BIOS not found.
|
|
598 |
Starting kswapd
|
|
599 |
Journalled Block Device driver loaded
|
|
600 |
Detected PS/2 Mouse Port.
|
|
601 |
pty: 256 Unix98 ptys configured
|
|
602 |
Serial driver version 5.05c (2001-07-08) with no serial options enabled
|
|
603 |
ttyS00 at 0x03f8 (irq = 4) is a 16450
|
|
604 |
ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com)
|
|
605 |
Last modified Nov 1, 2000 by Paul Gortmaker
|
|
606 |
NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
|
|
607 |
eth0: NE2000 found at 0x300, using IRQ 9.
|
|
608 |
RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
|
|
609 |
Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
|
|
610 |
ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
|
|
611 |
hda: QEMU HARDDISK, ATA DISK drive
|
|
612 |
ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
|
|
613 |
hda: attached ide-disk driver.
|
|
614 |
hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
|
|
615 |
Partition check:
|
|
616 |
hda:
|
|
617 |
Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
|
|
618 |
NET4: Linux TCP/IP 1.0 for NET4.0
|
|
619 |
IP Protocols: ICMP, UDP, TCP, IGMP
|
|
620 |
IP: routing cache hash table of 512 buckets, 4Kbytes
|
|
621 |
TCP: Hash tables configured (established 2048 bind 4096)
|
|
622 |
NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
|
|
623 |
EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
|
|
624 |
VFS: Mounted root (ext2 filesystem).
|
|
625 |
Freeing unused kernel memory: 64k freed
|
|
626 |
|
|
627 |
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
|
|
628 |
|
|
629 |
QEMU Linux test distribution (based on Redhat 9)
|
|
630 |
|
|
631 |
Type 'exit' to halt the system
|
|
632 |
|
|
633 |
sh-2.05b#
|
|
634 |
@end example
|
|
635 |
|
|
636 |
@item
|
|
637 |
Then you can play with the kernel inside the virtual serial console. You
|
|
638 |
can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help
|
|
639 |
about the keys you can type inside the virtual serial console. In
|
|
640 |
particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as
|
|
641 |
the Magic SysRq key.
|
|
642 |
|
|
643 |
@item
|
|
644 |
If the network is enabled, launch the script @file{/etc/linuxrc} in the
|
|
645 |
emulator (don't forget the leading dot):
|
|
646 |
@example
|
|
647 |
. /etc/linuxrc
|
|
648 |
@end example
|
|
649 |
|
|
650 |
Then enable X11 connections on your PC from the emulated Linux:
|
|
651 |
@example
|
|
652 |
xhost +172.20.0.2
|
|
653 |
@end example
|
|
654 |
|
|
655 |
You can now launch @file{xterm} or @file{xlogo} and verify that you have
|
|
656 |
a real Virtual Linux system !
|
|
657 |
|
|
658 |
@end enumerate
|
|
659 |
|
|
660 |
NOTES:
|
|
661 |
@enumerate
|
|
662 |
@item
|
|
663 |
A 2.5.74 kernel is also included in the archive. Just
|
|
664 |
replace the bzImage in qemu.sh to try it.
|
|
665 |
|
|
666 |
@item
|
|
667 |
qemu-fast creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the
|
|
668 |
default) containing all the simulated PC memory. If possible, try to use
|
|
669 |
a temporary directory using the tmpfs filesystem to avoid too many
|
|
670 |
unnecessary disk accesses.
|
|
671 |
|
|
672 |
@item
|
|
673 |
In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
|
|
674 |
qemu. qemu will automatically exit when the Linux shutdown is done.
|
|
675 |
|
|
676 |
@item
|
|
677 |
You can boot slightly faster by disabling the probe of non present IDE
|
|
678 |
interfaces. To do so, add the following options on the kernel command
|
|
679 |
line:
|
|
680 |
@example
|
|
681 |
ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
|
|
682 |
@end example
|
|
683 |
|
|
684 |
@item
|
|
685 |
The example disk image is a modified version of the one made by Kevin
|
|
686 |
Lawton for the plex86 Project (@url{www.plex86.org}).
|
|
687 |
|
|
688 |
@end enumerate
|
|
689 |
|
| 652 |
690 |
@node linux_compile
|
| 653 |
691 |
@section Linux Kernel Compilation
|
| 654 |
692 |
|
| 655 |
693 |
You can use any linux kernel with QEMU. However, if you want to use
|
| 656 |
|
@code{qemu-fast} to get maximum performances, you should make the
|
| 657 |
|
following changes to the Linux kernel (only 2.4.x and 2.5.x were
|
| 658 |
|
tested):
|
|
694 |
@code{qemu-fast} to get maximum performances, you must use a modified
|
|
695 |
guest kernel. If you are using a 2.6 guest kernel, you can use
|
|
696 |
directly the patch @file{linux-2.6-qemu-fast.patch} made by Rusty
|
|
697 |
Russel available in the QEMU source archive. Otherwise, you can make the
|
|
698 |
following changes @emph{by hand} to the Linux kernel:
|
| 659 |
699 |
|
| 660 |
700 |
@enumerate
|
| 661 |
701 |
@item
|
| ... | ... | |
| 694 |
734 |
use an SMP kernel with QEMU, it only supports one CPU.
|
| 695 |
735 |
|
| 696 |
736 |
@item
|
| 697 |
|
If you are not using a 2.5 kernel as host kernel but if you use a target
|
| 698 |
|
2.5 kernel, you must also ensure that the 'HZ' define is set to 100
|
|
737 |
If you are not using a 2.6 kernel as host kernel but if you use a target
|
|
738 |
2.6 kernel, you must also ensure that the 'HZ' define is set to 100
|
| 699 |
739 |
(1000 is the default) as QEMU cannot currently emulate timers at
|
| 700 |
|
frequencies greater than 100 Hz on host Linux systems < 2.5. In
|
|
740 |
frequencies greater than 100 Hz on host Linux systems < 2.6. In
|
| 701 |
741 |
@file{include/asm/param.h}, replace:
|
| 702 |
742 |
|
| 703 |
743 |
@example
|
| ... | ... | |
| 762 |
802 |
@code{x/10i $cs*16+*eip} to dump the code at the PC position.
|
| 763 |
803 |
@end enumerate
|
| 764 |
804 |
|
| 765 |
|
@chapter QEMU Internals
|
| 766 |
|
|
| 767 |
|
@section QEMU compared to other emulators
|
| 768 |
|
|
| 769 |
|
Like bochs [3], QEMU emulates an x86 CPU. But QEMU is much faster than
|
| 770 |
|
bochs as it uses dynamic compilation and because it uses the host MMU to
|
| 771 |
|
simulate the x86 MMU. The downside is that currently the emulation is
|
| 772 |
|
not as accurate as bochs (for example, you cannot currently run Windows
|
| 773 |
|
inside QEMU).
|
| 774 |
|
|
| 775 |
|
Like Valgrind [2], QEMU does user space emulation and dynamic
|
| 776 |
|
translation. Valgrind is mainly a memory debugger while QEMU has no
|
| 777 |
|
support for it (QEMU could be used to detect out of bound memory
|
| 778 |
|
accesses as Valgrind, but it has no support to track uninitialised data
|
| 779 |
|
as Valgrind does). The Valgrind dynamic translator generates better code
|
| 780 |
|
than QEMU (in particular it does register allocation) but it is closely
|
| 781 |
|
tied to an x86 host and target and has no support for precise exceptions
|
| 782 |
|
and system emulation.
|
| 783 |
|
|
| 784 |
|
EM86 [4] is the closest project to user space QEMU (and QEMU still uses
|
| 785 |
|
some of its code, in particular the ELF file loader). EM86 was limited
|
| 786 |
|
to an alpha host and used a proprietary and slow interpreter (the
|
| 787 |
|
interpreter part of the FX!32 Digital Win32 code translator [5]).
|
| 788 |
|
|
| 789 |
|
TWIN [6] is a Windows API emulator like Wine. It is less accurate than
|
| 790 |
|
Wine but includes a protected mode x86 interpreter to launch x86 Windows
|
| 791 |
|
executables. Such an approach as greater potential because most of the
|
| 792 |
|
Windows API is executed natively but it is far more difficult to develop
|
| 793 |
|
because all the data structures and function parameters exchanged
|
| 794 |
|
between the API and the x86 code must be converted.
|
| 795 |
|
|
| 796 |
|
User mode Linux [7] was the only solution before QEMU to launch a Linux
|
| 797 |
|
kernel as a process while not needing any host kernel patches. However,
|
| 798 |
|
user mode Linux requires heavy kernel patches while QEMU accepts
|
| 799 |
|
unpatched Linux kernels. It would be interesting to compare the
|
| 800 |
|
performance of the two approaches.
|
| 801 |
|
|
| 802 |
|
The new Plex86 [8] PC virtualizer is done in the same spirit as the QEMU
|
| 803 |
|
system emulator. It requires a patched Linux kernel to work (you cannot
|
| 804 |
|
launch the same kernel on your PC), but the patches are really small. As
|
| 805 |
|
it is a PC virtualizer (no emulation is done except for some priveledged
|
| 806 |
|
instructions), it has the potential of being faster than QEMU. The
|
| 807 |
|
downside is that a complicated (and potentially unsafe) host kernel
|
| 808 |
|
patch is needed.
|
| 809 |
|
|
| 810 |
|
@section Portable dynamic translation
|
| 811 |
|
|
| 812 |
|
QEMU is a dynamic translator. When it first encounters a piece of code,
|
| 813 |
|
it converts it to the host instruction set. Usually dynamic translators
|
| 814 |
|
are very complicated and highly CPU dependent. QEMU uses some tricks
|
| 815 |
|
which make it relatively easily portable and simple while achieving good
|
| 816 |
|
performances.
|
| 817 |
|
|
| 818 |
|
The basic idea is to split every x86 instruction into fewer simpler
|
| 819 |
|
instructions. Each simple instruction is implemented by a piece of C
|
| 820 |
|
code (see @file{op-i386.c}). Then a compile time tool (@file{dyngen})
|
| 821 |
|
takes the corresponding object file (@file{op-i386.o}) to generate a
|
| 822 |
|
dynamic code generator which concatenates the simple instructions to
|
| 823 |
|
build a function (see @file{op-i386.h:dyngen_code()}).
|
| 824 |
|
|
| 825 |
|
In essence, the process is similar to [1], but more work is done at
|
| 826 |
|
compile time.
|
| 827 |
|
|
| 828 |
|
A key idea to get optimal performances is that constant parameters can
|
| 829 |
|
be passed to the simple operations. For that purpose, dummy ELF
|
| 830 |
|
relocations are generated with gcc for each constant parameter. Then,
|
| 831 |
|
the tool (@file{dyngen}) can locate the relocations and generate the
|
| 832 |
|
appriopriate C code to resolve them when building the dynamic code.
|
| 833 |
|
|
| 834 |
|
That way, QEMU is no more difficult to port than a dynamic linker.
|
| 835 |
|
|
| 836 |
|
To go even faster, GCC static register variables are used to keep the
|
| 837 |
|
state of the virtual CPU.
|
| 838 |
|
|
| 839 |
|
@section Register allocation
|
| 840 |
|
|
| 841 |
|
Since QEMU uses fixed simple instructions, no efficient register
|
| 842 |
|
allocation can be done. However, because RISC CPUs have a lot of
|
| 843 |
|
register, most of the virtual CPU state can be put in registers without
|
| 844 |
|
doing complicated register allocation.
|
| 845 |
|
|
| 846 |
|
@section Condition code optimisations
|
| 847 |
|
|
| 848 |
|
Good CPU condition codes emulation (@code{EFLAGS} register on x86) is a
|
| 849 |
|
critical point to get good performances. QEMU uses lazy condition code
|
| 850 |
|
evaluation: instead of computing the condition codes after each x86
|
| 851 |
|
instruction, it just stores one operand (called @code{CC_SRC}), the
|
| 852 |
|
result (called @code{CC_DST}) and the type of operation (called
|
| 853 |
|
@code{CC_OP}).
|
| 854 |
|
|
| 855 |
|
@code{CC_OP} is almost never explicitely set in the generated code
|
| 856 |
|
because it is known at translation time.
|
| 857 |
|
|
| 858 |
|
In order to increase performances, a backward pass is performed on the
|
| 859 |
|
generated simple instructions (see
|
| 860 |
|
@code{translate-i386.c:optimize_flags()}). When it can be proved that
|
| 861 |
|
the condition codes are not needed by the next instructions, no
|
| 862 |
|
condition codes are computed at all.
|
| 863 |
|
|
| 864 |
|
@section CPU state optimisations
|
| 865 |
|
|
| 866 |
|
The x86 CPU has many internal states which change the way it evaluates
|
| 867 |
|
instructions. In order to achieve a good speed, the translation phase
|
| 868 |
|
considers that some state information of the virtual x86 CPU cannot
|
| 869 |
|
change in it. For example, if the SS, DS and ES segments have a zero
|
| 870 |
|
base, then the translator does not even generate an addition for the
|
| 871 |
|
segment base.
|
| 872 |
|
|
| 873 |
|
[The FPU stack pointer register is not handled that way yet].
|
| 874 |
|
|
| 875 |
|
@section Translation cache
|
| 876 |
|
|
| 877 |
|
A 2MByte cache holds the most recently used translations. For
|
| 878 |
|
simplicity, it is completely flushed when it is full. A translation unit
|
| 879 |
|
contains just a single basic block (a block of x86 instructions
|
| 880 |
|
terminated by a jump or by a virtual CPU state change which the
|
| 881 |
|
translator cannot deduce statically).
|
| 882 |
|
|
| 883 |
|
@section Direct block chaining
|
| 884 |
|
|
| 885 |
|
After each translated basic block is executed, QEMU uses the simulated
|
| 886 |
|
Program Counter (PC) and other cpu state informations (such as the CS
|
| 887 |
|
segment base value) to find the next basic block.
|
| 888 |
|
|
| 889 |
|
In order to accelerate the most common cases where the new simulated PC
|
| 890 |
|
is known, QEMU can patch a basic block so that it jumps directly to the
|
| 891 |
|
next one.
|
| 892 |
|
|
| 893 |
|
The most portable code uses an indirect jump. An indirect jump makes it
|
| 894 |
|
easier to make the jump target modification atomic. On some
|
| 895 |
|
architectures (such as PowerPC), the @code{JUMP} opcode is directly
|
| 896 |
|
patched so that the block chaining has no overhead.
|
| 897 |
|
|
| 898 |
|
@section Self-modifying code and translated code invalidation
|
| 899 |
|
|
| 900 |
|
Self-modifying code is a special challenge in x86 emulation because no
|
| 901 |
|
instruction cache invalidation is signaled by the application when code
|
| 902 |
|
is modified.
|
| 903 |
|
|
| 904 |
|
When translated code is generated for a basic block, the corresponding
|
| 905 |
|
host page is write protected if it is not already read-only (with the
|
| 906 |
|
system call @code{mprotect()}). Then, if a write access is done to the
|
| 907 |
|
page, Linux raises a SEGV signal. QEMU then invalidates all the
|
| 908 |
|
translated code in the page and enables write accesses to the page.
|
| 909 |
|
|
| 910 |
|
Correct translated code invalidation is done efficiently by maintaining
|
| 911 |
|
a linked list of every translated block contained in a given page. Other
|
| 912 |
|
linked lists are also maintained to undo direct block chaining.
|
| 913 |
|
|
| 914 |
|
Although the overhead of doing @code{mprotect()} calls is important,
|
| 915 |
|
most MSDOS programs can be emulated at reasonnable speed with QEMU and
|
| 916 |
|
DOSEMU.
|
| 917 |
|
|
| 918 |
|
Note that QEMU also invalidates pages of translated code when it detects
|
| 919 |
|
that memory mappings are modified with @code{mmap()} or @code{munmap()}.
|
| 920 |
|
|
| 921 |
|
@section Exception support
|
| 922 |
|
|
| 923 |
|
longjmp() is used when an exception such as division by zero is
|
| 924 |
|
encountered.
|
| 925 |
|
|
| 926 |
|
The host SIGSEGV and SIGBUS signal handlers are used to get invalid
|
| 927 |
|
memory accesses. The exact CPU state can be retrieved because all the
|
| 928 |
|
x86 registers are stored in fixed host registers. The simulated program
|
| 929 |
|
counter is found by retranslating the corresponding basic block and by
|
| 930 |
|
looking where the host program counter was at the exception point.
|
| 931 |
|
|
| 932 |
|
The virtual CPU cannot retrieve the exact @code{EFLAGS} register because
|
| 933 |
|
in some cases it is not computed because of condition code
|
| 934 |
|
optimisations. It is not a big concern because the emulated code can
|
| 935 |
|
still be restarted in any cases.
|
| 936 |
|
|
| 937 |
|
@section Linux system call translation
|
| 938 |
|
|
| 939 |
|
QEMU includes a generic system call translator for Linux. It means that
|
| 940 |
|
the parameters of the system calls can be converted to fix the
|
| 941 |
|
endianness and 32/64 bit issues. The IOCTLs are converted with a generic
|
| 942 |
|
type description system (see @file{ioctls.h} and @file{thunk.c}).
|
|
805 |
@chapter QEMU User space emulator invocation
|
| 943 |
806 |
|
| 944 |
|
QEMU supports host CPUs which have pages bigger than 4KB. It records all
|
| 945 |
|
the mappings the process does and try to emulated the @code{mmap()}
|
| 946 |
|
system calls in cases where the host @code{mmap()} call would fail
|
| 947 |
|
because of bad page alignment.
|
|
807 |
@section Quick Start
|
| 948 |
808 |
|
| 949 |
|
@section Linux signals
|
|
809 |
In order to launch a Linux process, QEMU needs the process executable
|
|
810 |
itself and all the target (x86) dynamic libraries used by it.
|
| 950 |
811 |
|
| 951 |
|
Normal and real-time signals are queued along with their information
|
| 952 |
|
(@code{siginfo_t}) as it is done in the Linux kernel. Then an interrupt
|