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