xref: /openbmc/qemu/docs/user/main.rst (revision 6ad034e71232c2929ed546304c9d249312bb632f)
1.. _user-mode:
2
3QEMU User space emulator
4========================
5
6Supported Operating Systems
7---------------------------
8
9The following OS are supported in user space emulation:
10
11-  Linux (referred as qemu-linux-user)
12
13-  BSD (referred as qemu-bsd-user)
14
15Features
16--------
17
18QEMU user space emulation has the following notable features:
19
20System call translation
21~~~~~~~~~~~~~~~~~~~~~~~
22
23System calls are the principle interface between user-space and the
24kernel. Generally the same system calls exist on all versions of the
25kernel so QEMU includes a generic system call translator. The
26translator takes care of adjusting endianess, 32/64 bit parameter size
27and then calling the equivalent host system call.
28
29QEMU can also adjust device specific ``ioctl()`` calls in a similar
30fashion.
31
32POSIX signal handling
33~~~~~~~~~~~~~~~~~~~~~
34
35QEMU can redirect to the running program all signals coming from the
36host (such as ``SIGALRM``), as well as synthesize signals from
37virtual CPU exceptions (for example ``SIGFPE`` when the program
38executes a division by zero).
39
40QEMU relies on the host kernel to emulate most signal system calls,
41for example to emulate the signal mask. On Linux, QEMU supports both
42normal and real-time signals.
43
44Threading
45~~~~~~~~~
46
47On Linux, QEMU can emulate the ``clone`` syscall and create a real
48host thread (with a separate virtual CPU) for each emulated thread.
49However as QEMU relies on the system libc to call ``clone`` on its
50behalf we limit the flags accepted to those it uses. Specifically this
51means flags affecting namespaces (e.g. container runtimes) are not
52supported. QEMU user-mode processes can still be run inside containers
53though.
54
55While QEMU does its best to emulate atomic operations properly
56differences between the host and guest memory models can cause issues
57for software that makes assumptions about the memory model.
58
59QEMU was conceived so that ultimately it can emulate itself. Although it
60is not very useful, it is an important test to show the power of the
61emulator.
62
63.. _linux-user-mode:
64
65Linux User space emulator
66-------------------------
67
68Command line options
69~~~~~~~~~~~~~~~~~~~~
70
71::
72
73   qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g endpoint] [-B offset] [-R size] program [arguments...]
74
75``-h``
76   Print the help
77
78``-L path``
79   Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
80
81``-s size``
82   Set the x86 stack size in bytes (default=524288)
83
84``-cpu model``
85   Select CPU model (-cpu help for list and additional feature
86   selection)
87
88``-E var=value``
89   Set environment var to value.
90
91``-U var``
92   Remove var from the environment.
93
94``-B offset``
95   Offset guest address by the specified number of bytes. This is useful
96   when the address region required by guest applications is reserved on
97   the host. This option is currently only supported on some hosts.
98
99``-R size``
100   Pre-allocate a guest virtual address space of the given size (in
101   bytes). \"G\", \"M\", and \"k\" suffixes may be used when specifying
102   the size.
103
104Debug options:
105
106``-d item1,...``
107   Activate logging of the specified items (use '-d help' for a list of
108   log items)
109
110``-g endpoint``
111   Wait gdb connection to a port (e.g., ``1234``) or a unix socket (e.g.,
112   ``/tmp/qemu.sock``).
113
114   If a unix socket path contains single ``%d`` placeholder (e.g.,
115   ``/tmp/qemu-%d.sock``), it is replaced by the emulator PID, which is useful
116   when passing this option via the ``QEMU_GDB`` environment variable to a
117   multi-process application.
118
119   If the endpoint address is followed by ``,suspend=n`` (e.g.,
120   ``1234,suspend=n``), then the emulated program starts without waiting for a
121   connection, which can be established at any later point in time.
122
123``-one-insn-per-tb``
124   Run the emulation with one guest instruction per translation block.
125   This slows down emulation a lot, but can be useful in some situations,
126   such as when trying to analyse the logs produced by the ``-d`` option.
127
128Environment variables:
129
130QEMU_STRACE
131   Print system calls and arguments similar to the 'strace' program
132   (NOTE: the actual 'strace' program will not work because the user
133   space emulator hasn't implemented ptrace). At the moment this is
134   incomplete. All system calls that don't have a specific argument
135   format are printed with information for six arguments. Many
136   flag-style arguments don't have decoders and will show up as numbers.
137
138Other binaries
139~~~~~~~~~~~~~~
140
141-  user mode (Alpha)
142
143   * ``qemu-alpha`` TODO.
144
145-  user mode (Arm)
146
147   * ``qemu-armeb`` TODO.
148
149   * ``qemu-arm`` is also capable of running Arm \"Angel\" semihosted ELF
150     binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
151     configurations), and arm-uclinux bFLT format binaries.
152
153-  user mode (ColdFire)
154
155-  user mode (M68K)
156
157   * ``qemu-m68k`` is capable of running semihosted binaries using the BDM
158     (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
159     coldfire uClinux bFLT format binaries.
160
161   The binary format is detected automatically.
162
163-  user mode (i386)
164
165   * ``qemu-i386`` TODO.
166   * ``qemu-x86_64`` TODO.
167
168-  user mode (Microblaze)
169
170   * ``qemu-microblaze`` TODO.
171
172-  user mode (MIPS)
173
174   * ``qemu-mips`` executes 32-bit big endian MIPS binaries (MIPS O32 ABI).
175
176   * ``qemu-mipsel`` executes 32-bit little endian MIPS binaries (MIPS O32 ABI).
177
178   * ``qemu-mips64`` executes 64-bit big endian MIPS binaries (MIPS N64 ABI).
179
180   * ``qemu-mips64el`` executes 64-bit little endian MIPS binaries (MIPS N64
181     ABI).
182
183   * ``qemu-mipsn32`` executes 32-bit big endian MIPS binaries (MIPS N32 ABI).
184
185   * ``qemu-mipsn32el`` executes 32-bit little endian MIPS binaries (MIPS N32
186     ABI).
187
188-  user mode (PowerPC)
189
190   * ``qemu-ppc64`` TODO.
191   * ``qemu-ppc`` TODO.
192
193-  user mode (SH4)
194
195   * ``qemu-sh4eb`` TODO.
196   * ``qemu-sh4`` TODO.
197
198-  user mode (SPARC)
199
200   * ``qemu-sparc`` can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
201
202   * ``qemu-sparc32plus`` can execute Sparc32 and SPARC32PLUS binaries
203     (Sparc64 CPU, 32 bit ABI).
204
205   * ``qemu-sparc64`` can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
206     SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
207
208.. _bsd-user-mode:
209
210BSD User space emulator
211-----------------------
212
213BSD Status
214~~~~~~~~~~
215
216-  target Sparc64 on Sparc64: Some trivial programs work.
217
218Quick Start
219~~~~~~~~~~~
220
221In order to launch a BSD process, QEMU needs the process executable
222itself and all the target dynamic libraries used by it.
223
224-  On Sparc64, you can just try to launch any process by using the
225   native libraries::
226
227      qemu-sparc64 /bin/ls
228
229Command line options
230~~~~~~~~~~~~~~~~~~~~
231
232::
233
234   qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
235
236``-h``
237   Print the help
238
239``-L path``
240   Set the library root path (default=/)
241
242``-s size``
243   Set the stack size in bytes (default=524288)
244
245``-ignore-environment``
246   Start with an empty environment. Without this option, the initial
247   environment is a copy of the caller's environment.
248
249``-E var=value``
250   Set environment var to value.
251
252``-U var``
253   Remove var from the environment.
254
255``-bsd type``
256   Set the type of the emulated BSD Operating system. Valid values are
257   FreeBSD, NetBSD and OpenBSD (default).
258
259Debug options:
260
261``-d item1,...``
262   Activate logging of the specified items (use '-d help' for a list of
263   log items)
264
265``-p pagesize``
266   Act as if the host page size was 'pagesize' bytes
267
268``-one-insn-per-tb``
269   Run the emulation with one guest instruction per translation block.
270   This slows down emulation a lot, but can be useful in some situations,
271   such as when trying to analyse the logs produced by the ``-d`` option.
272