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

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

unix.superglobalmegacorp.com