Annotation of qemu/qemu-doc.texi, revision 1.1.1.7

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

unix.superglobalmegacorp.com