/[qemu]/qemu/qemu-doc.texi
ViewVC logotype

Diff of /qemu/qemu-doc.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.54 by bellard, Sun Dec 19 23:18:01 2004 UTC revision 1.55 by bellard, Thu Feb 10 21:46:47 2005 UTC
# Line 34  to ease cross-compilation and cross-debu Line 34  to ease cross-compilation and cross-debu
34    
35  @end itemize  @end itemize
36    
37  As QEMU requires no host kernel driver to run, it is very safe and  QEMU can run without an host kernel driver and yet gives acceptable
38  easy to use.  performance. On an x86 host, if you want the highest performance for
39    the x86 target, the @emph{QEMU Accelerator Module} (KQEMU) allows QEMU
40    to reach near native performances. KQEMU is currently only supported
41    for an x86 Linux 2.4 or 2.6 host system, but more host OSes will be
42    supported in the future.
43    
44  For system emulation, the following hardware targets are supported:  For system emulation, the following hardware targets are supported:
45  @itemize  @itemize
# Line 52  If you want to compile QEMU yourself, se Line 56  If you want to compile QEMU yourself, se
56    
57  @section Linux  @section Linux
58    
59  Download the binary distribution (@file{qemu-XXX-i386.tar.gz}) in  If a precompiled package is available for your distribution - you just
60  @file{/tmp} and untar it as root from @file{/}:  have to install it. Otherwise, see @ref{compilation}.
   
 @example  
 su  
 cd /  
 tar zxvf /tmp/qemu-XXX-i386.tar.gz  
 @end example  
61    
62  @section Windows  @section Windows
63    
# Line 77  Download the experimental binary install Line 75  Download the experimental binary install
75    
76  @c man begin DESCRIPTION  @c man begin DESCRIPTION
77    
78  The QEMU System emulator simulates a complete PC.  The QEMU System emulator simulates the
79    following PC peripherials:
 In order to meet specific user needs, two versions of QEMU are  
 available:  
   
 @enumerate  
   
 @item  
 @code{qemu-fast} uses the host Memory Management Unit (MMU) to  
 simulate the x86 MMU. It is @emph{fast} but has limitations because  
 the whole 4 GB address space cannot be used and some memory mapped  
 peripherials cannot be emulated accurately yet. Therefore, a specific  
 guest Linux kernel can be used (@xref{linux_compile}) as guest  
 OS.  
   
 Moreover there is no separation between the host and target address  
 spaces, so it offers no security (the target OS can modify the  
 @code{qemu-fast} code by writing at the right addresses).  
   
 @item  
 @code{qemu} uses a software MMU. It is about @emph{two times slower}  
 but gives a more accurate emulation and a complete separation between  
 the host and target address spaces.  
   
 @end enumerate  
   
 QEMU emulates the following PC peripherials:  
80    
81  @itemize @minus  @itemize @minus
82  @item  @item
# Line 369  Force hard disk 0 physical geometry (1 < Line 342  Force hard disk 0 physical geometry (1 <
342  translation mode (@var{t}=none, lba or auto). Usually QEMU can guess  translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
343  all thoses parameters. This option is useful for old MS-DOS disk  all thoses parameters. This option is useful for old MS-DOS disk
344  images.  images.
345    
346    @item -no-kqemu
347    Disable the usage of the QEMU Accelerator module (KQEMU). QEMU will work as
348    usual but will be slower. This option can be useful to determine if
349    emulation problems are coming from KQEMU.
350    
351  @item -isa  @item -isa
352  Simulate an ISA-only system (default is PCI system).  Simulate an ISA-only system (default is PCI system).
353  @item -std-vga  @item -std-vga
# Line 444  Fabrice Bellard Line 423  Fabrice Bellard
423    
424  @end ignore  @end ignore
425    
426    @section QEMU Accelerator Module
427    
428    The QEMU Accelerator Module (KQEMU) is an optional part of QEMU currently only
429    available for Linux 2.4 or 2.6 x86 hosts. It enables QEMU to run x86
430    code much faster. Provided it is installed on your PC (see
431    @ref{kqemu_install}), QEMU will automatically use it.
432    
433    WARNING: as with any alpha stage kernel driver, KQEMU may cause
434    arbitrary data loss on your PC, so you'd better backup your sensitive
435    data before using it.
436    
437    When using KQEMU, QEMU will create a big hidden file containing the
438    RAM of the virtual machine. For best performance, it is important that
439    this file is kept in RAM and not on the hard disk. QEMU uses the
440    @file{/dev/shm} directory to create this file because @code{tmpfs} is
441    usually mounted on it (check with the shell command
442    @code{df}). Otherwise @file{/tmp} is used as fallback. You can use the
443    @var{QEMU_TMPDIR} shell variable to set a new directory for the QEMU
444    RAM file.
445    
446  @section QEMU Monitor  @section QEMU Monitor
447    
# Line 825  A 2.5.74 kernel is also included in the Line 823  A 2.5.74 kernel is also included in the
823  replace the bzImage in qemu.sh to try it.  replace the bzImage in qemu.sh to try it.
824    
825  @item  @item
 qemu-fast creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the  
 default) containing all the simulated PC memory. If possible, try to use  
 a temporary directory using the tmpfs filesystem to avoid too many  
 unnecessary disk accesses.  
   
 @item  
