Annotation of qemu/qemu-doc.texi, revision 1.1.1.13

1.1       root        1: \input texinfo @c -*- texinfo -*-
1.1.1.3   root        2: @c %**start of header
                      3: @setfilename qemu-doc.info
1.1.1.11  root        4: 
                      5: @documentlanguage en
                      6: @documentencoding UTF-8
                      7: 
1.1.1.5   root        8: @settitle QEMU Emulator User Documentation
1.1.1.3   root        9: @exampleindent 0
                     10: @paragraphindent 0
                     11: @c %**end of header
1.1       root       12: 
1.1.1.11  root       13: @ifinfo
                     14: @direntry
                     15: * QEMU: (qemu-doc).    The QEMU Emulator User Documentation.
                     16: @end direntry
                     17: @end ifinfo
                     18: 
1.1       root       19: @iftex
                     20: @titlepage
                     21: @sp 7
1.1.1.5   root       22: @center @titlefont{QEMU Emulator}
1.1.1.3   root       23: @sp 1
                     24: @center @titlefont{User Documentation}
1.1       root       25: @sp 3
                     26: @end titlepage
                     27: @end iftex
                     28: 
1.1.1.3   root       29: @ifnottex
                     30: @node Top
                     31: @top
                     32: 
                     33: @menu
                     34: * Introduction::
                     35: * Installation::
                     36: * QEMU PC System emulator::
                     37: * QEMU System emulator for non PC targets::
1.1.1.5   root       38: * QEMU User space emulator::
1.1.1.3   root       39: * compilation:: Compilation from the sources
1.1.1.11  root       40: * License::
1.1.1.3   root       41: * Index::
                     42: @end menu
                     43: @end ifnottex
                     44: 
                     45: @contents
                     46: 
                     47: @node Introduction
1.1       root       48: @chapter Introduction
                     49: 
1.1.1.3   root       50: @menu
                     51: * intro_features:: Features
                     52: @end menu
                     53: 
                     54: @node intro_features
1.1       root       55: @section Features
                     56: 
                     57: QEMU is a FAST! processor emulator using dynamic translation to
                     58: achieve good emulation speed.
                     59: 
                     60: QEMU has two operating modes:
                     61: 
1.1.1.11  root       62: @itemize
                     63: @cindex operating modes
1.1       root       64: 
1.1.1.6   root       65: @item
1.1.1.11  root       66: @cindex system emulation
1.1       root       67: Full system emulation. In this mode, QEMU emulates a full system (for
1.1.1.2   root       68: example a PC), including one or several processors and various
                     69: peripherals. It can be used to launch different Operating Systems
                     70: without rebooting the PC or to debug system code.
1.1       root       71: 
1.1.1.6   root       72: @item
1.1.1.11  root       73: @cindex user mode emulation
1.1.1.5   root       74: User mode emulation. In this mode, QEMU can launch
                     75: processes compiled for one CPU on another CPU. It can be used to
1.1       root       76: launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
                     77: to ease cross-compilation and cross-debugging.
                     78: 
                     79: @end itemize
                     80: 
                     81: QEMU can run without an host kernel driver and yet gives acceptable
1.1.1.6   root       82: performance.
1.1       root       83: 
                     84: For system emulation, the following hardware targets are supported:
                     85: @itemize
1.1.1.11  root       86: @cindex emulated target systems
                     87: @cindex supported target systems
1.1       root       88: @item PC (x86 or x86_64 processor)
1.1.1.2   root       89: @item ISA PC (old style PC without PCI bus)
1.1       root       90: @item PREP (PowerPC processor)
1.1.1.7   root       91: @item G3 Beige PowerMac (PowerPC processor)
1.1       root       92: @item Mac99 PowerMac (PowerPC processor, in progress)
1.1.1.6   root       93: @item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
1.1.1.7   root       94: @item Sun4u/Sun4v (64-bit Sparc processor, in progress)
1.1.1.6   root       95: @item Malta board (32-bit and 64-bit MIPS processors)
1.1.1.7   root       96: @item MIPS Magnum (64-bit MIPS processor)
1.1.1.6   root       97: @item ARM Integrator/CP (ARM)
                     98: @item ARM Versatile baseboard (ARM)
1.1.1.10  root       99: @item ARM RealView Emulation/Platform baseboard (ARM)
1.1.1.7   root      100: @item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
1.1.1.6   root      101: @item Luminary Micro LM3S811EVB (ARM Cortex-M3)
                    102: @item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
                    103: @item Freescale MCF5208EVB (ColdFire V2).
                    104: @item Arnewsh MCF5206 evaluation board (ColdFire V2).
                    105: @item Palm Tungsten|E PDA (OMAP310 processor)
1.1.1.7   root      106: @item N800 and N810 tablets (OMAP2420 processor)
                    107: @item MusicPal (MV88W8618 ARM processor)
                    108: @item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
                    109: @item Siemens SX1 smartphone (OMAP310 processor)
1.1.1.9   root      110: @item Syborg SVP base model (ARM Cortex-A8).
                    111: @item AXIS-Devboard88 (CRISv32 ETRAX-FS).
                    112: @item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).
1.1       root      113: @end itemize
                    114: 
1.1.1.11  root      115: @cindex supported user mode targets
                    116: For user emulation, x86 (32 and 64 bit), PowerPC (32 and 64 bit),
                    117: ARM, MIPS (32 bit only), Sparc (32 and 64 bit),
                    118: Alpha, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
1.1       root      119: 
1.1.1.3   root      120: @node Installation
1.1       root      121: @chapter Installation
                    122: 
                    123: If you want to compile QEMU yourself, see @ref{compilation}.
                    124: 
1.1.1.3   root      125: @menu
                    126: * install_linux::   Linux
                    127: * install_windows:: Windows
                    128: * install_mac::     Macintosh
                    129: @end menu
                    130: 
                    131: @node install_linux
1.1       root      132: @section Linux
1.1.1.11  root      133: @cindex installation (Linux)
1.1       root      134: 
                    135: If a precompiled package is available for your distribution - you just
                    136: have to install it. Otherwise, see @ref{compilation}.
                    137: 
1.1.1.3   root      138: @node install_windows
1.1       root      139: @section Windows
1.1.1.11  root      140: @cindex installation (Windows)
1.1       root      141: 
                    142: Download the experimental binary installer at
