     [file version.texi not included]

Introduction
************

Features
========

QEMU is a FAST! processor emulator using dynamic translation to achieve good emulation speed.

QEMU has two operating modes:

  * 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.

  * 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 (https://www.winehq.org) or to ease cross-compilation and cross-debugging.

QEMU has the following features:

  * 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.

  * It is portable to several operating systems (GNU/Linux, *BSD, Mac OS X, Windows) and architectures.

  * It performs accurate software emulation of the FPU.

QEMU user mode emulation has the following features:

  * Generic Linux system call converter, including most ioctls.

  * clone() emulation using native CPU clone() to use Linux scheduler for threads.

  * Accurate signal handling by remapping host signals to target signals.

QEMU full system emulation has the following features:

  * QEMU uses a full software MMU for maximum portability.

  * 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.

  * 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).

  * Symmetric multiprocessing (SMP) support.  Currently, an in-kernel accelerator is required to use more than one host CPU for emulation.

QEMU System emulator
********************

     [file quickstart.texi not included]
     [file invocation.texi not included]
     [file keys.texi not included]
     [file mux-chardev.texi not included]
     [file monitor.texi not included]
     [file images.texi not included]
     [file net.texi not included]
     [file usb.texi not included]
     [file ivshmem.texi not included]
     [file linuxboot.texi not included]
     [file vnc-security.texi not included]
     [file tls.texi not included]
     [file gdb.texi not included]

QEMU System emulator targets
****************************

QEMU is a generic emulator and it emulates many machines. Most of the options are similar for all machines. Specific information about the various targets are mentioned in the following sections.

x86 (PC) System emulator
========================

Peripherals
-----------

The QEMU PC System emulator simulates the following peripherals:

  - i440FX host PCI bridge and PIIX3 PCI to ISA bridge

  - Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA extensions (hardware level, including all non standard modes).

  - PS/2 mouse and keyboard

  - 2 PCI IDE interfaces with hard disk and CD-ROM support

  - Floppy disk

  - PCI and ISA network adapters

  - Serial ports

  - IPMI BMC, either and internal or external one

  - Creative SoundBlaster 16 sound card

  - ENSONIQ AudioPCI ES1370 sound card

  - Intel 82801AA AC97 Audio compatible sound card

  - Intel HD Audio Controller and HDA codec

  - Adlib (OPL2) - Yamaha YM3812 compatible chip

  - Gravis Ultrasound GF1 sound card

  - CS4231A compatible sound card

  - PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.

SMP is supported with up to 255 CPUs.

QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL VGA BIOS.

QEMU uses YM3812 emulation by Tatsuyuki Satoh.

QEMU uses GUS emulation (GUSEMU32 http://www.deinmeister.de/gusemu/) by Tibor "TS" Schütz.

Note that, by default, GUS shares IRQ(7) with parallel ports and so QEMU must be told to not have parallel ports to have working GUS.

     qemu-system-x86_64 dos.img -soundhw gus -parallel none

Alternatively:

     qemu-system-x86_64 dos.img -device gus,irq=5

Or some other unclaimed IRQ.

CS4231A is the chip used in Windows Sound System and GUSMAX products

     [file cpu-models-x86.texi not included]

PowerPC System emulator
=======================

Use the executable qemu-system-ppc to simulate a complete 40P (PREP) or PowerMac PowerPC system.

QEMU emulates the following PowerMac peripherals:

  - UniNorth or Grackle PCI Bridge

  - PCI VGA compatible card with VESA Bochs Extensions

  - 2 PMAC IDE interfaces with hard disk and CD-ROM support

  - NE2000 PCI adapters

  - Non Volatile RAM

  - VIA-CUDA with ADB keyboard and mouse.

QEMU emulates the following 40P (PREP) peripherals:

  - PCI Bridge

  - PCI VGA compatible card with VESA Bochs Extensions

  - 2 IDE interfaces with hard disk and CD-ROM support

  - Floppy disk

  - PCnet network adapters

  - Serial port

  - PREP Non Volatile RAM

  - PC compatible keyboard and mouse.

Since version 0.9.1, QEMU uses OpenBIOS https://www.openbios.org/ for the g3beige and mac99 PowerMac and the 40p machines. 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.

The following options are specific to the PowerPC emulation:

-g WxH[xDEPTH]

     Set the initial VGA graphic mode. The default is 800x600x32.

-prom-env STRING

     Set OpenBIOS variables in NVRAM, for example:

          qemu-system-ppc -prom-env 'auto-boot?=false' \
           -prom-env 'boot-device=hd:2,\yaboot' \
           -prom-env 'boot-args=conf=hd:2,\yaboot.conf'

More information is available at http://perso.magic.fr/l_indien/qemu-ppc/.

Sparc32 System emulator
=======================

Use the executable qemu-system-sparc to simulate the following Sun4m architecture machines:

  - SPARCstation 4

  - SPARCstation 5

  - SPARCstation 10

  - SPARCstation 20

  - SPARCserver 600MP

  - SPARCstation LX

  - SPARCstation Voyager

  - SPARCclassic

  - SPARCbook

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 peripherals:

  - IOMMU

  - TCX or cgthree Frame buffer

  - Lance (Am7990) Ethernet

  - Non Volatile RAM M48T02/M48T08

  - Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard and power/reset logic

  - ESP SCSI controller with hard disk and CD-ROM support

  - Floppy drive (not on SS-600MP)

  - CS4231 sound device (only on SS-5, not working yet)

The number of peripherals is fixed in the architecture.  Maximum memory size depends on the machine type, for SS-5 it is 256MB and for others 2047MB.

Since version 0.8.2, QEMU uses OpenBIOS https://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.

A sample Linux 2.6 series kernel and ram disk image are available on the QEMU web site. There are still issues with NetBSD and OpenBSD, but most kernel versions work. Please note that currently older Solaris kernels don't work probably due to interface issues between OpenBIOS and Solaris.

The following options are specific to the Sparc32 emulation:

-g WxHx[xDEPTH]

     Set the initial graphics mode. For TCX, the default is 1024x768x8 with the option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option of 1152x900x8 for people who wish to use OBP.

-prom-env STRING

     Set OpenBIOS variables in NVRAM, for example:

          qemu-system-sparc -prom-env 'auto-boot?=false' \
           -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'

-M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]

     Set the emulated machine type. Default is SS-5.

