moved CALL_FROM_TBx definitions

[qemu] / qemu-doc.texi

diff --git a/qemu-doc.texi b/qemu-doc.texi
index c262ee7..211b668 100644 (file)
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -22,7 +22,7 @@ QEMU has two operating modes:
 
 @item 
 Full system emulation. In this mode, QEMU emulates a full system (for
 
 @item 
 Full system emulation. In this mode, QEMU emulates a full system (for

-example a PC), including a processor and various peripherials. It can
+example a PC), including a processor and various peripherals. It can

 be used to launch different Operating Systems without rebooting the
 PC or to debug system code.
 
 be used to launch different Operating Systems without rebooting the
 PC or to debug system code.
 

@@ -34,17 +34,19 @@ to ease cross-compilation and cross-debugging.
 
 @end itemize
 
 
 @end itemize
 

-As QEMU requires no host kernel driver to run, it is very safe and
-easy to use.
+QEMU can run without an host kernel driver and yet gives acceptable
+performance. 

 
 For system emulation, the following hardware targets are supported:
 @itemize
 @item PC (x86 processor)
 @item PREP (PowerPC processor)
 @item PowerMac (PowerPC processor, in progress)
 
 For system emulation, the following hardware targets are supported:
 @itemize
 @item PC (x86 processor)
 @item PREP (PowerPC processor)
 @item PowerMac (PowerPC processor, in progress)

+@item Sun4m (32-bit Sparc processor)
+@item Sun4u (64-bit Sparc processor, in progress)

 @end itemize
 
 @end itemize
 

-For user emulation, x86, PowerPC, ARM, and SPARC CPUs are supported.
+For user emulation, x86, PowerPC, ARM, and Sparc32/64 CPUs are supported.

 
 @chapter Installation
 
 
 @chapter Installation
 

@@ -52,14 +54,8 @@ If you want to compile QEMU yourself, see @ref{compilation}.
 
 @section Linux
 
 
 @section Linux
 

-Download the binary distribution (@file{qemu-XXX-i386.tar.gz}) and
-untar it as root in @file{/}:
-
-@example
-su
-cd /
-tar zxvf /tmp/qemu-XXX-i386.tar.gz
-@end example
+If a precompiled package is available for your distribution - you just
+have to install it. Otherwise, see @ref{compilation}.

 
 @section Windows
 
 
 @section Windows
 

@@ -77,33 +73,8 @@ Download the experimental binary installer at
 
 @c man begin DESCRIPTION
 
 
 @c man begin DESCRIPTION
 

-The QEMU System emulator simulates a complete PC.
-
-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:
+The QEMU System emulator simulates the
+following PC peripherals:

 
 @itemize @minus
 @item 
 
 @itemize @minus
 @item 

@@ -189,6 +160,22 @@ command line application. The emulated serial port is redirected on
 the console. Therefore, you can still use QEMU to debug a Linux kernel
 with a serial console.
 
 the console. Therefore, you can still use QEMU to debug a Linux kernel
 with a serial console.
 

+@item -k language
+
+Use keyboard layout @var{language} (for example @code{fr} for
+French). This option is only needed where it is not easy to get raw PC
+keycodes (e.g. on Macs or with some X11 servers). You don't need to
+use it on PC/Linux or PC/Windows hosts.
+
+The available layouts are:
+@example
+ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
+da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
+de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
+@end example
+
+The default is @code{en-us}.
+

 @item -enable-audio
 
 The SB16 emulation is disabled by default as it may give problems with
 @item -enable-audio
 
 The SB16 emulation is disabled by default as it may give problems with

@@ -202,6 +189,10 @@ Windows.
 @item -full-screen
 Start in full screen.
 
 @item -full-screen
 Start in full screen.
 

+@item -pidfile file
+Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
+from a script.
+

 @end table
 
 Network options:
 @end table
 
 Network options:

@@ -213,6 +204,10 @@ Set TUN/TAP network init script [default=/etc/qemu-ifup]. This script
 is launched to configure the host network interface (usually tun0)
 corresponding to the virtual NE2000 card.
 
 is launched to configure the host network interface (usually tun0)
 corresponding to the virtual NE2000 card.
 

