@item
Full system emulation. In this mode, QEMU emulates a full system (for
-example a PC), including a processor and various peripherials. It can
+example a PC), including a processor and various peripherals. It can
be used to launch different Operating Systems without rebooting the
PC or to debug system code.
@end itemize
-As QEMU requires no host kernel driver to run, it is very safe and
-easy to use.
+QEMU can run without an host kernel driver and yet gives acceptable
+performance.
For system emulation, the following hardware targets are supported:
@itemize
@item PC (x86 processor)
@item PREP (PowerPC processor)
@item PowerMac (PowerPC processor, in progress)
+@item Sun4m (32-bit Sparc processor)
+@item Sun4u (64-bit Sparc processor, in progress)
@end itemize
-For user emulation, x86, PowerPC, ARM, and SPARC CPUs are supported.
+For user emulation, x86, PowerPC, ARM, and Sparc32/64 CPUs are supported.
@chapter Installation
@section Linux
-Download the binary distribution (@file{qemu-XXX-i386.tar.gz}) and
-untar it as root in @file{/}:
-
-@example
-su
-cd /
-tar zxvf /tmp/qemu-XXX-i386.tar.gz
-@end example
+If a precompiled package is available for your distribution - you just
+have to install it. Otherwise, see @ref{compilation}.
@section Windows
@c man begin DESCRIPTION
-The QEMU System emulator simulates a complete PC.
-
-In order to meet specific user needs, two versions of QEMU are
-available:
-
-@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
-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 and a complete separation between
-the host and target address spaces.
-
-@end enumerate
-
-QEMU emulates the following PC peripherials:
+The QEMU System emulator simulates the
+following PC peripherals:
@itemize @minus
@item
@item -m megs
Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
-@item -initrd file
-Use @var{file} as initial ram disk.
-
@item -nographic
Normally, QEMU uses SDL to display the VGA output. With this option,
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
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:
is launched to configure the host network interface (usually tun0)
corresponding to the virtual NE2000 card.
+@item -nics n
+
+Simulate @var{n} network cards (the default is 1).
+
@item -macaddr addr
Set the mac address of the first interface (the format is
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 by the network
cards.
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
During the graphical emulation, you can use the following keys:
@table @key
-@item Ctrl-Shift-f
+@item Ctrl-Alt-f
Toggle full screen
-@item Ctrl-Shift-Fn
+@item Ctrl-Alt-n
Switch to virtual console 'n'. Standard console mappings are:
@table @emph
@item 1
Serial port
@end table
-@item Ctrl-Shift
+@item Ctrl-Alt
Toggle mouse and keyboard grab.
@end table
@end ignore
-
@section QEMU Monitor
The QEMU monitor is used to give complex commands to the QEMU
@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.
-The disk images can simply be raw images of the hard disk. You can
-create them with the command:
+@subsection Quick start for disk image creation
+
+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.
+write back to the raw disk images by using the @code{commit} monitor
+command (or @key{C-a s} in the serial console).
-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:
+@node qemu_img_invocation
+@subsection @code{qemu-img} Invocation
-@example
-qemu-mkcow mycowimage.cow 1024
-@end example
-
-to create a 1 gigabyte empty COW disk image.
-
-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
-
-@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
+@include qemu-img.texi
@section Network emulation
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).
-The user mode network is currently only supported on a Unix host.
+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
replace the bzImage in qemu.sh to try it.
@item
-qemu-fast creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the
-default) containing all the simulated PC memory. If possible, try to use
-a temporary directory using the tmpfs filesystem to avoid too many
-unnecessary disk accesses.
-
-@item
In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
qemu. qemu will automatically exit when the Linux shutdown is done.
@end enumerate
-@node linux_compile
-@section Linux Kernel Compilation
-
-You can use any linux kernel with QEMU. However, if you want to use
-@code{qemu-fast} to get maximum performances, you must use a modified
-guest kernel. If you are using a 2.6 guest kernel, you can use
-directly the patch @file{linux-2.6-qemu-fast.patch} made by Rusty
-Russel available in the QEMU source archive. Otherwise, you can make the
-following changes @emph{by hand} to the Linux kernel:
-
-@enumerate
-@item
-The kernel must be mapped at 0x90000000 (the default is
-0xc0000000). You must modify only two lines in the kernel source:
-
-In @file{include/asm/page.h}, replace
-@example
-#define __PAGE_OFFSET (0xc0000000)
-@end example
-by
-@example
-#define __PAGE_OFFSET (0x90000000)
-@end example
-
-And in @file{arch/i386/vmlinux.lds}, replace
-@example
- . = 0xc0000000 + 0x100000;
-@end example
-by
-@example
- . = 0x90000000 + 0x100000;
-@end example
-
-@item
-If you want to enable SMP (Symmetric Multi-Processing) support, you
-must make the following change in @file{include/asm/fixmap.h}. Replace
-@example
-#define FIXADDR_TOP (0xffffX000UL)
-@end example
-by
-@example
-#define FIXADDR_TOP (0xa7ffX000UL)
-@end example
-(X is 'e' or 'f' depending on the kernel version). Although you can
-use an SMP kernel with QEMU, it only supports one CPU.
-
-@item
-If you are not using a 2.6 kernel as host kernel but if you use a target
-2.6 kernel, you must also ensure that the 'HZ' define is set to 100
-(1000 is the default) as QEMU cannot currently emulate timers at
-frequencies greater than 100 Hz on host Linux systems < 2.6. In
-@file{include/asm/param.h}, replace:
-
-@example
-# define HZ 1000 /* Internal kernel timer frequency */
-@end example
-by
-@example
-# define HZ 100 /* Internal kernel timer frequency */
-@end example
-
-@end enumerate
-
-The file config-2.x.x gives the configuration of the example kernels.
-
-Just type
-@example
-make bzImage
-@end example
-
-As you would do to make a real kernel. Then you can use with QEMU
-exactly the same kernel as you would boot on your PC (in
-@file{arch/i386/boot/bzImage}).
-
@node gdb_usage
@section GDB usage
kernels make very strict real time clock checks by default that QEMU
cannot simulate exactly.
+When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
+not activated because QEMU is slower with this patch. The QEMU
+Accelerator Module is also much slower in this case. Earlier Fedora
+Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this
+patch by default. Newer kernels don't have it.
+
@subsection Windows
If you have a slow host, using Windows 95 is better as it gives the
Use the executable @file{qemu-system-ppc} to simulate a complete PREP
or PowerMac PowerPC system.
-QEMU emulates the following PowerMac peripherials:
+QEMU emulates the following PowerMac peripherals:
@itemize @minus
@item
VIA-CUDA with ADB keyboard and mouse.
@end itemize
-QEMU emulates the following PREP peripherials:
+QEMU emulates the following PREP peripherals:
@itemize @minus
@item
More information is available at
@url{http://jocelyn.mayer.free.fr/qemu-ppc/}.
+@chapter Sparc32 System emulator invocation
+
+Use the executable @file{qemu-system-sparc} to simulate a JavaStation
+(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.
+
+QEMU uses the Proll, a PROM replacement available at
+@url{http://people.redhat.com/zaitcev/linux/}. The required
+QEMU-specific patches are included with the sources.
+
+A sample Linux 2.6 series kernel and ram disk image are available on
+the QEMU web site. Please note that currently neither Linux 2.4
+series, NetBSD, nor OpenBSD kernels 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
+
+@chapter Sparc64 System emulator invocation
+
+Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
+The emulator is not usable for anything yet.
+
@chapter QEMU User space emulator invocation
@section Quick Start
@node compilation
@chapter Compilation from the sources
-@section Linux/BSD
+@section Linux/Unix
-Read the @file{README} which gives the related information.
+@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 Tested tool versions
+
+In order to compile QEMU succesfully, it is very important that you
+have the right tools. The most important one is gcc. I cannot guaranty
+that QEMU works if you do not use a tested gcc version. Look at
+'configure' and 'Makefile' if you want to make a different gcc
+version work.
+
+@example
+host gcc binutils glibc linux distribution
+----------------------------------------------------------------------
+x86 3.2 2.13.2 2.1.3 2.4.18
+ 2.96 2.11.93.0.2 2.2.5 2.4.18 Red Hat 7.3
+ 3.2.2 2.13.90.0.18 2.3.2 2.4.20 Red Hat 9
+
+PowerPC 3.3 [4] 2.13.90.0.18 2.3.1 2.4.20briq
+ 3.2
+
+Alpha 3.3 [1] 2.14.90.0.4 2.2.5 2.2.20 [2] Debian 3.0
+
+Sparc32 2.95.4 2.12.90.0.1 2.2.5 2.4.18 Debian 3.0
+
+ARM 2.95.4 2.12.90.0.1 2.2.5 2.4.9 [3] Debian 3.0
+
+[1] On Alpha, QEMU needs the gcc 'visibility' attribute only available
+ for gcc version >= 3.3.
+[2] Linux >= 2.4.20 is necessary for precise exception support
+ (untested).
+[3] 2.4.9-ac10-rmk2-np1-cerf2
+
+[4] gcc 2.95.x generates invalid code when using too many register
+variables. You must use gcc 3.x on PowerPC.
+@end example
@section Windows
projects / qemu / blobdiff