docs/user/main.rst

   1 QEMU User space emulator
   2 ========================
   3
   4 Supported Operating Systems
   5 ---------------------------
   6
   7 The 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
  13 Features
  14 --------
  15
  16 QEMU 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
  41 QEMU was conceived so that ultimately it can emulate itself. Although it
  42 is not very useful, it is an important test to show the power of the
  43 emulator.
  44
  45 Linux User space emulator
  46 -------------------------
  47
  48 Quick Start
  49 ~~~~~~~~~~~
  50
  51 In order to launch a Linux process, QEMU needs the process executable
  52 itself 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
  88 Wine 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
 109 Command 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
 145 Debug 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
 160 Environment variables:
 161
 162 QEMU_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
 170 Other 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
 249 BSD User space emulator
 250 -----------------------
 251
 252 BSD Status
 253 ~~~~~~~~~~
 254
 255 -  target Sparc64 on Sparc64: Some trivial programs work.
 256
 257 Quick Start
 258 ~~~~~~~~~~~
 259
 260 In order to launch a BSD process, QEMU needs the process executable
 261 itself 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
 268 Command 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
 298 Debug 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.