826  In order to exit cleanly from qemu, you can do a @emph{shutdown} inside  In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
827  qemu. qemu will automatically exit when the Linux shutdown is done.  qemu. qemu will automatically exit when the Linux shutdown is done.
828    
# Line 848  Lawton for the plex86 Project (@url{www. Line 840  Lawton for the plex86 Project (@url{www.
840    
841  @end enumerate  @end enumerate
842    
 @node linux_compile  
 @section Linux Kernel Compilation  
   
 You can use any linux kernel with QEMU. However, if you want to use  
 @code{qemu-fast} to get maximum performances, you must use a modified  
 guest kernel. If you are using a 2.6 guest kernel, you can use  
 directly the patch @file{linux-2.6-qemu-fast.patch} made by Rusty  
 Russel available in the QEMU source archive. Otherwise, you can make the  
 following changes @emph{by hand} to the Linux kernel:  
   
 @enumerate  
 @item  
 The kernel must be mapped at 0x90000000 (the default is  
 0xc0000000). You must modify only two lines in the kernel source:  
   
 In @file{include/asm/page.h}, replace  
 @example  
 #define __PAGE_OFFSET           (0xc0000000)  
 @end example  
 by  
 @example  
 #define __PAGE_OFFSET           (0x90000000)  
 @end example  
   
 And in @file{arch/i386/vmlinux.lds}, replace  
 @example  
   . = 0xc0000000 + 0x100000;  
 @end example  
 by  
 @example  
   . = 0x90000000 + 0x100000;  
 @end example  
   
 @item  
 If you want to enable SMP (Symmetric Multi-Processing) support, you  
 must make the following change in @file{include/asm/fixmap.h}. Replace  
 @example  
 #define FIXADDR_TOP     (0xffffX000UL)  
 @end example  
 by  
 @example  
 #define FIXADDR_TOP     (0xa7ffX000UL)  
 @end example  
 (X is 'e' or 'f' depending on the kernel version). Although you can  
 use an SMP kernel with QEMU, it only supports one CPU.  
   
 @item  
 If you are not using a 2.6 kernel as host kernel but if you use a target  
 2.6 kernel, you must also ensure that the 'HZ' define is set to 100  
 (1000 is the default) as QEMU cannot currently emulate timers at  
 frequencies greater than 100 Hz on host Linux systems < 2.6. In  
 @file{include/asm/param.h}, replace:  
   
 @example  
 # define HZ             1000            /* Internal kernel timer frequency */  
 @end example  
 by  
 @example  
 # define HZ             100             /* Internal kernel timer frequency */  
 @end example  
   
 @end enumerate  
   
 The file config-2.x.x gives the configuration of the example kernels.  
   
 Just type  
 @example  
 make bzImage  
 @end example  
   
 As you would do to make a real kernel. Then you can use with QEMU  
 exactly the same kernel as you would boot on your PC (in  
 @file{arch/i386/boot/bzImage}).  
   
