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 48Quick Start 49~~~~~~~~~~~ 50 51In order to launch a Linux process, QEMU needs the process executable 52itself 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 88Wine 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 109Command 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 145Debug 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 160Environment variables: 161 162QEMU_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 170Other binaries 171~~~~~~~~~~~~~~ 172 173- user mode (Alpha) 174 175 * ``qemu-alpha`` TODO. 176 177- user mode (Arm) 178 179 * ``qemu-armeb`` TODO. 180 181 * ``qemu-arm`` is also capable of running Arm \"Angel\" semihosted ELF 182 binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB 183 configurations), and arm-uclinux bFLT format binaries. 184 185- user mode (ColdFire) 186 187- user mode (M68K) 188 189 * ``qemu-m68k`` is capable of running semihosted binaries using the BDM 190 (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and 191 coldfire uClinux bFLT format binaries. 192 193 The binary format is detected automatically. 194 195- user mode (Cris) 196 197 * ``qemu-cris`` TODO. 198 199- user mode (i386) 200 201 * ``qemu-i386`` TODO. 202 * ``qemu-x86_64`` TODO. 203 204- user mode (Microblaze) 205 206 * ``qemu-microblaze`` TODO. 207 208- user mode (MIPS) 209 210 * ``qemu-mips`` executes 32-bit big endian MIPS binaries (MIPS O32 ABI). 211 212 * ``qemu-mipsel`` executes 32-bit little endian MIPS binaries (MIPS O32 ABI). 213 214 * ``qemu-mips64`` executes 64-bit big endian MIPS binaries (MIPS N64 ABI). 215 216 * ``qemu-mips64el`` executes 64-bit little endian MIPS binaries (MIPS N64 217 ABI). 218 219 * ``qemu-mipsn32`` executes 32-bit big endian MIPS binaries (MIPS N32 ABI). 220 221 * ``qemu-mipsn32el`` executes 32-bit little endian MIPS binaries (MIPS N32 222 ABI). 223 224- user mode (NiosII) 225 226 * ``qemu-nios2`` TODO. 227 228- user mode (PowerPC) 229 230 * ``qemu-ppc64abi32`` TODO. 231 * ``qemu-ppc64`` TODO. 232 * ``qemu-ppc`` TODO. 233 234- user mode (SH4) 235 236 * ``qemu-sh4eb`` TODO. 237 * ``qemu-sh4`` TODO. 238 239- user mode (SPARC) 240 241 * ``qemu-sparc`` can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI). 242 243 * ``qemu-sparc32plus`` can execute Sparc32 and SPARC32PLUS binaries 244 (Sparc64 CPU, 32 bit ABI). 245 246 * ``qemu-sparc64`` can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and 247 SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI). 248 249BSD User space emulator 250----------------------- 251 252BSD Status 253~~~~~~~~~~ 254 255- target Sparc64 on Sparc64: Some trivial programs work. 256 257Quick Start 258~~~~~~~~~~~ 259 260In order to launch a BSD process, QEMU needs the process executable 261itself and all the target dynamic libraries used by it. 262 263- On Sparc64, you can just try to launch any process by using the 264 native libraries:: 265 266 qemu-sparc64 /bin/ls 267 268Command line options 269~~~~~~~~~~~~~~~~~~~~ 270 271:: 272 273 qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...] 274 275``-h`` 276 Print the help 277 278``-L path`` 279 Set the library root path (default=/) 280 281``-s size`` 282 Set the stack size in bytes (default=524288) 283 284``-ignore-environment`` 285 Start with an empty environment. Without this option, the initial 286 environment is a copy of the caller's environment. 287 288``-E var=value`` 289 Set environment var to value. 290 291``-U var`` 292 Remove var from the environment. 293 294``-bsd type`` 295 Set the type of the emulated BSD Operating system. Valid values are 296 FreeBSD, NetBSD and OpenBSD (default). 297 298Debug options: 299 300``-d item1,...`` 301 Activate logging of the specified items (use '-d help' for a list of 302 log items) 303 304``-p pagesize`` 305 Act as if the host page size was 'pagesize' bytes 306 307``-singlestep`` 308 Run the emulation in single step mode. 309