xref: /openbmc/qemu/docs/user/main.rst (revision c700d068)
1QEMU User space emulator
2========================
3
4Supported Operating Systems
5---------------------------
6
7The 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
13Features
14--------
15
16QEMU 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
41QEMU was conceived so that ultimately it can emulate itself. Although it
42is not very useful, it is an important test to show the power of the
43emulator.
44
45Linux User space emulator
46-------------------------
47
48Command 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
84Debug options:
85
86``-d item1,...``
87   Activate logging of the specified items (use '-d help' for a list of
88   log items)
89
90``-g port``
91   Wait gdb connection to port
92
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
98Environment variables:
99
100QEMU_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
108Other binaries
109~~~~~~~~~~~~~~
110
111-  user mode (Alpha)
112
113   * ``qemu-alpha`` TODO.
114
115-  user mode (Arm)
116
117   * ``qemu-armeb`` TODO.
118
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.
122
123-  user mode (ColdFire)
124
125-  user mode (M68K)
126
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.
130
131   The binary format is detected automatically.
132
133-  user mode (i386)
134
135   * ``qemu-i386`` TODO.
136   * ``qemu-x86_64`` TODO.
137
138-  user mode (Microblaze)
139
140   * ``qemu-microblaze`` TODO.
141
142-  user mode (MIPS)
143
144   * ``qemu-mips`` executes 32-bit big endian MIPS binaries (MIPS O32 ABI).
145
146   * ``qemu-mipsel`` executes 32-bit little endian MIPS binaries (MIPS O32 ABI).
147
148   * ``qemu-mips64`` executes 64-bit big endian MIPS binaries (MIPS N64 ABI).
149
150   * ``qemu-mips64el`` executes 64-bit little endian MIPS binaries (MIPS N64
151     ABI).
152
153   * ``qemu-mipsn32`` executes 32-bit big endian MIPS binaries (MIPS N32 ABI).
154
155   * ``qemu-mipsn32el`` executes 32-bit little endian MIPS binaries (MIPS N32
156     ABI).
157
158-  user mode (PowerPC)
159
160   * ``qemu-ppc64`` TODO.
161   * ``qemu-ppc`` TODO.
162
163-  user mode (SH4)
164
165   * ``qemu-sh4eb`` TODO.
166   * ``qemu-sh4`` TODO.
167
168-  user mode (SPARC)
169
170   * ``qemu-sparc`` can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
171
172   * ``qemu-sparc32plus`` can execute Sparc32 and SPARC32PLUS binaries
173     (Sparc64 CPU, 32 bit ABI).
174
175   * ``qemu-sparc64`` can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
176     SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
177
178BSD User space emulator
179-----------------------
180
181BSD Status
182~~~~~~~~~~
183
184-  target Sparc64 on Sparc64: Some trivial programs work.
185
186Quick Start
187~~~~~~~~~~~
188
189In order to launch a BSD process, QEMU needs the process executable
190itself and all the target dynamic libraries used by it.
191
192-  On Sparc64, you can just try to launch any process by using the
193   native libraries::
194
195      qemu-sparc64 /bin/ls
196
197Command line options
198~~~~~~~~~~~~~~~~~~~~
199
200::
201
202   qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
203
204``-h``
205   Print the help
206
207``-L path``
208   Set the library root path (default=/)
209
210``-s size``
211   Set the stack size in bytes (default=524288)
212
213``-ignore-environment``
214   Start with an empty environment. Without this option, the initial
215   environment is a copy of the caller's environment.
216
217``-E var=value``
218   Set environment var to value.
219
220``-U var``
221   Remove var from the environment.
222
223``-bsd type``
224   Set the type of the emulated BSD Operating system. Valid values are
225   FreeBSD, NetBSD and OpenBSD (default).
226
227Debug options:
228
229``-d item1,...``
230   Activate logging of the specified items (use '-d help' for a list of
231   log items)
232
233``-p pagesize``
234   Act as if the host page size was 'pagesize' bytes
235
236``-one-insn-per-tb``
237   Run the emulation with one guest instruction per translation block.
238   This slows down emulation a lot, but can be useful in some situations,
239   such as when trying to analyse the logs produced by the ``-d`` option.
240