@menu
* Introduction::
-* Installation::
* QEMU PC System emulator::
* QEMU System emulator for non PC targets::
* QEMU User space emulator::
-* compilation:: Compilation from the sources
+* Implementation notes::
* License::
* Index::
@end menu
QEMU is a FAST! processor emulator using dynamic translation to
achieve good emulation speed.
+@cindex operating modes
QEMU has two operating modes:
@itemize
-@cindex operating modes
-
-@item
@cindex system emulation
-Full system emulation. In this mode, QEMU emulates a full system (for
+@item Full system emulation. In this mode, QEMU emulates a full system (for
example a PC), including one or several processors and various
peripherals. It can be used to launch different Operating Systems
without rebooting the PC or to debug system code.
-@item
@cindex user mode emulation
-User mode emulation. In this mode, QEMU can launch
+@item 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.
@end itemize
-QEMU can run without a host kernel driver and yet gives acceptable
-performance.
+QEMU has the following features:
-For system emulation, the following hardware targets are supported:
@itemize
-@cindex emulated target systems
-@cindex supported target systems
-@item PC (x86 or x86_64 processor)
-@item ISA PC (old style PC without PCI bus)
-@item PREP (PowerPC processor)
-@item G3 Beige PowerMac (PowerPC processor)
-@item Mac99 PowerMac (PowerPC processor, in progress)
-@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
-@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 ARM Versatile baseboard (ARM)
-@item ARM RealView Emulation/Platform baseboard (ARM)
-@item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
-@item Luminary Micro LM3S811EVB (ARM Cortex-M3)
-@item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
-@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)
-@item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
-@item Siemens SX1 smartphone (OMAP310 processor)
-@item AXIS-Devboard88 (CRISv32 ETRAX-FS).
-@item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).
-@item Avnet LX60/LX110/LX200 boards (Xtensa)
-@end itemize
+@item QEMU can run without a host kernel driver and yet gives acceptable
+performance. It uses dynamic translation to native code for reasonable speed,
+with support for self-modifying code and precise exceptions.
-@cindex supported user mode targets
-For user emulation, x86 (32 and 64 bit), PowerPC (32 and 64 bit),
-ARM, MIPS (32 bit only), Sparc (32 and 64 bit),
-Alpha, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
+@item It is portable to several operating systems (GNU/Linux, *BSD, Mac OS X,
+Windows) and architectures.
-@node Installation
-@chapter Installation
+@item It performs accurate software emulation of the FPU.
+@end itemize
-If you want to compile QEMU yourself, see @ref{compilation}.
+QEMU user mode emulation has the following features:
+@itemize
+@item Generic Linux system call converter, including most ioctls.
-@menu
-* install_linux:: Linux
-* install_windows:: Windows
-* install_mac:: Macintosh
-@end menu
+@item clone() emulation using native CPU clone() to use Linux scheduler for threads.
-@node install_linux
-@section Linux
-@cindex installation (Linux)
+@item Accurate signal handling by remapping host signals to target signals.
+@end itemize
-If a precompiled package is available for your distribution - you just
-have to install it. Otherwise, see @ref{compilation}.
+QEMU full system emulation has the following features:
+@itemize
+@item
+QEMU uses a full software MMU for maximum portability.
-@node install_windows
-@section Windows
-@cindex installation (Windows)
+@item
+QEMU can optionally use an in-kernel accelerator, like kvm. The accelerators
+execute most of the guest code natively, while
+continuing to emulate the rest of the machine.
-Download the experimental binary installer at
-@url{http://www.free.oszoo.org/@/download.html}.
-TODO (no longer available)
+@item
+Various hardware devices can be emulated and in some cases, host
+devices (e.g. serial and parallel ports, USB, drives) can be used
+transparently by the guest Operating System. Host device passthrough
+can be used for talking to external physical peripherals (e.g. a
+webcam, modem or tape drive).
-@node install_mac
-@section Mac OS X
+@item
+Symmetric multiprocessing (SMP) support. Currently, an in-kernel
+accelerator is required to use more than one host CPU for emulation.
+
+@end itemize
-Download the experimental binary installer at
-@url{http://www.free.oszoo.org/@/download.html}.
-TODO (no longer available)
@node QEMU PC System emulator
@chapter QEMU PC System emulator
File name of a base image (see @option{create} subcommand).
@item compat6
Create a VMDK version 6 image (instead of version 4)
+@item hwversion
+Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
+if hwversion is specified.
@item subformat
Specifies which VMDK subformat to use. Valid options are
@code{monolithicSparse} (default),
@node disk_images_gluster
@subsection GlusterFS disk images
-GlusterFS is an user space distributed file system.
+GlusterFS is a user space distributed file system.
You can boot from the GlusterFS disk image with the command:
@example
-qemu-system-x86_64 -drive file=gluster[+@var{transport}]://[@var{server}[:@var{port}]]/@var{volname}/@var{image}[?socket=...]
+URI:
+qemu-system-x86_64 -drive file=gluster[+@var{type}]://[@var{host}[:@var{port}]]/@var{volume}/@var{path}
+ [?socket=...][,file.debug=9][,file.logfile=...]
+
+JSON:
+qemu-system-x86_64 'json:@{"driver":"qcow2",
+ "file":@{"driver":"gluster",
+ "volume":"testvol","path":"a.img","debug":9,"logfile":"...",
+ "server":[@{"type":"tcp","host":"...","port":"..."@},
+ @{"type":"unix","socket":"..."@}]@}@}'
@end example
@var{gluster} is the protocol.
-@var{transport} specifies the transport type used to connect to gluster
+@var{type} specifies the transport type used to connect to gluster
management daemon (glusterd). Valid transport types are
-tcp, unix and rdma. If a transport type isn't specified, then tcp
-type is assumed.
+tcp and unix. In the URI form, if a transport type isn't specified,
+then tcp type is assumed.
-@var{server} specifies the server where the volume file specification for
-the given volume resides. This can be either hostname, ipv4 address
-or ipv6 address. ipv6 address needs to be within square brackets [ ].
-If transport type is unix, then @var{server} field should not be specified.
+@var{host} specifies the server where the volume file specification for
+the given volume resides. This can be either a hostname or an ipv4 address.
+If transport type is unix, then @var{host} field should not be specified.
Instead @var{socket} field needs to be populated with the path to unix domain
socket.
@var{port} is the port number on which glusterd is listening. This is optional
-and if not specified, QEMU will send 0 which will make gluster to use the
-default port. If the transport type is unix, then @var{port} should not be
-specified.
+and if not specified, it defaults to port 24007. If the transport type is unix,
+then @var{port} should not be specified.
+
+@var{volume} is the name of the gluster volume which contains the disk image.
+
+@var{path} is the path to the actual disk image that resides on gluster volume.
+
+@var{debug} is the logging level of the gluster protocol driver. Debug levels
+are 0-9, with 9 being the most verbose, and 0 representing no debugging output.
+The default level is 4. The current logging levels defined in the gluster source
+are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning,
+6 - Notice, 7 - Info, 8 - Debug, 9 - Trace
+
+@var{logfile} is a commandline option to mention log file path which helps in
+logging to the specified file and also help in persisting the gfapi logs. The
+default is stderr.
+
-@var{volname} is the name of the gluster volume which contains the disk image.
-@var{image} is the path to the actual disk image that resides on gluster volume.
You can create a GlusterFS disk image with the command:
@example
-qemu-img create gluster://@var{server}/@var{volname}/@var{image} @var{size}
+qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size}
@end example
Examples
qemu-system-x86_64 -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
qemu-system-x86_64 -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
qemu-system-x86_64 -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
+qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
+qemu-system-x86_64 'json:@{"driver":"qcow2",
+ "file":@{"driver":"gluster",
+ "volume":"testvol","path":"a.img",
+ "debug":9,"logfile":"/var/log/qemu-gluster.log",
+ "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
+ @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
+qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
+ file.debug=9,file.logfile=/var/log/qemu-gluster.log,
+ file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
+ file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
@end example
@node disk_images_ssh
@subsection Inter-VM Shared Memory device
-With KVM enabled on a Linux host, a shared memory device is available. Guests
-map a POSIX shared memory region into the guest as a PCI device that enables
-zero-copy communication to the application level of the guests. The basic
-syntax is:
+On Linux hosts, a shared memory device is available. The basic syntax
+is:
@example
-qemu-system-i386 -device ivshmem,size=@var{size},shm=@var{shm-name}
+qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem}
+@end example
+
+where @var{hostmem} names a host memory backend. For a POSIX shared
+memory backend, use something like
+
+@example
+-object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
@end example
If desired, interrupts can be sent between guest VMs accessing the same shared
ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}
# Then start your qemu instances with matching arguments
-qemu-system-i386 -device ivshmem,size=@var{shm-size},vectors=@var{vectors},chardev=@var{id}
- [,msi=on][,ioeventfd=on][,role=peer|master]
+qemu-system-x86_64 -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
-chardev socket,path=@var{path},id=@var{id}
@end example
When using the server, the guest will be assigned a VM ID (>=0) that allows guests
using the same server to communicate via interrupts. Guests can read their
-VM ID from a device register (see example code). Since receiving the shared
-memory region from the server is asynchronous, there is a (small) chance the
-guest may boot before the shared memory is attached. To allow an application
-to ensure shared memory is attached, the VM ID register will return -1 (an
-invalid VM ID) until the memory is attached. Once the shared memory is
-attached, the VM ID will return the guest's valid VM ID. With these semantics,
-the guest application can check to ensure the shared memory is attached to the
-guest before proceeding.
-
-The @option{role} argument can be set to either master or peer and will affect
-how the shared memory is migrated. With @option{role=master}, the guest will
-copy the shared memory on migration to the destination host. With
-@option{role=peer}, the guest will not be able to migrate with the device attached.
-With the @option{peer} case, the device should be detached and then reattached
-after migration using the PCI hotplug support.
+VM ID from a device register (see ivshmem-spec.txt).
+
+@subsubsection Migration with ivshmem
+
+With device property @option{master=on}, the guest will copy the shared
+memory on migration to the destination host. With @option{master=off},
+the guest will not be able to migrate with the device attached. In the
+latter case, the device should be detached and then reattached after
+migration using the PCI hotplug support.
+
+At most one of the devices sharing the same memory can be master. The
+master must complete migration before you plug back the other devices.
@subsubsection ivshmem and hugepages
a memory backend that has hugepage support:
@example
-qemu-system-i386 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
- -device ivshmem,x-memdev=mb1
+qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
+ -device ivshmem-plain,memdev=mb1
@end example
ivshmem-server also supports hugepages mount points with the
(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
Niagara (T1) machine. The Sun4u emulator is mostly complete, being
able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
-Sun4v and Niagara emulators are still a work in progress.
+Sun4v emulator is still a work in progress.
+
+The Niagara T1 emulator makes use of firmware and OS binaries supplied in the S10image/ directory
+of the OpenSPARC T1 project @url{http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2}
+and is able to boot the disk.s10hw2 Solaris image.
+@example
+qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
+ -nographic -m 256 \
+ -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
+@end example
+
QEMU emulates the following peripherals:
qemu-system-sparc64 -prom-env 'auto-boot?=false'
@end example
-@item -M [sun4u|sun4v|Niagara]
+@item -M [sun4u|sun4v|niagara]
Set the emulated machine type. The default is sun4u.
@menu
* Supported Operating Systems ::
+* Features::
* Linux User space emulator::
* BSD User space emulator ::
@end menu
BSD (referred as qemu-bsd-user)
@end itemize
+@node Features
+@section Features
+
+QEMU user space emulation has the following notable features:
+
+@table @strong
+@item System call translation:
+QEMU includes a generic system call translator. This means that
+the parameters of the system calls can be converted to fix
+endianness and 32/64-bit mismatches between hosts and targets.
+IOCTLs can be converted too.
+
+@item POSIX signal handling:
+QEMU can redirect to the running program all signals coming from
+the host (such as @code{SIGALRM}), as well as synthesize signals from
+virtual CPU exceptions (for example @code{SIGFPE} when the program
+executes a division by zero).
+
+QEMU relies on the host kernel to emulate most signal system
+calls, for example to emulate the signal mask. On Linux, QEMU
+supports both normal and real-time signals.
+
+@item Threading:
+On Linux, QEMU can emulate the @code{clone} syscall and create a real
+host thread (with a separate virtual CPU) for each emulated thread.
+Note that not all targets currently emulate atomic operations correctly.
+x86 and ARM use a global lock in order to preserve their semantics.
+@end table
+
+QEMU was conceived so that ultimately it can emulate itself. Although
+it is not very useful, it is an important test to show the power of the
+emulator.
+
@node Linux User space emulator
@section Linux User space emulator
@command{qemu-mips} TODO.
@command{qemu-mipsel} TODO.
+@cindex user mode (NiosII)
+@command{qemu-nios2} TODO.
+
@cindex user mode (PowerPC)
@command{qemu-ppc64abi32} TODO.
@command{qemu-ppc64} TODO.
Run the emulation in single step mode.
@end table
-@node compilation
-@chapter Compilation from the sources
-
-@menu
-* Linux/Unix::
-* Windows::
-* Cross compilation for Windows with Linux::
-* Mac OS X::
-* Make targets::
-@end menu
-
-@node Linux/Unix
-@section Linux/Unix
-
-@subsection Compilation
-
-First you must decompress the sources:
-@example
-cd /tmp
-tar zxvf qemu-x.y.z.tar.gz
-cd qemu-x.y.z
-@end example
-
-Then you configure QEMU and build it (usually no options are needed):
-@example
-./configure
-make
-@end example
-
-Then type as root user:
-@example
-make install
-@end example
-to install QEMU in @file{/usr/local}.
-
-@node Windows
-@section Windows
-
-@itemize
-@item Install the current versions of MSYS and MinGW from
-@url{http://www.mingw.org/}. You can find detailed installation
-instructions in the download section and the FAQ.
-
-@item Download
-the MinGW development library of SDL 1.2.x
-(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
-@url{http://www.libsdl.org}. Unpack it in a temporary place and
-edit the @file{sdl-config} script so that it gives the
-correct SDL directory when invoked.
-
-@item Install the MinGW version of zlib and make sure
-@file{zlib.h} and @file{libz.dll.a} are in
-MinGW's default header and linker search paths.
-
-@item Extract the current version of QEMU.
-@item Start the MSYS shell (file @file{msys.bat}).
-
-@item Change to the QEMU directory. Launch @file{./configure} and
-@file{make}. If you have problems using SDL, verify that
-@file{sdl-config} can be launched from the MSYS command line.
-
-@item You can install QEMU in @file{Program Files/QEMU} by typing
-@file{make install}. Don't forget to copy @file{SDL.dll} in
-@file{Program Files/QEMU}.
-
-@end itemize
-
-@node Cross compilation for Windows with Linux
-@section Cross compilation for Windows with Linux
-
-@itemize
-@item
-Install the MinGW cross compilation tools available at
-@url{http://www.mingw.org/}.
-
-@item Download
-the MinGW development library of SDL 1.2.x
-(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
-@url{http://www.libsdl.org}. Unpack it in a temporary place and
-edit the @file{sdl-config} script so that it gives the
-correct SDL directory when invoked. Set up the @code{PATH} environment
-variable so that @file{sdl-config} can be launched by
-the QEMU configuration script.
-
-@item Install the MinGW version of zlib and make sure
-@file{zlib.h} and @file{libz.dll.a} are in
-MinGW's default header and linker search paths.
-
-@item
-Configure QEMU for Windows cross compilation:
-@example
-PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
-@end example
-The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
-MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
-We set the @code{PATH} environment variable to ensure the MinGW version of @file{sdl-config} is used and
-use --cross-prefix to specify the name of the cross compiler.
-You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/QEMU}.
-
-Under Fedora Linux, you can run:
-@example
-yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
-@end example
-to get a suitable cross compilation environment.
-
-@item You can install QEMU in the installation directory by typing
-@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
-installation directory.
-
-@end itemize
-
-Wine can be used to launch the resulting qemu-system-i386.exe
-and all other qemu-system-@var{target}.exe compiled for Win32.
-
-@node Mac OS X
-@section Mac OS X
-
-System Requirements:
-@itemize
-@item Mac OS 10.5 or higher
-@item The clang compiler shipped with Xcode 4.2 or higher,
-or GCC 4.3 or higher
-@end itemize
-
-Additional Requirements (install in order):
-@enumerate
-@item libffi: @uref{https://sourceware.org/libffi/}
-@item gettext: @uref{http://www.gnu.org/software/gettext/}
-@item glib: @uref{http://ftp.gnome.org/pub/GNOME/sources/glib/}
-@item pkg-config: @uref{http://www.freedesktop.org/wiki/Software/pkg-config/}
-@item autoconf: @uref{http://www.gnu.org/software/autoconf/autoconf.html}
-@item automake: @uref{http://www.gnu.org/software/automake/}
-@item pixman: @uref{http://www.pixman.org/}
-@end enumerate
-
-* You may find it easiest to get these from a third-party packager
-such as Homebrew, Macports, or Fink.
-
-After downloading the QEMU source code, double-click it to expand it.
-
-Then configure and make QEMU:
-@example
-./configure
-make
-@end example
-
-If you have a recent version of Mac OS X (OSX 10.7 or better
-with Xcode 4.2 or better) we recommend building QEMU with the
-default compiler provided by Apple, for your version of Mac OS X
-(which will be 'clang'). The configure script will
-automatically pick this.
-
-Note: If after the configure step you see a message like this:
-@example
-ERROR: Your compiler does not support the __thread specifier for
- Thread-Local Storage (TLS). Please upgrade to a version that does.
-@end example
-you may have to build your own version of gcc from source. Expect that to take
-several hours. More information can be found here:
-@uref{https://gcc.gnu.org/install/} @*
-
-These are some of the third party binaries of gcc available for download:
-@itemize
-@item Homebrew: @uref{http://brew.sh/}
-@item @uref{https://www.litebeam.net/gcc/gcc_472.pkg}
-@item @uref{http://www.macports.org/ports.php?by=name&substr=gcc}
-@end itemize
-
-You can have several versions of GCC on your system. To specify a certain version,
-use the --cc and --cxx options.
-@example
-./configure --cxx=<path of your c++ compiler> --cc=<path of your c compiler> <other options>
-@end example
-
-@node Make targets
-@section Make targets
-
-@table @code
-
-@item make
-@item make all
-Make everything which is typically needed.
-
-@item install
-TODO
-
-@item install-doc
-TODO
-
-@item make clean
-Remove most files which were built during make.
-
-@item make distclean
-Remove everything which was built during make.
-
-@item make dvi
-@item make html
-@item make info
-@item make pdf
-Create documentation in dvi, html, info or pdf format.
-
-@item make cscope
-TODO
-
-@item make defconfig
-(Re-)create some build configuration files.
-User made changes will be overwritten.
-
-@item tar
-@item tarbin
-TODO
-
-@end table
+@include qemu-tech.texi
@node License
@appendix License
projects / mirror_qemu.git / blobdiff