APIC init fix + APIC get_irq fix (Juergen Keil)
[qemu] / qemu-doc.texi
index 8ff329a..4634a22 100644 (file)
@@ -1,7 +1,7 @@
 \input texinfo @c -*- texinfo -*-
 @c %**start of header
 @setfilename qemu-doc.info
-@settitle QEMU CPU Emulator User Documentation
+@settitle QEMU Emulator User Documentation
 @exampleindent 0
 @paragraphindent 0
 @c %**end of header
@@ -9,7 +9,7 @@
 @iftex
 @titlepage
 @sp 7
-@center @titlefont{QEMU CPU Emulator}
+@center @titlefont{QEMU Emulator}
 @sp 1
 @center @titlefont{User Documentation}
 @sp 3
@@ -206,7 +206,7 @@ Select the emulated machine (@code{-M ?} for list)
 @item -fda file
 @item -fdb file
 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
-use the host floppy by using @file{/dev/fd0} as filename.
+use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
 
 @item -hda file
 @item -hdb file
@@ -217,7 +217,7 @@ Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
 @item -cdrom file
 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
 @option{-cdrom} at the same time). You can use the host CD-ROM by
-using @file{/dev/cdrom} as filename.
+using @file{/dev/cdrom} as filename (@pxref{host_drives}).
 
 @item -boot [a|c|d]
 Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
@@ -506,12 +506,16 @@ Redirect the virtual serial port to host character device
 This option can be used several times to simulate up to 4 serials
 ports.
 
+Use @code{-serial none} to disable all serial ports.
+
 Available character devices are:
 @table @code
 @item vc
 Virtual console
 @item pty
 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
+@item none
+No device is allocated.
 @item null
 void device
 @item /dev/XXX
@@ -559,8 +563,8 @@ localhost 5555
 The TCP Net Console has two modes of operation.  It can send the serial
 I/O to a location or wait for a connection from a location.  By default
 the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
-the @var{,server} option QEMU will wait for a client socket application
-to connect to the port before continuing, unless the @code{,nowait}
+the @var{server} option QEMU will wait for a client socket application
+to connect to the port before continuing, unless the @code{nowait}
 option was specified. If @var{host} is omitted, 0.0.0.0 is assumed. Only
 one TCP connection at a time is accepted. You can use @code{telnet} to
 connect to the corresponding character device.
@@ -593,6 +597,8 @@ parallel port.
 This option can be used several times to simulate up to 3 parallel
 ports.
 
+Use @code{-parallel none} to disable all parallel ports.
+
 @item -monitor dev
 Redirect the monitor to host device @var{dev} (same devices as the
 serial port).
@@ -614,6 +620,9 @@ 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 -L path
+Set the directory for the BIOS, VGA BIOS and keymaps.
+
 @item -std-vga
 Simulate a standard VGA card with Bochs VBE extensions (default is
 Cirrus Logic GD5446 PCI VGA). If your guest OS supports the VESA 2.0
@@ -625,6 +634,9 @@ Disable ACPI (Advanced Configuration and Power Interface) support. Use
 it if your guest OS complains about ACPI problems (PC target machine
 only).
 
+@item -no-reboot
+Exit instead of rebooting.
+
 @item -loadvm file
 Start right away with a saved state (@code{loadvm} in monitor)
 @end table
@@ -913,6 +925,7 @@ snapshots.
 * disk_images_snapshot_mode:: Snapshot mode
 * vm_snapshots::              VM snapshots
 * qemu_img_invocation::       qemu-img Invocation
+* host_drives::               Using host drives
 * disk_images_fat_images::    Virtual FAT disk images
 @end menu
 
@@ -994,6 +1007,57 @@ state is not saved or restored properly (in particular USB).
 
 @include qemu-img.texi
 
