\input texinfo @c -*- texinfo -*-
+@c %**start of header
+@setfilename qemu-doc.info
+@settitle QEMU CPU Emulator User Documentation
+@exampleindent 0
+@paragraphindent 0
+@c %**end of header
@iftex
-@settitle QEMU CPU Emulator User Documentation
@titlepage
@sp 7
-@center @titlefont{QEMU CPU Emulator User Documentation}
+@center @titlefont{QEMU CPU Emulator}
+@sp 1
+@center @titlefont{User Documentation}
@sp 3
@end titlepage
@end iftex
+@ifnottex
+@node Top
+@top
+
+@menu
+* Introduction::
+* Installation::
+* QEMU PC System emulator::
+* QEMU System emulator for non PC targets::
+* QEMU Linux User space emulator::
+* compilation:: Compilation from the sources
+* Index::
+@end menu
+@end ifnottex
+
+@contents
+
+@node Introduction
@chapter Introduction
+@menu
+* intro_features:: Features
+@end menu
+
+@node intro_features
@section Features
QEMU is a FAST! processor emulator using dynamic translation to
@item Sun4m (32-bit Sparc processor)
@item Sun4u (64-bit Sparc processor, in progress)
@item Malta board (32-bit MIPS processor)
-@item ARM Integrator/CP (ARM1026E processor)
+@item ARM Integrator/CP (ARM926E or 1026E processor)
+@item ARM Versatile baseboard (ARM926E)
@end itemize
For user emulation, x86, PowerPC, ARM, MIPS, and Sparc32/64 CPUs are supported.
+@node Installation
@chapter Installation
If you want to compile QEMU yourself, see @ref{compilation}.
+@menu
+* install_linux:: Linux
+* install_windows:: Windows
+* install_mac:: Macintosh
+@end menu
+
+@node install_linux
@section Linux
If a precompiled package is available for your distribution - you just
have to install it. Otherwise, see @ref{compilation}.
+@node install_windows
@section Windows
Download the experimental binary installer at
-@url{http://www.freeoszoo.org/download.php}.
+@url{http://www.free.oszoo.org/@/download.html}.
+@node install_mac
@section Mac OS X
Download the experimental binary installer at
-@url{http://www.freeoszoo.org/download.php}.
+@url{http://www.free.oszoo.org/@/download.html}.
+@node QEMU PC System emulator
@chapter QEMU PC System emulator
+@menu
+* pcsys_introduction:: Introduction
+* pcsys_quickstart:: Quick Start
+* sec_invocation:: Invocation
+* pcsys_keys:: Keys
+* pcsys_monitor:: QEMU Monitor
+* disk_images:: Disk Images
+* pcsys_network:: Network emulation
+* direct_linux_boot:: Direct Linux Boot
+* pcsys_usb:: USB emulation
+* gdb_usage:: GDB usage
+* pcsys_os_specific:: Target OS specific information
+@end menu
+
+@node pcsys_introduction
@section Introduction
@c man begin DESCRIPTION
@c man end
+@node pcsys_quickstart
@section Quick Start
Download and uncompress the linux image (@file{linux.img}) and type:
@item -fda file
@item -fdb file
-Use @var{file} as floppy disk 0/1 image (@xref{disk_images}). You can
+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.
@item -hda file
@item -hdb file
@item -hdc file
@item -hdd file
-Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}).
+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
@item -snapshot
Write to temporary files instead of disk image files. In this case,
the raw disk image you use is not written back. You can however force
-the write back by pressing @key{C-a s} (@xref{disk_images}).
+the write back by pressing @key{C-a s} (@pxref{disk_images}).
+
+@item -no-fd-bootchk
+Disable boot signature checking for floppy disks in Bochs BIOS. It may
+be needed to boot from old floppy disks.
@item -m megs
Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
the console. Therefore, you can still use QEMU to debug a Linux kernel
with a serial console.
+@item -vnc d
+
+Normally, QEMU uses SDL to display the VGA output. With this option,
+you can have QEMU listen on VNC display d and redirect the VGA display
+over the VNC session. It is very useful to enable the usb tablet device
+when using this option (option @option{-usbdevice tablet}).
+
@item -k language
Use keyboard layout @var{language} (for example @code{fr} for
The default is @code{en-us}.
-@item -enable-audio
-
-Will enable audio and all the sound hardware QEMU was built with.
-
@item -audio-help
Will show the audio subsystem help: list of drivers, tunable
parameters.
-@item -soundhw card1,card2,...
+@item -soundhw card1,card2,... or -soundhw all
Enable audio and selected sound hardware. Use ? to print all
available sound hardware.
@example
qemu -soundhw sb16,adlib hda
qemu -soundhw es1370 hda
+qemu -soundhw all hda
qemu -soundhw ?
@end example
Enable the USB driver (will be the default soon)
@item -usbdevice devname
-Add the USB device @var{devname}. See the monitor command
-@code{usb_add} to have more information.
+Add the USB device @var{devname}. @xref{usb_devices}.
@end table
Network options:
@table @option
-@item -net nic[,vlan=n][,macaddr=addr]
+@item -net nic[,vlan=n][,macaddr=addr][,model=type]
Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
= 0 is the default). The NIC is currently an NE2000 on the PC
target. Optionally, the MAC address can be changed. If no
@option{-net} option is specified, a single NIC is created.
+Qemu can emulate several different models of network card. Valid values for
+@var{type} are @code{ne2k_pci}, @code{ne2k_isa}, @code{rtl8139},
+@code{smc91c111} and @code{lance}. Not all devices are supported on all
+targets.
-@item -net user[,vlan=n]
+@item -net user[,vlan=n][,hostname=name]
Use the user mode network stack which requires no administrator
-priviledge to run. This is the default if no @option{-net} option is
-specified.
+priviledge to run. @option{hostname=name} can be used to specify the client
+hostname reported by the builtin DHCP server.
@item -net tap[,vlan=n][,fd=h][,ifname=name][,script=file]
Connect the host TAP network interface @var{name} to VLAN @var{n} and
Example:
@example
# launch a first QEMU instance
-qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,listen=:1234
-# connect the VLAN 0 of this instance to the VLAN 0 of the first instance
-qemu linux.img -net nic,macaddr=52:54:00:12:34:57 -net socket,connect=127.0.0.1:1234
+qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
+ -net socket,listen=:1234
+# connect the VLAN 0 of this instance to the VLAN 0
+# of the first instance
+qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
+ -net socket,connect=127.0.0.1:1234
@end example
@item -net socket[,vlan=n][,fd=h][,mcast=maddr:port]
Example:
@example
# launch one QEMU instance
-qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,mcast=230.0.0.1:1234
+qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
+ -net socket,mcast=230.0.0.1:1234
# launch another QEMU instance on same "bus"
-qemu linux.img -net nic,macaddr=52:54:00:12:34:57 -net socket,mcast=230.0.0.1:1234
+qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
+ -net socket,mcast=230.0.0.1:1234
# launch yet another QEMU instance on same "bus"
-qemu linux.img -net nic,macaddr=52:54:00:12:34:58 -net socket,mcast=230.0.0.1:1234
+qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
+ -net socket,mcast=230.0.0.1:1234
@end example
Example (User Mode Linux compat.):
@example
-# launch QEMU instance (note mcast address selected is UML's default)
-qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,mcast=239.192.168.1:1102
+# launch QEMU instance (note mcast address selected
+# is UML's default)
+qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
+ -net socket,mcast=239.192.168.1:1102
# launch UML
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
@end example
@item -net none
Indicate that no network devices should be configured. It is used to
-override the default configuration which is activated if no
-@option{-net} options are provided.
+override the default configuration (@option{-net nic -net user}) which
+is activated if no @option{-net} options are provided.
@item -tftp prefix
When using the user mode network stack, activate a built-in TFTP
non graphical mode.
@item -s
-Wait gdb connection to port 1234 (@xref{gdb_usage}).
+Wait gdb connection to port 1234 (@pxref{gdb_usage}).
@item -p port
Change gdb connection port.
@item -S
@c man end
+@node pcsys_keys
@section Keys
@c man begin OPTIONS
@ignore
-@setfilename qemu
-@settitle QEMU System Emulator
-
@c man begin SEEALSO
The HTML documentation of QEMU for more precise information and Linux
user mode emulator invocation.
@end ignore
-@end ignore
-
+@node pcsys_monitor
@section QEMU Monitor
The QEMU monitor is used to give complex commands to the QEMU
@item
Dump 80 16 bit values at the start of the video memory.
-@example
+@smallexample
(qemu) xp/80hx 0xb8000
0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
-@end example
+@end smallexample
@end itemize
@item p or print/fmt expr
@item usb_add devname
-Plug the USB device devname to the QEMU virtual USB hub. @var{devname}
-is either a virtual device name (for example @code{mouse}) or a host
-USB device identifier. Host USB device identifiers have the following
-syntax: @code{host:bus.addr} or @code{host:vendor_id:product_id}.
+Add the USB device @var{devname}. For details of available devices see
+@ref{usb_devices}
@item usb_del devname
growable disk images (their size increase as non empty sectors are
written), compressed and encrypted disk images.
+@menu
+* disk_images_quickstart:: Quick start for disk image creation
+* disk_images_snapshot_mode:: Snapshot mode
+* qemu_img_invocation:: qemu-img Invocation
+* disk_images_fat_images:: Virtual FAT disk images
+@end menu
+
+@node disk_images_quickstart
@subsection Quick start for disk image creation
You can create a disk image with the command:
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.
+See @ref{qemu_img_invocation} for more information.
+@node disk_images_snapshot_mode
@subsection Snapshot mode
If you use the option @option{-snapshot}, all disk images are
@include qemu-img.texi
+@node disk_images_fat_images
@subsection Virtual FAT disk images
QEMU can automatically create a virtual FAT disk image from a
@itemize
@item use non-ASCII filenames ;
@item use "-snapshot" together with ":rw:" ;
-@item expect it to work when loadvm'ing.
+@item expect it to work when loadvm'ing ;
+@item write to the FAT directory on the host system while accessing it with the guest system.
@end itemize
+@node pcsys_network
@section Network emulation
QEMU can simulate several networks cards (NE2000 boards on the PC
@item Launch @code{qemu.sh}. You should have the following output:
-@example
+@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
+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)
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
+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
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)
+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)
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)
+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.
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
+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 example
+@end smallexample
@item
Then you can play with the kernel inside the virtual serial console. You
@end enumerate
+@node pcsys_usb
@section USB emulation
-QEMU emulates a PCI UHCI USB controller and a 8 port USB hub connected
-to it. You can virtually plug to the hub virtual USB devices or real
-host USB devices (experimental, works only on Linux hosts).
-
-@subsection Using virtual USB devices
-
-A virtual USB mouse device is available for testing in QEMU.
+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.
-You can try it with the following monitor commands:
+@menu
+* usb_devices::
+* host_usb_devices::
+@end menu
+@node usb_devices
+@subsection Connecting USB devices
-@example
-# add the mouse device
-(qemu) usb_add mouse
-
-# show the virtual USB devices plugged on the QEMU Virtual USB hub
-(qemu) info usb
- Device 0.3, speed 12 Mb/s
+USB devices can be connected with the @option{-usbdevice} commandline option
+or the @code{usb_add} monitor command. Available devices are:
-# after some time you can try to remove the mouse
-(qemu) usb_del 0.3
-@end example
-
-The option @option{-usbdevice} is similar to the monitor command
-@code{usb_add}.
+@table @var
+@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).
+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}
+Mass storage device based on @var{file} (@pxref{disk_images})
+@item @code{host:bus.addr}
+Pass through the host device identified by @var{bus.addr}
+(Linux only)
+@item @code{host:vendor_id:product_id}
+Pass through the host device identified by @var{vendor_id:product_id}
+(Linux only)
+@end table
+@node host_usb_devices
@subsection Using host USB devices on a Linux host
WARNING: this is an experimental feature. QEMU will slow down when
In order to use gdb, launch qemu with the '-s' option. It will wait for a
gdb connection:
@example
-> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
+> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
+ -append "root=/dev/hda"
Connected to host network interface: tun0
Waiting gdb connection on port 1234
@end example
Use @code{x/10i $eip} to display the code at the PC position.
@item
Use @code{set architecture i8086} to dump 16 bit code. Then use
-@code{x/10i $cs*16+*eip} to dump the code at the PC position.
+@code{x/10i $cs*16+$eip} to dump the code at the PC position.
@end enumerate
+@node pcsys_os_specific
@section Target OS specific information
@subsection Linux
from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
problem.
+@node QEMU System emulator for non PC targets
@chapter QEMU System emulator for non PC targets
QEMU is a generic emulator and it emulates many non PC
machines. Most of the options are similar to the PC emulator. The
differences are mentionned in the following sections.
+@menu
+* QEMU PowerPC System emulator::
+* Sparc32 System emulator invocation::
+* Sparc64 System emulator invocation::
+* MIPS System emulator invocation::
+* ARM System emulator invocation::
+@end menu
+
+@node QEMU PowerPC System emulator
@section QEMU PowerPC System emulator
Use the executable @file{qemu-system-ppc} to simulate a complete PREP
More information is available at
@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
+@node Sparc32 System emulator invocation
@section Sparc32 System emulator invocation
-Use the executable @file{qemu-system-sparc} to simulate a JavaStation
+Use the executable @file{qemu-system-sparc} to simulate a SparcStation 5
(sun4m architecture). The emulation is somewhat complete.
QEMU emulates the following sun4m peripherals:
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.
+Since version 0.8.1, QEMU uses OpenBIOS
+@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
+firmware implementation. The goal is to implement a 100% IEEE
+1275-1994 (referred to as Open Firmware) compliant firmware.
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.
+the QEMU web site. Please note that currently NetBSD, OpenBSD or
+Solaris kernels don't work.
@c man begin OPTIONS
@c man end
+@node Sparc64 System emulator invocation
@section Sparc64 System emulator invocation
Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
PC-compatible serial ports
@end itemize
+@node MIPS System emulator invocation
@section MIPS System emulator invocation
Use the executable @file{qemu-system-mips} to simulate a MIPS machine.
More information is available in the QEMU mailing-list archive.
+@node ARM System emulator invocation
@section ARM System emulator invocation
Use the executable @file{qemu-system-arm} to simulate a ARM
@itemize @minus
@item
-ARM1026E CPU
+ARM926E or ARM1026E CPU
@item
Two PL011 UARTs
@item
SMC 91c111 Ethernet adapter
+@item
+PL110 LCD controller
+@item
+PL050 KMI with PS/2 keyboard and mouse.
+@end itemize
+
+The ARM Versatile baseboard is emulated with the following devices:
+
+@itemize @minus
+@item
+ARM926E CPU
+@item
+PL190 Vectored Interrupt Controller
+@item
+Four PL011 UARTs
+@item
+SMC 91c111 Ethernet adapter
+@item
+PL110 LCD controller
+@item
+PL050 KMI with PS/2 keyboard and mouse.
+@item
+PCI host bridge. Note the emulated PCI bridge only provides access to
+PCI memory space. It does not provide access to PCI IO space.
+This means some devices (eg. ne2k_pci NIC) are not useable, and others
+(eg. rtl8139 NIC) are only useable when the guest drivers use the memory
+mapped control registers.
@end itemize
A Linux 2.6 test image is available on the QEMU web site. More
information is available in the QEMU mailing-list archive.
+@node QEMU Linux User space emulator
@chapter QEMU Linux User space emulator
+@menu
+* Quick Start::
+* Wine launch::
+* Command line options::
+* Other binaries::
+@end menu
+
+@node Quick Start
@section Quick Start
In order to launch a Linux process, QEMU needs the process executable
@item The x86 version of QEMU is also included. You can try weird things such as:
@example
-qemu-i386 /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
@end example
@end itemize
+@node Wine launch
@section Wine launch
@itemize
(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
@item Configure Wine on your account. Look at the provided script
-@file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous
+@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
@item Then you can try the example @file{putty.exe}:
@example
-qemu-i386 /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
@end example
@end itemize
+@node Command line options
@section Command line options
@example
Act as if the host page size was 'pagesize' bytes
@end table
+@node Other binaries
+@section Other binaries
+
+@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
+binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
+configurations), and arm-uclinux bFLT format binaries.
+
+The binary format is detected automatically.
+
@node compilation
@chapter Compilation from the sources
+@menu
+* Linux/Unix::
+* Windows::
+* Cross compilation for Windows with Linux::
+* Mac OS X::
+@end menu
+
+@node Linux/Unix
@section Linux/Unix
@subsection Compilation
variables. You must use gcc 3.x on PowerPC.
@end example
+@node Windows
@section Windows
@itemize
@item Download
the MinGW development library of SDL 1.2.x
-(@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
+(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
@url{http://www.libsdl.org}. Unpack it in a temporary place, and
unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
directory. Edit the @file{sdl-config} script so that it gives the
@end itemize
+@node Cross compilation for Windows with Linux
@section Cross compilation for Windows with Linux
@itemize
Note: Currently, Wine does not seem able to launch
QEMU for Win32.
+@node Mac OS X
@section Mac OS X
The Mac OS X patches are not fully merged in QEMU, so you should look
at the QEMU mailing list archive to have all the necessary
information.
+@node Index
+@chapter Index
+@printindex cp
+
+@bye
projects / qemu.git / blobdiff