kqemu-doc.texi

   1 \input texinfo @c -*- texinfo -*-
   2
   3 @iftex
   4 @settitle QEMU Accelerator User Documentation
   5 @titlepage
   6 @sp 7
   7 @center @titlefont{QEMU Accelerator User Documentation}
   8 @sp 3
   9 @end titlepage
  10 @end iftex
  11
  12 @chapter Introduction
  13
  14 QEMU Accelerator (KQEMU) is a driver allowing the QEMU PC emulator to
  15 run much faster when emulating a PC on an x86 host.
  16
  17 KQEMU is supported on x86 or x86_64 Linux 2.4 or 2.6
  18 hosts. Experimental versions are available for FreeBSD and Windows
  19 NT/2000/2003/XP.
  20
  21 @node kqemu_install
  22 @chapter Installation
  23
  24 @section KQEMU Compilation (Linux only)
  25
  26 First ensure that you have a recent version of QEMU (> 0.9.1) with
  27 the KQEMU support enabled (this is the default).
  28
  29 Then decompress the KQEMU sources:
  30 @example
  31 cd /tmp
  32 tar zxvf kqemu-x.y.z.tar.gz
  33 cd kqemu-x.y.z
  34 @end example
  35
  36 Then you configure KQEMU and build it (usually no options are needed):
  37 @example
  38 ./configure
  39 make
  40 @end example
  41
  42 Then type as root user:
  43 @example
  44 make install
  45 @end example
  46 to install KQEMU in @file{/usr/local}.
  47
  48 @section QEMU Accelerator Installation for Linux
  49
  50 If you use x86 Linux, the compilation of the QEMU Accelerator Kernel
  51 Module (KQEMU) is automatically activated provided you have the
  52 necessary kernel headers. If nonetheless the compilation fails, you
  53 can disable its compilation with the @option{--disable-kqemu}
  54 configure option.
  55
  56 Note that KQEMU cannot currently work if the Xen virtualizer is
  57 running on your host.
  58
  59 If you are using a 2.6 host kernel, then all the necessary kernel
  60 headers should be already installed. If you are using a 2.4 kernel,
  61 then you should verify that properly configured kernel sources are
  62 installed and compiled. On a Redhat 9 distribution for example, the
  63 following must be done:
  64 @example
  65 1) Install the kernel-source-xxx package
  66 2) cd /usr/src/linux-xxx
  67 3) make distclean
  68 4) Copy /boot/config-vvv in .config (use uname -r to know your configuration name 'vvv')
  69 5) Edit the Makefile to change the EXTRAVERSION line to match your
  70    current configuration name:
  71    EXTRAVERSION = -custom
  72 to
  73    EXTRAVERSION = -8 # This is an example, it can be -8smp too
  74 5) make menuconfig # Just save the configuration
  75 6) make dep bzImage
  76 @end example
  77
  78 The installation of KQEMU is not fully automatic because it is highly
  79 distribution dependent. When launching
  80 @example
  81 make install
  82 @end example
  83
  84 KQEMU is installed in /lib/modules/@var{kernel_version}/misc.
  85
  86 If you want that KQEMU is installed automatically at boot time, you can add
  87
  88 @example
  89 # Load the KQEMU kernel module
  90 /sbin/modprobe kqemu
  91 @end example
  92
  93 in @file{/etc/rc.d/rc.local}.
  94
  95 By default, kqemu assumes that your distribution uses @code{udev} to
  96 have the device @file{/dev/kqemu} automatically created.  It is
  97 usually necessary to change the device access rights set by udev. With
  98 the Fedora Core >= 4, you can do:
  99 @example
 100 echo 'KERNEL=="kqemu", NAME="%k", MODE="0666"' \
 101      > /etc/udev/rules.d/60-kqemu.rules
 102 @end example
 103
 104 If you don't want to use udev, you can specify a specific major number
 105 for the @file{/dev/kqemu} device:
 106
 107 @example
 108 /sbin/modprobe kqemu major=250
 109 @end example
 110
 111 The device should be created with something like:
 112 @example
 113 mknod /dev/kqemu c 250 0
 114 chmod 666 /dev/kqemu
 115 @end example
 116
 117 @section QEMU Accelerator Installation for Windows
 118
 119 Right click on @file{kqemu.inf} in Explorer and choose Install.
 120
 121 In order to start kqemu, you must do:
 122 @example
 123 net start kqemu
 124 @end example
 125
 126 @chapter Usage
 127
 128 When QEMU is compiled with KQEMU support, the following option is
 129 added to QEMU:
 130
 131 @table @option
 132 @item -no-kqemu
 133 Disable the usage of the QEMU Accelerator module (KQEMU). QEMU will work as
 134 usual but will be slower. This option can be useful to determine if
 135 emulation problems are coming from KQEMU.
 136 @item -kernel-kqemu
 137 Enable full virtualization mode for best performances. This mode only
 138 works with the following guest OSes: Linux 2.4, Linux 2.6, Windows
 139 2000 and Windows XP. WARNING: for Windows 2000/XP, you cannot use it during
 140 installation. See the next chapter for more information about
 141 full virtualization.
 142 @end table
 143
 144 When using KQEMU on a Linux or FreeBSD host, QEMU will create a big
 145 hidden file containing the RAM of the virtual machine. For best
 146 performance, it is important that this file is kept in RAM and not on
 147 the hard disk. QEMU uses the @file{/dev/shm} directory to create this
 148 file because @code{tmpfs} is usually mounted on it (check with the
 149 shell command @code{df}). Otherwise @file{/tmp} is used as
 150 fallback. You can use the @var{QEMU_TMPDIR} shell variable to set a
 151 new directory for the QEMU RAM file.
 152
 153 KQEMU has only been tested with Linux 2.4, Linux 2.6 and Windows
 154 2000/XP as guest OSes. If your guest OS do not work with KQEMU, you
 155 can dynamically disable KQEMU with the @option{-no-kqemu} option.
 156
 157 To see if kqemu is enabled and working correctly, use the QEMU monitor
 158 command:
 159 @example
 160 info kqemu
 161 @end example
 162
 163
 164 @chapter Full virtualization mode
 165
 166 @section Introduction
 167
 168 This mode is activated with the @option{-kernel-kqemu} QEMU option. It
 169 is supported for 32 bit guest OSes. The support for 64 bit guest OSes
 170 is experimental (linux 2.6.18 for x86_64 is known to work). When KQEMU
 171 runs in full virtualization mode, both guest kernel and user code are
 172 executed directly on the host CPU. In normal mode, only the user code
 173 is executed directly and the kernel code is still dynamically
 174 translated by QEMU.
 175
 176 The full virtualization mode cannot work with all OSes because it
 177 makes some assumptions about the x86 instructions that the guest OS
 178 uses. Note that even if some assumptions are made on the guest OS, the
 179 full virtualization mode is secure by design: all the code is executed
 180 in user mode on the host processor which means it cannot break the
 181 host OS.
 182
 183 The requirements for a guest OS to work in full virtualization mode
 184 are very simple and most recent OSes (such as Linux or Windows
 185 2000/XP) fulfill them. Interested OS writers can read the KQEMU
 186 technical specification to learn more.
 187
 188 @section Full virtualization and Linux guests
 189
 190 @itemize
 191 @item Best performances are achieved with Linux 2.4 kernels.
 192 Linux 2.6 works but the performance gains are small.
 193
 194 @item 64 bit guest Linux kernel is experimental.
 195 @end itemize
 196
 197 @section Full virtualization and Windows guests
 198
 199 @itemize
 200
 201 @item Do not use full virtualization when installing Windows.
 202 You can enable it after Windows is installed.
 203
 204 @item Only Windows XP/2000 are known to work in
 205 full virtualization mode.
 206
 207 @end itemize