Strace for userland emulation, by Stuart Anderson and Thayne Harbaugh.
[qemu/qemu_0_9_1_stable.git] / qemu-tech.texi
blob9147096d93f59510af4fb7087faf35db8b0aefee
1 \input texinfo @c -*- texinfo -*-
2 @c %**start of header
3 @setfilename qemu-tech.info
4 @settitle QEMU Internals
5 @exampleindent 0
6 @paragraphindent 0
7 @c %**end of header
9 @iftex
10 @titlepage
11 @sp 7
12 @center @titlefont{QEMU Internals}
13 @sp 3
14 @end titlepage
15 @end iftex
17 @ifnottex
18 @node Top
19 @top
21 @menu
22 * Introduction::
23 * QEMU Internals::
24 * Regression Tests::
25 * Index::
26 @end menu
27 @end ifnottex
29 @contents
31 @node Introduction
32 @chapter Introduction
34 @menu
35 * intro_features::        Features
36 * intro_x86_emulation::   x86 emulation
37 * intro_arm_emulation::   ARM emulation
38 * intro_mips_emulation::  MIPS emulation
39 * intro_ppc_emulation::   PowerPC emulation
40 * intro_sparc_emulation:: SPARC emulation
41 @end menu
43 @node intro_features
44 @section Features
46 QEMU is a FAST! processor emulator using a portable dynamic
47 translator.
49 QEMU has two operating modes:
51 @itemize @minus
53 @item
54 Full system emulation. In this mode, QEMU emulates a full system
55 (usually a PC), including a processor and various peripherals. It can
56 be used to launch an different Operating System without rebooting the
57 PC or to debug system code.
59 @item
60 User mode emulation (Linux host only). In this mode, QEMU can launch
61 Linux processes compiled for one CPU on another CPU. It can be used to
62 launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
63 to ease cross-compilation and cross-debugging.
65 @end itemize
67 As QEMU requires no host kernel driver to run, it is very safe and
68 easy to use.
70 QEMU generic features:
72 @itemize
74 @item User space only or full system emulation.
76 @item Using dynamic translation to native code for reasonable speed.
78 @item Working on x86 and PowerPC hosts. Being tested on ARM, Sparc32, Alpha and S390.
80 @item Self-modifying code support.
82 @item Precise exceptions support.
84 @item The virtual CPU is a library (@code{libqemu}) which can be used
85 in other projects (look at @file{qemu/tests/qruncom.c} to have an
86 example of user mode @code{libqemu} usage).
88 @end itemize
90 QEMU user mode emulation features:
91 @itemize
92 @item Generic Linux system call converter, including most ioctls.
94 @item clone() emulation using native CPU clone() to use Linux scheduler for threads.
96 @item Accurate signal handling by remapping host signals to target signals.
97 @end itemize
99 QEMU full system emulation features:
100 @itemize
101 @item QEMU can either use a full software MMU for maximum portability or use the host system call mmap() to simulate the target MMU.
102 @end itemize
104 @node intro_x86_emulation
105 @section x86 emulation
107 QEMU x86 target features:
109 @itemize
111 @item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation.
112 LDT/GDT and IDT are emulated. VM86 mode is also supported to run DOSEMU.
114 @item Support of host page sizes bigger than 4KB in user mode emulation.
116 @item QEMU can emulate itself on x86.
118 @item An extensive Linux x86 CPU test program is included @file{tests/test-i386}.
119 It can be used to test other x86 virtual CPUs.
121 @end itemize
123 Current QEMU limitations:
125 @itemize
127 @item No SSE/MMX support (yet).
129 @item No x86-64 support.
131 @item IPC syscalls are missing.
133 @item The x86 segment limits and access rights are not tested at every
134 memory access (yet). Hopefully, very few OSes seem to rely on that for
135 normal use.
137 @item On non x86 host CPUs, @code{double}s are used instead of the non standard
138 10 byte @code{long double}s of x86 for floating point emulation to get
139 maximum performances.
141 @end itemize
143 @node intro_arm_emulation
144 @section ARM emulation
146 @itemize
148 @item Full ARM 7 user emulation.
150 @item NWFPE FPU support included in user Linux emulation.
152 @item Can run most ARM Linux binaries.
154 @end itemize
156 @node intro_mips_emulation
157 @section MIPS emulation
159 @itemize
161 @item The system emulation allows full MIPS32/MIPS64 Release 2 emulation,
162 including privileged instructions, FPU and MMU, in both little and big
163 endian modes.
165 @item The Linux userland emulation can run many 32 bit MIPS Linux binaries.
167 @end itemize
169 Current QEMU limitations:
171 @itemize
173 @item Self-modifying code is not always handled correctly.
175 @item 64 bit userland emulation is not implemented.
177 @item The system emulation is not complete enough to run real firmware.
179 @item The watchpoint debug facility is not implemented.
181 @end itemize
183 @node intro_ppc_emulation
184 @section PowerPC emulation
186 @itemize
188 @item Full PowerPC 32 bit emulation, including privileged instructions,
189 FPU and MMU.
191 @item Can run most PowerPC Linux binaries.
193 @end itemize
195 @node intro_sparc_emulation
196 @section SPARC emulation
198 @itemize
200 @item Full SPARC V8 emulation, including privileged
201 instructions, FPU and MMU. SPARC V9 emulation includes most privileged
202 and VIS instructions, FPU and I/D MMU. Alignment is fully enforced.
204 @item Can run most 32-bit SPARC Linux binaries, SPARC32PLUS Linux binaries and
205 some 64-bit SPARC Linux binaries.
207 @end itemize
209 Current QEMU limitations:
211 @itemize
213 @item IPC syscalls are missing.
215 @item 128-bit floating point operations are not supported, though none of the
216 real CPUs implement them either.  Floating point exception support is untested.
218 @item Atomic instructions are not correctly implemented.
220 @item Sparc64 emulators are not usable for anything yet.
222 @end itemize
224 @node QEMU Internals
225 @chapter QEMU Internals
227 @menu
228 * QEMU compared to other emulators::
229 * Portable dynamic translation::
230 * Register allocation::
231 * Condition code optimisations::
232 * CPU state optimisations::
233 * Translation cache::
234 * Direct block chaining::
235 * Self-modifying code and translated code invalidation::
236 * Exception support::
237 * MMU emulation::
238 * Hardware interrupts::
239 * User emulation specific details::
240 * Bibliography::
241 @end menu
243 @node QEMU compared to other emulators
244 @section QEMU compared to other emulators
246 Like bochs [3], QEMU emulates an x86 CPU. But QEMU is much faster than
247 bochs as it uses dynamic compilation. Bochs is closely tied to x86 PC
248 emulation while QEMU can emulate several processors.
250 Like Valgrind [2], QEMU does user space emulation and dynamic
251 translation. Valgrind is mainly a memory debugger while QEMU has no
252 support for it (QEMU could be used to detect out of bound memory
253 accesses as Valgrind, but it has no support to track uninitialised data
254 as Valgrind does). The Valgrind dynamic translator generates better code
255 than QEMU (in particular it does register allocation) but it is closely
256 tied to an x86 host and target and has no support for precise exceptions
257 and system emulation.
259 EM86 [4] is the closest project to user space QEMU (and QEMU still uses
260 some of its code, in particular the ELF file loader). EM86 was limited
261 to an alpha host and used a proprietary and slow interpreter (the
262 interpreter part of the FX!32 Digital Win32 code translator [5]).
264 TWIN [6] is a Windows API emulator like Wine. It is less accurate than
265 Wine but includes a protected mode x86 interpreter to launch x86 Windows
266 executables. Such an approach has greater potential because most of the
267 Windows API is executed natively but it is far more difficult to develop
268 because all the data structures and function parameters exchanged
269 between the API and the x86 code must be converted.
271 User mode Linux [7] was the only solution before QEMU to launch a
272 Linux kernel as a process while not needing any host kernel
273 patches. However, user mode Linux requires heavy kernel patches while
274 QEMU accepts unpatched Linux kernels. The price to pay is that QEMU is
275 slower.
277 The new Plex86 [8] PC virtualizer is done in the same spirit as the
278 qemu-fast system emulator. It requires a patched Linux kernel to work
279 (you cannot launch the same kernel on your PC), but the patches are
280 really small. As it is a PC virtualizer (no emulation is done except
281 for some priveledged instructions), it has the potential of being
282 faster than QEMU. The downside is that a complicated (and potentially
283 unsafe) host kernel patch is needed.
285 The commercial PC Virtualizers (VMWare [9], VirtualPC [10], TwoOStwo
286 [11]) are faster than QEMU, but they all need specific, proprietary
287 and potentially unsafe host drivers. Moreover, they are unable to
288 provide cycle exact simulation as an emulator can.
290 @node Portable dynamic translation
291 @section Portable dynamic translation
293 QEMU is a dynamic translator. When it first encounters a piece of code,
294 it converts it to the host instruction set. Usually dynamic translators
295 are very complicated and highly CPU dependent. QEMU uses some tricks
296 which make it relatively easily portable and simple while achieving good
297 performances.
299 The basic idea is to split every x86 instruction into fewer simpler
300 instructions. Each simple instruction is implemented by a piece of C
301 code (see @file{target-i386/op.c}). Then a compile time tool
302 (@file{dyngen}) takes the corresponding object file (@file{op.o})
303 to generate a dynamic code generator which concatenates the simple
304 instructions to build a function (see @file{op.h:dyngen_code()}).
306 In essence, the process is similar to [1], but more work is done at
307 compile time.
309 A key idea to get optimal performances is that constant parameters can
310 be passed to the simple operations. For that purpose, dummy ELF
311 relocations are generated with gcc for each constant parameter. Then,
312 the tool (@file{dyngen}) can locate the relocations and generate the
313 appriopriate C code to resolve them when building the dynamic code.
315 That way, QEMU is no more difficult to port than a dynamic linker.
317 To go even faster, GCC static register variables are used to keep the
318 state of the virtual CPU.
320 @node Register allocation
321 @section Register allocation
323 Since QEMU uses fixed simple instructions, no efficient register
324 allocation can be done. However, because RISC CPUs have a lot of
325 register, most of the virtual CPU state can be put in registers without
326 doing complicated register allocation.
328 @node Condition code optimisations
329 @section Condition code optimisations
331 Good CPU condition codes emulation (@code{EFLAGS} register on x86) is a
332 critical point to get good performances. QEMU uses lazy condition code
333 evaluation: instead of computing the condition codes after each x86
334 instruction, it just stores one operand (called @code{CC_SRC}), the
335 result (called @code{CC_DST}) and the type of operation (called
336 @code{CC_OP}).
338 @code{CC_OP} is almost never explicitely set in the generated code
339 because it is known at translation time.
341 In order to increase performances, a backward pass is performed on the
342 generated simple instructions (see
343 @code{target-i386/translate.c:optimize_flags()}). When it can be proved that
344 the condition codes are not needed by the next instructions, no
345 condition codes are computed at all.
347 @node CPU state optimisations
348 @section CPU state optimisations
350 The x86 CPU has many internal states which change the way it evaluates
351 instructions. In order to achieve a good speed, the translation phase
352 considers that some state information of the virtual x86 CPU cannot
353 change in it. For example, if the SS, DS and ES segments have a zero
354 base, then the translator does not even generate an addition for the
355 segment base.
357 [The FPU stack pointer register is not handled that way yet].
359 @node Translation cache
360 @section Translation cache
362 A 16 MByte cache holds the most recently used translations. For
363 simplicity, it is completely flushed when it is full. A translation unit
364 contains just a single basic block (a block of x86 instructions
365 terminated by a jump or by a virtual CPU state change which the
366 translator cannot deduce statically).
368 @node Direct block chaining
369 @section Direct block chaining
371 After each translated basic block is executed, QEMU uses the simulated
372 Program Counter (PC) and other cpu state informations (such as the CS
373 segment base value) to find the next basic block.
375 In order to accelerate the most common cases where the new simulated PC
376 is known, QEMU can patch a basic block so that it jumps directly to the
377 next one.
379 The most portable code uses an indirect jump. An indirect jump makes
380 it easier to make the jump target modification atomic. On some host
381 architectures (such as x86 or PowerPC), the @code{JUMP} opcode is
382 directly patched so that the block chaining has no overhead.
384 @node Self-modifying code and translated code invalidation
385 @section Self-modifying code and translated code invalidation
387 Self-modifying code is a special challenge in x86 emulation because no
388 instruction cache invalidation is signaled by the application when code
389 is modified.
391 When translated code is generated for a basic block, the corresponding
392 host page is write protected if it is not already read-only (with the
393 system call @code{mprotect()}). Then, if a write access is done to the
394 page, Linux raises a SEGV signal. QEMU then invalidates all the
395 translated code in the page and enables write accesses to the page.
397 Correct translated code invalidation is done efficiently by maintaining
398 a linked list of every translated block contained in a given page. Other
399 linked lists are also maintained to undo direct block chaining.
401 Although the overhead of doing @code{mprotect()} calls is important,
402 most MSDOS programs can be emulated at reasonnable speed with QEMU and
403 DOSEMU.
405 Note that QEMU also invalidates pages of translated code when it detects
406 that memory mappings are modified with @code{mmap()} or @code{munmap()}.
408 When using a software MMU, the code invalidation is more efficient: if
409 a given code page is invalidated too often because of write accesses,
410 then a bitmap representing all the code inside the page is
411 built. Every store into that page checks the bitmap to see if the code
412 really needs to be invalidated. It avoids invalidating the code when
413 only data is modified in the page.
415 @node Exception support
416 @section Exception support
418 longjmp() is used when an exception such as division by zero is
419 encountered.
421 The host SIGSEGV and SIGBUS signal handlers are used to get invalid
422 memory accesses. The exact CPU state can be retrieved because all the
423 x86 registers are stored in fixed host registers. The simulated program
424 counter is found by retranslating the corresponding basic block and by
425 looking where the host program counter was at the exception point.
427 The virtual CPU cannot retrieve the exact @code{EFLAGS} register because
428 in some cases it is not computed because of condition code
429 optimisations. It is not a big concern because the emulated code can
430 still be restarted in any cases.
432 @node MMU emulation
433 @section MMU emulation
435 For system emulation, QEMU uses the mmap() system call to emulate the
436 target CPU MMU. It works as long the emulated OS does not use an area
437 reserved by the host OS (such as the area above 0xc0000000 on x86
438 Linux).
440 In order to be able to launch any OS, QEMU also supports a soft
441 MMU. In that mode, the MMU virtual to physical address translation is
442 done at every memory access. QEMU uses an address translation cache to
443 speed up the translation.
445 In order to avoid flushing the translated code each time the MMU
446 mappings change, QEMU uses a physically indexed translation cache. It
447 means that each basic block is indexed with its physical address.
449 When MMU mappings change, only the chaining of the basic blocks is
450 reset (i.e. a basic block can no longer jump directly to another one).
452 @node Hardware interrupts
453 @section Hardware interrupts
455 In order to be faster, QEMU does not check at every basic block if an
456 hardware interrupt is pending. Instead, the user must asynchrously
457 call a specific function to tell that an interrupt is pending. This
458 function resets the chaining of the currently executing basic
459 block. It ensures that the execution will return soon in the main loop
460 of the CPU emulator. Then the main loop can test if the interrupt is
461 pending and handle it.
463 @node User emulation specific details
464 @section User emulation specific details
466 @subsection Linux system call translation
468 QEMU includes a generic system call translator for Linux. It means that
469 the parameters of the system calls can be converted to fix the
470 endianness and 32/64 bit issues. The IOCTLs are converted with a generic
471 type description system (see @file{ioctls.h} and @file{thunk.c}).
473 QEMU supports host CPUs which have pages bigger than 4KB. It records all
474 the mappings the process does and try to emulated the @code{mmap()}
475 system calls in cases where the host @code{mmap()} call would fail
476 because of bad page alignment.
478 @subsection Linux signals
480 Normal and real-time signals are queued along with their information
481 (@code{siginfo_t}) as it is done in the Linux kernel. Then an interrupt
482 request is done to the virtual CPU. When it is interrupted, one queued
483 signal is handled by generating a stack frame in the virtual CPU as the
484 Linux kernel does. The @code{sigreturn()} system call is emulated to return
485 from the virtual signal handler.
487 Some signals (such as SIGALRM) directly come from the host. Other
488 signals are synthetized from the virtual CPU exceptions such as SIGFPE
489 when a division by zero is done (see @code{main.c:cpu_loop()}).
491 The blocked signal mask is still handled by the host Linux kernel so
492 that most signal system calls can be redirected directly to the host
493 Linux kernel. Only the @code{sigaction()} and @code{sigreturn()} system
494 calls need to be fully emulated (see @file{signal.c}).
496 @subsection clone() system call and threads
498 The Linux clone() system call is usually used to create a thread. QEMU
499 uses the host clone() system call so that real host threads are created
500 for each emulated thread. One virtual CPU instance is created for each
501 thread.
503 The virtual x86 CPU atomic operations are emulated with a global lock so
504 that their semantic is preserved.
506 Note that currently there are still some locking issues in QEMU. In
507 particular, the translated cache flush is not protected yet against
508 reentrancy.
510 @subsection Self-virtualization
512 QEMU was conceived so that ultimately it can emulate itself. Although
513 it is not very useful, it is an important test to show the power of the
514 emulator.
516 Achieving self-virtualization is not easy because there may be address
517 space conflicts. QEMU solves this problem by being an executable ELF
518 shared object as the ld-linux.so ELF interpreter. That way, it can be
519 relocated at load time.
521 @node Bibliography
522 @section Bibliography
524 @table @asis
526 @item [1]
527 @url{http://citeseer.nj.nec.com/piumarta98optimizing.html}, Optimizing
528 direct threaded code by selective inlining (1998) by Ian Piumarta, Fabio
529 Riccardi.
531 @item [2]
532 @url{http://developer.kde.org/~sewardj/}, Valgrind, an open-source
533 memory debugger for x86-GNU/Linux, by Julian Seward.
535 @item [3]
536 @url{http://bochs.sourceforge.net/}, the Bochs IA-32 Emulator Project,
537 by Kevin Lawton et al.
539 @item [4]
540 @url{http://www.cs.rose-hulman.edu/~donaldlf/em86/index.html}, the EM86
541 x86 emulator on Alpha-Linux.
543 @item [5]
544 @url{http://www.usenix.org/publications/library/proceedings/usenix-nt97/@/full_papers/chernoff/chernoff.pdf},
545 DIGITAL FX!32: Running 32-Bit x86 Applications on Alpha NT, by Anton
546 Chernoff and Ray Hookway.
548 @item [6]
549 @url{http://www.willows.com/}, Windows API library emulation from
550 Willows Software.
552 @item [7]
553 @url{http://user-mode-linux.sourceforge.net/},
554 The User-mode Linux Kernel.
556 @item [8]
557 @url{http://www.plex86.org/},
558 The new Plex86 project.
560 @item [9]
561 @url{http://www.vmware.com/},
562 The VMWare PC virtualizer.
564 @item [10]
565 @url{http://www.microsoft.com/windowsxp/virtualpc/},
566 The VirtualPC PC virtualizer.
568 @item [11]
569 @url{http://www.twoostwo.org/},
570 The TwoOStwo PC virtualizer.
572 @end table
574 @node Regression Tests
575 @chapter Regression Tests
577 In the directory @file{tests/}, various interesting testing programs
578 are available. They are used for regression testing.
580 @menu
581 * test-i386::
582 * linux-test::
583 * qruncom.c::
584 @end menu
586 @node test-i386
587 @section @file{test-i386}
589 This program executes most of the 16 bit and 32 bit x86 instructions and
590 generates a text output. It can be compared with the output obtained with
591 a real CPU or another emulator. The target @code{make test} runs this
592 program and a @code{diff} on the generated output.
594 The Linux system call @code{modify_ldt()} is used to create x86 selectors
595 to test some 16 bit addressing and 32 bit with segmentation cases.
597 The Linux system call @code{vm86()} is used to test vm86 emulation.
599 Various exceptions are raised to test most of the x86 user space
600 exception reporting.
602 @node linux-test
603 @section @file{linux-test}
605 This program tests various Linux system calls. It is used to verify
606 that the system call parameters are correctly converted between target
607 and host CPUs.
609 @node qruncom.c
610 @section @file{qruncom.c}
612 Example of usage of @code{libqemu} to emulate a user mode i386 CPU.
614 @node Index
615 @chapter Index
616 @printindex cp
618 @bye