843  @node gdb_usage  @node gdb_usage
844  @section GDB usage  @section GDB usage
845    
# Line 976  When using a 2.6 guest Linux kernel, you Line 894  When using a 2.6 guest Linux kernel, you
894  kernels make very strict real time clock checks by default that QEMU  kernels make very strict real time clock checks by default that QEMU
895  cannot simulate exactly.  cannot simulate exactly.
896    
897    When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
898    not activated because QEMU is slower with this patch. The QEMU
899    Accelerator Module is also much slower in this case. Earlier Fedora
900    Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this
901    patch by default. Newer kernels don't have it.
902    
903  @subsection Windows  @subsection Windows
904    
905  If you have a slow host, using Windows 95 is better as it gives the  If you have a slow host, using Windows 95 is better as it gives the
# Line 1226  Act as if the host page size was 'pagesi Line 1150  Act as if the host page size was 'pagesi
1150  @node compilation  @node compilation
1151  @chapter Compilation from the sources  @chapter Compilation from the sources
1152    
1153  @section Linux/BSD  @section Linux/Unix
1154    
1155    @subsection Compilation
1156    
1157    First you must decompress the sources:
1158    @example
1159    cd /tmp
1160    tar zxvf qemu-x.y.z.tar.gz
1161    cd qemu-x.y.z
1162    @end example
1163    
1164    Then you configure QEMU and build it (usually no options are needed):
1165    @example
1166    ./configure
1167    make
1168    @end example
1169    
1170    Then type as root user:
1171    @example
1172    make install
1173    @end example
1174    to install QEMU in @file{/usr/local}.
1175    
1176    @node kqemu_install
1177    @subsection QEMU Accelerator Installation
1178    
1179    If you use x86 Linux, the compilation of the QEMU Accelerator Kernel
1180    Module (KQEMU) is automatically activated provided you have the
1181    necessary kernel headers. If nonetheless the compilation fails, you
1182    can disable its compilation with the @option{--disable-kqemu} option.
1183    
1184    If you are using a 2.6 host kernel, then all the necessary kernel
1185    headers should be already installed. If you are using a 2.4 kernel,
1186    then you should verify that properly configured kernel sources are
1187    installed and compiled. On a Redhat 9 distribution for example, the
1188    following must be done:
1189    @example
1190    1) Install the kernel-source-xxx package
1191    2) cd /usr/src/linux-xxx
1192    3) make distclean
1193    4) Copy /boot/config-vvv in .config (use uname -r to know your configuration name 'vvv')
1194    5) Edit the Makefile to change the EXTRAVERSION line to match your
1195       current configuration name:
1196       EXTRAVERSION = -custom
1197    to
1198       EXTRAVERSION = -8 # This is an example, it can be -8smp too
1199    5) make menuconfig # Just save the configuration
1200    6) make dep bzImage
1201    @end example
1202    
1203    The installation of KQEMU is not fully automatic because it is highly
1204    distribution dependent. When launching
1205    @example
1206    make install
1207    @end example
1208    
1209    KQEMU is installed in /lib/modules/@var{kernel_version}/misc. The
1210    device @file{/dev/kqemu} is created with read/write access rights for
1211    everyone. If you fear security issues, you can restrict the access
1212    rights of @file{/dev/kqemu}.
1213    
1214    If you want that KQEMU is installed automatically at boot time, you can add
1215    
1216    @example
1217    # Load the KQEMU kernel module
1218    /sbin/modprobe kqemu
1219    @end example
1220    
1221    in @file{/etc/rc.d/rc.local}.
1222    
1223  Read the @file{README} which gives the related information.  If your distribution uses udev (like Fedora), the @file{/dev/kqemu} is
1224    not created automatically (yet) at every reboot. You can add the
1225    following in @file{/etc/rc.d/rc.local}:
1226    
1227    @example
1228    # Create the KQEMU device
1229    mknod /dev/kqemu c 254 0
1230    chmod 666 /dev/kqemu
1231    @end example
1232    
1233    @subsection Tested tool versions
1234    
1235    In order to compile QEMU succesfully, it is very important that you
1236    have the right tools. The most important one is gcc. I cannot guaranty
1237    that QEMU works if you do not use a tested gcc version. Look at
1238    'configure' and 'Makefile' if you want to make a different gcc
1239    version work.
1240    
1241    @example
1242    host      gcc      binutils      glibc    linux       distribution
1243    ----------------------------------------------------------------------
1244    x86       3.2      2.13.2        2.1.3    2.4.18
1245              2.96     2.11.93.0.2   2.2.5    2.4.18      Red Hat 7.3
1246              3.2.2    2.13.90.0.18  2.3.2    2.4.20      Red Hat 9
1247    
1248    PowerPC   3.3 [4]  2.13.90.0.18  2.3.1    2.4.20briq
1249              3.2
1250    
1251    Alpha     3.3 [1]  2.14.90.0.4   2.2.5    2.2.20 [2]  Debian 3.0
1252    
1253    Sparc32   2.95.4   2.12.90.0.1   2.2.5    2.4.18      Debian 3.0
1254    
1255    ARM       2.95.4   2.12.90.0.1   2.2.5    2.4.9 [3]   Debian 3.0
1256    
1257    [1] On Alpha, QEMU needs the gcc 'visibility' attribute only available
1258        for gcc version >= 3.3.
1259    [2] Linux >= 2.4.20 is necessary for precise exception support
1260        (untested).
1261    [3] 2.4.9-ac10-rmk2-np1-cerf2
1262    
1263    [4] gcc 2.95.x generates invalid code when using too many register
1264    variables. You must use gcc 3.x on PowerPC.
1265    @end example
1266    
1267  @section Windows  @section Windows
1268    

Legend:
Removed from v.1.54  
changed lines
  Added in v.1.55

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26