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 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. Some semihosting calls (e.g. 133 ``SYS_READC``) can block execution indefinitely. You should only 134 ever run trusted code with semihosting enabled. 135 136Redirection 137~~~~~~~~~~~ 138 139Semihosting calls can be re-directed to a (potentially remote) gdb 140during debugging via the :ref:`gdbstub<GDB usage>`. Output to the 141semihosting console is configured as a ``chardev`` so can be 142redirected to a file, pipe or socket like any other ``chardev`` 143device. 144 145Supported Targets 146~~~~~~~~~~~~~~~~~ 147 148Most targets offer similar semihosting implementations with some 149minor changes to define the appropriate instruction to encode the 150semihosting call and which registers hold the parameters. They tend to 151presents a simple POSIX-like API which allows your program to read and 152write files, access the console and some other basic interactions. 153 154For full details of the ABI for a particular target, and the set of 155calls it provides, you should consult the semihosting specification 156for 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 192