]>
Commit | Line | Data |
---|---|---|
09147930 PB |
1 | QEMU User space emulator |
2 | ======================== | |
3 | ||
4 | Supported Operating Systems | |
5 | --------------------------- | |
6 | ||
7 | The following OS are supported in user space emulation: | |
8 | ||
9 | - Linux (referred as qemu-linux-user) | |
10 | ||
11 | - BSD (referred as qemu-bsd-user) | |
12 | ||
13 | Features | |
14 | -------- | |
15 | ||
16 | QEMU user space emulation has the following notable features: | |
17 | ||
18 | **System call translation:** | |
19 | QEMU includes a generic system call translator. This means that the | |
20 | parameters of the system calls can be converted to fix endianness and | |
21 | 32/64-bit mismatches between hosts and targets. IOCTLs can be | |
22 | converted too. | |
23 | ||
24 | **POSIX signal handling:** | |
25 | QEMU can redirect to the running program all signals coming from the | |
26 | host (such as ``SIGALRM``), as well as synthesize signals from | |
27 | virtual CPU exceptions (for example ``SIGFPE`` when the program | |
28 | executes a division by zero). | |
29 | ||
30 | QEMU relies on the host kernel to emulate most signal system calls, | |
31 | for example to emulate the signal mask. On Linux, QEMU supports both | |
32 | normal and real-time signals. | |
33 | ||
34 | **Threading:** | |
35 | On Linux, QEMU can emulate the ``clone`` syscall and create a real | |
36 | host thread (with a separate virtual CPU) for each emulated thread. | |
37 | Note that not all targets currently emulate atomic operations | |
38 | correctly. x86 and ARM use a global lock in order to preserve their | |
39 | semantics. | |
40 | ||
41 | QEMU was conceived so that ultimately it can emulate itself. Although it | |
42 | is not very useful, it is an important test to show the power of the | |
43 | emulator. | |
44 | ||
45 | Linux User space emulator | |
46 | ------------------------- | |
47 | ||
48 | Quick Start | |
49 | ~~~~~~~~~~~ | |
50 | ||
51 | In order to launch a Linux process, QEMU needs the process executable | |
52 | itself and all the target (x86) dynamic libraries used by it. | |
53 | ||
54 | - On x86, you can just try to launch any process by using the native | |
55 | libraries:: | |
56 | ||
57 | qemu-i386 -L / /bin/ls | |
58 | ||
59 | ``-L /`` tells that the x86 dynamic linker must be searched with a | |
60 | ``/`` prefix. | |
61 | ||
62 | - Since QEMU is also a linux process, you can launch QEMU with QEMU | |
63 | (NOTE: you can only do that if you compiled QEMU from the sources):: | |
64 | ||
65 | qemu-i386 -L / qemu-i386 -L / /bin/ls | |
66 | ||
67 | - On non x86 CPUs, you need first to download at least an x86 glibc | |
68 | (``qemu-runtime-i386-XXX-.tar.gz`` on the QEMU web page). Ensure that | |
69 | ``LD_LIBRARY_PATH`` is not set:: | |
70 | ||
71 | unset LD_LIBRARY_PATH | |
72 | ||
73 | Then you can launch the precompiled ``ls`` x86 executable:: | |
74 | ||
75 | qemu-i386 tests/i386/ls | |
76 | ||
77 | You can look at ``scripts/qemu-binfmt-conf.sh`` so that QEMU is | |
78 | automatically launched by the Linux kernel when you try to launch x86 | |
79 | executables. It requires the ``binfmt_misc`` module in the Linux | |
80 | kernel. | |
81 | ||
82 | - The x86 version of QEMU is also included. You can try weird things | |
83 | such as:: | |
84 | ||
85 | qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \ | |
86 | /usr/local/qemu-i386/bin/ls-i386 | |
87 | ||
88 | Wine launch | |
89 | ~~~~~~~~~~~ | |
90 | ||
91 | - Ensure that you have a working QEMU with the x86 glibc distribution | |
92 | (see previous section). In order to verify it, you must be able to | |
93 | do:: | |
94 | ||
95 | qemu-i386 /usr/local/qemu-i386/bin/ls-i386 | |
96 | ||
97 | - Download the binary x86 Wine install (``qemu-XXX-i386-wine.tar.gz`` | |
98 | on the QEMU web page). | |
99 | ||
100 | - Configure Wine on your account. Look at the provided script | |
101 | ``/usr/local/qemu-i386/bin/wine-conf.sh``. Your previous | |
102 | ``${HOME}/.wine`` directory is saved to ``${HOME}/.wine.org``. | |
103 | ||
104 | - Then you can try the example ``putty.exe``:: | |
105 | ||
106 | qemu-i386 /usr/local/qemu-i386/wine/bin/wine \ | |
107 | /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe | |
108 | ||
109 | Command line options | |
110 | ~~~~~~~~~~~~~~~~~~~~ | |
111 | ||
112 | :: | |
113 | ||
114 | qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...] | |
115 | ||
116 | ``-h`` | |
117 | Print the help | |
118 | ||
119 | ``-L path`` | |
120 | Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386) | |
121 | ||
122 | ``-s size`` | |
123 | Set the x86 stack size in bytes (default=524288) | |
124 | ||
125 | ``-cpu model`` | |
126 | Select CPU model (-cpu help for list and additional feature | |
127 | selection) | |
128 | ||
129 | ``-E var=value`` | |
130 | Set environment var to value. | |
131 | ||
132 | ``-U var`` | |
133 | Remove var from the environment. | |
134 | ||
135 | ``-B offset`` | |
136 | Offset guest address by the specified number of bytes. This is useful | |
137 | when the address region required by guest applications is reserved on | |
138 | the host. This option is currently only supported on some hosts. | |
139 | ||
140 | ``-R size`` | |
141 | Pre-allocate a guest virtual address space of the given size (in | |
142 | bytes). \"G\", \"M\", and \"k\" suffixes may be used when specifying | |
143 | the size. | |
144 | ||
145 | Debug options: | |
146 | ||
147 | ``-d item1,...`` | |
148 | Activate logging of the specified items (use '-d help' for a list of | |
149 | log items) | |
150 | ||
151 | ``-p pagesize`` | |
152 | Act as if the host page size was 'pagesize' bytes | |
153 | ||
154 | ``-g port`` | |
155 | Wait gdb connection to port | |
156 | ||
157 | ``-singlestep`` | |
158 | Run the emulation in single step mode. | |
159 | ||
160 | Environment variables: | |
161 | ||
162 | QEMU_STRACE | |
163 | Print system calls and arguments similar to the 'strace' program | |
164 | (NOTE: the actual 'strace' program will not work because the user | |
165 | space emulator hasn't implemented ptrace). At the moment this is | |
166 | incomplete. All system calls that don't have a specific argument | |
167 | format are printed with information for six arguments. Many | |
168 | flag-style arguments don't have decoders and will show up as numbers. | |
169 | ||
170 | Other binaries | |
171 | ~~~~~~~~~~~~~~ | |
172 | ||
173 | user mode (Alpha) | |
174 | ``qemu-alpha`` TODO. | |
175 | ||
176 | user mode (ARM) | |
177 | ``qemu-armeb`` TODO. | |
178 | ||
179 | user mode (ARM) | |
180 | ``qemu-arm`` is also capable of running ARM \"Angel\" semihosted ELF | |
181 | binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB | |
182 | configurations), and arm-uclinux bFLT format binaries. | |
183 | ||
184 | user mode (ColdFire) | |
185 | user mode (M68K) | |
186 | ``qemu-m68k`` is capable of running semihosted binaries using the BDM | |
187 | (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and | |
188 | coldfire uClinux bFLT format binaries. | |
189 | ||
190 | The binary format is detected automatically. | |
191 | ||
192 | user mode (Cris) | |
193 | ``qemu-cris`` TODO. | |
194 | ||
195 | user mode (i386) | |
196 | ``qemu-i386`` TODO. ``qemu-x86_64`` TODO. | |
197 | ||
198 | user mode (Microblaze) | |
199 | ``qemu-microblaze`` TODO. | |
200 | ||
201 | user mode (MIPS) | |
202 | ``qemu-mips`` executes 32-bit big endian MIPS binaries (MIPS O32 ABI). | |
203 | ||
204 | ``qemu-mipsel`` executes 32-bit little endian MIPS binaries (MIPS O32 | |
205 | ABI). | |
206 | ||
207 | ``qemu-mips64`` executes 64-bit big endian MIPS binaries (MIPS N64 ABI). | |
208 | ||
209 | ``qemu-mips64el`` executes 64-bit little endian MIPS binaries (MIPS N64 | |
210 | ABI). | |
211 | ||
212 | ``qemu-mipsn32`` executes 32-bit big endian MIPS binaries (MIPS N32 | |
213 | ABI). | |
214 | ||
215 | ``qemu-mipsn32el`` executes 32-bit little endian MIPS binaries (MIPS N32 | |
216 | ABI). | |
217 | ||
218 | user mode (NiosII) | |
219 | ``qemu-nios2`` TODO. | |
220 | ||
221 | user mode (PowerPC) | |
222 | ``qemu-ppc64abi32`` TODO. ``qemu-ppc64`` TODO. ``qemu-ppc`` TODO. | |
223 | ||
224 | user mode (SH4) | |
225 | ``qemu-sh4eb`` TODO. ``qemu-sh4`` TODO. | |
226 | ||
227 | user mode (SPARC) | |
228 | ``qemu-sparc`` can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI). | |
229 | ||
230 | ``qemu-sparc32plus`` can execute Sparc32 and SPARC32PLUS binaries | |
231 | (Sparc64 CPU, 32 bit ABI). | |
232 | ||
233 | ``qemu-sparc64`` can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and | |
234 | SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI). | |
235 | ||
236 | BSD User space emulator | |
237 | ----------------------- | |
238 | ||
239 | BSD Status | |
240 | ~~~~~~~~~~ | |
241 | ||
242 | - target Sparc64 on Sparc64: Some trivial programs work. | |
243 | ||
244 | Quick Start | |
245 | ~~~~~~~~~~~ | |
246 | ||
247 | In order to launch a BSD process, QEMU needs the process executable | |
248 | itself and all the target dynamic libraries used by it. | |
249 | ||
250 | - On Sparc64, you can just try to launch any process by using the | |
251 | native libraries:: | |
252 | ||
253 | qemu-sparc64 /bin/ls | |
254 | ||
255 | Command line options | |
256 | ~~~~~~~~~~~~~~~~~~~~ | |
257 | ||
258 | :: | |
259 | ||
260 | qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...] | |
261 | ||
262 | ``-h`` | |
263 | Print the help | |
264 | ||
265 | ``-L path`` | |
266 | Set the library root path (default=/) | |
267 | ||
268 | ``-s size`` | |
269 | Set the stack size in bytes (default=524288) | |
270 | ||
271 | ``-ignore-environment`` | |
272 | Start with an empty environment. Without this option, the initial | |
273 | environment is a copy of the caller's environment. | |
274 | ||
275 | ``-E var=value`` | |
276 | Set environment var to value. | |
277 | ||
278 | ``-U var`` | |
279 | Remove var from the environment. | |
280 | ||
281 | ``-bsd type`` | |
282 | Set the type of the emulated BSD Operating system. Valid values are | |
283 | FreeBSD, NetBSD and OpenBSD (default). | |
284 | ||
285 | Debug options: | |
286 | ||
287 | ``-d item1,...`` | |
288 | Activate logging of the specified items (use '-d help' for a list of | |
289 | log items) | |
290 | ||
291 | ``-p pagesize`` | |
292 | Act as if the host page size was 'pagesize' bytes | |
293 | ||
294 | ``-singlestep`` | |
295 | Run the emulation in single step mode. |