Revision 1f673135

b/Makefile
11 11
TOOLS=qemu-mkcow
12 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 15
	for d in $(TARGET_DIRS); do \
16 16
	make -C $$d $@ || exit 1 ; \
17 17
        done
......
61 61
	etags *.[ch] tests/*.[ch]
62 62

  
63 63
# documentation
64
qemu-doc.html: qemu-doc.texi
64
%.html: %.texi
65 65
	texi2html -monolithic -number $<
66 66

  
67 67
qemu.1: qemu-doc.texi
b/TODO
2 2
----------
3 3
- handle fast timers + add explicit clocks
4 4
- OS/2 install bug
5
- win 95 install bug
6 5
- handle Self Modifying Code even if modifying current TB (BE OS 5 install)
7 6
- physical memory cache (reduce qemu-fast address space size to about 32 MB)
8 7
- better code fetch
b/linux-2.6-qemu-fast.patch
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
b/qemu-doc.texi
1 1
\input texinfo @c -*- texinfo -*-
2 2

  
3 3
@iftex
4
@settitle QEMU CPU Emulator Reference Documentation
4
@settitle QEMU CPU Emulator User Documentation
5 5
@titlepage
6 6
@sp 7
7
@center @titlefont{QEMU CPU Emulator Reference Documentation}
7
@center @titlefont{QEMU CPU Emulator User Documentation}
8 8
@sp 3
9 9
@end titlepage
10 10
@end iftex
......
13 13

  
14 14
@section Features
15 15

  
16
QEMU is a FAST! processor emulator. By using dynamic translation it
17
achieves a reasonnable speed while being easy to port on new host
18
CPUs.
16
QEMU is a FAST! processor emulator using dynamic translation to
17
achieve good emulation speed.
19 18

  
20 19
QEMU has two operating modes:
21 20

  
22 21
@itemize @minus
23 22

  
24 23
@item 
25
User mode emulation. In this mode, QEMU can launch Linux processes
26
compiled for one CPU on another CPU. Linux system calls are converted
27
because of endianness and 32/64 bit mismatches. The Wine Windows API
28
emulator (@url{http://www.winehq.org}) and the DOSEMU DOS emulator
29
(@url{http://www.dosemu.org}) are the main targets for QEMU.
24
Full system emulation. In this mode, QEMU emulates a full system (for
25
example a PC), including a processor and various peripherials. It can
26
be used to launch different Operating Systems without rebooting the
27
PC or to debug system code.
30 28

  
31 29
@item 
32
Full system emulation. In this mode, QEMU emulates a full
33
system, including a processor and various peripherials. Currently, it
34
is only used to launch an x86 Linux kernel on an x86 Linux system. It
35
enables easier testing and debugging of system code. It can also be
36
used to provide virtual hosting of several virtual PCs on a single
37
server.
30
User mode emulation (Linux host only). In this mode, QEMU can launch
31
Linux processes compiled for one CPU on another CPU. It can be used to
32
launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
33
to ease cross-compilation and cross-debugging.
38 34

  
39 35
@end itemize
40 36

  
41
As QEMU requires no host kernel patches to run, it is very safe and
37
As QEMU requires no host kernel driver to run, it is very safe and
42 38
easy to use.
43 39

  
44
QEMU generic features:
40
For system emulation, only the x86 PC emulator is currently
41
usable. The PowerPC system emulator is being developped.
45 42

  
46
@itemize 
47

  
48
@item User space only or full system emulation.
49

  
50
@item Using dynamic translation to native code for reasonnable speed.
51

  
52
@item Working on x86 and PowerPC hosts. Being tested on ARM, Sparc32, Alpha and S390.
53

  
54
@item Self-modifying code support.
55

  
56
@item Precise exceptions support.
57

  
58
@item The virtual CPU is a library (@code{libqemu}) which can be used 
59
in other projects.
60

  
61
@end itemize
62

  
63
QEMU user mode emulation features:
64
@itemize 
65
@item Generic Linux system call converter, including most ioctls.
66

  
67
@item clone() emulation using native CPU clone() to use Linux scheduler for threads.
68

  
69
@item Accurate signal handling by remapping host signals to target signals. 
70
@end itemize
71
@end itemize
72

  
73
QEMU full system emulation features:
74
@itemize 
75
@item QEMU can either use a full software MMU for maximum portability or use the host system call mmap() to simulate the target MMU.
76
@end itemize
77

  
78
@section x86 emulation
79

  
80
QEMU x86 target features:
81

  
82
@itemize 
83

  
84
@item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation. 
85
LDT/GDT and IDT are emulated. VM86 mode is also supported to run DOSEMU.
86

  
87
@item Support of host page sizes bigger than 4KB in user mode emulation.
88

  
89
@item QEMU can emulate itself on x86.
90

  
91
@item An extensive Linux x86 CPU test program is included @file{tests/test-i386}. 
92
It can be used to test other x86 virtual CPUs.
93

  
94
@end itemize
95

  
96
Current QEMU limitations:
97

  
98
@itemize 
99

  
100
@item No SSE/MMX support (yet).
101

  
102
@item No x86-64 support.
103

  
104
@item IPC syscalls are missing.
105

  
106
@item The x86 segment limits and access rights are not tested at every 
107
memory access.
108

  
109
@item On non x86 host CPUs, @code{double}s are used instead of the non standard 
110
10 byte @code{long double}s of x86 for floating point emulation to get
111
maximum performances.
112

  
113
@item Some priviledged instructions or behaviors are missing, especially for segment protection testing (yet). 
114

  
115
@end itemize
116

  
117
@section ARM emulation
118

  
119
@itemize
120

  
121
@item ARM emulation can currently launch small programs while using the
122
generic dynamic code generation architecture of QEMU.
123

  
124
@item No FPU support (yet).
125

  
126
@item No automatic regression testing (yet).
127

  
128
@end itemize
129

  
130
@section SPARC emulation
131

  
132
The SPARC emulation is currently in development.
43
For user emulation, x86, PowerPC, ARM, and SPARC CPUs are supported.
133 44

  
134 45
@chapter Installation
135 46

  
47
@section Linux
48

  
136 49
If you want to compile QEMU, please read the @file{README} which gives
137 50
the related information. Otherwise just download the binary
138 51
distribution (@file{qemu-XXX-i386.tar.gz}) and untar it as root in
......
144 57
tar zxvf /tmp/qemu-XXX-i386.tar.gz
145 58
@end example
146 59

  
147
@chapter QEMU User space emulator invocation
148

  
149
@section Quick Start
150

  
151
In order to launch a Linux process, QEMU needs the process executable
152
itself and all the target (x86) dynamic libraries used by it. 
153

  
60
@section Windows
61
w
154 62
@itemize
63
@item Install the current versions of MSYS and MinGW from
64
@url{http://www.mingw.org/}. You can find detailed installation
65
instructions in the download section and the FAQ.
66

  
67
@item Download 
68
the MinGW development library of SDL 1.2.x
69
(@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
70
@url{http://www.libsdl.org}. Unpack it in a temporary place, and
71
unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
72
directory. Edit the @file{sdl-config} script so that it gives the
73
correct SDL directory when invoked.
74

  
75
@item Extract the current version of QEMU.
76
 
77
@item Start the MSYS shell (file @file{msys.bat}).
155 78

  
156
@item On x86, you can just try to launch any process by using the native
157
libraries:
158

  
159
@example 
160
qemu-i386 -L / /bin/ls
161
@end example
162

  
163
@code{-L /} tells that the x86 dynamic linker must be searched with a
164
@file{/} prefix.
165

  
166
@item Since QEMU is also a linux process, you can launch qemu with qemu (NOTE: you can only do that if you compiled QEMU from the sources):
167

  
168
@example 
169
qemu-i386 -L / qemu-i386 -L / /bin/ls
170
@end example
171

  
172
@item On non x86 CPUs, you need first to download at least an x86 glibc
173
(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
174
@code{LD_LIBRARY_PATH} is not set:
175

  
176
@example
177
unset LD_LIBRARY_PATH 
178
@end example
79
@item Change to the QEMU directory. Launch @file{./configure} and 
80
@file{make}.  If you have problems using SDL, verify that
81
@file{sdl-config} can be launched from the MSYS command line.
179 82

  
180
Then you can launch the precompiled @file{ls} x86 executable:
181

  
182
@example
183
qemu-i386 tests/i386/ls
184
@end example
185
You can look at @file{qemu-binfmt-conf.sh} so that
186
QEMU is automatically launched by the Linux kernel when you try to
187
launch x86 executables. It requires the @code{binfmt_misc} module in the
188
Linux kernel.
189

  
190
@item The x86 version of QEMU is also included. You can try weird things such as:
191
@example
192
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
193
@end example
83
@item You can install QEMU in @file{Program Files/Qemu} by typing 
84
@file{make install}. Don't forget to copy @file{SDL.dll} in
85
@file{Program Files/Qemu}.
194 86

  
195 87
@end itemize
196 88

  
197
@section Wine launch
89
@section Cross compilation for Windows with Linux
198 90

  
199 91
@itemize
92
@item
93
Install the MinGW cross compilation tools available at
94
@url{http://www.mingw.org/}.
200 95

  
201
@item Ensure that you have a working QEMU with the x86 glibc
202
distribution (see previous section). In order to verify it, you must be
203
able to do:
96
@item 
97
Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
98
unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
99
variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
100
the QEMU configuration script.
204 101

  
102
@item 
103
Configure QEMU for Windows cross compilation:
205 104
@example
206
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
105
./configure --enable-mingw32
207 106
@end example
107
If necessary, you can change the cross-prefix according to the prefix
108
choosen for the MinGW tools with --cross-prefix. You can also use
109
--prefix to set the Win32 install path.
208 110

  
209
@item Download the binary x86 Wine install
210
(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page). 
211

  
212
@item Configure Wine on your account. Look at the provided script
213
@file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous
214
@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
215

  
216
@item Then you can try the example @file{putty.exe}:
217

  
218
@example
219
qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
220
@end example
111
@item You can install QEMU in the installation directory by typing 
112
@file{make install}. Don't forget to copy @file{SDL.dll} in the
113
installation directory. 
221 114

  
222 115
@end itemize
223 116

  
224
@section Command line options
117
Note: Currently, Wine does not seem able to launch
118
QEMU for Win32.
225 119

  
226
@example
227
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
228
@end example
120
@section Mac OS X
229 121

  
230
@table @option
231
@item -h
232
Print the help
233
@item -L path   
234
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
235
@item -s size
236
Set the x86 stack size in bytes (default=524288)
237
@end table
238

  
239
Debug options:
240

  
241
@table @option
242
@item -d
243
Activate log (logfile=/tmp/qemu.log)
244
@item -p pagesize
245
Act as if the host page size was 'pagesize' bytes
246
@end table
122
Mac OS X is currently not supported.
247 123

  
248 124
@chapter QEMU System emulator invocation
249 125

  
......
251 127

  
252 128
@c man begin DESCRIPTION
253 129

  
254
The QEMU System emulator simulates a complete PC. It can either boot
255
directly a Linux kernel (without any BIOS or boot loader) or boot like a
256
real PC with the included BIOS.
130
The QEMU System emulator simulates a complete PC. 
257 131

  
258 132
In order to meet specific user needs, two versions of QEMU are
259 133
available:
......
282 156
PS/2 mouse and keyboard
283 157
@item 
284 158
2 IDE interfaces with hard disk and CD-ROM support
159
@item
160
Floppy disk
285 161
@item 
286
NE2000 network adapter (port=0x300, irq=9)
162
up to 6 NE2000 network adapters
287 163
@item
288 164
Serial port
289 165
@item 
290 166
Soundblaster 16 card
291
@item
292
PIC (interrupt controler)
293
@item
294
PIT (timers)
295
@item 
296
CMOS memory
297 167
@end itemize
298 168

  
299 169
@c man end
......
308 178

  
309 179
Linux should boot and give you a prompt.
310 180

  
311
@section Direct Linux Boot and Network emulation
312

  
313
This section explains how to launch a Linux kernel inside QEMU without
314
having to make a full bootable image. It is very useful for fast Linux
315
kernel testing. The QEMU network configuration is also explained.
316

  
317
@enumerate
318
@item
319
Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
320
kernel and a disk image. 
321

  
322
@item Optional: If you want network support (for example to launch X11 examples), you
323
must copy the script @file{qemu-ifup} in @file{/etc} and configure
324
properly @code{sudo} so that the command @code{ifconfig} contained in
325
@file{qemu-ifup} can be executed as root. You must verify that your host
326
kernel supports the TUN/TAP network interfaces: the device
327
@file{/dev/net/tun} must be present.
328

  
329
When network is enabled, there is a virtual network connection between
330
the host kernel and the emulated kernel. The emulated kernel is seen
331
from the host kernel at IP address 172.20.0.2 and the host kernel is
332
seen from the emulated kernel at IP address 172.20.0.1.
333

  
334
@item Launch @code{qemu.sh}. You should have the following output:
335

  
336
@example
337
> ./qemu.sh 
338
Connected to host network interface: tun0
339
Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
340
BIOS-provided physical RAM map:
341
 BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
342
 BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
343
32MB LOWMEM available.
344
On node 0 totalpages: 8192
345
zone(0): 4096 pages.
346
zone(1): 4096 pages.
347
zone(2): 0 pages.
348
Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0
349
ide_setup: ide2=noprobe
350
ide_setup: ide3=noprobe
351
ide_setup: ide4=noprobe
352
ide_setup: ide5=noprobe
353
Initializing CPU#0
354
Detected 2399.621 MHz processor.
355
Console: colour EGA 80x25
356
Calibrating delay loop... 4744.80 BogoMIPS
357
Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem)
358
Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
359
Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
360
Mount cache hash table entries: 512 (order: 0, 4096 bytes)
361
Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
362
Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
363
CPU: Intel Pentium Pro stepping 03
364
Checking 'hlt' instruction... OK.
365
POSIX conformance testing by UNIFIX
366
Linux NET4.0 for Linux 2.4
367
Based upon Swansea University Computer Society NET3.039
368
Initializing RT netlink socket
369
apm: BIOS not found.
370
Starting kswapd
371
Journalled Block Device driver loaded
372
Detected PS/2 Mouse Port.
373
pty: 256 Unix98 ptys configured
374
Serial driver version 5.05c (2001-07-08) with no serial options enabled
375
ttyS00 at 0x03f8 (irq = 4) is a 16450
376
ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com)
377
Last modified Nov 1, 2000 by Paul Gortmaker
378
NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
379
eth0: NE2000 found at 0x300, using IRQ 9.
380
RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
381
Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
382
ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
383
hda: QEMU HARDDISK, ATA DISK drive
384
ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
385
hda: attached ide-disk driver.
386
hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
387
Partition check:
388
 hda:
389
Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
390
NET4: Linux TCP/IP 1.0 for NET4.0
391
IP Protocols: ICMP, UDP, TCP, IGMP
392
IP: routing cache hash table of 512 buckets, 4Kbytes
393
TCP: Hash tables configured (established 2048 bind 4096)
394
NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
395
EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
396
VFS: Mounted root (ext2 filesystem).
397
Freeing unused kernel memory: 64k freed
398
 
399
Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
400
 
401
QEMU Linux test distribution (based on Redhat 9)
402
 
403
Type 'exit' to halt the system
404
 
405
sh-2.05b# 
406
@end example
407

  
408
@item
409
Then you can play with the kernel inside the virtual serial console. You
410
can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help
411
about the keys you can type inside the virtual serial console. In
412
particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as
413
the Magic SysRq key.
414

  
415
@item 
416
If the network is enabled, launch the script @file{/etc/linuxrc} in the
417
emulator (don't forget the leading dot):
418
@example
419
. /etc/linuxrc
420
@end example
421

  
422
Then enable X11 connections on your PC from the emulated Linux: 
423
@example
424
xhost +172.20.0.2
425
@end example
426

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

  
430
@end enumerate
431

  
432
NOTES:
433
@enumerate
434
@item 
435
A 2.5.74 kernel is also included in the archive. Just
436
replace the bzImage in qemu.sh to try it.
437

  
438
@item 
439
qemu creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the
440
default) containing all the simulated PC memory. If possible, try to use
441
a temporary directory using the tmpfs filesystem to avoid too many
442
unnecessary disk accesses.
443

  
444
@item 
445
In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
446
qemu. qemu will automatically exit when the Linux shutdown is done.
447

  
448
@item 
449
You can boot slightly faster by disabling the probe of non present IDE
450
interfaces. To do so, add the following options on the kernel command
451
line:
452
@example
453
ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
454
@end example
455

  
456
@item 
457
The example disk image is a modified version of the one made by Kevin
458
Lawton for the plex86 Project (@url{www.plex86.org}).
459

  
460
@end enumerate
461

  
462 181
@section Invocation
463 182

  
464 183
@example
......
486 205
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
487 206
@option{-cdrom} at the same time).
488 207

  
489
@item -boot [a|b|c|d]
490
Boot on floppy (a, b), hard disk (c) or CD-ROM (d). Hard disk boot is
208
@item -boot [a|c|d]
209
Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
491 210
the default.
492 211

  
493 212
@item -snapshot
......
498 217
@item -m megs
499 218
Set virtual RAM size to @var{megs} megabytes.
500 219

  
501
@item -n script      
502
Set network init script [default=/etc/qemu-ifup]. This script is
503
launched to configure the host network interface (usually tun0)
504
corresponding to the virtual NE2000 card.
505

  
506 220
@item -initrd file
507 221
Use @var{file} as initial ram disk.
508 222

  
509
@item -tun-fd fd      
510
Assumes @var{fd} talks to tap/tun and use it. Read
511
@url{http://bellard.org/qemu/tetrinet.html} to have an example of its
512
use.
513

  
514 223
@item -nographic
515 224

  
516 225
Normally, QEMU uses SDL to display the VGA output. With this option,
......
521 230

  
522 231
@end table
523 232

  
524
Linux boot specific (does not require a full PC boot with a BIOS):
233
Network options:
234

  
235
@table @option
236

  
237
@item -n script      
238
Set network init script [default=/etc/qemu-ifup]. This script is
239
launched to configure the host network interface (usually tun0)
240
corresponding to the virtual NE2000 card.
241

  
242
@item nics n
243
Simulate @var{n} network interfaces (default=1).
244

  
245
@item -macaddr addr   
246

  
247
Set the mac address of the first interface (the format is
248
aa:bb:cc:dd:ee:ff in hexa). The mac address is incremented for each
249
new network interface.
250

  
251
@item -tun-fd fd1,...
252
Assumes @var{fd} talks to tap/tun and use it. Read
253
@url{http://bellard.org/qemu/tetrinet.html} to have an example of its
254
use.
255

  
256
@end table
257

  
258
Linux boot specific. When using this options, you can use a given
259
Linux kernel without installing it in the disk image. It can be useful
260
for easier testing of various kernels.
261

  
525 262
@table @option
526 263

  
527 264
@item -kernel bzImage 
......
545 282
Output log in /tmp/qemu.log
546 283
@end table
547 284

  
548
During emulation, use @key{C-a h} to get terminal commands:
285
During emulation, if you are using the serial console, use @key{C-a h}
286
to get terminal commands:
549 287

  
550 288
@table @key
551 289
@item C-a h
......
555 293
@item C-a s    
556 294
Save disk data back to file (if -snapshot)
557 295
@item C-a b
558
Send break (magic sysrq)
296
Send break (magic sysrq in Linux)
297
@item C-a c
298
Switch between console and monitor
559 299
@item C-a C-a
560 300
Send C-a
561 301
@end table
......
566 306
@setfilename qemu 
567 307
@settitle QEMU System Emulator
568 308

  
569
@c man begin SEEALSO
570
The HTML documentation of QEMU for more precise information and Linux
571
user mode emulator invocation.
572
@c man end
309
@c man begin SEEALSO
310
The HTML documentation of QEMU for more precise information and Linux
311
user mode emulator invocation.
312
@c man end
313

  
314
@c man begin AUTHOR
315
Fabrice Bellard
316
@c man end
317

  
318
@end ignore
319

  
320
@end ignore
321

  
322

  
323
@section QEMU Monitor
324

  
325
The QEMU monitor is used to give complex commands to the QEMU
326
emulator. You can use it to:
327

  
328
@itemize @minus
329

  
330
@item
331
Remove or insert removable medias images
332
(such as CD-ROM or floppies)
333

  
334
@item 
335
Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
336
from a disk file.
337

  
338
@item Inspect the VM state without an external debugger.
339

  
340
@end itemize
341

  
342
@subsection Commands
343

  
344
The following commands are available:
345

  
346
@table @option
347

  
348
@item help or ? [cmd]
349
Show the help for all commands or just for command @var{cmd}.
350

  
351
@item commit  
352
Commit changes to the disk images (if -snapshot is used)
353

  
354
@item info subcommand 
355
show various information about the system state
356

  
357
@table @option
358
@item info network
359
show the network state
360
@item info block
361
show the block devices
362
@item info registers
363
show the cpu registers
364
@item info history
365
show the command line history
366
@end table
367

  
368
@item q or quit
369
Quit the emulator.
370

  
371
@item eject [-f] device
372
Eject a removable media (use -f to force it).
373

  
374
@item change device filename
375
Change a removable media.
376

  
377
@item screendump filename
378
Save screen into PPM image @var{filename}.
379

  
380
@item log item1[,...]
381
Activate logging of the specified items to @file{/tmp/qemu.log}.
382

  
383
@item savevm filename
384
Save the whole virtual machine state to @var{filename}.
385

  
386
@item loadvm filename
387
Restore the whole virtual machine state from @var{filename}.
388

  
389
@item stop
390
Stop emulation.
391

  
392
@item c or cont
393
Resume emulation.
394

  
395
@item gdbserver [port]
396
Start gdbserver session (default port=1234)
397

  
398
@item x/fmt addr
399
Virtual memory dump starting at @var{addr}.
400

  
401
@item xp /fmt addr
402
Physical memory dump starting at @var{addr}.
403

  
404
@var{fmt} is a format which tells the command how to format the
405
data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
406

  
407
@table @var
408
@item count 
409
is the number of items to be dumped.
410

  
411
@item format
412
can be x (hexa), d (signed decimal), u (unsigned decimal), o (octal),
413
c (char) or i (asm instruction).
414

  
415
@item size
416
can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits)
417

  
418
@end table
419

  
420
Examples: 
421
@itemize
422
@item
423
Dump 10 instructions at the current instruction pointer:
424
@example 
425
(qemu) x/10i $eip
426
0x90107063:  ret
427
0x90107064:  sti
428
0x90107065:  lea    0x0(%esi,1),%esi
429
0x90107069:  lea    0x0(%edi,1),%edi
430
0x90107070:  ret
431
0x90107071:  jmp    0x90107080
432
0x90107073:  nop
433
0x90107074:  nop
434
0x90107075:  nop
435
0x90107076:  nop
436
@end example
437

  
438
@item
439
Dump 80 16 bit values at the start of the video memory.
440
@example 
441
(qemu) xp/80hx 0xb8000
442
0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
443
0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
444
0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
445
0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
446
0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
447
0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
448
0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
449
0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
450
0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
451
0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
452
@end example
453
@end itemize
454

  
455
@item p or print/fmt expr
456

  
457
Print expression value. Only the @var{format} part of @var{fmt} is
458
used.
573 459

  
574
@c man begin AUTHOR
575
Fabrice Bellard
576
@c man end
460
@end table
577 461

  
578
@end ignore
462
@subsection Integer expressions
463

  
464
The monitor understands integers expressions for every integer
465
argument. You can use register names to get the value of specifics
466
CPU registers by prefixing them with @emph{$}.
579 467

  
580
@end ignore
581 468
@node disk_images
582 469
@section Disk Images
583 470

  
......
649 536
the real one. To know it, use the @code{ls -ls} command.
650 537
@end enumerate
651 538

  
539
@section Direct Linux Boot and Network emulation
540

  
541
This section explains how to launch a Linux kernel inside QEMU without
542
having to make a full bootable image. It is very useful for fast Linux
543
kernel testing. The QEMU network configuration is also explained.
544

  
545
@enumerate
546
@item
547
Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
548
kernel and a disk image. 
549

  
550
@item Optional: If you want network support (for example to launch X11 examples), you
551
must copy the script @file{qemu-ifup} in @file{/etc} and configure
552
properly @code{sudo} so that the command @code{ifconfig} contained in
553
@file{qemu-ifup} can be executed as root. You must verify that your host
554
kernel supports the TUN/TAP network interfaces: the device
555
@file{/dev/net/tun} must be present.
556

  
557
When network is enabled, there is a virtual network connection between
558
the host kernel and the emulated kernel. The emulated kernel is seen
559
from the host kernel at IP address 172.20.0.2 and the host kernel is
560
seen from the emulated kernel at IP address 172.20.0.1.
561

  
562
@item Launch @code{qemu.sh}. You should have the following output:
563

  
564
@example
565
> ./qemu.sh 
566
Connected to host network interface: tun0
567
Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
568
BIOS-provided physical RAM map:
569
 BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
570
 BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
571
32MB LOWMEM available.
572
On node 0 totalpages: 8192
573
zone(0): 4096 pages.
574
zone(1): 4096 pages.
575
zone(2): 0 pages.
576
Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0
577
ide_setup: ide2=noprobe
578
ide_setup: ide3=noprobe
579
ide_setup: ide4=noprobe
580
ide_setup: ide5=noprobe
581
Initializing CPU#0
582
Detected 2399.621 MHz processor.
583
Console: colour EGA 80x25
584
Calibrating delay loop... 4744.80 BogoMIPS
585
Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem)
586
Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
587
Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
588
Mount cache hash table entries: 512 (order: 0, 4096 bytes)
589
Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
590
Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
591
CPU: Intel Pentium Pro stepping 03
592
Checking 'hlt' instruction... OK.
593
POSIX conformance testing by UNIFIX
594
Linux NET4.0 for Linux 2.4
595
Based upon Swansea University Computer Society NET3.039
596
Initializing RT netlink socket
597
apm: BIOS not found.
598
Starting kswapd
599
Journalled Block Device driver loaded
600
Detected PS/2 Mouse Port.
601
pty: 256 Unix98 ptys configured
602
Serial driver version 5.05c (2001-07-08) with no serial options enabled
603
ttyS00 at 0x03f8 (irq = 4) is a 16450
604
ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com)
605
Last modified Nov 1, 2000 by Paul Gortmaker
606
NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
607
eth0: NE2000 found at 0x300, using IRQ 9.
608
RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
609
Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
610
ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
611
hda: QEMU HARDDISK, ATA DISK drive
612
ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
613
hda: attached ide-disk driver.
614
hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
615
Partition check:
616
 hda:
617
Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
618
NET4: Linux TCP/IP 1.0 for NET4.0
619
IP Protocols: ICMP, UDP, TCP, IGMP
620
IP: routing cache hash table of 512 buckets, 4Kbytes
621
TCP: Hash tables configured (established 2048 bind 4096)
622
NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
623
EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
624
VFS: Mounted root (ext2 filesystem).
625
Freeing unused kernel memory: 64k freed
626
 
627
Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
628
 
629
QEMU Linux test distribution (based on Redhat 9)
630
 
631
Type 'exit' to halt the system
632
 
633
sh-2.05b# 
634
@end example
635

  
636
@item
637
Then you can play with the kernel inside the virtual serial console. You
638
can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help
639
about the keys you can type inside the virtual serial console. In
640
particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as
641
the Magic SysRq key.
642

  
643
@item 
644
If the network is enabled, launch the script @file{/etc/linuxrc} in the
645
emulator (don't forget the leading dot):
646
@example
647
. /etc/linuxrc
648
@end example
649

  
650
Then enable X11 connections on your PC from the emulated Linux: 
651
@example
652
xhost +172.20.0.2
653
@end example
654

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

  
658
@end enumerate
659

  
660
NOTES:
661
@enumerate
662
@item 
663
A 2.5.74 kernel is also included in the archive. Just
664
replace the bzImage in qemu.sh to try it.
665

  
666
@item 
667
qemu-fast creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the
668
default) containing all the simulated PC memory. If possible, try to use
669
a temporary directory using the tmpfs filesystem to avoid too many
670
unnecessary disk accesses.
671

  
672
@item 
673
In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
674
qemu. qemu will automatically exit when the Linux shutdown is done.
675

  
676
@item 
677
You can boot slightly faster by disabling the probe of non present IDE
678
interfaces. To do so, add the following options on the kernel command
679
line:
680
@example
681
ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
682
@end example
683

  
684
@item 
685
The example disk image is a modified version of the one made by Kevin
686
Lawton for the plex86 Project (@url{www.plex86.org}).
687

  
688
@end enumerate
689

  
652 690
@node linux_compile
653 691
@section Linux Kernel Compilation
654 692

  
655 693
You can use any linux kernel with QEMU. However, if you want to use
656
@code{qemu-fast} to get maximum performances, you should make the
657
following changes to the Linux kernel (only 2.4.x and 2.5.x were
658
tested):
694
@code{qemu-fast} to get maximum performances, you must use a modified
695
guest kernel. If you are using a 2.6 guest kernel, you can use
696
directly the patch @file{linux-2.6-qemu-fast.patch} made by Rusty
697
Russel available in the QEMU source archive. Otherwise, you can make the
698
following changes @emph{by hand} to the Linux kernel:
659 699

  
660 700
@enumerate
661 701
@item
......
694 734
use an SMP kernel with QEMU, it only supports one CPU.
695 735

  
696 736
@item
697
If you are not using a 2.5 kernel as host kernel but if you use a target
698
2.5 kernel, you must also ensure that the 'HZ' define is set to 100
737
If you are not using a 2.6 kernel as host kernel but if you use a target
738
2.6 kernel, you must also ensure that the 'HZ' define is set to 100
699 739
(1000 is the default) as QEMU cannot currently emulate timers at
700
frequencies greater than 100 Hz on host Linux systems < 2.5. In
740
frequencies greater than 100 Hz on host Linux systems < 2.6. In
701 741
@file{include/asm/param.h}, replace:
702 742

  
703 743
@example
......
762 802
@code{x/10i $cs*16+*eip} to dump the code at the PC position.
763 803
@end enumerate
764 804

  
765
@chapter QEMU Internals
766

  
767
@section QEMU compared to other emulators
768

  
769
Like bochs [3], QEMU emulates an x86 CPU. But QEMU is much faster than
770
bochs as it uses dynamic compilation and because it uses the host MMU to
771
simulate the x86 MMU. The downside is that currently the emulation is
772
not as accurate as bochs (for example, you cannot currently run Windows
773
inside QEMU).
774

  
775
Like Valgrind [2], QEMU does user space emulation and dynamic
776
translation. Valgrind is mainly a memory debugger while QEMU has no
777
support for it (QEMU could be used to detect out of bound memory
778
accesses as Valgrind, but it has no support to track uninitialised data
779
as Valgrind does). The Valgrind dynamic translator generates better code
780
than QEMU (in particular it does register allocation) but it is closely
781
tied to an x86 host and target and has no support for precise exceptions
782
and system emulation.
783

  
784
EM86 [4] is the closest project to user space QEMU (and QEMU still uses
785
some of its code, in particular the ELF file loader). EM86 was limited
786
to an alpha host and used a proprietary and slow interpreter (the
787
interpreter part of the FX!32 Digital Win32 code translator [5]).
788

  
789
TWIN [6] is a Windows API emulator like Wine. It is less accurate than
790
Wine but includes a protected mode x86 interpreter to launch x86 Windows
791
executables. Such an approach as greater potential because most of the
792
Windows API is executed natively but it is far more difficult to develop
793
because all the data structures and function parameters exchanged
794
between the API and the x86 code must be converted.
795

  
796
User mode Linux [7] was the only solution before QEMU to launch a Linux
797
kernel as a process while not needing any host kernel patches. However,
798
user mode Linux requires heavy kernel patches while QEMU accepts
799
unpatched Linux kernels. It would be interesting to compare the
800
performance of the two approaches.
801

  
802
The new Plex86 [8] PC virtualizer is done in the same spirit as the QEMU
803
system emulator. It requires a patched Linux kernel to work (you cannot
804
launch the same kernel on your PC), but the patches are really small. As
805
it is a PC virtualizer (no emulation is done except for some priveledged
806
instructions), it has the potential of being faster than QEMU. The
807
downside is that a complicated (and potentially unsafe) host kernel
808
patch is needed.
809

  
810
@section Portable dynamic translation
811

  
812
QEMU is a dynamic translator. When it first encounters a piece of code,
813
it converts it to the host instruction set. Usually dynamic translators
814
are very complicated and highly CPU dependent. QEMU uses some tricks
815
which make it relatively easily portable and simple while achieving good
816
performances.
817

  
818
The basic idea is to split every x86 instruction into fewer simpler
819
instructions. Each simple instruction is implemented by a piece of C
820
code (see @file{op-i386.c}). Then a compile time tool (@file{dyngen})
821
takes the corresponding object file (@file{op-i386.o}) to generate a
822
dynamic code generator which concatenates the simple instructions to
823
build a function (see @file{op-i386.h:dyngen_code()}).
824

  
825
In essence, the process is similar to [1], but more work is done at
826
compile time. 
827

  
828
A key idea to get optimal performances is that constant parameters can
829
be passed to the simple operations. For that purpose, dummy ELF
830
relocations are generated with gcc for each constant parameter. Then,
831
the tool (@file{dyngen}) can locate the relocations and generate the
832
appriopriate C code to resolve them when building the dynamic code.
833

  
834
That way, QEMU is no more difficult to port than a dynamic linker.
835

  
836
To go even faster, GCC static register variables are used to keep the
837
state of the virtual CPU.
838

  
839
@section Register allocation
840

  
841
Since QEMU uses fixed simple instructions, no efficient register
842
allocation can be done. However, because RISC CPUs have a lot of
843
register, most of the virtual CPU state can be put in registers without
844
doing complicated register allocation.
845

  
846
@section Condition code optimisations
847

  
848
Good CPU condition codes emulation (@code{EFLAGS} register on x86) is a
849
critical point to get good performances. QEMU uses lazy condition code
850
evaluation: instead of computing the condition codes after each x86
851
instruction, it just stores one operand (called @code{CC_SRC}), the
852
result (called @code{CC_DST}) and the type of operation (called
853
@code{CC_OP}).
854

  
855
@code{CC_OP} is almost never explicitely set in the generated code
856
because it is known at translation time.
857

  
858
In order to increase performances, a backward pass is performed on the
859
generated simple instructions (see
860
@code{translate-i386.c:optimize_flags()}). When it can be proved that
861
the condition codes are not needed by the next instructions, no
862
condition codes are computed at all.
863

  
864
@section CPU state optimisations
865

  
866
The x86 CPU has many internal states which change the way it evaluates
867
instructions. In order to achieve a good speed, the translation phase
868
considers that some state information of the virtual x86 CPU cannot
869
change in it. For example, if the SS, DS and ES segments have a zero
870
base, then the translator does not even generate an addition for the
871
segment base.
872

  
873
[The FPU stack pointer register is not handled that way yet].
874

  
875
@section Translation cache
876

  
877
A 2MByte cache holds the most recently used translations. For
878
simplicity, it is completely flushed when it is full. A translation unit
879
contains just a single basic block (a block of x86 instructions
880
terminated by a jump or by a virtual CPU state change which the
881
translator cannot deduce statically).
882

  
883
@section Direct block chaining
884

  
885
After each translated basic block is executed, QEMU uses the simulated
886
Program Counter (PC) and other cpu state informations (such as the CS
887
segment base value) to find the next basic block.
888

  
889
In order to accelerate the most common cases where the new simulated PC
890
is known, QEMU can patch a basic block so that it jumps directly to the
891
next one.
892

  
893
The most portable code uses an indirect jump. An indirect jump makes it
894
easier to make the jump target modification atomic. On some
895
architectures (such as PowerPC), the @code{JUMP} opcode is directly
896
patched so that the block chaining has no overhead.
897

  
898
@section Self-modifying code and translated code invalidation
899

  
900
Self-modifying code is a special challenge in x86 emulation because no
901
instruction cache invalidation is signaled by the application when code
902
is modified.
903

  
904
When translated code is generated for a basic block, the corresponding
905
host page is write protected if it is not already read-only (with the
906
system call @code{mprotect()}). Then, if a write access is done to the
907
page, Linux raises a SEGV signal. QEMU then invalidates all the
908
translated code in the page and enables write accesses to the page.
909

  
910
Correct translated code invalidation is done efficiently by maintaining
911
a linked list of every translated block contained in a given page. Other
912
linked lists are also maintained to undo direct block chaining. 
913

  
914
Although the overhead of doing @code{mprotect()} calls is important,
915
most MSDOS programs can be emulated at reasonnable speed with QEMU and
916
DOSEMU.
917

  
918
Note that QEMU also invalidates pages of translated code when it detects
919
that memory mappings are modified with @code{mmap()} or @code{munmap()}.
920

  
921
@section Exception support
922

  
923
longjmp() is used when an exception such as division by zero is
924
encountered. 
925

  
926
The host SIGSEGV and SIGBUS signal handlers are used to get invalid
927
memory accesses. The exact CPU state can be retrieved because all the
928
x86 registers are stored in fixed host registers. The simulated program
929
counter is found by retranslating the corresponding basic block and by
930
looking where the host program counter was at the exception point.
931

  
932
The virtual CPU cannot retrieve the exact @code{EFLAGS} register because
933
in some cases it is not computed because of condition code
934
optimisations. It is not a big concern because the emulated code can
935
still be restarted in any cases.
936

  
937
@section Linux system call translation
938

  
939
QEMU includes a generic system call translator for Linux. It means that
940
the parameters of the system calls can be converted to fix the
941
endianness and 32/64 bit issues. The IOCTLs are converted with a generic
942
type description system (see @file{ioctls.h} and @file{thunk.c}).
805
@chapter QEMU User space emulator invocation
943 806

  
944
QEMU supports host CPUs which have pages bigger than 4KB. It records all
945
the mappings the process does and try to emulated the @code{mmap()}
946
system calls in cases where the host @code{mmap()} call would fail
947
because of bad page alignment.
807
@section Quick Start
948 808

  
949
@section Linux signals
809
In order to launch a Linux process, QEMU needs the process executable
810
itself and all the target (x86) dynamic libraries used by it. 
950 811

  
951
Normal and real-time signals are queued along with their information
952
(@code{siginfo_t}) as it is done in the Linux kernel. Then an interrupt
... This diff was truncated because it exceeds the maximum size that can be displayed.

Also available in: Unified diff