@item G3 BW PowerMac (PowerPC processor)
@item Mac99 PowerMac (PowerPC processor, in progress)
@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
-@item Sun4u (64-bit Sparc processor, in progress)
+@item Sun4u/Sun4v (64-bit Sparc processor, in progress)
@item Malta board (32-bit and 64-bit MIPS processors)
@item MIPS Magnum (64-bit MIPS processor)
@item ARM Integrator/CP (ARM)
@item Freescale MCF5208EVB (ColdFire V2).
@item Arnewsh MCF5206 evaluation board (ColdFire V2).
@item Palm Tungsten|E PDA (OMAP310 processor)
+@item N800 and N810 tablets (OMAP2420 processor)
+@item MusicPal (MV88W8618 ARM processor)
@end itemize
For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
@item
Gravis Ultrasound GF1 sound card
@item
+CS4231A compatible sound card
+@item
PCI UHCI USB controller and a virtual USB hub.
@end itemize
SMP is supported with up to 255 CPUs.
-Note that adlib, ac97 and gus are only available when QEMU was configured
-with --enable-adlib, --enable-ac97 or --enable-gus respectively.
+Note that adlib, ac97, gus and cs4231a are only available when QEMU
+was configured with --audio-card-list option containing the name(s) of
+required card(s).
QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
VGA BIOS.
QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
by Tibor "TS" Schütz.
+CS4231A is the chip used in Windows Sound System and GUSMAX products
+
@c man end
@node pcsys_quickstart
@item snapshot=@var{snapshot}
@var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
@item cache=@var{cache}
-@var{cache} is "on" or "off" and allows to disable host cache to access data.
+@var{cache} is "none", "writeback", or "writethrough" and controls how the host cache is used to access block data.
+@item format=@var{format}
+Specify which disk @var{format} will be used rather than detecting
+the format. Can be used to specifiy format=raw to avoid interpreting
+an untrusted format header.
@end table
+By default, writethrough caching is used for all block device. This means that
+the host page cache will be used to read and write data but write notification
+will be sent to the guest only when the data has been reported as written by
+the storage subsystem.
+
+Writeback caching will report data writes as completed as soon as the data is
+present in the host page cache. This is safe as long as you trust your host.
+If your host crashes or loses power, then the guest may experience data
+corruption. When using the @option{-snapshot} option, writeback caching is
+used by default.
+
+The host page can be avoided entirely with @option{cache=none}. This will
+attempt to do disk IO directly to the guests memory. QEMU may still perform
+an internal copy of the data.
+
Instead of @option{-cdrom} you can use:
@example
qemu -drive file=file,index=2,media=cdrom
be needed to boot from old floppy disks.
@item -m @var{megs}
-Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.
+Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB. Optionally,
+a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
+gigabytes respectively.
+
+@item -cpu @var{model}
+Select CPU model (-cpu ? for list and additional feature selection)
@item -smp @var{n}
Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
available screen space. This makes the using QEMU in a dedicated desktop
workspace more convenient.
+@item -no-quit
+
+Disable SDL window close capability.
+
@item -full-screen
Start in full screen.
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 disk:file
-Mass storage device based on file
+@item disk:[format=@var{format}]:file
+Mass storage device based on file. The optional @var{format} argument
+will be used rather than detecting the format. Can be used to specifiy
+format=raw to avoid interpreting an untrusted format header.
@item host:bus.addr
Pass through the host device identified by bus.addr (Linux only).
Braille device. This will use BrlAPI to display the braille output on a real
or fake device.
+@item net:options
+Network adapter that supports CDC ethernet and RNDIS protocols.
+
@end table
@end table
/path/to/linux ubd0=/path/to/root_fs eth0=mcast
@end example
+@item -net vde[,vlan=@var{n}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
+Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
+listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
+and MODE @var{octalmode} to change default ownership and permissions for
+communication port. This option is available only if QEMU has been compiled
+with vde support enabled.
+
+Example:
+@example
+# launch vde switch
+vde_switch -F -sock /tmp/myswitch
+# launch QEMU instance
+qemu linux.img -net nic -net vde,sock=/tmp/myswitch
+@end example
+
@item -net none
Indicate that no network devices should be configured. It is used to
override the default configuration (@option{-net nic -net user}) which
@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
-VBE extensions (e.g. Windows XP) and if you want to use high
-resolution modes (>= 1280x1024x16) then you should use this option.
+@item -vga @var{type}
+Select type of VGA card to emulate. Valid values for @var{type} are
+@table @code
+@item cirrus
+Cirrus Logic GD5446 Video card. All Windows versions starting from
+Windows 95 should recognize and use this graphic card. For optimal
+performances, use 16 bit color depth in the guest and the host OS.
+(This one is the default)
+@item std
+Standard VGA card with Bochs VBE extensions. 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 vmware
+VMWare SVGA-II compatible adapter. Use it if you have sufficiently
+recent XFree86/XOrg server or Windows guest with a driver for this
+card.
+@end table
@item -no-acpi
Disable ACPI (Advanced Configuration and Power Interface) support. Use
@item -no-reboot
Exit instead of rebooting.
+@item -no-shutdown
+Don't exit QEMU on guest shutdown, but instead only stop the emulation.
+This allows for instance switching to monitor to commit changes to the
+disk image.
+
@item -loadvm file
Start right away with a saved state (@code{loadvm} in monitor)
Note that this allows guest direct access to the host filesystem,
so should only be used with trusted guest OS.
+
+@item -icount [N|auto]
+Enable virtual instruction counter. The virtual cpu will execute one
+instruction every 2^N ns of virtual time. If @code{auto} is specified
+then the virtual cpu speed will be automatically adjusted to keep virtual
+time within a few seconds of real time.
+
+Note that while this option can give deterministic behavior, it does not
+provide cycle accurate emulation. Modern CPUs contain superscalar out of
+order cores with complex cache hierarchies. The number of instructions
+executed often has little or no correlation with actual performance.
@end table
@c man end
@item sendkey @var{keys}
-Send @var{keys} to the emulator. Use @code{-} to press several keys
-simultaneously. Example:
+Send @var{keys} to the emulator. @var{keys} could be the name of the
+key or @code{#} followed by the raw value in either decimal or hexadecimal
+format. Use @code{-} to press several keys simultaneously. Example:
@example
sendkey ctrl-alt-f1
@end example
Reset the system.
+@item boot_set @var{bootdevicelist}
+
+Define new values for the boot device list. Those values will override
+the values specified on the command line through the @code{-boot} option.
+
+The values that can be specified here depend on the machine type, but are
+the same that can be specified in the @code{-boot} command line option.
+
@item usb_add @var{devname}
Add the USB device @var{devname}. For details of available devices see
* disk_images_snapshot_mode:: Snapshot mode
* vm_snapshots:: VM snapshots
* qemu_img_invocation:: qemu-img Invocation
+* qemu_nbd_invocation:: qemu-nbd Invocation
* host_drives:: Using host drives
* disk_images_fat_images:: Virtual FAT disk images
+* disk_images_nbd:: NBD access
@end menu
@node disk_images_quickstart
@include qemu-img.texi
+@node qemu_nbd_invocation
+@subsection @code{qemu-nbd} Invocation
+
+@include qemu-nbd.texi
+
@node host_drives
@subsection Using host drives
@item write to the FAT directory on the host system while accessing it with the guest system.
@end itemize
+@node disk_images_nbd
+@subsection NBD access
+
+QEMU can access directly to block device exported using the Network Block Device
+protocol.
+
+@example
+qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
+@end example
+
+If the NBD server is located on the same host, you can use an unix socket instead
+of an inet socket:
+
+@example
+qemu linux.img -hdb nbd:unix:/tmp/my_socket
+@end example
+
+In this case, the block device must be exported using qemu-nbd:
+
+@example
+qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
+@end example
+
+The use of qemu-nbd allows to share a disk between several guests:
+@example
+qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
+@end example
+
+and then you can use it with two guests:
+@example
+qemu linux1.img -hdb nbd:unix:/tmp/my_socket
+qemu linux2.img -hdb nbd:unix:/tmp/my_socket
+@end example
+
@node pcsys_network
@section Network emulation
@item braille
Braille device. This will use BrlAPI to display the braille output on a real
or fake device.
+@item net:@var{options}
+Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
+specifies NIC options as with @code{-net nic,}@var{options} (see description).
+For instance, user-mode networking can be used with
+@example
+qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
+@end example
+Currently this cannot be used in machines that support PCI NICs.
@end table
@node host_usb_devices
to provide high security. The password can be fairly easily brute-forced by
a client making repeat connections. For this reason, a VNC server using password
authentication should be restricted to only listen on the loopback interface
-or UNIX domain sockets. Password ayuthentication is requested with the @code{password}
+or UNIX domain sockets. Password authentication is requested with the @code{password}
option, and then once QEMU is running the password is set with the monitor. Until
the monitor is used to set the password all clients will be rejected.
@code{x/10i $cs*16+$eip} to dump the code at the PC position.
@end enumerate
+Advanced debugging options:
+
+The default single stepping behavior is step with the IRQs and timer service routines off. It is set this way because when gdb executes a single step it expects to advance beyond the current instruction. With the IRQs and and timer service routines on, a single step might jump into the one of the interrupt or exception vectors instead of executing the current instruction. This means you may hit the same breakpoint a number of times before executing the instruction gdb wants to have executed. Because there are rare circumstances where you want to single step into an interrupt vector the behavior can be controlled from GDB. There are three commands you can query and set the single step behavior:
+@table @code
+@item maintenance packet qqemu.sstepbits
+
+This will display the MASK bits used to control the single stepping IE:
+@example
+(gdb) maintenance packet qqemu.sstepbits
+sending: "qqemu.sstepbits"
+received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
+@end example
+@item maintenance packet qqemu.sstep
+
+This will display the current value of the mask used when single stepping IE:
+@example
+(gdb) maintenance packet qqemu.sstep
+sending: "qqemu.sstep"
+received: "0x7"
+@end example
+@item maintenance packet Qqemu.sstep=HEX_VALUE
+
+This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
+@example
+(gdb) maintenance packet Qqemu.sstep=0x5
+sending: "qemu.sstep=0x5"
+received: "OK"
+@end example
+@end table
+
@node pcsys_os_specific
@section Target OS specific information
@node Sparc32 System emulator
@section Sparc32 System emulator
-Use the executable @file{qemu-system-sparc} to simulate a SPARCstation
-5, SPARCstation 10, SPARCstation 20, SPARCserver 600MP (sun4m
-architecture), SPARCstation 2 (sun4c architecture), SPARCserver 1000,
-or SPARCcenter 2000 (sun4d architecture). The emulation is somewhat
-complete. SMP up to 16 CPUs is supported, but Linux limits the number
-of usable CPUs to 4.
+Use the executable @file{qemu-system-sparc} to simulate the following
+Sun4m architecture machines:
+@itemize @minus
+@item
+SPARCstation 4
+@item
+SPARCstation 5
+@item
+SPARCstation 10
+@item
+SPARCstation 20
+@item
+SPARCserver 600MP
+@item
+SPARCstation LX
+@item
+SPARCstation Voyager
+@item
+SPARCclassic
+@item
+SPARCbook
+@end itemize
+
+The emulation is somewhat complete. SMP up to 16 CPUs is supported,
+but Linux limits the number of usable CPUs to 4.
-QEMU emulates the following sun4m/sun4d peripherals:
+It's also possible to simulate a SPARCstation 2 (sun4c architecture),
+SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
+emulators are not usable yet.
+
+QEMU emulates the following sun4m/sun4c/sun4d peripherals:
@itemize @minus
@item
@item
Lance (Am7990) Ethernet
@item
-Non Volatile RAM M48T08
+Non Volatile RAM M48T02/M48T08
@item
Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
and power/reset logic
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 NetBSD, OpenBSD or
-Solaris kernels don't work.
+the QEMU web site. There are still issues with NetBSD and OpenBSD, but
+some kernel versions work. Please note that currently Solaris kernels
+don't work probably due to interface issues between OpenBIOS and
+Solaris.
@c man begin OPTIONS
-prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
@end example
-@item -M [SS-5|SS-10|SS-20|SS-600MP|SS-2|SS-1000|SS-2000]
+@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic|SPARCbook|SS-2|SS-1000|SS-2000]
Set the emulated machine type. Default is SS-5.
@node Sparc64 System emulator
@section Sparc64 System emulator
-Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
-The emulator is not usable for anything yet.
+Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
+(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
+Niagara (T1) machine. The emulator is not usable for anything yet, but
+it can launch some kernels.
-QEMU emulates the following sun4u peripherals:
+QEMU emulates the following peripherals:
@itemize @minus
@item
@item
PCI VGA compatible card with VESA Bochs Extensions
@item
+PS/2 mouse and keyboard
+@item
Non Volatile RAM M48T59
@item
PC-compatible serial ports
+@item
+2 PCI IDE interfaces with hard disk and CD-ROM support
+@item
+Floppy disk
@end itemize
+@c man begin OPTIONS
+
+The following options are specific to the Sparc64 emulation:
+
+@table @option
+
+@item -prom-env string
+
+Set OpenBIOS variables in NVRAM, for example:
+
+@example
+qemu-system-sparc64 -prom-env 'auto-boot?=false'
+@end example
+
+@item -M [sun4u|sun4v|Niagara]
+
+Set the emulated machine type. The default is sun4u.
+
+@end table
+
+@c man end
+
@node MIPS System emulator
@section MIPS System emulator
Three on-chip UARTs
@end itemize
+Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
+emulation supports the following elements:
+
+@itemize @minus
+@item
+Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
+@item
+RAM and non-volatile OneNAND Flash memories
+@item
+Display connected to EPSON remote framebuffer chip and OMAP on-chip
+display controller and a LS041y3 MIPI DBI-C controller
+@item
+TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
+driven through SPI bus
+@item
+National Semiconductor LM8323-controlled qwerty keyboard driven
+through I@math{^2}C bus
+@item
+Secure Digital card connected to OMAP MMC/SD host
+@item
+Three OMAP on-chip UARTs and on-chip STI debugging console
+@item
+Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
+TUSB6010 chip - only USB host mode is supported
+@item
+TI TMP105 temperature sensor driven through I@math{^2}C bus
+@item
+TI TWL92230C power management companion with an RTC on I@math{^2}C bus
+@item
+Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
+through CBUS
+@end itemize
+
The Luminary Micro Stellaris LM3S811EVB emulation includes the following
devices:
OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
@end itemize
+The Freecom MusicPal internet radio emulation includes the following
+elements:
+
+@itemize @minus
+@item
+Marvell MV88W8618 ARM core.
+@item
+32 MB RAM, 256 KB SRAM, 8 MB flash.
+@item
+Up to 2 16550 UARTs
+@item
+MV88W8xx8 Ethernet controller
+@item
+MV88W8618 audio controller, WM8750 CODEC and mixer
+@item
+128×64 display with brightness control
+@item
+2 buttons, 2 navigation wheels with button function
+@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.
* Supported Operating Systems ::
* Linux User space emulator::
* Mac OS X/Darwin User space emulator ::
+* BSD User space emulator ::
@end menu
@node Supported Operating Systems
Linux (referred as qemu-linux-user)
@item
Mac OS X/Darwin (referred as qemu-darwin-user)
+@item
+BSD (referred as qemu-bsd-user)
@end itemize
@node Linux User space emulator
@subsection Command line options
@example
-usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
+usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] program [arguments...]
@end example
@table @option
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
@item -s size
Set the x86 stack size in bytes (default=524288)
+@item -cpu model
+Select CPU model (-cpu ? for list and additional feature selection)
@end table
Debug options:
Activate log (logfile=/tmp/qemu.log)
@item -p pagesize
Act as if the host page size was 'pagesize' bytes
+@item -g port
+Wait gdb connection to port
@end table
Environment variables:
The binary format is detected automatically.
+@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
+
@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
(Sparc64 CPU, 32 bit ABI).
Act as if the host page size was 'pagesize' bytes
@end table
+@node BSD User space emulator
+@section BSD User space emulator
+
+@menu
+* BSD Status::
+* BSD Quick Start::
+* BSD Command line options::
+@end menu
+
+@node BSD Status
+@subsection BSD Status
+
+@itemize @minus
+@item
+target Sparc64 on Sparc64: Some trivial programs work.
+@end itemize
+
+@node BSD Quick Start
+@subsection Quick Start
+
+In order to launch a BSD process, QEMU needs the process executable
+itself and all the target dynamic libraries used by it.
+
+@itemize
+
+@item On Sparc64, you can just try to launch any process by using the native
+libraries:
+
+@example
+qemu-sparc64 /bin/ls
+@end example
+
+@end itemize
+
+@node BSD Command line options
+@subsection Command line options
+
+@example
+usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] 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)
+@item -bsd type
+Set the type of the emulated BSD Operating system. Valid values are
+FreeBSD, NetBSD and OpenBSD (default).
+@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