Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging

* Thread Sanitizer fixes (Alex)
* Coverity fixes (David)
* test-qht fixes (Emilio)
* QOM interface for info irq/info pic (Hervé)
* -rtc clock=rt fix (Junlian)
* mux chardev fixes (Marc-André)
* nicer report on death by signal (Michal)
* qemu-tech TLC (Paolo)
* MSI support for edu device (Peter)
* qemu-nbd --offset fix (Tomáš)

# gpg: Signature made Fri 07 Oct 2016 17:25:10 BST
# gpg:                using RSA key 0xBFFBD25F78C7AE83
# gpg: Good signature from "Paolo Bonzini <bonzini@gnu.org>"
# gpg:                 aka "Paolo Bonzini <pbonzini@redhat.com>"
# Primary key fingerprint: 46F5 9FBD 57D6 12E7 BFD4  E2F7 7E15 100C CD36 69B1
#      Subkey fingerprint: F133 3857 4B66 2389 866C  7682 BFFB D25F 78C7 AE83

* remotes/bonzini/tags/for-upstream: (39 commits)
  qemu-doc: merge qemu-tech and qemu-doc
  qemu-tech: rewrite some parts
  qemu-tech: reorganize content
  qemu-tech: move TCG test documentation to tests/tcg/README
  qemu-tech: move user mode emulation features from qemu-tech
  qemu-tech: document lazy condition code evaluation in cpu.h
  qemu-tech: move text from qemu-tech to tcg/README
  qemu-doc: drop installation and compilation notes
  qemu-doc: replace introduction with the one from the internals manual
  qemu-tech: drop index
  test-qht: perform lookups under rcu_read_lock
  qht: fix unlock-after-free segfault upon resizing
  qht: simplify qht_reset_size
  qemu-nbd: Shrink image size by specified offset
  qemu_kill_report: Report PID name too
  util: Introduce qemu_get_pid_name
  char: update read handler in all cases
  char: use a fixed idx for child muxed chr
  i8259: give ISA device when registering ISA ioports
  .travis.yml: add gcc sanitizer build
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

1 files changed, 72 insertions, 280 deletions

diff --git a/qemu-doc.texi b/qemu-doc.texi
index f37fd31..023c140 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -32,11 +32,10 @@
 
 @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
@@ -57,98 +56,69 @@
 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
+
+QEMU full system emulation has the following features:
+@itemize
+@item
+QEMU uses a full software MMU for maximum portability.
 
-If a precompiled package is available for your distribution - you just
-have to install it. Otherwise, see @ref{compilation}.
+@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
@@ -2660,6 +2630,7 @@ so should only be used with trusted guest OS.
 
 @menu
 * Supported Operating Systems ::
+* Features::
 * Linux User space emulator::
 * BSD User space emulator ::
 @end menu
@@ -2676,6 +2647,39 @@ Linux (referred as qemu-linux-user)
 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
 
@@ -2945,220 +2949,8 @@ Act as if the host page size was 'pagesize' bytes
 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