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 ``-p pagesize``
  91    Act as if the host page size was 'pagesize' bytes
  92
  93 ``-g port``
  94    Wait gdb connection to port
  95
  96 ``-singlestep``
  97    Run the emulation in single step mode.
  98
  99 Environment variables:
 100
 101 QEMU_STRACE
 102    Print system calls and arguments similar to the 'strace' program
 103    (NOTE: the actual 'strace' program will not work because the user
 104    space emulator hasn't implemented ptrace). At the moment this is
 105    incomplete. All system calls that don't have a specific argument
 106    format are printed with information for six arguments. Many
 107    flag-style arguments don't have decoders and will show up as numbers.
 108
 109 Other binaries
 110 ~~~~~~~~~~~~~~
 111
 112 -  user mode (Alpha)
 113
 114    * ``qemu-alpha`` TODO.
 115
 116 -  user mode (Arm)
 117
 118    * ``qemu-armeb`` TODO.
 119
 120    * ``qemu-arm`` is also capable of running Arm \"Angel\" semihosted ELF
 121      binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
 122      configurations), and arm-uclinux bFLT format binaries.
 123
 124 -  user mode (ColdFire)
 125
 126 -  user mode (M68K)
 127
 128    * ``qemu-m68k`` is capable of running semihosted binaries using the BDM
 129      (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
 130      coldfire uClinux bFLT format binaries.
 131
 132    The binary format is detected automatically.
 133
 134 -  user mode (Cris)
 135
 136    * ``qemu-cris`` TODO.
 137
 138 -  user mode (i386)
 139
 140    * ``qemu-i386`` TODO.
 141    * ``qemu-x86_64`` TODO.
 142
 143 -  user mode (Microblaze)
 144
 145    * ``qemu-microblaze`` TODO.
 146
 147 -  user mode (MIPS)
 148
 149    * ``qemu-mips`` executes 32-bit big endian MIPS binaries (MIPS O32 ABI).
 150
 151    * ``qemu-mipsel`` executes 32-bit little endian MIPS binaries (MIPS O32 ABI).
 152
 153    * ``qemu-mips64`` executes 64-bit big endian MIPS binaries (MIPS N64 ABI).
 154
 155    * ``qemu-mips64el`` executes 64-bit little endian MIPS binaries (MIPS N64
 156      ABI).
 157
 158    * ``qemu-mipsn32`` executes 32-bit big endian MIPS binaries (MIPS N32 ABI).
 159
 160    * ``qemu-mipsn32el`` executes 32-bit little endian MIPS binaries (MIPS N32
 161      ABI).
 162
 163 -  user mode (NiosII)
 164
 165    * ``qemu-nios2`` TODO.
 166
 167 -  user mode (PowerPC)
 168
 169    * ``qemu-ppc64abi32`` TODO.
 170    * ``qemu-ppc64`` TODO.
 171    * ``qemu-ppc`` TODO.
 172
 173 -  user mode (SH4)
 174
 175    * ``qemu-sh4eb`` TODO.
 176    * ``qemu-sh4`` TODO.
 177
 178 -  user mode (SPARC)
 179
 180    * ``qemu-sparc`` can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
 181
 182    * ``qemu-sparc32plus`` can execute Sparc32 and SPARC32PLUS binaries
 183      (Sparc64 CPU, 32 bit ABI).
 184
 185    * ``qemu-sparc64`` can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
 186      SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
 187
 188 BSD User space emulator
 189 -----------------------
 190
 191 BSD Status
 192 ~~~~~~~~~~
 193
 194 -  target Sparc64 on Sparc64: Some trivial programs work.
 195
 196 Quick Start
 197 ~~~~~~~~~~~
 198
 199 In order to launch a BSD process, QEMU needs the process executable
 200 itself and all the target dynamic libraries used by it.
 201
 202 -  On Sparc64, you can just try to launch any process by using the
 203    native libraries::
 204
 205       qemu-sparc64 /bin/ls
 206
 207 Command line options
 208 ~~~~~~~~~~~~~~~~~~~~
 209
 210 ::
 211
 212    qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
 213
 214 ``-h``
 215    Print the help
 216
 217 ``-L path``
 218    Set the library root path (default=/)
 219
 220 ``-s size``
 221    Set the stack size in bytes (default=524288)
 222
 223 ``-ignore-environment``
 224    Start with an empty environment. Without this option, the initial
 225    environment is a copy of the caller's environment.
 226
 227 ``-E var=value``
 228    Set environment var to value.
 229
 230 ``-U var``
 231    Remove var from the environment.
 232
 233 ``-bsd type``
 234    Set the type of the emulated BSD Operating system. Valid values are
 235    FreeBSD, NetBSD and OpenBSD (default).
 236
 237 Debug options:
 238
 239 ``-d item1,...``
 240    Activate logging of the specified items (use '-d help' for a list of
 241    log items)
 242
 243 ``-p pagesize``
 244    Act as if the host page size was 'pagesize' bytes
 245
 246 ``-singlestep``
 247    Run the emulation in single step mode.