1.1.1.3   root      143: @url{http://www.free.oszoo.org/@/download.html}.
1.1.1.11  root      144: TODO (no longer available)
1.1       root      145: 
1.1.1.3   root      146: @node install_mac
1.1       root      147: @section Mac OS X
                    148: 
                    149: Download the experimental binary installer at
1.1.1.3   root      150: @url{http://www.free.oszoo.org/@/download.html}.
1.1.1.11  root      151: TODO (no longer available)
1.1       root      152: 
1.1.1.3   root      153: @node QEMU PC System emulator
1.1.1.2   root      154: @chapter QEMU PC System emulator
1.1.1.11  root      155: @cindex system emulation (PC)
1.1       root      156: 
1.1.1.3   root      157: @menu
                    158: * pcsys_introduction:: Introduction
                    159: * pcsys_quickstart::   Quick Start
                    160: * sec_invocation::     Invocation
                    161: * pcsys_keys::         Keys
                    162: * pcsys_monitor::      QEMU Monitor
                    163: * disk_images::        Disk Images
                    164: * pcsys_network::      Network emulation
1.1.1.12  root      165: * pcsys_other_devs::   Other Devices
1.1.1.3   root      166: * direct_linux_boot::  Direct Linux Boot
                    167: * pcsys_usb::          USB emulation
1.1.1.6   root      168: * vnc_security::       VNC security
1.1.1.3   root      169: * gdb_usage::          GDB usage
                    170: * pcsys_os_specific::  Target OS specific information
                    171: @end menu
                    172: 
                    173: @node pcsys_introduction
1.1       root      174: @section Introduction
                    175: 
                    176: @c man begin DESCRIPTION
                    177: 
1.1.1.2   root      178: The QEMU PC System emulator simulates the
                    179: following peripherals:
1.1       root      180: 
                    181: @itemize @minus
1.1.1.6   root      182: @item
1.1       root      183: i440FX host PCI bridge and PIIX3 PCI to ISA bridge
                    184: @item
                    185: Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
                    186: extensions (hardware level, including all non standard modes).
                    187: @item
                    188: PS/2 mouse and keyboard
1.1.1.6   root      189: @item
1.1       root      190: 2 PCI IDE interfaces with hard disk and CD-ROM support
                    191: @item
                    192: Floppy disk
1.1.1.6   root      193: @item
1.1.1.9   root      194: PCI and ISA network adapters
1.1       root      195: @item
                    196: Serial ports
                    197: @item
1.1.1.2   root      198: Creative SoundBlaster 16 sound card
                    199: @item
                    200: ENSONIQ AudioPCI ES1370 sound card
                    201: @item
1.1.1.7   root      202: Intel 82801AA AC97 Audio compatible sound card
                    203: @item
1.1.1.12  root      204: Intel HD Audio Controller and HDA codec
                    205: @item
                    206: Adlib (OPL2) - Yamaha YM3812 compatible chip
1.1.1.2   root      207: @item
1.1.1.7   root      208: Gravis Ultrasound GF1 sound card
                    209: @item
                    210: CS4231A compatible sound card
                    211: @item
1.1.1.2   root      212: PCI UHCI USB controller and a virtual USB hub.
1.1       root      213: @end itemize
                    214: 
1.1.1.2   root      215: SMP is supported with up to 255 CPUs.
                    216: 
1.1.1.7   root      217: Note that adlib, gus and cs4231a are only available when QEMU was
                    218: configured with --audio-card-list option containing the name(s) of
                    219: required card(s).
1.1.1.2   root      220: 
1.1       root      221: QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
                    222: VGA BIOS.
                    223: 
1.1.1.2   root      224: QEMU uses YM3812 emulation by Tatsuyuki Satoh.
                    225: 
1.1.1.12  root      226: QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
1.1.1.7   root      227: by Tibor "TS" Schütz.
                    228: 
1.1.1.10  root      229: Not that, by default, GUS shares IRQ(7) with parallel ports and so
                    230: qemu must be told to not have parallel ports to have working GUS
                    231: 
                    232: @example
                    233: qemu dos.img -soundhw gus -parallel none
                    234: @end example
                    235: 
                    236: Alternatively:
                    237: @example
                    238: qemu dos.img -device gus,irq=5
                    239: @end example
                    240: 
                    241: Or some other unclaimed IRQ.
                    242: 
1.1.1.7   root      243: CS4231A is the chip used in Windows Sound System and GUSMAX products
                    244: 
1.1       root      245: @c man end
                    246: 
1.1.1.3   root      247: @node pcsys_quickstart
1.1       root      248: @section Quick Start
1.1.1.11  root      249: @cindex quick start
1.1       root      250: 
                    251: Download and uncompress the linux image (@file{linux.img}) and type:
                    252: 
                    253: @example
                    254: qemu linux.img
                    255: @end example
                    256: 
                    257: Linux should boot and give you a prompt.
                    258: 
                    259: @node sec_invocation
                    260: @section Invocation
                    261: 
                    262: @example
                    263: @c man begin SYNOPSIS
1.1.1.6   root      264: usage: qemu [options] [@var{disk_image}]
1.1       root      265: @c man end
                    266: @end example
                    267: 
                    268: @c man begin OPTIONS
1.1.1.7   root      269: @var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
                    270: targets do not need a disk image.
1.1       root      271: 
1.1.1.9   root      272: @include qemu-options.texi
1.1       root      273: 
                    274: @c man end
                    275: 
1.1.1.3   root      276: @node pcsys_keys
1.1       root      277: @section Keys
                    278: 
                    279: @c man begin OPTIONS
                    280: 
1.1.1.13! root      281: During the graphical emulation, you can use special key combinations to change
        !           282: modes. The default key mappings are shown below, but if you use @code{-alt-grab}
        !           283: then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
        !           284: @code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
        !           285: 
1.1       root      286: @table @key
                    287: @item Ctrl-Alt-f
1.1.1.11  root      288: @kindex Ctrl-Alt-f
1.1       root      289: Toggle full screen
                    290: 
1.1.1.10  root      291: @item Ctrl-Alt-u
1.1.1.11  root      292: @kindex Ctrl-Alt-u
1.1.1.10  root      293: Restore the screen's un-scaled dimensions
                    294: 
1.1       root      295: @item Ctrl-Alt-n
1.1.1.11  root      296: @kindex Ctrl-Alt-n
1.1       root      297: Switch to virtual console 'n'. Standard console mappings are:
                    298: @table @emph
                    299: @item 1
                    300: Target system display
                    301: @item 2
                    302: Monitor
                    303: @item 3
                    304: Serial port
                    305: @end table
                    306: 
                    307: @item Ctrl-Alt
1.1.1.11  root      308: @kindex Ctrl-Alt
1.1       root      309: Toggle mouse and keyboard grab.
                    310: @end table
                    311: 
1.1.1.11  root      312: @kindex Ctrl-Up
                    313: @kindex Ctrl-Down
                    314: @kindex Ctrl-PageUp
                    315: @kindex Ctrl-PageDown
1.1       root      316: In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
                    317: @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
                    318: 
1.1.1.11  root      319: @kindex Ctrl-a h
1.1       root      320: During emulation, if you are using the @option{-nographic} option, use
                    321: @key{Ctrl-a h} to get terminal commands:
                    322: 
                    323: @table @key
                    324: @item Ctrl-a h
1.1.1.11  root      325: @kindex Ctrl-a h
1.1.1.7   root      326: @item Ctrl-a ?
1.1.1.11  root      327: @kindex Ctrl-a ?
1.1       root      328: Print this help
1.1.1.6   root      329: @item Ctrl-a x
1.1.1.11  root      330: @kindex Ctrl-a x
1.1.1.5   root      331: Exit emulator
1.1.1.6   root      332: @item Ctrl-a s
1.1.1.11  root      333: @kindex Ctrl-a s
1.1       root      334: Save disk data back to file (if -snapshot)
1.1.1.6   root      335: @item Ctrl-a t
1.1.1.11  root      336: @kindex Ctrl-a t
1.1.1.7   root      337: Toggle console timestamps
1.1       root      338: @item Ctrl-a b
1.1.1.11  root      339: @kindex Ctrl-a b
1.1       root      340: Send break (magic sysrq in Linux)
                    341: @item Ctrl-a c
1.1.1.11  root      342: @kindex Ctrl-a c
1.1       root      343: Switch between console and monitor
                    344: @item Ctrl-a Ctrl-a
1.1.1.11  root      345: @kindex Ctrl-a a
1.1       root      346: Send Ctrl-a
                    347: @end table
                    348: @c man end
                    349: 
                    350: @ignore
                    351: 
                    352: @c man begin SEEALSO
                    353: The HTML documentation of QEMU for more precise information and Linux
                    354: user mode emulator invocation.
                    355: @c man end
                    356: 
                    357: @c man begin AUTHOR
                    358: Fabrice Bellard
                    359: @c man end
                    360: 
                    361: @end ignore
                    362: 
1.1.1.3   root      363: @node pcsys_monitor
1.1       root      364: @section QEMU Monitor
1.1.1.11  root      365: @cindex QEMU monitor
1.1       root      366: 
                    367: The QEMU monitor is used to give complex commands to the QEMU
                    368: emulator. You can use it to:
                    369: 
                    370: @itemize @minus
                    371: 
                    372: @item
1.1.1.6   root      373: Remove or insert removable media images
                    374: (such as CD-ROM or floppies).
1.1       root      375: 
1.1.1.6   root      376: @item
1.1       root      377: Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
                    378: from a disk file.
                    379: 
                    380: @item Inspect the VM state without an external debugger.
                    381: 
                    382: @end itemize
                    383: 
                    384: @subsection Commands
                    385: 
                    386: The following commands are available:
                    387: 
1.1.1.9   root      388: @include qemu-monitor.texi
1.1       root      389: 
                    390: @subsection Integer expressions
                    391: 
                    392: The monitor understands integers expressions for every integer
                    393: argument. You can use register names to get the value of specifics
                    394: CPU registers by prefixing them with @emph{$}.
                    395: 
                    396: @node disk_images
                    397: @section Disk Images
                    398: 
                    399: Since version 0.6.1, QEMU supports many disk image formats, including
                    400: growable disk images (their size increase as non empty sectors are
1.1.1.5   root      401: written), compressed and encrypted disk images. Version 0.8.3 added
                    402: the new qcow2 disk image format which is essential to support VM
                    403: snapshots.
1.1       root      404: 
1.1.1.3   root      405: @menu
                    406: * disk_images_quickstart::    Quick start for disk image creation
                    407: * disk_images_snapshot_mode:: Snapshot mode
1.1.1.5   root      408: * vm_snapshots::              VM snapshots
1.1.1.3   root      409: * qemu_img_invocation::       qemu-img Invocation
1.1.1.7   root      410: * qemu_nbd_invocation::       qemu-nbd Invocation
1.1.1.5   root      411: * host_drives::               Using host drives
1.1.1.3   root      412: * disk_images_fat_images::    Virtual FAT disk images
1.1.1.7   root      413: * disk_images_nbd::           NBD access
1.1.1.12  root      414: * disk_images_sheepdog::      Sheepdog disk images
1.1.1.3   root      415: @end menu
                    416: 
                    417: @node disk_images_quickstart
1.1       root      418: @subsection Quick start for disk image creation
                    419: 
                    420: You can create a disk image with the command:
                    421: @example
                    422: qemu-img create myimage.img mysize
                    423: @end example
                    424: where @var{myimage.img} is the disk image filename and @var{mysize} is its
                    425: size in kilobytes. You can add an @code{M} suffix to give the size in
                    426: megabytes and a @code{G} suffix for gigabytes.
                    427: 
1.1.1.3   root      428: See @ref{qemu_img_invocation} for more information.
1.1       root      429: 
1.1.1.3   root      430: @node disk_images_snapshot_mode
1.1       root      431: @subsection Snapshot mode
                    432: 
                    433: If you use the option @option{-snapshot}, all disk images are
                    434: considered as read only. When sectors in written, they are written in
                    435: a temporary file created in @file{/tmp}. You can however force the
                    436: write back to the raw disk images by using the @code{commit} monitor
                    437: command (or @key{C-a s} in the serial console).
                    438: 
1.1.1.5   root      439: @node vm_snapshots
                    440: @subsection VM snapshots
                    441: 
                    442: VM snapshots are snapshots of the complete virtual machine including
                    443: CPU state, RAM, device state and the content of all the writable
                    444: disks. In order to use VM snapshots, you must have at least one non
                    445: removable and writable block device using the @code{qcow2} disk image
                    446: format. Normally this device is the first virtual hard drive.
                    447: 
                    448: Use the monitor command @code{savevm} to create a new VM snapshot or
                    449: replace an existing one. A human readable name can be assigned to each
                    450: snapshot in addition to its numerical ID.
                    451: 
                    452: Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
                    453: a VM snapshot. @code{info snapshots} lists the available snapshots
                    454: with their associated information:
                    455: 
                    456: @example
                    457: (qemu) info snapshots
                    458: Snapshot devices: hda
                    459: Snapshot list (from hda):
                    460: ID        TAG                 VM SIZE                DATE       VM CLOCK
                    461: 1         start                   41M 2006-08-06 12:38:02   00:00:14.954
                    462: 2                                 40M 2006-08-06 12:43:29   00:00:18.633
                    463: 3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
                    464: @end example
                    465: 
                    466: A VM snapshot is made of a VM state info (its size is shown in
                    467: @code{info snapshots}) and a snapshot of every writable disk image.
                    468: The VM state info is stored in the first @code{qcow2} non removable
                    469: and writable block device. The disk image snapshots are stored in
                    470: every disk image. The size of a snapshot in a disk image is difficult
                    471: to evaluate and is not shown by @code{info snapshots} because the
                    472: associated disk sectors are shared among all the snapshots to save
                    473: disk space (otherwise each snapshot would need a full copy of all the
                    474: disk images).
                    475: 
                    476: When using the (unrelated) @code{-snapshot} option
                    477: (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
                    478: but they are deleted as soon as you exit QEMU.
                    479: 
                    480: VM snapshots currently have the following known limitations:
                    481: @itemize
1.1.1.6   root      482: @item
1.1.1.5   root      483: They cannot cope with removable devices if they are removed or
                    484: inserted after a snapshot is done.
1.1.1.6   root      485: @item
1.1.1.5   root      486: A few device drivers still have incomplete snapshot support so their
                    487: state is not saved or restored properly (in particular USB).
                    488: @end itemize
                    489: 
1.1       root      490: @node qemu_img_invocation
                    491: @subsection @code{qemu-img} Invocation
                    492: 
                    493: @include qemu-img.texi
                    494: 
1.1.1.7   root      495: @node qemu_nbd_invocation
                    496: @subsection @code{qemu-nbd} Invocation
                    497: 
                    498: @include qemu-nbd.texi
                    499: 
1.1.1.5   root      500: @node host_drives
                    501: @subsection Using host drives
                    502: 
                    503: In addition to disk image files, QEMU can directly access host
                    504: devices. We describe here the usage for QEMU version >= 0.8.3.
                    505: 
                    506: @subsubsection Linux
                    507: 
                    508: On Linux, you can directly use the host device filename instead of a
1.1.1.6   root      509: disk image filename provided you have enough privileges to access
1.1.1.5   root      510: it. For example, use @file{/dev/cdrom} to access to the CDROM or
                    511: @file{/dev/fd0} for the floppy.
                    512: 
                    513: @table @code
                    514: @item CD
                    515: You can specify a CDROM device even if no CDROM is loaded. QEMU has
                    516: specific code to detect CDROM insertion or removal. CDROM ejection by
                    517: the guest OS is supported. Currently only data CDs are supported.
                    518: @item Floppy
                    519: You can specify a floppy device even if no floppy is loaded. Floppy
                    520: removal is currently not detected accurately (if you change floppy
                    521: without doing floppy access while the floppy is not loaded, the guest
                    522: OS will think that the same floppy is loaded).
                    523: @item Hard disks
                    524: Hard disks can be used. Normally you must specify the whole disk
                    525: (@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
                    526: see it as a partitioned disk. WARNING: unless you know what you do, it
                    527: is better to only make READ-ONLY accesses to the hard disk otherwise
                    528: you may corrupt your host data (use the @option{-snapshot} command
                    529: line option or modify the device permissions accordingly).
                    530: @end table
                    531: 
                    532: @subsubsection Windows
                    533: 
                    534: @table @code
                    535: @item CD
1.1.1.6   root      536: The preferred syntax is the drive letter (e.g. @file{d:}). The
1.1.1.5   root      537: alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
                    538: supported as an alias to the first CDROM drive.
                    539: 
1.1.1.6   root      540: Currently there is no specific code to handle removable media, so it
1.1.1.5   root      541: is better to use the @code{change} or @code{eject} monitor commands to
                    542: change or eject media.
                    543: @item Hard disks
1.1.1.6   root      544: Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
1.1.1.5   root      545: where @var{N} is the drive number (0 is the first hard disk).
                    546: 
                    547: WARNING: unless you know what you do, it is better to only make
                    548: READ-ONLY accesses to the hard disk otherwise you may corrupt your
                    549: host data (use the @option{-snapshot} command line so that the
                    550: modifications are written in a temporary file).
                    551: @end table
                    552: 
                    553: 
                    554: @subsubsection Mac OS X
                    555: 
1.1.1.6   root      556: @file{/dev/cdrom} is an alias to the first CDROM.
1.1.1.5   root      557: 
1.1.1.6   root      558: Currently there is no specific code to handle removable media, so it
1.1.1.5   root      559: is better to use the @code{change} or @code{eject} monitor commands to
                    560: change or eject media.
                    561: 
1.1.1.3   root      562: @node disk_images_fat_images
1.1.1.2   root      563: @subsection Virtual FAT disk images
                    564: 
                    565: QEMU can automatically create a virtual FAT disk image from a
                    566: directory tree. In order to use it, just type:
                    567: 
1.1.1.6   root      568: @example
1.1.1.2   root      569: qemu linux.img -hdb fat:/my_directory
                    570: @end example
                    571: 
                    572: Then you access access to all the files in the @file{/my_directory}
                    573: directory without having to copy them in a disk image or to export
                    574: them via SAMBA or NFS. The default access is @emph{read-only}.
1.1       root      575: 
1.1.1.2   root      576: Floppies can be emulated with the @code{:floppy:} option:
1.1       root      577: 
1.1.1.6   root      578: @example
1.1.1.2   root      579: qemu linux.img -fda fat:floppy:/my_directory
                    580: @end example
1.1       root      581: 
1.1.1.2   root      582: A read/write support is available for testing (beta stage) with the
                    583: @code{:rw:} option:
                    584: 
1.1.1.6   root      585: @example
1.1.1.2   root      586: qemu linux.img -fda fat:floppy:rw:/my_directory
                    587: @end example
                    588: 
                    589: What you should @emph{never} do:
                    590: @itemize
                    591: @item use non-ASCII filenames ;
                    592: @item use "-snapshot" together with ":rw:" ;
                    593: @item expect it to work when loadvm'ing ;
                    594: @item write to the FAT directory on the host system while accessing it with the guest system.
                    595: @end itemize
                    596: 
1.1.1.7   root      597: @node disk_images_nbd
                    598: @subsection NBD access
                    599: 
                    600: QEMU can access directly to block device exported using the Network Block Device
                    601: protocol.
                    602: 
                    603: @example
                    604: qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
                    605: @end example
                    606: 
                    607: If the NBD server is located on the same host, you can use an unix socket instead
                    608: of an inet socket:
                    609: 
                    610: @example
                    611: qemu linux.img -hdb nbd:unix:/tmp/my_socket
                    612: @end example
                    613: 
                    614: In this case, the block device must be exported using qemu-nbd:
                    615: 
                    616: @example
                    617: qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
                    618: @end example
                    619: 
                    620: The use of qemu-nbd allows to share a disk between several guests:
                    621: @example
                    622: qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
                    623: @end example
                    624: 
                    625: and then you can use it with two guests:
                    626: @example
                    627: qemu linux1.img -hdb nbd:unix:/tmp/my_socket
                    628: qemu linux2.img -hdb nbd:unix:/tmp/my_socket
                    629: @end example
                    630: 
1.1.1.12  root      631: If the nbd-server uses named exports (since NBD 2.9.18), you must use the
                    632: "exportname" option:
                    633: @example
                    634: qemu -cdrom nbd:localhost:exportname=debian-500-ppc-netinst
                    635: qemu -cdrom nbd:localhost:exportname=openSUSE-11.1-ppc-netinst
                    636: @end example
                    637: 
                    638: @node disk_images_sheepdog
                    639: @subsection Sheepdog disk images
                    640: 
                    641: Sheepdog is a distributed storage system for QEMU.  It provides highly
                    642: available block level storage volumes that can be attached to
                    643: QEMU-based virtual machines.
                    644: 
                    645: You can create a Sheepdog disk image with the command:
                    646: @example
                    647: qemu-img create sheepdog:@var{image} @var{size}
                    648: @end example
                    649: where @var{image} is the Sheepdog image name and @var{size} is its
                    650: size.
                    651: 
                    652: To import the existing @var{filename} to Sheepdog, you can use a
                    653: convert command.
                    654: @example
                    655: qemu-img convert @var{filename} sheepdog:@var{image}
                    656: @end example
                    657: 
                    658: You can boot from the Sheepdog disk image with the command:
                    659: @example
                    660: qemu sheepdog:@var{image}
                    661: @end example
                    662: 
                    663: You can also create a snapshot of the Sheepdog image like qcow2.
                    664: @example
                    665: qemu-img snapshot -c @var{tag} sheepdog:@var{image}
                    666: @end example
                    667: where @var{tag} is a tag name of the newly created snapshot.
                    668: 
                    669: To boot from the Sheepdog snapshot, specify the tag name of the
                    670: snapshot.
                    671: @example
                    672: qemu sheepdog:@var{image}:@var{tag}
                    673: @end example
                    674: 
                    675: You can create a cloned image from the existing snapshot.
                    676: @example
                    677: qemu-img create -b sheepdog:@var{base}:@var{tag} sheepdog:@var{image}
                    678: @end example
                    679: where @var{base} is a image name of the source snapshot and @var{tag}
                    680: is its tag name.
                    681: 
                    682: If the Sheepdog daemon doesn't run on the local host, you need to
                    683: specify one of the Sheepdog servers to connect to.
                    684: @example
                    685: qemu-img create sheepdog:@var{hostname}:@var{port}:@var{image} @var{size}
                    686: qemu sheepdog:@var{hostname}:@var{port}:@var{image}
                    687: @end example
                    688: 
1.1.1.3   root      689: @node pcsys_network
1.1.1.2   root      690: @section Network emulation
                    691: 
1.1.1.6   root      692: QEMU can simulate several network cards (PCI or ISA cards on the PC
1.1.1.2   root      693: target) and can connect them to an arbitrary number of Virtual Local
                    694: Area Networks (VLANs). Host TAP devices can be connected to any QEMU
                    695: VLAN. VLAN can be connected between separate instances of QEMU to
1.1.1.6   root      696: simulate large networks. For simpler usage, a non privileged user mode
1.1.1.2   root      697: network stack can replace the TAP device to have a basic network
                    698: connection.
                    699: 
                    700: @subsection VLANs
                    701: 
                    702: QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
                    703: connection between several network devices. These devices can be for
                    704: example QEMU virtual Ethernet cards or virtual Host ethernet devices
                    705: (TAP devices).
                    706: 
                    707: @subsection Using TAP network interfaces
                    708: 
                    709: This is the standard way to connect QEMU to a real network. QEMU adds
                    710: a virtual network device on your host (called @code{tapN}), and you
                    711: can then configure it as if it was a real ethernet card.
1.1       root      712: 
1.1.1.5   root      713: @subsubsection Linux host
                    714: 
1.1       root      715: As an example, you can download the @file{linux-test-xxx.tar.gz}
                    716: archive and copy the script @file{qemu-ifup} in @file{/etc} and
                    717: configure properly @code{sudo} so that the command @code{ifconfig}
                    718: contained in @file{qemu-ifup} can be executed as root. You must verify
1.1.1.2   root      719: that your host kernel supports the TAP network interfaces: the
1.1       root      720: device @file{/dev/net/tun} must be present.
                    721: 
1.1.1.5   root      722: See @ref{sec_invocation} to have examples of command lines using the
                    723: TAP network interfaces.
                    724: 
                    725: @subsubsection Windows host
                    726: 
                    727: There is a virtual ethernet driver for Windows 2000/XP systems, called
                    728: TAP-Win32. But it is not included in standard QEMU for Windows,
                    729: so you will need to get it separately. It is part of OpenVPN package,
                    730: so download OpenVPN from : @url{http://openvpn.net/}.
1.1       root      731: 
                    732: @subsection Using the user mode network stack
                    733: 
1.1.1.2   root      734: By using the option @option{-net user} (default configuration if no
                    735: @option{-net} option is specified), QEMU uses a completely user mode
1.1.1.6   root      736: network stack (you don't need root privilege to use the virtual
1.1.1.2   root      737: network). The virtual network configuration is the following:
1.1       root      738: 
                    739: @example
                    740: 
1.1.1.2   root      741:          QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
                    742:                            |          (10.0.2.2)
1.1       root      743:                            |
                    744:                            ---->  DNS server (10.0.2.3)
1.1.1.6   root      745:                            |
1.1       root      746:                            ---->  SMB server (10.0.2.4)
                    747: @end example
                    748: 
                    749: The QEMU VM behaves as if it was behind a firewall which blocks all
                    750: incoming connections. You can use a DHCP client to automatically
1.1.1.2   root      751: configure the network in the QEMU VM. The DHCP server assign addresses
                    752: to the hosts starting from 10.0.2.15.
1.1       root      753: 
                    754: In order to check that the user mode network is working, you can ping
                    755: the address 10.0.2.2 and verify that you got an address in the range
                    756: 10.0.2.x from the QEMU virtual DHCP server.
                    757: 
                    758: Note that @code{ping} is not supported reliably to the internet as it
1.1.1.6   root      759: would require root privileges. It means you can only ping the local
1.1       root      760: router (10.0.2.2).
                    761: 
                    762: When using the built-in TFTP server, the router is also the TFTP
                    763: server.
                    764: 
                    765: When using the @option{-redir} option, TCP or UDP connections can be
                    766: redirected from the host to the guest. It allows for example to
                    767: redirect X11, telnet or SSH connections.
                    768: 
1.1.1.2   root      769: @subsection Connecting VLANs between QEMU instances
                    770: 
                    771: Using the @option{-net socket} option, it is possible to make VLANs
                    772: that span several QEMU instances. See @ref{sec_invocation} to have a
                    773: basic example.
                    774: 
1.1.1.12  root      775: @node pcsys_other_devs
1.1.1.11  root      776: @section Other Devices
                    777: 
                    778: @subsection Inter-VM Shared Memory device
                    779: 
                    780: With KVM enabled on a Linux host, a shared memory device is available.  Guests
                    781: map a POSIX shared memory region into the guest as a PCI device that enables
                    782: zero-copy communication to the application level of the guests.  The basic
                    783: syntax is:
                    784: 
                    785: @example
                    786: qemu -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>]
                    787: @end example
                    788: 
                    789: If desired, interrupts can be sent between guest VMs accessing the same shared
                    790: memory region.  Interrupt support requires using a shared memory server and
                    791: using a chardev socket to connect to it.  The code for the shared memory server
                    792: is qemu.git/contrib/ivshmem-server.  An example syntax when using the shared
                    793: memory server is:
                    794: 
                    795: @example
                    796: qemu -device ivshmem,size=<size in format accepted by -m>[,chardev=<id>]
                    797:                         [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master]
                    798: qemu -chardev socket,path=<path>,id=<id>
                    799: @end example
                    800: 
                    801: When using the server, the guest will be assigned a VM ID (>=0) that allows guests
                    802: using the same server to communicate via interrupts.  Guests can read their
                    803: VM ID from a device register (see example code).  Since receiving the shared
                    804: memory region from the server is asynchronous, there is a (small) chance the
                    805: guest may boot before the shared memory is attached.  To allow an application
                    806: to ensure shared memory is attached, the VM ID register will return -1 (an
                    807: invalid VM ID) until the memory is attached.  Once the shared memory is
                    808: attached, the VM ID will return the guest's valid VM ID.  With these semantics,
                    809: the guest application can check to ensure the shared memory is attached to the
                    810: guest before proceeding.
                    811: 
                    812: The @option{role} argument can be set to either master or peer and will affect
                    813: how the shared memory is migrated.  With @option{role=master}, the guest will
                    814: copy the shared memory on migration to the destination host.  With
                    815: @option{role=peer}, the guest will not be able to migrate with the device attached.
                    816: With the @option{peer} case, the device should be detached and then reattached
                    817: after migration using the PCI hotplug support.
                    818: 
1.1       root      819: @node direct_linux_boot
                    820: @section Direct Linux Boot
                    821: 
                    822: This section explains how to launch a Linux kernel inside QEMU without
                    823: having to make a full bootable image. It is very useful for fast Linux
1.1.1.5   root      824: kernel testing.
1.1       root      825: 
1.1.1.5   root      826: The syntax is:
1.1       root      827: @example
1.1.1.5   root      828: qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1.1       root      829: @end example
                    830: 
1.1.1.5   root      831: Use @option{-kernel} to provide the Linux kernel image and
                    832: @option{-append} to give the kernel command line arguments. The
                    833: @option{-initrd} option can be used to provide an INITRD image.
1.1       root      834: 
1.1.1.5   root      835: When using the direct Linux boot, a disk image for the first hard disk
                    836: @file{hda} is required because its boot sector is used to launch the
                    837: Linux kernel.
1.1       root      838: 
1.1.1.5   root      839: If you do not need graphical output, you can disable it and redirect
                    840: the virtual serial port and the QEMU monitor to the console with the
                    841: @option{-nographic} option. The typical command line is:
1.1       root      842: @example
1.1.1.5   root      843: qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
                    844:      -append "root=/dev/hda console=ttyS0" -nographic
1.1       root      845: @end example
                    846: 
1.1.1.5   root      847: Use @key{Ctrl-a c} to switch between the serial console and the
                    848: monitor (@pxref{pcsys_keys}).
1.1       root      849: 
1.1.1.3   root      850: @node pcsys_usb
1.1.1.2   root      851: @section USB emulation
                    852: 
1.1.1.4   root      853: QEMU emulates a PCI UHCI USB controller. You can virtually plug
                    854: virtual USB devices or real host USB devices (experimental, works only
                    855: on Linux hosts).  Qemu will automatically create and connect virtual USB hubs
1.1.1.5   root      856: as necessary to connect multiple USB devices.
1.1.1.2   root      857: 
1.1.1.4   root      858: @menu
                    859: * usb_devices::
                    860: * host_usb_devices::
                    861: @end menu
                    862: @node usb_devices
                    863: @subsection Connecting USB devices
1.1.1.2   root      864: 
1.1.1.4   root      865: USB devices can be connected with the @option{-usbdevice} commandline option
                    866: or the @code{usb_add} monitor command.  Available devices are:
1.1.1.2   root      867: 
1.1.1.7   root      868: @table @code
                    869: @item mouse
1.1.1.4   root      870: Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
1.1.1.7   root      871: @item tablet
1.1.1.5   root      872: Pointer device that uses absolute coordinates (like a touchscreen).
1.1.1.4   root      873: This means qemu is able to report the mouse position without having
                    874: to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
1.1.1.7   root      875: @item disk:@var{file}
1.1.1.4   root      876: Mass storage device based on @var{file} (@pxref{disk_images})
1.1.1.7   root      877: @item host:@var{bus.addr}
1.1.1.4   root      878: Pass through the host device identified by @var{bus.addr}
                    879: (Linux only)
1.1.1.7   root      880: @item host:@var{vendor_id:product_id}
1.1.1.4   root      881: Pass through the host device identified by @var{vendor_id:product_id}
                    882: (Linux only)
1.1.1.7   root      883: @item wacom-tablet
1.1.1.6   root      884: Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
                    885: above but it can be used with the tslib library because in addition to touch
                    886: coordinates it reports touch pressure.
1.1.1.7   root      887: @item keyboard
1.1.1.6   root      888: Standard USB keyboard.  Will override the PS/2 keyboard (if present).
1.1.1.7   root      889: @item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
                    890: Serial converter. This emulates an FTDI FT232BM chip connected to host character
                    891: device @var{dev}. The available character devices are the same as for the
                    892: @code{-serial} option. The @code{vendorid} and @code{productid} options can be
1.1.1.12  root      893: used to override the default 0403:6001. For instance,
1.1.1.7   root      894: @example
                    895: usb_add serial:productid=FA00:tcp:192.168.0.2:4444
                    896: @end example
                    897: will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
                    898: serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
                    899: @item braille
                    900: Braille device.  This will use BrlAPI to display the braille output on a real
                    901: or fake device.
                    902: @item net:@var{options}
                    903: Network adapter that supports CDC ethernet and RNDIS protocols.  @var{options}
                    904: specifies NIC options as with @code{-net nic,}@var{options} (see description).
                    905: For instance, user-mode networking can be used with
                    906: @example
                    907: qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
                    908: @end example
                    909: Currently this cannot be used in machines that support PCI NICs.
                    910: @item bt[:@var{hci-type}]
                    911: Bluetooth dongle whose type is specified in the same format as with
                    912: the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
                    913: no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
                    914: This USB device implements the USB Transport Layer of HCI.  Example
                    915: usage:
                    916: @example
                    917: qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
                    918: @end example
1.1.1.4   root      919: @end table
1.1.1.2   root      920: 
1.1.1.4   root      921: @node host_usb_devices
1.1.1.2   root      922: @subsection Using host USB devices on a Linux host
                    923: 
                    924: WARNING: this is an experimental feature. QEMU will slow down when
                    925: using it. USB devices requiring real time streaming (i.e. USB Video
                    926: Cameras) are not supported yet.
                    927: 
                    928: @enumerate
1.1.1.6   root      929: @item If you use an early Linux 2.4 kernel, verify that no Linux driver
1.1.1.2   root      930: is actually using the USB device. A simple way to do that is simply to
                    931: disable the corresponding kernel module by renaming it from @file{mydriver.o}
                    932: to @file{mydriver.o.disabled}.
                    933: 
                    934: @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
                    935: @example
                    936: ls /proc/bus/usb
                    937: 001  devices  drivers
                    938: @end example
                    939: 
                    940: @item Since only root can access to the USB devices directly, you can either launch QEMU as root or change the permissions of the USB devices you want to use. For testing, the following suffices:
                    941: @example
                    942: chown -R myuid /proc/bus/usb
                    943: @end example
                    944: 
                    945: @item Launch QEMU and do in the monitor:
1.1.1.6   root      946: @example
1.1.1.2   root      947: info usbhost
                    948:   Device 1.2, speed 480 Mb/s
                    949:     Class 00: USB device 1234:5678, USB DISK
                    950: @end example
                    951: You should see the list of the devices you can use (Never try to use
                    952: hubs, it won't work).
                    953: 
                    954: @item Add the device in QEMU by using:
1.1.1.6   root      955: @example
1.1.1.2   root      956: usb_add host:1234:5678
                    957: @end example
                    958: 
                    959: Normally the guest OS should report that a new USB device is
                    960: plugged. You can use the option @option{-usbdevice} to do the same.
                    961: 
                    962: @item Now you can try to use the host USB device in QEMU.
                    963: 
                    964: @end enumerate
                    965: 
                    966: When relaunching QEMU, you may have to unplug and plug again the USB
                    967: device to make it work again (this is a bug).
                    968: 
1.1.1.6   root      969: @node vnc_security
                    970: @section VNC security
                    971: 
                    972: The VNC server capability provides access to the graphical console
                    973: of the guest VM across the network. This has a number of security
                    974: considerations depending on the deployment scenarios.
                    975: 
                    976: @menu
                    977: * vnc_sec_none::
                    978: * vnc_sec_password::
                    979: * vnc_sec_certificate::
                    980: * vnc_sec_certificate_verify::
                    981: * vnc_sec_certificate_pw::
1.1.1.9   root      982: * vnc_sec_sasl::
                    983: * vnc_sec_certificate_sasl::
1.1.1.6   root      984: * vnc_generate_cert::
1.1.1.9   root      985: * vnc_setup_sasl::
1.1.1.6   root      986: @end menu
                    987: @node vnc_sec_none
                    988: @subsection Without passwords
                    989: 
                    990: The simplest VNC server setup does not include any form of authentication.
                    991: For this setup it is recommended to restrict it to listen on a UNIX domain
                    992: socket only. For example
                    993: 
                    994: @example
                    995: qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
                    996: @end example
                    997: 
                    998: This ensures that only users on local box with read/write access to that
                    999: path can access the VNC server. To securely access the VNC server from a
                   1000: remote machine, a combination of netcat+ssh can be used to provide a secure
                   1001: tunnel.
                   1002: 
                   1003: @node vnc_sec_password
                   1004: @subsection With passwords
                   1005: 
                   1006: The VNC protocol has limited support for password based authentication. Since
                   1007: the protocol limits passwords to 8 characters it should not be considered
                   1008: to provide high security. The password can be fairly easily brute-forced by
                   1009: a client making repeat connections. For this reason, a VNC server using password
                   1010: authentication should be restricted to only listen on the loopback interface
1.1.1.7   root     1011: or UNIX domain sockets. Password authentication is requested with the @code{password}
1.1.1.6   root     1012: option, and then once QEMU is running the password is set with the monitor. Until
                   1013: the monitor is used to set the password all clients will be rejected.
                   1014: 
                   1015: @example
                   1016: qemu [...OPTIONS...] -vnc :1,password -monitor stdio
                   1017: (qemu) change vnc password
                   1018: Password: ********
                   1019: (qemu)
                   1020: @end example
                   1021: 
                   1022: @node vnc_sec_certificate
                   1023: @subsection With x509 certificates
                   1024: 
                   1025: The QEMU VNC server also implements the VeNCrypt extension allowing use of
                   1026: TLS for encryption of the session, and x509 certificates for authentication.
                   1027: The use of x509 certificates is strongly recommended, because TLS on its
                   1028: own is susceptible to man-in-the-middle attacks. Basic x509 certificate
                   1029: support provides a secure session, but no authentication. This allows any
                   1030: client to connect, and provides an encrypted session.
                   1031: 
                   1032: @example
                   1033: qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
                   1034: @end example
                   1035: 
                   1036: In the above example @code{/etc/pki/qemu} should contain at least three files,
                   1037: @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
                   1038: users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
                   1039: NB the @code{server-key.pem} file should be protected with file mode 0600 to
                   1040: only be readable by the user owning it.
                   1041: 
                   1042: @node vnc_sec_certificate_verify
                   1043: @subsection With x509 certificates and client verification
                   1044: 
                   1045: Certificates can also provide a means to authenticate the client connecting.
                   1046: The server will request that the client provide a certificate, which it will
                   1047: then validate against the CA certificate. This is a good choice if deploying
                   1048: in an environment with a private internal certificate authority.
                   1049: 
                   1050: @example
                   1051: qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
                   1052: @end example
                   1053: 
                   1054: 
                   1055: @node vnc_sec_certificate_pw
                   1056: @subsection With x509 certificates, client verification and passwords
                   1057: 
                   1058: Finally, the previous method can be combined with VNC password authentication
                   1059: to provide two layers of authentication for clients.
                   1060: 
                   1061: @example
                   1062: qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
                   1063: (qemu) change vnc password
                   1064: Password: ********
                   1065: (qemu)
                   1066: @end example
                   1067: 
1.1.1.9   root     1068: 
                   1069: @node vnc_sec_sasl
                   1070: @subsection With SASL authentication
                   1071: 
                   1072: The SASL authentication method is a VNC extension, that provides an
                   1073: easily extendable, pluggable authentication method. This allows for
                   1074: integration with a wide range of authentication mechanisms, such as
                   1075: PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
                   1076: The strength of the authentication depends on the exact mechanism
                   1077: configured. If the chosen mechanism also provides a SSF layer, then
                   1078: it will encrypt the datastream as well.
                   1079: 
                   1080: Refer to the later docs on how to choose the exact SASL mechanism
                   1081: used for authentication, but assuming use of one supporting SSF,
                   1082: then QEMU can be launched with:
                   1083: 
                   1084: @example
                   1085: qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio
                   1086: @end example
                   1087: 
                   1088: @node vnc_sec_certificate_sasl
                   1089: @subsection With x509 certificates and SASL authentication
                   1090: 
                   1091: If the desired SASL authentication mechanism does not supported
                   1092: SSF layers, then it is strongly advised to run it in combination
                   1093: with TLS and x509 certificates. This provides securely encrypted
                   1094: data stream, avoiding risk of compromising of the security
                   1095: credentials. This can be enabled, by combining the 'sasl' option
                   1096: with the aforementioned TLS + x509 options:
                   1097: 
                   1098: @example
                   1099: qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
                   1100: @end example
                   1101: 
                   1102: 
1.1.1.6   root     1103: @node vnc_generate_cert
                   1104: @subsection Generating certificates for VNC
                   1105: 
                   1106: The GNU TLS packages provides a command called @code{certtool} which can
                   1107: be used to generate certificates and keys in PEM format. At a minimum it
1.1.1.12  root     1108: is necessary to setup a certificate authority, and issue certificates to
1.1.1.6   root     1109: each server. If using certificates for authentication, then each client
                   1110: will also need to be issued a certificate. The recommendation is for the
                   1111: server to keep its certificates in either @code{/etc/pki/qemu} or for
                   1112: unprivileged users in @code{$HOME/.pki/qemu}.
                   1113: 
                   1114: @menu
                   1115: * vnc_generate_ca::
                   1116: * vnc_generate_server::
                   1117: * vnc_generate_client::
                   1118: @end menu
                   1119: @node vnc_generate_ca
                   1120: @subsubsection Setup the Certificate Authority
                   1121: 
                   1122: This step only needs to be performed once per organization / organizational
                   1123: unit. First the CA needs a private key. This key must be kept VERY secret
                   1124: and secure. If this key is compromised the entire trust chain of the certificates
                   1125: issued with it is lost.
                   1126: 
                   1127: @example
                   1128: # certtool --generate-privkey > ca-key.pem
                   1129: @end example
                   1130: 
                   1131: A CA needs to have a public certificate. For simplicity it can be a self-signed
                   1132: certificate, or one issue by a commercial certificate issuing authority. To
                   1133: generate a self-signed certificate requires one core piece of information, the
                   1134: name of the organization.
                   1135: 
                   1136: @example
                   1137: # cat > ca.info <<EOF
                   1138: cn = Name of your organization
                   1139: ca
                   1140: cert_signing_key
                   1141: EOF
                   1142: # certtool --generate-self-signed \
                   1143:            --load-privkey ca-key.pem
                   1144:            --template ca.info \
                   1145:            --outfile ca-cert.pem
                   1146: @end example
                   1147: 
                   1148: The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
                   1149: TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
                   1150: 
                   1151: @node vnc_generate_server
                   1152: @subsubsection Issuing server certificates
                   1153: 
                   1154: Each server (or host) needs to be issued with a key and certificate. When connecting
                   1155: the certificate is sent to the client which validates it against the CA certificate.
                   1156: The core piece of information for a server certificate is the hostname. This should
                   1157: be the fully qualified hostname that the client will connect with, since the client
                   1158: will typically also verify the hostname in the certificate. On the host holding the
                   1159: secure CA private key:
                   1160: 
                   1161: @example
                   1162: # cat > server.info <<EOF
                   1163: organization = Name  of your organization
                   1164: cn = server.foo.example.com
                   1165: tls_www_server
                   1166: encryption_key
                   1167: signing_key
                   1168: EOF
                   1169: # certtool --generate-privkey > server-key.pem
                   1170: # certtool --generate-certificate \
                   1171:            --load-ca-certificate ca-cert.pem \
                   1172:            --load-ca-privkey ca-key.pem \
                   1173:            --load-privkey server server-key.pem \
                   1174:            --template server.info \
                   1175:            --outfile server-cert.pem
                   1176: @end example
                   1177: 
                   1178: The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
                   1179: to the server for which they were generated. The @code{server-key.pem} is security
                   1180: sensitive and should be kept protected with file mode 0600 to prevent disclosure.
                   1181: 
                   1182: @node vnc_generate_client
                   1183: @subsubsection Issuing client certificates
                   1184: 
                   1185: If the QEMU VNC server is to use the @code{x509verify} option to validate client
                   1186: certificates as its authentication mechanism, each client also needs to be issued
                   1187: a certificate. The client certificate contains enough metadata to uniquely identify
                   1188: the client, typically organization, state, city, building, etc. On the host holding
                   1189: the secure CA private key:
                   1190: 
                   1191: @example
                   1192: # cat > client.info <<EOF
                   1193: country = GB
                   1194: state = London
                   1195: locality = London
                   1196: organiazation = Name of your organization
                   1197: cn = client.foo.example.com
                   1198: tls_www_client
                   1199: encryption_key
                   1200: signing_key
                   1201: EOF
                   1202: # certtool --generate-privkey > client-key.pem
                   1203: # certtool --generate-certificate \
                   1204:            --load-ca-certificate ca-cert.pem \
                   1205:            --load-ca-privkey ca-key.pem \
                   1206:            --load-privkey client-key.pem \
                   1207:            --template client.info \
                   1208:            --outfile client-cert.pem
                   1209: @end example
                   1210: 
                   1211: The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
                   1212: copied to the client for which they were generated.
                   1213: 
1.1.1.9   root     1214: 
                   1215: @node vnc_setup_sasl
                   1216: 
                   1217: @subsection Configuring SASL mechanisms
                   1218: 
                   1219: The following documentation assumes use of the Cyrus SASL implementation on a
                   1220: Linux host, but the principals should apply to any other SASL impl. When SASL
                   1221: is enabled, the mechanism configuration will be loaded from system default
                   1222: SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
                   1223: unprivileged user, an environment variable SASL_CONF_PATH can be used
                   1224: to make it search alternate locations for the service config.
                   1225: 
                   1226: The default configuration might contain
                   1227: 
                   1228: @example
                   1229: mech_list: digest-md5
                   1230: sasldb_path: /etc/qemu/passwd.db
                   1231: @end example
                   1232: 
                   1233: This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
                   1234: Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
                   1235: in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
                   1236: command. While this mechanism is easy to configure and use, it is not
                   1237: considered secure by modern standards, so only suitable for developers /
                   1238: ad-hoc testing.
                   1239: 
                   1240: A more serious deployment might use Kerberos, which is done with the 'gssapi'
                   1241: mechanism
                   1242: 
                   1243: @example
                   1244: mech_list: gssapi
                   1245: keytab: /etc/qemu/krb5.tab
                   1246: @end example
                   1247: 
                   1248: For this to work the administrator of your KDC must generate a Kerberos
                   1249: principal for the server, with a name of  'qemu/somehost.example.com@@EXAMPLE.COM'
                   1250: replacing 'somehost.example.com' with the fully qualified host name of the
1.1.1.12  root     1251: machine running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
1.1.1.9   root     1252: 
                   1253: Other configurations will be left as an exercise for the reader. It should
                   1254: be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
                   1255: encryption. For all other mechanisms, VNC should always be configured to
                   1256: use TLS and x509 certificates to protect security credentials from snooping.
                   1257: 
1.1       root     1258: @node gdb_usage
                   1259: @section GDB usage
                   1260: 
                   1261: QEMU has a primitive support to work with gdb, so that you can do
                   1262: 'Ctrl-C' while the virtual machine is running and inspect its state.
                   1263: 
                   1264: In order to use gdb, launch qemu with the '-s' option. It will wait for a
                   1265: gdb connection:
                   1266: @example
1.1.1.3   root     1267: > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
                   1268:        -append "root=/dev/hda"
1.1       root     1269: Connected to host network interface: tun0
                   1270: Waiting gdb connection on port 1234
                   1271: @end example
                   1272: 
                   1273: Then launch gdb on the 'vmlinux' executable:
                   1274: @example
                   1275: > gdb vmlinux
                   1276: @end example
                   1277: 
                   1278: In gdb, connect to QEMU:
                   1279: @example
                   1280: (gdb) target remote localhost:1234
                   1281: @end example
                   1282: 
                   1283: Then you can use gdb normally. For example, type 'c' to launch the kernel:
                   1284: @example
                   1285: (gdb) c
                   1286: @end example
                   1287: 
                   1288: Here are some useful tips in order to use gdb on system code:
                   1289: 
                   1290: @enumerate
                   1291: @item
                   1292: Use @code{info reg} to display all the CPU registers.
                   1293: @item
                   1294: Use @code{x/10i $eip} to display the code at the PC position.
                   1295: @item
                   1296: Use @code{set architecture i8086} to dump 16 bit code. Then use
1.1.1.4   root     1297: @code{x/10i $cs*16+$eip} to dump the code at the PC position.
1.1       root     1298: @end enumerate
                   1299: 
1.1.1.7   root     1300: Advanced debugging options:
                   1301: 
                   1302: The default single stepping behavior is step with the IRQs and timer service routines off.  It is set this way because when gdb executes a single step it expects to advance beyond the current instruction.  With the IRQs and and timer service routines on, a single step might jump into the one of the interrupt or exception vectors instead of executing the current instruction. This means you may hit the same breakpoint a number of times before executing the instruction gdb wants to have executed.  Because there are rare circumstances where you want to single step into an interrupt vector the behavior can be controlled from GDB.  There are three commands you can query and set the single step behavior:
                   1303: @table @code
                   1304: @item maintenance packet qqemu.sstepbits
                   1305: 
                   1306: This will display the MASK bits used to control the single stepping IE:
                   1307: @example
                   1308: (gdb) maintenance packet qqemu.sstepbits
                   1309: sending: "qqemu.sstepbits"
                   1310: received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
                   1311: @end example
                   1312: @item maintenance packet qqemu.sstep
                   1313: 
                   1314: This will display the current value of the mask used when single stepping IE:
                   1315: @example
                   1316: (gdb) maintenance packet qqemu.sstep
                   1317: sending: "qqemu.sstep"
                   1318: received: "0x7"
                   1319: @end example
                   1320: @item maintenance packet Qqemu.sstep=HEX_VALUE
                   1321: 
                   1322: This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
                   1323: @example
                   1324: (gdb) maintenance packet Qqemu.sstep=0x5
                   1325: sending: "qemu.sstep=0x5"
                   1326: received: "OK"
                   1327: @end example
                   1328: @end table
                   1329: 
1.1.1.3   root     1330: @node pcsys_os_specific
1.1       root     1331: @section Target OS specific information
                   1332: 
                   1333: @subsection Linux
                   1334: 
                   1335: To have access to SVGA graphic modes under X11, use the @code{vesa} or
                   1336: the @code{cirrus} X11 driver. For optimal performances, use 16 bit
                   1337: color depth in the guest and the host OS.
                   1338: 
                   1339: When using a 2.6 guest Linux kernel, you should add the option
                   1340: @code{clock=pit} on the kernel command line because the 2.6 Linux
                   1341: kernels make very strict real time clock checks by default that QEMU
                   1342: cannot simulate exactly.
                   1343: 
                   1344: When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
                   1345: not activated because QEMU is slower with this patch. The QEMU
                   1346: Accelerator Module is also much slower in this case. Earlier Fedora
1.1.1.6   root     1347: Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1.1       root     1348: patch by default. Newer kernels don't have it.
                   1349: 
                   1350: @subsection Windows
                   1351: 
                   1352: If you have a slow host, using Windows 95 is better as it gives the
                   1353: best speed. Windows 2000 is also a good choice.
                   1354: 
                   1355: @subsubsection SVGA graphic modes support
                   1356: 
                   1357: QEMU emulates a Cirrus Logic GD5446 Video
                   1358: card. All Windows versions starting from Windows 95 should recognize
                   1359: and use this graphic card. For optimal performances, use 16 bit color
                   1360: depth in the guest and the host OS.
                   1361: 
1.1.1.4   root     1362: If you are using Windows XP as guest OS and if you want to use high
                   1363: resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
                   1364: 1280x1024x16), then you should use the VESA VBE virtual graphic card
                   1365: (option @option{-std-vga}).
                   1366: 
1.1       root     1367: @subsubsection CPU usage reduction
                   1368: 
                   1369: Windows 9x does not correctly use the CPU HLT
                   1370: instruction. The result is that it takes host CPU cycles even when
                   1371: idle. You can install the utility from
                   1372: @url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
                   1373: problem. Note that no such tool is needed for NT, 2000 or XP.
                   1374: 
                   1375: @subsubsection Windows 2000 disk full problem
                   1376: 
                   1377: Windows 2000 has a bug which gives a disk full problem during its
                   1378: installation. When installing it, use the @option{-win2k-hack} QEMU
                   1379: option to enable a specific workaround. After Windows 2000 is
                   1380: installed, you no longer need this option (this option slows down the
                   1381: IDE transfers).
                   1382: 
                   1383: @subsubsection Windows 2000 shutdown
                   1384: 
                   1385: Windows 2000 cannot automatically shutdown in QEMU although Windows 98
                   1386: can. It comes from the fact that Windows 2000 does not automatically
                   1387: use the APM driver provided by the BIOS.
                   1388: 
                   1389: In order to correct that, do the following (thanks to Struan
                   1390: Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
                   1391: Add/Troubleshoot a device => Add a new device & Next => No, select the
                   1392: hardware from a list & Next => NT Apm/Legacy Support & Next => Next
                   1393: (again) a few times. Now the driver is installed and Windows 2000 now
1.1.1.6   root     1394: correctly instructs QEMU to shutdown at the appropriate moment.
1.1       root     1395: 
                   1396: @subsubsection Share a directory between Unix and Windows
                   1397: 
                   1398: See @ref{sec_invocation} about the help of the option @option{-smb}.
                   1399: 
1.1.1.5   root     1400: @subsubsection Windows XP security problem
1.1       root     1401: 
                   1402: Some releases of Windows XP install correctly but give a security
                   1403: error when booting:
                   1404: @example
                   1405: A problem is preventing Windows from accurately checking the
                   1406: license for this computer. Error code: 0x800703e6.
                   1407: @end example
                   1408: 
1.1.1.5   root     1409: The workaround is to install a service pack for XP after a boot in safe
                   1410: mode. Then reboot, and the problem should go away. Since there is no
                   1411: network while in safe mode, its recommended to download the full
                   1412: installation of SP1 or SP2 and transfer that via an ISO or using the
                   1413: vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1.1       root     1414: 
                   1415: @subsection MS-DOS and FreeDOS
                   1416: 
                   1417: @subsubsection CPU usage reduction
                   1418: 
                   1419: DOS does not correctly use the CPU HLT instruction. The result is that
                   1420: it takes host CPU cycles even when idle. You can install the utility
                   1421: from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
                   1422: problem.
                   1423: 
1.1.1.3   root     1424: @node QEMU System emulator for non PC targets
1.1.1.2   root     1425: @chapter QEMU System emulator for non PC targets
                   1426: 
                   1427: QEMU is a generic emulator and it emulates many non PC
                   1428: machines. Most of the options are similar to the PC emulator. The
1.1.1.6   root     1429: differences are mentioned in the following sections.
1.1.1.2   root     1430: 
1.1.1.3   root     1431: @menu
1.1.1.11  root     1432: * PowerPC System emulator::
1.1.1.6   root     1433: * Sparc32 System emulator::
                   1434: * Sparc64 System emulator::
                   1435: * MIPS System emulator::
                   1436: * ARM System emulator::
                   1437: * ColdFire System emulator::
1.1.1.11  root     1438: * Cris System emulator::
                   1439: * Microblaze System emulator::
                   1440: * SH4 System emulator::
1.1.1.3   root     1441: @end menu
                   1442: 
1.1.1.11  root     1443: @node PowerPC System emulator
                   1444: @section PowerPC System emulator
                   1445: @cindex system emulation (PowerPC)
1.1       root     1446: 
                   1447: Use the executable @file{qemu-system-ppc} to simulate a complete PREP
                   1448: or PowerMac PowerPC system.
                   1449: 
                   1450: QEMU emulates the following PowerMac peripherals:
                   1451: 
                   1452: @itemize @minus
1.1.1.6   root     1453: @item
1.1.1.7   root     1454: UniNorth or Grackle PCI Bridge
1.1       root     1455: @item
                   1456: PCI VGA compatible card with VESA Bochs Extensions
1.1.1.6   root     1457: @item
1.1       root     1458: 2 PMAC IDE interfaces with hard disk and CD-ROM support
1.1.1.6   root     1459: @item
1.1       root     1460: NE2000 PCI adapters
                   1461: @item
                   1462: Non Volatile RAM
                   1463: @item
                   1464: VIA-CUDA with ADB keyboard and mouse.
                   1465: @end itemize
                   1466: 
                   1467: QEMU emulates the following PREP peripherals:
                   1468: 
                   1469: @itemize @minus
1.1.1.6   root     1470: @item
1.1       root     1471: PCI Bridge
                   1472: @item
                   1473: PCI VGA compatible card with VESA Bochs Extensions
1.1.1.6   root     1474: @item
1.1       root     1475: 2 IDE interfaces with hard disk and CD-ROM support
                   1476: @item
                   1477: Floppy disk
1.1.1.6   root     1478: @item
1.1       root     1479: NE2000 network adapters
                   1480: @item
                   1481: Serial port
                   1482: @item
                   1483: PREP Non Volatile RAM
                   1484: @item
                   1485: PC compatible keyboard and mouse.
                   1486: @end itemize
                   1487: 
                   1488: QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1.1.1.2   root     1489: @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
1.1       root     1490: 
1.1.1.7   root     1491: Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
                   1492: for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
                   1493: v2) portable firmware implementation. The goal is to implement a 100%
                   1494: IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
                   1495: 
1.1       root     1496: @c man begin OPTIONS
                   1497: 
                   1498: The following options are specific to the PowerPC emulation:
                   1499: 
                   1500: @table @option
                   1501: 
1.1.1.10  root     1502: @item -g @var{W}x@var{H}[x@var{DEPTH}]
1.1       root     1503: 
                   1504: Set the initial VGA graphic mode. The default is 800x600x15.
                   1505: 
1.1.1.10  root     1506: @item -prom-env @var{string}
1.1.1.7   root     1507: 
                   1508: Set OpenBIOS variables in NVRAM, for example:
                   1509: 
                   1510: @example
                   1511: qemu-system-ppc -prom-env 'auto-boot?=false' \
                   1512:  -prom-env 'boot-device=hd:2,\yaboot' \
                   1513:  -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
                   1514: @end example
                   1515: 
                   1516: These variables are not used by Open Hack'Ware.
                   1517: 
1.1       root     1518: @end table
                   1519: 
1.1.1.6   root     1520: @c man end
1.1       root     1521: 
                   1522: 
                   1523: More information is available at
1.1.1.2   root     1524: @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1.1       root     1525: 
1.1.1.6   root     1526: @node Sparc32 System emulator
                   1527: @section Sparc32 System emulator
1.1.1.11  root     1528: @cindex system emulation (Sparc32)
1.1       root     1529: 
1.1.1.7   root     1530: Use the executable @file{qemu-system-sparc} to simulate the following
                   1531: Sun4m architecture machines:
                   1532: @itemize @minus
                   1533: @item
                   1534: SPARCstation 4
                   1535: @item
                   1536: SPARCstation 5
                   1537: @item
                   1538: SPARCstation 10
                   1539: @item
                   1540: SPARCstation 20
                   1541: @item
                   1542: SPARCserver 600MP
                   1543: @item
                   1544: SPARCstation LX
                   1545: @item
                   1546: SPARCstation Voyager
                   1547: @item
                   1548: SPARCclassic
                   1549: @item
                   1550: SPARCbook
                   1551: @end itemize
                   1552: 
                   1553: The emulation is somewhat complete. SMP up to 16 CPUs is supported,
                   1554: but Linux limits the number of usable CPUs to 4.
1.1       root     1555: 
1.1.1.7   root     1556: It's also possible to simulate a SPARCstation 2 (sun4c architecture),
                   1557: SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
                   1558: emulators are not usable yet.
                   1559: 
                   1560: QEMU emulates the following sun4m/sun4c/sun4d peripherals:
1.1       root     1561: 
                   1562: @itemize @minus
                   1563: @item
1.1.1.6   root     1564: IOMMU or IO-UNITs
1.1       root     1565: @item
                   1566: TCX Frame buffer
1.1.1.6   root     1567: @item
1.1       root     1568: Lance (Am7990) Ethernet
                   1569: @item
1.1.1.7   root     1570: Non Volatile RAM M48T02/M48T08
1.1       root     1571: @item
                   1572: Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
                   1573: and power/reset logic
                   1574: @item
                   1575: ESP SCSI controller with hard disk and CD-ROM support
                   1576: @item
1.1.1.6   root     1577: Floppy drive (not on SS-600MP)
                   1578: @item
                   1579: CS4231 sound device (only on SS-5, not working yet)
1.1       root     1580: @end itemize
                   1581: 
1.1.1.6   root     1582: The number of peripherals is fixed in the architecture.  Maximum
                   1583: memory size depends on the machine type, for SS-5 it is 256MB and for
                   1584: others 2047MB.
1.1       root     1585: 
1.1.1.4   root     1586: Since version 0.8.2, QEMU uses OpenBIOS
                   1587: @url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
                   1588: firmware implementation. The goal is to implement a 100% IEEE
                   1589: 1275-1994 (referred to as Open Firmware) compliant firmware.
1.1       root     1590: 
                   1591: A sample Linux 2.6 series kernel and ram disk image are available on
1.1.1.7   root     1592: the QEMU web site. There are still issues with NetBSD and OpenBSD, but
                   1593: some kernel versions work. Please note that currently Solaris kernels
                   1594: don't work probably due to interface issues between OpenBIOS and
                   1595: Solaris.
1.1       root     1596: 
                   1597: @c man begin OPTIONS
                   1598: 
1.1.1.6   root     1599: The following options are specific to the Sparc32 emulation:
1.1       root     1600: 
                   1601: @table @option
                   1602: 
1.1.1.10  root     1603: @item -g @var{W}x@var{H}x[x@var{DEPTH}]
1.1.1.6   root     1604: 
                   1605: Set the initial TCX graphic mode. The default is 1024x768x8, currently
                   1606: the only other possible mode is 1024x768x24.
                   1607: 
1.1.1.10  root     1608: @item -prom-env @var{string}
1.1       root     1609: 
1.1.1.6   root     1610: Set OpenBIOS variables in NVRAM, for example:
                   1611: 
                   1612: @example
                   1613: qemu-system-sparc -prom-env 'auto-boot?=false' \
                   1614:  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
                   1615: @end example
                   1616: 
1.1.1.11  root     1617: @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook|SS-2|SS-1000|SS-2000]
1.1.1.6   root     1618: 
                   1619: Set the emulated machine type. Default is SS-5.
1.1       root     1620: 
                   1621: @end table
                   1622: 
1.1.1.6   root     1623: @c man end
1.1       root     1624: 
1.1.1.6   root     1625: @node Sparc64 System emulator
                   1626: @section Sparc64 System emulator
1.1.1.11  root     1627: @cindex system emulation (Sparc64)
1.1       root     1628: 
1.1.1.7   root     1629: Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
                   1630: (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
                   1631: Niagara (T1) machine. The emulator is not usable for anything yet, but
                   1632: it can launch some kernels.
1.1       root     1633: 
1.1.1.7   root     1634: QEMU emulates the following peripherals:
1.1       root     1635: 
                   1636: @itemize @minus
                   1637: @item
1.1.1.6   root     1638: UltraSparc IIi APB PCI Bridge
1.1       root     1639: @item
                   1640: PCI VGA compatible card with VESA Bochs Extensions
                   1641: @item
1.1.1.7   root     1642: PS/2 mouse and keyboard
                   1643: @item
1.1       root     1644: Non Volatile RAM M48T59
                   1645: @item
                   1646: PC-compatible serial ports
1.1.1.7   root     1647: @item
                   1648: 2 PCI IDE interfaces with hard disk and CD-ROM support
                   1649: @item
                   1650: Floppy disk
1.1       root     1651: @end itemize
                   1652: 
1.1.1.7   root     1653: @c man begin OPTIONS
                   1654: 
                   1655: The following options are specific to the Sparc64 emulation:
                   1656: 
                   1657: @table @option
                   1658: 
1.1.1.10  root     1659: @item -prom-env @var{string}
1.1.1.7   root     1660: 
                   1661: Set OpenBIOS variables in NVRAM, for example:
                   1662: 
                   1663: @example
                   1664: qemu-system-sparc64 -prom-env 'auto-boot?=false'
                   1665: @end example
                   1666: 
                   1667: @item -M [sun4u|sun4v|Niagara]
                   1668: 
                   1669: Set the emulated machine type. The default is sun4u.
                   1670: 
                   1671: @end table
                   1672: 
                   1673: @c man end
                   1674: 
1.1.1.6   root     1675: @node MIPS System emulator
                   1676: @section MIPS System emulator
1.1.1.11  root     1677: @cindex system emulation (MIPS)
1.1.1.6   root     1678: 
                   1679: Four executables cover simulation of 32 and 64-bit MIPS systems in
                   1680: both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
                   1681: @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
1.1.1.7   root     1682: Five different machine types are emulated:
1.1.1.6   root     1683: 
                   1684: @itemize @minus
                   1685: @item
                   1686: A generic ISA PC-like machine "mips"
                   1687: @item
                   1688: The MIPS Malta prototype board "malta"
                   1689: @item
                   1690: An ACER Pica "pica61". This machine needs the 64-bit emulator.
                   1691: @item
                   1692: MIPS emulator pseudo board "mipssim"
1.1.1.7   root     1693: @item
                   1694: A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
1.1.1.6   root     1695: @end itemize
1.1       root     1696: 
1.1.1.6   root     1697: The generic emulation is supported by Debian 'Etch' and is able to
                   1698: install Debian into a virtual disk image. The following devices are
                   1699: emulated:
1.1.1.2   root     1700: 
                   1701: @itemize @minus
1.1.1.6   root     1702: @item
                   1703: A range of MIPS CPUs, default is the 24Kf
1.1.1.2   root     1704: @item
                   1705: PC style serial port
                   1706: @item
1.1.1.6   root     1707: PC style IDE disk
                   1708: @item
1.1.1.2   root     1709: NE2000 network card
                   1710: @end itemize
                   1711: 
1.1.1.6   root     1712: The Malta emulation supports the following devices:
                   1713: 
                   1714: @itemize @minus
                   1715: @item
                   1716: Core board with MIPS 24Kf CPU and Galileo system controller
                   1717: @item
                   1718: PIIX4 PCI/USB/SMbus controller
                   1719: @item
                   1720: The Multi-I/O chip's serial device
                   1721: @item
1.1.1.9   root     1722: PCI network cards (PCnet32 and others)
1.1.1.6   root     1723: @item
                   1724: Malta FPGA serial device
                   1725: @item
1.1.1.7   root     1726: Cirrus (default) or any other PCI VGA graphics card
1.1.1.6   root     1727: @end itemize
                   1728: 
                   1729: The ACER Pica emulation supports:
                   1730: 
                   1731: @itemize @minus
                   1732: @item
                   1733: MIPS R4000 CPU
                   1734: @item
                   1735: PC-style IRQ and DMA controllers
                   1736: @item
                   1737: PC Keyboard
                   1738: @item
                   1739: IDE controller
                   1740: @end itemize
1.1.1.2   root     1741: 
1.1.1.6   root     1742: The mipssim pseudo board emulation provides an environment similiar
                   1743: to what the proprietary MIPS emulator uses for running Linux.
                   1744: It supports:
                   1745: 
                   1746: @itemize @minus
                   1747: @item
                   1748: A range of MIPS CPUs, default is the 24Kf
                   1749: @item
                   1750: PC style serial port
                   1751: @item
                   1752: MIPSnet network emulation
                   1753: @end itemize
                   1754: 
1.1.1.7   root     1755: The MIPS Magnum R4000 emulation supports:
                   1756: 
                   1757: @itemize @minus
                   1758: @item
                   1759: MIPS R4000 CPU
                   1760: @item
                   1761: PC-style IRQ controller
                   1762: @item
                   1763: PC Keyboard
                   1764: @item
                   1765: SCSI controller
                   1766: @item
                   1767: G364 framebuffer
                   1768: @end itemize
                   1769: 
                   1770: 
1.1.1.6   root     1771: @node ARM System emulator
                   1772: @section ARM System emulator
1.1.1.11  root     1773: @cindex system emulation (ARM)
1.1.1.2   root     1774: 
                   1775: Use the executable @file{qemu-system-arm} to simulate a ARM
                   1776: machine. The ARM Integrator/CP board is emulated with the following
                   1777: devices:
                   1778: 
                   1779: @itemize @minus
                   1780: @item
1.1.1.6   root     1781: ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
1.1.1.2   root     1782: @item
                   1783: Two PL011 UARTs
1.1.1.6   root     1784: @item
1.1.1.2   root     1785: SMC 91c111 Ethernet adapter
1.1.1.4   root     1786: @item
                   1787: PL110 LCD controller
                   1788: @item
                   1789: PL050 KMI with PS/2 keyboard and mouse.
1.1.1.6   root     1790: @item
                   1791: PL181 MultiMedia Card Interface with SD card.
1.1.1.4   root     1792: @end itemize
                   1793: 
                   1794: The ARM Versatile baseboard is emulated with the following devices:
                   1795: 
                   1796: @itemize @minus
                   1797: @item
1.1.1.6   root     1798: ARM926E, ARM1136 or Cortex-A8 CPU
1.1.1.4   root     1799: @item
                   1800: PL190 Vectored Interrupt Controller
                   1801: @item
                   1802: Four PL011 UARTs
1.1.1.6   root     1803: @item
1.1.1.4   root     1804: SMC 91c111 Ethernet adapter
                   1805: @item
                   1806: PL110 LCD controller
                   1807: @item
                   1808: PL050 KMI with PS/2 keyboard and mouse.
                   1809: @item
                   1810: PCI host bridge.  Note the emulated PCI bridge only provides access to
                   1811: PCI memory space.  It does not provide access to PCI IO space.
1.1.1.6   root     1812: This means some devices (eg. ne2k_pci NIC) are not usable, and others
                   1813: (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
1.1.1.4   root     1814: mapped control registers.
                   1815: @item
                   1816: PCI OHCI USB controller.
                   1817: @item
                   1818: LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
1.1.1.6   root     1819: @item
                   1820: PL181 MultiMedia Card Interface with SD card.
                   1821: @end itemize
                   1822: 
1.1.1.11  root     1823: Several variants of the ARM RealView baseboard are emulated,
                   1824: including the EB, PB-A8 and PBX-A9.  Due to interactions with the
                   1825: bootloader, only certain Linux kernel configurations work out
                   1826: of the box on these boards.
                   1827: 
                   1828: Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
                   1829: enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board
                   1830: should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
                   1831: disabled and expect 1024M RAM.
                   1832: 
1.1.1.12  root     1833: The following devices are emulated:
1.1.1.6   root     1834: 
                   1835: @itemize @minus
                   1836: @item
1.1.1.10  root     1837: ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
1.1.1.6   root     1838: @item
                   1839: ARM AMBA Generic/Distributed Interrupt Controller
                   1840: @item
                   1841: Four PL011 UARTs
                   1842: @item
1.1.1.10  root     1843: SMC 91c111 or SMSC LAN9118 Ethernet adapter
1.1.1.6   root     1844: @item
                   1845: PL110 LCD controller
                   1846: @item
                   1847: PL050 KMI with PS/2 keyboard and mouse
                   1848: @item
                   1849: PCI host bridge
                   1850: @item
                   1851: PCI OHCI USB controller
                   1852: @item
                   1853: LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
                   1854: @item
                   1855: PL181 MultiMedia Card Interface with SD card.
                   1856: @end itemize
                   1857: 
                   1858: The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
                   1859: and "Terrier") emulation includes the following peripherals:
                   1860: 
                   1861: @itemize @minus
                   1862: @item
                   1863: Intel PXA270 System-on-chip (ARM V5TE core)
                   1864: @item
                   1865: NAND Flash memory
                   1866: @item
                   1867: IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
                   1868: @item
                   1869: On-chip OHCI USB controller
                   1870: @item
                   1871: On-chip LCD controller
                   1872: @item
                   1873: On-chip Real Time Clock
                   1874: @item
                   1875: TI ADS7846 touchscreen controller on SSP bus
                   1876: @item
                   1877: Maxim MAX1111 analog-digital converter on I@math{^2}C bus
                   1878: @item
                   1879: GPIO-connected keyboard controller and LEDs
                   1880: @item
                   1881: Secure Digital card connected to PXA MMC/SD host
                   1882: @item
                   1883: Three on-chip UARTs
                   1884: @item
                   1885: WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
                   1886: @end itemize
                   1887: 
                   1888: The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
                   1889: following elements:
                   1890: 
                   1891: @itemize @minus
                   1892: @item
                   1893: Texas Instruments OMAP310 System-on-chip (ARM 925T core)
                   1894: @item
                   1895: ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
                   1896: @item
                   1897: On-chip LCD controller
                   1898: @item
                   1899: On-chip Real Time Clock
                   1900: @item
                   1901: TI TSC2102i touchscreen controller / analog-digital converter / Audio
                   1902: CODEC, connected through MicroWire and I@math{^2}S busses
                   1903: @item
                   1904: GPIO-connected matrix keypad
                   1905: @item
                   1906: Secure Digital card connected to OMAP MMC/SD host
                   1907: @item
                   1908: Three on-chip UARTs
                   1909: @end itemize
                   1910: 
1.1.1.7   root     1911: Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
                   1912: emulation supports the following elements:
                   1913: 
                   1914: @itemize @minus
                   1915: @item
                   1916: Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
                   1917: @item
                   1918: RAM and non-volatile OneNAND Flash memories
                   1919: @item
                   1920: Display connected to EPSON remote framebuffer chip and OMAP on-chip
                   1921: display controller and a LS041y3 MIPI DBI-C controller
                   1922: @item
                   1923: TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
                   1924: driven through SPI bus
                   1925: @item
                   1926: National Semiconductor LM8323-controlled qwerty keyboard driven
                   1927: through I@math{^2}C bus
                   1928: @item
                   1929: Secure Digital card connected to OMAP MMC/SD host
                   1930: @item
                   1931: Three OMAP on-chip UARTs and on-chip STI debugging console
                   1932: @item
1.1.1.12  root     1933: A Bluetooth(R) transceiver and HCI connected to an UART
1.1.1.7   root     1934: @item
                   1935: Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
                   1936: TUSB6010 chip - only USB host mode is supported
                   1937: @item
                   1938: TI TMP105 temperature sensor driven through I@math{^2}C bus
                   1939: @item
                   1940: TI TWL92230C power management companion with an RTC on I@math{^2}C bus
                   1941: @item
                   1942: Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
                   1943: through CBUS
                   1944: @end itemize
                   1945: 
1.1.1.6   root     1946: The Luminary Micro Stellaris LM3S811EVB emulation includes the following
                   1947: devices:
                   1948: 
                   1949: @itemize @minus
                   1950: @item
                   1951: Cortex-M3 CPU core.
                   1952: @item
                   1953: 64k Flash and 8k SRAM.
                   1954: @item
                   1955: Timers, UARTs, ADC and I@math{^2}C interface.
                   1956: @item
                   1957: OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
                   1958: @end itemize
                   1959: 
                   1960: The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
                   1961: devices:
                   1962: 
                   1963: @itemize @minus
                   1964: @item
                   1965: Cortex-M3 CPU core.
                   1966: @item
                   1967: 256k Flash and 64k SRAM.
                   1968: @item
                   1969: Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
                   1970: @item
                   1971: OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
1.1.1.2   root     1972: @end itemize
                   1973: 
1.1.1.7   root     1974: The Freecom MusicPal internet radio emulation includes the following
                   1975: elements:
                   1976: 
                   1977: @itemize @minus
                   1978: @item
                   1979: Marvell MV88W8618 ARM core.
                   1980: @item
                   1981: 32 MB RAM, 256 KB SRAM, 8 MB flash.
                   1982: @item
                   1983: Up to 2 16550 UARTs
                   1984: @item
                   1985: MV88W8xx8 Ethernet controller
                   1986: @item
                   1987: MV88W8618 audio controller, WM8750 CODEC and mixer
                   1988: @item
1.1.1.11  root     1989: 128×64 display with brightness control
1.1.1.7   root     1990: @item
                   1991: 2 buttons, 2 navigation wheels with button function
                   1992: @end itemize
                   1993: 
                   1994: The Siemens SX1 models v1 and v2 (default) basic emulation.
1.1.1.12  root     1995: The emulation includes the following elements:
1.1.1.7   root     1996: 
                   1997: @itemize @minus
                   1998: @item
                   1999: Texas Instruments OMAP310 System-on-chip (ARM 925T core)
                   2000: @item
                   2001: ROM and RAM memories (ROM firmware image can be loaded with -pflash)
                   2002: V1
                   2003: 1 Flash of 16MB and 1 Flash of 8MB
                   2004: V2
                   2005: 1 Flash of 32MB
                   2006: @item
                   2007: On-chip LCD controller
                   2008: @item
                   2009: On-chip Real Time Clock
                   2010: @item
                   2011: Secure Digital card connected to OMAP MMC/SD host
                   2012: @item
                   2013: Three on-chip UARTs
                   2014: @end itemize
                   2015: 
1.1.1.9   root     2016: The "Syborg" Symbian Virtual Platform base model includes the following
                   2017: elements:
                   2018: 
                   2019: @itemize @minus
                   2020: @item
                   2021: ARM Cortex-A8 CPU
                   2022: @item
                   2023: Interrupt controller
                   2024: @item
                   2025: Timer
                   2026: @item
                   2027: Real Time Clock
                   2028: @item
                   2029: Keyboard
                   2030: @item
                   2031: Framebuffer
                   2032: @item
                   2033: Touchscreen
                   2034: @item
                   2035: UARTs
                   2036: @end itemize
                   2037: 
1.1.1.2   root     2038: A Linux 2.6 test image is available on the QEMU web site. More
                   2039: information is available in the QEMU mailing-list archive.
1.1       root     2040: 
1.1.1.7   root     2041: @c man begin OPTIONS
                   2042: 
                   2043: The following options are specific to the ARM emulation:
                   2044: 
                   2045: @table @option
                   2046: 
                   2047: @item -semihosting
                   2048: Enable semihosting syscall emulation.
                   2049: 
                   2050: On ARM this implements the "Angel" interface.
                   2051: 
                   2052: Note that this allows guest direct access to the host filesystem,
                   2053: so should only be used with trusted guest OS.
                   2054: 
                   2055: @end table
                   2056: 
1.1.1.6   root     2057: @node ColdFire System emulator
                   2058: @section ColdFire System emulator
1.1.1.11  root     2059: @cindex system emulation (ColdFire)
                   2060: @cindex system emulation (M68K)
1.1.1.6   root     2061: 
                   2062: Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
                   2063: The emulator is able to boot a uClinux kernel.
                   2064: 
                   2065: The M5208EVB emulation includes the following devices:
                   2066: 
                   2067: @itemize @minus
                   2068: @item
                   2069: MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
                   2070: @item
                   2071: Three Two on-chip UARTs.
                   2072: @item
                   2073: Fast Ethernet Controller (FEC)
                   2074: @end itemize
                   2075: 
                   2076: The AN5206 emulation includes the following devices:
                   2077: 
                   2078: @itemize @minus
                   2079: @item
                   2080: MCF5206 ColdFire V2 Microprocessor.
                   2081: @item
                   2082: Two on-chip UARTs.
                   2083: @end itemize
                   2084: 
1.1.1.7   root     2085: @c man begin OPTIONS
                   2086: 
1.1.1.11  root     2087: The following options are specific to the ColdFire emulation:
1.1.1.7   root     2088: 
                   2089: @table @option
                   2090: 
                   2091: @item -semihosting
                   2092: Enable semihosting syscall emulation.
                   2093: 
                   2094: On M68K this implements the "ColdFire GDB" interface used by libgloss.
                   2095: 
                   2096: Note that this allows guest direct access to the host filesystem,
                   2097: so should only be used with trusted guest OS.
                   2098: 
                   2099: @end table
                   2100: 
1.1.1.11  root     2101: @node Cris System emulator
                   2102: @section Cris System emulator
                   2103: @cindex system emulation (Cris)
                   2104: 
                   2105: TODO
                   2106: 
                   2107: @node Microblaze System emulator
                   2108: @section Microblaze System emulator
                   2109: @cindex system emulation (Microblaze)
                   2110: 
                   2111: TODO
                   2112: 
                   2113: @node SH4 System emulator
                   2114: @section SH4 System emulator
                   2115: @cindex system emulation (SH4)
                   2116: 
                   2117: TODO
                   2118: 
1.1.1.6   root     2119: @node QEMU User space emulator
                   2120: @chapter QEMU User space emulator
1.1.1.5   root     2121: 
                   2122: @menu
                   2123: * Supported Operating Systems ::
                   2124: * Linux User space emulator::
                   2125: * Mac OS X/Darwin User space emulator ::
1.1.1.7   root     2126: * BSD User space emulator ::
1.1.1.5   root     2127: @end menu
                   2128: 
                   2129: @node Supported Operating Systems
                   2130: @section Supported Operating Systems
                   2131: 
                   2132: The following OS are supported in user space emulation:
                   2133: 
                   2134: @itemize @minus
                   2135: @item
1.1.1.6   root     2136: Linux (referred as qemu-linux-user)
1.1.1.5   root     2137: @item
1.1.1.6   root     2138: Mac OS X/Darwin (referred as qemu-darwin-user)
1.1.1.7   root     2139: @item
                   2140: BSD (referred as qemu-bsd-user)
1.1.1.5   root     2141: @end itemize
                   2142: 
                   2143: @node Linux User space emulator
                   2144: @section Linux User space emulator
1.1       root     2145: 
1.1.1.3   root     2146: @menu
                   2147: * Quick Start::
                   2148: * Wine launch::
                   2149: * Command line options::
1.1.1.4   root     2150: * Other binaries::
1.1.1.3   root     2151: @end menu
                   2152: 
                   2153: @node Quick Start
1.1.1.5   root     2154: @subsection Quick Start
1.1       root     2155: 
                   2156: In order to launch a Linux process, QEMU needs the process executable
1.1.1.6   root     2157: itself and all the target (x86) dynamic libraries used by it.
1.1       root     2158: 
                   2159: @itemize
                   2160: 
                   2161: @item On x86, you can just try to launch any process by using the native
                   2162: libraries:
                   2163: 
1.1.1.6   root     2164: @example
1.1       root     2165: qemu-i386 -L / /bin/ls
                   2166: @end example
                   2167: 
                   2168: @code{-L /} tells that the x86 dynamic linker must be searched with a
                   2169: @file{/} prefix.
                   2170: 
1.1.1.6   root     2171: @item Since QEMU is also a linux process, you can launch qemu with
                   2172: qemu (NOTE: you can only do that if you compiled QEMU from the sources):
1.1       root     2173: 
1.1.1.6   root     2174: @example
1.1       root     2175: qemu-i386 -L / qemu-i386 -L / /bin/ls
                   2176: @end example
                   2177: 
                   2178: @item On non x86 CPUs, you need first to download at least an x86 glibc
                   2179: (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
                   2180: @code{LD_LIBRARY_PATH} is not set:
                   2181: 
                   2182: @example
1.1.1.6   root     2183: unset LD_LIBRARY_PATH
1.1       root     2184: @end example
                   2185: 
                   2186: Then you can launch the precompiled @file{ls} x86 executable:
                   2187: 
                   2188: @example
                   2189: qemu-i386 tests/i386/ls
                   2190: @end example
1.1.1.12  root     2191: You can look at @file{scripts/qemu-binfmt-conf.sh} so that
1.1       root     2192: QEMU is automatically launched by the Linux kernel when you try to
                   2193: launch x86 executables. It requires the @code{binfmt_misc} module in the
                   2194: Linux kernel.
                   2195: 
                   2196: @item The x86 version of QEMU is also included. You can try weird things such as:
                   2197: @example
1.1.1.3   root     2198: qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
                   2199:           /usr/local/qemu-i386/bin/ls-i386
1.1       root     2200: @end example
                   2201: 
                   2202: @end itemize
                   2203: 
1.1.1.3   root     2204: @node Wine launch
1.1.1.5   root     2205: @subsection Wine launch
1.1       root     2206: 
                   2207: @itemize
                   2208: 
                   2209: @item Ensure that you have a working QEMU with the x86 glibc
                   2210: distribution (see previous section). In order to verify it, you must be
                   2211: able to do:
                   2212: 
                   2213: @example
                   2214: qemu-i386 /usr/local/qemu-i386/bin/ls-i386
                   2215: @end example
                   2216: 
                   2217: @item Download the binary x86 Wine install
1.1.1.6   root     2218: (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
1.1       root     2219: 
                   2220: @item Configure Wine on your account. Look at the provided script
1.1.1.3   root     2221: @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
1.1       root     2222: @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
                   2223: 
                   2224: @item Then you can try the example @file{putty.exe}:
                   2225: 
                   2226: @example
1.1.1.3   root     2227: qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
                   2228:           /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
1.1       root     2229: @end example
                   2230: 
                   2231: @end itemize
                   2232: 
1.1.1.3   root     2233: @node Command line options
1.1.1.5   root     2234: @subsection Command line options
1.1       root     2235: 
                   2236: @example
1.1.1.11  root     2237: usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...]
1.1       root     2238: @end example
                   2239: 
                   2240: @table @option
                   2241: @item -h
                   2242: Print the help
1.1.1.6   root     2243: @item -L path
1.1       root     2244: Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
                   2245: @item -s size
                   2246: Set the x86 stack size in bytes (default=524288)
1.1.1.7   root     2247: @item -cpu model
                   2248: Select CPU model (-cpu ? for list and additional feature selection)
1.1.1.12  root     2249: @item -ignore-environment
                   2250: Start with an empty environment. Without this option,
                   2251: the initial environment is a copy of the caller's environment.
                   2252: @item -E @var{var}=@var{value}
                   2253: Set environment @var{var} to @var{value}.
                   2254: @item -U @var{var}
                   2255: Remove @var{var} from the environment.
1.1.1.10  root     2256: @item -B offset
                   2257: Offset guest address by the specified number of bytes.  This is useful when
1.1.1.11  root     2258: the address region required by guest applications is reserved on the host.
                   2259: This option is currently only supported on some hosts.
                   2260: @item -R size
                   2261: Pre-allocate a guest virtual address space of the given size (in bytes).
1.1.1.12  root     2262: "G", "M", and "k" suffixes may be used when specifying the size.
1.1       root     2263: @end table
                   2264: 
                   2265: Debug options:
                   2266: 
                   2267: @table @option
                   2268: @item -d
                   2269: Activate log (logfile=/tmp/qemu.log)
                   2270: @item -p pagesize
                   2271: Act as if the host page size was 'pagesize' bytes
1.1.1.7   root     2272: @item -g port
                   2273: Wait gdb connection to port
1.1.1.9   root     2274: @item -singlestep
                   2275: Run the emulation in single step mode.
1.1       root     2276: @end table
                   2277: 
1.1.1.6   root     2278: Environment variables:
                   2279: 
                   2280: @table @env
                   2281: @item QEMU_STRACE
                   2282: Print system calls and arguments similar to the 'strace' program
                   2283: (NOTE: the actual 'strace' program will not work because the user
                   2284: space emulator hasn't implemented ptrace).  At the moment this is
                   2285: incomplete.  All system calls that don't have a specific argument
                   2286: format are printed with information for six arguments.  Many
                   2287: flag-style arguments don't have decoders and will show up as numbers.
                   2288: @end table
                   2289: 
1.1.1.4   root     2290: @node Other binaries
1.1.1.5   root     2291: @subsection Other binaries
1.1.1.4   root     2292: 
1.1.1.11  root     2293: @cindex user mode (Alpha)
                   2294: @command{qemu-alpha} TODO.
                   2295: 
                   2296: @cindex user mode (ARM)
                   2297: @command{qemu-armeb} TODO.
                   2298: 
                   2299: @cindex user mode (ARM)
1.1.1.4   root     2300: @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
                   2301: binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
                   2302: configurations), and arm-uclinux bFLT format binaries.
                   2303: 
1.1.1.11  root     2304: @cindex user mode (ColdFire)
                   2305: @cindex user mode (M68K)
1.1.1.5   root     2306: @command{qemu-m68k} is capable of running semihosted binaries using the BDM
                   2307: (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
                   2308: coldfire uClinux bFLT format binaries.
                   2309: 
1.1.1.4   root     2310: The binary format is detected automatically.
                   2311: 
1.1.1.11  root     2312: @cindex user mode (Cris)
                   2313: @command{qemu-cris} TODO.
                   2314: 
                   2315: @cindex user mode (i386)
                   2316: @command{qemu-i386} TODO.
                   2317: @command{qemu-x86_64} TODO.
                   2318: 
                   2319: @cindex user mode (Microblaze)
                   2320: @command{qemu-microblaze} TODO.
                   2321: 
                   2322: @cindex user mode (MIPS)
                   2323: @command{qemu-mips} TODO.
                   2324: @command{qemu-mipsel} TODO.
                   2325: 
                   2326: @cindex user mode (PowerPC)
                   2327: @command{qemu-ppc64abi32} TODO.
                   2328: @command{qemu-ppc64} TODO.
                   2329: @command{qemu-ppc} TODO.
                   2330: 
                   2331: @cindex user mode (SH4)
                   2332: @command{qemu-sh4eb} TODO.
                   2333: @command{qemu-sh4} TODO.
                   2334: 
                   2335: @cindex user mode (SPARC)
1.1.1.7   root     2336: @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
                   2337: 
1.1.1.6   root     2338: @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
                   2339: (Sparc64 CPU, 32 bit ABI).
                   2340: 
                   2341: @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
                   2342: SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
                   2343: 
1.1.1.5   root     2344: @node Mac OS X/Darwin User space emulator
                   2345: @section Mac OS X/Darwin User space emulator
                   2346: 
                   2347: @menu
                   2348: * Mac OS X/Darwin Status::
                   2349: * Mac OS X/Darwin Quick Start::
                   2350: * Mac OS X/Darwin Command line options::
                   2351: @end menu
                   2352: 
                   2353: @node Mac OS X/Darwin Status
                   2354: @subsection Mac OS X/Darwin Status
                   2355: 
                   2356: @itemize @minus
                   2357: @item
                   2358: target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
                   2359: @item
                   2360: target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
                   2361: @item
1.1.1.6   root     2362: target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
1.1.1.5   root     2363: @item
                   2364: target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
                   2365: @end itemize
                   2366: 
                   2367: [1] If you're host commpage can be executed by qemu.
                   2368: 
                   2369: @node Mac OS X/Darwin Quick Start
                   2370: @subsection Quick Start
                   2371: 
                   2372: In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
                   2373: itself and all the target dynamic libraries used by it. If you don't have the FAT
                   2374: libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
                   2375: CD or compile them by hand.
                   2376: 
                   2377: @itemize
                   2378: 
                   2379: @item On x86, you can just try to launch any process by using the native
                   2380: libraries:
                   2381: 
1.1.1.6   root     2382: @example
                   2383: qemu-i386 /bin/ls
1.1.1.5   root     2384: @end example
                   2385: 
                   2386: or to run the ppc version of the executable:
                   2387: 
1.1.1.6   root     2388: @example
                   2389: qemu-ppc /bin/ls
1.1.1.5   root     2390: @end example
                   2391: 
                   2392: @item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
                   2393: are installed:
                   2394: 
1.1.1.6   root     2395: @example
                   2396: qemu-i386 -L /opt/x86_root/ /bin/ls
1.1.1.5   root     2397: @end example
                   2398: 
                   2399: @code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
                   2400: @file{/opt/x86_root/usr/bin/dyld}.
                   2401: 
                   2402: @end itemize
                   2403: 
                   2404: @node Mac OS X/Darwin Command line options
                   2405: @subsection Command line options
                   2406: 
                   2407: @example
1.1.1.6   root     2408: usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
1.1.1.5   root     2409: @end example
                   2410: 
                   2411: @table @option
                   2412: @item -h
                   2413: Print the help
1.1.1.6   root     2414: @item -L path
1.1.1.5   root     2415: Set the library root path (default=/)
                   2416: @item -s size
                   2417: Set the stack size in bytes (default=524288)
                   2418: @end table
                   2419: 
                   2420: Debug options:
                   2421: 
                   2422: @table @option
                   2423: @item -d
                   2424: Activate log (logfile=/tmp/qemu.log)
                   2425: @item -p pagesize
                   2426: Act as if the host page size was 'pagesize' bytes
1.1.1.9   root     2427: @item -singlestep
                   2428: Run the emulation in single step mode.
1.1.1.5   root     2429: @end table
                   2430: 
1.1.1.7   root     2431: @node BSD User space emulator
                   2432: @section BSD User space emulator
                   2433: 
                   2434: @menu
                   2435: * BSD Status::
                   2436: * BSD Quick Start::
                   2437: * BSD Command line options::
                   2438: @end menu
                   2439: 
                   2440: @node BSD Status
                   2441: @subsection BSD Status
                   2442: 
                   2443: @itemize @minus
                   2444: @item
                   2445: target Sparc64 on Sparc64: Some trivial programs work.
                   2446: @end itemize
                   2447: 
                   2448: @node BSD Quick Start
                   2449: @subsection Quick Start
                   2450: 
                   2451: In order to launch a BSD process, QEMU needs the process executable
                   2452: itself and all the target dynamic libraries used by it.
                   2453: 
                   2454: @itemize
                   2455: 
                   2456: @item On Sparc64, you can just try to launch any process by using the native
                   2457: libraries:
                   2458: 
                   2459: @example
                   2460: qemu-sparc64 /bin/ls
                   2461: @end example
                   2462: 
                   2463: @end itemize
                   2464: 
                   2465: @node BSD Command line options
                   2466: @subsection Command line options
                   2467: 
                   2468: @example
                   2469: usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
                   2470: @end example
                   2471: 
                   2472: @table @option
                   2473: @item -h
                   2474: Print the help
                   2475: @item -L path
                   2476: Set the library root path (default=/)
                   2477: @item -s size
                   2478: Set the stack size in bytes (default=524288)
1.1.1.12  root     2479: @item -ignore-environment
                   2480: Start with an empty environment. Without this option,
                   2481: the initial environment is a copy of the caller's environment.
                   2482: @item -E @var{var}=@var{value}
                   2483: Set environment @var{var} to @var{value}.
                   2484: @item -U @var{var}
                   2485: Remove @var{var} from the environment.
1.1.1.7   root     2486: @item -bsd type
                   2487: Set the type of the emulated BSD Operating system. Valid values are
                   2488: FreeBSD, NetBSD and OpenBSD (default).
                   2489: @end table
                   2490: 
                   2491: Debug options:
                   2492: 
                   2493: @table @option
                   2494: @item -d
                   2495: Activate log (logfile=/tmp/qemu.log)
                   2496: @item -p pagesize
                   2497: Act as if the host page size was 'pagesize' bytes
1.1.1.9   root     2498: @item -singlestep
                   2499: Run the emulation in single step mode.
1.1.1.7   root     2500: @end table
                   2501: 
1.1       root     2502: @node compilation
                   2503: @chapter Compilation from the sources
                   2504: 
1.1.1.3   root     2505: @menu
                   2506: * Linux/Unix::
                   2507: * Windows::
                   2508: * Cross compilation for Windows with Linux::
                   2509: * Mac OS X::
1.1.1.11  root     2510: * Make targets::
1.1.1.3   root     2511: @end menu
                   2512: 
                   2513: @node Linux/Unix
1.1       root     2514: @section Linux/Unix
                   2515: 
                   2516: @subsection Compilation
                   2517: 
                   2518: First you must decompress the sources:
                   2519: @example
                   2520: cd /tmp
                   2521: tar zxvf qemu-x.y.z.tar.gz
                   2522: cd qemu-x.y.z
                   2523: @end example
                   2524: 
                   2525: Then you configure QEMU and build it (usually no options are needed):
                   2526: @example
                   2527: ./configure
                   2528: make
                   2529: @end example
                   2530: 
                   2531: Then type as root user:
                   2532: @example
                   2533: make install
                   2534: @end example
                   2535: to install QEMU in @file{/usr/local}.
                   2536: 
1.1.1.3   root     2537: @node Windows
1.1       root     2538: @section Windows
                   2539: 
                   2540: @itemize
                   2541: @item Install the current versions of MSYS and MinGW from
                   2542: @url{http://www.mingw.org/}. You can find detailed installation
                   2543: instructions in the download section and the FAQ.
                   2544: 
1.1.1.6   root     2545: @item Download
1.1       root     2546: the MinGW development library of SDL 1.2.x
1.1.1.3   root     2547: (@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
1.1.1.11  root     2548: @url{http://www.libsdl.org}. Unpack it in a temporary place and
                   2549: edit the @file{sdl-config} script so that it gives the
1.1       root     2550: correct SDL directory when invoked.
                   2551: 
1.1.1.11  root     2552: @item Install the MinGW version of zlib and make sure
                   2553: @file{zlib.h} and @file{libz.dll.a} are in
1.1.1.12  root     2554: MinGW's default header and linker search paths.
1.1.1.11  root     2555: 
1.1       root     2556: @item Extract the current version of QEMU.
1.1.1.6   root     2557: 
1.1       root     2558: @item Start the MSYS shell (file @file{msys.bat}).
                   2559: 
1.1.1.6   root     2560: @item Change to the QEMU directory. Launch @file{./configure} and
1.1       root     2561: @file{make}.  If you have problems using SDL, verify that
                   2562: @file{sdl-config} can be launched from the MSYS command line.
                   2563: 
1.1.1.6   root     2564: @item You can install QEMU in @file{Program Files/Qemu} by typing
1.1       root     2565: @file{make install}. Don't forget to copy @file{SDL.dll} in
                   2566: @file{Program Files/Qemu}.
                   2567: 
                   2568: @end itemize
                   2569: 
1.1.1.3   root     2570: @node Cross compilation for Windows with Linux
1.1       root     2571: @section Cross compilation for Windows with Linux
                   2572: 
                   2573: @itemize
                   2574: @item
                   2575: Install the MinGW cross compilation tools available at
                   2576: @url{http://www.mingw.org/}.
                   2577: 
1.1.1.11  root     2578: @item Download
                   2579: the MinGW development library of SDL 1.2.x
                   2580: (@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
                   2581: @url{http://www.libsdl.org}. Unpack it in a temporary place and
                   2582: edit the @file{sdl-config} script so that it gives the
                   2583: correct SDL directory when invoked.  Set up the @code{PATH} environment
                   2584: variable so that @file{sdl-config} can be launched by
1.1       root     2585: the QEMU configuration script.
                   2586: 
1.1.1.11  root     2587: @item Install the MinGW version of zlib and make sure
                   2588: @file{zlib.h} and @file{libz.dll.a} are in
1.1.1.12  root     2589: MinGW's default header and linker search paths.
1.1.1.11  root     2590: 
1.1.1.6   root     2591: @item
1.1       root     2592: Configure QEMU for Windows cross compilation:
                   2593: @example
1.1.1.11  root     2594: PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'
                   2595: @end example
                   2596: The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and
                   2597: MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.
1.1.1.12  root     2598: We set the @code{PATH} environment variable to ensure the MinGW version of @file{sdl-config} is used and
1.1.1.11  root     2599: use --cross-prefix to specify the name of the cross compiler.
                   2600: You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/Qemu}.
                   2601: 
                   2602: Under Fedora Linux, you can run:
                   2603: @example
                   2604: yum -y install mingw32-gcc mingw32-SDL mingw32-zlib
1.1       root     2605: @end example
1.1.1.11  root     2606: to get a suitable cross compilation environment.
1.1       root     2607: 
1.1.1.6   root     2608: @item You can install QEMU in the installation directory by typing
1.1.1.11  root     2609: @code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the
1.1.1.6   root     2610: installation directory.
1.1       root     2611: 
                   2612: @end itemize
                   2613: 
1.1.1.11  root     2614: Wine can be used to launch the resulting qemu.exe compiled for Win32.
1.1       root     2615: 
1.1.1.3   root     2616: @node Mac OS X
1.1       root     2617: @section Mac OS X
                   2618: 
                   2619: The Mac OS X patches are not fully merged in QEMU, so you should look
                   2620: at the QEMU mailing list archive to have all the necessary
                   2621: information.
                   2622: 
1.1.1.11  root     2623: @node Make targets
                   2624: @section Make targets
                   2625: 
                   2626: @table @code
                   2627: 
                   2628: @item make
                   2629: @item make all
                   2630: Make everything which is typically needed.
                   2631: 
                   2632: @item install
                   2633: TODO
                   2634: 
                   2635: @item install-doc
                   2636: TODO
                   2637: 
                   2638: @item make clean
                   2639: Remove most files which were built during make.
                   2640: 
                   2641: @item make distclean
                   2642: Remove everything which was built during make.
                   2643: 
                   2644: @item make dvi
                   2645: @item make html
                   2646: @item make info
                   2647: @item make pdf
                   2648: Create documentation in dvi, html, info or pdf format.
                   2649: 
                   2650: @item make cscope
                   2651: TODO
                   2652: 
                   2653: @item make defconfig
                   2654: (Re-)create some build configuration files.
                   2655: User made changes will be overwritten.
                   2656: 
                   2657: @item tar
                   2658: @item tarbin
                   2659: TODO
                   2660: 
                   2661: @end table
                   2662: 
                   2663: @node License
                   2664: @appendix License
                   2665: 
                   2666: QEMU is a trademark of Fabrice Bellard.
                   2667: 
                   2668: QEMU is released under the GNU General Public License (TODO: add link).
                   2669: Parts of QEMU have specific licenses, see file LICENSE.
                   2670: 
                   2671: TODO (refer to file LICENSE, include it, include the GPL?)
                   2672: 
1.1.1.3   root     2673: @node Index
1.1.1.11  root     2674: @appendix Index
                   2675: @menu
                   2676: * Concept Index::
                   2677: * Function Index::
                   2678: * Keystroke Index::
                   2679: * Program Index::
                   2680: * Data Type Index::
                   2681: * Variable Index::
                   2682: @end menu
                   2683: 
                   2684: @node Concept Index
                   2685: @section Concept Index
                   2686: This is the main index. Should we combine all keywords in one index? TODO
1.1.1.3   root     2687: @printindex cp
                   2688: 
1.1.1.11  root     2689: @node Function Index
                   2690: @section Function Index
                   2691: This index could be used for command line options and monitor functions.
                   2692: @printindex fn
                   2693: 
                   2694: @node Keystroke Index
                   2695: @section Keystroke Index
                   2696: 
                   2697: This is a list of all keystrokes which have a special function
                   2698: in system emulation.
                   2699: 
                   2700: @printindex ky
                   2701: 
                   2702: @node Program Index
                   2703: @section Program Index
                   2704: @printindex pg
                   2705: 
                   2706: @node Data Type Index
                   2707: @section Data Type Index
                   2708: 
                   2709: This index could be used for qdev device names and options.
                   2710: 
                   2711: @printindex tp
                   2712: 
                   2713: @node Variable Index
                   2714: @section Variable Index
                   2715: @printindex vr
                   2716: 
1.1.1.3   root     2717: @bye

unix.superglobalmegacorp.com