| 1 | .. _user-mode: |
| 2 | |
| 3 | QEMU User space emulator |
| 4 | ======================== |
| 5 | |
| 6 | Supported Operating Systems |
| 7 | --------------------------- |
| 8 | |
| 9 | The 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 | |
| 15 | Features |
| 16 | -------- |
| 17 | |
| 18 | QEMU user space emulation has the following notable features: |
| 19 | |
| 20 | System call translation |
| 21 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 22 | |
| 23 | System calls are the principle interface between user-space and the |
| 24 | kernel. Generally the same system calls exist on all versions of the |
| 25 | kernel so QEMU includes a generic system call translator. The |
| 26 | translator takes care of adjusting endianess, 32/64 bit parameter size |
| 27 | and then calling the equivalent host system call. |
| 28 | |
| 29 | QEMU can also adjust device specific ``ioctl()`` calls in a similar |
| 30 | fashion. |
| 31 | |
| 32 | POSIX signal handling |
| 33 | ~~~~~~~~~~~~~~~~~~~~~ |
| 34 | |
| 35 | QEMU can redirect to the running program all signals coming from the |
| 36 | host (such as ``SIGALRM``), as well as synthesize signals from |
| 37 | virtual CPU exceptions (for example ``SIGFPE`` when the program |
| 38 | executes a division by zero). |
| 39 | |
| 40 | QEMU relies on the host kernel to emulate most signal system calls, |
| 41 | for example to emulate the signal mask. On Linux, QEMU supports both |
| 42 | normal and real-time signals. |
| 43 | |
| 44 | Threading |
| 45 | ~~~~~~~~~ |
| 46 | |
| 47 | On Linux, QEMU can emulate the ``clone`` syscall and create a real |
| 48 | host thread (with a separate virtual CPU) for each emulated thread. |
| 49 | However as QEMU relies on the system libc to call ``clone`` on its |
| 50 | behalf we limit the flags accepted to those it uses. Specifically this |
| 51 | means flags affecting namespaces (e.g. container runtimes) are not |
| 52 | supported. QEMU user-mode processes can still be run inside containers |
| 53 | though. |
| 54 | |
| 55 | While QEMU does its best to emulate atomic operations properly |
| 56 | differences between the host and guest memory models can cause issues |
| 57 | for software that makes assumptions about the memory model. |
| 58 | |
| 59 | QEMU was conceived so that ultimately it can emulate itself. Although it |
| 60 | is not very useful, it is an important test to show the power of the |
| 61 | emulator. |
| 62 | |
| 63 | .. _linux-user-mode: |
| 64 | |
| 65 | Linux User space emulator |
| 66 | ------------------------- |
| 67 | |
| 68 | Command 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 | |
| 104 | Debug 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 | |
| 128 | Environment variables: |
| 129 | |
| 130 | QEMU_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 | |
| 138 | Other 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 | |
| 210 | BSD User space emulator |
| 211 | ----------------------- |
| 212 | |
| 213 | BSD Status |
| 214 | ~~~~~~~~~~ |
| 215 | |
| 216 | - target Sparc64 on Sparc64: Some trivial programs work. |
| 217 | |
| 218 | Quick Start |
| 219 | ~~~~~~~~~~~ |
| 220 | |
| 221 | In order to launch a BSD process, QEMU needs the process executable |
| 222 | itself 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 | |
| 229 | Command 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 | |
| 259 | Debug options: |
| 260 | |
| 261 | ``-d item1,...`` |
| 262 | Activate logging of the specified items (use '-d help' for a list of |
| 263 | log items) |
| 264 | |
| 265 | ``-one-insn-per-tb`` |
| 266 | Run the emulation with one guest instruction per translation block. |
| 267 | This slows down emulation a lot, but can be useful in some situations, |
| 268 | such as when trying to analyse the logs produced by the ``-d`` option. |