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