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