]>
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 FB |
94 | @item On non x86 CPUs, you need first to download at least an x86 glibc |
95 | (@file{qemu-i386-glibc21.tar.gz} on the QEMU web page). Then you can | |
96 | launch the precompiled @file{ls} x86 executable: | |
97 | @example | |
98 | qemu /usr/local/qemu-i386/bin/ls | |
386405f7 | 99 | @end example |
d691f669 FB |
100 | You can look at @file{/usr/local/qemu-i386/bin/qemu-conf.sh} so that QEMU is automatically |
101 | launched by the Linux kernel when you try to launch x86 executables. It | |
102 | requires the @code{binfmt_misc} module in the Linux kernel. | |
103 | ||
104 | @end itemize | |
105 | ||
106 | @section Command line options | |
107 | ||
108 | @example | |
109 | usage: qemu [-h] [-d] [-L path] [-s size] program [arguments...] | |
110 | @end example | |
111 | ||
112 | @table @samp | |
113 | @item -h | |
114 | Print the help | |
115 | @item -d | |
116 | Activate log (logfile=/tmp/qemu.log) | |
117 | @item -L path | |
118 | Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386) | |
119 | @item -s size | |
120 | Set the x86 stack size in bytes (default=524288) | |
121 | @end table | |
386405f7 FB |
122 | |
123 | @chapter QEMU Internals | |
124 | ||
125 | @section QEMU compared to other emulators | |
126 | ||
127 | Unlike bochs [3], QEMU emulates only a user space x86 CPU. It means that | |
128 | you cannot launch an operating system with it. The benefit is that it is | |
129 | simpler and faster due to the fact that some of the low level CPU state | |
130 | can be ignored (in particular, no virtual memory needs to be emulated). | |
131 | ||
132 | Like Valgrind [2], QEMU does user space emulation and dynamic | |
133 | translation. Valgrind is mainly a memory debugger while QEMU has no | |
134 | support for it (QEMU could be used to detect out of bound memory accesses | |
135 | as Valgrind, but it has no support to track uninitialised data as | |
136 | Valgrind does). Valgrind dynamic translator generates better code than | |
137 | QEMU (in particular it does register allocation) but it is closely tied | |
138 | to an x86 host. | |
139 | ||
140 | EM86 [4] is the closest project to QEMU (and QEMU still uses some of its | |
141 | code, in particular the ELF file loader). EM86 was limited to an alpha | |
142 | host and used a proprietary and slow interpreter (the interpreter part | |
143 | of the FX!32 Digital Win32 code translator [5]). | |
144 | ||
145 | @section Portable dynamic translation | |
146 | ||
147 | QEMU is a dynamic translator. When it first encounters a piece of code, | |
148 | it converts it to the host instruction set. Usually dynamic translators | |
149 | are very complicated and highly CPU dependant. QEMU uses some tricks | |
150 | which make it relatively easily portable and simple while achieving good | |
151 | performances. | |
152 | ||
153 | The basic idea is to split every x86 instruction into fewer simpler | |
154 | instructions. Each simple instruction is implemented by a piece of C | |
155 | code (see @file{op-i386.c}). Then a compile time tool (@file{dyngen}) | |
156 | takes the corresponding object file (@file{op-i386.o}) to generate a | |
157 | dynamic code generator which concatenates the simple instructions to | |
158 | build a function (see @file{op-i386.h:dyngen_code()}). | |
159 | ||
160 | In essence, the process is similar to [1], but more work is done at | |
161 | compile time. | |
162 | ||
163 | A key idea to get optimal performances is that constant parameters can | |
164 | be passed to the simple operations. For that purpose, dummy ELF | |
165 | relocations are generated with gcc for each constant parameter. Then, | |
166 | the tool (@file{dyngen}) can locate the relocations and generate the | |
167 | appriopriate C code to resolve them when building the dynamic code. | |
168 | ||
169 | That way, QEMU is no more difficult to port than a dynamic linker. | |
170 | ||
171 | To go even faster, GCC static register variables are used to keep the | |
172 | state of the virtual CPU. | |
173 | ||
174 | @section Register allocation | |
175 | ||
176 | Since QEMU uses fixed simple instructions, no efficient register | |
177 | allocation can be done. However, because RISC CPUs have a lot of | |
178 | register, most of the virtual CPU state can be put in registers without | |
179 | doing complicated register allocation. | |
180 | ||
181 | @section Condition code optimisations | |
182 | ||
183 | Good CPU condition codes emulation (@code{EFLAGS} register on x86) is a | |
184 | critical point to get good performances. QEMU uses lazy condition code | |
185 | evaluation: instead of computing the condition codes after each x86 | |
186 | instruction, it store justs one operand (called @code{CC_CRC}), the | |
187 | result (called @code{CC_DST}) and the type of operation (called | |
188 | @code{CC_OP}). | |
189 | ||
190 | @code{CC_OP} is almost never explicitely set in the generated code | |
191 | because it is known at translation time. | |
192 | ||
193 | In order to increase performances, a backward pass is performed on the | |
194 | generated simple instructions (see | |
195 | @code{translate-i386.c:optimize_flags()}). When it can be proved that | |
196 | the condition codes are not needed by the next instructions, no | |
197 | condition codes are computed at all. | |
198 | ||
199 | @section Translation CPU state optimisations | |
200 | ||
201 | The x86 CPU has many internal states which change the way it evaluates | |
202 | instructions. In order to achieve a good speed, the translation phase | |
203 | considers that some state information of the virtual x86 CPU cannot | |
204 | change in it. For example, if the SS, DS and ES segments have a zero | |
205 | base, then the translator does not even generate an addition for the | |
206 | segment base. | |
207 | ||
208 | [The FPU stack pointer register is not handled that way yet]. | |
209 | ||
210 | @section Translation cache | |
211 | ||
212 | A 2MByte cache holds the most recently used translations. For | |
213 | simplicity, it is completely flushed when it is full. A translation unit | |
214 | contains just a single basic block (a block of x86 instructions | |
215 | terminated by a jump or by a virtual CPU state change which the | |
216 | translator cannot deduce statically). | |
217 | ||
218 | [Currently, the translated code is not patched if it jumps to another | |
219 | translated code]. | |
220 | ||
221 | @section Exception support | |
222 | ||
223 | longjmp() is used when an exception such as division by zero is | |
224 | encountered. The host SIGSEGV and SIGBUS signal handlers are used to get | |
225 | invalid memory accesses. | |
226 | ||
227 | [Currently, the virtual CPU cannot retrieve the exact CPU state in some | |
228 | exceptions, although it could except for the @code{EFLAGS} register]. | |
229 | ||
230 | @section Linux system call translation | |
231 | ||
232 | QEMU includes a generic system call translator for Linux. It means that | |
233 | the parameters of the system calls can be converted to fix the | |
234 | endianness and 32/64 bit issues. The IOCTLs are converted with a generic | |
235 | type description system (see @file{ioctls.h} and @file{thunk.c}). | |
236 | ||
237 | @section Linux signals | |
238 | ||
239 | Normal and real-time signals are queued along with their information | |
240 | (@code{siginfo_t}) as it is done in the Linux kernel. Then an interrupt | |
241 | request is done to the virtual CPU. When it is interrupted, one queued | |
242 | signal is handled by generating a stack frame in the virtual CPU as the | |
243 | Linux kernel does. The @code{sigreturn()} system call is emulated to return | |
244 | from the virtual signal handler. | |
245 | ||
246 | Some signals (such as SIGALRM) directly come from the host. Other | |
247 | signals are synthetized from the virtual CPU exceptions such as SIGFPE | |
248 | when a division by zero is done (see @code{main.c:cpu_loop()}). | |
249 | ||
250 | The blocked signal mask is still handled by the host Linux kernel so | |
251 | that most signal system calls can be redirected directly to the host | |
252 | Linux kernel. Only the @code{sigaction()} and @code{sigreturn()} system | |
253 | calls need to be fully emulated (see @file{signal.c}). | |
254 | ||
255 | @section clone() system call and threads | |
256 | ||
257 | The Linux clone() system call is usually used to create a thread. QEMU | |
258 | uses the host clone() system call so that real host threads are created | |
259 | for each emulated thread. One virtual CPU instance is created for each | |
260 | thread. | |
261 | ||
262 | The virtual x86 CPU atomic operations are emulated with a global lock so | |
263 | that their semantic is preserved. | |
264 | ||
265 | @section Bibliography | |
266 | ||
267 | @table @asis | |
268 | ||
269 | @item [1] | |
270 | @url{http://citeseer.nj.nec.com/piumarta98optimizing.html}, Optimizing | |
271 | direct threaded code by selective inlining (1998) by Ian Piumarta, Fabio | |
272 | Riccardi. | |
273 | ||
274 | @item [2] | |
275 | @url{http://developer.kde.org/~sewardj/}, Valgrind, an open-source | |
276 | memory debugger for x86-GNU/Linux, by Julian Seward. | |
277 | ||
278 | @item [3] | |
279 | @url{http://bochs.sourceforge.net/}, the Bochs IA-32 Emulator Project, | |
280 | by Kevin Lawton et al. | |
281 | ||
282 | @item [4] | |
283 | @url{http://www.cs.rose-hulman.edu/~donaldlf/em86/index.html}, the EM86 | |
284 | x86 emulator on Alpha-Linux. | |
285 | ||
286 | @item [5] | |
287 | @url{http://www.usenix.org/publications/library/proceedings/usenix-nt97/full_papers/chernoff/chernoff.pdf}, | |
288 | DIGITAL FX!32: Running 32-Bit x86 Applications on Alpha NT, by Anton | |
289 | Chernoff and Ray Hookway. | |
290 | ||
291 | @end table | |
292 | ||
293 | @chapter Regression Tests | |
294 | ||
295 | In the directory @file{tests/}, various interesting x86 testing programs | |
296 | are available. There are used for regression testing. | |
297 | ||
298 | @section @file{hello} | |
299 | ||
300 | Very simple statically linked x86 program, just to test QEMU during a | |
301 | port to a new host CPU. | |
302 | ||
303 | @section @file{test-i386} | |
304 | ||
305 | This program executes most of the 16 bit and 32 bit x86 instructions and | |
306 | generates a text output. It can be compared with the output obtained with | |
307 | a real CPU or another emulator. The target @code{make test} runs this | |
308 | program and a @code{diff} on the generated output. | |
309 | ||
310 | The Linux system call @code{modify_ldt()} is used to create x86 selectors | |
311 | to test some 16 bit addressing and 32 bit with segmentation cases. | |
312 | ||
313 | @section @file{testsig} | |
314 | ||
315 | This program tests various signal cases, including SIGFPE, SIGSEGV and | |
316 | SIGILL. | |
317 | ||
318 | @section @file{testclone} | |
319 | ||
320 | Tests the @code{clone()} system call (basic test). | |
321 | ||
322 | @section @file{testthread} | |
323 | ||
324 | Tests the glibc threads (more complicated than @code{clone()} because signals | |
325 | are also used). | |
326 | ||
327 | @section @file{sha1} | |
328 | ||
329 | It is a simple benchmark. Care must be taken to interpret the results | |
330 | because it mostly tests the ability of the virtual CPU to optimize the | |
331 | @code{rol} x86 instruction and the condition code computations. | |
332 |