\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename qemu-doc.info
+
+@documentlanguage en
+@documentencoding UTF-8
+
@settitle QEMU Emulator User Documentation
@exampleindent 0
@paragraphindent 0
@c %**end of header
+@ifinfo
+@direntry
+* QEMU: (qemu-doc). The QEMU Emulator User Documentation.
+@end direntry
+@end ifinfo
+
@iftex
@titlepage
@sp 7
* QEMU System emulator for non PC targets::
* QEMU User space emulator::
* compilation:: Compilation from the sources
+* License::
* Index::
@end menu
@end ifnottex
QEMU has two operating modes:
-@itemize @minus
+@itemize
+@cindex operating modes
@item
+@cindex system emulation
Full system emulation. In this mode, QEMU emulates a full system (for
example a PC), including one or several processors and various
peripherals. It can be used to launch different Operating Systems
without rebooting the PC or to debug system code.
@item
+@cindex user mode emulation
User mode emulation. In this mode, QEMU can launch
processes compiled for one CPU on another CPU. It can be used to
launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
For system emulation, the following hardware targets are supported:
@itemize
+@cindex emulated target systems
+@cindex supported target systems
@item PC (x86 or x86_64 processor)
@item ISA PC (old style PC without PCI bus)
@item PREP (PowerPC processor)
@item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).
@end itemize
-For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
+@cindex supported user mode targets
+For user emulation, x86 (32 and 64 bit), PowerPC (32 and 64 bit),
+ARM, MIPS (32 bit only), Sparc (32 and 64 bit),
+Alpha, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
@node Installation
@chapter Installation
@node install_linux
@section Linux
+@cindex installation (Linux)
If a precompiled package is available for your distribution - you just
have to install it. Otherwise, see @ref{compilation}.
@node install_windows
@section Windows
+@cindex installation (Windows)
Download the experimental binary installer at
@url{http://www.free.oszoo.org/@/download.html}.
+TODO (no longer available)
@node install_mac
@section Mac OS X
Download the experimental binary installer at
@url{http://www.free.oszoo.org/@/download.html}.
+TODO (no longer available)
@node QEMU PC System emulator
@chapter QEMU PC System emulator
+@cindex system emulation (PC)
@menu
* pcsys_introduction:: Introduction
@node pcsys_quickstart
@section Quick Start
+@cindex quick start
Download and uncompress the linux image (@file{linux.img}) and type:
During the graphical emulation, you can use the following keys:
@table @key
@item Ctrl-Alt-f
+@kindex Ctrl-Alt-f
Toggle full screen
@item Ctrl-Alt-u
+@kindex Ctrl-Alt-u
Restore the screen's un-scaled dimensions
@item Ctrl-Alt-n
+@kindex Ctrl-Alt-n
Switch to virtual console 'n'. Standard console mappings are:
@table @emph
@item 1
@end table
@item Ctrl-Alt
+@kindex Ctrl-Alt
Toggle mouse and keyboard grab.
@end table
+@kindex Ctrl-Up
+@kindex Ctrl-Down
+@kindex Ctrl-PageUp
+@kindex Ctrl-PageDown
In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
+@kindex Ctrl-a h
During emulation, if you are using the @option{-nographic} option, use
@key{Ctrl-a h} to get terminal commands:
@table @key
@item Ctrl-a h
+@kindex Ctrl-a h
@item Ctrl-a ?
+@kindex Ctrl-a ?
Print this help
@item Ctrl-a x
+@kindex Ctrl-a x
Exit emulator
@item Ctrl-a s
+@kindex Ctrl-a s
Save disk data back to file (if -snapshot)
@item Ctrl-a t
+@kindex Ctrl-a t
Toggle console timestamps
@item Ctrl-a b
+@kindex Ctrl-a b
Send break (magic sysrq in Linux)
@item Ctrl-a c
+@kindex Ctrl-a c
Switch between console and monitor
@item Ctrl-a Ctrl-a
+@kindex Ctrl-a a
Send Ctrl-a
@end table
@c man end
@node pcsys_monitor
@section QEMU Monitor
+@cindex QEMU monitor
The QEMU monitor is used to give complex commands to the QEMU
emulator. You can use it to:
differences are mentioned in the following sections.
@menu
-* QEMU PowerPC System emulator::
+* PowerPC System emulator::
* Sparc32 System emulator::
* Sparc64 System emulator::
* MIPS System emulator::
* ARM System emulator::
* ColdFire System emulator::
+* Cris System emulator::
+* Microblaze System emulator::
+* SH4 System emulator::
@end menu
-@node QEMU PowerPC System emulator
-@section QEMU PowerPC System emulator
+@node PowerPC System emulator
+@section PowerPC System emulator
+@cindex system emulation (PowerPC)
Use the executable @file{qemu-system-ppc} to simulate a complete PREP
or PowerMac PowerPC system.
@node Sparc32 System emulator
@section Sparc32 System emulator
+@cindex system emulation (Sparc32)
Use the executable @file{qemu-system-sparc} to simulate the following
Sun4m architecture machines:
-prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
@end example
-@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic|SPARCbook|SS-2|SS-1000|SS-2000]
+@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook|SS-2|SS-1000|SS-2000]
Set the emulated machine type. Default is SS-5.
@node Sparc64 System emulator
@section Sparc64 System emulator
+@cindex system emulation (Sparc64)
Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
@node MIPS System emulator
@section MIPS System emulator
+@cindex system emulation (MIPS)
Four executables cover simulation of 32 and 64-bit MIPS systems in
both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
@node ARM System emulator
@section ARM System emulator
+@cindex system emulation (ARM)
Use the executable @file{qemu-system-arm} to simulate a ARM
machine. The ARM Integrator/CP board is emulated with the following
PL181 MultiMedia Card Interface with SD card.
@end itemize
-The ARM RealView Emulation/Platform baseboard is emulated with the following
-devices:
+Several variants of the ARM RealView baseboard are emulated,
+including the EB, PB-A8 and PBX-A9. Due to interactions with the
+bootloader, only certain Linux kernel configurations work out
+of the box on these boards.
+
+Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
+enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
+should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
+disabled and expect 1024M RAM.
+
+The following devices are emuilated:
@itemize @minus
@item
-ARM926E, ARM1136, ARM11MPCORE or Cortex-A8 CPU
+ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
@item
ARM AMBA Generic/Distributed Interrupt Controller
@item
@item
MV88W8618 audio controller, WM8750 CODEC and mixer
@item
-128×64 display with brightness control
+128×64 display with brightness control
@item
2 buttons, 2 navigation wheels with button function
@end itemize
@node ColdFire System emulator
@section ColdFire System emulator
+@cindex system emulation (ColdFire)
+@cindex system emulation (M68K)
Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
The emulator is able to boot a uClinux kernel.
@c man begin OPTIONS
-The following options are specific to the ARM emulation:
+The following options are specific to the ColdFire emulation:
@table @option
@end table
+@node Cris System emulator
+@section Cris System emulator
+@cindex system emulation (Cris)
+
+TODO
+
+@node Microblaze System emulator
+@section Microblaze System emulator
+@cindex system emulation (Microblaze)
+
+TODO
+
+@node SH4 System emulator
+@section SH4 System emulator
+@cindex system emulation (SH4)
+
+TODO
+
@node QEMU User space emulator
@chapter QEMU User space emulator
@subsection Command line options
@example
-usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] program [arguments...]
+usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...]
@end example
@table @option
Offset guest address by the specified number of bytes. This is useful when
the address region rewuired by guest applications is reserved on the host.
Ths option is currently only supported on some hosts.
+@item -R size
+Pre-allocate a guest virtual address space of the given size (in bytes).
+"G", "M", and "k" suffixes may be used when specifying the size.
@end table
Debug options:
@node Other binaries
@subsection Other binaries
+@cindex user mode (Alpha)
+@command{qemu-alpha} TODO.
+
+@cindex user mode (ARM)
+@command{qemu-armeb} TODO.
+
+@cindex user mode (ARM)
@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.
+@cindex user mode (ColdFire)
+@cindex user mode (M68K)
@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.
+@cindex user mode (Cris)
+@command{qemu-cris} TODO.
+
+@cindex user mode (i386)
+@command{qemu-i386} TODO.
+@command{qemu-x86_64} TODO.
+
+@cindex user mode (Microblaze)
+@command{qemu-microblaze} TODO.
+
+@cindex user mode (MIPS)
+@command{qemu-mips} TODO.
+@command{qemu-mipsel} TODO.
+
+@cindex user mode (PowerPC)
+@command{qemu-ppc64abi32} TODO.
+@command{qemu-ppc64} TODO.
+@command{qemu-ppc} TODO.
+
+@cindex user mode (SH4)
+@command{qemu-sh4eb} TODO.
+@command{qemu-sh4} TODO.
+
+@cindex user mode (SPARC)
@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
* Windows::
* Cross compilation for Windows with Linux::
* Mac OS X::
+* Make targets::
@end menu
@node Linux/Unix
@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
+@url{http://www.libsdl.org}. Unpack it in a temporary place and
+edit the @file{sdl-config} script so that it gives the
correct SDL directory when invoked.
+@item Install the MinGW version of zlib and make sure
+@file{zlib.h} and @file{libz.dll.a} are in
+MingGW's default header and linker search paths.
+
@item Extract the current version of QEMU.
@item Start the MSYS shell (file @file{msys.bat}).
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
+@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
+edit the @file{sdl-config} script so that it gives the
+correct SDL directory when invoked. Set up the @code{PATH} environment
+variable so that @file{sdl-config} can be launched by
the QEMU configuration script.
+@item Install the MinGW version of zlib and make sure
+@file{zlib.h} and @file{libz.dll.a} are in
+MingGW's default header and linker search paths.
+
@item
Configure QEMU for Windows cross compilation:
@example
-./configure --enable-mingw32
+PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
+@end example
+The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
+MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
+We set the @code{PATH} environment variable to ensure the MingW version of @file{sdl-config} is used and
+use --cross-prefix to specify the name of the cross compiler.
+You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/Qemu}.
+
+Under Fedora Linux, you can run:
+@example
+yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
@end example
-If necessary, you can change the cross-prefix according to the prefix
-chosen for the MinGW tools with --cross-prefix. You can also use
---prefix to set the Win32 install path.
+to get a suitable cross compilation environment.
@item You can install QEMU in the installation directory by typing
-@file{make install}. Don't forget to copy @file{SDL.dll} in the
+@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
installation directory.
@end itemize
-Note: Currently, Wine does not seem able to launch
-QEMU for Win32.
+Wine can be used to launch the resulting qemu.exe compiled for Win32.
@node Mac OS X
@section Mac OS X
at the QEMU mailing list archive to have all the necessary
information.
+@node Make targets
+@section Make targets
+
+@table @code
+
+@item make
+@item make all
+Make everything which is typically needed.
+
+@item install
+TODO
+
+@item install-doc
+TODO
+
+@item make clean
+Remove most files which were built during make.
+
+@item make distclean
+Remove everything which was built during make.
+
+@item make dvi
+@item make html
+@item make info
+@item make pdf
+Create documentation in dvi, html, info or pdf format.
+
+@item make cscope
+TODO
+
+@item make defconfig
+(Re-)create some build configuration files.
+User made changes will be overwritten.
+
+@item tar
+@item tarbin
+TODO
+
+@end table
+
+@node License
+@appendix License
+
+QEMU is a trademark of Fabrice Bellard.
+
+QEMU is released under the GNU General Public License (TODO: add link).
+Parts of QEMU have specific licenses, see file LICENSE.
+
+TODO (refer to file LICENSE, include it, include the GPL?)
+
@node Index
-@chapter Index
+@appendix Index
+@menu
+* Concept Index::
+* Function Index::
+* Keystroke Index::
+* Program Index::
+* Data Type Index::
+* Variable Index::
+@end menu
+
+@node Concept Index
+@section Concept Index
+This is the main index. Should we combine all keywords in one index? TODO
@printindex cp
+@node Function Index
+@section Function Index
+This index could be used for command line options and monitor functions.
+@printindex fn
+
+@node Keystroke Index
+@section Keystroke Index
+
+This is a list of all keystrokes which have a special function
+in system emulation.
+
+@printindex ky
+
+@node Program Index
+@section Program Index
+@printindex pg
+
+@node Data Type Index
+@section Data Type Index
+
+This index could be used for qdev device names and options.
+
+@printindex tp
+
+@node Variable Index
+@section Variable Index
+@printindex vr
+
@bye
projects / qemu.git / blobdiff