git.maemo.org Git - qemu/blob - kqemu/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 currently only supported for an x86 Linux 2.4 or 2.6 host
  18 system, but more host OSes (Windows, *BSD) and processors (x86_64)
  19 will be supported in the future.
  20
  21 @node kqemu_install
  22 @chapter Installation
  23
  24 KQEMU is currently only supported on Linux/x86.
  25
  26 @section QEMU Compilation
  27
  28 First you must decompress the QEMU sources:
  29 @example
  30 cd /tmp
  31 tar zxvf qemu-x.y.z.tar.gz
  32 cd qemu-x.y.z
  33 @end example
  34
  35 Download and install the QEMU Accelerator Module in
  36 qemu-x.y.z/:
  37 @example
  38 tar zxvf /tmp/kqemu-x.y.z.tar.gz
  39 @end example
  40
  41 Then you configure QEMU and build it (usually no options are needed):
  42 @example
  43 ./configure
  44 make
  45 @end example
  46
  47 Then type as root user:
  48 @example
  49 make install
  50 @end example
  51 to install QEMU in @file{/usr/local}.
  52
  53 @section QEMU Accelerator Installation
  54
  55 If you use x86 Linux, the compilation of the QEMU Accelerator Kernel
  56 Module (KQEMU) is automatically activated provided you have the
  57 necessary kernel headers. If nonetheless the compilation fails, you
  58 can disable its compilation with the @option{--disable-kqemu}
  59 configure option.
  60
  61 If you are using a 2.6 host kernel, then all the necessary kernel
  62 headers should be already installed. If you are using a 2.4 kernel,
  63 then you should verify that properly configured kernel sources are
  64 installed and compiled. On a Redhat 9 distribution for example, the
  65 following must be done:
  66 @example
  67 1) Install the kernel-source-xxx package
  68 2) cd /usr/src/linux-xxx
  69 3) make distclean
  70 4) Copy /boot/config-vvv in .config (use uname -r to know your configuration name 'vvv')
  71 5) Edit the Makefile to change the EXTRAVERSION line to match your
  72    current configuration name:
  73    EXTRAVERSION = -custom
  74 to
  75    EXTRAVERSION = -8 # This is an example, it can be -8smp too
  76 5) make menuconfig # Just save the configuration
  77 6) make dep bzImage
  78 @end example
  79
  80 The installation of KQEMU is not fully automatic because it is highly
  81 distribution dependent. When launching
  82 @example
  83 make install
  84 @end example
  85
  86 KQEMU is installed in /lib/modules/@var{kernel_version}/misc. The
  87 device @file{/dev/kqemu} is created with read/write access rights for
  88 everyone. If you fear security issues, you can restrict the access
  89 rights of @file{/dev/kqemu}.
  90
  91 If you want that KQEMU is installed automatically at boot time, you can add
  92
  93 @example
  94 # Load the KQEMU kernel module
  95 /sbin/modprobe kqemu
  96 @end example
  97
  98 in @file{/etc/rc.d/rc.local}.
  99
 100 If your distribution uses udev (like Fedora), the @file{/dev/kqemu} is
 101 not created automatically (yet) at every reboot. You can add the
 102 following in @file{/etc/rc.d/rc.local}:
 103
 104 @example
 105 # Create the KQEMU device
 106 mknod /dev/kqemu c 250 0
 107 chmod 666 /dev/kqemu
 108 @end example
 109
 110 @chapter Usage
 111
 112 When QEMU is compiled with KQEMU support, the following option is
 113 added to QEMU:
 114
 115 @table @option
 116 @item -no-kqemu
 117 Disable the usage of the QEMU Accelerator module (KQEMU). QEMU will work as
 118 usual but will be slower. This option can be useful to determine if
 119 emulation problems are coming from KQEMU.
 120 @end table
 121
 122 When using KQEMU, QEMU will create a big hidden file containing the
 123 RAM of the virtual machine. For best performance, it is important that
 124 this file is kept in RAM and not on the hard disk. QEMU uses the
 125 @file{/dev/shm} directory to create this file because @code{tmpfs} is
 126 usually mounted on it (check with the shell command
 127 @code{df}). Otherwise @file{/tmp} is used as fallback. You can use the
 128 @var{QEMU_TMPDIR} shell variable to set a new directory for the QEMU
 129 RAM file.
 130
 131 KQEMU has only been tested with Linux 2.4, Linux 2.6 and Windows 2000
 132 as guest OSes. If your guest OS do not work with KQEMU, you can
 133 dynamically disable KQEMU with the @option{-no-kqemu} option.
 134