\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. An obviously interesting x86 only process
-is 'wine' (Windows emulation).
+@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.
-@itemize
+QEMU generic features:
-@item User space only x86 emulator.
+@itemize
-@item Currently ported on i386 and PowerPC.
+@item User space only emulation.
-@item Using dynamic translation for reasonnable speed.
+@item Working on x86 and PowerPC hosts. Being tested on ARM, Sparc32, Alpha and S390.
-@item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation.
-User space LDT and GDT are emulated.
+@item Using dynamic translation to native code for reasonnable speed.
@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 Not self virtualizable (yet). [You cannot launch qemu with qemu on the same CPU].
+@item Support of host page sizes bigger than 4KB.
-@item No support for self modifying code (yet). [Very few programs need that, a notable exception is QEMU itself !].
+@item QEMU can emulate itself on x86.
-@item No VM86 mode (yet), althought the virtual
-CPU has support for most of it. [VM86 support is useful to launch old 16
-bit DOS programs with dosemu or wine].
+@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
+
+Current QEMU limitations:
+
+@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. Currently,
-QEMU is not distributed with the necessary packages so that you can test
-it easily on non x86 CPUs.
+itself and all the target (x86) dynamic libraries used by it.
+
+@itemize
-However, the statically x86 binary 'tests/hello' can be used to do a
-first test:
+@item On x86, you can just try to launch any process by using the native
+libraries:
@example
-qemu tests/hello
+qemu -L / /bin/ls
@end example
-@code{Hello world} should be printed on the terminal.
+@code{-L /} tells that the x86 dynamic linker must be searched with a
+@file{/} prefix.
-If you are testing it on a x86 CPU, then you can test it on any process:
+@item Since QEMU is also a linux process, you can launch qemu with qemu:
@example
-qemu /bin/ls -l
+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-XXX-i386-glibc21.tar.gz} on the QEMU web page). Ensure that
+@code{LD_LIBRARY_PATH} is not set:
+
+@example
+unset LD_LIBRARY_PATH
+@end example
+
+Then you can launch the precompiled @file{ls} x86 executable:
+
+@example
+qemu /usr/local/qemu-i386/bin/ls-i386
+@end example
+You can look at @file{/usr/local/qemu-i386/bin/qemu-conf.sh} so that
+QEMU is automatically launched by the Linux kernel when you try to
+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
+
+@itemize
+
+@item Ensure that you have a working QEMU with the x86 glibc
+distribution (see previous section). In order to verify it, you must be
+able to do:
+
+@example
+qemu /usr/local/qemu-i386/bin/ls-i386
+@end example
+
+@item Download the binary x86 Wine install
+(@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
+@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
+
+@item Then you can try the example @file{putty.exe}:
+
+@example
+qemu /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
+@end example
+
+@end itemize
+
+@section Command line options
+
+@example
+usage: qemu [-h] [-d] [-L path] [-s size] program [arguments...]
@end example
+@table @option
+@item -h
+Print the help
+@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
host and used a proprietary and slow interpreter (the interpreter part
of the FX!32 Digital Win32 code translator [5]).
+TWIN [6] is a Windows API emulator like Wine. It is less accurate than
+Wine but includes a protected mode x86 interpreter to launch x86 Windows
+executables. Such an approach as greater potential because most of the
+Windows API is executed natively but it is far more difficult to develop
+because all the data structures and function parameters exchanged
+between the API and the x86 code must be converted.
+
@section Portable dynamic translation
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.
Good CPU condition codes emulation (@code{EFLAGS} register on x86) is a
critical point to get good performances. QEMU uses lazy condition code
evaluation: instead of computing the condition codes after each x86
-instruction, it store justs one operand (called @code{CC_CRC}), the
+instruction, it just stores one operand (called @code{CC_SRC}), the
result (called @code{CC_DST}) and the type of operation (called
@code{CC_OP}).
the condition codes are not needed by the next instructions, no
condition codes are computed at all.
-@section Translation CPU state optimisations
+@section CPU state optimisations
The x86 CPU has many internal states which change the way it evaluates
instructions. In order to achieve a good speed, the translation phase
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
DIGITAL FX!32: Running 32-Bit x86 Applications on Alpha NT, by Anton
Chernoff and Ray Hookway.
+@item [6]
+@url{http://www.willows.com/}, Windows API library emulation from
+Willows Software.
+
@end table
@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}
-
-Tests the @code{clone()} system call (basic test).
-
-@section @file{testthread}
+The Linux system call @code{vm86()} is used to test vm86 emulation.
-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}
projects / qemu.git / blobdiff