File:  [Qemu by Fabrice Bellard] / qemu / qemu-doc.texi
Revision 1.1.1.7 (vendor branch): download - view: text, annotated - select for diffs
Tue Apr 24 16:50:14 2018 UTC (3 years, 2 months ago) by root
Branches: qemu, MAIN
CVS tags: qemu0104, qemu0103, qemu0102, qemu0101, qemu0100, HEAD
qemu 0.10.0

    1: \input texinfo @c -*- texinfo -*-
    2: @c %**start of header
    3: @setfilename qemu-doc.info
    4: @settitle QEMU Emulator User Documentation
    5: @exampleindent 0
    6: @paragraphindent 0
    7: @c %**end of header
    8: 
    9: @iftex
   10: @titlepage
   11: @sp 7
   12: @center @titlefont{QEMU Emulator}
   13: @sp 1
   14: @center @titlefont{User Documentation}
   15: @sp 3
   16: @end titlepage
   17: @end iftex
   18: 
   19: @ifnottex
   20: @node Top
   21: @top
   22: 
   23: @menu
   24: * Introduction::
   25: * Installation::
   26: * QEMU PC System emulator::
   27: * QEMU System emulator for non PC targets::
   28: * QEMU User space emulator::
   29: * compilation:: Compilation from the sources
   30: * Index::
   31: @end menu
   32: @end ifnottex
   33: 
   34: @contents
   35: 
   36: @node Introduction
   37: @chapter Introduction
   38: 
   39: @menu
   40: * intro_features:: Features
   41: @end menu
   42: 
   43: @node intro_features
   44: @section Features
   45: 
   46: QEMU is a FAST! processor emulator using dynamic translation to
   47: achieve good emulation speed.
   48: 
   49: QEMU has two operating modes:
   50: 
   51: @itemize @minus
   52: 
   53: @item
   54: Full system emulation. In this mode, QEMU emulates a full system (for
   55: example a PC), including one or several processors and various
   56: peripherals. It can be used to launch different Operating Systems
   57: without rebooting the PC or to debug system code.
   58: 
   59: @item
   60: User mode emulation. In this mode, QEMU can launch
   61: processes compiled for one CPU on another CPU. It can be used to
   62: launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
   63: to ease cross-compilation and cross-debugging.
   64: 
   65: @end itemize
   66: 
   67: QEMU can run without an host kernel driver and yet gives acceptable
   68: performance.
   69: 
   70: For system emulation, the following hardware targets are supported:
   71: @itemize
   72: @item PC (x86 or x86_64 processor)
   73: @item ISA PC (old style PC without PCI bus)
   74: @item PREP (PowerPC processor)
   75: @item G3 Beige PowerMac (PowerPC processor)
   76: @item Mac99 PowerMac (PowerPC processor, in progress)
   77: @item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
   78: @item Sun4u/Sun4v (64-bit Sparc processor, in progress)
   79: @item Malta board (32-bit and 64-bit MIPS processors)
   80: @item MIPS Magnum (64-bit MIPS processor)
   81: @item ARM Integrator/CP (ARM)
   82: @item ARM Versatile baseboard (ARM)
   83: @item ARM RealView Emulation baseboard (ARM)
   84: @item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
   85: @item Luminary Micro LM3S811EVB (ARM Cortex-M3)
   86: @item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
   87: @item Freescale MCF5208EVB (ColdFire V2).
   88: @item Arnewsh MCF5206 evaluation board (ColdFire V2).
   89: @item Palm Tungsten|E PDA (OMAP310 processor)
   90: @item N800 and N810 tablets (OMAP2420 processor)
   91: @item MusicPal (MV88W8618 ARM processor)
   92: @item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
   93: @item Siemens SX1 smartphone (OMAP310 processor)
   94: @end itemize
   95: 
   96: For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
   97: 
   98: @node Installation
   99: @chapter Installation
  100: 
  101: If you want to compile QEMU yourself, see @ref{compilation}.
  102: 
  103: @menu
  104: * install_linux::   Linux
  105: * install_windows:: Windows
  106: * install_mac::     Macintosh
  107: @end menu
  108: 
  109: @node install_linux
  110: @section Linux
  111: 
  112: If a precompiled package is available for your distribution - you just
  113: have to install it. Otherwise, see @ref{compilation}.
  114: 
  115: @node install_windows
  116: @section Windows
  117: 
  118: Download the experimental binary installer at
  119: @url{http://www.free.oszoo.org/@/download.html}.
  120: 
  121: @node install_mac
  122: @section Mac OS X
  123: 
  124: Download the experimental binary installer at
  125: @url{http://www.free.oszoo.org/@/download.html}.
  126: 
  127: @node QEMU PC System emulator
  128: @chapter QEMU PC System emulator
  129: 
  130: @menu
  131: * pcsys_introduction:: Introduction
  132: * pcsys_quickstart::   Quick Start
  133: * sec_invocation::     Invocation
  134: * pcsys_keys::         Keys
  135: * pcsys_monitor::      QEMU Monitor
  136: * disk_images::        Disk Images
  137: * pcsys_network::      Network emulation
  138: * direct_linux_boot::  Direct Linux Boot
  139: * pcsys_usb::          USB emulation
  140: * vnc_security::       VNC security
  141: * gdb_usage::          GDB usage
  142: * pcsys_os_specific::  Target OS specific information
  143: @end menu
  144: 
  145: @node pcsys_introduction
  146: @section Introduction
  147: 
  148: @c man begin DESCRIPTION
  149: 
  150: The QEMU PC System emulator simulates the
  151: following peripherals:
  152: 
  153: @itemize @minus
  154: @item
  155: i440FX host PCI bridge and PIIX3 PCI to ISA bridge
  156: @item
  157: Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
  158: extensions (hardware level, including all non standard modes).
  159: @item
  160: PS/2 mouse and keyboard
  161: @item
  162: 2 PCI IDE interfaces with hard disk and CD-ROM support
  163: @item
  164: Floppy disk
  165: @item
  166: PCI/ISA PCI network adapters
  167: @item
  168: Serial ports
  169: @item
  170: Creative SoundBlaster 16 sound card
  171: @item
  172: ENSONIQ AudioPCI ES1370 sound card
  173: @item
  174: Intel 82801AA AC97 Audio compatible sound card
  175: @item
  176: Adlib(OPL2) - Yamaha YM3812 compatible chip
  177: @item
  178: Gravis Ultrasound GF1 sound card
  179: @item
  180: CS4231A compatible sound card
  181: @item
  182: PCI UHCI USB controller and a virtual USB hub.
  183: @end itemize
  184: 
  185: SMP is supported with up to 255 CPUs.
  186: 
  187: Note that adlib, gus and cs4231a are only available when QEMU was
  188: configured with --audio-card-list option containing the name(s) of
  189: required card(s).
  190: 
  191: QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
  192: VGA BIOS.
  193: 
  194: QEMU uses YM3812 emulation by Tatsuyuki Satoh.
  195: 
  196: QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
  197: by Tibor "TS" Schütz.
  198: 
  199: CS4231A is the chip used in Windows Sound System and GUSMAX products
  200: 
  201: @c man end
  202: 
  203: @node pcsys_quickstart
  204: @section Quick Start
  205: 
  206: Download and uncompress the linux image (@file{linux.img}) and type:
  207: 
  208: @example
  209: qemu linux.img
  210: @end example
  211: 
  212: Linux should boot and give you a prompt.
  213: 
  214: @node sec_invocation
  215: @section Invocation
  216: 
  217: @example
  218: @c man begin SYNOPSIS
  219: usage: qemu [options] [@var{disk_image}]
  220: @c man end
  221: @end example
  222: 
  223: @c man begin OPTIONS
  224: @var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
  225: targets do not need a disk image.
  226: 
  227: General options:
  228: @table @option
  229: @item -h
  230: Display help and exit
  231: 
  232: @item -M @var{machine}
  233: Select the emulated @var{machine} (@code{-M ?} for list)
  234: 
  235: @item -cpu @var{model}
  236: Select CPU model (-cpu ? for list and additional feature selection)
  237: 
  238: @item -smp @var{n}
  239: Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
  240: CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
  241: to 4.
  242: 
  243: @item -fda @var{file}
  244: @item -fdb @var{file}
  245: Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
  246: use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
  247: 
  248: @item -hda @var{file}
  249: @item -hdb @var{file}
  250: @item -hdc @var{file}
  251: @item -hdd @var{file}
  252: Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
  253: 
  254: @item -cdrom @var{file}
  255: Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
  256: @option{-cdrom} at the same time). You can use the host CD-ROM by
  257: using @file{/dev/cdrom} as filename (@pxref{host_drives}).
  258: 
  259: @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
  260: 
  261: Define a new drive. Valid options are:
  262: 
  263: @table @code
  264: @item file=@var{file}
  265: This option defines which disk image (@pxref{disk_images}) to use with
  266: this drive. If the filename contains comma, you must double it
  267: (for instance, "file=my,,file" to use file "my,file").
  268: @item if=@var{interface}
  269: This option defines on which type on interface the drive is connected.
  270: Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
  271: @item bus=@var{bus},unit=@var{unit}
  272: These options define where is connected the drive by defining the bus number and
  273: the unit id.
  274: @item index=@var{index}
  275: This option defines where is connected the drive by using an index in the list
  276: of available connectors of a given interface type.
  277: @item media=@var{media}
  278: This option defines the type of the media: disk or cdrom.
  279: @item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
  280: These options have the same definition as they have in @option{-hdachs}.
  281: @item snapshot=@var{snapshot}
  282: @var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
  283: @item cache=@var{cache}
  284: @var{cache} is "none", "writeback", or "writethrough" and controls how the host cache is used to access block data.
  285: @item format=@var{format}
  286: Specify which disk @var{format} will be used rather than detecting
  287: the format.  Can be used to specifiy format=raw to avoid interpreting
  288: an untrusted format header.
  289: @item serial=@var{serial}
  290: This option specifies the serial number to assign to the device.
  291: @end table
  292: 
  293: By default, writethrough caching is used for all block device.  This means that
  294: the host page cache will be used to read and write data but write notification
  295: will be sent to the guest only when the data has been reported as written by
  296: the storage subsystem.
  297: 
  298: Writeback caching will report data writes as completed as soon as the data is
  299: present in the host page cache.  This is safe as long as you trust your host.
  300: If your host crashes or loses power, then the guest may experience data
  301: corruption.  When using the @option{-snapshot} option, writeback caching is
  302: used by default.
  303: 
  304: The host page can be avoided entirely with @option{cache=none}.  This will
  305: attempt to do disk IO directly to the guests memory.  QEMU may still perform
  306: an internal copy of the data.
  307: 
  308: Some block drivers perform badly with @option{cache=writethrough}, most notably,
  309: qcow2.  If performance is more important than correctness,
  310: @option{cache=writeback} should be used with qcow2.  By default, if no explicit
  311: caching is specified for a qcow2 disk image, @option{cache=writeback} will be
  312: used.  For all other disk types, @option{cache=writethrough} is the default.
  313: 
  314: Instead of @option{-cdrom} you can use:
  315: @example
  316: qemu -drive file=file,index=2,media=cdrom
  317: @end example
  318: 
  319: Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
  320: use:
  321: @example
  322: qemu -drive file=file,index=0,media=disk
  323: qemu -drive file=file,index=1,media=disk
  324: qemu -drive file=file,index=2,media=disk
  325: qemu -drive file=file,index=3,media=disk
  326: @end example
  327: 
  328: You can connect a CDROM to the slave of ide0:
  329: @example
  330: qemu -drive file=file,if=ide,index=1,media=cdrom
  331: @end example
  332: 
  333: If you don't specify the "file=" argument, you define an empty drive:
  334: @example
  335: qemu -drive if=ide,index=1,media=cdrom
  336: @end example
  337: 
  338: You can connect a SCSI disk with unit ID 6 on the bus #0:
  339: @example
  340: qemu -drive file=file,if=scsi,bus=0,unit=6
  341: @end example
  342: 
  343: Instead of @option{-fda}, @option{-fdb}, you can use:
  344: @example
  345: qemu -drive file=file,index=0,if=floppy
  346: qemu -drive file=file,index=1,if=floppy
  347: @end example
  348: 
  349: By default, @var{interface} is "ide" and @var{index} is automatically
  350: incremented:
  351: @example
  352: qemu -drive file=a -drive file=b"
  353: @end example
  354: is interpreted like:
  355: @example
  356: qemu -hda a -hdb b
  357: @end example
  358: 
  359: @item -mtdblock file
  360: Use 'file' as on-board Flash memory image.
  361: 
  362: @item -sd file
  363: Use 'file' as SecureDigital card image.
  364: 
  365: @item -pflash file
  366: Use 'file' as a parallel flash image.
  367: 
  368: @item -boot [a|c|d|n]
  369: Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
  370: is the default.
  371: 
  372: @item -snapshot
  373: Write to temporary files instead of disk image files. In this case,
  374: the raw disk image you use is not written back. You can however force
  375: the write back by pressing @key{C-a s} (@pxref{disk_images}).
  376: 
  377: @item -m @var{megs}
  378: Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
  379: a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
  380: gigabytes respectively.
  381: 
  382: @item -k @var{language}
  383: 
  384: Use keyboard layout @var{language} (for example @code{fr} for
  385: French). This option is only needed where it is not easy to get raw PC
  386: keycodes (e.g. on Macs, with some X11 servers or with a VNC
  387: display). You don't normally need to use it on PC/Linux or PC/Windows
  388: hosts.
  389: 
  390: The available layouts are:
  391: @example
  392: ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
  393: da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
  394: de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
  395: @end example
  396: 
  397: The default is @code{en-us}.
  398: 
  399: @item -audio-help
  400: 
  401: Will show the audio subsystem help: list of drivers, tunable
  402: parameters.
  403: 
  404: @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
  405: 
  406: Enable audio and selected sound hardware. Use ? to print all
  407: available sound hardware.
  408: 
  409: @example
  410: qemu -soundhw sb16,adlib disk.img
  411: qemu -soundhw es1370 disk.img
  412: qemu -soundhw ac97 disk.img
  413: qemu -soundhw all disk.img
  414: qemu -soundhw ?
  415: @end example
  416: 
  417: Note that Linux's i810_audio OSS kernel (for AC97) module might
  418: require manually specifying clocking.
  419: 
  420: @example
  421: modprobe i810_audio clocking=48000
  422: @end example
  423: 
  424: @end table
  425: 
  426: USB options:
  427: @table @option
  428: 
  429: @item -usb
  430: Enable the USB driver (will be the default soon)
  431: 
  432: @item -usbdevice @var{devname}
  433: Add the USB device @var{devname}. @xref{usb_devices}.
  434: 
  435: @table @code
  436: 
  437: @item mouse
  438: Virtual Mouse. This will override the PS/2 mouse emulation when activated.
  439: 
  440: @item tablet
  441: Pointer device that uses absolute coordinates (like a touchscreen). This
  442: means qemu is able to report the mouse position without having to grab the
  443: mouse. Also overrides the PS/2 mouse emulation when activated.
  444: 
  445: @item disk:[format=@var{format}]:file
  446: Mass storage device based on file. The optional @var{format} argument
  447: will be used rather than detecting the format. Can be used to specifiy
  448: format=raw to avoid interpreting an untrusted format header.
  449: 
  450: @item host:bus.addr
  451: Pass through the host device identified by bus.addr (Linux only).
  452: 
  453: @item host:vendor_id:product_id
  454: Pass through the host device identified by vendor_id:product_id (Linux only).
  455: 
  456: @item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
  457: Serial converter to host character device @var{dev}, see @code{-serial} for the
  458: available devices.
  459: 
  460: @item braille
  461: Braille device.  This will use BrlAPI to display the braille output on a real
  462: or fake device.
  463: 
  464: @item net:options
  465: Network adapter that supports CDC ethernet and RNDIS protocols.
  466: 
  467: @end table
  468: 
  469: @item -name @var{name}
  470: Sets the @var{name} of the guest.
  471: This name will be displayed in the SDL window caption.
  472: The @var{name} will also be used for the VNC server.
  473: 
  474: @item -uuid @var{uuid}
  475: Set system UUID.
  476: 
  477: @end table
  478: 
  479: Display options:
  480: @table @option
  481: 
  482: @item -nographic
  483: 
  484: Normally, QEMU uses SDL to display the VGA output. With this option,
  485: you can totally disable graphical output so that QEMU is a simple
  486: command line application. The emulated serial port is redirected on
  487: the console. Therefore, you can still use QEMU to debug a Linux kernel
  488: with a serial console.
  489: 
  490: @item -curses
  491: 
  492: Normally, QEMU uses SDL to display the VGA output.  With this option,
  493: QEMU can display the VGA output when in text mode using a 
  494: curses/ncurses interface.  Nothing is displayed in graphical mode.
  495: 
  496: @item -no-frame
  497: 
  498: Do not use decorations for SDL windows and start them using the whole
  499: available screen space. This makes the using QEMU in a dedicated desktop
  500: workspace more convenient.
  501: 
  502: @item -alt-grab
  503: 
  504: Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt).
  505: 
  506: @item -no-quit
  507: 
  508: Disable SDL window close capability.
  509: 
  510: @item -sdl
  511: 
  512: Enable SDL.
  513: 
  514: @item -portrait
  515: 
  516: Rotate graphical output 90 deg left (only PXA LCD).
  517: 
  518: @item -vga @var{type}
  519: Select type of VGA card to emulate. Valid values for @var{type} are
  520: @table @code
  521: @item cirrus
  522: Cirrus Logic GD5446 Video card. All Windows versions starting from
  523: Windows 95 should recognize and use this graphic card. For optimal
  524: performances, use 16 bit color depth in the guest and the host OS.
  525: (This one is the default)
  526: @item std
  527: Standard VGA card with Bochs VBE extensions.  If your guest OS
  528: supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
  529: to use high resolution modes (>= 1280x1024x16) then you should use
  530: this option.
  531: @item vmware
  532: VMWare SVGA-II compatible adapter. Use it if you have sufficiently
  533: recent XFree86/XOrg server or Windows guest with a driver for this
  534: card.
  535: @item none
  536: Disable VGA card.
  537: @end table
  538: 
  539: @item -full-screen
  540: Start in full screen.
  541: 
  542: @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
  543: 
  544: Normally, QEMU uses SDL to display the VGA output.  With this option,
  545: you can have QEMU listen on VNC display @var{display} and redirect the VGA
  546: display over the VNC session.  It is very useful to enable the usb
  547: tablet device when using this option (option @option{-usbdevice
  548: tablet}). When using the VNC display, you must use the @option{-k}
  549: parameter to set the keyboard layout if you are not using en-us. Valid
  550: syntax for the @var{display} is
  551: 
  552: @table @code
  553: 
  554: @item @var{host}:@var{d}
  555: 
  556: TCP connections will only be allowed from @var{host} on display @var{d}.
  557: By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
  558: be omitted in which case the server will accept connections from any host.
  559: 
  560: @item @code{unix}:@var{path}
  561: 
  562: Connections will be allowed over UNIX domain sockets where @var{path} is the
  563: location of a unix socket to listen for connections on.
  564: 
  565: @item none
  566: 
  567: VNC is initialized but not started. The monitor @code{change} command
  568: can be used to later start the VNC server.
  569: 
  570: @end table
  571: 
  572: Following the @var{display} value there may be one or more @var{option} flags
  573: separated by commas. Valid options are
  574: 
  575: @table @code
  576: 
  577: @item reverse
  578: 
  579: Connect to a listening VNC client via a ``reverse'' connection. The
  580: client is specified by the @var{display}. For reverse network
  581: connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
  582: is a TCP port number, not a display number.
  583: 
  584: @item password
  585: 
  586: Require that password based authentication is used for client connections.
  587: The password must be set separately using the @code{change} command in the
  588: @ref{pcsys_monitor}
  589: 
  590: @item tls
  591: 
  592: Require that client use TLS when communicating with the VNC server. This
  593: uses anonymous TLS credentials so is susceptible to a man-in-the-middle
  594: attack. It is recommended that this option be combined with either the
  595: @var{x509} or @var{x509verify} options.
  596: 
  597: @item x509=@var{/path/to/certificate/dir}
  598: 
  599: Valid if @option{tls} is specified. Require that x509 credentials are used
  600: for negotiating the TLS session. The server will send its x509 certificate
  601: to the client. It is recommended that a password be set on the VNC server
  602: to provide authentication of the client when this is used. The path following
  603: this option specifies where the x509 certificates are to be loaded from.
  604: See the @ref{vnc_security} section for details on generating certificates.
  605: 
  606: @item x509verify=@var{/path/to/certificate/dir}
  607: 
  608: Valid if @option{tls} is specified. Require that x509 credentials are used
  609: for negotiating the TLS session. The server will send its x509 certificate
  610: to the client, and request that the client send its own x509 certificate.
  611: The server will validate the client's certificate against the CA certificate,
  612: and reject clients when validation fails. If the certificate authority is
  613: trusted, this is a sufficient authentication mechanism. You may still wish
  614: to set a password on the VNC server as a second authentication layer. The
  615: path following this option specifies where the x509 certificates are to
  616: be loaded from. See the @ref{vnc_security} section for details on generating
  617: certificates.
  618: 
  619: @end table
  620: 
  621: @end table
  622: 
  623: Network options:
  624: 
  625: @table @option
  626: 
  627: @item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}][,name=@var{name}]
  628: Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
  629: = 0 is the default). The NIC is an ne2k_pci by default on the PC
  630: target. Optionally, the MAC address can be changed to @var{addr}
  631: and a @var{name} can be assigned for use in monitor commands. If no
  632: @option{-net} option is specified, a single NIC is created.
  633: Qemu can emulate several different models of network card.
  634: Valid values for @var{type} are
  635: @code{i82551}, @code{i82557b}, @code{i82559er},
  636: @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
  637: @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
  638: Not all devices are supported on all targets.  Use -net nic,model=?
  639: for a list of available devices for your target.
  640: 
  641: @item -net user[,vlan=@var{n}][,hostname=@var{name}][,name=@var{name}]
  642: Use the user mode network stack which requires no administrator
  643: privilege to run.  @option{hostname=name} can be used to specify the client
  644: hostname reported by the builtin DHCP server.
  645: 
  646: @item -net channel,@var{port}:@var{dev}
  647: Forward @option{user} TCP connection to port @var{port} to character device @var{dev}
  648: 
  649: @item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}]
  650: Connect the host TAP network interface @var{name} to VLAN @var{n}, use
  651: the network script @var{file} to configure it and the network script 
  652: @var{dfile} to deconfigure it. If @var{name} is not provided, the OS 
  653: automatically provides one. @option{fd}=@var{h} can be used to specify
  654: the handle of an already opened host TAP interface. The default network 
  655: configure script is @file{/etc/qemu-ifup} and the default network 
  656: deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no} 
  657: or @option{downscript=no} to disable script execution. Example:
  658: 
  659: @example
  660: qemu linux.img -net nic -net tap
  661: @end example
  662: 
  663: More complicated example (two NICs, each one connected to a TAP device)
  664: @example
  665: qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
  666:                -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
  667: @end example
  668: 
  669: 
  670: @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
  671: 
  672: Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
  673: machine using a TCP socket connection. If @option{listen} is
  674: specified, QEMU waits for incoming connections on @var{port}
  675: (@var{host} is optional). @option{connect} is used to connect to
  676: another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
  677: specifies an already opened TCP socket.
  678: 
  679: Example:
  680: @example
  681: # launch a first QEMU instance
  682: qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
  683:                -net socket,listen=:1234
  684: # connect the VLAN 0 of this instance to the VLAN 0
  685: # of the first instance
  686: qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
  687:                -net socket,connect=127.0.0.1:1234
  688: @end example
  689: 
  690: @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
  691: 
  692: Create a VLAN @var{n} shared with another QEMU virtual
  693: machines using a UDP multicast socket, effectively making a bus for
  694: every QEMU with same multicast address @var{maddr} and @var{port}.
  695: NOTES:
  696: @enumerate
  697: @item
  698: Several QEMU can be running on different hosts and share same bus (assuming
  699: correct multicast setup for these hosts).
  700: @item
  701: mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
  702: @url{http://user-mode-linux.sf.net}.
  703: @item
  704: Use @option{fd=h} to specify an already opened UDP multicast socket.
  705: @end enumerate
  706: 
  707: Example:
  708: @example
  709: # launch one QEMU instance
  710: qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
  711:                -net socket,mcast=230.0.0.1:1234
  712: # launch another QEMU instance on same "bus"
  713: qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
  714:                -net socket,mcast=230.0.0.1:1234
  715: # launch yet another QEMU instance on same "bus"
  716: qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
  717:                -net socket,mcast=230.0.0.1:1234
  718: @end example
  719: 
  720: Example (User Mode Linux compat.):
  721: @example
  722: # launch QEMU instance (note mcast address selected
  723: # is UML's default)
  724: qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
  725:                -net socket,mcast=239.192.168.1:1102
  726: # launch UML
  727: /path/to/linux ubd0=/path/to/root_fs eth0=mcast
  728: @end example
  729: 
  730: @item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
  731: Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
  732: listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
  733: and MODE @var{octalmode} to change default ownership and permissions for
  734: communication port. This option is available only if QEMU has been compiled
  735: with vde support enabled.
  736: 
  737: Example:
  738: @example
  739: # launch vde switch
  740: vde_switch -F -sock /tmp/myswitch
  741: # launch QEMU instance
  742: qemu linux.img -net nic -net vde,sock=/tmp/myswitch
  743: @end example
  744: 
  745: @item -net none
  746: Indicate that no network devices should be configured. It is used to
  747: override the default configuration (@option{-net nic -net user}) which
  748: is activated if no @option{-net} options are provided.
  749: 
  750: @item -tftp @var{dir}
  751: When using the user mode network stack, activate a built-in TFTP
  752: server. The files in @var{dir} will be exposed as the root of a TFTP server.
  753: The TFTP client on the guest must be configured in binary mode (use the command
  754: @code{bin} of the Unix TFTP client). The host IP address on the guest is as
  755: usual 10.0.2.2.
  756: 
  757: @item -bootp @var{file}
  758: When using the user mode network stack, broadcast @var{file} as the BOOTP
  759: filename.  In conjunction with @option{-tftp}, this can be used to network boot
  760: a guest from a local directory.
  761: 
  762: Example (using pxelinux):
  763: @example
  764: qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0
  765: @end example
  766: 
  767: @item -smb @var{dir}
  768: When using the user mode network stack, activate a built-in SMB
  769: server so that Windows OSes can access to the host files in @file{@var{dir}}
  770: transparently.
  771: 
  772: In the guest Windows OS, the line:
  773: @example
  774: 10.0.2.4 smbserver
  775: @end example
  776: must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
  777: or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
  778: 
  779: Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
  780: 
  781: Note that a SAMBA server must be installed on the host OS in
  782: @file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version
  783: 2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
  784: 
  785: @item -redir [tcp|udp]:@var{host-port}:[@var{guest-host}]:@var{guest-port}
  786: 
  787: When using the user mode network stack, redirect incoming TCP or UDP
  788: connections to the host port @var{host-port} to the guest
  789: @var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
  790: is not specified, its value is 10.0.2.15 (default address given by the
  791: built-in DHCP server).
  792: 
  793: For example, to redirect host X11 connection from screen 1 to guest
  794: screen 0, use the following:
  795: 
  796: @example
  797: # on the host
  798: qemu -redir tcp:6001::6000 [...]
  799: # this host xterm should open in the guest X11 server
  800: xterm -display :1
  801: @end example
  802: 
  803: To redirect telnet connections from host port 5555 to telnet port on
  804: the guest, use the following:
  805: 
  806: @example
  807: # on the host
  808: qemu -redir tcp:5555::23 [...]
  809: telnet localhost 5555
  810: @end example
  811: 
  812: Then when you use on the host @code{telnet localhost 5555}, you
  813: connect to the guest telnet server.
  814: 
  815: @end table
  816: 
  817: Bluetooth(R) options:
  818: @table @option
  819: 
  820: @item -bt hci[...]
  821: Defines the function of the corresponding Bluetooth HCI.  -bt options
  822: are matched with the HCIs present in the chosen machine type.  For
  823: example when emulating a machine with only one HCI built into it, only
  824: the first @code{-bt hci[...]} option is valid and defines the HCI's
  825: logic.  The Transport Layer is decided by the machine type.  Currently
  826: the machines @code{n800} and @code{n810} have one HCI and all other
  827: machines have none.
  828: 
  829: @anchor{bt-hcis}
  830: The following three types are recognized:
  831: 
  832: @table @code
  833: @item -bt hci,null
  834: (default) The corresponding Bluetooth HCI assumes no internal logic
  835: and will not respond to any HCI commands or emit events.
  836: 
  837: @item -bt hci,host[:@var{id}]
  838: (@code{bluez} only) The corresponding HCI passes commands / events
  839: to / from the physical HCI identified by the name @var{id} (default:
  840: @code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
  841: capable systems like Linux.
  842: 
  843: @item -bt hci[,vlan=@var{n}]
  844: Add a virtual, standard HCI that will participate in the Bluetooth
  845: scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
  846: VLANs, devices inside a bluetooth network @var{n} can only communicate
  847: with other devices in the same network (scatternet).
  848: @end table
  849: 
  850: @item -bt vhci[,vlan=@var{n}]
  851: (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
  852: to the host bluetooth stack instead of to the emulated target.  This
  853: allows the host and target machines to participate in a common scatternet
  854: and communicate.  Requires the Linux @code{vhci} driver installed.  Can
  855: be used as following:
  856: 
  857: @example
  858: qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
  859: @end example
  860: 
  861: @item -bt device:@var{dev}[,vlan=@var{n}]
  862: Emulate a bluetooth device @var{dev} and place it in network @var{n}
  863: (default @code{0}).  QEMU can only emulate one type of bluetooth devices
  864: currently:
  865: 
  866: @table @code
  867: @item keyboard
  868: Virtual wireless keyboard implementing the HIDP bluetooth profile.
  869: @end table
  870: 
  871: @end table
  872: 
  873: i386 target only:
  874: 
  875: @table @option
  876: 
  877: @item -win2k-hack
  878: Use it when installing Windows 2000 to avoid a disk full bug. After
  879: Windows 2000 is installed, you no longer need this option (this option
  880: slows down the IDE transfers).
  881: 
  882: @item -rtc-td-hack
  883: Use it if you experience time drift problem in Windows with ACPI HAL.
  884: This option will try to figure out how many timer interrupts were not
  885: processed by the Windows guest and will re-inject them.
  886: 
  887: @item -no-fd-bootchk
  888: Disable boot signature checking for floppy disks in Bochs BIOS. It may
  889: be needed to boot from old floppy disks.
  890: 
  891: @item -no-acpi
  892: Disable ACPI (Advanced Configuration and Power Interface) support. Use
  893: it if your guest OS complains about ACPI problems (PC target machine
  894: only).
  895: 
  896: @item -no-hpet
  897: Disable HPET support.
  898: 
  899: @item -acpitable [sig=@var{str}][,rev=@var{n}][,oem_id=@var{str}][,oem_table_id=@var{str}][,oem_rev=@var{n}] [,asl_compiler_id=@var{str}][,asl_compiler_rev=@var{n}][,data=@var{file1}[:@var{file2}]...]
  900: Add ACPI table with specified header fields and context from specified files.
  901: 
  902: @end table
  903: 
  904: Linux boot specific: When using these options, you can use a given
  905: Linux kernel without installing it in the disk image. It can be useful
  906: for easier testing of various kernels.
  907: 
  908: @table @option
  909: 
  910: @item -kernel @var{bzImage}
  911: Use @var{bzImage} as kernel image.
  912: 
  913: @item -append @var{cmdline}
  914: Use @var{cmdline} as kernel command line
  915: 
  916: @item -initrd @var{file}
  917: Use @var{file} as initial ram disk.
  918: 
  919: @end table
  920: 
  921: Debug/Expert options:
  922: @table @option
  923: 
  924: @item -serial @var{dev}
  925: Redirect the virtual serial port to host character device
  926: @var{dev}. The default device is @code{vc} in graphical mode and
  927: @code{stdio} in non graphical mode.
  928: 
  929: This option can be used several times to simulate up to 4 serial
  930: ports.
  931: 
  932: Use @code{-serial none} to disable all serial ports.
  933: 
  934: Available character devices are:
  935: @table @code
  936: @item vc[:WxH]
  937: Virtual console. Optionally, a width and height can be given in pixel with
  938: @example
  939: vc:800x600
  940: @end example
  941: It is also possible to specify width or height in characters:
  942: @example
  943: vc:80Cx24C
  944: @end example
  945: @item pty
  946: [Linux only] Pseudo TTY (a new PTY is automatically allocated)
  947: @item none
  948: No device is allocated.
  949: @item null
  950: void device
  951: @item /dev/XXX
  952: [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
  953: parameters are set according to the emulated ones.
  954: @item /dev/parport@var{N}
  955: [Linux only, parallel port only] Use host parallel port
  956: @var{N}. Currently SPP and EPP parallel port features can be used.
  957: @item file:@var{filename}
  958: Write output to @var{filename}. No character can be read.
  959: @item stdio
  960: [Unix only] standard input/output
  961: @item pipe:@var{filename}
  962: name pipe @var{filename}
  963: @item COM@var{n}
  964: [Windows only] Use host serial port @var{n}
  965: @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
  966: This implements UDP Net Console.
  967: When @var{remote_host} or @var{src_ip} are not specified
  968: they default to @code{0.0.0.0}.
  969: When not using a specified @var{src_port} a random port is automatically chosen.
  970: @item msmouse
  971: Three button serial mouse. Configure the guest to use Microsoft protocol.
  972: 
  973: If you just want a simple readonly console you can use @code{netcat} or
  974: @code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
  975: @code{nc -u -l -p 4555}. Any time qemu writes something to that port it
  976: will appear in the netconsole session.
  977: 
  978: If you plan to send characters back via netconsole or you want to stop
  979: and start qemu a lot of times, you should have qemu use the same
  980: source port each time by using something like @code{-serial
  981: udp::4555@@:4556} to qemu. Another approach is to use a patched
  982: version of netcat which can listen to a TCP port and send and receive
  983: characters via udp.  If you have a patched version of netcat which
  984: activates telnet remote echo and single char transfer, then you can
  985: use the following options to step up a netcat redirector to allow
  986: telnet on port 5555 to access the qemu port.
  987: @table @code
  988: @item Qemu Options:
  989: -serial udp::4555@@:4556
  990: @item netcat options:
  991: -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
  992: @item telnet options:
  993: localhost 5555
  994: @end table
  995: 
  996: 
  997: @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
  998: The TCP Net Console has two modes of operation.  It can send the serial
  999: I/O to a location or wait for a connection from a location.  By default
 1000: the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
 1001: the @var{server} option QEMU will wait for a client socket application
 1002: to connect to the port before continuing, unless the @code{nowait}
 1003: option was specified.  The @code{nodelay} option disables the Nagle buffering
 1004: algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
 1005: one TCP connection at a time is accepted. You can use @code{telnet} to
 1006: connect to the corresponding character device.
 1007: @table @code
 1008: @item Example to send tcp console to 192.168.0.2 port 4444
 1009: -serial tcp:192.168.0.2:4444
 1010: @item Example to listen and wait on port 4444 for connection
 1011: -serial tcp::4444,server
 1012: @item Example to not wait and listen on ip 192.168.0.100 port 4444
 1013: -serial tcp:192.168.0.100:4444,server,nowait
 1014: @end table
 1015: 
 1016: @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
 1017: The telnet protocol is used instead of raw tcp sockets.  The options
 1018: work the same as if you had specified @code{-serial tcp}.  The
 1019: difference is that the port acts like a telnet server or client using
 1020: telnet option negotiation.  This will also allow you to send the
 1021: MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
 1022: sequence.  Typically in unix telnet you do it with Control-] and then
 1023: type "send break" followed by pressing the enter key.
 1024: 
 1025: @item unix:@var{path}[,server][,nowait]
 1026: A unix domain socket is used instead of a tcp socket.  The option works the
 1027: same as if you had specified @code{-serial tcp} except the unix domain socket
 1028: @var{path} is used for connections.
 1029: 
 1030: @item mon:@var{dev_string}
 1031: This is a special option to allow the monitor to be multiplexed onto
 1032: another serial port.  The monitor is accessed with key sequence of
 1033: @key{Control-a} and then pressing @key{c}. See monitor access
 1034: @ref{pcsys_keys} in the -nographic section for more keys.
 1035: @var{dev_string} should be any one of the serial devices specified
 1036: above.  An example to multiplex the monitor onto a telnet server
 1037: listening on port 4444 would be:
 1038: @table @code
 1039: @item -serial mon:telnet::4444,server,nowait
 1040: @end table
 1041: 
 1042: @item braille
 1043: Braille device.  This will use BrlAPI to display the braille output on a real
 1044: or fake device.
 1045: 
 1046: @end table
 1047: 
 1048: @item -parallel @var{dev}
 1049: Redirect the virtual parallel port to host device @var{dev} (same
 1050: devices as the serial port). On Linux hosts, @file{/dev/parportN} can
 1051: be used to use hardware devices connected on the corresponding host
 1052: parallel port.
 1053: 
 1054: This option can be used several times to simulate up to 3 parallel
 1055: ports.
 1056: 
 1057: Use @code{-parallel none} to disable all parallel ports.
 1058: 
 1059: @item -monitor @var{dev}
 1060: Redirect the monitor to host device @var{dev} (same devices as the
 1061: serial port).
 1062: The default device is @code{vc} in graphical mode and @code{stdio} in
 1063: non graphical mode.
 1064: 
 1065: @item -pidfile @var{file}
 1066: Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
 1067: from a script.
 1068: 
 1069: @item -S
 1070: Do not start CPU at startup (you must type 'c' in the monitor).
 1071: 
 1072: @item -s
 1073: Wait gdb connection to port 1234 (@pxref{gdb_usage}).
 1074: 
 1075: @item -p @var{port}
 1076: Change gdb connection port.  @var{port} can be either a decimal number
 1077: to specify a TCP port, or a host device (same devices as the serial port).
 1078: 
 1079: @item -d
 1080: Output log in /tmp/qemu.log
 1081: @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
 1082: Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
 1083: @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
 1084: translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
 1085: all those parameters. This option is useful for old MS-DOS disk
 1086: images.
 1087: 
 1088: @item -L  @var{path}
 1089: Set the directory for the BIOS, VGA BIOS and keymaps.
 1090: 
 1091: @item -bios @var{file}
 1092: Set the filename for the BIOS.
 1093: 
 1094: @item -kernel-kqemu
 1095: Enable KQEMU full virtualization (default is user mode only).
 1096: 
 1097: @item -no-kqemu
 1098: Disable KQEMU kernel module usage. KQEMU options are only available if
 1099: KQEMU support is enabled when compiling.
 1100: 
 1101: @item -enable-kvm
 1102: Enable KVM full virtualization support. This option is only available
 1103: if KVM support is enabled when compiling.
 1104: 
 1105: @item -no-reboot
 1106: Exit instead of rebooting.
 1107: 
 1108: @item -no-shutdown
 1109: Don't exit QEMU on guest shutdown, but instead only stop the emulation.
 1110: This allows for instance switching to monitor to commit changes to the
 1111: disk image.
 1112: 
 1113: @item -loadvm @var{file}
 1114: Start right away with a saved state (@code{loadvm} in monitor)
 1115: 
 1116: @item -daemonize
 1117: Daemonize the QEMU process after initialization.  QEMU will not detach from
 1118: standard IO until it is ready to receive connections on any of its devices.
 1119: This option is a useful way for external programs to launch QEMU without having
 1120: to cope with initialization race conditions.
 1121: 
 1122: @item -option-rom @var{file}
 1123: Load the contents of @var{file} as an option ROM.
 1124: This option is useful to load things like EtherBoot.
 1125: 
 1126: @item -clock @var{method}
 1127: Force the use of the given methods for timer alarm. To see what timers
 1128: are available use -clock ?.
 1129: 
 1130: @item -localtime
 1131: Set the real time clock to local time (the default is to UTC
 1132: time). This option is needed to have correct date in MS-DOS or
 1133: Windows.
 1134: 
 1135: @item -startdate @var{date}
 1136: Set the initial date of the real time clock. Valid formats for
 1137: @var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
 1138: @code{2006-06-17}. The default value is @code{now}.
 1139: 
 1140: @item -icount [N|auto]
 1141: Enable virtual instruction counter.  The virtual cpu will execute one
 1142: instruction every 2^N ns of virtual time.  If @code{auto} is specified
 1143: then the virtual cpu speed will be automatically adjusted to keep virtual
 1144: time within a few seconds of real time.
 1145: 
 1146: Note that while this option can give deterministic behavior, it does not
 1147: provide cycle accurate emulation.  Modern CPUs contain superscalar out of
 1148: order cores with complex cache hierarchies.  The number of instructions
 1149: executed often has little or no correlation with actual performance.
 1150: 
 1151: @item -echr numeric_ascii_value
 1152: Change the escape character used for switching to the monitor when using
 1153: monitor and serial sharing.  The default is @code{0x01} when using the
 1154: @code{-nographic} option.  @code{0x01} is equal to pressing
 1155: @code{Control-a}.  You can select a different character from the ascii
 1156: control keys where 1 through 26 map to Control-a through Control-z.  For
 1157: instance you could use the either of the following to change the escape
 1158: character to Control-t.
 1159: @table @code
 1160: @item -echr 0x14
 1161: @item -echr 20
 1162: @end table
 1163: 
 1164: @item -chroot dir
 1165: Immediately before starting guest execution, chroot to the specified
 1166: directory.  Especially useful in combination with -runas.
 1167: 
 1168: @item -runas user
 1169: Immediately before starting guest execution, drop root privileges, switching
 1170: to the specified user.
 1171: 
 1172: @end table
 1173: 
 1174: @c man end
 1175: 
 1176: @node pcsys_keys
 1177: @section Keys
 1178: 
 1179: @c man begin OPTIONS
 1180: 
 1181: During the graphical emulation, you can use the following keys:
 1182: @table @key
 1183: @item Ctrl-Alt-f
 1184: Toggle full screen
 1185: 
 1186: @item Ctrl-Alt-n
 1187: Switch to virtual console 'n'. Standard console mappings are:
 1188: @table @emph
 1189: @item 1
 1190: Target system display
 1191: @item 2
 1192: Monitor
 1193: @item 3
 1194: Serial port
 1195: @end table
 1196: 
 1197: @item Ctrl-Alt
 1198: Toggle mouse and keyboard grab.
 1199: @end table
 1200: 
 1201: In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
 1202: @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
 1203: 
 1204: During emulation, if you are using the @option{-nographic} option, use
 1205: @key{Ctrl-a h} to get terminal commands:
 1206: 
 1207: @table @key
 1208: @item Ctrl-a h
 1209: @item Ctrl-a ?
 1210: Print this help
 1211: @item Ctrl-a x
 1212: Exit emulator
 1213: @item Ctrl-a s
 1214: Save disk data back to file (if -snapshot)
 1215: @item Ctrl-a t
 1216: Toggle console timestamps
 1217: @item Ctrl-a b
 1218: Send break (magic sysrq in Linux)
 1219: @item Ctrl-a c
 1220: Switch between console and monitor
 1221: @item Ctrl-a Ctrl-a
 1222: Send Ctrl-a
 1223: @end table
 1224: @c man end
 1225: 
 1226: @ignore
 1227: 
 1228: @c man begin SEEALSO
 1229: The HTML documentation of QEMU for more precise information and Linux
 1230: user mode emulator invocation.
 1231: @c man end
 1232: 
 1233: @c man begin AUTHOR
 1234: Fabrice Bellard
 1235: @c man end
 1236: 
 1237: @end ignore
 1238: 
 1239: @node pcsys_monitor
 1240: @section QEMU Monitor
 1241: 
 1242: The QEMU monitor is used to give complex commands to the QEMU
 1243: emulator. You can use it to:
 1244: 
 1245: @itemize @minus
 1246: 
 1247: @item
 1248: Remove or insert removable media images
 1249: (such as CD-ROM or floppies).
 1250: 
 1251: @item
 1252: Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
 1253: from a disk file.
 1254: 
 1255: @item Inspect the VM state without an external debugger.
 1256: 
 1257: @end itemize
 1258: 
 1259: @subsection Commands
 1260: 
 1261: The following commands are available:
 1262: 
 1263: @table @option
 1264: 
 1265: @item help or ? [@var{cmd}]
 1266: Show the help for all commands or just for command @var{cmd}.
 1267: 
 1268: @item commit
 1269: Commit changes to the disk images (if -snapshot is used).
 1270: 
 1271: @item info @var{subcommand}
 1272: Show various information about the system state.
 1273: 
 1274: @table @option
 1275: @item info version
 1276: show the version of QEMU
 1277: @item info network
 1278: show the various VLANs and the associated devices
 1279: @item info chardev
 1280: show the character devices
 1281: @item info block
 1282: show the block devices
 1283: @item info block
 1284: show block device statistics
 1285: @item info registers
 1286: show the cpu registers
 1287: @item info cpus
 1288: show infos for each CPU
 1289: @item info history
 1290: show the command line history
 1291: @item info irq
 1292: show the interrupts statistics (if available)
 1293: @item info pic
 1294: show i8259 (PIC) state
 1295: @item info pci
 1296: show emulated PCI device info
 1297: @item info tlb
 1298: show virtual to physical memory mappings (i386 only)
 1299: @item info mem
 1300: show the active virtual memory mappings (i386 only)
 1301: @item info hpet
 1302: show state of HPET (i386 only)
 1303: @item info kqemu
 1304: show KQEMU information
 1305: @item info kvm
 1306: show KVM information
 1307: @item info usb
 1308: show USB devices plugged on the virtual USB hub
 1309: @item info usbhost
 1310: show all USB host devices
 1311: @item info profile
 1312: show profiling information
 1313: @item info capture
 1314: show information about active capturing
 1315: @item info snapshots
 1316: show list of VM snapshots
 1317: @item info status
 1318: show the current VM status (running|paused)
 1319: @item info pcmcia
 1320: show guest PCMCIA status
 1321: @item info mice
 1322: show which guest mouse is receiving events
 1323: @item info vnc
 1324: show the vnc server status
 1325: @item info name
 1326: show the current VM name
 1327: @item info uuid
 1328: show the current VM UUID
 1329: @item info cpustats
 1330: show CPU statistics
 1331: @item info slirp
 1332: show SLIRP statistics (if available)
 1333: @item info migrate
 1334: show migration status
 1335: @item info balloon
 1336: show balloon information
 1337: @end table
 1338: 
 1339: @item q or quit
 1340: Quit the emulator.
 1341: 
 1342: @item eject [-f] @var{device}
 1343: Eject a removable medium (use -f to force it).
 1344: 
 1345: @item change @var{device} @var{setting}
 1346: 
 1347: Change the configuration of a device.
 1348: 
 1349: @table @option
 1350: @item change @var{diskdevice} @var{filename} [@var{format}]
 1351: Change the medium for a removable disk device to point to @var{filename}. eg
 1352: 
 1353: @example
 1354: (qemu) change ide1-cd0 /path/to/some.iso
 1355: @end example
 1356: 
 1357: @var{format} is optional.
 1358: 
 1359: @item change vnc @var{display},@var{options}
 1360: Change the configuration of the VNC server. The valid syntax for @var{display}
 1361: and @var{options} are described at @ref{sec_invocation}. eg
 1362: 
 1363: @example
 1364: (qemu) change vnc localhost:1
 1365: @end example
 1366: 
 1367: @item change vnc password [@var{password}]
 1368: 
 1369: Change the password associated with the VNC server. If the new password is not
 1370: supplied, the monitor will prompt for it to be entered. VNC passwords are only
 1371: significant up to 8 letters. eg
 1372: 
 1373: @example
 1374: (qemu) change vnc password
 1375: Password: ********
 1376: @end example
 1377: 
 1378: @end table
 1379: 
 1380: @item screendump @var{filename}
 1381: Save screen into PPM image @var{filename}.
 1382: 
 1383: @item logfile @var{filename}
 1384: Output logs to @var{filename}.
 1385: 
 1386: @item log @var{item1}[,...]
 1387: Activate logging of the specified items to @file{/tmp/qemu.log}.
 1388: 
 1389: @item savevm [@var{tag}|@var{id}]
 1390: Create a snapshot of the whole virtual machine. If @var{tag} is
 1391: provided, it is used as human readable identifier. If there is already
 1392: a snapshot with the same tag or ID, it is replaced. More info at
 1393: @ref{vm_snapshots}.
 1394: 
 1395: @item loadvm @var{tag}|@var{id}
 1396: Set the whole virtual machine to the snapshot identified by the tag
 1397: @var{tag} or the unique snapshot ID @var{id}.
 1398: 
 1399: @item delvm @var{tag}|@var{id}
 1400: Delete the snapshot identified by @var{tag} or @var{id}.
 1401: 
 1402: @item stop
 1403: Stop emulation.
 1404: 
 1405: @item c or cont
 1406: Resume emulation.
 1407: 
 1408: @item gdbserver [@var{port}]
 1409: Start gdbserver session (default @var{port}=1234)
 1410: 
 1411: @item x/fmt @var{addr}
 1412: Virtual memory dump starting at @var{addr}.
 1413: 
 1414: @item xp /@var{fmt} @var{addr}
 1415: Physical memory dump starting at @var{addr}.
 1416: 
 1417: @var{fmt} is a format which tells the command how to format the
 1418: data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
 1419: 
 1420: @table @var
 1421: @item count
 1422: is the number of items to be dumped.
 1423: 
 1424: @item format
 1425: can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
 1426: c (char) or i (asm instruction).
 1427: 
 1428: @item size
 1429: can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
 1430: @code{h} or @code{w} can be specified with the @code{i} format to
 1431: respectively select 16 or 32 bit code instruction size.
 1432: 
 1433: @end table
 1434: 
 1435: Examples:
 1436: @itemize
 1437: @item
 1438: Dump 10 instructions at the current instruction pointer:
 1439: @example
 1440: (qemu) x/10i $eip
 1441: 0x90107063:  ret
 1442: 0x90107064:  sti
 1443: 0x90107065:  lea    0x0(%esi,1),%esi
 1444: 0x90107069:  lea    0x0(%edi,1),%edi
 1445: 0x90107070:  ret
 1446: 0x90107071:  jmp    0x90107080
 1447: 0x90107073:  nop
 1448: 0x90107074:  nop
 1449: 0x90107075:  nop
 1450: 0x90107076:  nop
 1451: @end example
 1452: 
 1453: @item
 1454: Dump 80 16 bit values at the start of the video memory.
 1455: @smallexample
 1456: (qemu) xp/80hx 0xb8000
 1457: 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
 1458: 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
 1459: 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
 1460: 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
 1461: 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
 1462: 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
 1463: 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 1464: 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 1465: 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 1466: 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 1467: @end smallexample
 1468: @end itemize
 1469: 
 1470: @item p or print/@var{fmt} @var{expr}
 1471: 
 1472: Print expression value. Only the @var{format} part of @var{fmt} is
 1473: used.
 1474: 
 1475: @item sendkey @var{keys}
 1476: 
 1477: Send @var{keys} to the emulator. @var{keys} could be the name of the
 1478: key or @code{#} followed by the raw value in either decimal or hexadecimal
 1479: format. Use @code{-} to press several keys simultaneously. Example:
 1480: @example
 1481: sendkey ctrl-alt-f1
 1482: @end example
 1483: 
 1484: This command is useful to send keys that your graphical user interface
 1485: intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
 1486: 
 1487: @item system_reset
 1488: 
 1489: Reset the system.
 1490: 
 1491: @item system_powerdown
 1492: 
 1493: Power down the system (if supported).
 1494: 
 1495: @item sum @var{addr} @var{size}
 1496: 
 1497: Compute the checksum of a memory region.
 1498: 
 1499: @item usb_add @var{devname}
 1500: 
 1501: Add the USB device @var{devname}.  For details of available devices see
 1502: @ref{usb_devices}
 1503: 
 1504: @item usb_del @var{devname}
 1505: 
 1506: Remove the USB device @var{devname} from the QEMU virtual USB
 1507: hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
 1508: command @code{info usb} to see the devices you can remove.
 1509: 
 1510: @item mouse_move @var{dx} @var{dy} [@var{dz}]
 1511: Move the active mouse to the specified coordinates @var{dx} @var{dy}
 1512: with optional scroll axis @var{dz}.
 1513: 
 1514: @item mouse_button @var{val}
 1515: Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
 1516: 
 1517: @item mouse_set @var{index}
 1518: Set which mouse device receives events at given @var{index}, index
 1519: can be obtained with
 1520: @example
 1521: info mice
 1522: @end example
 1523: 
 1524: @item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
 1525: Capture audio into @var{filename}. Using sample rate @var{frequency}
 1526: bits per sample @var{bits} and number of channels @var{channels}.
 1527: 
 1528: Defaults:
 1529: @itemize @minus
 1530: @item Sample rate = 44100 Hz - CD quality
 1531: @item Bits = 16
 1532: @item Number of channels = 2 - Stereo
 1533: @end itemize
 1534: 
 1535: @item stopcapture @var{index}
 1536: Stop capture with a given @var{index}, index can be obtained with
 1537: @example
 1538: info capture
 1539: @end example
 1540: 
 1541: @item memsave @var{addr} @var{size} @var{file}
 1542: save to disk virtual memory dump starting at @var{addr} of size @var{size}.
 1543: 
 1544: @item pmemsave @var{addr} @var{size} @var{file}
 1545: save to disk physical memory dump starting at @var{addr} of size @var{size}.
 1546: 
 1547: @item boot_set @var{bootdevicelist}
 1548: 
 1549: Define new values for the boot device list. Those values will override
 1550: the values specified on the command line through the @code{-boot} option.
 1551: 
 1552: The values that can be specified here depend on the machine type, but are
 1553: the same that can be specified in the @code{-boot} command line option.
 1554: 
 1555: @item nmi @var{cpu}
 1556: Inject an NMI on the given CPU.
 1557: 
 1558: @item migrate [-d] @var{uri}
 1559: Migrate to @var{uri} (using -d to not wait for completion).
 1560: 
 1561: @item migrate_cancel
 1562: Cancel the current VM migration.
 1563: 
 1564: @item migrate_set_speed @var{value}
 1565: Set maximum speed to @var{value} (in bytes) for migrations.
 1566: 
 1567: @item balloon @var{value}
 1568: Request VM to change its memory allocation to @var{value} (in MB).
 1569: 
 1570: @item set_link @var{name} [up|down]
 1571: Set link @var{name} up or down.
 1572: 
 1573: @end table
 1574: 
 1575: @subsection Integer expressions
 1576: 
 1577: The monitor understands integers expressions for every integer
 1578: argument. You can use register names to get the value of specifics
 1579: CPU registers by prefixing them with @emph{$}.
 1580: 
 1581: @node disk_images
 1582: @section Disk Images
 1583: 
 1584: Since version 0.6.1, QEMU supports many disk image formats, including
 1585: growable disk images (their size increase as non empty sectors are
 1586: written), compressed and encrypted disk images. Version 0.8.3 added
 1587: the new qcow2 disk image format which is essential to support VM
 1588: snapshots.
 1589: 
 1590: @menu
 1591: * disk_images_quickstart::    Quick start for disk image creation
 1592: * disk_images_snapshot_mode:: Snapshot mode
 1593: * vm_snapshots::              VM snapshots
 1594: * qemu_img_invocation::       qemu-img Invocation
 1595: * qemu_nbd_invocation::       qemu-nbd Invocation
 1596: * host_drives::               Using host drives
 1597: * disk_images_fat_images::    Virtual FAT disk images
 1598: * disk_images_nbd::           NBD access
 1599: @end menu
 1600: 
 1601: @node disk_images_quickstart
 1602: @subsection Quick start for disk image creation
 1603: 
 1604: You can create a disk image with the command:
 1605: @example
 1606: qemu-img create myimage.img mysize
 1607: @end example
 1608: where @var{myimage.img} is the disk image filename and @var{mysize} is its
 1609: size in kilobytes. You can add an @code{M} suffix to give the size in
 1610: megabytes and a @code{G} suffix for gigabytes.
 1611: 
 1612: See @ref{qemu_img_invocation} for more information.
 1613: 
 1614: @node disk_images_snapshot_mode
 1615: @subsection Snapshot mode
 1616: 
 1617: If you use the option @option{-snapshot}, all disk images are
 1618: considered as read only. When sectors in written, they are written in
 1619: a temporary file created in @file{/tmp}. You can however force the
 1620: write back to the raw disk images by using the @code{commit} monitor
 1621: command (or @key{C-a s} in the serial console).
 1622: 
 1623: @node vm_snapshots
 1624: @subsection VM snapshots
 1625: 
 1626: VM snapshots are snapshots of the complete virtual machine including
 1627: CPU state, RAM, device state and the content of all the writable
 1628: disks. In order to use VM snapshots, you must have at least one non
 1629: removable and writable block device using the @code{qcow2} disk image
 1630: format. Normally this device is the first virtual hard drive.
 1631: 
 1632: Use the monitor command @code{savevm} to create a new VM snapshot or
 1633: replace an existing one. A human readable name can be assigned to each
 1634: snapshot in addition to its numerical ID.
 1635: 
 1636: Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
 1637: a VM snapshot. @code{info snapshots} lists the available snapshots
 1638: with their associated information:
 1639: 
 1640: @example
 1641: (qemu) info snapshots
 1642: Snapshot devices: hda
 1643: Snapshot list (from hda):
 1644: ID        TAG                 VM SIZE                DATE       VM CLOCK
 1645: 1         start                   41M 2006-08-06 12:38:02   00:00:14.954
 1646: 2                                 40M 2006-08-06 12:43:29   00:00:18.633
 1647: 3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
 1648: @end example
 1649: 
 1650: A VM snapshot is made of a VM state info (its size is shown in
 1651: @code{info snapshots}) and a snapshot of every writable disk image.
 1652: The VM state info is stored in the first @code{qcow2} non removable
 1653: and writable block device. The disk image snapshots are stored in
 1654: every disk image. The size of a snapshot in a disk image is difficult
 1655: to evaluate and is not shown by @code{info snapshots} because the
 1656: associated disk sectors are shared among all the snapshots to save
 1657: disk space (otherwise each snapshot would need a full copy of all the
 1658: disk images).
 1659: 
 1660: When using the (unrelated) @code{-snapshot} option
 1661: (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
 1662: but they are deleted as soon as you exit QEMU.
 1663: 
 1664: VM snapshots currently have the following known limitations:
 1665: @itemize
 1666: @item
 1667: They cannot cope with removable devices if they are removed or
 1668: inserted after a snapshot is done.
 1669: @item
 1670: A few device drivers still have incomplete snapshot support so their
 1671: state is not saved or restored properly (in particular USB).
 1672: @end itemize
 1673: 
 1674: @node qemu_img_invocation
 1675: @subsection @code{qemu-img} Invocation
 1676: 
 1677: @include qemu-img.texi
 1678: 
 1679: @node qemu_nbd_invocation
 1680: @subsection @code{qemu-nbd} Invocation
 1681: 
 1682: @include qemu-nbd.texi
 1683: 
 1684: @node host_drives
 1685: @subsection Using host drives
 1686: 
 1687: In addition to disk image files, QEMU can directly access host
 1688: devices. We describe here the usage for QEMU version >= 0.8.3.
 1689: 
 1690: @subsubsection Linux
 1691: 
 1692: On Linux, you can directly use the host device filename instead of a
 1693: disk image filename provided you have enough privileges to access
 1694: it. For example, use @file{/dev/cdrom} to access to the CDROM or
 1695: @file{/dev/fd0} for the floppy.
 1696: 
 1697: @table @code
 1698: @item CD
 1699: You can specify a CDROM device even if no CDROM is loaded. QEMU has
 1700: specific code to detect CDROM insertion or removal. CDROM ejection by
 1701: the guest OS is supported. Currently only data CDs are supported.
 1702: @item Floppy
 1703: You can specify a floppy device even if no floppy is loaded. Floppy
 1704: removal is currently not detected accurately (if you change floppy
 1705: without doing floppy access while the floppy is not loaded, the guest
 1706: OS will think that the same floppy is loaded).
 1707: @item Hard disks
 1708: Hard disks can be used. Normally you must specify the whole disk
 1709: (@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
 1710: see it as a partitioned disk. WARNING: unless you know what you do, it
 1711: is better to only make READ-ONLY accesses to the hard disk otherwise
 1712: you may corrupt your host data (use the @option{-snapshot} command
 1713: line option or modify the device permissions accordingly).
 1714: @end table
 1715: 
 1716: @subsubsection Windows
 1717: 
 1718: @table @code
 1719: @item CD
 1720: The preferred syntax is the drive letter (e.g. @file{d:}). The
 1721: alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
 1722: supported as an alias to the first CDROM drive.
 1723: 
 1724: Currently there is no specific code to handle removable media, so it
 1725: is better to use the @code{change} or @code{eject} monitor commands to
 1726: change or eject media.
 1727: @item Hard disks
 1728: Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
 1729: where @var{N} is the drive number (0 is the first hard disk).
 1730: 
 1731: WARNING: unless you know what you do, it is better to only make
 1732: READ-ONLY accesses to the hard disk otherwise you may corrupt your
 1733: host data (use the @option{-snapshot} command line so that the
 1734: modifications are written in a temporary file).
 1735: @end table
 1736: 
 1737: 
 1738: @subsubsection Mac OS X
 1739: 
 1740: @file{/dev/cdrom} is an alias to the first CDROM.
 1741: 
 1742: Currently there is no specific code to handle removable media, so it
 1743: is better to use the @code{change} or @code{eject} monitor commands to
 1744: change or eject media.
 1745: 
 1746: @node disk_images_fat_images
 1747: @subsection Virtual FAT disk images
 1748: 
 1749: QEMU can automatically create a virtual FAT disk image from a
 1750: directory tree. In order to use it, just type:
 1751: 
 1752: @example
 1753: qemu linux.img -hdb fat:/my_directory
 1754: @end example
 1755: 
 1756: Then you access access to all the files in the @file{/my_directory}
 1757: directory without having to copy them in a disk image or to export
 1758: them via SAMBA or NFS. The default access is @emph{read-only}.
 1759: 
 1760: Floppies can be emulated with the @code{:floppy:} option:
 1761: 
 1762: @example
 1763: qemu linux.img -fda fat:floppy:/my_directory
 1764: @end example
 1765: 
 1766: A read/write support is available for testing (beta stage) with the
 1767: @code{:rw:} option:
 1768: 
 1769: @example
 1770: qemu linux.img -fda fat:floppy:rw:/my_directory
 1771: @end example
 1772: 
 1773: What you should @emph{never} do:
 1774: @itemize
 1775: @item use non-ASCII filenames ;
 1776: @item use "-snapshot" together with ":rw:" ;
 1777: @item expect it to work when loadvm'ing ;
 1778: @item write to the FAT directory on the host system while accessing it with the guest system.
 1779: @end itemize
 1780: 
 1781: @node disk_images_nbd
 1782: @subsection NBD access
 1783: 
 1784: QEMU can access directly to block device exported using the Network Block Device
 1785: protocol.
 1786: 
 1787: @example
 1788: qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
 1789: @end example
 1790: 
 1791: If the NBD server is located on the same host, you can use an unix socket instead
 1792: of an inet socket:
 1793: 
 1794: @example
 1795: qemu linux.img -hdb nbd:unix:/tmp/my_socket
 1796: @end example
 1797: 
 1798: In this case, the block device must be exported using qemu-nbd:
 1799: 
 1800: @example
 1801: qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
 1802: @end example
 1803: 
 1804: The use of qemu-nbd allows to share a disk between several guests:
 1805: @example
 1806: qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
 1807: @end example
 1808: 
 1809: and then you can use it with two guests:
 1810: @example
 1811: qemu linux1.img -hdb nbd:unix:/tmp/my_socket
 1812: qemu linux2.img -hdb nbd:unix:/tmp/my_socket
 1813: @end example
 1814: 
 1815: @node pcsys_network
 1816: @section Network emulation
 1817: 
 1818: QEMU can simulate several network cards (PCI or ISA cards on the PC
 1819: target) and can connect them to an arbitrary number of Virtual Local
 1820: Area Networks (VLANs). Host TAP devices can be connected to any QEMU
 1821: VLAN. VLAN can be connected between separate instances of QEMU to
 1822: simulate large networks. For simpler usage, a non privileged user mode
 1823: network stack can replace the TAP device to have a basic network
 1824: connection.
 1825: 
 1826: @subsection VLANs
 1827: 
 1828: QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
 1829: connection between several network devices. These devices can be for
 1830: example QEMU virtual Ethernet cards or virtual Host ethernet devices
 1831: (TAP devices).
 1832: 
 1833: @subsection Using TAP network interfaces
 1834: 
 1835: This is the standard way to connect QEMU to a real network. QEMU adds
 1836: a virtual network device on your host (called @code{tapN}), and you
 1837: can then configure it as if it was a real ethernet card.
 1838: 
 1839: @subsubsection Linux host
 1840: 
 1841: As an example, you can download the @file{linux-test-xxx.tar.gz}
 1842: archive and copy the script @file{qemu-ifup} in @file{/etc} and
 1843: configure properly @code{sudo} so that the command @code{ifconfig}
 1844: contained in @file{qemu-ifup} can be executed as root. You must verify
 1845: that your host kernel supports the TAP network interfaces: the
 1846: device @file{/dev/net/tun} must be present.
 1847: 
 1848: See @ref{sec_invocation} to have examples of command lines using the
 1849: TAP network interfaces.
 1850: 
 1851: @subsubsection Windows host
 1852: 
 1853: There is a virtual ethernet driver for Windows 2000/XP systems, called
 1854: TAP-Win32. But it is not included in standard QEMU for Windows,
 1855: so you will need to get it separately. It is part of OpenVPN package,
 1856: so download OpenVPN from : @url{http://openvpn.net/}.
 1857: 
 1858: @subsection Using the user mode network stack
 1859: 
 1860: By using the option @option{-net user} (default configuration if no
 1861: @option{-net} option is specified), QEMU uses a completely user mode
 1862: network stack (you don't need root privilege to use the virtual
 1863: network). The virtual network configuration is the following:
 1864: 
 1865: @example
 1866: 
 1867:          QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
 1868:                            |          (10.0.2.2)
 1869:                            |
 1870:                            ---->  DNS server (10.0.2.3)
 1871:                            |
 1872:                            ---->  SMB server (10.0.2.4)
 1873: @end example
 1874: 
 1875: The QEMU VM behaves as if it was behind a firewall which blocks all
 1876: incoming connections. You can use a DHCP client to automatically
 1877: configure the network in the QEMU VM. The DHCP server assign addresses
 1878: to the hosts starting from 10.0.2.15.
 1879: 
 1880: In order to check that the user mode network is working, you can ping
 1881: the address 10.0.2.2 and verify that you got an address in the range
 1882: 10.0.2.x from the QEMU virtual DHCP server.
 1883: 
 1884: Note that @code{ping} is not supported reliably to the internet as it
 1885: would require root privileges. It means you can only ping the local
 1886: router (10.0.2.2).
 1887: 
 1888: When using the built-in TFTP server, the router is also the TFTP
 1889: server.
 1890: 
 1891: When using the @option{-redir} option, TCP or UDP connections can be
 1892: redirected from the host to the guest. It allows for example to
 1893: redirect X11, telnet or SSH connections.
 1894: 
 1895: @subsection Connecting VLANs between QEMU instances
 1896: 
 1897: Using the @option{-net socket} option, it is possible to make VLANs
 1898: that span several QEMU instances. See @ref{sec_invocation} to have a
 1899: basic example.
 1900: 
 1901: @node direct_linux_boot
 1902: @section Direct Linux Boot
 1903: 
 1904: This section explains how to launch a Linux kernel inside QEMU without
 1905: having to make a full bootable image. It is very useful for fast Linux
 1906: kernel testing.
 1907: 
 1908: The syntax is:
 1909: @example
 1910: qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
 1911: @end example
 1912: 
 1913: Use @option{-kernel} to provide the Linux kernel image and
 1914: @option{-append} to give the kernel command line arguments. The
 1915: @option{-initrd} option can be used to provide an INITRD image.
 1916: 
 1917: When using the direct Linux boot, a disk image for the first hard disk
 1918: @file{hda} is required because its boot sector is used to launch the
 1919: Linux kernel.
 1920: 
 1921: If you do not need graphical output, you can disable it and redirect
 1922: the virtual serial port and the QEMU monitor to the console with the
 1923: @option{-nographic} option. The typical command line is:
 1924: @example
 1925: qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
 1926:      -append "root=/dev/hda console=ttyS0" -nographic
 1927: @end example
 1928: 
 1929: Use @key{Ctrl-a c} to switch between the serial console and the
 1930: monitor (@pxref{pcsys_keys}).
 1931: 
 1932: @node pcsys_usb
 1933: @section USB emulation
 1934: 
 1935: QEMU emulates a PCI UHCI USB controller. You can virtually plug
 1936: virtual USB devices or real host USB devices (experimental, works only
 1937: on Linux hosts).  Qemu will automatically create and connect virtual USB hubs
 1938: as necessary to connect multiple USB devices.
 1939: 
 1940: @menu
 1941: * usb_devices::
 1942: * host_usb_devices::
 1943: @end menu
 1944: @node usb_devices
 1945: @subsection Connecting USB devices
 1946: 
 1947: USB devices can be connected with the @option{-usbdevice} commandline option
 1948: or the @code{usb_add} monitor command.  Available devices are:
 1949: 
 1950: @table @code
 1951: @item mouse
 1952: Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
 1953: @item tablet
 1954: Pointer device that uses absolute coordinates (like a touchscreen).
 1955: This means qemu is able to report the mouse position without having
 1956: to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
 1957: @item disk:@var{file}
 1958: Mass storage device based on @var{file} (@pxref{disk_images})
 1959: @item host:@var{bus.addr}
 1960: Pass through the host device identified by @var{bus.addr}
 1961: (Linux only)
 1962: @item host:@var{vendor_id:product_id}
 1963: Pass through the host device identified by @var{vendor_id:product_id}
 1964: (Linux only)
 1965: @item wacom-tablet
 1966: Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
 1967: above but it can be used with the tslib library because in addition to touch
 1968: coordinates it reports touch pressure.
 1969: @item keyboard
 1970: Standard USB keyboard.  Will override the PS/2 keyboard (if present).
 1971: @item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
 1972: Serial converter. This emulates an FTDI FT232BM chip connected to host character
 1973: device @var{dev}. The available character devices are the same as for the
 1974: @code{-serial} option. The @code{vendorid} and @code{productid} options can be
 1975: used to override the default 0403:6001. For instance, 
 1976: @example
 1977: usb_add serial:productid=FA00:tcp:192.168.0.2:4444
 1978: @end example
 1979: will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
 1980: serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
 1981: @item braille
 1982: Braille device.  This will use BrlAPI to display the braille output on a real
 1983: or fake device.
 1984: @item net:@var{options}
 1985: Network adapter that supports CDC ethernet and RNDIS protocols.  @var{options}
 1986: specifies NIC options as with @code{-net nic,}@var{options} (see description).
 1987: For instance, user-mode networking can be used with
 1988: @example
 1989: qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
 1990: @end example
 1991: Currently this cannot be used in machines that support PCI NICs.
 1992: @item bt[:@var{hci-type}]
 1993: Bluetooth dongle whose type is specified in the same format as with
 1994: the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
 1995: no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
 1996: This USB device implements the USB Transport Layer of HCI.  Example
 1997: usage:
 1998: @example
 1999: qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
 2000: @end example
 2001: @end table
 2002: 
 2003: @node host_usb_devices
 2004: @subsection Using host USB devices on a Linux host
 2005: 
 2006: WARNING: this is an experimental feature. QEMU will slow down when
 2007: using it. USB devices requiring real time streaming (i.e. USB Video
 2008: Cameras) are not supported yet.
 2009: 
 2010: @enumerate
 2011: @item If you use an early Linux 2.4 kernel, verify that no Linux driver
 2012: is actually using the USB device. A simple way to do that is simply to
 2013: disable the corresponding kernel module by renaming it from @file{mydriver.o}
 2014: to @file{mydriver.o.disabled}.
 2015: 
 2016: @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
 2017: @example
 2018: ls /proc/bus/usb
 2019: 001  devices  drivers
 2020: @end example
 2021: 
 2022: @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:
 2023: @example
 2024: chown -R myuid /proc/bus/usb
 2025: @end example
 2026: 
 2027: @item Launch QEMU and do in the monitor:
 2028: @example
 2029: info usbhost
 2030:   Device 1.2, speed 480 Mb/s
 2031:     Class 00: USB device 1234:5678, USB DISK
 2032: @end example
 2033: You should see the list of the devices you can use (Never try to use
 2034: hubs, it won't work).
 2035: 
 2036: @item Add the device in QEMU by using:
 2037: @example
 2038: usb_add host:1234:5678
 2039: @end example
 2040: 
 2041: Normally the guest OS should report that a new USB device is
 2042: plugged. You can use the option @option{-usbdevice} to do the same.
 2043: 
 2044: @item Now you can try to use the host USB device in QEMU.
 2045: 
 2046: @end enumerate
 2047: 
 2048: When relaunching QEMU, you may have to unplug and plug again the USB
 2049: device to make it work again (this is a bug).
 2050: 
 2051: @node vnc_security
 2052: @section VNC security
 2053: 
 2054: The VNC server capability provides access to the graphical console
 2055: of the guest VM across the network. This has a number of security
 2056: considerations depending on the deployment scenarios.
 2057: 
 2058: @menu
 2059: * vnc_sec_none::
 2060: * vnc_sec_password::
 2061: * vnc_sec_certificate::
 2062: * vnc_sec_certificate_verify::
 2063: * vnc_sec_certificate_pw::
 2064: * vnc_generate_cert::
 2065: @end menu
 2066: @node vnc_sec_none
 2067: @subsection Without passwords
 2068: 
 2069: The simplest VNC server setup does not include any form of authentication.
 2070: For this setup it is recommended to restrict it to listen on a UNIX domain
 2071: socket only. For example
 2072: 
 2073: @example
 2074: qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
 2075: @end example
 2076: 
 2077: This ensures that only users on local box with read/write access to that
 2078: path can access the VNC server. To securely access the VNC server from a
 2079: remote machine, a combination of netcat+ssh can be used to provide a secure
 2080: tunnel.
 2081: 
 2082: @node vnc_sec_password
 2083: @subsection With passwords
 2084: 
 2085: The VNC protocol has limited support for password based authentication. Since
 2086: the protocol limits passwords to 8 characters it should not be considered
 2087: to provide high security. The password can be fairly easily brute-forced by
 2088: a client making repeat connections. For this reason, a VNC server using password
 2089: authentication should be restricted to only listen on the loopback interface
 2090: or UNIX domain sockets. Password authentication is requested with the @code{password}
 2091: option, and then once QEMU is running the password is set with the monitor. Until
 2092: the monitor is used to set the password all clients will be rejected.
 2093: 
 2094: @example
 2095: qemu [...OPTIONS...] -vnc :1,password -monitor stdio
 2096: (qemu) change vnc password
 2097: Password: ********
 2098: (qemu)
 2099: @end example
 2100: 
 2101: @node vnc_sec_certificate
 2102: @subsection With x509 certificates
 2103: 
 2104: The QEMU VNC server also implements the VeNCrypt extension allowing use of
 2105: TLS for encryption of the session, and x509 certificates for authentication.
 2106: The use of x509 certificates is strongly recommended, because TLS on its
 2107: own is susceptible to man-in-the-middle attacks. Basic x509 certificate
 2108: support provides a secure session, but no authentication. This allows any
 2109: client to connect, and provides an encrypted session.
 2110: 
 2111: @example
 2112: qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
 2113: @end example
 2114: 
 2115: In the above example @code{/etc/pki/qemu} should contain at least three files,
 2116: @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
 2117: users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
 2118: NB the @code{server-key.pem} file should be protected with file mode 0600 to
 2119: only be readable by the user owning it.
 2120: 
 2121: @node vnc_sec_certificate_verify
 2122: @subsection With x509 certificates and client verification
 2123: 
 2124: Certificates can also provide a means to authenticate the client connecting.
 2125: The server will request that the client provide a certificate, which it will
 2126: then validate against the CA certificate. This is a good choice if deploying
 2127: in an environment with a private internal certificate authority.
 2128: 
 2129: @example
 2130: qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
 2131: @end example
 2132: 
 2133: 
 2134: @node vnc_sec_certificate_pw
 2135: @subsection With x509 certificates, client verification and passwords
 2136: 
 2137: Finally, the previous method can be combined with VNC password authentication
 2138: to provide two layers of authentication for clients.
 2139: 
 2140: @example
 2141: qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
 2142: (qemu) change vnc password
 2143: Password: ********
 2144: (qemu)
 2145: @end example
 2146: 
 2147: @node vnc_generate_cert
 2148: @subsection Generating certificates for VNC
 2149: 
 2150: The GNU TLS packages provides a command called @code{certtool} which can
 2151: be used to generate certificates and keys in PEM format. At a minimum it
 2152: is neccessary to setup a certificate authority, and issue certificates to
 2153: each server. If using certificates for authentication, then each client
 2154: will also need to be issued a certificate. The recommendation is for the
 2155: server to keep its certificates in either @code{/etc/pki/qemu} or for
 2156: unprivileged users in @code{$HOME/.pki/qemu}.
 2157: 
 2158: @menu
 2159: * vnc_generate_ca::
 2160: * vnc_generate_server::
 2161: * vnc_generate_client::
 2162: @end menu
 2163: @node vnc_generate_ca
 2164: @subsubsection Setup the Certificate Authority
 2165: 
 2166: This step only needs to be performed once per organization / organizational
 2167: unit. First the CA needs a private key. This key must be kept VERY secret
 2168: and secure. If this key is compromised the entire trust chain of the certificates
 2169: issued with it is lost.
 2170: 
 2171: @example
 2172: # certtool --generate-privkey > ca-key.pem
 2173: @end example
 2174: 
 2175: A CA needs to have a public certificate. For simplicity it can be a self-signed
 2176: certificate, or one issue by a commercial certificate issuing authority. To
 2177: generate a self-signed certificate requires one core piece of information, the
 2178: name of the organization.
 2179: 
 2180: @example
 2181: # cat > ca.info <<EOF
 2182: cn = Name of your organization
 2183: ca
 2184: cert_signing_key
 2185: EOF
 2186: # certtool --generate-self-signed \
 2187:            --load-privkey ca-key.pem
 2188:            --template ca.info \
 2189:            --outfile ca-cert.pem
 2190: @end example
 2191: 
 2192: The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
 2193: TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
 2194: 
 2195: @node vnc_generate_server
 2196: @subsubsection Issuing server certificates
 2197: 
 2198: Each server (or host) needs to be issued with a key and certificate. When connecting
 2199: the certificate is sent to the client which validates it against the CA certificate.
 2200: The core piece of information for a server certificate is the hostname. This should
 2201: be the fully qualified hostname that the client will connect with, since the client
 2202: will typically also verify the hostname in the certificate. On the host holding the
 2203: secure CA private key:
 2204: 
 2205: @example
 2206: # cat > server.info <<EOF
 2207: organization = Name  of your organization
 2208: cn = server.foo.example.com
 2209: tls_www_server
 2210: encryption_key
 2211: signing_key
 2212: EOF
 2213: # certtool --generate-privkey > server-key.pem
 2214: # certtool --generate-certificate \
 2215:            --load-ca-certificate ca-cert.pem \
 2216:            --load-ca-privkey ca-key.pem \
 2217:            --load-privkey server server-key.pem \
 2218:            --template server.info \
 2219:            --outfile server-cert.pem
 2220: @end example
 2221: 
 2222: The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
 2223: to the server for which they were generated. The @code{server-key.pem} is security
 2224: sensitive and should be kept protected with file mode 0600 to prevent disclosure.
 2225: 
 2226: @node vnc_generate_client
 2227: @subsubsection Issuing client certificates
 2228: 
 2229: If the QEMU VNC server is to use the @code{x509verify} option to validate client
 2230: certificates as its authentication mechanism, each client also needs to be issued
 2231: a certificate. The client certificate contains enough metadata to uniquely identify
 2232: the client, typically organization, state, city, building, etc. On the host holding
 2233: the secure CA private key:
 2234: 
 2235: @example
 2236: # cat > client.info <<EOF
 2237: country = GB
 2238: state = London
 2239: locality = London
 2240: organiazation = Name of your organization
 2241: cn = client.foo.example.com
 2242: tls_www_client
 2243: encryption_key
 2244: signing_key
 2245: EOF
 2246: # certtool --generate-privkey > client-key.pem
 2247: # certtool --generate-certificate \
 2248:            --load-ca-certificate ca-cert.pem \
 2249:            --load-ca-privkey ca-key.pem \
 2250:            --load-privkey client-key.pem \
 2251:            --template client.info \
 2252:            --outfile client-cert.pem
 2253: @end example
 2254: 
 2255: The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
 2256: copied to the client for which they were generated.
 2257: 
 2258: @node gdb_usage
 2259: @section GDB usage
 2260: 
 2261: QEMU has a primitive support to work with gdb, so that you can do
 2262: 'Ctrl-C' while the virtual machine is running and inspect its state.
 2263: 
 2264: In order to use gdb, launch qemu with the '-s' option. It will wait for a
 2265: gdb connection:
 2266: @example
 2267: > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
 2268:        -append "root=/dev/hda"
 2269: Connected to host network interface: tun0
 2270: Waiting gdb connection on port 1234
 2271: @end example
 2272: 
 2273: Then launch gdb on the 'vmlinux' executable:
 2274: @example
 2275: > gdb vmlinux
 2276: @end example
 2277: 
 2278: In gdb, connect to QEMU:
 2279: @example
 2280: (gdb) target remote localhost:1234
 2281: @end example
 2282: 
 2283: Then you can use gdb normally. For example, type 'c' to launch the kernel:
 2284: @example
 2285: (gdb) c
 2286: @end example
 2287: 
 2288: Here are some useful tips in order to use gdb on system code:
 2289: 
 2290: @enumerate
 2291: @item
 2292: Use @code{info reg} to display all the CPU registers.
 2293: @item
 2294: Use @code{x/10i $eip} to display the code at the PC position.
 2295: @item
 2296: Use @code{set architecture i8086} to dump 16 bit code. Then use
 2297: @code{x/10i $cs*16+$eip} to dump the code at the PC position.
 2298: @end enumerate
 2299: 
 2300: Advanced debugging options:
 2301: 
 2302: 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:
 2303: @table @code
 2304: @item maintenance packet qqemu.sstepbits
 2305: 
 2306: This will display the MASK bits used to control the single stepping IE:
 2307: @example
 2308: (gdb) maintenance packet qqemu.sstepbits
 2309: sending: "qqemu.sstepbits"
 2310: received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
 2311: @end example
 2312: @item maintenance packet qqemu.sstep
 2313: 
 2314: This will display the current value of the mask used when single stepping IE:
 2315: @example
 2316: (gdb) maintenance packet qqemu.sstep
 2317: sending: "qqemu.sstep"
 2318: received: "0x7"
 2319: @end example
 2320: @item maintenance packet Qqemu.sstep=HEX_VALUE
 2321: 
 2322: This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
 2323: @example
 2324: (gdb) maintenance packet Qqemu.sstep=0x5
 2325: sending: "qemu.sstep=0x5"
 2326: received: "OK"
 2327: @end example
 2328: @end table
 2329: 
 2330: @node pcsys_os_specific
 2331: @section Target OS specific information
 2332: 
 2333: @subsection Linux
 2334: 
 2335: To have access to SVGA graphic modes under X11, use the @code{vesa} or
 2336: the @code{cirrus} X11 driver. For optimal performances, use 16 bit
 2337: color depth in the guest and the host OS.
 2338: 
 2339: When using a 2.6 guest Linux kernel, you should add the option
 2340: @code{clock=pit} on the kernel command line because the 2.6 Linux
 2341: kernels make very strict real time clock checks by default that QEMU
 2342: cannot simulate exactly.
 2343: 
 2344: When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
 2345: not activated because QEMU is slower with this patch. The QEMU
 2346: Accelerator Module is also much slower in this case. Earlier Fedora
 2347: Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
 2348: patch by default. Newer kernels don't have it.
 2349: 
 2350: @subsection Windows
 2351: 
 2352: If you have a slow host, using Windows 95 is better as it gives the
 2353: best speed. Windows 2000 is also a good choice.
 2354: 
 2355: @subsubsection SVGA graphic modes support
 2356: 
 2357: QEMU emulates a Cirrus Logic GD5446 Video
 2358: card. All Windows versions starting from Windows 95 should recognize
 2359: and use this graphic card. For optimal performances, use 16 bit color
 2360: depth in the guest and the host OS.
 2361: 
 2362: If you are using Windows XP as guest OS and if you want to use high
 2363: resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
 2364: 1280x1024x16), then you should use the VESA VBE virtual graphic card
 2365: (option @option{-std-vga}).
 2366: 
 2367: @subsubsection CPU usage reduction
 2368: 
 2369: Windows 9x does not correctly use the CPU HLT
 2370: instruction. The result is that it takes host CPU cycles even when
 2371: idle. You can install the utility from
 2372: @url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
 2373: problem. Note that no such tool is needed for NT, 2000 or XP.
 2374: 
 2375: @subsubsection Windows 2000 disk full problem
 2376: 
 2377: Windows 2000 has a bug which gives a disk full problem during its
 2378: installation. When installing it, use the @option{-win2k-hack} QEMU
 2379: option to enable a specific workaround. After Windows 2000 is
 2380: installed, you no longer need this option (this option slows down the
 2381: IDE transfers).
 2382: 
 2383: @subsubsection Windows 2000 shutdown
 2384: 
 2385: Windows 2000 cannot automatically shutdown in QEMU although Windows 98
 2386: can. It comes from the fact that Windows 2000 does not automatically
 2387: use the APM driver provided by the BIOS.
 2388: 
 2389: In order to correct that, do the following (thanks to Struan
 2390: Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
 2391: Add/Troubleshoot a device => Add a new device & Next => No, select the
 2392: hardware from a list & Next => NT Apm/Legacy Support & Next => Next
 2393: (again) a few times. Now the driver is installed and Windows 2000 now
 2394: correctly instructs QEMU to shutdown at the appropriate moment.
 2395: 
 2396: @subsubsection Share a directory between Unix and Windows
 2397: 
 2398: See @ref{sec_invocation} about the help of the option @option{-smb}.
 2399: 
 2400: @subsubsection Windows XP security problem
 2401: 
 2402: Some releases of Windows XP install correctly but give a security
 2403: error when booting:
 2404: @example
 2405: A problem is preventing Windows from accurately checking the
 2406: license for this computer. Error code: 0x800703e6.
 2407: @end example
 2408: 
 2409: The workaround is to install a service pack for XP after a boot in safe
 2410: mode. Then reboot, and the problem should go away. Since there is no
 2411: network while in safe mode, its recommended to download the full
 2412: installation of SP1 or SP2 and transfer that via an ISO or using the
 2413: vvfat block device ("-hdb fat:directory_which_holds_the_SP").
 2414: 
 2415: @subsection MS-DOS and FreeDOS
 2416: 
 2417: @subsubsection CPU usage reduction
 2418: 
 2419: DOS does not correctly use the CPU HLT instruction. The result is that
 2420: it takes host CPU cycles even when idle. You can install the utility
 2421: from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
 2422: problem.
 2423: 
 2424: @node QEMU System emulator for non PC targets
 2425: @chapter QEMU System emulator for non PC targets
 2426: 
 2427: QEMU is a generic emulator and it emulates many non PC
 2428: machines. Most of the options are similar to the PC emulator. The
 2429: differences are mentioned in the following sections.
 2430: 
 2431: @menu
 2432: * QEMU PowerPC System emulator::
 2433: * Sparc32 System emulator::
 2434: * Sparc64 System emulator::
 2435: * MIPS System emulator::
 2436: * ARM System emulator::
 2437: * ColdFire System emulator::
 2438: @end menu
 2439: 
 2440: @node QEMU PowerPC System emulator
 2441: @section QEMU PowerPC System emulator
 2442: 
 2443: Use the executable @file{qemu-system-ppc} to simulate a complete PREP
 2444: or PowerMac PowerPC system.
 2445: 
 2446: QEMU emulates the following PowerMac peripherals:
 2447: 
 2448: @itemize @minus
 2449: @item
 2450: UniNorth or Grackle PCI Bridge
 2451: @item
 2452: PCI VGA compatible card with VESA Bochs Extensions
 2453: @item
 2454: 2 PMAC IDE interfaces with hard disk and CD-ROM support
 2455: @item
 2456: NE2000 PCI adapters
 2457: @item
 2458: Non Volatile RAM
 2459: @item
 2460: VIA-CUDA with ADB keyboard and mouse.
 2461: @end itemize
 2462: 
 2463: QEMU emulates the following PREP peripherals:
 2464: 
 2465: @itemize @minus
 2466: @item
 2467: PCI Bridge
 2468: @item
 2469: PCI VGA compatible card with VESA Bochs Extensions
 2470: @item
 2471: 2 IDE interfaces with hard disk and CD-ROM support
 2472: @item
 2473: Floppy disk
 2474: @item
 2475: NE2000 network adapters
 2476: @item
 2477: Serial port
 2478: @item
 2479: PREP Non Volatile RAM
 2480: @item
 2481: PC compatible keyboard and mouse.
 2482: @end itemize
 2483: 
 2484: QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
 2485: @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
 2486: 
 2487: Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
 2488: for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
 2489: v2) portable firmware implementation. The goal is to implement a 100%
 2490: IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
 2491: 
 2492: @c man begin OPTIONS
 2493: 
 2494: The following options are specific to the PowerPC emulation:
 2495: 
 2496: @table @option
 2497: 
 2498: @item -g WxH[xDEPTH]
 2499: 
 2500: Set the initial VGA graphic mode. The default is 800x600x15.
 2501: 
 2502: @item -prom-env string
 2503: 
 2504: Set OpenBIOS variables in NVRAM, for example:
 2505: 
 2506: @example
 2507: qemu-system-ppc -prom-env 'auto-boot?=false' \
 2508:  -prom-env 'boot-device=hd:2,\yaboot' \
 2509:  -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
 2510: @end example
 2511: 
 2512: These variables are not used by Open Hack'Ware.
 2513: 
 2514: @end table
 2515: 
 2516: @c man end
 2517: 
 2518: 
 2519: More information is available at
 2520: @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
 2521: 
 2522: @node Sparc32 System emulator
 2523: @section Sparc32 System emulator
 2524: 
 2525: Use the executable @file{qemu-system-sparc} to simulate the following
 2526: Sun4m architecture machines:
 2527: @itemize @minus
 2528: @item
 2529: SPARCstation 4
 2530: @item
 2531: SPARCstation 5
 2532: @item
 2533: SPARCstation 10
 2534: @item
 2535: SPARCstation 20
 2536: @item
 2537: SPARCserver 600MP
 2538: @item
 2539: SPARCstation LX
 2540: @item
 2541: SPARCstation Voyager
 2542: @item
 2543: SPARCclassic
 2544: @item
 2545: SPARCbook
 2546: @end itemize
 2547: 
 2548: The emulation is somewhat complete. SMP up to 16 CPUs is supported,
 2549: but Linux limits the number of usable CPUs to 4.
 2550: 
 2551: It's also possible to simulate a SPARCstation 2 (sun4c architecture),
 2552: SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
 2553: emulators are not usable yet.
 2554: 
 2555: QEMU emulates the following sun4m/sun4c/sun4d peripherals:
 2556: 
 2557: @itemize @minus
 2558: @item
 2559: IOMMU or IO-UNITs
 2560: @item
 2561: TCX Frame buffer
 2562: @item
 2563: Lance (Am7990) Ethernet
 2564: @item
 2565: Non Volatile RAM M48T02/M48T08
 2566: @item
 2567: Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
 2568: and power/reset logic
 2569: @item
 2570: ESP SCSI controller with hard disk and CD-ROM support
 2571: @item
 2572: Floppy drive (not on SS-600MP)
 2573: @item
 2574: CS4231 sound device (only on SS-5, not working yet)
 2575: @end itemize
 2576: 
 2577: The number of peripherals is fixed in the architecture.  Maximum
 2578: memory size depends on the machine type, for SS-5 it is 256MB and for
 2579: others 2047MB.
 2580: 
 2581: Since version 0.8.2, QEMU uses OpenBIOS
 2582: @url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
 2583: firmware implementation. The goal is to implement a 100% IEEE
 2584: 1275-1994 (referred to as Open Firmware) compliant firmware.
 2585: 
 2586: A sample Linux 2.6 series kernel and ram disk image are available on
 2587: the QEMU web site. There are still issues with NetBSD and OpenBSD, but
 2588: some kernel versions work. Please note that currently Solaris kernels
 2589: don't work probably due to interface issues between OpenBIOS and
 2590: Solaris.
 2591: 
 2592: @c man begin OPTIONS
 2593: 
 2594: The following options are specific to the Sparc32 emulation:
 2595: 
 2596: @table @option
 2597: 
 2598: @item -g WxHx[xDEPTH]
 2599: 
 2600: Set the initial TCX graphic mode. The default is 1024x768x8, currently
 2601: the only other possible mode is 1024x768x24.
 2602: 
 2603: @item -prom-env string
 2604: 
 2605: Set OpenBIOS variables in NVRAM, for example:
 2606: 
 2607: @example
 2608: qemu-system-sparc -prom-env 'auto-boot?=false' \
 2609:  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
 2610: @end example
 2611: 
 2612: @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic|SPARCbook|SS-2|SS-1000|SS-2000]
 2613: 
 2614: Set the emulated machine type. Default is SS-5.
 2615: 
 2616: @end table
 2617: 
 2618: @c man end
 2619: 
 2620: @node Sparc64 System emulator
 2621: @section Sparc64 System emulator
 2622: 
 2623: Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
 2624: (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
 2625: Niagara (T1) machine. The emulator is not usable for anything yet, but
 2626: it can launch some kernels.
 2627: 
 2628: QEMU emulates the following peripherals:
 2629: 
 2630: @itemize @minus
 2631: @item
 2632: UltraSparc IIi APB PCI Bridge
 2633: @item
 2634: PCI VGA compatible card with VESA Bochs Extensions
 2635: @item
 2636: PS/2 mouse and keyboard
 2637: @item
 2638: Non Volatile RAM M48T59
 2639: @item
 2640: PC-compatible serial ports
 2641: @item
 2642: 2 PCI IDE interfaces with hard disk and CD-ROM support
 2643: @item
 2644: Floppy disk
 2645: @end itemize
 2646: 
 2647: @c man begin OPTIONS
 2648: 
 2649: The following options are specific to the Sparc64 emulation:
 2650: 
 2651: @table @option
 2652: 
 2653: @item -prom-env string
 2654: 
 2655: Set OpenBIOS variables in NVRAM, for example:
 2656: 
 2657: @example
 2658: qemu-system-sparc64 -prom-env 'auto-boot?=false'
 2659: @end example
 2660: 
 2661: @item -M [sun4u|sun4v|Niagara]
 2662: 
 2663: Set the emulated machine type. The default is sun4u.
 2664: 
 2665: @end table
 2666: 
 2667: @c man end
 2668: 
 2669: @node MIPS System emulator
 2670: @section MIPS System emulator
 2671: 
 2672: Four executables cover simulation of 32 and 64-bit MIPS systems in
 2673: both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
 2674: @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
 2675: Five different machine types are emulated:
 2676: 
 2677: @itemize @minus
 2678: @item
 2679: A generic ISA PC-like machine "mips"
 2680: @item
 2681: The MIPS Malta prototype board "malta"
 2682: @item
 2683: An ACER Pica "pica61". This machine needs the 64-bit emulator.
 2684: @item
 2685: MIPS emulator pseudo board "mipssim"
 2686: @item
 2687: A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
 2688: @end itemize
 2689: 
 2690: The generic emulation is supported by Debian 'Etch' and is able to
 2691: install Debian into a virtual disk image. The following devices are
 2692: emulated:
 2693: 
 2694: @itemize @minus
 2695: @item
 2696: A range of MIPS CPUs, default is the 24Kf
 2697: @item
 2698: PC style serial port
 2699: @item
 2700: PC style IDE disk
 2701: @item
 2702: NE2000 network card
 2703: @end itemize
 2704: 
 2705: The Malta emulation supports the following devices:
 2706: 
 2707: @itemize @minus
 2708: @item
 2709: Core board with MIPS 24Kf CPU and Galileo system controller
 2710: @item
 2711: PIIX4 PCI/USB/SMbus controller
 2712: @item
 2713: The Multi-I/O chip's serial device
 2714: @item
 2715: PCnet32 PCI network card
 2716: @item
 2717: Malta FPGA serial device
 2718: @item
 2719: Cirrus (default) or any other PCI VGA graphics card
 2720: @end itemize
 2721: 
 2722: The ACER Pica emulation supports:
 2723: 
 2724: @itemize @minus
 2725: @item
 2726: MIPS R4000 CPU
 2727: @item
 2728: PC-style IRQ and DMA controllers
 2729: @item
 2730: PC Keyboard
 2731: @item
 2732: IDE controller
 2733: @end itemize
 2734: 
 2735: The mipssim pseudo board emulation provides an environment similiar
 2736: to what the proprietary MIPS emulator uses for running Linux.
 2737: It supports:
 2738: 
 2739: @itemize @minus
 2740: @item
 2741: A range of MIPS CPUs, default is the 24Kf
 2742: @item
 2743: PC style serial port
 2744: @item
 2745: MIPSnet network emulation
 2746: @end itemize
 2747: 
 2748: The MIPS Magnum R4000 emulation supports:
 2749: 
 2750: @itemize @minus
 2751: @item
 2752: MIPS R4000 CPU
 2753: @item
 2754: PC-style IRQ controller
 2755: @item
 2756: PC Keyboard
 2757: @item
 2758: SCSI controller
 2759: @item
 2760: G364 framebuffer
 2761: @end itemize
 2762: 
 2763: 
 2764: @node ARM System emulator
 2765: @section ARM System emulator
 2766: 
 2767: Use the executable @file{qemu-system-arm} to simulate a ARM
 2768: machine. The ARM Integrator/CP board is emulated with the following
 2769: devices:
 2770: 
 2771: @itemize @minus
 2772: @item
 2773: ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
 2774: @item
 2775: Two PL011 UARTs
 2776: @item
 2777: SMC 91c111 Ethernet adapter
 2778: @item
 2779: PL110 LCD controller
 2780: @item
 2781: PL050 KMI with PS/2 keyboard and mouse.
 2782: @item
 2783: PL181 MultiMedia Card Interface with SD card.
 2784: @end itemize
 2785: 
 2786: The ARM Versatile baseboard is emulated with the following devices:
 2787: 
 2788: @itemize @minus
 2789: @item
 2790: ARM926E, ARM1136 or Cortex-A8 CPU
 2791: @item
 2792: PL190 Vectored Interrupt Controller
 2793: @item
 2794: Four PL011 UARTs
 2795: @item
 2796: SMC 91c111 Ethernet adapter
 2797: @item
 2798: PL110 LCD controller
 2799: @item
 2800: PL050 KMI with PS/2 keyboard and mouse.
 2801: @item
 2802: PCI host bridge.  Note the emulated PCI bridge only provides access to
 2803: PCI memory space.  It does not provide access to PCI IO space.
 2804: This means some devices (eg. ne2k_pci NIC) are not usable, and others
 2805: (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
 2806: mapped control registers.
 2807: @item
 2808: PCI OHCI USB controller.
 2809: @item
 2810: LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
 2811: @item
 2812: PL181 MultiMedia Card Interface with SD card.
 2813: @end itemize
 2814: 
 2815: The ARM RealView Emulation baseboard is emulated with the following devices:
 2816: 
 2817: @itemize @minus
 2818: @item
 2819: ARM926E, ARM1136, ARM11MPCORE(x4) or Cortex-A8 CPU
 2820: @item
 2821: ARM AMBA Generic/Distributed Interrupt Controller
 2822: @item
 2823: Four PL011 UARTs
 2824: @item
 2825: SMC 91c111 Ethernet adapter
 2826: @item
 2827: PL110 LCD controller
 2828: @item
 2829: PL050 KMI with PS/2 keyboard and mouse
 2830: @item
 2831: PCI host bridge
 2832: @item
 2833: PCI OHCI USB controller
 2834: @item
 2835: LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
 2836: @item
 2837: PL181 MultiMedia Card Interface with SD card.
 2838: @end itemize
 2839: 
 2840: The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
 2841: and "Terrier") emulation includes the following peripherals:
 2842: 
 2843: @itemize @minus
 2844: @item
 2845: Intel PXA270 System-on-chip (ARM V5TE core)
 2846: @item
 2847: NAND Flash memory
 2848: @item
 2849: IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
 2850: @item
 2851: On-chip OHCI USB controller
 2852: @item
 2853: On-chip LCD controller
 2854: @item
 2855: On-chip Real Time Clock
 2856: @item
 2857: TI ADS7846 touchscreen controller on SSP bus
 2858: @item
 2859: Maxim MAX1111 analog-digital converter on I@math{^2}C bus
 2860: @item
 2861: GPIO-connected keyboard controller and LEDs
 2862: @item
 2863: Secure Digital card connected to PXA MMC/SD host
 2864: @item
 2865: Three on-chip UARTs
 2866: @item
 2867: WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
 2868: @end itemize
 2869: 
 2870: The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
 2871: following elements:
 2872: 
 2873: @itemize @minus
 2874: @item
 2875: Texas Instruments OMAP310 System-on-chip (ARM 925T core)
 2876: @item
 2877: ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
 2878: @item
 2879: On-chip LCD controller
 2880: @item
 2881: On-chip Real Time Clock
 2882: @item
 2883: TI TSC2102i touchscreen controller / analog-digital converter / Audio
 2884: CODEC, connected through MicroWire and I@math{^2}S busses
 2885: @item
 2886: GPIO-connected matrix keypad
 2887: @item
 2888: Secure Digital card connected to OMAP MMC/SD host
 2889: @item
 2890: Three on-chip UARTs
 2891: @end itemize
 2892: 
 2893: Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
 2894: emulation supports the following elements:
 2895: 
 2896: @itemize @minus
 2897: @item
 2898: Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
 2899: @item
 2900: RAM and non-volatile OneNAND Flash memories
 2901: @item
 2902: Display connected to EPSON remote framebuffer chip and OMAP on-chip
 2903: display controller and a LS041y3 MIPI DBI-C controller
 2904: @item
 2905: TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
 2906: driven through SPI bus
 2907: @item
 2908: National Semiconductor LM8323-controlled qwerty keyboard driven
 2909: through I@math{^2}C bus
 2910: @item
 2911: Secure Digital card connected to OMAP MMC/SD host
 2912: @item
 2913: Three OMAP on-chip UARTs and on-chip STI debugging console
 2914: @item
 2915: A Bluetooth(R) transciever and HCI connected to an UART
 2916: @item
 2917: Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
 2918: TUSB6010 chip - only USB host mode is supported
 2919: @item
 2920: TI TMP105 temperature sensor driven through I@math{^2}C bus
 2921: @item
 2922: TI TWL92230C power management companion with an RTC on I@math{^2}C bus
 2923: @item
 2924: Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
 2925: through CBUS
 2926: @end itemize
 2927: 
 2928: The Luminary Micro Stellaris LM3S811EVB emulation includes the following
 2929: devices:
 2930: 
 2931: @itemize @minus
 2932: @item
 2933: Cortex-M3 CPU core.
 2934: @item
 2935: 64k Flash and 8k SRAM.
 2936: @item
 2937: Timers, UARTs, ADC and I@math{^2}C interface.
 2938: @item
 2939: OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
 2940: @end itemize
 2941: 
 2942: The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
 2943: devices:
 2944: 
 2945: @itemize @minus
 2946: @item
 2947: Cortex-M3 CPU core.
 2948: @item
 2949: 256k Flash and 64k SRAM.
 2950: @item
 2951: Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
 2952: @item
 2953: OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
 2954: @end itemize
 2955: 
 2956: The Freecom MusicPal internet radio emulation includes the following
 2957: elements:
 2958: 
 2959: @itemize @minus
 2960: @item
 2961: Marvell MV88W8618 ARM core.
 2962: @item
 2963: 32 MB RAM, 256 KB SRAM, 8 MB flash.
 2964: @item
 2965: Up to 2 16550 UARTs
 2966: @item
 2967: MV88W8xx8 Ethernet controller
 2968: @item
 2969: MV88W8618 audio controller, WM8750 CODEC and mixer
 2970: @item
 2971: 12864 display with brightness control
 2972: @item
 2973: 2 buttons, 2 navigation wheels with button function
 2974: @end itemize
 2975: 
 2976: The Siemens SX1 models v1 and v2 (default) basic emulation.
 2977: The emulaton includes the following elements:
 2978: 
 2979: @itemize @minus
 2980: @item
 2981: Texas Instruments OMAP310 System-on-chip (ARM 925T core)
 2982: @item
 2983: ROM and RAM memories (ROM firmware image can be loaded with -pflash)
 2984: V1
 2985: 1 Flash of 16MB and 1 Flash of 8MB
 2986: V2
 2987: 1 Flash of 32MB
 2988: @item
 2989: On-chip LCD controller
 2990: @item
 2991: On-chip Real Time Clock
 2992: @item
 2993: Secure Digital card connected to OMAP MMC/SD host
 2994: @item
 2995: Three on-chip UARTs
 2996: @end itemize
 2997: 
 2998: A Linux 2.6 test image is available on the QEMU web site. More
 2999: information is available in the QEMU mailing-list archive.
 3000: 
 3001: @c man begin OPTIONS
 3002: 
 3003: The following options are specific to the ARM emulation:
 3004: 
 3005: @table @option
 3006: 
 3007: @item -semihosting
 3008: Enable semihosting syscall emulation.
 3009: 
 3010: On ARM this implements the "Angel" interface.
 3011: 
 3012: Note that this allows guest direct access to the host filesystem,
 3013: so should only be used with trusted guest OS.
 3014: 
 3015: @end table
 3016: 
 3017: @node ColdFire System emulator
 3018: @section ColdFire System emulator
 3019: 
 3020: Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
 3021: The emulator is able to boot a uClinux kernel.
 3022: 
 3023: The M5208EVB emulation includes the following devices:
 3024: 
 3025: @itemize @minus
 3026: @item
 3027: MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
 3028: @item
 3029: Three Two on-chip UARTs.
 3030: @item
 3031: Fast Ethernet Controller (FEC)
 3032: @end itemize
 3033: 
 3034: The AN5206 emulation includes the following devices:
 3035: 
 3036: @itemize @minus
 3037: @item
 3038: MCF5206 ColdFire V2 Microprocessor.
 3039: @item
 3040: Two on-chip UARTs.
 3041: @end itemize
 3042: 
 3043: @c man begin OPTIONS
 3044: 
 3045: The following options are specific to the ARM emulation:
 3046: 
 3047: @table @option
 3048: 
 3049: @item -semihosting
 3050: Enable semihosting syscall emulation.
 3051: 
 3052: On M68K this implements the "ColdFire GDB" interface used by libgloss.
 3053: 
 3054: Note that this allows guest direct access to the host filesystem,
 3055: so should only be used with trusted guest OS.
 3056: 
 3057: @end table
 3058: 
 3059: @node QEMU User space emulator
 3060: @chapter QEMU User space emulator
 3061: 
 3062: @menu
 3063: * Supported Operating Systems ::
 3064: * Linux User space emulator::
 3065: * Mac OS X/Darwin User space emulator ::
 3066: * BSD User space emulator ::
 3067: @end menu
 3068: 
 3069: @node Supported Operating Systems
 3070: @section Supported Operating Systems
 3071: 
 3072: The following OS are supported in user space emulation:
 3073: 
 3074: @itemize @minus
 3075: @item
 3076: Linux (referred as qemu-linux-user)
 3077: @item
 3078: Mac OS X/Darwin (referred as qemu-darwin-user)
 3079: @item
 3080: BSD (referred as qemu-bsd-user)
 3081: @end itemize
 3082: 
 3083: @node Linux User space emulator
 3084: @section Linux User space emulator
 3085: 
 3086: @menu
 3087: * Quick Start::
 3088: * Wine launch::
 3089: * Command line options::
 3090: * Other binaries::
 3091: @end menu
 3092: 
 3093: @node Quick Start
 3094: @subsection Quick Start
 3095: 
 3096: In order to launch a Linux process, QEMU needs the process executable
 3097: itself and all the target (x86) dynamic libraries used by it.
 3098: 
 3099: @itemize
 3100: 
 3101: @item On x86, you can just try to launch any process by using the native
 3102: libraries:
 3103: 
 3104: @example
 3105: qemu-i386 -L / /bin/ls
 3106: @end example
 3107: 
 3108: @code{-L /} tells that the x86 dynamic linker must be searched with a
 3109: @file{/} prefix.
 3110: 
 3111: @item Since QEMU is also a linux process, you can launch qemu with
 3112: qemu (NOTE: you can only do that if you compiled QEMU from the sources):
 3113: 
 3114: @example
 3115: qemu-i386 -L / qemu-i386 -L / /bin/ls
 3116: @end example
 3117: 
 3118: @item On non x86 CPUs, you need first to download at least an x86 glibc
 3119: (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
 3120: @code{LD_LIBRARY_PATH} is not set:
 3121: 
 3122: @example
 3123: unset LD_LIBRARY_PATH
 3124: @end example
 3125: 
 3126: Then you can launch the precompiled @file{ls} x86 executable:
 3127: 
 3128: @example
 3129: qemu-i386 tests/i386/ls
 3130: @end example
 3131: You can look at @file{qemu-binfmt-conf.sh} so that
 3132: QEMU is automatically launched by the Linux kernel when you try to
 3133: launch x86 executables. It requires the @code{binfmt_misc} module in the
 3134: Linux kernel.
 3135: 
 3136: @item The x86 version of QEMU is also included. You can try weird things such as:
 3137: @example
 3138: qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
 3139:           /usr/local/qemu-i386/bin/ls-i386
 3140: @end example
 3141: 
 3142: @end itemize
 3143: 
 3144: @node Wine launch
 3145: @subsection Wine launch
 3146: 
 3147: @itemize
 3148: 
 3149: @item Ensure that you have a working QEMU with the x86 glibc
 3150: distribution (see previous section). In order to verify it, you must be
 3151: able to do:
 3152: 
 3153: @example
 3154: qemu-i386 /usr/local/qemu-i386/bin/ls-i386
 3155: @end example
 3156: 
 3157: @item Download the binary x86 Wine install
 3158: (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
 3159: 
 3160: @item Configure Wine on your account. Look at the provided script
 3161: @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
 3162: @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
 3163: 
 3164: @item Then you can try the example @file{putty.exe}:
 3165: 
 3166: @example
 3167: qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
 3168:           /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
 3169: @end example
 3170: 
 3171: @end itemize
 3172: 
 3173: @node Command line options
 3174: @subsection Command line options
 3175: 
 3176: @example
 3177: usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] program [arguments...]
 3178: @end example
 3179: 
 3180: @table @option
 3181: @item -h
 3182: Print the help
 3183: @item -L path
 3184: Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
 3185: @item -s size
 3186: Set the x86 stack size in bytes (default=524288)
 3187: @item -cpu model
 3188: Select CPU model (-cpu ? for list and additional feature selection)
 3189: @end table
 3190: 
 3191: Debug options:
 3192: 
 3193: @table @option
 3194: @item -d
 3195: Activate log (logfile=/tmp/qemu.log)
 3196: @item -p pagesize
 3197: Act as if the host page size was 'pagesize' bytes
 3198: @item -g port
 3199: Wait gdb connection to port
 3200: @end table
 3201: 
 3202: Environment variables:
 3203: 
 3204: @table @env
 3205: @item QEMU_STRACE
 3206: Print system calls and arguments similar to the 'strace' program
 3207: (NOTE: the actual 'strace' program will not work because the user
 3208: space emulator hasn't implemented ptrace).  At the moment this is
 3209: incomplete.  All system calls that don't have a specific argument
 3210: format are printed with information for six arguments.  Many
 3211: flag-style arguments don't have decoders and will show up as numbers.
 3212: @end table
 3213: 
 3214: @node Other binaries
 3215: @subsection Other binaries
 3216: 
 3217: @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
 3218: binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
 3219: configurations), and arm-uclinux bFLT format binaries.
 3220: 
 3221: @command{qemu-m68k} is capable of running semihosted binaries using the BDM
 3222: (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
 3223: coldfire uClinux bFLT format binaries.
 3224: 
 3225: The binary format is detected automatically.
 3226: 
 3227: @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
 3228: 
 3229: @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
 3230: (Sparc64 CPU, 32 bit ABI).
 3231: 
 3232: @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
 3233: SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
 3234: 
 3235: @node Mac OS X/Darwin User space emulator
 3236: @section Mac OS X/Darwin User space emulator
 3237: 
 3238: @menu
 3239: * Mac OS X/Darwin Status::
 3240: * Mac OS X/Darwin Quick Start::
 3241: * Mac OS X/Darwin Command line options::
 3242: @end menu
 3243: 
 3244: @node Mac OS X/Darwin Status
 3245: @subsection Mac OS X/Darwin Status
 3246: 
 3247: @itemize @minus
 3248: @item
 3249: target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
 3250: @item
 3251: target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
 3252: @item
 3253: target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
 3254: @item
 3255: target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
 3256: @end itemize
 3257: 
 3258: [1] If you're host commpage can be executed by qemu.
 3259: 
 3260: @node Mac OS X/Darwin Quick Start
 3261: @subsection Quick Start
 3262: 
 3263: In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
 3264: itself and all the target dynamic libraries used by it. If you don't have the FAT
 3265: libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
 3266: CD or compile them by hand.
 3267: 
 3268: @itemize
 3269: 
 3270: @item On x86, you can just try to launch any process by using the native
 3271: libraries:
 3272: 
 3273: @example
 3274: qemu-i386 /bin/ls
 3275: @end example
 3276: 
 3277: or to run the ppc version of the executable:
 3278: 
 3279: @example
 3280: qemu-ppc /bin/ls
 3281: @end example
 3282: 
 3283: @item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
 3284: are installed:
 3285: 
 3286: @example
 3287: qemu-i386 -L /opt/x86_root/ /bin/ls
 3288: @end example
 3289: 
 3290: @code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
 3291: @file{/opt/x86_root/usr/bin/dyld}.
 3292: 
 3293: @end itemize
 3294: 
 3295: @node Mac OS X/Darwin Command line options
 3296: @subsection Command line options
 3297: 
 3298: @example
 3299: usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
 3300: @end example
 3301: 
 3302: @table @option
 3303: @item -h
 3304: Print the help
 3305: @item -L path
 3306: Set the library root path (default=/)
 3307: @item -s size
 3308: Set the stack size in bytes (default=524288)
 3309: @end table
 3310: 
 3311: Debug options:
 3312: 
 3313: @table @option
 3314: @item -d
 3315: Activate log (logfile=/tmp/qemu.log)
 3316: @item -p pagesize
 3317: Act as if the host page size was 'pagesize' bytes
 3318: @end table
 3319: 
 3320: @node BSD User space emulator
 3321: @section BSD User space emulator
 3322: 
 3323: @menu
 3324: * BSD Status::
 3325: * BSD Quick Start::
 3326: * BSD Command line options::
 3327: @end menu
 3328: 
 3329: @node BSD Status
 3330: @subsection BSD Status
 3331: 
 3332: @itemize @minus
 3333: @item
 3334: target Sparc64 on Sparc64: Some trivial programs work.
 3335: @end itemize
 3336: 
 3337: @node BSD Quick Start
 3338: @subsection Quick Start
 3339: 
 3340: In order to launch a BSD process, QEMU needs the process executable
 3341: itself and all the target dynamic libraries used by it.
 3342: 
 3343: @itemize
 3344: 
 3345: @item On Sparc64, you can just try to launch any process by using the native
 3346: libraries:
 3347: 
 3348: @example
 3349: qemu-sparc64 /bin/ls
 3350: @end example
 3351: 
 3352: @end itemize
 3353: 
 3354: @node BSD Command line options
 3355: @subsection Command line options
 3356: 
 3357: @example
 3358: usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
 3359: @end example
 3360: 
 3361: @table @option
 3362: @item -h
 3363: Print the help
 3364: @item -L path
 3365: Set the library root path (default=/)
 3366: @item -s size
 3367: Set the stack size in bytes (default=524288)
 3368: @item -bsd type
 3369: Set the type of the emulated BSD Operating system. Valid values are
 3370: FreeBSD, NetBSD and OpenBSD (default).
 3371: @end table
 3372: 
 3373: Debug options:
 3374: 
 3375: @table @option
 3376: @item -d
 3377: Activate log (logfile=/tmp/qemu.log)
 3378: @item -p pagesize
 3379: Act as if the host page size was 'pagesize' bytes
 3380: @end table
 3381: 
 3382: @node compilation
 3383: @chapter Compilation from the sources
 3384: 
 3385: @menu
 3386: * Linux/Unix::
 3387: * Windows::
 3388: * Cross compilation for Windows with Linux::
 3389: * Mac OS X::
 3390: @end menu
 3391: 
 3392: @node Linux/Unix
 3393: @section Linux/Unix
 3394: 
 3395: @subsection Compilation
 3396: 
 3397: First you must decompress the sources:
 3398: @example
 3399: cd /tmp
 3400: tar zxvf qemu-x.y.z.tar.gz
 3401: cd qemu-x.y.z
 3402: @end example
 3403: 
 3404: Then you configure QEMU and build it (usually no options are needed):
 3405: @example
 3406: ./configure
 3407: make
 3408: @end example
 3409: 
 3410: Then type as root user:
 3411: @example
 3412: make install
 3413: @end example
 3414: to install QEMU in @file{/usr/local}.
 3415: 
 3416: @subsection GCC version
 3417: 
 3418: In order to compile QEMU successfully, it is very important that you
 3419: have the right tools. The most important one is gcc. On most hosts and
 3420: in particular on x86 ones, @emph{gcc 4.x is not supported}. If your
 3421: Linux distribution includes a gcc 4.x compiler, you can usually
 3422: install an older version (it is invoked by @code{gcc32} or
 3423: @code{gcc34}). The QEMU configure script automatically probes for
 3424: these older versions so that usually you don't have to do anything.
 3425: 
 3426: @node Windows
 3427: @section Windows
 3428: 
 3429: @itemize
 3430: @item Install the current versions of MSYS and MinGW from
 3431: @url{http://www.mingw.org/}. You can find detailed installation
 3432: instructions in the download section and the FAQ.
 3433: 
 3434: @item Download
 3435: the MinGW development library of SDL 1.2.x
 3436: (@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
 3437: @url{http://www.libsdl.org}. Unpack it in a temporary place, and
 3438: unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
 3439: directory. Edit the @file{sdl-config} script so that it gives the
 3440: correct SDL directory when invoked.
 3441: 
 3442: @item Extract the current version of QEMU.
 3443: 
 3444: @item Start the MSYS shell (file @file{msys.bat}).
 3445: 
 3446: @item Change to the QEMU directory. Launch @file{./configure} and
 3447: @file{make}.  If you have problems using SDL, verify that
 3448: @file{sdl-config} can be launched from the MSYS command line.
 3449: 
 3450: @item You can install QEMU in @file{Program Files/Qemu} by typing
 3451: @file{make install}. Don't forget to copy @file{SDL.dll} in
 3452: @file{Program Files/Qemu}.
 3453: 
 3454: @end itemize
 3455: 
 3456: @node Cross compilation for Windows with Linux
 3457: @section Cross compilation for Windows with Linux
 3458: 
 3459: @itemize
 3460: @item
 3461: Install the MinGW cross compilation tools available at
 3462: @url{http://www.mingw.org/}.
 3463: 
 3464: @item
 3465: Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
 3466: unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
 3467: variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
 3468: the QEMU configuration script.
 3469: 
 3470: @item
 3471: Configure QEMU for Windows cross compilation:
 3472: @example
 3473: ./configure --enable-mingw32
 3474: @end example
 3475: If necessary, you can change the cross-prefix according to the prefix
 3476: chosen for the MinGW tools with --cross-prefix. You can also use
 3477: --prefix to set the Win32 install path.
 3478: 
 3479: @item You can install QEMU in the installation directory by typing
 3480: @file{make install}. Don't forget to copy @file{SDL.dll} in the
 3481: installation directory.
 3482: 
 3483: @end itemize
 3484: 
 3485: Note: Currently, Wine does not seem able to launch
 3486: QEMU for Win32.
 3487: 
 3488: @node Mac OS X
 3489: @section Mac OS X
 3490: 
 3491: The Mac OS X patches are not fully merged in QEMU, so you should look
 3492: at the QEMU mailing list archive to have all the necessary
 3493: information.
 3494: 
 3495: @node Index
 3496: @chapter Index
 3497: @printindex cp
 3498: 
 3499: @bye

unix.superglobalmegacorp.com