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