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