docs/about/emulation.rst

   1 Emulation
   2 =========
   3
   4 QEMU's Tiny Code Generator (TCG) provides the ability to emulate a
   5 number of CPU architectures on any supported host platform. Both
   6 :ref:`System Emulation` and :ref:`User Mode Emulation` are supported
   7 depending on the guest architecture.
   8
   9 .. list-table:: Supported Guest Architectures for Emulation
  10   :widths: 30 10 10 50
  11   :header-rows: 1
  12
  13   * - Architecture (qemu name)
  14     - System
  15     - User
  16     - Notes
  17   * - Alpha
  18     - Yes
  19     - Yes
  20     - Legacy 64 bit RISC ISA developed by DEC
  21   * - Arm (arm, aarch64)
  22     - :ref:`Yes<ARM-System-emulator>`
  23     - Yes
  24     - Wide range of features, see :ref:`Arm Emulation` for details
  25   * - AVR
  26     - :ref:`Yes<AVR-System-emulator>`
  27     - No
  28     - 8 bit micro controller, often used in maker projects
  29   * - Cris
  30     - Yes
  31     - Yes
  32     - Embedded RISC chip developed by AXIS
  33   * - Hexagon
  34     - No
  35     - Yes
  36     - Family of DSPs by Qualcomm
  37   * - PA-RISC (hppa)
  38     - Yes
  39     - Yes
  40     - A legacy RISC system used in HP's old minicomputers
  41   * - x86 (i386, x86_64)
  42     - :ref:`Yes<QEMU-PC-System-emulator>`
  43     - Yes
  44     - The ubiquitous desktop PC CPU architecture, 32 and 64 bit.
  45   * - Loongarch
  46     - Yes
  47     - Yes
  48     - A MIPS-like 64bit RISC architecture developed in China
  49   * - m68k
  50     - :ref:`Yes<ColdFire-System-emulator>`
  51     - Yes
  52     - Motorola 68000 variants and ColdFire
  53   * - Microblaze
  54     - Yes
  55     - Yes
  56     - RISC based soft-core by Xilinx
  57   * - MIPS (mips*)
  58     - :ref:`Yes<MIPS-System-emulator>`
  59     - Yes
  60     - Venerable RISC architecture originally out of Stanford University
  61   * - Nios2
  62     - Yes
  63     - Yes
  64     - 32 bit embedded soft-core by Altera
  65   * - OpenRISC
  66     - :ref:`Yes<OpenRISC-System-emulator>`
  67     - Yes
  68     - Open source RISC architecture developed by the OpenRISC community
  69   * - Power (ppc, ppc64)
  70     - :ref:`Yes<PowerPC-System-emulator>`
  71     - Yes
  72     - A general purpose RISC architecture now managed by IBM
  73   * - RISC-V
  74     - :ref:`Yes<RISC-V-System-emulator>`
  75     - Yes
  76     - An open standard RISC ISA maintained by RISC-V International
  77   * - RX
  78     - :ref:`Yes<RX-System-emulator>`
  79     - No
  80     - A 32 bit micro controller developed by Renesas
  81   * - s390x
  82     - :ref:`Yes<s390x-System-emulator>`
  83     - Yes
  84     - A 64 bit CPU found in IBM's System Z mainframes
  85   * - sh4
  86     - Yes
  87     - Yes
  88     - A 32 bit RISC embedded CPU developed by Hitachi
  89   * - SPARC (sparc, sparc64)
  90     - :ref:`Yes<Sparc32-System-emulator>`
  91     - Yes
  92     - A RISC ISA originally developed by Sun Microsystems
  93   * - Tricore
  94     - Yes
  95     - No
  96     - A 32 bit RISC/uController/DSP developed by Infineon
  97   * - Xtensa
  98     - :ref:`Yes<Xtensa-System-emulator>`
  99     - Yes
 100     - A configurable 32 bit soft core now owned by Cadence
 101
 102 A number of features are only available when running under
 103 emulation including :ref:`Record/Replay<replay>` and :ref:`TCG Plugins`.
 104
 105 .. _Semihosting:
 106
 107 Semihosting
 108 -----------
 109
 110 Semihosting is a feature defined by the owner of the architecture to
 111 allow programs to interact with a debugging host system. On real
 112 hardware this is usually provided by an In-circuit emulator (ICE)
 113 hooked directly to the board. QEMU's implementation allows for
 114 semihosting calls to be passed to the host system or via the
 115 ``gdbstub``.
 116
 117 Generally semihosting makes it easier to bring up low level code before a
 118 more fully functional operating system has been enabled. On QEMU it
 119 also allows for embedded micro-controller code which typically doesn't
 120 have a full libc to be run as "bare-metal" code under QEMU's user-mode
 121 emulation. It is also useful for writing test cases and indeed a
 122 number of compiler suites as well as QEMU itself use semihosting calls
 123 to exit test code while reporting the success state.
 124
 125 Semihosting is only available using TCG emulation. This is because the
 126 instructions to trigger a semihosting call are typically reserved
 127 causing most hypervisors to trap and fault on them.
 128
 129 .. warning::
 130    Semihosting inherently bypasses any isolation there may be between
 131    the guest and the host. As a result a program using semihosting can
 132    happily trash your host system. You should only ever run trusted
 133    code with semihosting enabled.
 134
 135 Redirection
 136 ~~~~~~~~~~~
 137
 138 Semihosting calls can be re-directed to a (potentially remote) gdb
 139 during debugging via the :ref:`gdbstub<GDB usage>`. Output to the
 140 semihosting console is configured as a ``chardev`` so can be
 141 redirected to a file, pipe or socket like any other ``chardev``
 142 device.
 143
 144 Supported Targets
 145 ~~~~~~~~~~~~~~~~~
 146
 147 Most targets offer similar semihosting implementations with some
 148 minor changes to define the appropriate instruction to encode the
 149 semihosting call and which registers hold the parameters. They tend to
 150 presents a simple POSIX-like API which allows your program to read and
 151 write files, access the console and some other basic interactions.
 152
 153 For full details of the ABI for a particular target, and the set of
 154 calls it provides, you should consult the semihosting specification
 155 for that architecture.
 156
 157 .. note::
 158    QEMU makes an implementation decision to implement all file
 159    access in ``O_BINARY`` mode. The user-visible effect of this is
 160    regardless of the text/binary mode the program sets QEMU will
 161    always select a binary mode ensuring no line-terminator conversion
 162    is performed on input or output. This is because gdb semihosting
 163    support doesn't make the distinction between the modes and
 164    magically processing line endings can be confusing.
 165
 166 .. list-table:: Guest Architectures supporting Semihosting
 167   :widths: 10 10 80
 168   :header-rows: 1
 169
 170   * - Architecture
 171     - Modes
 172     - Specification
 173   * - Arm
 174     - System and User-mode
 175     - https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst
 176   * - m68k
 177     - System
 178     - https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=libgloss/m68k/m68k-semi.txt;hb=HEAD
 179   * - MIPS
 180     - System
 181     - Unified Hosting Interface (MD01069)
 182   * - Nios II
 183     - System
 184     - https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;a=blob;f=libgloss/nios2/nios2-semi.txt;hb=HEAD
 185   * - RISC-V
 186     - System and User-mode
 187     - https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc
 188   * - Xtensa
 189     - System
 190     - Tensilica ISS SIMCALL