@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}) in
+@file{/tmp} and untar it as root from @file{/}:
@example
su
@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.
+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
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 -k language
+
+Use keyboard layout @var{language} (for example @code{fr} for
+French). This option is only needed where it is not easy to get raw PC
+keycodes (e.g. on Macs or with some X11 servers). You don't need to
+use it on PC/Linux or PC/Windows hosts.
+
+The available layouts are:
+@example
+ar de-ch es fo fr-ca hu ja mk no pt-br sv
+da en-gb et fr fr-ch is lt nl pl ru th
+de en-us fi fr-be hr it lv nl-be pt sl tr
+@end example
+
+The default is @code{en-us}.
+
@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.
+
+@item -full-screen
+Start in full screen.
+
+@item -pidfile file
+Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
+from a script.
+
@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 -smb dir
+When using the user mode network stack, activate a built-in SMB
+server so that Windows OSes can access to the host files in @file{dir}
+transparently.
+
+In the guest Windows OS, the line:
+@example
+10.0.2.4 smbserver
+@end example
+must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
+or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
+
+Then @file{dir} can be accessed in @file{\\smbserver\qemu}.
+
+Note that a SAMBA server must be installed on the host OS in
+@file{/usr/sbin/smbd}. QEMU was tested succesfully with smbd version
+2.2.7a from the Red Hat 9.
+
+@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 -hdachs c,h,s,[,t]
+Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
+@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
+translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
+all thoses parameters. This option is useful for old MS-DOS disk
+images.
+@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)
+@item -loadvm file
+Start right away with a saved state (@code{loadvm} in monitor)
@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
-Toggle mouse and keyboard grab.
-@item Ctrl-Shift-f
+@item Ctrl-Alt-f
Toggle full screen
+
+@item Ctrl-Alt-n
+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
+
+@item Ctrl-Alt
+Toggle mouse and keyboard grab.
@end table
-During emulation, if you are using the serial console, use @key{C-a h}
-to get terminal commands:
+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 Ctrl-a h
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
@node disk_images
@section Disk Images
-@subsection Raw disk images
+Since version 0.6.1, QEMU supports many disk image formats, including
+growable disk images (their size increase as non empty sectors are
+written), compressed and encrypted disk images.
+
+@subsection Quick start for disk image creation
-The disk images can simply be raw images of the hard disk. You can
-create them with the command:
+You can create a disk image with the command:
@example
-dd of=myimage bs=1024 seek=mysize count=0
+qemu-img create myimage.img mysize
@end example
-where @var{myimage} is the image filename and @var{mysize} is its size
-in kilobytes.
+where @var{myimage.img} is the disk image filename and @var{mysize} is its
+size in kilobytes. You can add an @code{M} suffix to give the size in
+megabytes and a @code{G} suffix for gigabytes.
+
+@xref{qemu_img_invocation} for more information.
@subsection Snapshot mode
If you use the option @option{-snapshot}, all disk images are
considered as read only. When sectors in written, they are written in
a temporary file created in @file{/tmp}. You can however force the
-write back to the raw disk images by pressing @key{C-a s}.
-
-NOTE: The snapshot mode only works with raw disk images.
-
-@subsection Copy On Write disk images
-
-QEMU also supports user mode Linux
-(@url{http://user-mode-linux.sourceforge.net/}) Copy On Write (COW)
-disk images. The COW disk images are much smaller than normal images
-as they store only modified sectors. They also permit the use of the
-same disk image template for many users.
-
-To create a COW disk images, use the command:
-
-@example
-qemu-mkcow -f myrawimage.bin mycowimage.cow
-@end example
-
-@file{myrawimage.bin} is a raw image you want to use as original disk
-image. It will never be written to.
-
-@file{mycowimage.cow} is the COW disk image which is created by
-@code{qemu-mkcow}. You can use it directly with the @option{-hdx}
-options. You must not modify the original raw disk image if you use
-COW images, as COW images only store the modified sectors from the raw
-disk image. QEMU stores the original raw disk image name and its
-modified time in the COW disk image so that chances of mistakes are
-reduced.
-
-If the raw disk image is not read-only, by pressing @key{C-a s} you
-can flush the COW disk image back into the raw disk image, as in
-snapshot mode.
-
-COW disk images can also be created without a corresponding raw disk
-image. It is useful to have a big initial virtual disk image without
-using much disk space. Use:
-
-@example
-qemu-mkcow mycowimage.cow 1024
-@end example
+write back to the raw disk images by using the @code{commit} monitor
+command (or @key{C-a s} in the serial console).
-to create a 1 gigabyte empty COW disk image.
+@node qemu_img_invocation
+@subsection @code{qemu-img} Invocation
-NOTES:
-@enumerate
-@item
-COW disk images must be created on file systems supporting
-@emph{holes} such as ext2 or ext3.
-@item
-Since holes are used, the displayed size of the COW disk image is not
-the real one. To know it, use the @code{ls -ls} command.
-@end enumerate
+@include qemu-img.texi
@section Network emulation
@subsection Using the user mode network stack
-This is @emph{experimental} (version 0.5.4). You must configure qemu
-with @code{--enable-slirp}. Then 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:
+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)
+ ----> DNS server (10.0.2.3)
+ |
+ ----> SMB server (10.0.2.4)
@end example
The QEMU VM behaves as if it was behind a firewall which blocks all
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
@subsection Linux
-To have access to SVGA graphic modes under X11, use the @code{vesa}
-X11 driver. For optimal performances, use the same depth as your
-native display.
+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.
-SVGA graphic modes support: QEMU currently supports the Bochs VESA VBE
-extensions. It supports color depths of 8, 15, 16 and 32 bits per
-pixel in 640x480, 800x600 and 1024x768. For optimal performances, use
-the same depth as your native display.
+@subsubsection SVGA graphic modes support
-@itemize
+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.
-@item Windows XP: it should be automatically detected.
+@subsubsection CPU usage reduction
-@item Windows NT4 or 2000: use the driver
-@url{http://www.volny.cz/xnavara/qemuvid_bin.zip} by Filip Navara.
+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.
-@item Windows 95/98/Me: no clean solution yet (but it will change
-soon). You can however use the shareware driver from SciTech. Here are
-the steps recommended by Christophe Bothamy on the Bochs mailing list:
+@subsubsection Windows 2000 disk full problems
-@itemize
-@item install win95 with the VGA driver.
-@item download sdd 7 beta from @url{http://www.majorgeeks.com/download382.html}
-@item download pmhelp.vxd from @url{http://unununium.org/viewcvs/snap/redist/release/pmhelp.vxd}
-@item copy pmhelp.vxd to the win95 system directory
-@item install sdd7
-@end itemize
-@end itemize
+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
-@chapter QEMU PREP PowerPC System emulator invocation
+@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/}.
+@chapter Sparc System emulator invocation
+
+Use the executable @file{qemu-system-sparc} to simulate a JavaStation
+(sun4m architecture). The emulation is far from complete.
+
+QEMU emulates the following sun4m peripherials:
+
+@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
+@end itemize
+
+QEMU uses the Proll, a PROM replacement available at
+@url{http://people.redhat.com/zaitcev/linux/}.
+
@chapter QEMU User space emulator invocation
@section Quick Start
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 / blobdiff