1 |
\input texinfo @c -*- texinfo -*- |
\input texinfo @c -*- texinfo -*- |
2 |
|
|
3 |
|
@iftex |
4 |
@settitle QEMU CPU Emulator Reference Documentation |
@settitle QEMU CPU Emulator Reference Documentation |
5 |
@titlepage |
@titlepage |
6 |
@sp 7 |
@sp 7 |
7 |
@center @titlefont{QEMU CPU Emulator Reference Documentation} |
@center @titlefont{QEMU CPU Emulator Reference Documentation} |
8 |
@sp 3 |
@sp 3 |
9 |
@end titlepage |
@end titlepage |
10 |
|
@end iftex |
11 |
|
|
12 |
@chapter Introduction |
@chapter Introduction |
13 |
|
|
18 |
CPUs. |
CPUs. |
19 |
|
|
20 |
QEMU has two operating modes: |
QEMU has two operating modes: |
21 |
@itemize |
|
22 |
@item User mode emulation. In this mode, QEMU can launch Linux processes |
@itemize @minus |
23 |
|
|
24 |
|
@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 |
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 |
because of endianness and 32/64 bit mismatches. The Wine Windows API |
28 |
emulator (@url{http://www.winehq.org}) and the DOSEMU DOS emulator |
emulator (@url{http://www.winehq.org}) and the DOSEMU DOS emulator |
29 |
(@url{www.dosemu.org}) are the main targets for QEMU. |
(@url{www.dosemu.org}) are the main targets for QEMU. |
30 |
|
|
31 |
@item Full system emulation. In this mode, QEMU emulates a full |
@item |
32 |
|
Full system emulation. In this mode, QEMU emulates a full |
33 |
system, including a processor and various peripherials. Currently, it |
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 |
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 |
enables easier testing and debugging of system code. It can also be |
134 |
|
|
135 |
@end itemize |
@end itemize |
136 |
|
|
137 |
|
@section SPARC emulation |
138 |
|
|
139 |
|
The SPARC emulation is currently in development. |
140 |
|
|
141 |
@chapter QEMU User space emulator invocation |
@chapter QEMU User space emulator invocation |
142 |
|
|
143 |
@section Quick Start |
@section Quick Start |
154 |
libraries: |
libraries: |
155 |
|
|
156 |
@example |
@example |
157 |
qemu -L / /bin/ls |
qemu-i386 -L / /bin/ls |
158 |
@end example |
@end example |
159 |
|
|
160 |
@code{-L /} tells that the x86 dynamic linker must be searched with a |
@code{-L /} tells that the x86 dynamic linker must be searched with a |
163 |
@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: |
164 |
|
|
165 |
@example |
@example |
166 |
qemu -L / qemu -L / /bin/ls |
qemu-i386 -L / qemu-i386 -L / /bin/ls |
167 |
@end example |
@end example |
168 |
|
|
169 |
@item On non x86 CPUs, you need first to download at least an x86 glibc |
@item On non x86 CPUs, you need first to download at least an x86 glibc |
177 |
Then you can launch the precompiled @file{ls} x86 executable: |
Then you can launch the precompiled @file{ls} x86 executable: |
178 |
|
|
179 |
@example |
@example |
180 |
qemu /usr/local/qemu-i386/bin/ls-i386 |
qemu-i386 /usr/local/qemu-i386/bin/ls-i386 |
181 |
@end example |
@end example |
182 |
You can look at @file{/usr/local/qemu-i386/bin/qemu-conf.sh} so that |
You can look at @file{/usr/local/qemu-i386/bin/qemu-conf.sh} so that |
183 |
QEMU is automatically launched by the Linux kernel when you try to |
QEMU is automatically launched by the Linux kernel when you try to |
186 |
|
|
187 |
@item The x86 version of QEMU is also included. You can try weird things such as: |
@item The x86 version of QEMU is also included. You can try weird things such as: |
188 |
@example |
@example |
189 |
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 |
190 |
@end example |
@end example |
191 |
|
|
192 |
@end itemize |
@end itemize |
200 |
able to do: |
able to do: |
201 |
|
|
202 |
@example |
@example |
203 |
qemu /usr/local/qemu-i386/bin/ls-i386 |
qemu-i386 /usr/local/qemu-i386/bin/ls-i386 |
204 |
@end example |
@end example |
205 |
|
|
206 |
@item Download the binary x86 Wine install |
@item Download the binary x86 Wine install |
213 |
@item Then you can try the example @file{putty.exe}: |
@item Then you can try the example @file{putty.exe}: |
214 |
|
|
215 |
@example |
@example |
216 |
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 |
217 |
@end example |
@end example |
218 |
|
|
219 |
@end itemize |
@end itemize |
221 |
@section Command line options |
@section Command line options |
222 |
|
|
223 |
@example |
@example |
224 |
usage: qemu [-h] [-d] [-L path] [-s size] program [arguments...] |
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...] |
225 |
@end example |
@end example |
226 |
|
|
227 |
@table @option |
@table @option |
244 |
|
|
245 |
@chapter QEMU System emulator invocation |
@chapter QEMU System emulator invocation |
246 |
|
|
247 |
|
@section Introduction |
248 |
|
|
249 |
|
@c man begin DESCRIPTION |
250 |
|
|
251 |
|
The QEMU System emulator simulates a complete PC. It can either boot |
252 |
|
directly a Linux kernel (without any BIOS or boot loader) or boot like a |
253 |
|
real PC with the included BIOS. |
254 |
|
|
255 |
|
In order to meet specific user needs, two versions of QEMU are |
256 |
|
available: |
257 |
|
|
258 |
|
@enumerate |
259 |
|
|
260 |
|
@item |
261 |
|
@code{qemu} uses the host Memory Management Unit (MMU) to simulate |
262 |
|
the x86 MMU. It is @emph{fast} but has limitations because the whole 4 GB |
263 |
|
address space cannot be used and some memory mapped peripherials |
264 |
|
cannot be emulated accurately yet. Therefore, a specific Linux kernel |
265 |
|
must be used (@xref{linux_compile}). |
266 |
|
|
267 |
|
@item |
268 |
|
@code{qemu-softmmu} uses a software MMU. It is about @emph{two times |
269 |
|
slower} but gives a more accurate emulation. (XXX: Linux cannot be ran |
270 |
|
unpatched yet). |
271 |
|
|
272 |
|
@end enumerate |
273 |
|
|
274 |
|
QEMU emulates the following PC peripherials: |
275 |
|
|
276 |
|
@itemize @minus |
277 |
|
@item |
278 |
|
VGA (hardware level, including all non standard modes) |
279 |
|
@item |
280 |
|
PS/2 mouse and keyboard |
281 |
|
@item |
282 |
|
IDE disk interface (port=0x1f0, irq=14) |
283 |
|
@item |
284 |
|
NE2000 network adapter (port=0x300, irq=9) |
285 |
|
@item |
286 |
|
Serial port (port=0x3f8, irq=4) |
287 |
|
@item |
288 |
|
PIC (interrupt controler) |
289 |
|
@item |
290 |
|
PIT (timers) |
291 |
|
@item |
292 |
|
CMOS memory |
293 |
|
@end itemize |
294 |
|
|
295 |
|
@c man end |
296 |
|
|
297 |
@section Quick Start |
@section Quick Start |
298 |
|
|
299 |
This section explains how to launch a Linux kernel inside QEMU. |
Download the linux image (@file{linux.img}) and type: |
300 |
|
|
301 |
|
@example |
302 |
|
qemu-softmmu linux.img |
303 |
|
@end example |
304 |
|
|
305 |
|
Linux should boot and give you a prompt. |
306 |
|
|
307 |
|
@section Direct Linux Boot and Network emulation |
308 |
|
|
309 |
|
This section explains how to launch a Linux kernel inside QEMU without |
310 |
|
having to make a full bootable image. It is very useful for fast Linux |
311 |
|
kernel testing. The QEMU network configuration is also explained. |
312 |
|
|
313 |
@enumerate |
@enumerate |
314 |
@item |
@item |
315 |
Download the archive @file{vl-test-xxx.tar.gz} containing a Linux |
Download the archive @file{linux-test-xxx.tar.gz} containing a Linux |
316 |
kernel and a disk image. The archive also contains a precompiled |
kernel and a disk image. |
|
version of @file{vl}, the QEMU System emulator. |
|
317 |
|
|
318 |
@item Optional: If you want network support (for example to launch X11 examples), you |
@item Optional: If you want network support (for example to launch X11 examples), you |
319 |
must copy the script @file{vl-ifup} in @file{/etc} and configure |
must copy the script @file{qemu-ifup} in @file{/etc} and configure |
320 |
properly @code{sudo} so that the command @code{ifconfig} contained in |
properly @code{sudo} so that the command @code{ifconfig} contained in |
321 |
@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 |
322 |
kernel supports the TUN/TAP network interfaces: the device |
kernel supports the TUN/TAP network interfaces: the device |
323 |
@file{/dev/net/tun} must be present. |
@file{/dev/net/tun} must be present. |
324 |
|
|
327 |
from the host kernel at IP address 172.20.0.2 and the host kernel is |
from the host kernel at IP address 172.20.0.2 and the host kernel is |
328 |
seen from the emulated kernel at IP address 172.20.0.1. |
seen from the emulated kernel at IP address 172.20.0.1. |
329 |
|
|
330 |
@item Launch @code{vl.sh}. You should have the following output: |
@item Launch @code{qemu.sh}. You should have the following output: |
331 |
|
|
332 |
@example |
@example |
333 |
> ./vl.sh |
> ./qemu.sh |
334 |
connected to host network interface: tun0 |
connected to host network interface: tun0 |
335 |
Uncompressing Linux... Ok, booting the kernel. |
Uncompressing Linux... Ok, booting the kernel. |
336 |
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 |
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 |
420 |
NOTES: |
NOTES: |
421 |
@enumerate |
@enumerate |
422 |
@item |
@item |
423 |
A 2.5.74 kernel is also included in the vl-test archive. Just |
A 2.5.74 kernel is also included in the archive. Just |
424 |
replace the bzImage in vl.sh to try it. |
replace the bzImage in qemu.sh to try it. |
425 |
|
|
426 |
@item |
@item |
427 |
vl creates a temporary file in @var{$VLTMPDIR} (@file{/tmp} is the |
vl creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the |
428 |
default) containing all the simulated PC memory. If possible, try to use |
default) containing all the simulated PC memory. If possible, try to use |
429 |
a temporary directory using the tmpfs filesystem to avoid too many |
a temporary directory using the tmpfs filesystem to avoid too many |
430 |
unnecessary disk accesses. |
unnecessary disk accesses. |
450 |
@section Invocation |
@section Invocation |
451 |
|
|
452 |
@example |
@example |
453 |
usage: vl [options] bzImage [kernel parameters...] |
@c man begin SYNOPSIS |
454 |
|
usage: qemu [options] [disk_image] |
455 |
|
@c man end |
456 |
@end example |
@end example |
457 |
|
|
458 |
@file{bzImage} is a Linux kernel image. |
@c man begin OPTIONS |
459 |
|
@var{disk_image} is a raw hard image image for IDE hard disk 0. |
460 |
|
|
461 |
General options: |
General options: |
462 |
@table @option |
@table @option |
463 |
@item -hda file |
@item -hda file |
464 |
@item -hdb file |
@item -hdb file |
465 |
Use 'file' as hard disk 0 or 1 image (@xref{disk_images}). |
Use @var{file} as hard disk 0 or 1 image (@xref{disk_images}). |
466 |
|
|
467 |
@item -snapshot |
@item -snapshot |
468 |
|
|
479 |
corresponding to the virtual NE2000 card. |
corresponding to the virtual NE2000 card. |
480 |
|
|
481 |
@item -initrd file |
@item -initrd file |
482 |
Use 'file' as initial ram disk. |
Use @var{file} as initial ram disk. |
483 |
|
|
484 |
|
@item -tun-fd fd |
485 |
|
Assumes @var{fd} talks to tap/tun and use it. Read |
486 |
|
@url{http://bellard.org/qemu/tetrinet.html} to have an example of its |
487 |
|
use. |
488 |
|
|
489 |
|
@item -nographic |
490 |
|
|
491 |
|
Normally, QEMU uses SDL to display the VGA output. With this option, |
492 |
|
you can totally disable graphical output so that QEMU is a simple |
493 |
|
command line application. The emulated serial port is redirected on |
494 |
|
the console. Therefore, you can still use QEMU to debug a Linux kernel |
495 |
|
with a serial console. |
496 |
|
|
497 |
|
@end table |
498 |
|
|
499 |
|
Linux boot specific (does not require a full PC boot with a BIOS): |
500 |
|
@table @option |
501 |
|
|
502 |
|
@item -kernel bzImage |
503 |
|
Use @var{bzImage} as kernel image. |
504 |
|
|
505 |
|
@item -append cmdline |
506 |
|
Use @var{cmdline} as kernel command line |
507 |
|
|
508 |
|
@item -initrd file |
509 |
|
Use @var{file} as initial ram disk. |
510 |
|
|
511 |
@end table |
@end table |
512 |
|
|
513 |
Debug options: |
Debug options: |
514 |
@table @option |
@table @option |
515 |
@item -s |
@item -s |
516 |
Wait gdb connection to port 1234. |
Wait gdb connection to port 1234 (@xref{gdb_usage}). |
517 |
@item -p port |
@item -p port |
518 |
Change gdb connection port. |
Change gdb connection port. |
519 |
@item -d |
@item -d |
534 |
@item C-a C-a |
@item C-a C-a |
535 |
Send C-a |
Send C-a |
536 |
@end table |
@end table |
537 |
|
@c man end |
538 |
|
|
539 |
|
@ignore |
540 |
|
|
541 |
|
@setfilename qemu |
542 |
|
@settitle QEMU System Emulator |
543 |
|
|
544 |
|
@c man begin SEEALSO |
545 |
|
The HTML documentation of QEMU for more precise information and Linux |
546 |
|
user mode emulator invocation. |
547 |
|
@c man end |
548 |
|
|
549 |
|
@c man begin AUTHOR |
550 |
|
Fabrice Bellard |
551 |
|
@c man end |
552 |
|
|
553 |
|
@end ignore |
554 |
|
|
555 |
|
@end ignore |
556 |
@node disk_images |
@node disk_images |
557 |
@section Disk Images |
@section Disk Images |
558 |
|
|
586 |
To create a COW disk images, use the command: |
To create a COW disk images, use the command: |
587 |
|
|
588 |
@example |
@example |
589 |
vlmkcow -f myrawimage.bin mycowimage.cow |
qemu-mkcow -f myrawimage.bin mycowimage.cow |
590 |
@end example |
@end example |
591 |
|
|
592 |
@file{myrawimage.bin} is a raw image you want to use as original disk |
@file{myrawimage.bin} is a raw image you want to use as original disk |
593 |
image. It will never be written to. |
image. It will never be written to. |
594 |
|
|
595 |
@file{mycowimage.cow} is the COW disk image which is created by |
@file{mycowimage.cow} is the COW disk image which is created by |
596 |
@code{vlmkcow}. You can use it directly with the @option{-hdx} |
@code{qemu-mkcow}. You can use it directly with the @option{-hdx} |
597 |
options. You must not modify the original raw disk image if you use |
options. You must not modify the original raw disk image if you use |
598 |
COW images, as COW images only store the modified sectors from the raw |
COW images, as COW images only store the modified sectors from the raw |
599 |
disk image. QEMU stores the original raw disk image name and its |
disk image. QEMU stores the original raw disk image name and its |
609 |
using much disk space. Use: |
using much disk space. Use: |
610 |
|
|
611 |
@example |
@example |
612 |
vlmkcow mycowimage.cow 1024 |
qemu-mkcow mycowimage.cow 1024 |
613 |
@end example |
@end example |
614 |
|
|
615 |
to create a 1 gigabyte empty COW disk image. |
to create a 1 gigabyte empty COW disk image. |
624 |
the real one. To know it, use the @code{ls -ls} command. |
the real one. To know it, use the @code{ls -ls} command. |
625 |
@end enumerate |
@end enumerate |
626 |
|
|
627 |
|
@node linux_compile |
628 |
@section Linux Kernel Compilation |
@section Linux Kernel Compilation |
629 |
|
|
630 |
You should be able to use any kernel with QEMU provided you make the |
You should be able to use any kernel with QEMU provided you make the |
694 |
exactly the same kernel as you would boot on your PC (in |
exactly the same kernel as you would boot on your PC (in |
695 |
@file{arch/i386/boot/bzImage}). |
@file{arch/i386/boot/bzImage}). |
696 |
|
|
697 |
@section PC Emulation |
@node gdb_usage |
|
|
|
|
QEMU emulates the following PC peripherials: |
|
|
|
|
|
@itemize |
|
|
@item |
|
|
PIC (interrupt controler) |
|
|
@item |
|
|
PIT (timers) |
|
|
@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 |
|
|
IDE disk interface (port=0x1f0, irq=14) |
|
|
@end itemize |
|
|
|
|
698 |
@section GDB usage |
@section GDB usage |
699 |
|
|
700 |
QEMU has a primitive support to work with gdb, so that you can do |
QEMU has a primitive support to work with gdb, so that you can do |
701 |
'Ctrl-C' while the kernel is running and inspect its state. |
'Ctrl-C' while the virtual machine is running and inspect its state. |
702 |
|
|
703 |
In order to use gdb, launch vl with the '-s' option. It will wait for a |
In order to use gdb, launch vl with the '-s' option. It will wait for a |
704 |
gdb connection: |
gdb connection: |
725 |
|
|
726 |
WARNING: breakpoints and single stepping are not yet supported. |
WARNING: breakpoints and single stepping are not yet supported. |
727 |
|
|
728 |
|
Here are some useful tips in order to use gdb on system code: |
729 |
|
|
730 |
|
@enumerate |
731 |
|
@item |
732 |
|
Use @code{info reg} to display all the CPU registers. |
733 |
|
@item |
734 |
|
Use @code{x/10i $eip} to display the code at the PC position. |
735 |
|
@item |
736 |
|
Use @code{set architecture i8086} to dump 16 bit code. Then use |
737 |
|
@code{x/10i $cs*16+*eip} to dump the code at the PC position. |
738 |
|
@end enumerate |
739 |
|
|
740 |
@chapter QEMU Internals |
@chapter QEMU Internals |
741 |
|
|
742 |
@section QEMU compared to other emulators |
@section QEMU compared to other emulators |