+@node host_drives
+@subsection Using host drives
+
+In addition to disk image files, QEMU can directly access host
+devices. We describe here the usage for QEMU version >= 0.8.3.
+
+@subsubsection Linux
+
+On Linux, you can directly use the host device filename instead of a
+disk image filename provided you have enough proviledge to access
+it. For example, use @file{/dev/cdrom} to access to the CDROM or
+@file{/dev/fd0} for the floppy.
+
+@table @code
+@item CD
+You can specify a CDROM device even if no CDROM is loaded. QEMU has
+specific code to detect CDROM insertion or removal. CDROM ejection by
+the guest OS is supported. Currently only data CDs are supported.
+@item Floppy
+You can specify a floppy device even if no floppy is loaded. Floppy
+removal is currently not detected accurately (if you change floppy
+without doing floppy access while the floppy is not loaded, the guest
+OS will think that the same floppy is loaded).
+@item Hard disks
+Hard disks can be used. Normally you must specify the whole disk
+(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
+see it as a partitioned disk. WARNING: unless you know what you do, it
+is better to only make READ-ONLY accesses to the hard disk otherwise
+you may corrupt your host data (use the @option{-snapshot} command
+line option or modify the device permissions accordingly).
+@end table
+
+@subsubsection Windows
+
+On Windows you can use any host drives as QEMU drive. The prefered
+syntax is the driver letter (e.g. @file{d:}). The alternate syntax
+@file{\\.\d:} is supported. @file{/dev/cdrom} is supported as an alias
+to the first CDROM drive.
+
+Currently there is no specific code to handle removable medias, so it
+is better to use the @code{change} or @code{eject} monitor commands to
+change or eject media.
+
+@subsubsection Mac OS X
+
+@file{/dev/cdrom} is an alias to the first CDROM. 
+
+Currently there is no specific code to handle removable medias, so it
+is better to use the @code{change} or @code{eject} monitor commands to
+change or eject media.
+
 @node disk_images_fat_images
 @subsection Virtual FAT disk images
 
@@ -1053,6 +1117,8 @@ This is the standard way to connect QEMU to a real network. QEMU adds
 a virtual network device on your host (called @code{tapN}), and you
 can then configure it as if it was a real ethernet card.
 
+@subsubsection Linux host
+
 As an example, you can download the @file{linux-test-xxx.tar.gz}
 archive and copy the script @file{qemu-ifup} in @file{/etc} and
 configure properly @code{sudo} so that the command @code{ifconfig}
@@ -1060,9 +1126,15 @@ contained in @file{qemu-ifup} can be executed as root. You must verify
 that your host kernel supports the TAP network interfaces: the
 device @file{/dev/net/tun} must be present.
 
-See @ref{direct_linux_boot} to have an example of network use with a
-Linux distribution and @ref{sec_invocation} to have examples of
-command lines using the TAP network interfaces.
+See @ref{sec_invocation} to have examples of command lines using the
+TAP network interfaces.
+
+@subsubsection Windows host
+
+There is a virtual ethernet driver for Windows 2000/XP systems, called
+TAP-Win32. But it is not included in standard QEMU for Windows,
+so you will need to get it separately. It is part of OpenVPN package,
+so download OpenVPN from : @url{http://openvpn.net/}.
 
 @subsection Using the user mode network stack
 
@@ -1112,146 +1184,31 @@ basic example.
 
 This section explains how to launch a Linux kernel inside QEMU without
 having to make a full bootable image. It is very useful for fast Linux
-kernel testing. The QEMU network configuration is also explained.
-
-@enumerate
-@item
-Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
-kernel and a disk image. 
-
-@item Optional: If you want network support (for example to launch X11 examples), you
-must copy the script @file{qemu-ifup} in @file{/etc} and configure
-properly @code{sudo} so that the command @code{ifconfig} contained in
-@file{qemu-ifup} can be executed as root. You must verify that your host
-kernel supports the TUN/TAP network interfaces: the device
-@file{/dev/net/tun} must be present.
-
-When network is enabled, there is a virtual network connection between
-the host kernel and the emulated kernel. The emulated kernel is seen
-from the host kernel at IP address 172.20.0.2 and the host kernel is
-seen from the emulated kernel at IP address 172.20.0.1.
-
-@item Launch @code{qemu.sh}. You should have the following output:
+kernel testing.
 
-@smallexample
-> ./qemu.sh 
-Connected to host network interface: tun0
-Linux version 2.4.21 (bellard@@voyager.localdomain) (gcc version 3.2.2 20030222 @/(Red Hat @/Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
-BIOS-provided physical RAM map:
- BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
- BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
-32MB LOWMEM available.
-On node 0 totalpages: 8192
-zone(0): 4096 pages.
-zone(1): 4096 pages.
-zone(2): 0 pages.
-Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe @/ide5=noprobe console=ttyS0
-ide_setup: ide2=noprobe
-ide_setup: ide3=noprobe
-ide_setup: ide4=noprobe
-ide_setup: ide5=noprobe
-Initializing CPU#0
-Detected 2399.621 MHz processor.
-Console: colour EGA 80x25
-Calibrating delay loop... 4744.80 BogoMIPS
-Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, @/0k highmem)
-Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
-Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
-Mount cache hash table entries: 512 (order: 0, 4096 bytes)
-Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
-Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
-CPU: Intel Pentium Pro stepping 03
-Checking 'hlt' instruction... OK.
-POSIX conformance testing by UNIFIX
-Linux NET4.0 for Linux 2.4
-Based upon Swansea University Computer Society NET3.039
-Initializing RT netlink socket
-apm: BIOS not found.
-Starting kswapd
-Journalled Block Device driver loaded
-Detected PS/2 Mouse Port.
-pty: 256 Unix98 ptys configured
-Serial driver version 5.05c (2001-07-08) with no serial options enabled
-ttyS00 at 0x03f8 (irq = 4) is a 16450
-ne.c:v1.10 9/23/94 Donald Becker (becker@@scyld.com)
-Last modified Nov 1, 2000 by Paul Gortmaker
-NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
-eth0: NE2000 found at 0x300, using IRQ 9.
-RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
-Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
-ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
-hda: QEMU HARDDISK, ATA DISK drive
-ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
-hda: attached ide-disk driver.
-hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
-Partition check:
- hda:
-Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
-NET4: Linux TCP/IP 1.0 for NET4.0
-IP Protocols: ICMP, UDP, TCP, IGMP
-IP: routing cache hash table of 512 buckets, 4Kbytes
-TCP: Hash tables configured (established 2048 bind 4096)
-NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
-EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
-VFS: Mounted root (ext2 filesystem).
-Freeing unused kernel memory: 64k freed
-Linux version 2.4.21 (bellard@@voyager.localdomain) (gcc version 3.2.2 20030222 @/(Red Hat @/Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
-QEMU Linux test distribution (based on Redhat 9)
-Type 'exit' to halt the system
-sh-2.05b# 
-@end smallexample
-
-@item
-Then you can play with the kernel inside the virtual serial console. You
-can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help
-about the keys you can type inside the virtual serial console. In
-particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as
-the Magic SysRq key.
-
-@item 
-If the network is enabled, launch the script @file{/etc/linuxrc} in the
-emulator (don't forget the leading dot):
-@example
-. /etc/linuxrc
-@end example
-
-Then enable X11 connections on your PC from the emulated Linux: 
+The syntax is:
 @example
-xhost +172.20.0.2
+qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
 @end example
 
-You can now launch @file{xterm} or @file{xlogo} and verify that you have
-a real Virtual Linux system !
+Use @option{-kernel} to provide the Linux kernel image and
+@option{-append} to give the kernel command line arguments. The
+@option{-initrd} option can be used to provide an INITRD image.
 
-@end enumerate
-
-NOTES:
-@enumerate
-@item 
-A 2.5.74 kernel is also included in the archive. Just
-replace the bzImage in qemu.sh to try it.
-
-@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.
+When using the direct Linux boot, a disk image for the first hard disk
+@file{hda} is required because its boot sector is used to launch the
+Linux kernel.
 
-@item 
-You can boot slightly faster by disabling the probe of non present IDE
-interfaces. To do so, add the following options on the kernel command
-line:
+If you do not need graphical output, you can disable it and redirect
+the virtual serial port and the QEMU monitor to the console with the
+@option{-nographic} option. The typical command line is:
 @example
-ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
+qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
+     -append "root=/dev/hda console=ttyS0" -nographic
 @end example
 
-@item 
-The example disk image is a modified version of the one made by Kevin
-Lawton for the plex86 Project (@url{www.plex86.org}).
-
-@end enumerate
+Use @key{Ctrl-a c} to switch between the serial console and the
+monitor (@pxref{pcsys_keys}).
 
 @node pcsys_usb
 @section USB emulation
@@ -1259,7 +1216,7 @@ Lawton for the plex86 Project (@url{www.plex86.org}).
 QEMU emulates a PCI UHCI USB controller. You can virtually plug
 virtual USB devices or real host USB devices (experimental, works only
 on Linux hosts).  Qemu will automatically create and connect virtual USB hubs
-as neccessary to connect multiple USB devices.
+as necessary to connect multiple USB devices.
 
 @menu
 * usb_devices::
@@ -1275,7 +1232,7 @@ or the @code{usb_add} monitor command.  Available devices are:
 @item @code{mouse}
 Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
 @item @code{tablet}
-Pointer device that uses abolsute coordinates (like a touchscreen).
+Pointer device that uses absolute coordinates (like a touchscreen).
 This means qemu is able to report the mouse position without having
 to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
 @item @code{disk:file}
@@ -1448,7 +1405,7 @@ correctly instructs QEMU to shutdown at the appropriate moment.
 
 See @ref{sec_invocation} about the help of the option @option{-smb}.
 
-@subsubsection Windows XP security problems
+@subsubsection Windows XP security problem
 
 Some releases of Windows XP install correctly but give a security
 error when booting:
@@ -1456,10 +1413,12 @@ error when booting:
 A problem is preventing Windows from accurately checking the
 license for this computer. Error code: 0x800703e6.
 @end example
-The only known workaround is to boot in Safe mode
-without networking support. 
 
-Future QEMU releases are likely to correct this bug.
+The workaround is to install a service pack for XP after a boot in safe
+mode. Then reboot, and the problem should go away. Since there is no
+network while in safe mode, its recommended to download the full
+installation of SP1 or SP2 and transfer that via an ISO or using the
+vvfat block device ("-hdb fat:directory_which_holds_the_SP").
 
 @subsection MS-DOS and FreeDOS