]>
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 | |
6fe6d6c9 | 38 | correctly. x86 and Arm use a global lock in order to preserve their |
09147930 PB |
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 | ||
09147930 PB |
48 | Command line options |
49 | ~~~~~~~~~~~~~~~~~~~~ | |
50 | ||
51 | :: | |
52 | ||
53 | qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...] | |
54 | ||
55 | ``-h`` | |
56 | Print the help | |
57 | ||
58 | ``-L path`` | |
59 | Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386) | |
60 | ||
61 | ``-s size`` | |
62 | Set the x86 stack size in bytes (default=524288) | |
63 | ||
64 | ``-cpu model`` | |
65 | Select CPU model (-cpu help for list and additional feature | |
66 | selection) | |
67 | ||
68 | ``-E var=value`` | |
69 | Set environment var to value. | |
70 | ||
71 | ``-U var`` | |
72 | Remove var from the environment. | |
73 | ||
74 | ``-B offset`` | |
75 | Offset guest address by the specified number of bytes. This is useful | |
76 | when the address region required by guest applications is reserved on | |
77 | the host. This option is currently only supported on some hosts. | |
78 | ||
79 | ``-R size`` | |
80 | Pre-allocate a guest virtual address space of the given size (in | |
81 | bytes). \"G\", \"M\", and \"k\" suffixes may be used when specifying | |
82 | the size. | |
83 | ||
84 | Debug options: | |
85 | ||
86 | ``-d item1,...`` | |
87 | Activate logging of the specified items (use '-d help' for a list of | |
88 | log items) | |
89 | ||
90 | ``-p pagesize`` | |
91 | Act as if the host page size was 'pagesize' bytes | |
92 | ||
93 | ``-g port`` | |
94 | Wait gdb connection to port | |
95 | ||
e99c1f89 PM |
96 | ``-one-insn-per-tb`` |
97 | Run the emulation with one guest instruction per translation block. | |
98 | This slows down emulation a lot, but can be useful in some situations, | |
99 | such as when trying to analyse the logs produced by the ``-d`` option. | |
100 | ||
09147930 PB |
101 | Environment variables: |
102 | ||
103 | QEMU_STRACE | |
104 | Print system calls and arguments similar to the 'strace' program | |
105 | (NOTE: the actual 'strace' program will not work because the user | |
106 | space emulator hasn't implemented ptrace). At the moment this is | |
107 | incomplete. All system calls that don't have a specific argument | |
108 | format are printed with information for six arguments. Many | |
109 | flag-style arguments don't have decoders and will show up as numbers. | |
110 | ||
111 | Other binaries | |
112 | ~~~~~~~~~~~~~~ | |
113 | ||
c8a03a8f | 114 | - user mode (Alpha) |
09147930 | 115 | |
c8a03a8f | 116 | * ``qemu-alpha`` TODO. |
09147930 | 117 | |
c8a03a8f | 118 | - user mode (Arm) |
09147930 | 119 | |
c8a03a8f | 120 | * ``qemu-armeb`` TODO. |
09147930 | 121 | |
c8a03a8f PMD |
122 | * ``qemu-arm`` is also capable of running Arm \"Angel\" semihosted ELF |
123 | binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB | |
124 | configurations), and arm-uclinux bFLT format binaries. | |
09147930 | 125 | |
c8a03a8f | 126 | - user mode (ColdFire) |
09147930 | 127 | |
c8a03a8f | 128 | - user mode (M68K) |
09147930 | 129 | |
c8a03a8f PMD |
130 | * ``qemu-m68k`` is capable of running semihosted binaries using the BDM |
131 | (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and | |
132 | coldfire uClinux bFLT format binaries. | |
09147930 | 133 | |
c8a03a8f | 134 | The binary format is detected automatically. |
09147930 | 135 | |
c8a03a8f | 136 | - user mode (Cris) |
09147930 | 137 | |
c8a03a8f | 138 | * ``qemu-cris`` TODO. |
09147930 | 139 | |
c8a03a8f | 140 | - user mode (i386) |
09147930 | 141 | |
c8a03a8f PMD |
142 | * ``qemu-i386`` TODO. |
143 | * ``qemu-x86_64`` TODO. | |
09147930 | 144 | |
c8a03a8f | 145 | - user mode (Microblaze) |
09147930 | 146 | |
c8a03a8f | 147 | * ``qemu-microblaze`` TODO. |
09147930 | 148 | |
c8a03a8f | 149 | - user mode (MIPS) |
09147930 | 150 | |
c8a03a8f | 151 | * ``qemu-mips`` executes 32-bit big endian MIPS binaries (MIPS O32 ABI). |
09147930 | 152 | |
c8a03a8f | 153 | * ``qemu-mipsel`` executes 32-bit little endian MIPS binaries (MIPS O32 ABI). |
09147930 | 154 | |
c8a03a8f | 155 | * ``qemu-mips64`` executes 64-bit big endian MIPS binaries (MIPS N64 ABI). |
09147930 | 156 | |
c8a03a8f PMD |
157 | * ``qemu-mips64el`` executes 64-bit little endian MIPS binaries (MIPS N64 |
158 | ABI). | |
159 | ||
160 | * ``qemu-mipsn32`` executes 32-bit big endian MIPS binaries (MIPS N32 ABI). | |
161 | ||
162 | * ``qemu-mipsn32el`` executes 32-bit little endian MIPS binaries (MIPS N32 | |
163 | ABI). | |
164 | ||
165 | - user mode (NiosII) | |
166 | ||
167 | * ``qemu-nios2`` TODO. | |
168 | ||
169 | - user mode (PowerPC) | |
170 | ||
c8a03a8f PMD |
171 | * ``qemu-ppc64`` TODO. |
172 | * ``qemu-ppc`` TODO. | |
173 | ||
174 | - user mode (SH4) | |
175 | ||
176 | * ``qemu-sh4eb`` TODO. | |
177 | * ``qemu-sh4`` TODO. | |
178 | ||
179 | - user mode (SPARC) | |
180 | ||
181 | * ``qemu-sparc`` can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI). | |
182 | ||
183 | * ``qemu-sparc32plus`` can execute Sparc32 and SPARC32PLUS binaries | |
184 | (Sparc64 CPU, 32 bit ABI). | |
185 | ||
186 | * ``qemu-sparc64`` can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and | |
187 | SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI). | |
09147930 PB |
188 | |
189 | BSD User space emulator | |
190 | ----------------------- | |
191 | ||
192 | BSD Status | |
193 | ~~~~~~~~~~ | |
194 | ||
195 | - target Sparc64 on Sparc64: Some trivial programs work. | |
196 | ||
197 | Quick Start | |
198 | ~~~~~~~~~~~ | |
199 | ||
200 | In order to launch a BSD process, QEMU needs the process executable | |
201 | itself and all the target dynamic libraries used by it. | |
202 | ||
203 | - On Sparc64, you can just try to launch any process by using the | |
204 | native libraries:: | |
205 | ||
206 | qemu-sparc64 /bin/ls | |
207 | ||
208 | Command line options | |
209 | ~~~~~~~~~~~~~~~~~~~~ | |
210 | ||
211 | :: | |
212 | ||
213 | qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...] | |
214 | ||
215 | ``-h`` | |
216 | Print the help | |
217 | ||
218 | ``-L path`` | |
219 | Set the library root path (default=/) | |
220 | ||
221 | ``-s size`` | |
222 | Set the stack size in bytes (default=524288) | |
223 | ||
224 | ``-ignore-environment`` | |
225 | Start with an empty environment. Without this option, the initial | |
226 | environment is a copy of the caller's environment. | |
227 | ||
228 | ``-E var=value`` | |
229 | Set environment var to value. | |
230 | ||
231 | ``-U var`` | |
232 | Remove var from the environment. | |
233 | ||
234 | ``-bsd type`` | |
235 | Set the type of the emulated BSD Operating system. Valid values are | |
236 | FreeBSD, NetBSD and OpenBSD (default). | |
237 | ||
238 | Debug options: | |
239 | ||
240 | ``-d item1,...`` | |
241 | Activate logging of the specified items (use '-d help' for a list of | |
242 | log items) | |
243 | ||
244 | ``-p pagesize`` | |
245 | Act as if the host page size was 'pagesize' bytes | |
246 | ||
060e0cd7 PM |
247 | ``-one-insn-per-tb`` |
248 | Run the emulation with one guest instruction per translation block. | |
249 | This slows down emulation a lot, but can be useful in some situations, | |
250 | such as when trying to analyse the logs produced by the ``-d`` option. |