xref: /qemu/docs/about/emulation.rst (revision 5db05230) 
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