]>
Commit | Line | Data |
---|---|---|
386405f7 FB |
1 | \input texinfo @c -*- texinfo -*- |
2 | ||
3 | @settitle QEMU x86 Emulator Reference Documentation | |
4 | @titlepage | |
5 | @sp 7 | |
6 | @center @titlefont{QEMU x86 Emulator Reference Documentation} | |
7 | @sp 3 | |
8 | @end titlepage | |
9 | ||
10 | @chapter Introduction | |
11 | ||
12 | QEMU is an x86 processor emulator. Its purpose is to run x86 Linux | |
13 | processes on non-x86 Linux architectures such as PowerPC or ARM. By | |
14 | using dynamic translation it achieves a reasonnable speed while being | |
15 | easy to port on new host CPUs. An obviously interesting x86 only process | |
16 | is 'wine' (Windows emulation). | |
17 | ||
18 | QEMU features: | |
19 | ||
20 | @itemize | |
21 | ||
22 | @item User space only x86 emulator. | |
23 | ||
24 | @item Currently ported on i386 and PowerPC. | |
25 | ||
26 | @item Using dynamic translation for reasonnable speed. | |
27 | ||
28 | @item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation. | |
29 | User space LDT and GDT are emulated. | |
30 | ||
31 | @item Generic Linux system call converter, including most ioctls. | |
32 | ||
33 | @item clone() emulation using native CPU clone() to use Linux scheduler for threads. | |
34 | ||
35 | @item Accurate signal handling by remapping host signals to virtual x86 signals. | |
36 | ||
37 | @item The virtual x86 CPU is a library (@code{libqemu}) which can be used | |
38 | in other projects. | |
39 | ||
40 | @item An extensive Linux x86 CPU test program is included @file{tests/test-i386}. | |
41 | It can be used to test other x86 virtual CPUs. | |
42 | ||
43 | @end itemize | |
44 | ||
45 | Current QEMU Limitations: | |
46 | ||
47 | @itemize | |
48 | ||
49 | @item Not all x86 exceptions are precise (yet). [Very few programs need that]. | |
50 | ||
51 | @item Not self virtualizable (yet). [You cannot launch qemu with qemu on the same CPU]. | |
52 | ||
53 | @item No support for self modifying code (yet). [Very few programs need that, a notable exception is QEMU itself !]. | |
54 | ||
55 | @item No VM86 mode (yet), althought the virtual | |
56 | CPU has support for most of it. [VM86 support is useful to launch old 16 | |
57 | bit DOS programs with dosemu or wine]. | |
58 | ||
59 | @item No SSE/MMX support (yet). | |
60 | ||
61 | @item No x86-64 support. | |
62 | ||
63 | @item Some Linux syscalls are missing. | |
64 | ||
65 | @item The x86 segment limits and access rights are not tested at every | |
66 | memory access (and will never be to have good performances). | |
67 | ||
68 | @item On non x86 host CPUs, @code{double}s are used instead of the non standard | |
69 | 10 byte @code{long double}s of x86 for floating point emulation to get | |
70 | maximum performances. | |
71 | ||
72 | @end itemize | |
73 | ||
74 | @chapter Invocation | |
75 | ||
d691f669 FB |
76 | @section Quick Start |
77 | ||
386405f7 | 78 | In order to launch a Linux process, QEMU needs the process executable |
d691f669 FB |
79 | itself and all the target (x86) dynamic libraries used by it. |
80 | ||
81 | @itemize | |
386405f7 | 82 | |
d691f669 FB |
83 | @item On x86, you can just try to launch any process by using the native |
84 | libraries: | |
386405f7 FB |
85 | |
86 | @example | |
d691f669 | 87 | qemu -L / /bin/ls |
386405f7 FB |
88 | @end example |
89 | ||
d691f669 FB |
90 | @code{-L /} tells that the x86 dynamic linker must be searched with a |
91 | @file{/} prefix. | |
386405f7 | 92 | |
386405f7 | 93 | |
d691f669 | 94 | @item On non x86 CPUs, you need first to download at least an x86 glibc |
644c433c FB |
95 | (@file{qemu-i386-glibc21.tar.gz} on the QEMU web page). Ensure that |
96 | @code{LD_LIBRARY_PATH} is not set: | |
97 | ||
98 | @example | |
99 | unset LD_LIBRARY_PATH | |
100 | @end example | |
101 | ||
102 | Then you can launch the precompiled @file{ls} x86 executable: | |
103 | ||
d691f669 | 104 | @example |
168485b7 FB |
105 | qemu /usr/local/qemu-i386/bin/ls-i386 |
106 | @end example | |
107 | You can look at @file{/usr/local/qemu-i386/bin/qemu-conf.sh} so that | |
108 | QEMU is automatically launched by the Linux kernel when you try to | |
109 | launch x86 executables. It requires the @code{binfmt_misc} module in the | |
110 | Linux kernel. | |
111 | ||
112 | @end itemize | |
113 | ||
114 | @section Wine launch (Currently only tested when emulating x86 on x86) | |
115 | ||
116 | @itemize | |
117 | ||
118 | @item Ensure that you have a working QEMU with the x86 glibc | |
119 | distribution (see previous section). In order to verify it, you must be | |
120 | able to do: | |
121 | ||
122 | @example | |
123 | qemu /usr/local/qemu-i386/bin/ls-i386 | |
124 | @end example | |
125 | ||
126 | @item Download the binary x86 wine install | |
127 | (@file{qemu-i386-wine.tar.gz} on the QEMU web page). | |
128 | ||
129 | @item Configure wine on your account. Look at the provided script | |
130 | @file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous | |
131 | @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}. | |
132 | ||
133 | @item Then you can try the example @file{putty.exe}: | |
134 | ||
135 | @example | |
136 | qemu /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe | |
386405f7 | 137 | @end example |
d691f669 FB |
138 | |
139 | @end itemize | |
140 | ||
141 | @section Command line options | |
142 | ||
143 | @example | |
144 | usage: qemu [-h] [-d] [-L path] [-s size] program [arguments...] | |
145 | @end example | |
146 | ||
147 | @table @samp | |
148 | @item -h | |
149 | Print the help | |
150 | @item -d | |
151 | Activate log (logfile=/tmp/qemu.log) | |
152 | @item -L path | |
153 | Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386) | |
154 | @item -s size | |
155 | Set the x86 stack size in bytes (default=524288) | |
156 | @end table | |
386405f7 FB |
157 | |
158 | @chapter QEMU Internals | |
159 | ||
160 | @section QEMU compared to other emulators | |
161 | ||
162 | Unlike bochs [3], QEMU emulates only a user space x86 CPU. It means that | |
163 | you cannot launch an operating system with it. The benefit is that it is | |
164 | simpler and faster due to the fact that some of the low level CPU state | |
165 | can be ignored (in particular, no virtual memory needs to be emulated). | |
166 | ||
167 | Like Valgrind [2], QEMU does user space emulation and dynamic | |
168 | translation. Valgrind is mainly a memory debugger while QEMU has no | |
169 | support for it (QEMU could be used to detect out of bound memory accesses | |
170 | as Valgrind, but it has no support to track uninitialised data as | |
171 | Valgrind does). Valgrind dynamic translator generates better code than | |
172 | QEMU (in particular it does register allocation) but it is closely tied | |
173 | to an x86 host. | |
174 | ||
175 | EM86 [4] is the closest project to QEMU (and QEMU still uses some of its | |
176 | code, in particular the ELF file loader). EM86 was limited to an alpha | |
177 | host and used a proprietary and slow interpreter (the interpreter part | |
178 | of the FX!32 Digital Win32 code translator [5]). | |
179 | ||
180 | @section Portable dynamic translation | |
181 | ||
182 | QEMU is a dynamic translator. When it first encounters a piece of code, | |
183 | it converts it to the host instruction set. Usually dynamic translators | |
184 | are very complicated and highly CPU dependant. QEMU uses some tricks | |
185 | which make it relatively easily portable and simple while achieving good | |
186 | performances. | |
187 | ||
188 | The basic idea is to split every x86 instruction into fewer simpler | |
189 | instructions. Each simple instruction is implemented by a piece of C | |
190 | code (see @file{op-i386.c}). Then a compile time tool (@file{dyngen}) | |
191 | takes the corresponding object file (@file{op-i386.o}) to generate a | |
192 | dynamic code generator which concatenates the simple instructions to | |
193 | build a function (see @file{op-i386.h:dyngen_code()}). | |
194 | ||
195 | In essence, the process is similar to [1], but more work is done at | |
196 | compile time. | |
197 | ||
198 | A key idea to get optimal performances is that constant parameters can | |
199 | be passed to the simple operations. For that purpose, dummy ELF | |
200 | relocations are generated with gcc for each constant parameter. Then, | |
201 | the tool (@file{dyngen}) can locate the relocations and generate the | |
202 | appriopriate C code to resolve them when building the dynamic code. | |
203 | ||
204 | That way, QEMU is no more difficult to port than a dynamic linker. | |
205 | ||
206 | To go even faster, GCC static register variables are used to keep the | |
207 | state of the virtual CPU. | |
208 | ||
209 | @section Register allocation | |
210 | ||
211 | Since QEMU uses fixed simple instructions, no efficient register | |
212 | allocation can be done. However, because RISC CPUs have a lot of | |
213 | register, most of the virtual CPU state can be put in registers without | |
214 | doing complicated register allocation. | |
215 | ||
216 | @section Condition code optimisations | |
217 | ||
218 | Good CPU condition codes emulation (@code{EFLAGS} register on x86) is a | |
219 | critical point to get good performances. QEMU uses lazy condition code | |
220 | evaluation: instead of computing the condition codes after each x86 | |
221 | instruction, it store justs one operand (called @code{CC_CRC}), the | |
222 | result (called @code{CC_DST}) and the type of operation (called | |
223 | @code{CC_OP}). | |
224 | ||
225 | @code{CC_OP} is almost never explicitely set in the generated code | |
226 | because it is known at translation time. | |
227 | ||
228 | In order to increase performances, a backward pass is performed on the | |
229 | generated simple instructions (see | |
230 | @code{translate-i386.c:optimize_flags()}). When it can be proved that | |
231 | the condition codes are not needed by the next instructions, no | |
232 | condition codes are computed at all. | |
233 | ||
234 | @section Translation CPU state optimisations | |
235 | ||
236 | The x86 CPU has many internal states which change the way it evaluates | |
237 | instructions. In order to achieve a good speed, the translation phase | |
238 | considers that some state information of the virtual x86 CPU cannot | |
239 | change in it. For example, if the SS, DS and ES segments have a zero | |
240 | base, then the translator does not even generate an addition for the | |
241 | segment base. | |
242 | ||
243 | [The FPU stack pointer register is not handled that way yet]. | |
244 | ||
245 | @section Translation cache | |
246 | ||
247 | A 2MByte cache holds the most recently used translations. For | |
248 | simplicity, it is completely flushed when it is full. A translation unit | |
249 | contains just a single basic block (a block of x86 instructions | |
250 | terminated by a jump or by a virtual CPU state change which the | |
251 | translator cannot deduce statically). | |
252 | ||
253 | [Currently, the translated code is not patched if it jumps to another | |
254 | translated code]. | |
255 | ||
256 | @section Exception support | |
257 | ||
258 | longjmp() is used when an exception such as division by zero is | |
259 | encountered. The host SIGSEGV and SIGBUS signal handlers are used to get | |
260 | invalid memory accesses. | |
261 | ||
262 | [Currently, the virtual CPU cannot retrieve the exact CPU state in some | |
263 | exceptions, although it could except for the @code{EFLAGS} register]. | |
264 | ||
265 | @section Linux system call translation | |
266 | ||
267 | QEMU includes a generic system call translator for Linux. It means that | |
268 | the parameters of the system calls can be converted to fix the | |
269 | endianness and 32/64 bit issues. The IOCTLs are converted with a generic | |
270 | type description system (see @file{ioctls.h} and @file{thunk.c}). | |
271 | ||
272 | @section Linux signals | |
273 | ||
274 | Normal and real-time signals are queued along with their information | |
275 | (@code{siginfo_t}) as it is done in the Linux kernel. Then an interrupt | |
276 | request is done to the virtual CPU. When it is interrupted, one queued | |
277 | signal is handled by generating a stack frame in the virtual CPU as the | |
278 | Linux kernel does. The @code{sigreturn()} system call is emulated to return | |
279 | from the virtual signal handler. | |
280 | ||
281 | Some signals (such as SIGALRM) directly come from the host. Other | |
282 | signals are synthetized from the virtual CPU exceptions such as SIGFPE | |
283 | when a division by zero is done (see @code{main.c:cpu_loop()}). | |
284 | ||
285 | The blocked signal mask is still handled by the host Linux kernel so | |
286 | that most signal system calls can be redirected directly to the host | |
287 | Linux kernel. Only the @code{sigaction()} and @code{sigreturn()} system | |
288 | calls need to be fully emulated (see @file{signal.c}). | |
289 | ||
290 | @section clone() system call and threads | |
291 | ||
292 | The Linux clone() system call is usually used to create a thread. QEMU | |
293 | uses the host clone() system call so that real host threads are created | |
294 | for each emulated thread. One virtual CPU instance is created for each | |
295 | thread. | |
296 | ||
297 | The virtual x86 CPU atomic operations are emulated with a global lock so | |
298 | that their semantic is preserved. | |
299 | ||
300 | @section Bibliography | |
301 | ||
302 | @table @asis | |
303 | ||
304 | @item [1] | |
305 | @url{http://citeseer.nj.nec.com/piumarta98optimizing.html}, Optimizing | |
306 | direct threaded code by selective inlining (1998) by Ian Piumarta, Fabio | |
307 | Riccardi. | |
308 | ||
309 | @item [2] | |
310 | @url{http://developer.kde.org/~sewardj/}, Valgrind, an open-source | |
311 | memory debugger for x86-GNU/Linux, by Julian Seward. | |
312 | ||
313 | @item [3] | |
314 | @url{http://bochs.sourceforge.net/}, the Bochs IA-32 Emulator Project, | |
315 | by Kevin Lawton et al. | |
316 | ||
317 | @item [4] | |
318 | @url{http://www.cs.rose-hulman.edu/~donaldlf/em86/index.html}, the EM86 | |
319 | x86 emulator on Alpha-Linux. | |
320 | ||
321 | @item [5] | |
322 | @url{http://www.usenix.org/publications/library/proceedings/usenix-nt97/full_papers/chernoff/chernoff.pdf}, | |
323 | DIGITAL FX!32: Running 32-Bit x86 Applications on Alpha NT, by Anton | |
324 | Chernoff and Ray Hookway. | |
325 | ||
326 | @end table | |
327 | ||
328 | @chapter Regression Tests | |
329 | ||
330 | In the directory @file{tests/}, various interesting x86 testing programs | |
331 | are available. There are used for regression testing. | |
332 | ||
333 | @section @file{hello} | |
334 | ||
335 | Very simple statically linked x86 program, just to test QEMU during a | |
336 | port to a new host CPU. | |
337 | ||
338 | @section @file{test-i386} | |
339 | ||
340 | This program executes most of the 16 bit and 32 bit x86 instructions and | |
341 | generates a text output. It can be compared with the output obtained with | |
342 | a real CPU or another emulator. The target @code{make test} runs this | |
343 | program and a @code{diff} on the generated output. | |
344 | ||
345 | The Linux system call @code{modify_ldt()} is used to create x86 selectors | |
346 | to test some 16 bit addressing and 32 bit with segmentation cases. | |
347 | ||
348 | @section @file{testsig} | |
349 | ||
350 | This program tests various signal cases, including SIGFPE, SIGSEGV and | |
351 | SIGILL. | |
352 | ||
353 | @section @file{testclone} | |
354 | ||
355 | Tests the @code{clone()} system call (basic test). | |
356 | ||
357 | @section @file{testthread} | |
358 | ||
359 | Tests the glibc threads (more complicated than @code{clone()} because signals | |
360 | are also used). | |
361 | ||
362 | @section @file{sha1} | |
363 | ||
364 | It is a simple benchmark. Care must be taken to interpret the results | |
365 | because it mostly tests the ability of the virtual CPU to optimize the | |
366 | @code{rol} x86 instruction and the condition code computations. | |
367 |