/[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.17 by bellard, Sun Jul 13 22:37:44 2003 UTC revision 1.18 by bellard, Wed Oct 1 00:15:32 2003 UTC
# Line 1  Line 1 
1  \input texinfo @c -*- texinfo -*-  \input texinfo @c -*- texinfo -*-
2    
3    @iftex
4  @settitle QEMU CPU Emulator Reference Documentation  @settitle QEMU CPU Emulator Reference Documentation
5  @titlepage  @titlepage
6  @sp 7  @sp 7
7  @center @titlefont{QEMU CPU Emulator Reference Documentation}  @center @titlefont{QEMU CPU Emulator Reference Documentation}
8  @sp 3  @sp 3
9  @end titlepage  @end titlepage
10    @end iftex
11    
12  @chapter Introduction  @chapter Introduction
13    
# Line 16  achieves a reasonnable speed while being Line 18  achieves a reasonnable speed while being
18  CPUs.  CPUs.
19    
20  QEMU has two operating modes:  QEMU has two operating modes:
21  @itemize  
22  @item User mode emulation. In this mode, QEMU can launch Linux processes  @itemize @minus
23    
24    @item
25    User mode emulation. In this mode, QEMU can launch Linux processes
26  compiled for one CPU on another CPU. Linux system calls are converted  compiled for one CPU on another CPU. Linux system calls are converted
27  because of endianness and 32/64 bit mismatches. The Wine Windows API  because of endianness and 32/64 bit mismatches. The Wine Windows API
28  emulator (@url{http://www.winehq.org}) and the DOSEMU DOS emulator  emulator (@url{http://www.winehq.org}) and the DOSEMU DOS emulator
29  (@url{www.dosemu.org}) are the main targets for QEMU.  (@url{www.dosemu.org}) are the main targets for QEMU.
30    
31  @item Full system emulation. In this mode, QEMU emulates a full  @item
32    Full system emulation. In this mode, QEMU emulates a full
33  system, including a processor and various peripherials. Currently, it  system, including a processor and various peripherials. Currently, it
34  is only used to launch an x86 Linux kernel on an x86 Linux system. It  is only used to launch an x86 Linux kernel on an x86 Linux system. It
35  enables easier testing and debugging of system code. It can also be  enables easier testing and debugging of system code. It can also be
# Line 128  generic dynamic code generation architec Line 134  generic dynamic code generation architec
134    
135  @end itemize  @end itemize
136    
137    @section SPARC emulation
138    
139    The SPARC emulation is currently in development.
140    
141  @chapter QEMU User space emulator invocation  @chapter QEMU User space emulator invocation
142    
143  @section Quick Start  @section Quick Start
# Line 144  itself and all the target (x86) dynamic Line 154  itself and all the target (x86) dynamic
154  libraries:  libraries:
155    
156  @example  @example
157  qemu -L / /bin/ls  qemu-i386 -L / /bin/ls
158  @end example  @end example
159    
160  @code{-L /} tells that the x86 dynamic linker must be searched with a  @code{-L /} tells that the x86 dynamic linker must be searched with a
# Line 153  qemu -L / /bin/ls Line 163  qemu -L / /bin/ls
163  @item Since QEMU is also a linux process, you can launch qemu with qemu:  @item Since QEMU is also a linux process, you can launch qemu with qemu:
164    
165  @example  @example
166  qemu -L / qemu -L / /bin/ls  qemu-i386 -L / qemu-i386 -L / /bin/ls
167  @end example  @end example
168    
169  @item On non x86 CPUs, you need first to download at least an x86 glibc  @item On non x86 CPUs, you need first to download at least an x86 glibc
# Line 167  unset LD_LIBRARY_PATH Line 177  unset LD_LIBRARY_PATH
177  Then you can launch the precompiled @file{ls} x86 executable:  Then you can launch the precompiled @file{ls} x86 executable:
178    
179  @example  @example
180  qemu /usr/local/qemu-i386/bin/ls-i386  qemu-i386 /usr/local/qemu-i386/bin/ls-i386
181  @end example  @end example
182  You can look at @file{/usr/local/qemu-i386/bin/qemu-conf.sh} so that  You can look at @file{/usr/local/qemu-i386/bin/qemu-conf.sh} so that
183  QEMU is automatically launched by the Linux kernel when you try to  QEMU is automatically launched by the Linux kernel when you try to
# Line 176  Linux kernel. Line 186  Linux kernel.
186    
187  @item The x86 version of QEMU is also included. You can try weird things such as:  @item The x86 version of QEMU is also included. You can try weird things such as:
188  @example  @example
189  qemu /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386  qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
190  @end example  @end example
191    
192  @end itemize  @end itemize
# Line 190  distribution (see previous section). In Line 200  distribution (see previous section). In
200  able to do:  able to do:
201    
202  @example  @example
203  qemu /usr/local/qemu-i386/bin/ls-i386  qemu-i386 /usr/local/qemu-i386/bin/ls-i386
204  @end example  @end example
205    
206  @item Download the binary x86 Wine install  @item Download the binary x86 Wine install
# Line 203  qemu /usr/local/qemu-i386/bin/ls-i386 Line 213  qemu /usr/local/qemu-i386/bin/ls-i386
213  @item Then you can try the example @file{putty.exe}:  @item Then you can try the example @file{putty.exe}:
214    
215  @example  @example
216  qemu /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe  qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
217  @end example  @end example
218    
219  @end itemize  @end itemize
# Line 211  qemu /usr/local/qemu-i386/wine/bin/wine Line 221  qemu /usr/local/qemu-i386/wine/bin/wine
221  @section Command line options  @section Command line options
222    
223  @example  @example
224  usage: qemu [-h] [-d] [-L path] [-s size] program [arguments...]  usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
225  @end example  @end example
226    
227  @table @option  @table @option
# Line 234  Act as if the host page size was 'pagesi Line 244  Act as if the host page size was 'pagesi
244    
245  @chapter QEMU System emulator invocation  @chapter QEMU System emulator invocation
246    
247    @section Introduction
248    
249    @c man begin DESCRIPTION
250    
251    The QEMU System emulator simulates a complete PC. It can either boot
252    directly a Linux kernel (without any BIOS or boot loader) or boot like a
253    real PC with the included BIOS.
254    
255    In order to meet specific user needs, two versions of QEMU are
256    available:
257    
258    @enumerate
259    
260    @item
261    @code{qemu} uses the host Memory Management Unit (MMU) to simulate
262    the x86 MMU. It is @emph{fast} but has limitations because the whole 4 GB
263    address space cannot be used and some memory mapped peripherials
264    cannot be emulated accurately yet. Therefore, a specific Linux kernel
265    must be used (@xref{linux_compile}).
266    
267    @item
268    @code{qemu-softmmu} uses a software MMU. It is about @emph{two times
269    slower} but gives a more accurate emulation. (XXX: Linux cannot be ran
270    unpatched yet).
271    
272    @end enumerate
273    
274    QEMU emulates the following PC peripherials:
275    
276    @itemize @minus
277    @item
278    VGA (hardware level, including all non standard modes)
279    @item
280    PS/2 mouse and keyboard
281    @item
282    IDE disk interface (port=0x1f0, irq=14)
283    @item
284    NE2000 network adapter (port=0x300, irq=9)
285    @item
286    Serial port (port=0x3f8, irq=4)
287    @item
288    PIC (interrupt controler)
289    @item
290    PIT (timers)
291    @item
292    CMOS memory
293    @end itemize
294    
295    @c man end
296    
297  @section Quick Start  @section Quick Start
298    
299  This section explains how to launch a Linux kernel inside QEMU.  Download the linux image (@file{linux.img}) and type:
300    
301    @example
302    qemu-softmmu linux.img
303    @end example
304    
305    Linux should boot and give you a prompt.
306    
307    @section Direct Linux Boot and Network emulation
308    
309    This section explains how to launch a Linux kernel inside QEMU without
310    having to make a full bootable image. It is very useful for fast Linux
311    kernel testing. The QEMU network configuration is also explained.
312    
313  @enumerate  @enumerate
314  @item  @item
315  Download the archive @file{vl-test-xxx.tar.gz} containing a Linux  Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
316  kernel and a disk image. The archive also contains a precompiled  kernel and a disk image.
 version of @file{vl}, the QEMU System emulator.  
317    
318  @item Optional: If you want network support (for example to launch X11 examples), you  @item Optional: If you want network support (for example to launch X11 examples), you
319  must copy the script @file{vl-ifup} in @file{/etc} and configure  must copy the script @file{qemu-ifup} in @file{/etc} and configure
320  properly @code{sudo} so that the command @code{ifconfig} contained in  properly @code{sudo} so that the command @code{ifconfig} contained in
321  @file{vl-ifup} can be executed as root. You must verify that your host  @file{qemu-ifup} can be executed as root. You must verify that your host
322  kernel supports the TUN/TAP network interfaces: the device  kernel supports the TUN/TAP network interfaces: the device
323  @file{/dev/net/tun} must be present.  @file{/dev/net/tun} must be present.
324    
# Line 256  the host kernel and the emulated kernel. Line 327  the host kernel and the emulated kernel.
327  from the host kernel at IP address 172.20.0.2 and the host kernel is  from the host kernel at IP address 172.20.0.2 and the host kernel is
328  seen from the emulated kernel at IP address 172.20.0.1.  seen from the emulated kernel at IP address 172.20.0.1.
329    
330  @item Launch @code{vl.sh}. You should have the following output:  @item Launch @code{qemu.sh}. You should have the following output:
331    
332  @example  @example
333  > ./vl.sh  > ./qemu.sh
334  connected to host network interface: tun0  connected to host network interface: tun0
335  Uncompressing Linux... Ok, booting the kernel.  Uncompressing Linux... Ok, booting the kernel.
336  Linux version 2.4.20 (fabrice@localhost.localdomain) (gcc version 2.96 20000731 (Red Hat Linux 7.3 2.96-110)) #22 lun jui 7 13:37:41 CEST 2003  Linux version 2.4.20 (fabrice@localhost.localdomain) (gcc version 2.96 20000731 (Red Hat Linux 7.3 2.96-110)) #22 lun jui 7 13:37:41 CEST 2003
# Line 349  a real Virtual Linux system ! Line 420  a real Virtual Linux system !
420  NOTES:  NOTES:
421  @enumerate  @enumerate
422  @item  @item
423  A 2.5.74 kernel is also included in the vl-test archive. Just  A 2.5.74 kernel is also included in the archive. Just
424  replace the bzImage in vl.sh to try it.  replace the bzImage in qemu.sh to try it.
425    
426  @item  @item
427  vl creates a temporary file in @var{$VLTMPDIR} (@file{/tmp} is the  vl creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the
428  default) containing all the simulated PC memory. If possible, try to use  default) containing all the simulated PC memory. If possible, try to use
429  a temporary directory using the tmpfs filesystem to avoid too many  a temporary directory using the tmpfs filesystem to avoid too many
430  unnecessary disk accesses.  unnecessary disk accesses.
# Line 379  Lawton for the plex86 Project (@url{www. Line 450  Lawton for the plex86 Project (@url{www.
450  @section Invocation  @section Invocation
451    
452  @example  @example
453  usage: vl [options] bzImage [kernel parameters...]  @c man begin SYNOPSIS
454    usage: qemu [options] [disk_image]
455    @c man end
456  @end example  @end example
457    
458  @file{bzImage} is a Linux kernel image.  @c man begin OPTIONS
459    @var{disk_image} is a raw hard image image for IDE hard disk 0.
460    
461  General options:  General options:
462  @table @option  @table @option
463  @item -hda file  @item -hda file
464  @item -hdb file  @item -hdb file
465  Use 'file' as hard disk 0 or 1 image (@xref{disk_images}).  Use @var{file} as hard disk 0 or 1 image (@xref{disk_images}).
466    
467  @item -snapshot  @item -snapshot
468    
# Line 405  launched to configure the host network i Line 479  launched to configure the host network i
479  corresponding to the virtual NE2000 card.  corresponding to the virtual NE2000 card.
480    
481  @item -initrd file  @item -initrd file
482  Use 'file' as initial ram disk.  Use @var{file} as initial ram disk.
483    
484    @item -tun-fd fd      
485    Assumes @var{fd} talks to tap/tun and use it. Read
486    @url{http://bellard.org/qemu/tetrinet.html} to have an example of its
487    use.
488    
489    @item -nographic
490    
491    Normally, QEMU uses SDL to display the VGA output. With this option,
492    you can totally disable graphical output so that QEMU is a simple
493    command line application. The emulated serial port is redirected on
494    the console. Therefore, you can still use QEMU to debug a Linux kernel
495    with a serial console.
496    
497    @end table
498    
499    Linux boot specific (does not require a full PC boot with a BIOS):
500    @table @option
501    
502    @item -kernel bzImage
503    Use @var{bzImage} as kernel image.
504    
505    @item -append cmdline
506    Use @var{cmdline} as kernel command line
507    
508    @item -initrd file
509    Use @var{file} as initial ram disk.
510    
511  @end table  @end table
512    
513  Debug options:  Debug options:
514  @table @option  @table @option
515  @item -s  @item -s
516  Wait gdb connection to port 1234.  Wait gdb connection to port 1234 (@xref{gdb_usage}).
517  @item -p port  @item -p port
518  Change gdb connection port.  Change gdb connection port.
519  @item -d              @item -d            
# Line 432  Send break (magic sysrq) Line 534  Send break (magic sysrq)
534  @item C-a C-a  @item C-a C-a
535  Send C-a  Send C-a
536  @end table  @end table
537    @c man end
538    
539    @ignore
540    
541    @setfilename qemu
542    @settitle QEMU System Emulator
543    
544    @c man begin SEEALSO
545    The HTML documentation of QEMU for more precise information and Linux
546    user mode emulator invocation.
547    @c man end
548    
549    @c man begin AUTHOR
550    Fabrice Bellard
551    @c man end
552    
553    @end ignore
554    
555    @end ignore
556  @node disk_images  @node disk_images
557  @section Disk Images  @section Disk Images
558    
# Line 466  same disk image template for many users. Line 586  same disk image template for many users.
586  To create a COW disk images, use the command:  To create a COW disk images, use the command:
587    
588  @example  @example
589  vlmkcow -f myrawimage.bin mycowimage.cow  qemu-mkcow -f myrawimage.bin mycowimage.cow
590  @end example  @end example
591    
592  @file{myrawimage.bin} is a raw image you want to use as original disk  @file{myrawimage.bin} is a raw image you want to use as original disk
593  image. It will never be written to.  image. It will never be written to.
594    
595  @file{mycowimage.cow} is the COW disk image which is created by  @file{mycowimage.cow} is the COW disk image which is created by
596  @code{vlmkcow}. You can use it directly with the @option{-hdx}  @code{qemu-mkcow}. You can use it directly with the @option{-hdx}
597  options. You must not modify the original raw disk image if you use  options. You must not modify the original raw disk image if you use
598  COW images, as COW images only store the modified sectors from the raw  COW images, as COW images only store the modified sectors from the raw
599  disk image. QEMU stores the original raw disk image name and its  disk image. QEMU stores the original raw disk image name and its
# Line 489  image. It is useful to have a big initia Line 609  image. It is useful to have a big initia
609  using much disk space. Use:  using much disk space. Use:
610    
611  @example  @example
612  vlmkcow mycowimage.cow 1024  qemu-mkcow mycowimage.cow 1024
613  @end example  @end example
614    
615  to create a 1 gigabyte empty COW disk image.  to create a 1 gigabyte empty COW disk image.
# Line 504  Since holes are used, the displayed size Line 624  Since holes are used, the displayed size
624  the real one. To know it, use the @code{ls -ls} command.  the real one. To know it, use the @code{ls -ls} command.
625  @end enumerate  @end enumerate
626    
627    @node linux_compile
628  @section Linux Kernel Compilation  @section Linux Kernel Compilation
629    
630  You should be able to use any kernel with QEMU provided you make the  You should be able to use any kernel with QEMU provided you make the
# Line 573  As you would do to make a real kernel. T Line 694  As you would do to make a real kernel. T
694  exactly the same kernel as you would boot on your PC (in  exactly the same kernel as you would boot on your PC (in
695  @file{arch/i386/boot/bzImage}).  @file{arch/i386/boot/bzImage}).
696    
697  @section PC Emulation  @node gdb_usage
   
 QEMU emulates the following PC peripherials:  
   
 @itemize  
 @item  
 PIC (interrupt controler)  
 @item  
 PIT (timers)  
 @item  
 CMOS memory  
 @item  
 Dumb VGA (to print the @code{Uncompressing Linux} message)  
 @item  
 Serial port (port=0x3f8, irq=4)  
 @item  
 NE2000 network adapter (port=0x300, irq=9)  
 @item  
 IDE disk interface (port=0x1f0, irq=14)  
 @end itemize  
   
698  @section GDB usage  @section GDB usage
699    
700  QEMU has a primitive support to work with gdb, so that you can do  QEMU has a primitive support to work with gdb, so that you can do
701  'Ctrl-C' while the kernel is running and inspect its state.  'Ctrl-C' while the virtual machine is running and inspect its state.
702    
703  In order to use gdb, launch vl with the '-s' option. It will wait for a  In order to use gdb, launch vl with the '-s' option. It will wait for a
704  gdb connection:  gdb connection:
# Line 624  Then you can use gdb normally. For examp Line 725  Then you can use gdb normally. For examp
725    
726  WARNING: breakpoints and single stepping are not yet supported.  WARNING: breakpoints and single stepping are not yet supported.
727    
728    Here are some useful tips in order to use gdb on system code:
729    
730    @enumerate
731    @item
732    Use @code{info reg} to display all the CPU registers.
733    @item
734    Use @code{x/10i $eip} to display the code at the PC position.
735    @item
736    Use @code{set architecture i8086} to dump 16 bit code. Then use
737    @code{x/10i $cs*16+*eip} to dump the code at the PC position.
738    @end enumerate
739    
740  @chapter QEMU Internals  @chapter QEMU Internals
741    
742  @section QEMU compared to other emulators  @section QEMU compared to other emulators

Legend:
Removed from v.1.17  
changed lines
  Added in v.1.18

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