File:  [Qemu by Fabrice Bellard] / qemu / qemu-doc.texi
Revision 1.1.1.12 (vendor branch): download - view: text, annotated - select for diffs
Tue Apr 24 18:33:09 2018 UTC (3 years, 1 month ago) by root
Branches: qemu, MAIN
CVS tags: qemu0150, qemu0141, qemu0140, HEAD
qemu 0.14.0

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

unix.superglobalmegacorp.com