File:  [Qemu by Fabrice Bellard] / qemu / qemu-doc.texi
Revision 1.1.1.13 (vendor branch): download - view: text, annotated - select for diffs
Tue Apr 24 18:55:28 2018 UTC (3 years, 5 months ago) by root
Branches: qemu, MAIN
CVS tags: qemu1000, qemu0151, HEAD
qemu 0.15.1

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

unix.superglobalmegacorp.com