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