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