Sparc64 System emulator
=======================

Use the executable qemu-system-sparc64 to simulate a Sun4u (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 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 http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2 and is able to boot the disk.s10hw2 Solaris image.

     qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
                         -nographic -m 256 \
                         -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2

QEMU emulates the following peripherals:

  - UltraSparc IIi APB PCI Bridge

  - PCI VGA compatible card with VESA Bochs Extensions

  - PS/2 mouse and keyboard

  - Non Volatile RAM M48T59

  - PC-compatible serial ports

  - 2 PCI IDE interfaces with hard disk and CD-ROM support

  - Floppy disk

The following options are specific to the Sparc64 emulation:

-prom-env STRING

     Set OpenBIOS variables in NVRAM, for example:

          qemu-system-sparc64 -prom-env 'auto-boot?=false'

-M [sun4u|sun4v|niagara]

     Set the emulated machine type. The default is sun4u.

MIPS System emulator
====================

Four executables cover simulation of 32 and 64-bit MIPS systems in both endian options, qemu-system-mips, qemu-system-mipsel qemu-system-mips64 and qemu-system-mips64el. Five different machine types are emulated:

  - A generic ISA PC-like machine "mips"

  - The MIPS Malta prototype board "malta"

  - An ACER Pica "pica61". This machine needs the 64-bit emulator.

  - MIPS emulator pseudo board "mipssim"

  - A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.

The generic emulation is supported by Debian 'Etch' and is able to install Debian into a virtual disk image. The following devices are emulated:

  - A range of MIPS CPUs, default is the 24Kf

  - PC style serial port

  - PC style IDE disk

  - NE2000 network card

The Malta emulation supports the following devices:

  - Core board with MIPS 24Kf CPU and Galileo system controller

  - PIIX4 PCI/USB/SMbus controller

  - The Multi-I/O chip's serial device

  - PCI network cards (PCnet32 and others)

  - Malta FPGA serial device

  - Cirrus (default) or any other PCI VGA graphics card

The Boston board emulation supports the following devices:

  - Xilinx FPGA, which includes a PCIe root port and an UART

  - Intel EG20T PCH connects the I/O peripherals, but only the SATA bus is emulated

The ACER Pica emulation supports:

  - MIPS R4000 CPU

  - PC-style IRQ and DMA controllers

  - PC Keyboard

  - IDE controller

The MIPS Magnum R4000 emulation supports:

  - MIPS R4000 CPU

  - PC-style IRQ controller

  - PC Keyboard

  - SCSI controller

  - G364 framebuffer

The Fulong 2E emulation supports:

  - Loongson 2E CPU

  - Bonito64 system controller as North Bridge

  - VT82C686 chipset as South Bridge

  - RTL8139D as a network card chipset

The mipssim pseudo board emulation provides an environment similar to what the proprietary MIPS emulator uses for running Linux. It supports:

  - A range of MIPS CPUs, default is the 24Kf

  - PC style serial port

  - MIPSnet network emulation

     [file cpu-models-mips.texi not included]

nanoMIPS System emulator
------------------------

Executable qemu-system-mipsel also covers simulation of 32-bit nanoMIPS system in little endian mode:

  - nanoMIPS I7200 CPU

Example of qemu-system-mipsel usage for nanoMIPS is shown below:

Download <disk_image_file> from https://mipsdistros.mips.com/LinuxDistro/nanomips/buildroot/index.html.

Download <kernel_image_file> from https://mipsdistros.mips.com/LinuxDistro/nanomips/kernels/v4.15.18-432-gb2eb9a8b07a1-20180627102142/index.html.

Start system emulation of Malta board with nanoMIPS I7200 CPU:

     qemu-system-mipsel -cpu I7200 -kernel <kernel_image_file> \
         -M malta -serial stdio -m <memory_size> -hda <disk_image_file> \
         -append "mem=256m@0x0 rw console=ttyS0 vga=cirrus vesa=0x111 root=/dev/sda"

ARM System emulator
===================

Use the executable qemu-system-arm to simulate a ARM machine. The ARM Integrator/CP board is emulated with the following devices:

  - ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU

  - Two PL011 UARTs

  - SMC 91c111 Ethernet adapter

  - PL110 LCD controller

  - PL050 KMI with PS/2 keyboard and mouse.

  - PL181 MultiMedia Card Interface with SD card.

The ARM Versatile baseboard is emulated with the following devices:

  - ARM926E, ARM1136 or Cortex-A8 CPU

  - PL190 Vectored Interrupt Controller

  - Four PL011 UARTs

  - SMC 91c111 Ethernet adapter

  - PL110 LCD controller

  - PL050 KMI with PS/2 keyboard and mouse.

  - PCI host bridge.  Note the emulated PCI bridge only provides access to PCI memory space.  It does not provide access to PCI IO space. This means some devices (eg. ne2k_pci NIC) are not usable, and others (eg. rtl8139 NIC) are only usable when the guest drivers use the memory mapped control registers.

  - PCI OHCI USB controller.

  - LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.

  - PL181 MultiMedia Card Interface with SD card.

Several variants of the ARM RealView baseboard are emulated, including the EB, PB-A8 and PBX-A9.  Due to interactions with the bootloader, only certain Linux kernel configurations work out of the box on these boards.

Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET disabled and expect 1024M RAM.

The following devices are emulated:

  - ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU

  - ARM AMBA Generic/Distributed Interrupt Controller

  - Four PL011 UARTs

  - SMC 91c111 or SMSC LAN9118 Ethernet adapter

  - PL110 LCD controller

  - PL050 KMI with PS/2 keyboard and mouse

  - PCI host bridge

  - PCI OHCI USB controller

  - LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices

  - PL181 MultiMedia Card Interface with SD card.

The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi" and "Terrier") emulation includes the following peripherals:

  - Intel PXA270 System-on-chip (ARM V5TE core)

  - NAND Flash memory

  - IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"

  - On-chip OHCI USB controller

  - On-chip LCD controller

  - On-chip Real Time Clock

  - TI ADS7846 touchscreen controller on SSP bus

  - Maxim MAX1111 analog-digital converter on I^2C bus

  - GPIO-connected keyboard controller and LEDs

  - Secure Digital card connected to PXA MMC/SD host

  - Three on-chip UARTs

  - WM8750 audio CODEC on I^2C and I^2S busses

The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the following elements:

  - Texas Instruments OMAP310 System-on-chip (ARM 925T core)

  - ROM and RAM memories (ROM firmware image can be loaded with -option-rom)

  - On-chip LCD controller

  - On-chip Real Time Clock

  - TI TSC2102i touchscreen controller / analog-digital converter / Audio CODEC, connected through MicroWire and I^2S busses

  - GPIO-connected matrix keypad

  - Secure Digital card connected to OMAP MMC/SD host

  - Three on-chip UARTs

Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48) emulation supports the following elements:

  - Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)

  - RAM and non-volatile OneNAND Flash memories

  - Display connected to EPSON remote framebuffer chip and OMAP on-chip display controller and a LS041y3 MIPI DBI-C controller

  - TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers driven through SPI bus

  - National Semiconductor LM8323-controlled qwerty keyboard driven through I^2C bus

  - Secure Digital card connected to OMAP MMC/SD host

  - Three OMAP on-chip UARTs and on-chip STI debugging console

  - Mentor Graphics "Inventra" dual-role USB controller embedded in a TI TUSB6010 chip - only USB host mode is supported

  - TI TMP105 temperature sensor driven through I^2C bus

  - TI TWL92230C power management companion with an RTC on I^2C bus

  - Nokia RETU and TAHVO multi-purpose chips with an RTC, connected through CBUS

