qemu-doc.texi

qemu性能直逼VMware的仿真器QEMU 的模擬速度約為實機的 25％；約為 Bochs 的 60 倍。Plex86、User-Mode-Linux、VMware 和 Virtual PC 則比

@end itemize

QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.

@c man begin OPTIONS

The following options are specific to the PowerPC emulation:

@table @option

@item -g WxH[xDEPTH]  

Set the initial VGA graphic mode. The default is 800x600x15.

@end table

@c man end 


More information is available at
@url{http://perso.magic.fr/l_indien/qemu-ppc/}.

@node Sparc32 System emulator invocation
@section Sparc32 System emulator invocation

Use the executable @file{qemu-system-sparc} to simulate a SparcStation 5
(sun4m architecture). The emulation is somewhat complete.

QEMU emulates the following sun4m peripherals:

@itemize @minus
@item
IOMMU
@item
TCX Frame buffer
@item 
Lance (Am7990) Ethernet
@item
Non Volatile RAM M48T08
@item
Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
and power/reset logic
@item
ESP SCSI controller with hard disk and CD-ROM support
@item
Floppy drive
@end itemize

The number of peripherals is fixed in the architecture.

Since version 0.8.2, QEMU uses OpenBIOS
@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
firmware implementation. The goal is to implement a 100% IEEE
1275-1994 (referred to as Open Firmware) compliant firmware.

A sample Linux 2.6 series kernel and ram disk image are available on
the QEMU web site. Please note that currently NetBSD, OpenBSD or
Solaris kernels don't work.

@c man begin OPTIONS

The following options are specific to the Sparc emulation:

@table @option

@item -g WxH

Set the initial TCX graphic mode. The default is 1024x768.

@end table

@c man end 

@node Sparc64 System emulator invocation
@section Sparc64 System emulator invocation

Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
The emulator is not usable for anything yet.

QEMU emulates the following sun4u peripherals:

@itemize @minus
@item
UltraSparc IIi APB PCI Bridge 
@item
PCI VGA compatible card with VESA Bochs Extensions
@item
Non Volatile RAM M48T59
@item
PC-compatible serial ports
@end itemize

@node MIPS System emulator invocation
@section MIPS System emulator invocation

Use the executable @file{qemu-system-mips} to simulate a MIPS machine.
The emulator is able to boot a Linux kernel and to run a Linux Debian
installation from NFS. The following devices are emulated:

@itemize @minus
@item 
MIPS R4K CPU
@item
PC style serial port
@item
NE2000 network card
@end itemize

More information is available in the QEMU mailing-list archive.

@node ARM System emulator invocation
@section ARM System emulator invocation

Use the executable @file{qemu-system-arm} to simulate a ARM
machine. The ARM Integrator/CP board is emulated with the following
devices:

@itemize @minus
@item
ARM926E or ARM1026E CPU
@item
Two PL011 UARTs
@item 
SMC 91c111 Ethernet adapter
@item
PL110 LCD controller
@item
PL050 KMI with PS/2 keyboard and mouse.
@end itemize

The ARM Versatile baseboard is emulated with the following devices:

@itemize @minus
@item
ARM926E CPU
@item
PL190 Vectored Interrupt Controller
@item
Four PL011 UARTs
@item 
SMC 91c111 Ethernet adapter
@item
PL110 LCD controller
@item
PL050 KMI with PS/2 keyboard and mouse.
@item
PCI host bridge.  Note the emulated PCI bridge only provides access to
PCI memory space.  It does not provide access to PCI IO space.
This means some devices (eg. ne2k_pci NIC) are not useable, and others
(eg. rtl8139 NIC) are only useable when the guest drivers use the memory
mapped control registers.
@item
PCI OHCI USB controller.
@item
LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
@end itemize

A Linux 2.6 test image is available on the QEMU web site. More
information is available in the QEMU mailing-list archive.

@node QEMU User space emulator 
@chapter QEMU User space emulator 

@menu
* Supported Operating Systems ::
* Linux User space emulator::
* Mac OS X/Darwin User space emulator ::
@end menu

@node Supported Operating Systems
@section Supported Operating Systems

The following OS are supported in user space emulation:

@itemize @minus
@item
Linux (refered as qemu-linux-user)
@item
Mac OS X/Darwin (refered as qemu-darwin-user)
@end itemize

@node Linux User space emulator
@section Linux User space emulator

@menu
* Quick Start::
* Wine launch::
* Command line options::
* Other binaries::
@end menu

@node Quick Start
@subsection Quick Start

In order to launch a Linux process, QEMU needs the process executable
itself and all the target (x86) dynamic libraries used by it. 

@itemize

@item On x86, you can just try to launch any process by using the native
libraries:

@example 
qemu-i386 -L / /bin/ls
@end example

@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 (NOTE: you can only do that if you compiled QEMU from the sources):

@example 
qemu-i386 -L / qemu-i386 -L / /bin/ls
@end example

@item On non x86 CPUs, you need first to download at least an x86 glibc
(@file{qemu-runtime-i386-XXX-.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-i386 tests/i386/ls
@end example
You can look at @file{qemu-binfmt-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-i386 /usr/local/qemu-i386/bin/qemu-i386 \
          /usr/local/qemu-i386/bin/ls-i386
@end example

@end itemize

@node Wine launch
@subsection 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-i386 /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-i386 /usr/local/qemu-i386/wine/bin/wine \
          /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
@end example

@end itemize

@node Command line options
@subsection Command line options

@example
usage: qemu-i386 [-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

@node Other binaries
@subsection Other binaries

@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
configurations), and arm-uclinux bFLT format binaries.

@command{qemu-m68k} is capable of running semihosted binaries using the BDM
(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
coldfire uClinux bFLT format binaries.

The binary format is detected automatically.

@node Mac OS X/Darwin User space emulator
@section Mac OS X/Darwin User space emulator

@menu
* Mac OS X/Darwin Status::
* Mac OS X/Darwin Quick Start::
* Mac OS X/Darwin Command line options::
@end menu

@node Mac OS X/Darwin Status
@subsection Mac OS X/Darwin Status

@itemize @minus
@item
target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
@item
target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
@item
target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
@item
target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
@end itemize

[1] If you're host commpage can be executed by qemu.

@node Mac OS X/Darwin Quick Start
@subsection Quick Start

In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
itself and all the target dynamic libraries used by it. If you don't have the FAT
libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
CD or compile them by hand.

@itemize

@item On x86, you can just try to launch any process by using the native
libraries:

@example 
qemu-darwin-i386 /bin/ls
@end example

or to run the ppc version of the executable:

@example 
qemu-darwin-ppc /bin/ls
@end example

@item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
are installed:

@example 
qemu-darwin-i386 -L /opt/x86_root/ /bin/ls
@end example

@code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
@file{/opt/x86_root/usr/bin/dyld}.

@end itemize

@node Mac OS X/Darwin Command line options
@subsection Command line options

@example
usage: qemu-darwin-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
@end example

@table @option
@item -h
Print the help
@item -L path   
Set the library root path (default=/)
@item -s size
Set the 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

@node compilation
@chapter Compilation from the sources

@menu
* Linux/Unix::
* Windows::
* Cross compilation for Windows with Linux::
* Mac OS X::
@end menu

@node Linux/Unix
@section Linux/Unix

@subsection Compilation

First you must decompress the sources:
@example
cd /tmp
tar zxvf qemu-x.y.z.tar.gz
cd qemu-x.y.z
@end example

Then you configure QEMU and build it (usually no options are needed):
@example
./configure
make
@end example

Then type as root user:
@example
make install
@end example
to install QEMU in @file{/usr/local}.

@subsection GCC version

In order to compile QEMU successfully, it is very important that you
have the right tools. The most important one is gcc. On most hosts and
in particular on x86 ones, @emph{gcc 4.x is not supported}. If your
Linux distribution includes a gcc 4.x compiler, you can usually
install an older version (it is invoked by @code{gcc32} or
@code{gcc34}). The QEMU configure script automatically probes for
these older versions so that usally you don't have to do anything.

@node Windows
@section Windows

@itemize
@item Install the current versions of MSYS and MinGW from
@url{http://www.mingw.org/}. You can find detailed installation
instructions in the download section and the FAQ.

@item Download 
the MinGW development library of SDL 1.2.x
(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
@url{http://www.libsdl.org}. Unpack it in a temporary place, and
unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
directory. Edit the @file{sdl-config} script so that it gives the
correct SDL directory when invoked.

@item Extract the current version of QEMU.
 
@item Start the MSYS shell (file @file{msys.bat}).

@item Change to the QEMU directory. Launch @file{./configure} and 
@file{make}.  If you have problems using SDL, verify that
@file{sdl-config} can be launched from the MSYS command line.

@item You can install QEMU in @file{Program Files/Qemu} by typing 
@file{make install}. Don't forget to copy @file{SDL.dll} in
@file{Program Files/Qemu}.

@end itemize

@node Cross compilation for Windows with Linux
@section Cross compilation for Windows with Linux

@itemize
@item
Install the MinGW cross compilation tools available at
@url{http://www.mingw.org/}.

@item 
Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
the QEMU configuration script.

@item 
Configure QEMU for Windows cross compilation:
@example
./configure --enable-mingw32
@end example
If necessary, you can change the cross-prefix according to the prefix
choosen for the MinGW tools with --cross-prefix. You can also use
--prefix to set the Win32 install path.

@item You can install QEMU in the installation directory by typing 
@file{make install}. Don't forget to copy @file{SDL.dll} in the
installation directory. 

@end itemize

Note: Currently, Wine does not seem able to launch
QEMU for Win32.

@node Mac OS X
@section Mac OS X

The Mac OS X patches are not fully merged in QEMU, so you should look
at the QEMU mailing list archive to have all the necessary
information.

@node Index
@chapter Index
@printindex cp

@bye