Commit 1f673135acedadf942edb0c6c5238739313d718c
1 parent
aa455485
doc update
git-svn-id: svn://svn.savannah.nongnu.org/qemu/trunk@705 c046a42c-6fe2-441c-8c8c-71466251a162
Showing
5 changed files
with
1302 additions
and
670 deletions
Makefile
@@ -11,7 +11,7 @@ ifndef CONFIG_WIN32 | @@ -11,7 +11,7 @@ ifndef CONFIG_WIN32 | ||
11 | TOOLS=qemu-mkcow | 11 | TOOLS=qemu-mkcow |
12 | endif | 12 | endif |
13 | 13 | ||
14 | -all: dyngen$(EXESUF) $(TOOLS) qemu-doc.html qemu.1 | 14 | +all: dyngen$(EXESUF) $(TOOLS) qemu-doc.html qemu-tech.html qemu.1 |
15 | for d in $(TARGET_DIRS); do \ | 15 | for d in $(TARGET_DIRS); do \ |
16 | make -C $$d $@ || exit 1 ; \ | 16 | make -C $$d $@ || exit 1 ; \ |
17 | done | 17 | done |
@@ -61,7 +61,7 @@ TAGS: | @@ -61,7 +61,7 @@ TAGS: | ||
61 | etags *.[ch] tests/*.[ch] | 61 | etags *.[ch] tests/*.[ch] |
62 | 62 | ||
63 | # documentation | 63 | # documentation |
64 | -qemu-doc.html: qemu-doc.texi | 64 | +%.html: %.texi |
65 | texi2html -monolithic -number $< | 65 | texi2html -monolithic -number $< |
66 | 66 | ||
67 | qemu.1: qemu-doc.texi | 67 | qemu.1: qemu-doc.texi |
TODO
@@ -2,7 +2,6 @@ short term: | @@ -2,7 +2,6 @@ short term: | ||
2 | ---------- | 2 | ---------- |
3 | - handle fast timers + add explicit clocks | 3 | - handle fast timers + add explicit clocks |
4 | - OS/2 install bug | 4 | - OS/2 install bug |
5 | -- win 95 install bug | ||
6 | - handle Self Modifying Code even if modifying current TB (BE OS 5 install) | 5 | - handle Self Modifying Code even if modifying current TB (BE OS 5 install) |
7 | - physical memory cache (reduce qemu-fast address space size to about 32 MB) | 6 | - physical memory cache (reduce qemu-fast address space size to about 32 MB) |
8 | - better code fetch | 7 | - better code fetch |
linux-2.6-qemu-fast.patch
0 → 100644
1 | +diff -urpN --exclude TAGS -X /home/rusty/devel/kernel/kernel-patches/current-dontdiff --minimal .32324-linux-2.6.0/arch/i386/Kconfig .32324-linux-2.6.0.updated/arch/i386/Kconfig | ||
2 | +--- .32324-linux-2.6.0/arch/i386/Kconfig 2003-10-09 18:02:48.000000000 +1000 | ||
3 | ++++ .32324-linux-2.6.0.updated/arch/i386/Kconfig 2003-12-26 16:46:49.000000000 +1100 | ||
4 | +@@ -307,6 +307,14 @@ config X86_GENERIC | ||
5 | + when it has moderate overhead. This is intended for generic | ||
6 | + distributions kernels. | ||
7 | + | ||
8 | ++config QEMU | ||
9 | ++ bool "Kernel to run under QEMU" | ||
10 | ++ depends on EXPERIMENTAL | ||
11 | ++ help | ||
12 | ++ Select this if you want to boot the kernel inside qemu-fast, | ||
13 | ++ the non-mmu version of the x86 emulator. See | ||
14 | ++ <http://fabrice.bellard.free.fr/qemu/>. Say N. | ||
15 | ++ | ||
16 | + # | ||
17 | + # Define implied options from the CPU selection here | ||
18 | + # | ||
19 | +diff -urpN --exclude TAGS -X /home/rusty/devel/kernel/kernel-patches/current-dontdiff --minimal .32324-linux-2.6.0/arch/i386/kernel/Makefile .32324-linux-2.6.0.updated/arch/i386/kernel/Makefile | ||
20 | +--- .32324-linux-2.6.0/arch/i386/kernel/Makefile 2003-09-29 10:25:15.000000000 +1000 | ||
21 | ++++ .32324-linux-2.6.0.updated/arch/i386/kernel/Makefile 2003-12-26 16:46:49.000000000 +1100 | ||
22 | +@@ -46,12 +46,14 @@ quiet_cmd_syscall = SYSCALL $@ | ||
23 | + cmd_syscall = $(CC) -nostdlib $(SYSCFLAGS_$(@F)) \ | ||
24 | + -Wl,-T,$(filter-out FORCE,$^) -o $@ | ||
25 | + | ||
26 | ++export AFLAGS_vsyscall.lds.o += -P -C -U$(ARCH) | ||
27 | ++ | ||
28 | + vsyscall-flags = -shared -s -Wl,-soname=linux-gate.so.1 | ||
29 | + SYSCFLAGS_vsyscall-sysenter.so = $(vsyscall-flags) | ||
30 | + SYSCFLAGS_vsyscall-int80.so = $(vsyscall-flags) | ||
31 | + | ||
32 | + $(obj)/vsyscall-int80.so $(obj)/vsyscall-sysenter.so: \ | ||
33 | +-$(obj)/vsyscall-%.so: $(src)/vsyscall.lds $(obj)/vsyscall-%.o FORCE | ||
34 | ++$(obj)/vsyscall-%.so: $(src)/vsyscall.lds.s $(obj)/vsyscall-%.o FORCE | ||
35 | + $(call if_changed,syscall) | ||
36 | + | ||
37 | + # We also create a special relocatable object that should mirror the symbol | ||
38 | +@@ -62,5 +64,5 @@ $(obj)/built-in.o: $(obj)/vsyscall-syms. | ||
39 | + $(obj)/built-in.o: ld_flags += -R $(obj)/vsyscall-syms.o | ||
40 | + | ||
41 | + SYSCFLAGS_vsyscall-syms.o = -r | ||
42 | +-$(obj)/vsyscall-syms.o: $(src)/vsyscall.lds $(obj)/vsyscall-sysenter.o FORCE | ||
43 | ++$(obj)/vsyscall-syms.o: $(src)/vsyscall.lds.s $(obj)/vsyscall-sysenter.o FORCE | ||
44 | + $(call if_changed,syscall) | ||
45 | +diff -urpN --exclude TAGS -X /home/rusty/devel/kernel/kernel-patches/current-dontdiff --minimal .32324-linux-2.6.0/arch/i386/kernel/vmlinux.lds.S .32324-linux-2.6.0.updated/arch/i386/kernel/vmlinux.lds.S | ||
46 | +--- .32324-linux-2.6.0/arch/i386/kernel/vmlinux.lds.S 2003-09-22 10:27:28.000000000 +1000 | ||
47 | ++++ .32324-linux-2.6.0.updated/arch/i386/kernel/vmlinux.lds.S 2003-12-26 16:46:49.000000000 +1100 | ||
48 | +@@ -3,6 +3,7 @@ | ||
49 | + */ | ||
50 | + | ||
51 | + #include <asm-generic/vmlinux.lds.h> | ||
52 | ++#include <asm/page.h> | ||
53 | + | ||
54 | + OUTPUT_FORMAT("elf32-i386", "elf32-i386", "elf32-i386") | ||
55 | + OUTPUT_ARCH(i386) | ||
56 | +@@ -10,7 +11,7 @@ ENTRY(startup_32) | ||
57 | + jiffies = jiffies_64; | ||
58 | + SECTIONS | ||
59 | + { | ||
60 | +- . = 0xC0000000 + 0x100000; | ||
61 | ++ . = __PAGE_OFFSET + 0x100000; | ||
62 | + /* read-only */ | ||
63 | + _text = .; /* Text and read-only data */ | ||
64 | + .text : { | ||
65 | +diff -urpN --exclude TAGS -X /home/rusty/devel/kernel/kernel-patches/current-dontdiff --minimal .32324-linux-2.6.0/arch/i386/kernel/vsyscall.lds .32324-linux-2.6.0.updated/arch/i386/kernel/vsyscall.lds | ||
66 | +--- .32324-linux-2.6.0/arch/i386/kernel/vsyscall.lds 2003-09-22 10:07:26.000000000 +1000 | ||
67 | ++++ .32324-linux-2.6.0.updated/arch/i386/kernel/vsyscall.lds 1970-01-01 10:00:00.000000000 +1000 | ||
68 | +@@ -1,67 +0,0 @@ | ||
69 | +-/* | ||
70 | +- * Linker script for vsyscall DSO. The vsyscall page is an ELF shared | ||
71 | +- * object prelinked to its virtual address, and with only one read-only | ||
72 | +- * segment (that fits in one page). This script controls its layout. | ||
73 | +- */ | ||
74 | +- | ||
75 | +-/* This must match <asm/fixmap.h>. */ | ||
76 | +-VSYSCALL_BASE = 0xffffe000; | ||
77 | +- | ||
78 | +-SECTIONS | ||
79 | +-{ | ||
80 | +- . = VSYSCALL_BASE + SIZEOF_HEADERS; | ||
81 | +- | ||
82 | +- .hash : { *(.hash) } :text | ||
83 | +- .dynsym : { *(.dynsym) } | ||
84 | +- .dynstr : { *(.dynstr) } | ||
85 | +- .gnu.version : { *(.gnu.version) } | ||
86 | +- .gnu.version_d : { *(.gnu.version_d) } | ||
87 | +- .gnu.version_r : { *(.gnu.version_r) } | ||
88 | +- | ||
89 | +- /* This linker script is used both with -r and with -shared. | ||
90 | +- For the layouts to match, we need to skip more than enough | ||
91 | +- space for the dynamic symbol table et al. If this amount | ||
92 | +- is insufficient, ld -shared will barf. Just increase it here. */ | ||
93 | +- . = VSYSCALL_BASE + 0x400; | ||
94 | +- | ||
95 | +- .text : { *(.text) } :text =0x90909090 | ||
96 | +- | ||
97 | +- .eh_frame_hdr : { *(.eh_frame_hdr) } :text :eh_frame_hdr | ||
98 | +- .eh_frame : { KEEP (*(.eh_frame)) } :text | ||
99 | +- .dynamic : { *(.dynamic) } :text :dynamic | ||
100 | +- .useless : { | ||
101 | +- *(.got.plt) *(.got) | ||
102 | +- *(.data .data.* .gnu.linkonce.d.*) | ||
103 | +- *(.dynbss) | ||
104 | +- *(.bss .bss.* .gnu.linkonce.b.*) | ||
105 | +- } :text | ||
106 | +-} | ||
107 | +- | ||
108 | +-/* | ||
109 | +- * We must supply the ELF program headers explicitly to get just one | ||
110 | +- * PT_LOAD segment, and set the flags explicitly to make segments read-only. | ||
111 | +- */ | ||
112 | +-PHDRS | ||
113 | +-{ | ||
114 | +- text PT_LOAD FILEHDR PHDRS FLAGS(5); /* PF_R|PF_X */ | ||
115 | +- dynamic PT_DYNAMIC FLAGS(4); /* PF_R */ | ||
116 | +- eh_frame_hdr 0x6474e550; /* PT_GNU_EH_FRAME, but ld doesn't match the name */ | ||
117 | +-} | ||
118 | +- | ||
119 | +-/* | ||
120 | +- * This controls what symbols we export from the DSO. | ||
121 | +- */ | ||
122 | +-VERSION | ||
123 | +-{ | ||
124 | +- LINUX_2.5 { | ||
125 | +- global: | ||
126 | +- __kernel_vsyscall; | ||
127 | +- __kernel_sigreturn; | ||
128 | +- __kernel_rt_sigreturn; | ||
129 | +- | ||
130 | +- local: *; | ||
131 | +- }; | ||
132 | +-} | ||
133 | +- | ||
134 | +-/* The ELF entry point can be used to set the AT_SYSINFO value. */ | ||
135 | +-ENTRY(__kernel_vsyscall); | ||
136 | +diff -urpN --exclude TAGS -X /home/rusty/devel/kernel/kernel-patches/current-dontdiff --minimal .32324-linux-2.6.0/arch/i386/kernel/vsyscall.lds.S .32324-linux-2.6.0.updated/arch/i386/kernel/vsyscall.lds.S | ||
137 | +--- .32324-linux-2.6.0/arch/i386/kernel/vsyscall.lds.S 1970-01-01 10:00:00.000000000 +1000 | ||
138 | ++++ .32324-linux-2.6.0.updated/arch/i386/kernel/vsyscall.lds.S 2003-12-26 16:46:49.000000000 +1100 | ||
139 | +@@ -0,0 +1,67 @@ | ||
140 | ++/* | ||
141 | ++ * Linker script for vsyscall DSO. The vsyscall page is an ELF shared | ||
142 | ++ * object prelinked to its virtual address, and with only one read-only | ||
143 | ++ * segment (that fits in one page). This script controls its layout. | ||
144 | ++ */ | ||
145 | ++#include <asm/fixmap.h> | ||
146 | ++ | ||
147 | ++VSYSCALL_BASE = __FIXADDR_TOP - 0x1000; | ||
148 | ++ | ||
149 | ++SECTIONS | ||
150 | ++{ | ||
151 | ++ . = VSYSCALL_BASE + SIZEOF_HEADERS; | ||
152 | ++ | ||
153 | ++ .hash : { *(.hash) } :text | ||
154 | ++ .dynsym : { *(.dynsym) } | ||
155 | ++ .dynstr : { *(.dynstr) } | ||
156 | ++ .gnu.version : { *(.gnu.version) } | ||
157 | ++ .gnu.version_d : { *(.gnu.version_d) } | ||
158 | ++ .gnu.version_r : { *(.gnu.version_r) } | ||
159 | ++ | ||
160 | ++ /* This linker script is used both with -r and with -shared. | ||
161 | ++ For the layouts to match, we need to skip more than enough | ||
162 | ++ space for the dynamic symbol table et al. If this amount | ||
163 | ++ is insufficient, ld -shared will barf. Just increase it here. */ | ||
164 | ++ . = VSYSCALL_BASE + 0x400; | ||
165 | ++ | ||
166 | ++ .text : { *(.text) } :text =0x90909090 | ||
167 | ++ | ||
168 | ++ .eh_frame_hdr : { *(.eh_frame_hdr) } :text :eh_frame_hdr | ||
169 | ++ .eh_frame : { KEEP (*(.eh_frame)) } :text | ||
170 | ++ .dynamic : { *(.dynamic) } :text :dynamic | ||
171 | ++ .useless : { | ||
172 | ++ *(.got.plt) *(.got) | ||
173 | ++ *(.data .data.* .gnu.linkonce.d.*) | ||
174 | ++ *(.dynbss) | ||
175 | ++ *(.bss .bss.* .gnu.linkonce.b.*) | ||
176 | ++ } :text | ||
177 | ++} | ||
178 | ++ | ||
179 | ++/* | ||
180 | ++ * We must supply the ELF program headers explicitly to get just one | ||
181 | ++ * PT_LOAD segment, and set the flags explicitly to make segments read-only. | ||
182 | ++ */ | ||
183 | ++PHDRS | ||
184 | ++{ | ||
185 | ++ text PT_LOAD FILEHDR PHDRS FLAGS(5); /* PF_R|PF_X */ | ||
186 | ++ dynamic PT_DYNAMIC FLAGS(4); /* PF_R */ | ||
187 | ++ eh_frame_hdr 0x6474e550; /* PT_GNU_EH_FRAME, but ld doesn't match the name */ | ||
188 | ++} | ||
189 | ++ | ||
190 | ++/* | ||
191 | ++ * This controls what symbols we export from the DSO. | ||
192 | ++ */ | ||
193 | ++VERSION | ||
194 | ++{ | ||
195 | ++ LINUX_2.5 { | ||
196 | ++ global: | ||
197 | ++ __kernel_vsyscall; | ||
198 | ++ __kernel_sigreturn; | ||
199 | ++ __kernel_rt_sigreturn; | ||
200 | ++ | ||
201 | ++ local: *; | ||
202 | ++ }; | ||
203 | ++} | ||
204 | ++ | ||
205 | ++/* The ELF entry point can be used to set the AT_SYSINFO value. */ | ||
206 | ++ENTRY(__kernel_vsyscall); | ||
207 | +diff -urpN --exclude TAGS -X /home/rusty/devel/kernel/kernel-patches/current-dontdiff --minimal .32324-linux-2.6.0/include/asm-i386/fixmap.h .32324-linux-2.6.0.updated/include/asm-i386/fixmap.h | ||
208 | +--- .32324-linux-2.6.0/include/asm-i386/fixmap.h 2003-09-22 10:09:12.000000000 +1000 | ||
209 | ++++ .32324-linux-2.6.0.updated/include/asm-i386/fixmap.h 2003-12-26 16:46:49.000000000 +1100 | ||
210 | +@@ -14,6 +14,19 @@ | ||
211 | + #define _ASM_FIXMAP_H | ||
212 | + | ||
213 | + #include <linux/config.h> | ||
214 | ++ | ||
215 | ++/* used by vmalloc.c, vsyscall.lds.S. | ||
216 | ++ * | ||
217 | ++ * Leave one empty page between vmalloc'ed areas and | ||
218 | ++ * the start of the fixmap. | ||
219 | ++ */ | ||
220 | ++#ifdef CONFIG_QEMU | ||
221 | ++#define __FIXADDR_TOP 0xa7fff000 | ||
222 | ++#else | ||
223 | ++#define __FIXADDR_TOP 0xfffff000 | ||
224 | ++#endif | ||
225 | ++ | ||
226 | ++#ifndef __ASSEMBLY__ | ||
227 | + #include <linux/kernel.h> | ||
228 | + #include <asm/acpi.h> | ||
229 | + #include <asm/apicdef.h> | ||
230 | +@@ -94,13 +107,8 @@ extern void __set_fixmap (enum fixed_add | ||
231 | + #define clear_fixmap(idx) \ | ||
232 | + __set_fixmap(idx, 0, __pgprot(0)) | ||
233 | + | ||
234 | +-/* | ||
235 | +- * used by vmalloc.c. | ||
236 | +- * | ||
237 | +- * Leave one empty page between vmalloc'ed areas and | ||
238 | +- * the start of the fixmap. | ||
239 | +- */ | ||
240 | +-#define FIXADDR_TOP (0xfffff000UL) | ||
241 | ++#define FIXADDR_TOP ((unsigned long)__FIXADDR_TOP) | ||
242 | ++ | ||
243 | + #define __FIXADDR_SIZE (__end_of_permanent_fixed_addresses << PAGE_SHIFT) | ||
244 | + #define FIXADDR_START (FIXADDR_TOP - __FIXADDR_SIZE) | ||
245 | + | ||
246 | +@@ -145,4 +153,5 @@ static inline unsigned long virt_to_fix( | ||
247 | + return __virt_to_fix(vaddr); | ||
248 | + } | ||
249 | + | ||
250 | ++#endif /* !__ASSEMBLY__ */ | ||
251 | + #endif | ||
252 | +diff -urpN --exclude TAGS -X /home/rusty/devel/kernel/kernel-patches/current-dontdiff --minimal .32324-linux-2.6.0/include/asm-i386/page.h .32324-linux-2.6.0.updated/include/asm-i386/page.h | ||
253 | +--- .32324-linux-2.6.0/include/asm-i386/page.h 2003-09-22 10:06:42.000000000 +1000 | ||
254 | ++++ .32324-linux-2.6.0.updated/include/asm-i386/page.h 2003-12-26 16:46:49.000000000 +1100 | ||
255 | +@@ -10,10 +10,10 @@ | ||
256 | + #define LARGE_PAGE_SIZE (1UL << PMD_SHIFT) | ||
257 | + | ||
258 | + #ifdef __KERNEL__ | ||
259 | +-#ifndef __ASSEMBLY__ | ||
260 | +- | ||
261 | + #include <linux/config.h> | ||
262 | + | ||
263 | ++#ifndef __ASSEMBLY__ | ||
264 | ++ | ||
265 | + #ifdef CONFIG_X86_USE_3DNOW | ||
266 | + | ||
267 | + #include <asm/mmx.h> | ||
268 | +@@ -115,12 +115,19 @@ static __inline__ int get_order(unsigned | ||
269 | + #endif /* __ASSEMBLY__ */ | ||
270 | + | ||
271 | + #ifdef __ASSEMBLY__ | ||
272 | ++#ifdef CONFIG_QEMU | ||
273 | ++#define __PAGE_OFFSET (0x90000000) | ||
274 | ++#else | ||
275 | + #define __PAGE_OFFSET (0xC0000000) | ||
276 | ++#endif /* QEMU */ | ||
277 | ++#else | ||
278 | ++#ifdef CONFIG_QEMU | ||
279 | ++#define __PAGE_OFFSET (0x90000000UL) | ||
280 | + #else | ||
281 | + #define __PAGE_OFFSET (0xC0000000UL) | ||
282 | ++#endif /* QEMU */ | ||
283 | + #endif | ||
284 | + | ||
285 | +- | ||
286 | + #define PAGE_OFFSET ((unsigned long)__PAGE_OFFSET) | ||
287 | + #define VMALLOC_RESERVE ((unsigned long)__VMALLOC_RESERVE) | ||
288 | + #define MAXMEM (-__PAGE_OFFSET-__VMALLOC_RESERVE) | ||
289 | +diff -urpN --exclude TAGS -X /home/rusty/devel/kernel/kernel-patches/current-dontdiff --minimal .32324-linux-2.6.0/include/asm-i386/param.h .32324-linux-2.6.0.updated/include/asm-i386/param.h | ||
290 | +--- .32324-linux-2.6.0/include/asm-i386/param.h 2003-09-21 17:26:06.000000000 +1000 | ||
291 | ++++ .32324-linux-2.6.0.updated/include/asm-i386/param.h 2003-12-26 16:46:49.000000000 +1100 | ||
292 | +@@ -2,7 +2,12 @@ | ||
293 | + #define _ASMi386_PARAM_H | ||
294 | + | ||
295 | + #ifdef __KERNEL__ | ||
296 | +-# define HZ 1000 /* Internal kernel timer frequency */ | ||
297 | ++# include <linux/config.h> | ||
298 | ++# ifdef CONFIG_QEMU | ||
299 | ++# define HZ 100 | ||
300 | ++# else | ||
301 | ++# define HZ 1000 /* Internal kernel timer frequency */ | ||
302 | ++# endif | ||
303 | + # define USER_HZ 100 /* .. some user interfaces are in "ticks" */ | ||
304 | + # define CLOCKS_PER_SEC (USER_HZ) /* like times() */ | ||
305 | + #endif |
qemu-doc.texi
1 | \input texinfo @c -*- texinfo -*- | 1 | \input texinfo @c -*- texinfo -*- |
2 | 2 | ||
3 | @iftex | 3 | @iftex |
4 | -@settitle QEMU CPU Emulator Reference Documentation | 4 | +@settitle QEMU CPU Emulator User Documentation |
5 | @titlepage | 5 | @titlepage |
6 | @sp 7 | 6 | @sp 7 |
7 | -@center @titlefont{QEMU CPU Emulator Reference Documentation} | 7 | +@center @titlefont{QEMU CPU Emulator User Documentation} |
8 | @sp 3 | 8 | @sp 3 |
9 | @end titlepage | 9 | @end titlepage |
10 | @end iftex | 10 | @end iftex |
@@ -13,126 +13,39 @@ | @@ -13,126 +13,39 @@ | ||
13 | 13 | ||
14 | @section Features | 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 | QEMU has two operating modes: | 19 | QEMU has two operating modes: |
21 | 20 | ||
22 | @itemize @minus | 21 | @itemize @minus |
23 | 22 | ||
24 | @item | 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 | @item | 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 | @end itemize | 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 | easy to use. | 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 | @chapter Installation | 45 | @chapter Installation |
135 | 46 | ||
47 | +@section Linux | ||
48 | + | ||
136 | If you want to compile QEMU, please read the @file{README} which gives | 49 | If you want to compile QEMU, please read the @file{README} which gives |
137 | the related information. Otherwise just download the binary | 50 | the related information. Otherwise just download the binary |
138 | distribution (@file{qemu-XXX-i386.tar.gz}) and untar it as root in | 51 | distribution (@file{qemu-XXX-i386.tar.gz}) and untar it as root in |
@@ -144,106 +57,69 @@ cd / | @@ -144,106 +57,69 @@ cd / | ||
144 | tar zxvf /tmp/qemu-XXX-i386.tar.gz | 57 | tar zxvf /tmp/qemu-XXX-i386.tar.gz |
145 | @end example | 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 | @itemize | 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 | @end itemize | 87 | @end itemize |
196 | 88 | ||
197 | -@section Wine launch | 89 | +@section Cross compilation for Windows with Linux |
198 | 90 | ||
199 | @itemize | 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 | @example | 104 | @example |
206 | -qemu-i386 /usr/local/qemu-i386/bin/ls-i386 | 105 | +./configure --enable-mingw32 |
207 | @end example | 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 | @end itemize | 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 | @chapter QEMU System emulator invocation | 124 | @chapter QEMU System emulator invocation |
249 | 125 | ||
@@ -251,9 +127,7 @@ Act as if the host page size was 'pagesize' bytes | @@ -251,9 +127,7 @@ Act as if the host page size was 'pagesize' bytes | ||
251 | 127 | ||
252 | @c man begin DESCRIPTION | 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 | In order to meet specific user needs, two versions of QEMU are | 132 | In order to meet specific user needs, two versions of QEMU are |
259 | available: | 133 | available: |
@@ -282,18 +156,14 @@ VGA (hardware level, including all non standard modes) | @@ -282,18 +156,14 @@ VGA (hardware level, including all non standard modes) | ||
282 | PS/2 mouse and keyboard | 156 | PS/2 mouse and keyboard |
283 | @item | 157 | @item |
284 | 2 IDE interfaces with hard disk and CD-ROM support | 158 | 2 IDE interfaces with hard disk and CD-ROM support |
159 | +@item | ||
160 | +Floppy disk | ||
285 | @item | 161 | @item |
286 | -NE2000 network adapter (port=0x300, irq=9) | 162 | +up to 6 NE2000 network adapters |
287 | @item | 163 | @item |
288 | Serial port | 164 | Serial port |
289 | @item | 165 | @item |
290 | Soundblaster 16 card | 166 | Soundblaster 16 card |
291 | -@item | ||
292 | -PIC (interrupt controler) | ||
293 | -@item | ||
294 | -PIT (timers) | ||
295 | -@item | ||
296 | -CMOS memory | ||
297 | @end itemize | 167 | @end itemize |
298 | 168 | ||
299 | @c man end | 169 | @c man end |
@@ -308,157 +178,6 @@ qemu linux.img | @@ -308,157 +178,6 @@ qemu linux.img | ||
308 | 178 | ||
309 | Linux should boot and give you a prompt. | 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 | @section Invocation | 181 | @section Invocation |
463 | 182 | ||
464 | @example | 183 | @example |
@@ -486,8 +205,8 @@ Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}). | @@ -486,8 +205,8 @@ Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}). | ||
486 | Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and | 205 | Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and |
487 | @option{-cdrom} at the same time). | 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 | the default. | 210 | the default. |
492 | 211 | ||
493 | @item -snapshot | 212 | @item -snapshot |
@@ -498,19 +217,9 @@ the write back by pressing @key{C-a s} (@xref{disk_images}). | @@ -498,19 +217,9 @@ the write back by pressing @key{C-a s} (@xref{disk_images}). | ||
498 | @item -m megs | 217 | @item -m megs |
499 | Set virtual RAM size to @var{megs} megabytes. | 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 | @item -initrd file | 220 | @item -initrd file |
507 | Use @var{file} as initial ram disk. | 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 | @item -nographic | 223 | @item -nographic |
515 | 224 | ||
516 | Normally, QEMU uses SDL to display the VGA output. With this option, | 225 | Normally, QEMU uses SDL to display the VGA output. With this option, |
@@ -521,7 +230,35 @@ with a serial console. | @@ -521,7 +230,35 @@ with a serial console. | ||
521 | 230 | ||
522 | @end table | 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 | @table @option | 262 | @table @option |
526 | 263 | ||
527 | @item -kernel bzImage | 264 | @item -kernel bzImage |
@@ -545,7 +282,8 @@ Change gdb connection port. | @@ -545,7 +282,8 @@ Change gdb connection port. | ||
545 | Output log in /tmp/qemu.log | 282 | Output log in /tmp/qemu.log |
546 | @end table | 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 | @table @key | 288 | @table @key |
551 | @item C-a h | 289 | @item C-a h |
@@ -555,7 +293,9 @@ Exit emulatior | @@ -555,7 +293,9 @@ Exit emulatior | ||
555 | @item C-a s | 293 | @item C-a s |
556 | Save disk data back to file (if -snapshot) | 294 | Save disk data back to file (if -snapshot) |
557 | @item C-a b | 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 | @item C-a C-a | 299 | @item C-a C-a |
560 | Send C-a | 300 | Send C-a |
561 | @end table | 301 | @end table |
@@ -566,18 +306,165 @@ Send C-a | @@ -566,18 +306,165 @@ Send C-a | ||
566 | @setfilename qemu | 306 | @setfilename qemu |
567 | @settitle QEMU System Emulator | 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 | @node disk_images | 468 | @node disk_images |
582 | @section Disk Images | 469 | @section Disk Images |
583 | 470 | ||
@@ -649,13 +536,166 @@ Since holes are used, the displayed size of the COW disk image is not | @@ -649,13 +536,166 @@ Since holes are used, the displayed size of the COW disk image is not | ||
649 | the real one. To know it, use the @code{ls -ls} command. | 536 | the real one. To know it, use the @code{ls -ls} command. |
650 | @end enumerate | 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 | @node linux_compile | 690 | @node linux_compile |
653 | @section Linux Kernel Compilation | 691 | @section Linux Kernel Compilation |
654 | 692 | ||
655 | You can use any linux kernel with QEMU. However, if you want to use | 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 | @enumerate | 700 | @enumerate |
661 | @item | 701 | @item |
@@ -694,10 +734,10 @@ by | @@ -694,10 +734,10 @@ by | ||
694 | use an SMP kernel with QEMU, it only supports one CPU. | 734 | use an SMP kernel with QEMU, it only supports one CPU. |
695 | 735 | ||
696 | @item | 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 | (1000 is the default) as QEMU cannot currently emulate timers at | 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 | @file{include/asm/param.h}, replace: | 741 | @file{include/asm/param.h}, replace: |
702 | 742 | ||
703 | @example | 743 | @example |
@@ -762,322 +802,104 @@ Use @code{set architecture i8086} to dump 16 bit code. Then use | @@ -762,322 +802,104 @@ Use @code{set architecture i8086} to dump 16 bit code. Then use | ||
762 | @code{x/10i $cs*16+*eip} to dump the code at the PC position. | 802 | @code{x/10i $cs*16+*eip} to dump the code at the PC position. |
763 | @end enumerate | 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 | ||
953 | -request is done to the virtual CPU. When it is interrupted, one queued | ||
954 | -signal is handled by generating a stack frame in the virtual CPU as the | ||
955 | -Linux kernel does. The @code{sigreturn()} system call is emulated to return | ||
956 | -from the virtual signal handler. | 812 | +@itemize |
957 | 813 | ||
958 | -Some signals (such as SIGALRM) directly come from the host. Other | ||
959 | -signals are synthetized from the virtual CPU exceptions such as SIGFPE | ||
960 | -when a division by zero is done (see @code{main.c:cpu_loop()}). | 814 | +@item On x86, you can just try to launch any process by using the native |
815 | +libraries: | ||
961 | 816 | ||
962 | -The blocked signal mask is still handled by the host Linux kernel so | ||
963 | -that most signal system calls can be redirected directly to the host | ||
964 | -Linux kernel. Only the @code{sigaction()} and @code{sigreturn()} system | ||
965 | -calls need to be fully emulated (see @file{signal.c}). | 817 | +@example |
818 | +qemu-i386 -L / /bin/ls | ||
819 | +@end example | ||
966 | 820 | ||
967 | -@section clone() system call and threads | 821 | +@code{-L /} tells that the x86 dynamic linker must be searched with a |
822 | +@file{/} prefix. | ||
968 | 823 | ||
969 | -The Linux clone() system call is usually used to create a thread. QEMU | ||
970 | -uses the host clone() system call so that real host threads are created | ||
971 | -for each emulated thread. One virtual CPU instance is created for each | ||
972 | -thread. | 824 | +@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): |
973 | 825 | ||
974 | -The virtual x86 CPU atomic operations are emulated with a global lock so | ||
975 | -that their semantic is preserved. | 826 | +@example |
827 | +qemu-i386 -L / qemu-i386 -L / /bin/ls | ||
828 | +@end example | ||
976 | 829 | ||
977 | -Note that currently there are still some locking issues in QEMU. In | ||
978 | -particular, the translated cache flush is not protected yet against | ||
979 | -reentrancy. | 830 | +@item On non x86 CPUs, you need first to download at least an x86 glibc |
831 | +(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that | ||
832 | +@code{LD_LIBRARY_PATH} is not set: | ||
980 | 833 | ||
981 | -@section Self-virtualization | 834 | +@example |
835 | +unset LD_LIBRARY_PATH | ||
836 | +@end example | ||
982 | 837 | ||
983 | -QEMU was conceived so that ultimately it can emulate itself. Although | ||
984 | -it is not very useful, it is an important test to show the power of the | ||
985 | -emulator. | 838 | +Then you can launch the precompiled @file{ls} x86 executable: |
986 | 839 | ||
987 | -Achieving self-virtualization is not easy because there may be address | ||
988 | -space conflicts. QEMU solves this problem by being an executable ELF | ||
989 | -shared object as the ld-linux.so ELF interpreter. That way, it can be | ||
990 | -relocated at load time. | 840 | +@example |
841 | +qemu-i386 tests/i386/ls | ||
842 | +@end example | ||
843 | +You can look at @file{qemu-binfmt-conf.sh} so that | ||
844 | +QEMU is automatically launched by the Linux kernel when you try to | ||
845 | +launch x86 executables. It requires the @code{binfmt_misc} module in the | ||
846 | +Linux kernel. | ||
991 | 847 | ||
992 | -@section MMU emulation | 848 | +@item The x86 version of QEMU is also included. You can try weird things such as: |
849 | +@example | ||
850 | +qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386 | ||
851 | +@end example | ||
993 | 852 | ||
994 | -For system emulation, QEMU uses the mmap() system call to emulate the | ||
995 | -target CPU MMU. It works as long the emulated OS does not use an area | ||
996 | -reserved by the host OS (such as the area above 0xc0000000 on x86 | ||
997 | -Linux). | 853 | +@end itemize |
998 | 854 | ||
999 | -It is planned to add a slower but more precise MMU emulation | ||
1000 | -with a software MMU. | 855 | +@section Wine launch |
1001 | 856 | ||
1002 | -@section Bibliography | 857 | +@itemize |
1003 | 858 | ||
1004 | -@table @asis | 859 | +@item Ensure that you have a working QEMU with the x86 glibc |
860 | +distribution (see previous section). In order to verify it, you must be | ||
861 | +able to do: | ||
1005 | 862 | ||
1006 | -@item [1] | ||
1007 | -@url{http://citeseer.nj.nec.com/piumarta98optimizing.html}, Optimizing | ||
1008 | -direct threaded code by selective inlining (1998) by Ian Piumarta, Fabio | ||
1009 | -Riccardi. | 863 | +@example |
864 | +qemu-i386 /usr/local/qemu-i386/bin/ls-i386 | ||
865 | +@end example | ||
1010 | 866 | ||
1011 | -@item [2] | ||
1012 | -@url{http://developer.kde.org/~sewardj/}, Valgrind, an open-source | ||
1013 | -memory debugger for x86-GNU/Linux, by Julian Seward. | 867 | +@item Download the binary x86 Wine install |
868 | +(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page). | ||
1014 | 869 | ||
1015 | -@item [3] | ||
1016 | -@url{http://bochs.sourceforge.net/}, the Bochs IA-32 Emulator Project, | ||
1017 | -by Kevin Lawton et al. | 870 | +@item Configure Wine on your account. Look at the provided script |
871 | +@file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous | ||
872 | +@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}. | ||
1018 | 873 | ||
1019 | -@item [4] | ||
1020 | -@url{http://www.cs.rose-hulman.edu/~donaldlf/em86/index.html}, the EM86 | ||
1021 | -x86 emulator on Alpha-Linux. | 874 | +@item Then you can try the example @file{putty.exe}: |
1022 | 875 | ||
1023 | -@item [5] | ||
1024 | -@url{http://www.usenix.org/publications/library/proceedings/usenix-nt97/full_papers/chernoff/chernoff.pdf}, | ||
1025 | -DIGITAL FX!32: Running 32-Bit x86 Applications on Alpha NT, by Anton | ||
1026 | -Chernoff and Ray Hookway. | 876 | +@example |
877 | +qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe | ||
878 | +@end example | ||
1027 | 879 | ||
1028 | -@item [6] | ||
1029 | -@url{http://www.willows.com/}, Windows API library emulation from | ||
1030 | -Willows Software. | 880 | +@end itemize |
1031 | 881 | ||
1032 | -@item [7] | ||
1033 | -@url{http://user-mode-linux.sourceforge.net/}, | ||
1034 | -The User-mode Linux Kernel. | 882 | +@section Command line options |
1035 | 883 | ||
1036 | -@item [8] | ||
1037 | -@url{http://www.plex86.org/}, | ||
1038 | -The new Plex86 project. | 884 | +@example |
885 | +usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...] | ||
886 | +@end example | ||
1039 | 887 | ||
888 | +@table @option | ||
889 | +@item -h | ||
890 | +Print the help | ||
891 | +@item -L path | ||
892 | +Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386) | ||
893 | +@item -s size | ||
894 | +Set the x86 stack size in bytes (default=524288) | ||
1040 | @end table | 895 | @end table |
1041 | 896 | ||
1042 | -@chapter Regression Tests | ||
1043 | - | ||
1044 | -In the directory @file{tests/}, various interesting testing programs | ||
1045 | -are available. There are used for regression testing. | ||
1046 | - | ||
1047 | -@section @file{test-i386} | ||
1048 | - | ||
1049 | -This program executes most of the 16 bit and 32 bit x86 instructions and | ||
1050 | -generates a text output. It can be compared with the output obtained with | ||
1051 | -a real CPU or another emulator. The target @code{make test} runs this | ||
1052 | -program and a @code{diff} on the generated output. | ||
1053 | - | ||
1054 | -The Linux system call @code{modify_ldt()} is used to create x86 selectors | ||
1055 | -to test some 16 bit addressing and 32 bit with segmentation cases. | ||
1056 | - | ||
1057 | -The Linux system call @code{vm86()} is used to test vm86 emulation. | ||
1058 | - | ||
1059 | -Various exceptions are raised to test most of the x86 user space | ||
1060 | -exception reporting. | ||
1061 | - | ||
1062 | -@section @file{linux-test} | ||
1063 | - | ||
1064 | -This program tests various Linux system calls. It is used to verify | ||
1065 | -that the system call parameters are correctly converted between target | ||
1066 | -and host CPUs. | ||
1067 | - | ||
1068 | -@section @file{hello-i386} | ||
1069 | - | ||
1070 | -Very simple statically linked x86 program, just to test QEMU during a | ||
1071 | -port to a new host CPU. | ||
1072 | - | ||
1073 | -@section @file{hello-arm} | ||
1074 | - | ||
1075 | -Very simple statically linked ARM program, just to test QEMU during a | ||
1076 | -port to a new host CPU. | ||
1077 | - | ||
1078 | -@section @file{sha1} | 897 | +Debug options: |
1079 | 898 | ||
1080 | -It is a simple benchmark. Care must be taken to interpret the results | ||
1081 | -because it mostly tests the ability of the virtual CPU to optimize the | ||
1082 | -@code{rol} x86 instruction and the condition code computations. | 899 | +@table @option |
900 | +@item -d | ||
901 | +Activate log (logfile=/tmp/qemu.log) | ||
902 | +@item -p pagesize | ||
903 | +Act as if the host page size was 'pagesize' bytes | ||
904 | +@end table | ||
1083 | 905 |
qemu-tech.texi
0 → 100644
1 | +\input texinfo @c -*- texinfo -*- | ||
2 | + | ||
3 | +@iftex | ||
4 | +@settitle QEMU Internals | ||
5 | +@titlepage | ||
6 | +@sp 7 | ||
7 | +@center @titlefont{QEMU Internals} | ||
8 | +@sp 3 | ||
9 | +@end titlepage | ||
10 | +@end iftex | ||
11 | + | ||
12 | +@chapter Introduction | ||
13 | + | ||
14 | +@section Features | ||
15 | + | ||
16 | +QEMU is a FAST! processor emulator using a portable dynamic | ||
17 | +translator. | ||
18 | + | ||
19 | +QEMU has two operating modes: | ||
20 | + | ||
21 | +@itemize @minus | ||
22 | + | ||
23 | +@item | ||
24 | +Full system emulation. In this mode, QEMU emulates a full system | ||
25 | +(usually a PC), including a processor and various peripherials. It can | ||
26 | +be used to launch an different Operating System without rebooting the | ||
27 | +PC or to debug system code. | ||
28 | + | ||
29 | +@item | ||
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. | ||
34 | + | ||
35 | +@end itemize | ||
36 | + | ||
37 | +As QEMU requires no host kernel driver to run, it is very safe and | ||
38 | +easy to use. | ||
39 | + | ||
40 | +QEMU generic features: | ||
41 | + | ||
42 | +@itemize | ||
43 | + | ||
44 | +@item User space only or full system emulation. | ||
45 | + | ||
46 | +@item Using dynamic translation to native code for reasonnable speed. | ||
47 | + | ||
48 | +@item Working on x86 and PowerPC hosts. Being tested on ARM, Sparc32, Alpha and S390. | ||
49 | + | ||
50 | +@item Self-modifying code support. | ||
51 | + | ||
52 | +@item Precise exceptions support. | ||
53 | + | ||
54 | +@item The virtual CPU is a library (@code{libqemu}) which can be used | ||
55 | +in other projects. | ||
56 | + | ||
57 | +@end itemize | ||
58 | + | ||
59 | +QEMU user mode emulation features: | ||
60 | +@itemize | ||
61 | +@item Generic Linux system call converter, including most ioctls. | ||
62 | + | ||
63 | +@item clone() emulation using native CPU clone() to use Linux scheduler for threads. | ||
64 | + | ||
65 | +@item Accurate signal handling by remapping host signals to target signals. | ||
66 | +@end itemize | ||
67 | +@end itemize | ||
68 | + | ||
69 | +QEMU full system emulation features: | ||
70 | +@itemize | ||
71 | +@item QEMU can either use a full software MMU for maximum portability or use the host system call mmap() to simulate the target MMU. | ||
72 | +@end itemize | ||
73 | + | ||
74 | +@section x86 emulation | ||
75 | + | ||
76 | +QEMU x86 target features: | ||
77 | + | ||
78 | +@itemize | ||
79 | + | ||
80 | +@item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation. | ||
81 | +LDT/GDT and IDT are emulated. VM86 mode is also supported to run DOSEMU. | ||
82 | + | ||
83 | +@item Support of host page sizes bigger than 4KB in user mode emulation. | ||
84 | + | ||
85 | +@item QEMU can emulate itself on x86. | ||
86 | + | ||
87 | +@item An extensive Linux x86 CPU test program is included @file{tests/test-i386}. | ||
88 | +It can be used to test other x86 virtual CPUs. | ||
89 | + | ||
90 | +@end itemize | ||
91 | + | ||
92 | +Current QEMU limitations: | ||
93 | + | ||
94 | +@itemize | ||
95 | + | ||
96 | +@item No SSE/MMX support (yet). | ||
97 | + | ||
98 | +@item No x86-64 support. | ||
99 | + | ||
100 | +@item IPC syscalls are missing. | ||
101 | + | ||
102 | +@item The x86 segment limits and access rights are not tested at every | ||
103 | +memory access (yet). Hopefully, very few OSes seem to rely on that for | ||
104 | +normal use. | ||
105 | + | ||
106 | +@item On non x86 host CPUs, @code{double}s are used instead of the non standard | ||
107 | +10 byte @code{long double}s of x86 for floating point emulation to get | ||
108 | +maximum performances. | ||
109 | + | ||
110 | +@end itemize | ||
111 | + | ||
112 | +@section ARM emulation | ||
113 | + | ||
114 | +@itemize | ||
115 | + | ||
116 | +@item Full ARM 7 user emulation. | ||
117 | + | ||
118 | +@item NWFPE FPU support included in user Linux emulation. | ||
119 | + | ||
120 | +@item Can run most ARM Linux binaries. | ||
121 | + | ||
122 | +@end itemize | ||
123 | + | ||
124 | +@section PowerPC emulation | ||
125 | + | ||
126 | +@itemize | ||
127 | + | ||
128 | +@item Full PowerPC 32 bit emulation, including priviledged instructions, | ||
129 | +FPU and MMU. | ||
130 | + | ||
131 | +@item Can run most PowerPC Linux binaries. | ||
132 | + | ||
133 | +@end itemize | ||
134 | + | ||
135 | +@section SPARC emulation | ||
136 | + | ||
137 | +@itemize | ||
138 | + | ||
139 | +@item SPARC V8 user support, except FPU instructions. | ||
140 | + | ||
141 | +@item Can run some SPARC Linux binaries. | ||
142 | + | ||
143 | +@end itemize | ||
144 | + | ||
145 | +@chapter QEMU Internals | ||
146 | + | ||
147 | +@section QEMU compared to other emulators | ||
148 | + | ||
149 | +Like bochs [3], QEMU emulates an x86 CPU. But QEMU is much faster than | ||
150 | +bochs as it uses dynamic compilation. Bochs is closely tied to x86 PC | ||
151 | +emulation while QEMU can emulate several processors. | ||
152 | + | ||
153 | +Like Valgrind [2], QEMU does user space emulation and dynamic | ||
154 | +translation. Valgrind is mainly a memory debugger while QEMU has no | ||
155 | +support for it (QEMU could be used to detect out of bound memory | ||
156 | +accesses as Valgrind, but it has no support to track uninitialised data | ||
157 | +as Valgrind does). The Valgrind dynamic translator generates better code | ||
158 | +than QEMU (in particular it does register allocation) but it is closely | ||
159 | +tied to an x86 host and target and has no support for precise exceptions | ||
160 | +and system emulation. | ||
161 | + | ||
162 | +EM86 [4] is the closest project to user space QEMU (and QEMU still uses | ||
163 | +some of its code, in particular the ELF file loader). EM86 was limited | ||
164 | +to an alpha host and used a proprietary and slow interpreter (the | ||
165 | +interpreter part of the FX!32 Digital Win32 code translator [5]). | ||
166 | + | ||
167 | +TWIN [6] is a Windows API emulator like Wine. It is less accurate than | ||
168 | +Wine but includes a protected mode x86 interpreter to launch x86 Windows | ||
169 | +executables. Such an approach as greater potential because most of the | ||
170 | +Windows API is executed natively but it is far more difficult to develop | ||
171 | +because all the data structures and function parameters exchanged | ||
172 | +between the API and the x86 code must be converted. | ||
173 | + | ||
174 | +User mode Linux [7] was the only solution before QEMU to launch a | ||
175 | +Linux kernel as a process while not needing any host kernel | ||
176 | +patches. However, user mode Linux requires heavy kernel patches while | ||
177 | +QEMU accepts unpatched Linux kernels. The price to pay is that QEMU is | ||
178 | +slower. | ||
179 | + | ||
180 | +The new Plex86 [8] PC virtualizer is done in the same spirit as the | ||
181 | +qemu-fast system emulator. It requires a patched Linux kernel to work | ||
182 | +(you cannot launch the same kernel on your PC), but the patches are | ||
183 | +really small. As it is a PC virtualizer (no emulation is done except | ||
184 | +for some priveledged instructions), it has the potential of being | ||
185 | +faster than QEMU. The downside is that a complicated (and potentially | ||
186 | +unsafe) host kernel patch is needed. | ||
187 | + | ||
188 | +The commercial PC Virtualizers (VMWare [9], VirtualPC [10], TwoOStwo | ||
189 | +[11]) are faster than QEMU, but they all need specific, proprietary | ||
190 | +and potentially unsafe host drivers. Moreover, they are unable to | ||
191 | +provide cycle exact simulation as an emulator can. | ||
192 | + | ||
193 | +@section Portable dynamic translation | ||
194 | + | ||
195 | +QEMU is a dynamic translator. When it first encounters a piece of code, | ||
196 | +it converts it to the host instruction set. Usually dynamic translators | ||
197 | +are very complicated and highly CPU dependent. QEMU uses some tricks | ||
198 | +which make it relatively easily portable and simple while achieving good | ||
199 | +performances. | ||
200 | + | ||
201 | +The basic idea is to split every x86 instruction into fewer simpler | ||
202 | +instructions. Each simple instruction is implemented by a piece of C | ||
203 | +code (see @file{target-i386/op.c}). Then a compile time tool | ||
204 | +(@file{dyngen}) takes the corresponding object file (@file{op.o}) | ||
205 | +to generate a dynamic code generator which concatenates the simple | ||
206 | +instructions to build a function (see @file{op.h:dyngen_code()}). | ||
207 | + | ||
208 | +In essence, the process is similar to [1], but more work is done at | ||
209 | +compile time. | ||
210 | + | ||
211 | +A key idea to get optimal performances is that constant parameters can | ||
212 | +be passed to the simple operations. For that purpose, dummy ELF | ||
213 | +relocations are generated with gcc for each constant parameter. Then, | ||
214 | +the tool (@file{dyngen}) can locate the relocations and generate the | ||
215 | +appriopriate C code to resolve them when building the dynamic code. | ||
216 | + | ||
217 | +That way, QEMU is no more difficult to port than a dynamic linker. | ||
218 | + | ||
219 | +To go even faster, GCC static register variables are used to keep the | ||
220 | +state of the virtual CPU. | ||
221 | + | ||
222 | +@section Register allocation | ||
223 | + | ||
224 | +Since QEMU uses fixed simple instructions, no efficient register | ||
225 | +allocation can be done. However, because RISC CPUs have a lot of | ||
226 | +register, most of the virtual CPU state can be put in registers without | ||
227 | +doing complicated register allocation. | ||
228 | + | ||
229 | +@section Condition code optimisations | ||
230 | + | ||
231 | +Good CPU condition codes emulation (@code{EFLAGS} register on x86) is a | ||
232 | +critical point to get good performances. QEMU uses lazy condition code | ||
233 | +evaluation: instead of computing the condition codes after each x86 | ||
234 | +instruction, it just stores one operand (called @code{CC_SRC}), the | ||
235 | +result (called @code{CC_DST}) and the type of operation (called | ||
236 | +@code{CC_OP}). | ||
237 | + | ||
238 | +@code{CC_OP} is almost never explicitely set in the generated code | ||
239 | +because it is known at translation time. | ||
240 | + | ||
241 | +In order to increase performances, a backward pass is performed on the | ||
242 | +generated simple instructions (see | ||
243 | +@code{target-i386/translate.c:optimize_flags()}). When it can be proved that | ||
244 | +the condition codes are not needed by the next instructions, no | ||
245 | +condition codes are computed at all. | ||
246 | + | ||
247 | +@section CPU state optimisations | ||
248 | + | ||
249 | +The x86 CPU has many internal states which change the way it evaluates | ||
250 | +instructions. In order to achieve a good speed, the translation phase | ||
251 | +considers that some state information of the virtual x86 CPU cannot | ||
252 | +change in it. For example, if the SS, DS and ES segments have a zero | ||
253 | +base, then the translator does not even generate an addition for the | ||
254 | +segment base. | ||
255 | + | ||
256 | +[The FPU stack pointer register is not handled that way yet]. | ||
257 | + | ||
258 | +@section Translation cache | ||
259 | + | ||
260 | +A 2MByte cache holds the most recently used translations. For | ||
261 | +simplicity, it is completely flushed when it is full. A translation unit | ||
262 | +contains just a single basic block (a block of x86 instructions | ||
263 | +terminated by a jump or by a virtual CPU state change which the | ||
264 | +translator cannot deduce statically). | ||
265 | + | ||
266 | +@section Direct block chaining | ||
267 | + | ||
268 | +After each translated basic block is executed, QEMU uses the simulated | ||
269 | +Program Counter (PC) and other cpu state informations (such as the CS | ||
270 | +segment base value) to find the next basic block. | ||
271 | + | ||
272 | +In order to accelerate the most common cases where the new simulated PC | ||
273 | +is known, QEMU can patch a basic block so that it jumps directly to the | ||
274 | +next one. | ||
275 | + | ||
276 | +The most portable code uses an indirect jump. An indirect jump makes | ||
277 | +it easier to make the jump target modification atomic. On some host | ||
278 | +architectures (such as x86 or PowerPC), the @code{JUMP} opcode is | ||
279 | +directly patched so that the block chaining has no overhead. | ||
280 | + | ||
281 | +@section Self-modifying code and translated code invalidation | ||
282 | + | ||
283 | +Self-modifying code is a special challenge in x86 emulation because no | ||
284 | +instruction cache invalidation is signaled by the application when code | ||
285 | +is modified. | ||
286 | + | ||
287 | +When translated code is generated for a basic block, the corresponding | ||
288 | +host page is write protected if it is not already read-only (with the | ||
289 | +system call @code{mprotect()}). Then, if a write access is done to the | ||
290 | +page, Linux raises a SEGV signal. QEMU then invalidates all the | ||
291 | +translated code in the page and enables write accesses to the page. | ||
292 | + | ||
293 | +Correct translated code invalidation is done efficiently by maintaining | ||
294 | +a linked list of every translated block contained in a given page. Other | ||
295 | +linked lists are also maintained to undo direct block chaining. | ||
296 | + | ||
297 | +Although the overhead of doing @code{mprotect()} calls is important, | ||
298 | +most MSDOS programs can be emulated at reasonnable speed with QEMU and | ||
299 | +DOSEMU. | ||
300 | + | ||
301 | +Note that QEMU also invalidates pages of translated code when it detects | ||
302 | +that memory mappings are modified with @code{mmap()} or @code{munmap()}. | ||
303 | + | ||
304 | +When using a software MMU, the code invalidation is more efficient: if | ||
305 | +a given code page is invalidated too often because of write accesses, | ||
306 | +then a bitmap representing all the code inside the page is | ||
307 | +built. Every store into that page checks the bitmap to see if the code | ||
308 | +really needs to be invalidated. It avoids invalidating the code when | ||
309 | +only data is modified in the page. | ||
310 | + | ||
311 | +@section Exception support | ||
312 | + | ||
313 | +longjmp() is used when an exception such as division by zero is | ||
314 | +encountered. | ||
315 | + | ||
316 | +The host SIGSEGV and SIGBUS signal handlers are used to get invalid | ||
317 | +memory accesses. The exact CPU state can be retrieved because all the | ||
318 | +x86 registers are stored in fixed host registers. The simulated program | ||
319 | +counter is found by retranslating the corresponding basic block and by | ||
320 | +looking where the host program counter was at the exception point. | ||
321 | + | ||
322 | +The virtual CPU cannot retrieve the exact @code{EFLAGS} register because | ||
323 | +in some cases it is not computed because of condition code | ||
324 | +optimisations. It is not a big concern because the emulated code can | ||
325 | +still be restarted in any cases. | ||
326 | + | ||
327 | +@section MMU emulation | ||
328 | + | ||
329 | +For system emulation, QEMU uses the mmap() system call to emulate the | ||
330 | +target CPU MMU. It works as long the emulated OS does not use an area | ||
331 | +reserved by the host OS (such as the area above 0xc0000000 on x86 | ||
332 | +Linux). | ||
333 | + | ||
334 | +In order to be able to launch any OS, QEMU also supports a soft | ||
335 | +MMU. In that mode, the MMU virtual to physical address translation is | ||
336 | +done at every memory access. QEMU uses an address translation cache to | ||
337 | +speed up the translation. | ||
338 | + | ||
339 | +In order to avoid flushing the translated code each time the MMU | ||
340 | +mappings change, QEMU uses a physically indexed translation cache. It | ||
341 | +means that each basic block is indexed with its physical address. | ||
342 | + | ||
343 | +When MMU mappings change, only the chaining of the basic blocks is | ||
344 | +reset (i.e. a basic block can no longer jump directly to another one). | ||
345 | + | ||
346 | +@section Hardware interrupts | ||
347 | + | ||
348 | +In order to be faster, QEMU does not check at every basic block if an | ||
349 | +hardware interrupt is pending. Instead, the user must asynchrously | ||
350 | +call a specific function to tell that an interrupt is pending. This | ||
351 | +function resets the chaining of the currently executing basic | ||
352 | +block. It ensures that the execution will return soon in the main loop | ||
353 | +of the CPU emulator. Then the main loop can test if the interrupt is | ||
354 | +pending and handle it. | ||
355 | + | ||
356 | +@section User emulation specific details | ||
357 | + | ||
358 | +@subsection Linux system call translation | ||
359 | + | ||
360 | +QEMU includes a generic system call translator for Linux. It means that | ||
361 | +the parameters of the system calls can be converted to fix the | ||
362 | +endianness and 32/64 bit issues. The IOCTLs are converted with a generic | ||
363 | +type description system (see @file{ioctls.h} and @file{thunk.c}). | ||
364 | + | ||
365 | +QEMU supports host CPUs which have pages bigger than 4KB. It records all | ||
366 | +the mappings the process does and try to emulated the @code{mmap()} | ||
367 | +system calls in cases where the host @code{mmap()} call would fail | ||
368 | +because of bad page alignment. | ||
369 | + | ||
370 | +@subsection Linux signals | ||
371 | + | ||
372 | +Normal and real-time signals are queued along with their information | ||
373 | +(@code{siginfo_t}) as it is done in the Linux kernel. Then an interrupt | ||
374 | +request is done to the virtual CPU. When it is interrupted, one queued | ||
375 | +signal is handled by generating a stack frame in the virtual CPU as the | ||
376 | +Linux kernel does. The @code{sigreturn()} system call is emulated to return | ||
377 | +from the virtual signal handler. | ||
378 | + | ||
379 | +Some signals (such as SIGALRM) directly come from the host. Other | ||
380 | +signals are synthetized from the virtual CPU exceptions such as SIGFPE | ||
381 | +when a division by zero is done (see @code{main.c:cpu_loop()}). | ||
382 | + | ||
383 | +The blocked signal mask is still handled by the host Linux kernel so | ||
384 | +that most signal system calls can be redirected directly to the host | ||
385 | +Linux kernel. Only the @code{sigaction()} and @code{sigreturn()} system | ||
386 | +calls need to be fully emulated (see @file{signal.c}). | ||
387 | + | ||
388 | +@subsection clone() system call and threads | ||
389 | + | ||
390 | +The Linux clone() system call is usually used to create a thread. QEMU | ||
391 | +uses the host clone() system call so that real host threads are created | ||
392 | +for each emulated thread. One virtual CPU instance is created for each | ||
393 | +thread. | ||
394 | + | ||
395 | +The virtual x86 CPU atomic operations are emulated with a global lock so | ||
396 | +that their semantic is preserved. | ||
397 | + | ||
398 | +Note that currently there are still some locking issues in QEMU. In | ||
399 | +particular, the translated cache flush is not protected yet against | ||
400 | +reentrancy. | ||
401 | + | ||
402 | +@subsection Self-virtualization | ||
403 | + | ||
404 | +QEMU was conceived so that ultimately it can emulate itself. Although | ||
405 | +it is not very useful, it is an important test to show the power of the | ||
406 | +emulator. | ||
407 | + | ||
408 | +Achieving self-virtualization is not easy because there may be address | ||
409 | +space conflicts. QEMU solves this problem by being an executable ELF | ||
410 | +shared object as the ld-linux.so ELF interpreter. That way, it can be | ||
411 | +relocated at load time. | ||
412 | + | ||
413 | +@section Bibliography | ||
414 | + | ||
415 | +@table @asis | ||
416 | + | ||
417 | +@item [1] | ||
418 | +@url{http://citeseer.nj.nec.com/piumarta98optimizing.html}, Optimizing | ||
419 | +direct threaded code by selective inlining (1998) by Ian Piumarta, Fabio | ||
420 | +Riccardi. | ||
421 | + | ||
422 | +@item [2] | ||
423 | +@url{http://developer.kde.org/~sewardj/}, Valgrind, an open-source | ||
424 | +memory debugger for x86-GNU/Linux, by Julian Seward. | ||
425 | + | ||
426 | +@item [3] | ||
427 | +@url{http://bochs.sourceforge.net/}, the Bochs IA-32 Emulator Project, | ||
428 | +by Kevin Lawton et al. | ||
429 | + | ||
430 | +@item [4] | ||
431 | +@url{http://www.cs.rose-hulman.edu/~donaldlf/em86/index.html}, the EM86 | ||
432 | +x86 emulator on Alpha-Linux. | ||
433 | + | ||
434 | +@item [5] | ||
435 | +@url{http://www.usenix.org/publications/library/proceedings/usenix-nt97/full_papers/chernoff/chernoff.pdf}, | ||
436 | +DIGITAL FX!32: Running 32-Bit x86 Applications on Alpha NT, by Anton | ||
437 | +Chernoff and Ray Hookway. | ||
438 | + | ||
439 | +@item [6] | ||
440 | +@url{http://www.willows.com/}, Windows API library emulation from | ||
441 | +Willows Software. | ||
442 | + | ||
443 | +@item [7] | ||
444 | +@url{http://user-mode-linux.sourceforge.net/}, | ||
445 | +The User-mode Linux Kernel. | ||
446 | + | ||
447 | +@item [8] | ||
448 | +@url{http://www.plex86.org/}, | ||
449 | +The new Plex86 project. | ||
450 | + | ||
451 | +@item [9] | ||
452 | +@url{http://www.vmware.com/}, | ||
453 | +The VMWare PC virtualizer. | ||
454 | + | ||
455 | +@item [10] | ||
456 | +@url{http://www.microsoft.com/windowsxp/virtualpc/}, | ||
457 | +The VirtualPC PC virtualizer. | ||
458 | + | ||
459 | +@item [11] | ||
460 | +@url{http://www.twoostwo.org/}, | ||
461 | +The TwoOStwo PC virtualizer. | ||
462 | + | ||
463 | +@end table | ||
464 | + | ||
465 | +@chapter Regression Tests | ||
466 | + | ||
467 | +In the directory @file{tests/}, various interesting testing programs | ||
468 | +are available. There are used for regression testing. | ||
469 | + | ||
470 | +@section @file{test-i386} | ||
471 | + | ||
472 | +This program executes most of the 16 bit and 32 bit x86 instructions and | ||
473 | +generates a text output. It can be compared with the output obtained with | ||
474 | +a real CPU or another emulator. The target @code{make test} runs this | ||
475 | +program and a @code{diff} on the generated output. | ||
476 | + | ||
477 | +The Linux system call @code{modify_ldt()} is used to create x86 selectors | ||
478 | +to test some 16 bit addressing and 32 bit with segmentation cases. | ||
479 | + | ||
480 | +The Linux system call @code{vm86()} is used to test vm86 emulation. | ||
481 | + | ||
482 | +Various exceptions are raised to test most of the x86 user space | ||
483 | +exception reporting. | ||
484 | + | ||
485 | +@section @file{linux-test} | ||
486 | + | ||
487 | +This program tests various Linux system calls. It is used to verify | ||
488 | +that the system call parameters are correctly converted between target | ||
489 | +and host CPUs. | ||
490 | + | ||
491 | +@section @file{hello-i386} | ||
492 | + | ||
493 | +Very simple statically linked x86 program, just to test QEMU during a | ||
494 | +port to a new host CPU. | ||
495 | + | ||
496 | +@section @file{hello-arm} | ||
497 | + | ||
498 | +Very simple statically linked ARM program, just to test QEMU during a | ||
499 | +port to a new host CPU. | ||
500 | + | ||
501 | +@section @file{sha1} | ||
502 | + | ||
503 | +It is a simple benchmark. Care must be taken to interpret the results | ||
504 | +because it mostly tests the ability of the virtual CPU to optimize the | ||
505 | +@code{rol} x86 instruction and the condition code computations. | ||
506 | + |