File:  [Qemu by Fabrice Bellard] / qemu / qemu-doc.texi
Revision 1.1.1.6 (vendor branch): download - view: text, annotated - select for diffs
Tue Apr 24 16:47:00 2018 UTC (3 years, 7 months ago) by root
Branches: qemu, MAIN
CVS tags: qemu0091, HEAD
qemu 0.9.1

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

unix.superglobalmegacorp.com