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 * - OpenRISC 62 - :ref:`Yes<OpenRISC-System-emulator>` 63 - Yes 64 - Open source RISC architecture developed by the OpenRISC community 65 * - Power (ppc, ppc64) 66 - :ref:`Yes<PowerPC-System-emulator>` 67 - Yes 68 - A general purpose RISC architecture now managed by IBM 69 * - RISC-V 70 - :ref:`Yes<RISC-V-System-emulator>` 71 - Yes 72 - An open standard RISC ISA maintained by RISC-V International 73 * - RX 74 - :ref:`Yes<RX-System-emulator>` 75 - No 76 - A 32 bit micro controller developed by Renesas 77 * - s390x 78 - :ref:`Yes<s390x-System-emulator>` 79 - Yes 80 - A 64 bit CPU found in IBM's System Z mainframes 81 * - sh4 82 - Yes 83 - Yes 84 - A 32 bit RISC embedded CPU developed by Hitachi 85 * - SPARC (sparc, sparc64) 86 - :ref:`Yes<Sparc32-System-emulator>` 87 - Yes 88 - A RISC ISA originally developed by Sun Microsystems 89 * - Tricore 90 - Yes 91 - No 92 - A 32 bit RISC/uController/DSP developed by Infineon 93 * - Xtensa 94 - :ref:`Yes<Xtensa-System-emulator>` 95 - Yes 96 - A configurable 32 bit soft core now owned by Cadence 97 98A number of features are only available when running under 99emulation including :ref:`Record/Replay<replay>` and :ref:`TCG Plugins`. 100 101.. _Semihosting: 102 103Semihosting 104----------- 105 106Semihosting is a feature defined by the owner of the architecture to 107allow programs to interact with a debugging host system. On real 108hardware this is usually provided by an In-circuit emulator (ICE) 109hooked directly to the board. QEMU's implementation allows for 110semihosting calls to be passed to the host system or via the 111``gdbstub``. 112 113Generally semihosting makes it easier to bring up low level code before a 114more fully functional operating system has been enabled. On QEMU it 115also allows for embedded micro-controller code which typically doesn't 116have a full libc to be run as "bare-metal" code under QEMU's user-mode 117emulation. It is also useful for writing test cases and indeed a 118number of compiler suites as well as QEMU itself use semihosting calls 119to exit test code while reporting the success state. 120 121Semihosting is only available using TCG emulation. This is because the 122instructions to trigger a semihosting call are typically reserved 123causing most hypervisors to trap and fault on them. 124 125.. warning:: 126 Semihosting inherently bypasses any isolation there may be between 127 the guest and the host. As a result a program using semihosting can 128 happily trash your host system. Some semihosting calls (e.g. 129 ``SYS_READC``) can block execution indefinitely. You should only 130 ever run trusted code with semihosting enabled. 131 132Redirection 133~~~~~~~~~~~ 134 135Semihosting calls can be re-directed to a (potentially remote) gdb 136during debugging via the :ref:`gdbstub<GDB usage>`. Output to the 137semihosting console is configured as a ``chardev`` so can be 138redirected to a file, pipe or socket like any other ``chardev`` 139device. 140 141Supported Targets 142~~~~~~~~~~~~~~~~~ 143 144Most targets offer similar semihosting implementations with some 145minor changes to define the appropriate instruction to encode the 146semihosting call and which registers hold the parameters. They tend to 147presents a simple POSIX-like API which allows your program to read and 148write files, access the console and some other basic interactions. 149 150For full details of the ABI for a particular target, and the set of 151calls it provides, you should consult the semihosting specification 152for that architecture. 153 154.. note:: 155 QEMU makes an implementation decision to implement all file 156 access in ``O_BINARY`` mode. The user-visible effect of this is 157 regardless of the text/binary mode the program sets QEMU will 158 always select a binary mode ensuring no line-terminator conversion 159 is performed on input or output. This is because gdb semihosting 160 support doesn't make the distinction between the modes and 161 magically processing line endings can be confusing. 162 163.. list-table:: Guest Architectures supporting Semihosting 164 :widths: 10 10 80 165 :header-rows: 1 166 167 * - Architecture 168 - Modes 169 - Specification 170 * - Arm 171 - System and User-mode 172 - https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst 173 * - m68k 174 - System 175 - https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=libgloss/m68k/m68k-semi.txt;hb=HEAD 176 * - MIPS 177 - System 178 - Unified Hosting Interface (MD01069) 179 * - RISC-V 180 - System and User-mode 181 - https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc 182 * - Xtensa 183 - System 184 - Tensilica ISS SIMCALL 185