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