Documentation/KQemu

Introduction

QEMU Accelerator (KQEMU) is an old driver allowing the QEMU PC emulator to run much faster when emulating a PC on an x86 host. Current versions of qemu (0.11 and up) has no support for kqemu anymore, focusing on kvm instead. The information below is provided for historical reasons only.

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.

Installation

KQEMU Compilation (Linux only)

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

Then decompress the KQEMU sources:

 cd /tmp
 tar zxvf kqemu-x.y.z.tar.gz
 cd kqemu-x.y.z

Then you configure KQEMU and build it (usually no options are needed):

 ./configure
 make

Then type as root user:

 make install

to install KQEMU in `/usr/local'.

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 `--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:

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:
6. make menuconfig # Just save the configuration
7. make dep bzImage

The installation of KQEMU is not fully automatic because it is highly distribution dependent. When launching

 make install

KQEMU is installed in /lib/modules/kernel_version/misc.

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

 # Load the KQEMU kernel module
 /sbin/modprobe kqemu

in `/etc/rc.d/rc.local'.

By default, kqemu assumes that your distribution uses udev to have the device `/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:

 echo 'KERNEL=="kqemu", NAME="%k", MODE="0666"' \
      > /etc/udev/rules.d/60-kqemu.rules

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

 /sbin/modprobe kqemu major=250

The device should be created with something like:

 mknod /dev/kqemu c 250 0
 chmod 666 /dev/kqemu

QEMU Accelerator Installation for Windows

Right click on `kqemu.inf' in Explorer and choose Install.

In order to start kqemu, you must do:

 net start kqemu

Usage

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

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

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 `/dev/shm' directory to create this file because tmpfs is usually mounted on it (check with the shell command df). Otherwise `/tmp' is used as fallback. You can use the 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 `-no-kqemu' option.

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

 info kqemu

Full virtualization mode

Introduction

This mode is activated with the `-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.

Full virtualization and Linux guests

• Best performances are achieved with Linux 2.4 kernels. Linux 2.6 works but the performance gains are small.
• 64 bit guest Linux kernel is experimental.

Full virtualization and Windows guests

• Do not use full virtualization when installing Windows. You can enable it after Windows is installed.
• Only Windows XP/2000 are known to work in full virtualization mode.