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