\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
@iftex
@titlepage
@sp 7
-@center @titlefont{QEMU CPU Emulator}
+@center @titlefont{QEMU Emulator}
@sp 1
@center @titlefont{User Documentation}
@sp 3
* Installation::
* QEMU PC System emulator::
* QEMU System emulator for non PC targets::
-* QEMU Linux User space emulator::
+* QEMU User space emulator::
* compilation:: Compilation from the sources
* Index::
@end menu
without rebooting the PC or to debug system code.
@item
-User mode emulation (Linux host only). In this mode, QEMU can launch
-Linux processes compiled for one CPU on another CPU. It can be used to
+User mode emulation. In this mode, QEMU can launch
+processes compiled for one CPU on another CPU. It can be used to
launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
to ease cross-compilation and cross-debugging.
@item Malta board (32-bit MIPS processor)
@item ARM Integrator/CP (ARM926E or 1026E processor)
@item ARM Versatile baseboard (ARM926E)
+@item ARM RealView Emulation baseboard (ARM926EJ-S)
@end itemize
-For user emulation, x86, PowerPC, ARM, MIPS, and Sparc32/64 CPUs are supported.
+For user emulation, x86, PowerPC, ARM, MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
@node Installation
@chapter Installation
@option{-cdrom} at the same time). You can use the host CD-ROM by
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
-the default.
+@item -boot [a|c|d|n]
+Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
+is the default.
@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} (@pxref{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
the console. Therefore, you can still use QEMU to debug a Linux kernel
with a serial console.
-@item -vnc d
+@item -no-frame
+
+Do not use decorations for SDL windows and start them using the whole
+available screen space. This makes the using QEMU in a dedicated desktop
+workspace more convenient.
+
+@item -vnc display
Normally, QEMU uses SDL to display the VGA output. With this option,
-you can have QEMU listen on VNC display @var{d} and redirect the VGA
+you can have QEMU listen on VNC display @var{display} 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}). When using the VNC display, you must use the @option{-k}
-option to set the keyboard layout.
+option to set the keyboard layout if you are not using en-us.
+
+@var{display} may be in the form @var{interface:d}, in which case connections
+will only be allowed from @var{interface} on display @var{d}. Optionally,
+@var{interface} can be omitted. @var{display} can also be in the form
+@var{unix:path} where @var{path} is the location of a unix socket to listen for
+connections on.
+
@item -k language
Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
from a script.
+@item -daemonize
+Daemonize the QEMU process after initialization. QEMU will not detach from
+standard IO until it is ready to receive connections on any of its devices.
+This option is a useful way for external programs to launch QEMU without having
+to cope with initialization race conditions.
+
@item -win2k-hack
Use it when installing Windows 2000 to avoid a disk full bug. After
Windows 2000 is installed, you no longer need this option (this option
slows down the IDE transfers).
+@item -option-rom file
+Load the contents of file as an option ROM. This option is useful to load
+things like EtherBoot.
+
+@item -name string
+Sets the name of the guest. This name will be display in the SDL window
+caption. The name will also be used for the VNC server.
+
@end table
USB options:
@item -net tap[,vlan=n][,fd=h][,ifname=name][,script=file]
Connect the host TAP network interface @var{name} to VLAN @var{n} and
use the network script @var{file} to configure it. The default
-network script is @file{/etc/qemu-ifup}. If @var{name} is not
+network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
+disable script execution. If @var{name} is not
provided, the OS automatically provides one. @option{fd=h} can be
used to specify the handle of an already opened host TAP interface. Example:
override the default configuration (@option{-net nic -net user}) which
is activated if no @option{-net} options are provided.
-@item -tftp prefix
+@item -tftp dir
When using the user mode network stack, activate a built-in TFTP
-server. All filenames beginning with @var{prefix} can be downloaded
-from the host to the guest using a TFTP client. The TFTP client on the
-guest must be configured in binary mode (use the command @code{bin} of
-the Unix TFTP client). The host IP address on the guest is as usual
-10.0.2.2.
+server. The files in @var{dir} will be exposed as the root of a TFTP server.
+The TFTP client on the guest must be configured in binary mode (use the command
+@code{bin} of the Unix TFTP client). The host IP address on the guest is as
+usual 10.0.2.2.
+
+@item -bootp file
+When using the user mode network stack, broadcast @var{file} as the BOOTP
+filename. In conjunction with @option{-tftp}, this can be used to network boot
+a guest from a local directory.
+
+Example (using pxelinux):
+@example
+qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0
+@end example
@item -smb dir
When using the user mode network stack, activate a built-in SMB
Then @file{dir} can be accessed in @file{\\smbserver\qemu}.
Note that a SAMBA server must be installed on the host OS in
-@file{/usr/sbin/smbd}. QEMU was tested succesfully with smbd version
+@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version
2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
@item -redir [tcp|udp]:host-port:[guest-host]:guest-port
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
parameters are set according to the emulated ones.
@item /dev/parportN
[Linux only, parallel port only] Use host parallel port
-@var{N}. Currently only SPP parallel port features can be used.
+@var{N}. Currently SPP and EPP parallel port features can be used.
@item file:filename
Write output to filename. No character can be read.
@item stdio
@end table
-@item tcp:[host]:port[,server][,nowait]
+@item tcp:[host]:port[,server][,nowait][,nodelay]
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}
-option was specified. If @var{host} is omitted, 0.0.0.0 is assumed. Only
+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. The @code{nodelay} option disables the Nagle buffering
+algoritm. 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.
@table @code
-serial tcp:192.168.0.100:4444,server,nowait
@end table
-@item telnet:host:port[,server][,nowait]
+@item telnet:host:port[,server][,nowait][,nodelay]
The telnet protocol is used instead of raw tcp sockets. The options
work the same as if you had specified @code{-serial tcp}. The
difference is that the port acts like a telnet server or client using
sequence. Typically in unix telnet you do it with Control-] and then
type "send break" followed by pressing the enter key.
+@item unix:path[,server][,nowait]
+A unix domain socket is used instead of a tcp socket. The option works the
+same as if you had specified @code{-serial tcp} except the unix domain socket
+@var{path} is used for connections.
+
+@item mon:dev_string
+This is a special option to allow the monitor to be multiplexed onto
+another serial port. The monitor is accessed with key sequence of
+@key{Control-a} and then pressing @key{c}. See monitor access
+@ref{pcsys_keys} in the -nographic section for more keys.
+@var{dev_string} should be any one of the serial devices specified
+above. An example to multiplex the monitor onto a telnet server
+listening on port 4444 would be:
+@table @code
+@item -serial mon:telnet::4444,server,nowait
+@end table
+
@end table
@item -parallel dev
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).
The default device is @code{vc} in graphical mode and @code{stdio} in
non graphical mode.
+@item -echr numeric_ascii_value
+Change the escape character used for switching to the monitor when using
+monitor and serial sharing. The default is @code{0x01} when using the
+@code{-nographic} option. @code{0x01} is equal to pressing
+@code{Control-a}. You can select a different character from the ascii
+control keys where 1 through 26 map to Control-a through Control-z. For
+instance you could use the either of the following to change the escape
+character to Control-t.
+@table @code
+@item -echr 0x14
+@item -echr 20
+@end table
+
@item -s
Wait gdb connection to port 1234 (@pxref{gdb_usage}).
@item -p port
-Change gdb connection port.
+Change gdb connection port. @var{port} can be either a decimal number
+to specify a TCP port, or a host device (same devices as the serial port).
@item -S
Do not start CPU at startup (you must type 'c' in the monitor).
@item -d
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)
+
+@item -semihosting
+Enable "Angel" semihosting interface (ARM target machines only).
+Note that this allows guest direct access to the host filesystem,
+so should only be used with trusted guest OS.
@end table
@c man end
@item Ctrl-a h
Print this help
@item Ctrl-a x
-Exit emulatior
+Exit emulator
@item Ctrl-a s
Save disk data back to file (if -snapshot)
+@item Ctrl-a t
+toggle console timestamps
@item Ctrl-a b
Send break (magic sysrq in Linux)
@item Ctrl-a c
@itemize @minus
@item
-Remove or insert removable medias images
+Remove or insert removable media images
(such as CD-ROM or floppies)
@item
show information about active capturing
@item info snapshots
show list of VM snapshots
+@item info mice
+show which guest mouse is receiving events
@end table
@item q or quit
Quit the emulator.
@item eject [-f] device
-Eject a removable media (use -f to force it).
+Eject a removable medium (use -f to force it).
@item change device filename
-Change a removable media.
+Change a removable medium.
@item screendump filename
Save screen into PPM image @var{filename}.
+@item mouse_move dx dy [dz]
+Move the active mouse to the specified coordinates @var{dx} @var{dy}
+with optional scroll axis @var{dz}.
+
+@item mouse_button val
+Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
+
+@item mouse_set index
+Set which mouse device receives events at given @var{index}, index
+can be obtained with
+@example
+info mice
+@end example
+
@item wavcapture filename [frequency [bits [channels]]]
Capture audio into @var{filename}. Using sample rate @var{frequency}
bits per sample @var{bits} and number of channels @var{channels}.
it. For example, use @file{/dev/cdrom} to access to the CDROM or
@file{/dev/fd0} for the floppy.
-@table
+@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
@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.
+@table @code
+@item CD
+The prefered syntax is the drive 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
+Currently there is no specific code to handle removable media, so it
is better to use the @code{change} or @code{eject} monitor commands to
change or eject media.
+@item Hard disks
+Hard disks can be used with the syntax: @file{\\.\PhysicalDriveN}
+where @var{N} is the drive number (0 is the first hard 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 so that the
+modifications are written in a temporary file).
+@end table
+
@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
+Currently there is no specific code to handle removable media, so it
is better to use the @code{change} or @code{eject} monitor commands to
change or eject media.
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}
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
By using the option @option{-net user} (default configuration if no
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::
@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}
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:
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
PL110 LCD controller
@item
PL050 KMI with PS/2 keyboard and mouse.
+@item
+PL181 MultiMedia Card Interface with SD card.
@end itemize
The ARM Versatile baseboard is emulated with the following devices:
PCI OHCI USB controller.
@item
LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
+@item
+PL181 MultiMedia Card Interface with SD card.
+@end itemize
+
+The ARM RealView Emulation baseboard is emulated with the following devices:
+
+@itemize @minus
+@item
+ARM926E CPU
+@item
+ARM AMBA Generic/Distributed 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
+@item
+PCI OHCI USB controller
+@item
+LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
+@item
+PL181 MultiMedia Card Interface with SD card.
@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
+@node QEMU User space emulator
+@chapter QEMU User space emulator
+
+@menu
+* Supported Operating Systems ::
+* Linux User space emulator::
+* Mac OS X/Darwin User space emulator ::
+@end menu
+
+@node Supported Operating Systems
+@section Supported Operating Systems
+
+The following OS are supported in user space emulation:
+
+@itemize @minus
+@item
+Linux (refered as qemu-linux-user)
+@item
+Mac OS X/Darwin (refered as qemu-darwin-user)
+@end itemize
+
+@node Linux User space emulator
+@section Linux User space emulator
@menu
* Quick Start::
@end menu
@node Quick Start
-@section Quick Start
+@subsection Quick Start
In order to launch a Linux process, QEMU needs the process executable
itself and all the target (x86) dynamic libraries used by it.
@code{-L /} tells that the x86 dynamic linker must be searched with a
@file{/} prefix.
-@item Since QEMU is also a linux process, you can launch qemu with qemu (NOTE: you can only do that if you compiled QEMU from the sources):
+@item Since QEMU is also a linux process, you can launch qemu with
+qemu (NOTE: you can only do that if you compiled QEMU from the sources):
@example
qemu-i386 -L / qemu-i386 -L / /bin/ls
@end itemize
@node Wine launch
-@section Wine launch
+@subsection Wine launch
@itemize
@end itemize
@node Command line options
-@section Command line options
+@subsection Command line options
@example
usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
@end table
@node Other binaries
-@section Other binaries
+@subsection 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.
+@command{qemu-m68k} is capable of running semihosted binaries using the BDM
+(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
+coldfire uClinux bFLT format binaries.
+
The binary format is detected automatically.
+@node Mac OS X/Darwin User space emulator
+@section Mac OS X/Darwin User space emulator
+
+@menu
+* Mac OS X/Darwin Status::
+* Mac OS X/Darwin Quick Start::
+* Mac OS X/Darwin Command line options::
+@end menu
+
+@node Mac OS X/Darwin Status
+@subsection Mac OS X/Darwin Status
+
+@itemize @minus
+@item
+target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
+@item
+target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
+@item
+target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
+@item
+target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
+@end itemize
+
+[1] If you're host commpage can be executed by qemu.
+
+@node Mac OS X/Darwin Quick Start
+@subsection Quick Start
+
+In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
+itself and all the target dynamic libraries used by it. If you don't have the FAT
+libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
+CD or compile them by hand.
+
+@itemize
+
+@item On x86, you can just try to launch any process by using the native
+libraries:
+
+@example
+qemu-i386 /bin/ls
+@end example
+
+or to run the ppc version of the executable:
+
+@example
+qemu-ppc /bin/ls
+@end example
+
+@item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
+are installed:
+
+@example
+qemu-i386 -L /opt/x86_root/ /bin/ls
+@end example
+
+@code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
+@file{/opt/x86_root/usr/bin/dyld}.
+
+@end itemize
+
+@node Mac OS X/Darwin Command line options
+@subsection Command line options
+
+@example
+usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
+@end example
+
+@table @option
+@item -h
+Print the help
+@item -L path
+Set the library root path (default=/)
+@item -s size
+Set the stack size in bytes (default=524288)
+@end table
+
+Debug options:
+
+@table @option
+@item -d
+Activate log (logfile=/tmp/qemu.log)
+@item -p pagesize
+Act as if the host page size was 'pagesize' bytes
+@end table
+
@node compilation
@chapter Compilation from the sources
@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.
+@subsection GCC version
-@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
+In order to compile QEMU successfully, it is very important that you
+have the right tools. The most important one is gcc. On most hosts and
+in particular on x86 ones, @emph{gcc 4.x is not supported}. If your
+Linux distribution includes a gcc 4.x compiler, you can usually
+install an older version (it is invoked by @code{gcc32} or
+@code{gcc34}). The QEMU configure script automatically probes for
+these older versions so that usally you don't have to do anything.
@node Windows
@section Windows
projects / qemu / blobdiff