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