\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 has two operating modes:
-@itemize @minus
+@itemize
@item
Full system emulation. In this mode, QEMU emulates a full system (for
@item MIPS Magnum (64-bit MIPS processor)
@item ARM Integrator/CP (ARM)
@item ARM Versatile baseboard (ARM)
-@item ARM RealView Emulation baseboard (ARM)
+@item ARM RealView Emulation/Platform baseboard (ARM)
@item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
by Tibor "TS" Schütz.
+Not that, by default, GUS shares IRQ(7) with parallel ports and so
+qemu must be told to not have parallel ports to have working GUS
+
+@example
+qemu dos.img -soundhw gus -parallel none
+@end example
+
+Alternatively:
+@example
+qemu dos.img -device gus,irq=5
+@end example
+
+Or some other unclaimed IRQ.
+
CS4231A is the chip used in Windows Sound System and GUSMAX products
@c man end
@item Ctrl-Alt-f
Toggle full screen
+@item Ctrl-Alt-u
+Restore the screen's un-scaled dimensions
+
@item Ctrl-Alt-n
Switch to virtual console 'n'. Standard console mappings are:
@table @emph
@table @option
-@item -g WxH[xDEPTH]
+@item -g @var{W}x@var{H}[x@var{DEPTH}]
Set the initial VGA graphic mode. The default is 800x600x15.
-@item -prom-env string
+@item -prom-env @var{string}
Set OpenBIOS variables in NVRAM, for example:
@table @option
-@item -g WxHx[xDEPTH]
+@item -g @var{W}x@var{H}x[x@var{DEPTH}]
Set the initial TCX graphic mode. The default is 1024x768x8, currently
the only other possible mode is 1024x768x24.
-@item -prom-env string
+@item -prom-env @var{string}
Set OpenBIOS variables in NVRAM, for example:
@table @option
-@item -prom-env string
+@item -prom-env @var{string}
Set OpenBIOS variables in NVRAM, for example:
PL181 MultiMedia Card Interface with SD card.
@end itemize
-The ARM RealView Emulation 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(x4) or Cortex-A8 CPU
+ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
@item
ARM AMBA Generic/Distributed Interrupt Controller
@item
Four PL011 UARTs
@item
-SMC 91c111 Ethernet adapter
+SMC 91c111 or SMSC LAN9118 Ethernet adapter
@item
PL110 LCD 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
@subsection Command line options
@example
-usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] program [arguments...]
+usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] program [arguments...]
@end example
@table @option
Set the x86 stack size in bytes (default=524288)
@item -cpu model
Select CPU model (-cpu ? for list and additional feature selection)
+@item -B offset
+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.
@end table
Debug options:
* 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 Index
@chapter Index
@printindex cp