\input texinfo @c -*- texinfo -*-

@iftex
@settitle QEMU Accelerator User Documentation
@titlepage
@sp 7
@center @titlefont{QEMU Accelerator User Documentation}
@sp 3
@end titlepage
@end iftex

@chapter Introduction

QEMU Accelerator (KQEMU) is a driver allowing the QEMU PC emulator to
run much faster when emulating a PC on an x86 host. 

KQEMU is supported on x86 or x86_64 Linux 2.4 or 2.6
hosts. Experimental versions are available for FreeBSD and Windows
NT/2000/2003/XP. 

@node kqemu_install
@chapter Installation

@section KQEMU Compilation (Linux only)

First ensure that you have a recent version of QEMU (>= 0.8.1) with
the KQEMU support enabled (this is the default).

Then decompress the KQEMU sources:
@example
cd /tmp
tar zxvf kqemu-x.y.z.tar.gz
cd kqemu-x.y.z
@end example

Then you configure KQEMU 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 KQEMU in @file{/usr/local}.

@section QEMU Accelerator Installation for Linux

If you use x86 Linux, the compilation of the QEMU Accelerator Kernel
Module (KQEMU) is automatically activated provided you have the
necessary kernel headers. If nonetheless the compilation fails, you
can disable its compilation with the @option{--disable-kqemu}
configure option. 

Note that KQEMU cannot currently work if the Xen virtualizer is
running on your host.

If you are using a 2.6 host kernel, then all the necessary kernel
headers should be already installed. If you are using a 2.4 kernel,
then you should verify that properly configured kernel sources are
installed and compiled. On a Redhat 9 distribution for example, the
following must be done:
@example
1) Install the kernel-source-xxx package
2) cd /usr/src/linux-xxx
3) make distclean
4) Copy /boot/config-vvv in .config (use uname -r to know your configuration name 'vvv')
5) Edit the Makefile to change the EXTRAVERSION line to match your
   current configuration name:
   EXTRAVERSION = -custom
to 
   EXTRAVERSION = -8 # This is an example, it can be -8smp too
5) make menuconfig # Just save the configuration
6) make dep bzImage
@end example

The installation of KQEMU is not fully automatic because it is highly
distribution dependent. When launching 
@example
make install
@end example

KQEMU is installed in /lib/modules/@var{kernel_version}/misc. 

If you want that KQEMU is installed automatically at boot time, you can add

@example
# Load the KQEMU kernel module
/sbin/modprobe kqemu
@end example

in @file{/etc/rc.d/rc.local}.

By default, kqemu assumes that your distribution uses @code{udev} to
have the device @file{/dev/kqemu} automatically created.  It is
usually necessary to change the device access rights set by udev. With
the Fedora Core >= 4, you can do:
@example
echo 'KERNEL=="kqemu", NAME="%k", MODE="0666"' \
     > /etc/udev/rules.d/60-kqemu.rules
@end example

If you don't want to use udev, you can specify a specific major number
for the @file{/dev/kqemu} device:

@example
/sbin/modprobe kqemu major=250
@end example

The device should be created with something like:
@example
mknod /dev/kqemu c 250 0
chmod 666 /dev/kqemu
@end example

@section QEMU Accelerator Installation for Windows

Right click on @file{kqemu.inf} in Explorer and choose Install.

In order to start kqemu, you must do:
@example
net start kqemu
@end example

@chapter Usage

When QEMU is compiled with KQEMU support, the following option is
added to QEMU:

@table @option
@item -no-kqemu
Disable the usage of the QEMU Accelerator module (KQEMU). QEMU will work as
usual but will be slower. This option can be useful to determine if
emulation problems are coming from KQEMU.
@item -kernel-kqemu
Enable full virtualization mode for best performances. This mode only
works with the following guest OSes: Linux 2.4, Linux 2.6, Windows
2000 and Windows XP. WARNING: for Windows 2000/XP, you cannot use it during
installation. See the next chapter for more information about
full virtualization.
@end table

When using KQEMU on a Linux or FreeBSD host, QEMU will create a big
hidden file containing the RAM of the virtual machine. For best
performance, it is important that this file is kept in RAM and not on
the hard disk. QEMU uses the @file{/dev/shm} directory to create this
file because @code{tmpfs} is usually mounted on it (check with the
shell command @code{df}). Otherwise @file{/tmp} is used as
fallback. You can use the @var{QEMU_TMPDIR} shell variable to set a
new directory for the QEMU RAM file.

KQEMU has only been tested with Linux 2.4, Linux 2.6 and Windows
2000/XP as guest OSes. If your guest OS do not work with KQEMU, you
can dynamically disable KQEMU with the @option{-no-kqemu} option.

If you use kqemu on an x86_64 host, you must use
@file{qemu-system-x86_64} instead of @file{qemu}.

To see if kqemu is enabled and working correctly, use the QEMU monitor
command:
@example
info kqemu
@end example


@chapter Full virtualization mode

@section Introduction

This mode is activated with the @option{-kernel-kqemu} QEMU option. It
is supported for 32 bit guest OSes. The support for 64 bit guest OSes
is experimental (linux 2.6.18 for x86_64 is known to work). When KQEMU
runs in full virtualization mode, both guest kernel and user code are
executed directly on the host CPU. In normal mode, only the user code
is executed directly and the kernel code is still dynamically
translated by QEMU.

The full virtualization mode cannot work with all OSes because it
makes some assumptions about the x86 instructions that the guest OS
uses. Note that even if some assumptions are made on the guest OS, the
full virtualization mode is secure by design: all the code is executed
in user mode on the host processor which means it cannot break the
host OS.

The requirements for a guest OS to work in full virtualization mode
are very simple and most recent OSes (such as Linux or Windows
2000/XP) fulfill them. Interested OS writers can read the KQEMU
technical specification to learn more.

@section Full virtualization and Linux guests

@itemize
@item Best performances are achieved with Linux 2.4 kernels. 
Linux 2.6 works but the performance gains are small.

@item 64 bit guest Linux kernel is experimental.
@end itemize

@section Full virtualization and Windows guests

@itemize

@item Do not use full virtualization when installing Windows. 
You can enable it after Windows is installed.

@item Only Windows XP/2000 are known to work in 
full virtualization mode.

@end itemize


