meson: convert hw/vfio
[qemu.git] / docs / user / main.rst
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.