1 \input texinfo @c -*- texinfo -*-
3 @settitle QEMU x86 Emulator Reference Documentation
6 @center @titlefont{QEMU x86 Emulator Reference Documentation}
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).
22 @item User space only x86 emulator.
24 @item Currently ported on i386 and PowerPC.
26 @item Using dynamic translation for reasonnable speed.
28 @item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation.
29 User space LDT and GDT are emulated.
31 @item Generic Linux system call converter, including most ioctls.
33 @item clone() emulation using native CPU clone() to use Linux scheduler for threads.
35 @item Accurate signal handling by remapping host signals to virtual x86 signals.
37 @item The virtual x86 CPU is a library (@code{libqemu}) which can be used
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.
45 Current QEMU Limitations:
49 @item Not all x86 exceptions are precise (yet). [Very few programs need that].
51 @item Not self virtualizable (yet). [You cannot launch qemu with qemu on the same CPU].
53 @item No support for self modifying code (yet). [Very few programs need that, a notable exception is QEMU itself !].
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].
59 @item No SSE/MMX support (yet).
61 @item No x86-64 support.
63 @item Some Linux syscalls are missing.
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).
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
78 In order to launch a Linux process, QEMU needs the process executable
79 itself and all the target (x86) dynamic libraries used by it.
83 @item On x86, you can just try to launch any process by using the native
90 @code{-L /} tells that the x86 dynamic linker must be searched with a
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). Ensure that
96 @code{LD_LIBRARY_PATH} is not set:
102 Then you can launch the precompiled @file{ls} x86 executable:
105 qemu /usr/local/qemu-i386/bin/ls-i386
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
114 @section Wine launch (Currently only tested when emulating x86 on x86)
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
123 qemu /usr/local/qemu-i386/bin/ls-i386
126 @item Download the binary x86 wine install
127 (@file{qemu-i386-wine.tar.gz} on the QEMU web page).
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}.
133 @item Then you can try the example @file{putty.exe}:
136 qemu /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
141 @section Command line options
144 usage: qemu [-h] [-d] [-L path] [-s size] program [arguments...]
151 Activate log (logfile=/tmp/qemu.log)
153 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
155 Set the x86 stack size in bytes (default=524288)
158 @chapter QEMU Internals
160 @section QEMU compared to other emulators
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).
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
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]).
180 @section Portable dynamic translation
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
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()}).
195 In essence, the process is similar to [1], but more work is done at
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.
204 That way, QEMU is no more difficult to port than a dynamic linker.
206 To go even faster, GCC static register variables are used to keep the
207 state of the virtual CPU.
209 @section Register allocation
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.
216 @section Condition code optimisations
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
225 @code{CC_OP} is almost never explicitely set in the generated code
226 because it is known at translation time.
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.
234 @section Translation CPU state optimisations
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
243 [The FPU stack pointer register is not handled that way yet].
245 @section Translation cache
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).
253 [Currently, the translated code is not patched if it jumps to another
256 @section Exception support
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.
262 [Currently, the virtual CPU cannot retrieve the exact CPU state in some
263 exceptions, although it could except for the @code{EFLAGS} register].
265 @section Linux system call translation
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}).
272 @section Linux signals
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.
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()}).
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}).
290 @section clone() system call and threads
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
297 The virtual x86 CPU atomic operations are emulated with a global lock so
298 that their semantic is preserved.
300 @section Bibliography
305 @url{http://citeseer.nj.nec.com/piumarta98optimizing.html}, Optimizing
306 direct threaded code by selective inlining (1998) by Ian Piumarta, Fabio
310 @url{http://developer.kde.org/~sewardj/}, Valgrind, an open-source
311 memory debugger for x86-GNU/Linux, by Julian Seward.
314 @url{http://bochs.sourceforge.net/}, the Bochs IA-32 Emulator Project,
315 by Kevin Lawton et al.
318 @url{http://www.cs.rose-hulman.edu/~donaldlf/em86/index.html}, the EM86
319 x86 emulator on Alpha-Linux.
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.
328 @chapter Regression Tests
330 In the directory @file{tests/}, various interesting x86 testing programs
331 are available. There are used for regression testing.
333 @section @file{hello}
335 Very simple statically linked x86 program, just to test QEMU during a
336 port to a new host CPU.
338 @section @file{test-i386}
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.
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.
348 @section @file{testsig}
350 This program tests various signal cases, including SIGFPE, SIGSEGV and
353 @section @file{testclone}
355 Tests the @code{clone()} system call (basic test).
357 @section @file{testthread}
359 Tests the glibc threads (more complicated than @code{clone()} because signals
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.