\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
@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
@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
-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 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}).
+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 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
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.
+keycodes (e.g. on Macs, with some X11 servers or with a VNC
+display). You don't normally need to use it on PC/Linux or PC/Windows
+hosts.
The available layouts are:
@example
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
@table @option
@item -serial dev
-Redirect the virtual serial port to host device @var{dev}. Available
-devices are:
+Redirect the virtual serial port to host character device
+@var{dev}. The default device is @code{vc} in graphical mode and
+@code{stdio} in non graphical mode.
+
+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
[Unix only] standard input/output
@item pipe:filename
-[Unix only] name pipe @var{filename}
+name pipe @var{filename}
+@item COMn
+[Windows only] Use host serial port @var{n}
+@item udp:[remote_host]:remote_port[@@[src_ip]:src_port]
+This implements UDP Net Console. When @var{remote_host} or @var{src_ip} are not specified they default to @code{0.0.0.0}. When not using a specifed @var{src_port} a random port is automatically chosen.
+
+If you just want a simple readonly console you can use @code{netcat} or
+@code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
+@code{nc -u -l -p 4555}. Any time qemu writes something to that port it
+will appear in the netconsole session.
+
+If you plan to send characters back via netconsole or you want to stop
+and start qemu a lot of times, you should have qemu use the same
+source port each time by using something like @code{-serial
+udp::4555@@:4556} to qemu. Another approach is to use a patched
+version of netcat which can listen to a TCP port and send and receive
+characters via udp. If you have a patched version of netcat which
+activates telnet remote echo and single char transfer, then you can
+use the following options to step up a netcat redirector to allow
+telnet on port 5555 to access the qemu port.
+@table @code
+@item Qemu Options:
+-serial udp::4555@@:4556
+@item netcat options:
+-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
+@item telnet options:
+localhost 5555
@end table
-The default device is @code{vc} in graphical mode and @code{stdio} in
-non graphical mode.
-This option can be used several times to simulate up to 4 serials
-ports.
+
+@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. 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
+@item Example to send tcp console to 192.168.0.2 port 4444
+-serial tcp:192.168.0.2:4444
+@item Example to listen and wait on port 4444 for connection
+-serial tcp::4444,server
+@item Example to not wait and listen on ip 192.168.0.100 port 4444
+-serial tcp:192.168.0.100:4444,server,nowait
+@end table
+
+@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
+telnet option negotiation. This will also allow you to send the
+MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
+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
Redirect the virtual parallel port to host device @var{dev} (same
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
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)
+Cirrus Logic GD5446 PCI VGA). If your guest OS supports the VESA 2.0
+VBE extensions (e.g. Windows XP) and if you want to use high
+resolution modes (>= 1280x1024x16) then you should use this option.
+
+@item -no-acpi
+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)
+
+@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 USB devices plugged on the virtual USB hub
@item info usbhost
show all USB host devices
+@item info capture
+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}.
+
+Defaults:
+@itemize @minus
+@item Sample rate = 44100 Hz - CD quality
+@item Bits = 16
+@item Number of channels = 2 - Stereo
+@end itemize
+
+@item stopcapture index
+Stop capture with a given @var{index}, index can be obtained with
+@example
+info capture
+@end example
+
@item log item1[,...]
Activate logging of the specified items to @file{/tmp/qemu.log}.
-@item savevm filename
-Save the whole virtual machine state to @var{filename}.
+@item savevm [tag|id]
+Create a snapshot of the whole virtual machine. If @var{tag} is
+provided, it is used as human readable identifier. If there is already
+a snapshot with the same tag or ID, it is replaced. More info at
+@ref{vm_snapshots}.
-@item loadvm filename
-Restore the whole virtual machine state from @var{filename}.
+@item loadvm tag|id
+Set the whole virtual machine to the snapshot identified by the tag
+@var{tag} or the unique snapshot ID @var{id}.
+
+@item delvm tag|id
+Delete the snapshot identified by @var{tag} or @var{id}.
@item stop
Stop emulation.
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.
+written), compressed and encrypted disk images. Version 0.8.3 added
+the new qcow2 disk image format which is essential to support VM
+snapshots.
@menu
* disk_images_quickstart:: Quick start for disk image creation
* 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
write back to the raw disk images by using the @code{commit} monitor
command (or @key{C-a s} in the serial console).
+@node vm_snapshots
+@subsection VM snapshots
+
+VM snapshots are snapshots of the complete virtual machine including
+CPU state, RAM, device state and the content of all the writable
+disks. In order to use VM snapshots, you must have at least one non
+removable and writable block device using the @code{qcow2} disk image
+format. Normally this device is the first virtual hard drive.
+
+Use the monitor command @code{savevm} to create a new VM snapshot or
+replace an existing one. A human readable name can be assigned to each
+snapshot in addition to its numerical ID.
+
+Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
+a VM snapshot. @code{info snapshots} lists the available snapshots
+with their associated information:
+
+@example
+(qemu) info snapshots
+Snapshot devices: hda
+Snapshot list (from hda):
+ID TAG VM SIZE DATE VM CLOCK
+1 start 41M 2006-08-06 12:38:02 00:00:14.954
+2 40M 2006-08-06 12:43:29 00:00:18.633
+3 msys 40M 2006-08-06 12:44:04 00:00:23.514
+@end example
+
+A VM snapshot is made of a VM state info (its size is shown in
+@code{info snapshots}) and a snapshot of every writable disk image.
+The VM state info is stored in the first @code{qcow2} non removable
+and writable block device. The disk image snapshots are stored in
+every disk image. The size of a snapshot in a disk image is difficult
+to evaluate and is not shown by @code{info snapshots} because the
+associated disk sectors are shared among all the snapshots to save
+disk space (otherwise each snapshot would need a full copy of all the
+disk images).
+
+When using the (unrelated) @code{-snapshot} option
+(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
+but they are deleted as soon as you exit QEMU.
+
+VM snapshots currently have the following known limitations:
+@itemize
+@item
+They cannot cope with removable devices if they are removed or
+inserted after a snapshot is done.
+@item
+A few device drivers still have incomplete snapshot support so their
+state is not saved or restored properly (in particular USB).
+@end itemize
+
@node qemu_img_invocation
@subsection @code{qemu-img} Invocation
@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
+
+@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 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 media, 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
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}
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
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:
-
-@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
+kernel testing.
-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 !
-
-@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.
+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.
-@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
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}
and use this graphic card. For optimal performances, use 16 bit color
depth in the guest and the host OS.
+If you are using Windows XP as guest OS and if you want to use high
+resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
+1280x1024x16), then you should use the VESA VBE virtual graphic card
+(option @option{-std-vga}).
+
@subsubsection CPU usage reduction
Windows 9x does not correctly use the CPU HLT
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
The number of peripherals is fixed in the architecture.
-Since version 0.8.1, QEMU uses OpenBIOS
+Since version 0.8.2, 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.
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:
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.
+@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
+
+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.
-
-@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
+@subsection GCC version
-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