+@item -nics n
+
+Simulate @var{n} network cards (the default is 1).
+

 @item -macaddr addr   
 
 Set the mac address of the first interface (the format is
 @item -macaddr addr   
 
 Set the mac address of the first interface (the format is

@@ -343,6 +338,13 @@ Change gdb connection port.
 Do not start CPU at startup (you must type 'c' in the monitor).
 @item -d             
 Output log in /tmp/qemu.log
 Do not start CPU at startup (you must type 'c' in the monitor).
 @item -d             
 Output log in /tmp/qemu.log

+@item -hdachs c,h,s,[,t]
+Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
+@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
+translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
+all thoses parameters. This option is useful for old MS-DOS disk
+images.
+

 @item -isa
 Simulate an ISA-only system (default is PCI system).
 @item -std-vga
 @item -isa
 Simulate an ISA-only system (default is PCI system).
 @item -std-vga

@@ -418,7 +420,6 @@ Fabrice Bellard
 
 @end ignore
 
 
 @end ignore
 

-

 @section QEMU Monitor
 
 The QEMU monitor is used to give complex commands to the QEMU
 @section QEMU Monitor
 
 The QEMU monitor is used to give complex commands to the QEMU

@@ -584,81 +585,34 @@ CPU registers by prefixing them with @emph{$}.
 @node disk_images
 @section Disk Images
 
 @node disk_images
 @section Disk Images
 

-@subsection Raw disk images
+Since version 0.6.1, QEMU supports many disk image formats, including
+growable disk images (their size increase as non empty sectors are
+written), compressed and encrypted disk images.
+
+@subsection Quick start for disk image creation

 
 

-The disk images can simply be raw images of the hard disk. You can
-create them with the command:
+You can create a disk image with the command:

 @example
 @example

-dd of=myimage bs=1024 seek=mysize count=0
+qemu-img create myimage.img mysize

 @end example
 @end example

-where @var{myimage} is the image filename and @var{mysize} is its size
-in kilobytes.
+where @var{myimage.img} is the disk image filename and @var{mysize} is its
+size in kilobytes. You can add an @code{M} suffix to give the size in
+megabytes and a @code{G} suffix for gigabytes.
+
+@xref{qemu_img_invocation} for more information.

 
 @subsection Snapshot mode
 
 If you use the option @option{-snapshot}, all disk images are
 considered as read only. When sectors in written, they are written in
 a temporary file created in @file{/tmp}. You can however force the
 
 @subsection Snapshot mode
 
 If you use the option @option{-snapshot}, all disk images are
 considered as read only. When sectors in written, they are written in
 a temporary file created in @file{/tmp}. You can however force the

-write back to the raw disk images by pressing @key{C-a s}.
-
-NOTE: The snapshot mode only works with raw disk images.
-
-@subsection Copy On Write disk images
-
-QEMU also supports user mode Linux
-(@url{http://user-mode-linux.sourceforge.net/}) Copy On Write (COW)
-disk images. The COW disk images are much smaller than normal images
-as they store only modified sectors. They also permit the use of the
-same disk image template for many users.
-
-To create a COW disk images, use the command:
-
-@example
-qemu-mkcow -f myrawimage.bin mycowimage.cow
-@end example
+write back to the raw disk images by using the @code{commit} monitor
+command (or @key{C-a s} in the serial console).

 
 

-@file{myrawimage.bin} is a raw image you want to use as original disk
-image. It will never be written to.
+@node qemu_img_invocation
+@subsection @code{qemu-img} Invocation

 
 

-@file{mycowimage.cow} is the COW disk image which is created by
-@code{qemu-mkcow}. You can use it directly with the @option{-hdx}
-options. You must not modify the original raw disk image if you use
-COW images, as COW images only store the modified sectors from the raw
-disk image. QEMU stores the original raw disk image name and its
-modified time in the COW disk image so that chances of mistakes are
-reduced.
-
-If the raw disk image is not read-only, by pressing @key{C-a s} you
-can flush the COW disk image back into the raw disk image, as in
-snapshot mode.
-
-COW disk images can also be created without a corresponding raw disk
-image. It is useful to have a big initial virtual disk image without
-using much disk space. Use:
-
-@example
-qemu-mkcow mycowimage.cow 1024
-@end example
-
-to create a 1 gigabyte empty COW disk image.
-
-NOTES: 
-@enumerate
-@item
-COW disk images must be created on file systems supporting
-@emph{holes} such as ext2 or ext3.
-@item 
-Since holes are used, the displayed size of the COW disk image is not
-the real one. To know it, use the @code{ls -ls} command.
-@end enumerate
-
-@subsection Convert VMware disk images to raw disk images
-
-You can use the tool @file{vmdk2raw} to convert VMware disk images to
-raw disk images directly usable by QEMU. The syntax is:
-@example
-vmdk2raw vmware_image output_image
-@end example
+@include qemu-img.texi

 
 @section Network emulation
 
 
 @section Network emulation
 

@@ -846,12 +800,6 @@ A 2.5.74 kernel is also included in the archive. Just
 replace the bzImage in qemu.sh to try it.
 
 @item 
 replace the bzImage in qemu.sh to try it.
 
 @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 

 In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
 qemu. qemu will automatically exit when the Linux shutdown is done.
 
 In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
 qemu. qemu will automatically exit when the Linux shutdown is done.
 

@@ -869,80 +817,6 @@ Lawton for the plex86 Project (@url{www.plex86.org}).
 
 @end enumerate
 
 
 @end enumerate
 

-@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}).
-

 @node gdb_usage
 @section GDB usage
 
 @node gdb_usage
 @section GDB usage
 

@@ -997,6 +871,12 @@ When using a 2.6 guest Linux kernel, you should add the option
 kernels make very strict real time clock checks by default that QEMU
 cannot simulate exactly.
 
 kernels make very strict real time clock checks by default that QEMU
 cannot simulate exactly.
 

+When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
+not activated because QEMU is slower with this patch. The QEMU
+Accelerator Module is also much slower in this case. Earlier Fedora
+Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this
+patch by default. Newer kernels don't have it.
+

 @subsection Windows
 
 If you have a slow host, using Windows 95 is better as it gives the
 @subsection Windows
 
 If you have a slow host, using Windows 95 is better as it gives the

@@ -1055,7 +935,7 @@ problem.
 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
 or PowerMac PowerPC system.
 
 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
 or PowerMac PowerPC system.
 

-QEMU emulates the following PowerMac peripherials:
+QEMU emulates the following PowerMac peripherals:

 
 @itemize @minus
 @item 
 
 @itemize @minus
 @item 

@@ -1072,7 +952,7 @@ Non Volatile RAM
 VIA-CUDA with ADB keyboard and mouse.
 @end itemize
 
 VIA-CUDA with ADB keyboard and mouse.
 @end itemize
 

-QEMU emulates the following PREP peripherials:
+QEMU emulates the following PREP peripherals:

 
 @itemize @minus
 @item 
 
 @itemize @minus
 @item 

@@ -1120,6 +1000,60 @@ Set the initial VGA graphic mode. The default is 800x600x15.
 More information is available at
 @url{http://jocelyn.mayer.free.fr/qemu-ppc/}.
 
 More information is available at
 @url{http://jocelyn.mayer.free.fr/qemu-ppc/}.
 

+@chapter Sparc32 System emulator invocation
+
+Use the executable @file{qemu-system-sparc} to simulate a JavaStation
+(sun4m architecture). The emulation is somewhat complete.
+
+QEMU emulates the following sun4m peripherals:
+
+@itemize @minus
+@item
+IOMMU
+@item
+TCX Frame buffer
+@item 
+Lance (Am7990) Ethernet
+@item
+Non Volatile RAM M48T08
+@item
+Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
+and power/reset logic
+@item
+ESP SCSI controller with hard disk and CD-ROM support
+@item
+Floppy drive
+@end itemize
+
+The number of peripherals is fixed in the architecture.
+
+QEMU uses the Proll, a PROM replacement available at
+@url{http://people.redhat.com/zaitcev/linux/}. The required
+QEMU-specific patches are included with the sources.
+
+A sample Linux 2.6 series kernel and ram disk image are available on
+the QEMU web site. Please note that currently neither Linux 2.4
+series, NetBSD, nor OpenBSD kernels work.
+
+@c man begin OPTIONS
+
+The following options are specific to the Sparc emulation:
+
+@table @option
+
+@item -g WxH
+
+Set the initial TCX graphic mode. The default is 1024x768.
+
+@end table
+
+@c man end 
+
+@chapter Sparc64 System emulator invocation
+
+Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
+The emulator is not usable for anything yet.
+

 @chapter QEMU User space emulator invocation
 
 @section Quick Start
 @chapter QEMU User space emulator invocation
 
 @section Quick Start

@@ -1224,9 +1158,62 @@ Act as if the host page size was 'pagesize' bytes
 @node compilation
 @chapter Compilation from the sources
 
 @node compilation
 @chapter Compilation from the sources
 

-@section Linux/BSD
+@section Linux/Unix
+
+@subsection Compilation
+
+First you must decompress the sources:
+@example
+cd /tmp
+tar zxvf qemu-x.y.z.tar.gz
+cd qemu-x.y.z
+@end example
+
+Then you configure QEMU and build it (usually no options are needed):
+@example
+./configure
+make
+@end example
+
+Then type as root user:
+@example
+make install
+@end example
+to install QEMU in @file{/usr/local}.
+
+@subsection Tested tool versions
+
+In order to compile QEMU succesfully, it is very important that you
+have the right tools. The most important one is gcc. I cannot guaranty
+that QEMU works if you do not use a tested gcc version. Look at
+'configure' and 'Makefile' if you want to make a different gcc
+version work.

 
 

-Read the @file{README} which gives the related information.
+@example
+host      gcc      binutils      glibc    linux       distribution
+----------------------------------------------------------------------
+x86       3.2      2.13.2        2.1.3    2.4.18
+          2.96     2.11.93.0.2   2.2.5    2.4.18      Red Hat 7.3
+          3.2.2    2.13.90.0.18  2.3.2    2.4.20      Red Hat 9
+
+PowerPC   3.3 [4]  2.13.90.0.18  2.3.1    2.4.20briq
+          3.2
+
+Alpha     3.3 [1]  2.14.90.0.4   2.2.5    2.2.20 [2]  Debian 3.0
+
+Sparc32   2.95.4   2.12.90.0.1   2.2.5    2.4.18      Debian 3.0
+
+ARM       2.95.4   2.12.90.0.1   2.2.5    2.4.9 [3]   Debian 3.0
+
+[1] On Alpha, QEMU needs the gcc 'visibility' attribute only available
+    for gcc version >= 3.3.
+[2] Linux >= 2.4.20 is necessary for precise exception support
+    (untested).
+[3] 2.4.9-ac10-rmk2-np1-cerf2
+
+[4] gcc 2.95.x generates invalid code when using too many register
+variables. You must use gcc 3.x on PowerPC.
+@end example

 
 @section Windows
 
 
 @section Windows