1 \input texinfo @c -*- texinfo -*-

     2 @c %**start of header

     3 @setfilename qemu-doc.info

     4 @settitle QEMU Emulator User Documentation

     5 @exampleindent 0

     6 @paragraphindent 0

     7 @c %**end of header

     8 

     9 @iftex

    10 @titlepage

    11 @sp 7

    12 @center @titlefont{QEMU Emulator}

    13 @sp 1

    14 @center @titlefont{User Documentation}

    15 @sp 3

    16 @end titlepage

    17 @end iftex

    18 

    19 @ifnottex

    20 @node Top

    21 @top

    22 

    23 @menu

    24 * Introduction::

    25 * Installation::

    26 * QEMU PC System emulator::

    27 * QEMU System emulator for non PC targets::

    28 * QEMU User space emulator::

    29 * compilation:: Compilation from the sources

    30 * Index::

    31 @end menu

    32 @end ifnottex

    33 

    34 @contents

    35 

    36 @node Introduction

    37 @chapter Introduction

    38 

    39 @menu

    40 * intro_features:: Features

    41 @end menu

    42 

    43 @node intro_features

    44 @section Features

    45 

    46 QEMU is a FAST! processor emulator using dynamic translation to

    47 achieve good emulation speed.

    48 

    49 QEMU has two operating modes:

    50 

    51 @itemize @minus

    52 

    53 @item

    54 Full system emulation. In this mode, QEMU emulates a full system (for

    55 example a PC), including one or several processors and various

    56 peripherals. It can be used to launch different Operating Systems

    57 without rebooting the PC or to debug system code.

    58 

    59 @item

    60 User mode emulation. In this mode, QEMU can launch

    61 processes compiled for one CPU on another CPU. It can be used to

    62 launch the Wine Windows API emulator (@url{http://www.winehq.org}) or

    63 to ease cross-compilation and cross-debugging.

    64 

    65 @end itemize

    66 

    67 QEMU can run without an host kernel driver and yet gives acceptable

    68 performance.

    69 

    70 For system emulation, the following hardware targets are supported:

    71 @itemize

    72 @item PC (x86 or x86_64 processor)

    73 @item ISA PC (old style PC without PCI bus)

    74 @item PREP (PowerPC processor)

    75 @item G3 BW PowerMac (PowerPC processor)

    76 @item Mac99 PowerMac (PowerPC processor, in progress)

    77 @item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)

    78 @item Sun4u/Sun4v (64-bit Sparc processor, in progress)

    79 @item Malta board (32-bit and 64-bit MIPS processors)

    80 @item MIPS Magnum (64-bit MIPS processor)

    81 @item ARM Integrator/CP (ARM)

    82 @item ARM Versatile baseboard (ARM)

    83 @item ARM RealView Emulation baseboard (ARM)

    84 @item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)

    85 @item Luminary Micro LM3S811EVB (ARM Cortex-M3)

    86 @item Luminary Micro LM3S6965EVB (ARM Cortex-M3)

    87 @item Freescale MCF5208EVB (ColdFire V2).

    88 @item Arnewsh MCF5206 evaluation board (ColdFire V2).

    89 @item Palm Tungsten|E PDA (OMAP310 processor)

    90 @item N800 and N810 tablets (OMAP2420 processor)

    91 @item MusicPal (MV88W8618 ARM processor)

    92 @item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).

    93 @item Siemens SX1 smartphone (OMAP310 processor)

    94 @end itemize

    95 

    96 For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.

    97 

    98 @node Installation

    99 @chapter Installation

   100 

   101 If you want to compile QEMU yourself, see @ref{compilation}.

   102 

   103 @menu

   104 * install_linux::   Linux

   105 * install_windows:: Windows

   106 * install_mac::     Macintosh

   107 @end menu

   108 

   109 @node install_linux

   110 @section Linux

   111 

   112 If a precompiled package is available for your distribution - you just

   113 have to install it. Otherwise, see @ref{compilation}.

   114 

   115 @node install_windows

   116 @section Windows

   117 

   118 Download the experimental binary installer at

   119 @url{http://www.free.oszoo.org/@/download.html}.

   120 

   121 @node install_mac

   122 @section Mac OS X

   123 

   124 Download the experimental binary installer at

   125 @url{http://www.free.oszoo.org/@/download.html}.

   126 

   127 @node QEMU PC System emulator

   128 @chapter QEMU PC System emulator

   129 

   130 @menu

   131 * pcsys_introduction:: Introduction

   132 * pcsys_quickstart::   Quick Start

   133 * sec_invocation::     Invocation

   134 * pcsys_keys::         Keys

   135 * pcsys_monitor::      QEMU Monitor

   136 * disk_images::        Disk Images

   137 * pcsys_network::      Network emulation

   138 * direct_linux_boot::  Direct Linux Boot

   139 * pcsys_usb::          USB emulation

   140 * vnc_security::       VNC security

   141 * gdb_usage::          GDB usage

   142 * pcsys_os_specific::  Target OS specific information

   143 @end menu

   144 

   145 @node pcsys_introduction

   146 @section Introduction

   147 

   148 @c man begin DESCRIPTION

   149 

   150 The QEMU PC System emulator simulates the

   151 following peripherals:

   152 

   153 @itemize @minus

   154 @item

   155 i440FX host PCI bridge and PIIX3 PCI to ISA bridge

   156 @item

   157 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA

   158 extensions (hardware level, including all non standard modes).

   159 @item

   160 PS/2 mouse and keyboard

   161 @item

   162 2 PCI IDE interfaces with hard disk and CD-ROM support

   163 @item

   164 Floppy disk

   165 @item

   166 PCI/ISA PCI network adapters

   167 @item

   168 Serial ports

   169 @item

   170 Creative SoundBlaster 16 sound card

   171 @item

   172 ENSONIQ AudioPCI ES1370 sound card

   173 @item

   174 Intel 82801AA AC97 Audio compatible sound card

   175 @item

   176 Adlib(OPL2) - Yamaha YM3812 compatible chip

   177 @item

   178 Gravis Ultrasound GF1 sound card

   179 @item

   180 CS4231A compatible sound card

   181 @item

   182 PCI UHCI USB controller and a virtual USB hub.

   183 @end itemize

   184 

   185 SMP is supported with up to 255 CPUs.

   186 

   187 Note that adlib, ac97, gus and cs4231a are only available when QEMU

   188 was configured with --audio-card-list option containing the name(s) of

   189 required card(s).

   190 

   191 QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL

   192 VGA BIOS.

   193 

   194 QEMU uses YM3812 emulation by Tatsuyuki Satoh.

   195 

   196 QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})

   197 by Tibor "TS" Schütz.

   198 

   199 CS4231A is the chip used in Windows Sound System and GUSMAX products

   200 

   201 @c man end

   202 

   203 @node pcsys_quickstart

   204 @section Quick Start

   205 

   206 Download and uncompress the linux image (@file{linux.img}) and type:

   207 

   208 @example

   209 qemu linux.img

   210 @end example

   211 

   212 Linux should boot and give you a prompt.

   213 

   214 @node sec_invocation

   215 @section Invocation

   216 

   217 @example

   218 @c man begin SYNOPSIS

   219 usage: qemu [options] [@var{disk_image}]

   220 @c man end

   221 @end example

   222 

   223 @c man begin OPTIONS

   224 @var{disk_image} is a raw hard disk image for IDE hard disk 0.

   225 

   226 General options:

   227 @table @option

   228 @item -M @var{machine}

   229 Select the emulated @var{machine} (@code{-M ?} for list)

   230 

   231 @item -fda @var{file}

   232 @item -fdb @var{file}

   233 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can

   234 use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).

   235 

   236 @item -hda @var{file}

   237 @item -hdb @var{file}

   238 @item -hdc @var{file}

   239 @item -hdd @var{file}

   240 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).

   241 

   242 @item -cdrom @var{file}

   243 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and

   244 @option{-cdrom} at the same time). You can use the host CD-ROM by

   245 using @file{/dev/cdrom} as filename (@pxref{host_drives}).

   246 

   247 @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]

   248 

   249 Define a new drive. Valid options are:

   250 

   251 @table @code

   252 @item file=@var{file}

   253 This option defines which disk image (@pxref{disk_images}) to use with

   254 this drive. If the filename contains comma, you must double it

   255 (for instance, "file=my,,file" to use file "my,file").

   256 @item if=@var{interface}

   257 This option defines on which type on interface the drive is connected.

   258 Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.

   259 @item bus=@var{bus},unit=@var{unit}

   260 These options define where is connected the drive by defining the bus number and

   261 the unit id.

   262 @item index=@var{index}

   263 This option defines where is connected the drive by using an index in the list

   264 of available connectors of a given interface type.

   265 @item media=@var{media}

   266 This option defines the type of the media: disk or cdrom.

   267 @item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]

   268 These options have the same definition as they have in @option{-hdachs}.

   269 @item snapshot=@var{snapshot}

   270 @var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).

   271 @item cache=@var{cache}

   272 @var{cache} is "none", "writeback", or "writethrough" and controls how the host cache is used to access block data.

   273 @item format=@var{format}

   274 Specify which disk @var{format} will be used rather than detecting

   275 the format.  Can be used to specifiy format=raw to avoid interpreting

   276 an untrusted format header.

   277 @end table

   278 

   279 By default, writethrough caching is used for all block device.  This means that

   280 the host page cache will be used to read and write data but write notification

   281 will be sent to the guest only when the data has been reported as written by

   282 the storage subsystem.

   283 

   284 Writeback caching will report data writes as completed as soon as the data is

   285 present in the host page cache.  This is safe as long as you trust your host.

   286 If your host crashes or loses power, then the guest may experience data

   287 corruption.  When using the @option{-snapshot} option, writeback caching is

   288 used by default.

   289 

   290 The host page can be avoided entirely with @option{cache=none}.  This will

   291 attempt to do disk IO directly to the guests memory.  QEMU may still perform

   292 an internal copy of the data.

   293 

   294 Some block drivers perform badly with @option{cache=writethrough}, most notably,

   295 qcow2.  If performance is more important than correctness,

   296 @option{cache=writeback} should be used with qcow2.  By default, if no explicit

   297 caching is specified for a qcow2 disk image, @option{cache=writeback} will be

   298 used.  For all other disk types, @option{cache=writethrough} is the default.

   299 

   300 Instead of @option{-cdrom} you can use:

   301 @example

   302 qemu -drive file=file,index=2,media=cdrom

   303 @end example

   304 

   305 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can

   306 use:

   307 @example

   308 qemu -drive file=file,index=0,media=disk

   309 qemu -drive file=file,index=1,media=disk

   310 qemu -drive file=file,index=2,media=disk

   311 qemu -drive file=file,index=3,media=disk

   312 @end example

   313 

   314 You can connect a CDROM to the slave of ide0:

   315 @example

   316 qemu -drive file=file,if=ide,index=1,media=cdrom

   317 @end example

   318 

   319 If you don't specify the "file=" argument, you define an empty drive:

   320 @example

   321 qemu -drive if=ide,index=1,media=cdrom

   322 @end example

   323 

   324 You can connect a SCSI disk with unit ID 6 on the bus #0:

   325 @example

   326 qemu -drive file=file,if=scsi,bus=0,unit=6

   327 @end example

   328 

   329 Instead of @option{-fda}, @option{-fdb}, you can use:

   330 @example

   331 qemu -drive file=file,index=0,if=floppy

   332 qemu -drive file=file,index=1,if=floppy

   333 @end example

   334 

   335 By default, @var{interface} is "ide" and @var{index} is automatically

   336 incremented:

   337 @example

   338 qemu -drive file=a -drive file=b"

   339 @end example

   340 is interpreted like:

   341 @example

   342 qemu -hda a -hdb b

   343 @end example

   344 

   345 @item -boot [a|c|d|n]

   346 Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot

   347 is the default.

   348 

   349 @item -snapshot

   350 Write to temporary files instead of disk image files. In this case,

   351 the raw disk image you use is not written back. You can however force

   352 the write back by pressing @key{C-a s} (@pxref{disk_images}).

   353 

   354 @item -no-fd-bootchk

   355 Disable boot signature checking for floppy disks in Bochs BIOS. It may

   356 be needed to boot from old floppy disks.

   357 

   358 @item -m @var{megs}

   359 Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,

   360 a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or

   361 gigabytes respectively.

   362 

   363 @item -cpu @var{model}

   364 Select CPU model (-cpu ? for list and additional feature selection)

   365 

   366 @item -smp @var{n}

   367 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255

   368 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs

   369 to 4.

   370 

   371 @item -audio-help

   372 

   373 Will show the audio subsystem help: list of drivers, tunable

   374 parameters.

   375 

   376 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all

   377 

   378 Enable audio and selected sound hardware. Use ? to print all

   379 available sound hardware.

   380 

   381 @example

   382 qemu -soundhw sb16,adlib disk.img

   383 qemu -soundhw es1370 disk.img

   384 qemu -soundhw ac97 disk.img

   385 qemu -soundhw all disk.img

   386 qemu -soundhw ?

   387 @end example

   388 

   389 Note that Linux's i810_audio OSS kernel (for AC97) module might

   390 require manually specifying clocking.

   391 

   392 @example

   393 modprobe i810_audio clocking=48000

   394 @end example

   395 

   396 @item -localtime

   397 Set the real time clock to local time (the default is to UTC

   398 time). This option is needed to have correct date in MS-DOS or

   399 Windows.

   400 

   401 @item -startdate @var{date}

   402 Set the initial date of the real time clock. Valid formats for

   403 @var{date} are: @code{now} or @code{2006-06-17T16:01:21} or

   404 @code{2006-06-17}. The default value is @code{now}.

   405 

   406 @item -pidfile @var{file}

   407 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU

   408 from a script.

   409 

   410 @item -daemonize

   411 Daemonize the QEMU process after initialization.  QEMU will not detach from

   412 standard IO until it is ready to receive connections on any of its devices.

   413 This option is a useful way for external programs to launch QEMU without having

   414 to cope with initialization race conditions.

   415 

   416 @item -win2k-hack

   417 Use it when installing Windows 2000 to avoid a disk full bug. After

   418 Windows 2000 is installed, you no longer need this option (this option

   419 slows down the IDE transfers).

   420 

   421 @item -option-rom @var{file}

   422 Load the contents of @var{file} as an option ROM.

   423 This option is useful to load things like EtherBoot.

   424 

   425 @item -name @var{name}

   426 Sets the @var{name} of the guest.

   427 This name will be displayed in the SDL window caption.

   428 The @var{name} will also be used for the VNC server.

   429 

   430 @end table

   431 

   432 Display options:

   433 @table @option

   434 

   435 @item -nographic

   436 

   437 Normally, QEMU uses SDL to display the VGA output. With this option,

   438 you can totally disable graphical output so that QEMU is a simple

   439 command line application. The emulated serial port is redirected on

   440 the console. Therefore, you can still use QEMU to debug a Linux kernel

   441 with a serial console.

   442 

   443 @item -curses

   444 

   445 Normally, QEMU uses SDL to display the VGA output.  With this option,

   446 QEMU can display the VGA output when in text mode using a 

   447 curses/ncurses interface.  Nothing is displayed in graphical mode.

   448 

   449 @item -no-frame

   450 

   451 Do not use decorations for SDL windows and start them using the whole

   452 available screen space. This makes the using QEMU in a dedicated desktop

   453 workspace more convenient.

   454 

   455 @item -no-quit

   456 

   457 Disable SDL window close capability.

   458 

   459 @item -full-screen

   460 Start in full screen.

   461 

   462 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]

   463 

   464 Normally, QEMU uses SDL to display the VGA output.  With this option,

   465 you can have QEMU listen on VNC display @var{display} and redirect the VGA

   466 display over the VNC session.  It is very useful to enable the usb

   467 tablet device when using this option (option @option{-usbdevice

   468 tablet}). When using the VNC display, you must use the @option{-k}

   469 parameter to set the keyboard layout if you are not using en-us. Valid

   470 syntax for the @var{display} is

   471 

   472 @table @code

   473 

   474 @item @var{host}:@var{d}

   475 

   476 TCP connections will only be allowed from @var{host} on display @var{d}.

   477 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can

   478 be omitted in which case the server will accept connections from any host.

   479 

   480 @item @code{unix}:@var{path}

   481 

   482 Connections will be allowed over UNIX domain sockets where @var{path} is the

   483 location of a unix socket to listen for connections on.

   484 

   485 @item none

   486 

   487 VNC is initialized but not started. The monitor @code{change} command

   488 can be used to later start the VNC server.

   489 

   490 @end table

   491 

   492 Following the @var{display} value there may be one or more @var{option} flags

   493 separated by commas. Valid options are

   494 

   495 @table @code

   496 

   497 @item reverse

   498 

   499 Connect to a listening VNC client via a ``reverse'' connection. The

   500 client is specified by the @var{display}. For reverse network

   501 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument

   502 is a TCP port number, not a display number.

   503 

   504 @item password

   505 

   506 Require that password based authentication is used for client connections.

   507 The password must be set separately using the @code{change} command in the

   508 @ref{pcsys_monitor}

   509 

   510 @item tls

   511 

   512 Require that client use TLS when communicating with the VNC server. This

   513 uses anonymous TLS credentials so is susceptible to a man-in-the-middle

   514 attack. It is recommended that this option be combined with either the

   515 @var{x509} or @var{x509verify} options.

   516 

   517 @item x509=@var{/path/to/certificate/dir}

   518 

   519 Valid if @option{tls} is specified. Require that x509 credentials are used

   520 for negotiating the TLS session. The server will send its x509 certificate

   521 to the client. It is recommended that a password be set on the VNC server

   522 to provide authentication of the client when this is used. The path following

   523 this option specifies where the x509 certificates are to be loaded from.

   524 See the @ref{vnc_security} section for details on generating certificates.

   525 

   526 @item x509verify=@var{/path/to/certificate/dir}

   527 

   528 Valid if @option{tls} is specified. Require that x509 credentials are used

   529 for negotiating the TLS session. The server will send its x509 certificate

   530 to the client, and request that the client send its own x509 certificate.

   531 The server will validate the client's certificate against the CA certificate,

   532 and reject clients when validation fails. If the certificate authority is

   533 trusted, this is a sufficient authentication mechanism. You may still wish

   534 to set a password on the VNC server as a second authentication layer. The

   535 path following this option specifies where the x509 certificates are to

   536 be loaded from. See the @ref{vnc_security} section for details on generating

   537 certificates.

   538 

   539 @end table

   540 

   541 @item -k @var{language}

   542 

   543 Use keyboard layout @var{language} (for example @code{fr} for

   544 French). This option is only needed where it is not easy to get raw PC

   545 keycodes (e.g. on Macs, with some X11 servers or with a VNC

   546 display). You don't normally need to use it on PC/Linux or PC/Windows

   547 hosts.

   548 

   549 The available layouts are:

   550 @example

   551 ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv

   552 da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th

   553 de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr

   554 @end example

   555 

   556 The default is @code{en-us}.

   557 

   558 @end table

   559 

   560 USB options:

   561 @table @option

   562 

   563 @item -usb

   564 Enable the USB driver (will be the default soon)

   565 

   566 @item -usbdevice @var{devname}

   567 Add the USB device @var{devname}. @xref{usb_devices}.

   568 

   569 @table @code

   570 

   571 @item mouse

   572 Virtual Mouse. This will override the PS/2 mouse emulation when activated.

   573 

   574 @item tablet

   575 Pointer device that uses absolute coordinates (like a touchscreen). This

   576 means qemu is able to report the mouse position without having to grab the

   577 mouse. Also overrides the PS/2 mouse emulation when activated.

   578 

   579 @item disk:[format=@var{format}]:file

   580 Mass storage device based on file. The optional @var{format} argument

   581 will be used rather than detecting the format. Can be used to specifiy

   582 format=raw to avoid interpreting an untrusted format header.

   583 

   584 @item host:bus.addr

   585 Pass through the host device identified by bus.addr (Linux only).

   586 

   587 @item host:vendor_id:product_id

   588 Pass through the host device identified by vendor_id:product_id (Linux only).

   589 

   590 @item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}

   591 Serial converter to host character device @var{dev}, see @code{-serial} for the

   592 available devices.

   593 

   594 @item braille

   595 Braille device.  This will use BrlAPI to display the braille output on a real

   596 or fake device.

   597 

   598 @item net:options

   599 Network adapter that supports CDC ethernet and RNDIS protocols.

   600 

   601 @end table

   602 

   603 @end table

   604 

   605 Network options:

   606 

   607 @table @option

   608 

   609 @item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}]

   610 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}

   611 = 0 is the default). The NIC is an ne2k_pci by default on the PC

   612 target. Optionally, the MAC address can be changed. If no

   613 @option{-net} option is specified, a single NIC is created.

   614 Qemu can emulate several different models of network card.

   615 Valid values for @var{type} are

   616 @code{i82551}, @code{i82557b}, @code{i82559er},

   617 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},

   618 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.

   619 Not all devices are supported on all targets.  Use -net nic,model=?

   620 for a list of available devices for your target.

   621 

   622 @item -net user[,vlan=@var{n}][,hostname=@var{name}]

   623 Use the user mode network stack which requires no administrator

   624 privilege to run.  @option{hostname=name} can be used to specify the client

   625 hostname reported by the builtin DHCP server.

   626 

   627 @item -net tap[,vlan=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}]

   628 Connect the host TAP network interface @var{name} to VLAN @var{n}, use

   629 the network script @var{file} to configure it and the network script 

   630 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS 

   631 automatically provides one. @option{fd}=@var{h} can be used to specify

   632 the handle of an already opened host TAP interface. The default network 

   633 configure script is @file{/etc/qemu-ifup} and the default network 

   634 deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no} 

   635 or @option{downscript=no} to disable script execution. Example:

   636 

   637 @example

   638 qemu linux.img -net nic -net tap

   639 @end example

   640 

   641 More complicated example (two NICs, each one connected to a TAP device)

   642 @example

   643 qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \

   644                -net nic,vlan=1 -net tap,vlan=1,ifname=tap1

   645 @end example

   646 

   647 

   648 @item -net socket[,vlan=@var{n}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]

   649 

   650 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual

   651 machine using a TCP socket connection. If @option{listen} is

   652 specified, QEMU waits for incoming connections on @var{port}

   653 (@var{host} is optional). @option{connect} is used to connect to

   654 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}

   655 specifies an already opened TCP socket.

   656 

   657 Example:

   658 @example

   659 # launch a first QEMU instance

   660 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \

   661                -net socket,listen=:1234

   662 # connect the VLAN 0 of this instance to the VLAN 0

   663 # of the first instance

   664 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \

   665                -net socket,connect=127.0.0.1:1234

   666 @end example

   667 

   668 @item -net socket[,vlan=@var{n}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]

   669 

   670 Create a VLAN @var{n} shared with another QEMU virtual

   671 machines using a UDP multicast socket, effectively making a bus for

   672 every QEMU with same multicast address @var{maddr} and @var{port}.

   673 NOTES:

   674 @enumerate

   675 @item

   676 Several QEMU can be running on different hosts and share same bus (assuming

   677 correct multicast setup for these hosts).

   678 @item

   679 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see

   680 @url{http://user-mode-linux.sf.net}.

   681 @item

   682 Use @option{fd=h} to specify an already opened UDP multicast socket.

   683 @end enumerate

   684 

   685 Example:

   686 @example

   687 # launch one QEMU instance

   688 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \

   689                -net socket,mcast=230.0.0.1:1234

   690 # launch another QEMU instance on same "bus"

   691 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \

   692                -net socket,mcast=230.0.0.1:1234

   693 # launch yet another QEMU instance on same "bus"

   694 qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \

   695                -net socket,mcast=230.0.0.1:1234

   696 @end example

   697 

   698 Example (User Mode Linux compat.):

   699 @example

   700 # launch QEMU instance (note mcast address selected

   701 # is UML's default)

   702 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \

   703                -net socket,mcast=239.192.168.1:1102

   704 # launch UML

   705 /path/to/linux ubd0=/path/to/root_fs eth0=mcast

   706 @end example

   707 

   708 @item -net vde[,vlan=@var{n}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]

   709 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and

   710 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}

   711 and MODE @var{octalmode} to change default ownership and permissions for

   712 communication port. This option is available only if QEMU has been compiled

   713 with vde support enabled.

   714 

   715 Example:

   716 @example

   717 # launch vde switch

   718 vde_switch -F -sock /tmp/myswitch

   719 # launch QEMU instance

   720 qemu linux.img -net nic -net vde,sock=/tmp/myswitch

   721 @end example

   722 

   723 @item -net none

   724 Indicate that no network devices should be configured. It is used to

   725 override the default configuration (@option{-net nic -net user}) which

   726 is activated if no @option{-net} options are provided.

   727 

   728 @item -tftp @var{dir}

   729 When using the user mode network stack, activate a built-in TFTP

   730 server. The files in @var{dir} will be exposed as the root of a TFTP server.

   731 The TFTP client on the guest must be configured in binary mode (use the command

   732 @code{bin} of the Unix TFTP client). The host IP address on the guest is as

   733 usual 10.0.2.2.

   734 

   735 @item -bootp @var{file}

   736 When using the user mode network stack, broadcast @var{file} as the BOOTP

   737 filename.  In conjunction with @option{-tftp}, this can be used to network boot

   738 a guest from a local directory.

   739 

   740 Example (using pxelinux):

   741 @example

   742 qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0

   743 @end example

   744 

   745 @item -smb @var{dir}

   746 When using the user mode network stack, activate a built-in SMB

   747 server so that Windows OSes can access to the host files in @file{@var{dir}}

   748 transparently.

   749 

   750 In the guest Windows OS, the line:

   751 @example

   752 10.0.2.4 smbserver

   753 @end example

   754 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)

   755 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).

   756 

   757 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.

   758 

   759 Note that a SAMBA server must be installed on the host OS in

   760 @file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version

   761 2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.

   762 

   763 @item -redir [tcp|udp]:@var{host-port}:[@var{guest-host}]:@var{guest-port}

   764 

   765 When using the user mode network stack, redirect incoming TCP or UDP

   766 connections to the host port @var{host-port} to the guest

   767 @var{guest-host} on guest port @var{guest-port}. If @var{guest-host}

   768 is not specified, its value is 10.0.2.15 (default address given by the

   769 built-in DHCP server).

   770 

   771 For example, to redirect host X11 connection from screen 1 to guest

   772 screen 0, use the following:

   773 

   774 @example

   775 # on the host

   776 qemu -redir tcp:6001::6000 [...]

   777 # this host xterm should open in the guest X11 server

   778 xterm -display :1

   779 @end example

   780 

   781 To redirect telnet connections from host port 5555 to telnet port on

   782 the guest, use the following:

   783 

   784 @example

   785 # on the host

   786 qemu -redir tcp:5555::23 [...]

   787 telnet localhost 5555

   788 @end example

   789 

   790 Then when you use on the host @code{telnet localhost 5555}, you

   791 connect to the guest telnet server.

   792 

   793 @end table

   794 

   795 Bluetooth(R) options:

   796 @table @option

   797 

   798 @item -bt hci[...]

   799 Defines the function of the corresponding Bluetooth HCI.  -bt options

   800 are matched with the HCIs present in the chosen machine type.  For

   801 example when emulating a machine with only one HCI built into it, only

   802 the first @code{-bt hci[...]} option is valid and defines the HCI's

   803 logic.  The Transport Layer is decided by the machine type.  Currently

   804 the machines @code{n800} and @code{n810} have one HCI and all other

   805 machines have none.

   806 

   807 @anchor{bt-hcis}

   808 The following three types are recognized:

   809 

   810 @table @code

   811 @item -bt hci,null

   812 (default) The corresponding Bluetooth HCI assumes no internal logic

   813 and will not respond to any HCI commands or emit events.

   814 

   815 @item -bt hci,host[:@var{id}]

   816 (@code{bluez} only) The corresponding HCI passes commands / events

   817 to / from the physical HCI identified by the name @var{id} (default:

   818 @code{hci0}) on the computer running QEMU.  Only available on @code{bluez}

   819 capable systems like Linux.

   820 

   821 @item -bt hci[,vlan=@var{n}]

   822 Add a virtual, standard HCI that will participate in the Bluetooth

   823 scatternet @var{n} (default @code{0}).  Similarly to @option{-net}

   824 VLANs, devices inside a bluetooth network @var{n} can only communicate

   825 with other devices in the same network (scatternet).

   826 @end table

   827 

   828 @item -bt vhci[,vlan=@var{n}]

   829 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached

   830 to the host bluetooth stack instead of to the emulated target.  This

   831 allows the host and target machines to participate in a common scatternet

   832 and communicate.  Requires the Linux @code{vhci} driver installed.  Can

   833 be used as following:

   834 

   835 @example

   836 qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5

   837 @end example

   838 

   839 @item -bt device:@var{dev}[,vlan=@var{n}]

   840 Emulate a bluetooth device @var{dev} and place it in network @var{n}

   841 (default @code{0}).  QEMU can only emulate one type of bluetooth devices

   842 currently:

   843 

   844 @table @code

   845 @item keyboard

   846 Virtual wireless keyboard implementing the HIDP bluetooth profile.

   847 @end table

   848 

   849 @end table

   850 

   851 Linux boot specific: When using these options, you can use a given

   852 Linux kernel without installing it in the disk image. It can be useful

   853 for easier testing of various kernels.

   854 

   855 @table @option

   856 

   857 @item -kernel @var{bzImage}

   858 Use @var{bzImage} as kernel image.

   859 

   860 @item -append @var{cmdline}

   861 Use @var{cmdline} as kernel command line

   862 

   863 @item -initrd @var{file}

   864 Use @var{file} as initial ram disk.

   865 

   866 @end table

   867 

   868 Debug/Expert options:

   869 @table @option

   870 

   871 @item -serial @var{dev}

   872 Redirect the virtual serial port to host character device

   873 @var{dev}. The default device is @code{vc} in graphical mode and

   874 @code{stdio} in non graphical mode.

   875 

   876 This option can be used several times to simulate up to 4 serials

   877 ports.

   878 

   879 Use @code{-serial none} to disable all serial ports.

   880 

   881 Available character devices are:

   882 @table @code

   883 @item vc[:WxH]

   884 Virtual console. Optionally, a width and height can be given in pixel with

   885 @example

   886 vc:800x600

   887 @end example

   888 It is also possible to specify width or height in characters:

   889 @example

   890 vc:80Cx24C

   891 @end example

   892 @item pty

   893 [Linux only] Pseudo TTY (a new PTY is automatically allocated)

   894 @item none

   895 No device is allocated.

   896 @item null

   897 void device

   898 @item /dev/XXX

   899 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port

   900 parameters are set according to the emulated ones.

   901 @item /dev/parport@var{N}

   902 [Linux only, parallel port only] Use host parallel port

   903 @var{N}. Currently SPP and EPP parallel port features can be used.

   904 @item file:@var{filename}

   905 Write output to @var{filename}. No character can be read.

   906 @item stdio

   907 [Unix only] standard input/output

   908 @item pipe:@var{filename}

   909 name pipe @var{filename}

   910 @item COM@var{n}

   911 [Windows only] Use host serial port @var{n}

   912 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]

   913 This implements UDP Net Console.

   914 When @var{remote_host} or @var{src_ip} are not specified

   915 they default to @code{0.0.0.0}.

   916 When not using a specified @var{src_port} a random port is automatically chosen.

   917 

   918 If you just want a simple readonly console you can use @code{netcat} or

   919 @code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:

   920 @code{nc -u -l -p 4555}. Any time qemu writes something to that port it

   921 will appear in the netconsole session.

   922 

   923 If you plan to send characters back via netconsole or you want to stop

   924 and start qemu a lot of times, you should have qemu use the same

   925 source port each time by using something like @code{-serial

   926 udp::4555@@:4556} to qemu. Another approach is to use a patched

   927 version of netcat which can listen to a TCP port and send and receive

   928 characters via udp.  If you have a patched version of netcat which

   929 activates telnet remote echo and single char transfer, then you can

   930 use the following options to step up a netcat redirector to allow

   931 telnet on port 5555 to access the qemu port.

   932 @table @code

   933 @item Qemu Options:

   934 -serial udp::4555@@:4556

   935 @item netcat options:

   936 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T

   937 @item telnet options:

   938 localhost 5555

   939 @end table

   940 

   941 

   942 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]

   943 The TCP Net Console has two modes of operation.  It can send the serial

   944 I/O to a location or wait for a connection from a location.  By default

   945 the TCP Net Console is sent to @var{host} at the @var{port}.  If you use

   946 the @var{server} option QEMU will wait for a client socket application

   947 to connect to the port before continuing, unless the @code{nowait}

   948 option was specified.  The @code{nodelay} option disables the Nagle buffering

   949 algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only

   950 one TCP connection at a time is accepted. You can use @code{telnet} to

   951 connect to the corresponding character device.

   952 @table @code

   953 @item Example to send tcp console to 192.168.0.2 port 4444

   954 -serial tcp:192.168.0.2:4444

   955 @item Example to listen and wait on port 4444 for connection

   956 -serial tcp::4444,server

   957 @item Example to not wait and listen on ip 192.168.0.100 port 4444

   958 -serial tcp:192.168.0.100:4444,server,nowait

   959 @end table

   960 

   961 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]

   962 The telnet protocol is used instead of raw tcp sockets.  The options

   963 work the same as if you had specified @code{-serial tcp}.  The

   964 difference is that the port acts like a telnet server or client using

   965 telnet option negotiation.  This will also allow you to send the

   966 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break

   967 sequence.  Typically in unix telnet you do it with Control-] and then

   968 type "send break" followed by pressing the enter key.

   969 

   970 @item unix:@var{path}[,server][,nowait]

   971 A unix domain socket is used instead of a tcp socket.  The option works the

   972 same as if you had specified @code{-serial tcp} except the unix domain socket

   973 @var{path} is used for connections.

   974 

   975 @item mon:@var{dev_string}

   976 This is a special option to allow the monitor to be multiplexed onto

   977 another serial port.  The monitor is accessed with key sequence of

   978 @key{Control-a} and then pressing @key{c}. See monitor access

   979 @ref{pcsys_keys} in the -nographic section for more keys.

   980 @var{dev_string} should be any one of the serial devices specified

   981 above.  An example to multiplex the monitor onto a telnet server

   982 listening on port 4444 would be:

   983 @table @code

   984 @item -serial mon:telnet::4444,server,nowait

   985 @end table

   986 

   987 @item braille

   988 Braille device.  This will use BrlAPI to display the braille output on a real

   989 or fake device.

   990 

   991 @end table

   992 

   993 @item -parallel @var{dev}

   994 Redirect the virtual parallel port to host device @var{dev} (same

   995 devices as the serial port). On Linux hosts, @file{/dev/parportN} can

   996 be used to use hardware devices connected on the corresponding host

   997 parallel port.

   998 

   999 This option can be used several times to simulate up to 3 parallel

  1000 ports.

  1001 

  1002 Use @code{-parallel none} to disable all parallel ports.

  1003 

  1004 @item -monitor @var{dev}

  1005 Redirect the monitor to host device @var{dev} (same devices as the

  1006 serial port).

  1007 The default device is @code{vc} in graphical mode and @code{stdio} in

  1008 non graphical mode.

  1009 

  1010 @item -echr numeric_ascii_value

  1011 Change the escape character used for switching to the monitor when using

  1012 monitor and serial sharing.  The default is @code{0x01} when using the

  1013 @code{-nographic} option.  @code{0x01} is equal to pressing

  1014 @code{Control-a}.  You can select a different character from the ascii

  1015 control keys where 1 through 26 map to Control-a through Control-z.  For

  1016 instance you could use the either of the following to change the escape

  1017 character to Control-t.

  1018 @table @code

  1019 @item -echr 0x14

  1020 @item -echr 20

  1021 @end table

  1022 

  1023 @item -s

  1024 Wait gdb connection to port 1234 (@pxref{gdb_usage}).

  1025 @item -p @var{port}

  1026 Change gdb connection port.  @var{port} can be either a decimal number

  1027 to specify a TCP port, or a host device (same devices as the serial port).

  1028 @item -S

  1029 Do not start CPU at startup (you must type 'c' in the monitor).

  1030 @item -d

  1031 Output log in /tmp/qemu.log

  1032 @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]

  1033 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=

  1034 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS

  1035 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess

  1036 all those parameters. This option is useful for old MS-DOS disk

  1037 images.

  1038 

  1039 @item -L path

  1040 Set the directory for the BIOS, VGA BIOS and keymaps.

  1041 

  1042 @item -vga @var{type}

  1043 Select type of VGA card to emulate. Valid values for @var{type} are

  1044 @table @code

  1045 @item cirrus

  1046 Cirrus Logic GD5446 Video card. All Windows versions starting from

  1047 Windows 95 should recognize and use this graphic card. For optimal

  1048 performances, use 16 bit color depth in the guest and the host OS.

  1049 (This one is the default)

  1050 @item std

  1051 Standard VGA card with Bochs VBE extensions.  If your guest OS

  1052 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want

  1053 to use high resolution modes (>= 1280x1024x16) then you should use

  1054 this option.

  1055 @item vmware

  1056 VMWare SVGA-II compatible adapter. Use it if you have sufficiently

  1057 recent XFree86/XOrg server or Windows guest with a driver for this

  1058 card.

  1059 @end table

  1060 

  1061 @item -no-acpi

  1062 Disable ACPI (Advanced Configuration and Power Interface) support. Use

  1063 it if your guest OS complains about ACPI problems (PC target machine

  1064 only).

  1065 

  1066 @item -no-reboot

  1067 Exit instead of rebooting.

  1068 

  1069 @item -no-shutdown

  1070 Don't exit QEMU on guest shutdown, but instead only stop the emulation.

  1071 This allows for instance switching to monitor to commit changes to the

  1072 disk image.

  1073 

  1074 @item -loadvm file

  1075 Start right away with a saved state (@code{loadvm} in monitor)

  1076 

  1077 @item -semihosting

  1078 Enable semihosting syscall emulation (ARM and M68K target machines only).

  1079 

  1080 On ARM this implements the "Angel" interface.

  1081 On M68K this implements the "ColdFire GDB" interface used by libgloss.

  1082 

  1083 Note that this allows guest direct access to the host filesystem,

  1084 so should only be used with trusted guest OS.

  1085 

  1086 @item -icount [N|auto]

  1087 Enable virtual instruction counter.  The virtual cpu will execute one

  1088 instruction every 2^N ns of virtual time.  If @code{auto} is specified

  1089 then the virtual cpu speed will be automatically adjusted to keep virtual

  1090 time within a few seconds of real time.

  1091 

  1092 Note that while this option can give deterministic behavior, it does not

  1093 provide cycle accurate emulation.  Modern CPUs contain superscalar out of

  1094 order cores with complex cache hierarchies.  The number of instructions

  1095 executed often has little or no correlation with actual performance.

  1096 @end table

  1097 

  1098 @c man end

  1099 

  1100 @node pcsys_keys

  1101 @section Keys

  1102 

  1103 @c man begin OPTIONS

  1104 

  1105 During the graphical emulation, you can use the following keys:

  1106 @table @key

  1107 @item Ctrl-Alt-f

  1108 Toggle full screen

  1109 

  1110 @item Ctrl-Alt-n

  1111 Switch to virtual console 'n'. Standard console mappings are:

  1112 @table @emph

  1113 @item 1

  1114 Target system display

  1115 @item 2

  1116 Monitor

  1117 @item 3

  1118 Serial port

  1119 @end table

  1120 

  1121 @item Ctrl-Alt

  1122 Toggle mouse and keyboard grab.

  1123 @end table

  1124 

  1125 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},

  1126 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.

  1127 

  1128 During emulation, if you are using the @option{-nographic} option, use

  1129 @key{Ctrl-a h} to get terminal commands:

  1130 

  1131 @table @key

  1132 @item Ctrl-a h

  1133 Print this help

  1134 @item Ctrl-a x

  1135 Exit emulator