The Luminary Micro Stellaris LM3S811EVB emulation includes the following devices:

  - Cortex-M3 CPU core.

  - 64k Flash and 8k SRAM.

  - Timers, UARTs, ADC and I^2C interface.

  - OSRAM Pictiva 96x16 OLED with SSD0303 controller on I^2C bus.

The Luminary Micro Stellaris LM3S6965EVB emulation includes the following devices:

  - Cortex-M3 CPU core.

  - 256k Flash and 64k SRAM.

  - Timers, UARTs, ADC, I^2C and SSI interfaces.

  - OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.

The Freecom MusicPal internet radio emulation includes the following elements:

  - Marvell MV88W8618 ARM core.

  - 32 MB RAM, 256 KB SRAM, 8 MB flash.

  - Up to 2 16550 UARTs

  - MV88W8xx8 Ethernet controller

  - MV88W8618 audio controller, WM8750 CODEC and mixer

  - 128×64 display with brightness control

  - 2 buttons, 2 navigation wheels with button function

The Siemens SX1 models v1 and v2 (default) basic emulation. The emulation includes the following elements:

  - Texas Instruments OMAP310 System-on-chip (ARM 925T core)

  - ROM and RAM memories (ROM firmware image can be loaded with -pflash) V1 1 Flash of 16MB and 1 Flash of 8MB V2 1 Flash of 32MB

  - On-chip LCD controller

  - On-chip Real Time Clock

  - Secure Digital card connected to OMAP MMC/SD host

  - Three on-chip UARTs

