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. Some semihosting calls (e.g.
 133    ``SYS_READC``) can block execution indefinitely. You should only
 134    ever run trusted code with semihosting enabled.
 135
 136 Redirection
 137 ~~~~~~~~~~~
 138
 139 Semihosting calls can be re-directed to a (potentially remote) gdb
 140 during debugging via the :ref:`gdbstub<GDB usage>`. Output to the
 141 semihosting console is configured as a ``chardev`` so can be
 142 redirected to a file, pipe or socket like any other ``chardev``
 143 device.
 144
 145 Supported Targets
 146 ~~~~~~~~~~~~~~~~~
 147
 148 Most targets offer similar semihosting implementations with some
 149 minor changes to define the appropriate instruction to encode the
 150 semihosting call and which registers hold the parameters. They tend to
 151 presents a simple POSIX-like API which allows your program to read and
 152 write files, access the console and some other basic interactions.
 153
 154 For full details of the ABI for a particular target, and the set of
 155 calls it provides, you should consult the semihosting specification
 156 for that architecture.
 157
 158 .. note::
 159    QEMU makes an implementation decision to implement all file
 160    access in ``O_BINARY`` mode. The user-visible effect of this is
 161    regardless of the text/binary mode the program sets QEMU will
 162    always select a binary mode ensuring no line-terminator conversion
 163    is performed on input or output. This is because gdb semihosting
 164    support doesn't make the distinction between the modes and
 165    magically processing line endings can be confusing.
 166
 167 .. list-table:: Guest Architectures supporting Semihosting
 168   :widths: 10 10 80
 169   :header-rows: 1
 170
 171   * - Architecture
 172     - Modes
 173     - Specification
 174   * - Arm
 175     - System and User-mode
 176     - https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst
 177   * - m68k
 178     - System
 179     - https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=libgloss/m68k/m68k-semi.txt;hb=HEAD
 180   * - MIPS
 181     - System
 182     - Unified Hosting Interface (MD01069)
 183   * - Nios II
 184     - System
 185     - https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;a=blob;f=libgloss/nios2/nios2-semi.txt;hb=HEAD
 186   * - RISC-V
 187     - System and User-mode
 188     - https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc
 189   * - Xtensa
 190     - System
 191     - Tensilica ISS SIMCALL