1Emulation 2========= 3 4QEMU's Tiny Code Generator (TCG) provides the ability to emulate a 5number of CPU architectures on any supported host platform. Both 6:ref:`System Emulation` and :ref:`User Mode Emulation` are supported 7depending 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 102A number of features are are only available when running under 103emulation including :ref:`Record/Replay<replay>` and :ref:`TCG Plugins`. 104 105.. _Semihosting: 106 107Semihosting 108----------- 109 110Semihosting is a feature defined by the owner of the architecture to 111allow programs to interact with a debugging host system. On real 112hardware this is usually provided by an In-circuit emulator (ICE) 113hooked directly to the board. QEMU's implementation allows for 114semihosting calls to be passed to the host system or via the 115``gdbstub``. 116 117Generally semihosting makes it easier to bring up low level code before a 118more fully functional operating system has been enabled. On QEMU it 119also allows for embedded micro-controller code which typically doesn't 120have a full libc to be run as "bare-metal" code under QEMU's user-mode 121emulation. It is also useful for writing test cases and indeed a 122number of compiler suites as well as QEMU itself use semihosting calls 123to exit test code while reporting the success state. 124 125Semihosting is only available using TCG emulation. This is because the 126instructions to trigger a semihosting call are typically reserved 127causing 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 135Redirection 136~~~~~~~~~~~ 137 138Semihosting calls can be re-directed to a (potentially remote) gdb 139during debugging via the :ref:`gdbstub<GDB usage>`. Output to the 140semihosting console is configured as a ``chardev`` so can be 141redirected to a file, pipe or socket like any other ``chardev`` 142device. 143 144Supported Targets 145~~~~~~~~~~~~~~~~~ 146 147Most targets offer similar semihosting implementations with some 148minor changes to define the appropriate instruction to encode the 149semihosting call and which registers hold the parameters. They tend to 150presents a simple POSIX-like API which allows your program to read and 151write files, access the console and some other basic interactions. 152 153For full details of the ABI for a particular target, and the set of 154calls it provides, you should consult the semihosting specification 155for 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 191