A Linux 2.6 test image is available on the QEMU web site. More information is available in the QEMU mailing-list archive.

The following options are specific to the ARM emulation:

-semihosting
     Enable semihosting syscall emulation.

     On ARM this implements the "Angel" interface.

     Note that this allows guest direct access to the host filesystem, so should only be used with trusted guest OS.

ColdFire System emulator
========================

Use the executable qemu-system-m68k to simulate a ColdFire machine. The emulator is able to boot a uClinux kernel.

The M5208EVB emulation includes the following devices:

  - MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).

  - Three Two on-chip UARTs.

  - Fast Ethernet Controller (FEC)

The AN5206 emulation includes the following devices:

  - MCF5206 ColdFire V2 Microprocessor.

  - Two on-chip UARTs.

The following options are specific to the ColdFire emulation:

-semihosting
     Enable semihosting syscall emulation.

     On M68K this implements the "ColdFire GDB" interface used by libgloss.

     Note that this allows guest direct access to the host filesystem, so should only be used with trusted guest OS.

Cris System emulator
====================

TODO

Microblaze System emulator
==========================

TODO

SH4 System emulator
===================

TODO

Xtensa System emulator
======================

Two executables cover simulation of both Xtensa endian options, qemu-system-xtensa and qemu-system-xtensaeb. Two different machine types are emulated:

  - Xtensa emulator pseudo board "sim"

  - Avnet LX60/LX110/LX200 board

The sim pseudo board emulation provides an environment similar to one provided by the proprietary Tensilica ISS. It supports:

  - A range of Xtensa CPUs, default is the DC232B

  - Console and filesystem access via semihosting calls

The Avnet LX60/LX110/LX200 emulation supports:

  - A range of Xtensa CPUs, default is the DC232B

  - 16550 UART

  - OpenCores 10/100 Mbps Ethernet MAC

The following options are specific to the Xtensa emulation:

-semihosting
     Enable semihosting syscall emulation.

     Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select. Tensilica baremetal libc for ISS and linux platform "sim" use this interface.

     Note that this allows guest direct access to the host filesystem, so should only be used with trusted guest OS.

System requirements
*******************

KVM kernel module
=================

On x86_64 hosts, the default set of CPU features enabled by the KVM accelerator require the host to be running Linux v4.5 or newer.

The OpteronG[345] CPU models require KVM support for RDTSCP, which was added with Linux 4.5 which is supported by the major distros. And even if RHEL7 has kernel 3.10, KVM there has the required functionality there to make it close to a 4.5 or newer kernel.

     [file security.texi not included]

     [file qemu-tech.texi not included]

     [file qemu-deprecated.texi not included]

     [file build-platforms.texi not included]

     [file license.texi not included]

Index
*****

Concept Index
=============

This is the main index. Should we combine all keywords in one index? TODO

Function Index
==============

This index could be used for command line options and monitor functions.

Keystroke Index
===============

This is a list of all keystrokes which have a special function in system emulation.

Data Type Index
===============

This index could be used for qdev device names and options.