File:  [Qemu by Fabrice Bellard] / qemu / qemu-doc.texi
Revision 1.1.1.14 (vendor branch): download - view: text, annotated - select for diffs
Tue Apr 24 19:16:29 2018 UTC (3 years, 1 month ago) by root
Branches: qemu, MAIN
CVS tags: qemu1001, HEAD
qemu 1.0.1

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

unix.superglobalmegacorp.com