\input texinfo @c -*- texinfo -*-
-@settitle QEMU x86 Emulator Reference Documentation
+@settitle QEMU CPU Emulator Reference Documentation
@titlepage
@sp 7
-@center @titlefont{QEMU x86 Emulator Reference Documentation}
+@center @titlefont{QEMU CPU Emulator Reference Documentation}
@sp 3
@end titlepage
@chapter Introduction
-QEMU is an x86 processor emulator. Its purpose is to run x86 Linux
-processes on non-x86 Linux architectures such as PowerPC or ARM. By
-using dynamic translation it achieves a reasonnable speed while being
-easy to port on new host CPUs. Its main goal is to be able to launch the
-@code{Wine} Windows API emulator (@url{http://www.winehq.org}) on
-non-x86 CPUs.
+@section Features
-QEMU features:
+QEMU is a FAST! processor emulator. Its purpose is to run Linux executables
+compiled for one architecture on another. For example, x86 Linux
+processes can be ran on PowerPC Linux architectures. By using dynamic
+translation it achieves a reasonnable speed while being easy to port on
+new host CPUs. Its main goal is to be able to launch the @code{Wine}
+Windows API emulator (@url{http://www.winehq.org}) or @code{DOSEMU}
+(@url{http://www.dosemu.org}) on non-x86 CPUs.
+
+QEMU generic features:
@itemize
-@item User space only x86 emulator.
+@item User space only emulation.
-@item Currently ported on i386, PowerPC and S390.
+@item Working on x86 and PowerPC hosts. Being tested on ARM, Sparc32, Alpha and S390.
@item Using dynamic translation to native code for reasonnable speed.
-@item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation.
-User space LDT and GDT are emulated. VM86 mode is also supported
-(experimental).
-
@item Generic Linux system call converter, including most ioctls.
@item clone() emulation using native CPU clone() to use Linux scheduler for threads.
-@item Accurate signal handling by remapping host signals to virtual x86 signals.
+@item Accurate signal handling by remapping host signals to target signals.
-@item The virtual x86 CPU is a library (@code{libqemu}) which can be used
-in other projects.
+@item Self-modifying code support.
-@item An extensive Linux x86 CPU test program is included @file{tests/test-i386}.
-It can be used to test other x86 virtual CPUs.
+@item The virtual CPU is a library (@code{libqemu}) which can be used
+in other projects.
@end itemize
-Current QEMU Limitations:
+@section x86 emulation
+
+QEMU x86 target features:
@itemize
-@item Not all x86 exceptions are precise (yet). [Very few programs need that].
+@item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation.
+User space LDT and GDT are emulated. VM86 mode is also supported to run DOSEMU.
+
+@item Precise user space x86 exceptions.
+
+@item Support of host page sizes bigger than 4KB.
+
+@item QEMU can emulate itself on x86.
+
+@item An extensive Linux x86 CPU test program is included @file{tests/test-i386}.
+It can be used to test other x86 virtual CPUs.
+
+@end itemize
-@item Not self virtualizable (yet). [You cannot launch qemu with qemu on the same CPU].
+Current QEMU limitations:
-@item No support for self modifying code (yet). [Very few programs need that, a notable exception is QEMU itself !].
+@itemize
@item No SSE/MMX support (yet).
@item No x86-64 support.
-@item Some Linux syscalls are missing.
+@item IPC syscalls are missing.
@item The x86 segment limits and access rights are not tested at every
memory access (and will never be to have good performances).
@end itemize
+@section ARM emulation
+
+@itemize
+
+@item ARM emulation can currently launch small programs while using the
+generic dynamic code generation architecture of QEMU.
+
+@item No FPU support (yet).
+
+@item No automatic regression testing (yet).
+
+@end itemize
+
@chapter Invocation
@section Quick Start
+If you need to compile QEMU, please read the @file{README} which gives
+the related information.
+
In order to launch a Linux process, QEMU needs the process executable
itself and all the target (x86) dynamic libraries used by it.
@code{-L /} tells that the x86 dynamic linker must be searched with a
@file{/} prefix.
+@item Since QEMU is also a linux process, you can launch qemu with qemu:
+
+@example
+qemu -L / qemu -L / /bin/ls
+@end example
@item On non x86 CPUs, you need first to download at least an x86 glibc
-(@file{qemu-i386-glibc21.tar.gz} on the QEMU web page). Ensure that
+(@file{qemu-XXX-i386-glibc21.tar.gz} on the QEMU web page). Ensure that
@code{LD_LIBRARY_PATH} is not set:
@example
launch x86 executables. It requires the @code{binfmt_misc} module in the
Linux kernel.
+@item The x86 version of QEMU is also included. You can try weird things such as:
+@example
+qemu /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
+@end example
+
@end itemize
-@section Wine launch (Currently only tested when emulating x86 on x86)
+@section Wine launch
@itemize
@end example
@item Download the binary x86 Wine install
-(@file{qemu-i386-wine.tar.gz} on the QEMU web page).
+(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
@item Configure Wine on your account. Look at the provided script
@file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous
usage: qemu [-h] [-d] [-L path] [-s size] program [arguments...]
@end example
-@table @samp
+@table @option
@item -h
Print the help
-@item -d
-Activate log (logfile=/tmp/qemu.log)
@item -L path
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
@item -s size
Set the x86 stack size in bytes (default=524288)
@end table
+Debug options:
+
+@table @option
+@item -d
+Activate log (logfile=/tmp/qemu.log)
+@item -p pagesize
+Act as if the host page size was 'pagesize' bytes
+@end table
+
@chapter QEMU Internals
@section QEMU compared to other emulators
as Valgrind, but it has no support to track uninitialised data as
Valgrind does). Valgrind dynamic translator generates better code than
QEMU (in particular it does register allocation) but it is closely tied
-to an x86 host.
+to an x86 host and target.
EM86 [4] is the closest project to QEMU (and QEMU still uses some of its
code, in particular the ELF file loader). EM86 was limited to an alpha
QEMU is a dynamic translator. When it first encounters a piece of code,
it converts it to the host instruction set. Usually dynamic translators
-are very complicated and highly CPU dependant. QEMU uses some tricks
+are very complicated and highly CPU dependent. QEMU uses some tricks
which make it relatively easily portable and simple while achieving good
performances.
terminated by a jump or by a virtual CPU state change which the
translator cannot deduce statically).
-[Currently, the translated code is not patched if it jumps to another
-translated code].
+@section Direct block chaining
+
+After each translated basic block is executed, QEMU uses the simulated
+Program Counter (PC) and other cpu state informations (such as the CS
+segment base value) to find the next basic block.
+
+In order to accelerate the most common cases where the new simulated PC
+is known, QEMU can patch a basic block so that it jumps directly to the
+next one.
+
+The most portable code uses an indirect jump. An indirect jump makes it
+easier to make the jump target modification atomic. On some
+architectures (such as PowerPC), the @code{JUMP} opcode is directly
+patched so that the block chaining has no overhead.
+
+@section Self-modifying code and translated code invalidation
+
+Self-modifying code is a special challenge in x86 emulation because no
+instruction cache invalidation is signaled by the application when code
+is modified.
+
+When translated code is generated for a basic block, the corresponding
+host page is write protected if it is not already read-only (with the
+system call @code{mprotect()}). Then, if a write access is done to the
+page, Linux raises a SEGV signal. QEMU then invalidates all the
+translated code in the page and enables write accesses to the page.
+
+Correct translated code invalidation is done efficiently by maintaining
+a linked list of every translated block contained in a given page. Other
+linked lists are also maintained to undo direct block chaining.
+
+Althought the overhead of doing @code{mprotect()} calls is important,
+most MSDOS programs can be emulated at reasonnable speed with QEMU and
+DOSEMU.
+
+Note that QEMU also invalidates pages of translated code when it detects
+that memory mappings are modified with @code{mmap()} or @code{munmap()}.
@section Exception support
longjmp() is used when an exception such as division by zero is
-encountered. The host SIGSEGV and SIGBUS signal handlers are used to get
-invalid memory accesses.
+encountered.
+
+The host SIGSEGV and SIGBUS signal handlers are used to get invalid
+memory accesses. The exact CPU state can be retrieved because all the
+x86 registers are stored in fixed host registers. The simulated program
+counter is found by retranslating the corresponding basic block and by
+looking where the host program counter was at the exception point.
-[Currently, the virtual CPU cannot retrieve the exact CPU state in some
-exceptions, although it could except for the @code{EFLAGS} register].
+The virtual CPU cannot retrieve the exact @code{EFLAGS} register because
+in some cases it is not computed because of condition code
+optimisations. It is not a big concern because the emulated code can
+still be restarted in any cases.
@section Linux system call translation
endianness and 32/64 bit issues. The IOCTLs are converted with a generic
type description system (see @file{ioctls.h} and @file{thunk.c}).
+QEMU supports host CPUs which have pages bigger than 4KB. It records all
+the mappings the process does and try to emulated the @code{mmap()}
+system calls in cases where the host @code{mmap()} call would fail
+because of bad page alignment.
+
@section Linux signals
Normal and real-time signals are queued along with their information
The virtual x86 CPU atomic operations are emulated with a global lock so
that their semantic is preserved.
+Note that currently there are still some locking issues in QEMU. In
+particular, the translated cache flush is not protected yet against
+reentrancy.
+
+@section Self-virtualization
+
+QEMU was conceived so that ultimately it can emulate itself. Althought
+it is not very useful, it is an important test to show the power of the
+emulator.
+
+Achieving self-virtualization is not easy because there may be address
+space conflicts. QEMU solves this problem by being an executable ELF
+shared object as the ld-linux.so ELF interpreter. That way, it can be
+relocated at load time.
+
@section Bibliography
@table @asis
@chapter Regression Tests
-In the directory @file{tests/}, various interesting x86 testing programs
+In the directory @file{tests/}, various interesting testing programs
are available. There are used for regression testing.
-@section @file{hello}
+@section @file{hello-i386}
Very simple statically linked x86 program, just to test QEMU during a
port to a new host CPU.
+@section @file{hello-arm}
+
+Very simple statically linked ARM program, just to test QEMU during a
+port to a new host CPU.
+
@section @file{test-i386}
This program executes most of the 16 bit and 32 bit x86 instructions and
The Linux system call @code{modify_ldt()} is used to create x86 selectors
to test some 16 bit addressing and 32 bit with segmentation cases.
-@section @file{testsig}
-
-This program tests various signal cases, including SIGFPE, SIGSEGV and
-SIGILL.
-
-@section @file{testclone}
+The Linux system call @code{vm86()} is used to test vm86 emulation.
-Tests the @code{clone()} system call (basic test).
-
-@section @file{testthread}
-
-Tests the glibc threads (more complicated than @code{clone()} because signals
-are also used).
+Various exceptions are raised to test most of the x86 user space
+exception reporting.
@section @file{sha1}
because it mostly tests the ability of the virtual CPU to optimize the
@code{rol} x86 instruction and the condition code computations.
-@section @file{runcom}
-
-A very simple MSDOS emulator to test the Linux vm86() system call
-emulation. The excellent 54 byte @file{pi_10.com} PI number calculator
-can be launched with it. @file{pi_10.com} was written by Bertram
-Felgenhauer (more information at @url{http://www.boo.net/~jasonp/pipage.html}).
projects / qemu.git / blobdiff