\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. The
device @file{/dev/kqemu} is created with read/write access rights for
everyone. If you fear security issues, you can restrict the access
rights of @file{/dev/kqemu}.

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}.

If the major number 250 is already used by another driver, you can use
the option @code{major=N} to set an alternate major number.

If your distribution uses udev (like Fedora), use the kqemu module
option @code{major=0} to have the device @file{/dev/kqemu} automatically
created:

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

It is usually necessary to change the device access rights set by
udev. Edit @file{/etc/udev/permissions.d/50-udev.permissions} and add:
@example
# kqemu
kqemu:root:root:0666
@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

This mode is activated with the @option{-kernel-kqemu} QEMU
option. 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 contact the author
to get the necessary information to make their OS work in full
virtualization mode in QEMU.