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