@itemize
@item PC (x86 processor)
@item PREP (PowerPC processor)
+@item PowerMac (PowerPC processor, in progress)
@end itemize
For user emulation, x86, PowerPC, ARM, and SPARC CPUs are supported.
@chapter Installation
+If you want to compile QEMU yourself, see @ref{compilation}.
+
@section Linux
-If you want to compile QEMU, please read the @file{README} which gives
-the related information. Otherwise just download the binary
-distribution (@file{qemu-XXX-i386.tar.gz}) and untar it as root in
-@file{/}:
+Download the binary distribution (@file{qemu-XXX-i386.tar.gz}) and
+untar it as root in @file{/}:
@example
su
@end example
@section Windows
-w
-@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
-
-@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.
+Download the experimental binary installer at
+@url{http://www.freeoszoo.org/download.php}.
@section Mac OS X
-Mac OS X is currently not supported.
+Download the experimental binary installer at
+@url{http://www.freeoszoo.org/download.php}.
@chapter QEMU PC System emulator invocation
@enumerate
@item
-@code{qemu-fast} uses the host Memory Management Unit (MMU) to simulate
-the x86 MMU. It is @emph{fast} but has limitations because the whole 4 GB
-address space cannot be used and some memory mapped peripherials
-cannot be emulated accurately yet. Therefore, a specific Linux kernel
-must be used (@xref{linux_compile}).
+@code{qemu-fast} uses the host Memory Management Unit (MMU) to
+simulate the x86 MMU. It is @emph{fast} but has limitations because
+the whole 4 GB address space cannot be used and some memory mapped
+peripherials cannot be emulated accurately yet. Therefore, a specific
+guest Linux kernel can be used (@xref{linux_compile}) as guest
+OS.
+
+Moreover there is no separation between the host and target address
+spaces, so it offers no security (the target OS can modify the
+@code{qemu-fast} code by writing at the right addresses).
@item
-@code{qemu} uses a software MMU. It is about @emph{two times
-slower} but gives a more accurate emulation.
+@code{qemu} uses a software MMU. It is about @emph{two times slower}
+but gives a more accurate emulation and a complete separation between
+the host and target address spaces.
@end enumerate
QEMU emulates the following PC peripherials:
@itemize @minus
+@item
+i440FX host PCI bridge and PIIX3 PCI to ISA bridge
@item
-VGA (hardware level, including all non standard modes)
+Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
+extensions (hardware level, including all non standard modes).
@item
PS/2 mouse and keyboard
@item
-2 IDE interfaces with hard disk and CD-ROM support
+2 PCI IDE interfaces with hard disk and CD-ROM support
@item
Floppy disk
@item
-up to 6 NE2000 network adapters
+NE2000 PCI network adapters
+@item
+Serial ports
@item
-Serial port
-@item
Soundblaster 16 card
@end itemize
+QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
+VGA BIOS.
+
@c man end
@section Quick Start
@table @option
@item -fda file
@item -fdb file
-Use @var{file} as floppy disk 0/1 image (@xref{disk_images}).
+Use @var{file} as floppy disk 0/1 image (@xref{disk_images}). You can
+use the host floppy by using @file{/dev/fd0} as filename.
@item -hda file
@item -hdb file
@item -cdrom file
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
-@option{-cdrom} at the same time).
+@option{-cdrom} at the same time). You can use the host CD-ROM by
+using @file{/dev/cdrom} as filename.
@item -boot [a|c|d]
Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
the write back by pressing @key{C-a s} (@xref{disk_images}).
@item -m megs
-Set virtual RAM size to @var{megs} megabytes.
-
-@item -initrd file
-Use @var{file} as initial ram disk.
+Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
@item -nographic
the console. Therefore, you can still use QEMU to debug a Linux kernel
with a serial console.
+@item -enable-audio
+
+The SB16 emulation is disabled by default as it may give problems with
+Windows. You can enable it manually with this option.
+
+@item -localtime
+Set the real time clock to local time (the default is to UTC
+time). This option is needed to have correct date in MS-DOS or
+Windows.
+
@end table
Network options:
example of its use.
@item -user-net
-(Experimental) Use the user mode network stack. This is the default if
-no tun/tap network init script is found.
+Use the user mode network stack. This is the default if no tun/tap
+network init script is found.
+
+@item -tftp prefix
+When using the user mode network stack, activate a built-in TFTP
+server. All filenames beginning with @var{prefix} can be downloaded
+from the host to the guest using a TFTP client. The TFTP client on the
+guest must be configured in binary mode (use the command @code{bin} of
+the Unix TFTP client). The host IP address on the guest is as usual
+10.0.2.2.
+
+@item -redir [tcp|udp]:host-port:[guest-host]:guest-port
+
+When using the user mode network stack, redirect incoming TCP or UDP
+connections to the host port @var{host-port} to the guest
+@var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
+is not specified, its value is 10.0.2.15 (default address given by the
+built-in DHCP server).
+
+For example, to redirect host X11 connection from screen 1 to guest
+screen 0, use the following:
+
+@example
+# on the host
+qemu -redir tcp:6001::6000 [...]
+# this host xterm should open in the guest X11 server
+xterm -display :1
+@end example
+
+To redirect telnet connections from host port 5555 to telnet port on
+the guest, use the following:
+
+@example
+# on the host
+qemu -redir tcp:5555::23 [...]
+telnet localhost 5555
+@end example
+
+Then when you use on the host @code{telnet localhost 5555}, you
+connect to the guest telnet server.
@item -dummy-net
-Use the dummy network stack: no packet will be received on the network
+Use the dummy network stack: no packet will be received by the network
cards.
@end table
@end table
-Debug options:
+Debug/Expert options:
@table @option
+
+@item -serial dev
+Redirect the virtual serial port to host device @var{dev}. Available
+devices are:
+@table @code
+@item vc
+Virtual console
+@item pty
+[Linux only] Pseudo TTY (a new PTY is automatically allocated)
+@item null
+void device
+@item stdio
+[Unix only] standard input/output
+@end table
+The default device is @code{vc} in graphical mode and @code{stdio} in
+non graphical mode.
+
+This option can be used several times to simulate up to 4 serials
+ports.
+
+@item -monitor dev
+Redirect the monitor to host device @var{dev} (same devices as the
+serial port).
+The default device is @code{vc} in graphical mode and @code{stdio} in
+non graphical mode.
+
@item -s
Wait gdb connection to port 1234 (@xref{gdb_usage}).
@item -p port
Do not start CPU at startup (you must type 'c' in the monitor).
@item -d
Output log in /tmp/qemu.log
+@item -isa
+Simulate an ISA-only system (default is PCI system).
+@item -std-vga
+Simulate a standard VGA card with Bochs VBE extensions (default is
+Cirrus Logic GD5446 PCI VGA)
+
+@end table
+
+@c man end
+
+@section Keys
+
+@c man begin OPTIONS
+
+During the graphical emulation, you can use the following keys:
+@table @key
+@item Ctrl-Shift-f
+Toggle full screen
+
+@item Ctrl-Shift-Fn
+Switch to virtual console 'n'. Standard console mappings are:
+@table @emph
+@item 1
+Target system display
+@item 2
+Monitor
+@item 3
+Serial port
@end table
-During emulation, if you are using the serial console, use @key{C-a h}
-to get terminal commands:
+@item Ctrl-Shift
+Toggle mouse and keyboard grab.
+@end table
+
+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.
+
+During emulation, if you are using the @option{-nographic} option, use
+@key{Ctrl-a h} to get terminal commands:
@table @key
-@item C-a h
+@item Ctrl-a h
Print this help
-@item C-a x
+@item Ctrl-a x
Exit emulatior
-@item C-a s
+@item Ctrl-a s
Save disk data back to file (if -snapshot)
-@item C-a b
+@item Ctrl-a b
Send break (magic sysrq in Linux)
-@item C-a c
+@item Ctrl-a c
Switch between console and monitor
-@item C-a C-a
-Send C-a
+@item Ctrl-a Ctrl-a
+Send Ctrl-a
@end table
@c man end
Print expression value. Only the @var{format} part of @var{fmt} is
used.
+@item sendkey keys
+
+Send @var{keys} to the emulator. Use @code{-} to press several keys
+simultaneously. Example:
+@example
+sendkey ctrl-alt-f1
+@end example
+
+This command is useful to send keys that your graphical user interface
+intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
+
+@item system_reset
+
+Reset the system.
+
@end table
@subsection Integer expressions
The disk images can simply be raw images of the hard disk. You can
create them with the command:
@example
-dd if=/dev/zero of=myimage bs=1024 count=mysize
+dd of=myimage bs=1024 seek=mysize count=0
@end example
where @var{myimage} is the image filename and @var{mysize} is its size
in kilobytes.
the real one. To know it, use the @code{ls -ls} command.
@end enumerate
-@section Direct Linux Boot and Network emulation
+@subsection Convert VMware disk images to raw disk images
+
+You can use the tool @file{vmdk2raw} to convert VMware disk images to
+raw disk images directly usable by QEMU. The syntax is:
+@example
+vmdk2raw vmware_image output_image
+@end example
+
+@section Network emulation
+
+QEMU simulates up to 6 networks cards (NE2000 boards). Each card can
+be connected to a specific host network interface.
+
+@subsection Using tun/tap network interface
+
+This is the standard way to emulate network. QEMU adds a virtual
+network device on your host (called @code{tun0}), and you can then
+configure it as if it was a real ethernet card.
+
+As an example, you can download the @file{linux-test-xxx.tar.gz}
+archive and copy the script @file{qemu-ifup} in @file{/etc} and
+configure properly @code{sudo} so that the command @code{ifconfig}
+contained in @file{qemu-ifup} can be executed as root. You must verify
+that your host kernel supports the TUN/TAP network interfaces: the
+device @file{/dev/net/tun} must be present.
+
+See @ref{direct_linux_boot} to have an example of network use with a
+Linux distribution.
+
+@subsection Using the user mode network stack
+
+By using the option @option{-user-net} or if you have no tun/tap init
+script, QEMU uses a completely user mode network stack (you don't need
+root priviledge to use the virtual network). The virtual network
+configuration is the following:
+
+@example
+
+QEMU Virtual Machine <------> Firewall/DHCP server <-----> Internet
+ (10.0.2.x) | (10.0.2.2)
+ |
+ ----> DNS
+ (10.0.2.3)
+@end example
+
+The QEMU VM behaves as if it was behind a firewall which blocks all
+incoming connections. You can use a DHCP client to automatically
+configure the network in the QEMU VM.
+
+In order to check that the user mode network is working, you can ping
+the address 10.0.2.2 and verify that you got an address in the range
+10.0.2.x from the QEMU virtual DHCP server.
+
+Note that @code{ping} is not supported reliably to the internet as it
+would require root priviledges. It means you can only ping the local
+router (10.0.2.2).
+
+When using the built-in TFTP server, the router is also the TFTP
+server.
+
+When using the @option{-redir} option, TCP or UDP connections can be
+redirected from the host to the guest. It allows for example to
+redirect X11, telnet or SSH connections.
+
+@node direct_linux_boot
+@section Direct Linux Boot
This section explains how to launch a Linux kernel inside QEMU without
having to make a full bootable image. It is very useful for fast Linux
@code{x/10i $cs*16+*eip} to dump the code at the PC position.
@end enumerate
-@chapter QEMU PREP PowerPC System emulator invocation
+@section Target OS specific information
+
+@subsection Linux
+
+To have access to SVGA graphic modes under X11, use the @code{vesa} or
+the @code{cirrus} X11 driver. For optimal performances, use 16 bit
+color depth in the guest and the host OS.
+
+When using a 2.6 guest Linux kernel, you should add the option
+@code{clock=pit} on the kernel command line because the 2.6 Linux
+kernels make very strict real time clock checks by default that QEMU
+cannot simulate exactly.
+
+@subsection Windows
+
+If you have a slow host, using Windows 95 is better as it gives the
+best speed. Windows 2000 is also a good choice.
+
+@subsubsection SVGA graphic modes support
+
+QEMU emulates a Cirrus Logic GD5446 Video
+card. All Windows versions starting from Windows 95 should recognize
+and use this graphic card. For optimal performances, use 16 bit color
+depth in the guest and the host OS.
+
+@subsubsection CPU usage reduction
+
+Windows 9x does not correctly use the CPU HLT
+instruction. The result is that it takes host CPU cycles even when
+idle. You can install the utility from
+@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
+problem. Note that no such tool is needed for NT, 2000 or XP.
+
+@subsubsection Windows 2000 disk full problems
+
+Currently (release 0.6.0) QEMU has a bug which gives a @code{disk
+full} error during installation of some releases of Windows 2000. The
+workaround is to stop QEMU as soon as you notice that your disk image
+size is growing too fast (monitor it with @code{ls -ls}). Then
+relaunch QEMU to continue the installation. If you still experience
+the problem, relaunch QEMU again.
+
+Future QEMU releases are likely to correct this bug.
+
+@subsubsection Windows XP security problems
+
+Some releases of Windows XP install correctly but give a security
+error when booting:
+@example
+A problem is preventing Windows from accurately checking the
+license for this computer. Error code: 0x800703e6.
+@end example
+The only known workaround is to boot in Safe mode
+without networking support.
+
+Future QEMU releases are likely to correct this bug.
+
+@subsection MS-DOS and FreeDOS
+
+@subsubsection CPU usage reduction
+
+DOS does not correctly use the CPU HLT instruction. The result is that
+it takes host CPU cycles even when idle. You can install the utility
+from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
+problem.
+
+@chapter QEMU PowerPC System emulator invocation
Use the executable @file{qemu-system-ppc} to simulate a complete PREP
-PowerPC system.
+or PowerMac PowerPC system.
+
+QEMU emulates the following PowerMac peripherials:
+
+@itemize @minus
+@item
+UniNorth PCI Bridge
+@item
+PCI VGA compatible card with VESA Bochs Extensions
+@item
+2 PMAC IDE interfaces with hard disk and CD-ROM support
+@item
+NE2000 PCI adapters
+@item
+Non Volatile RAM
+@item
+VIA-CUDA with ADB keyboard and mouse.
+@end itemize
QEMU emulates the following PREP peripherials:
@itemize @minus
@item
+PCI Bridge
+@item
+PCI VGA compatible card with VESA Bochs Extensions
+@item
2 IDE interfaces with hard disk and CD-ROM support
@item
Floppy disk
@item
-up to 6 NE2000 network adapters
+NE2000 network adapters
@item
Serial port
@item
PREP Non Volatile RAM
+@item
+PC compatible keyboard and mouse.
@end itemize
+QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
+@url{http://site.voila.fr/jmayer/OpenHackWare/index.htm}.
+
You can read the qemu PC system emulation chapter to have more
informations about QEMU usage.
+@c man begin OPTIONS
+
+The following options are specific to the PowerPC emulation:
+
+@table @option
+
+@item -prep
+Simulate a PREP system (default is PowerMAC)
+
+@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://jocelyn.mayer.free.fr/qemu-ppc/}.
Act as if the host page size was 'pagesize' bytes
@end table
+@node compilation
+@chapter Compilation from the sources
+
+@section Linux/BSD
+
+Read the @file{README} which gives the related information.
+
+@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
+
+@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.
+
+@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.
+
projects / qemu.git / blobdiff