@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.
+
+@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.
-@node install_windows
-@section Windows
-@cindex installation (Windows)
+@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).
-Download the experimental binary installer at
-@url{http://www.free.oszoo.org/@/download.html}.
-TODO (no longer available)
+@item
+Symmetric multiprocessing (SMP) support. Currently, an in-kernel
+accelerator is required to use more than one host CPU for emulation.
-@node install_mac
-@section Mac OS X
+@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
using the same server to communicate via interrupts. Guests can read their
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
Instead of specifying the <shm size> using POSIX shm, you may specify
(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