sh4/r2d: update pci, usb and kernel management
[qemu/sh4.git] / qemu-doc.texi
blob77170d3ad672f66a5e6b1d19e866ebbb07f6db65
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, virtio.
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 Some block drivers perform badly with @option{cache=writethrough}, most notably,
293 qcow2.  If performance is more important than correctness,
294 @option{cache=writeback} should be used with qcow2.  By default, if no explicit
295 caching is specified for a qcow2 disk image, @option{cache=writeback} will be
296 used.  For all other disk types, @option{cache=writethrough} is the default.
298 Instead of @option{-cdrom} you can use:
299 @example
300 qemu -drive file=file,index=2,media=cdrom
301 @end example
303 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
304 use:
305 @example
306 qemu -drive file=file,index=0,media=disk
307 qemu -drive file=file,index=1,media=disk
308 qemu -drive file=file,index=2,media=disk
309 qemu -drive file=file,index=3,media=disk
310 @end example
312 You can connect a CDROM to the slave of ide0:
313 @example
314 qemu -drive file=file,if=ide,index=1,media=cdrom
315 @end example
317 If you don't specify the "file=" argument, you define an empty drive:
318 @example
319 qemu -drive if=ide,index=1,media=cdrom
320 @end example
322 You can connect a SCSI disk with unit ID 6 on the bus #0:
323 @example
324 qemu -drive file=file,if=scsi,bus=0,unit=6
325 @end example
327 Instead of @option{-fda}, @option{-fdb}, you can use:
328 @example
329 qemu -drive file=file,index=0,if=floppy
330 qemu -drive file=file,index=1,if=floppy
331 @end example
333 By default, @var{interface} is "ide" and @var{index} is automatically
334 incremented:
335 @example
336 qemu -drive file=a -drive file=b"
337 @end example
338 is interpreted like:
339 @example
340 qemu -hda a -hdb b
341 @end example
343 @item -boot [a|c|d|n]
344 Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
345 is the default.
347 @item -snapshot
348 Write to temporary files instead of disk image files. In this case,
349 the raw disk image you use is not written back. You can however force
350 the write back by pressing @key{C-a s} (@pxref{disk_images}).
352 @item -no-fd-bootchk
353 Disable boot signature checking for floppy disks in Bochs BIOS. It may
354 be needed to boot from old floppy disks.
356 @item -m @var{megs}
357 Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB.  Optionally,
358 a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
359 gigabytes respectively.
361 @item -cpu @var{model}
362 Select CPU model (-cpu ? for list and additional feature selection)
364 @item -smp @var{n}
365 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
366 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
367 to 4.
369 @item -audio-help
371 Will show the audio subsystem help: list of drivers, tunable
372 parameters.
374 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
376 Enable audio and selected sound hardware. Use ? to print all
377 available sound hardware.
379 @example
380 qemu -soundhw sb16,adlib disk.img
381 qemu -soundhw es1370 disk.img
382 qemu -soundhw ac97 disk.img
383 qemu -soundhw all disk.img
384 qemu -soundhw ?
385 @end example
387 Note that Linux's i810_audio OSS kernel (for AC97) module might
388 require manually specifying clocking.
390 @example
391 modprobe i810_audio clocking=48000
392 @end example
394 @item -localtime
395 Set the real time clock to local time (the default is to UTC
396 time). This option is needed to have correct date in MS-DOS or
397 Windows.
399 @item -startdate @var{date}
400 Set the initial date of the real time clock. Valid formats for
401 @var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
402 @code{2006-06-17}. The default value is @code{now}.
404 @item -pidfile @var{file}
405 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
406 from a script.
408 @item -daemonize
409 Daemonize the QEMU process after initialization.  QEMU will not detach from
410 standard IO until it is ready to receive connections on any of its devices.
411 This option is a useful way for external programs to launch QEMU without having
412 to cope with initialization race conditions.
414 @item -win2k-hack
415 Use it when installing Windows 2000 to avoid a disk full bug. After
416 Windows 2000 is installed, you no longer need this option (this option
417 slows down the IDE transfers).
419 @item -option-rom @var{file}
420 Load the contents of @var{file} as an option ROM.
421 This option is useful to load things like EtherBoot.
423 @item -name @var{name}
424 Sets the @var{name} of the guest.
425 This name will be displayed in the SDL window caption.
426 The @var{name} will also be used for the VNC server.
428 @end table
430 Display options:
431 @table @option
433 @item -nographic
435 Normally, QEMU uses SDL to display the VGA output. With this option,
436 you can totally disable graphical output so that QEMU is a simple
437 command line application. The emulated serial port is redirected on
438 the console. Therefore, you can still use QEMU to debug a Linux kernel
439 with a serial console.
441 @item -curses
443 Normally, QEMU uses SDL to display the VGA output.  With this option,
444 QEMU can display the VGA output when in text mode using a 
445 curses/ncurses interface.  Nothing is displayed in graphical mode.
447 @item -no-frame
449 Do not use decorations for SDL windows and start them using the whole
450 available screen space. This makes the using QEMU in a dedicated desktop
451 workspace more convenient.
453 @item -no-quit
455 Disable SDL window close capability.
457 @item -full-screen
458 Start in full screen.
460 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
462 Normally, QEMU uses SDL to display the VGA output.  With this option,
463 you can have QEMU listen on VNC display @var{display} and redirect the VGA
464 display over the VNC session.  It is very useful to enable the usb
465 tablet device when using this option (option @option{-usbdevice
466 tablet}). When using the VNC display, you must use the @option{-k}
467 parameter to set the keyboard layout if you are not using en-us. Valid
468 syntax for the @var{display} is
470 @table @code
472 @item @var{host}:@var{d}
474 TCP connections will only be allowed from @var{host} on display @var{d}.
475 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
476 be omitted in which case the server will accept connections from any host.
478 @item @code{unix}:@var{path}
480 Connections will be allowed over UNIX domain sockets where @var{path} is the
481 location of a unix socket to listen for connections on.
483 @item none
485 VNC is initialized but not started. The monitor @code{change} command
486 can be used to later start the VNC server.
488 @end table
490 Following the @var{display} value there may be one or more @var{option} flags
491 separated by commas. Valid options are
493 @table @code
495 @item reverse
497 Connect to a listening VNC client via a ``reverse'' connection. The
498 client is specified by the @var{display}. For reverse network
499 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
500 is a TCP port number, not a display number.
502 @item password
504 Require that password based authentication is used for client connections.
505 The password must be set separately using the @code{change} command in the
506 @ref{pcsys_monitor}
508 @item tls
510 Require that client use TLS when communicating with the VNC server. This
511 uses anonymous TLS credentials so is susceptible to a man-in-the-middle
512 attack. It is recommended that this option be combined with either the
513 @var{x509} or @var{x509verify} options.
515 @item x509=@var{/path/to/certificate/dir}
517 Valid if @option{tls} is specified. Require that x509 credentials are used
518 for negotiating the TLS session. The server will send its x509 certificate
519 to the client. It is recommended that a password be set on the VNC server
520 to provide authentication of the client when this is used. The path following
521 this option specifies where the x509 certificates are to be loaded from.
522 See the @ref{vnc_security} section for details on generating certificates.
524 @item x509verify=@var{/path/to/certificate/dir}
526 Valid if @option{tls} is specified. Require that x509 credentials are used
527 for negotiating the TLS session. The server will send its x509 certificate
528 to the client, and request that the client send its own x509 certificate.
529 The server will validate the client's certificate against the CA certificate,
530 and reject clients when validation fails. If the certificate authority is
531 trusted, this is a sufficient authentication mechanism. You may still wish
532 to set a password on the VNC server as a second authentication layer. The
533 path following this option specifies where the x509 certificates are to
534 be loaded from. See the @ref{vnc_security} section for details on generating
535 certificates.
537 @end table
539 @item -k @var{language}
541 Use keyboard layout @var{language} (for example @code{fr} for
542 French). This option is only needed where it is not easy to get raw PC
543 keycodes (e.g. on Macs, with some X11 servers or with a VNC
544 display). You don't normally need to use it on PC/Linux or PC/Windows
545 hosts.
547 The available layouts are:
548 @example
549 ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
550 da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
551 de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
552 @end example
554 The default is @code{en-us}.
556 @end table
558 USB options:
559 @table @option
561 @item -usb
562 Enable the USB driver (will be the default soon)
564 @item -usbdevice @var{devname}
565 Add the USB device @var{devname}. @xref{usb_devices}.
567 @table @code
569 @item mouse
570 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
572 @item tablet
573 Pointer device that uses absolute coordinates (like a touchscreen). This
574 means qemu is able to report the mouse position without having to grab the
575 mouse. Also overrides the PS/2 mouse emulation when activated.
577 @item disk:[format=@var{format}]:file
578 Mass storage device based on file. The optional @var{format} argument
579 will be used rather than detecting the format. Can be used to specifiy
580 format=raw to avoid interpreting an untrusted format header.
582 @item host:bus.addr
583 Pass through the host device identified by bus.addr (Linux only).
585 @item host:vendor_id:product_id
586 Pass through the host device identified by vendor_id:product_id (Linux only).
588 @item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
589 Serial converter to host character device @var{dev}, see @code{-serial} for the
590 available devices.
592 @item braille
593 Braille device.  This will use BrlAPI to display the braille output on a real
594 or fake device.
596 @item net:options
597 Network adapter that supports CDC ethernet and RNDIS protocols.
599 @end table
601 @end table
603 Network options:
605 @table @option
607 @item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}]
608 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
609 = 0 is the default). The NIC is an ne2k_pci by default on the PC
610 target. Optionally, the MAC address can be changed. If no
611 @option{-net} option is specified, a single NIC is created.
612 Qemu can emulate several different models of network card.
613 Valid values for @var{type} are
614 @code{i82551}, @code{i82557b}, @code{i82559er},
615 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
616 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
617 Not all devices are supported on all targets.  Use -net nic,model=?
618 for a list of available devices for your target.
620 @item -net user[,vlan=@var{n}][,hostname=@var{name}]
621 Use the user mode network stack which requires no administrator
622 privilege to run.  @option{hostname=name} can be used to specify the client
623 hostname reported by the builtin DHCP server.
625 @item -net tap[,vlan=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}]
626 Connect the host TAP network interface @var{name} to VLAN @var{n}, use
627 the network script @var{file} to configure it and the network script 
628 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS 
629 automatically provides one. @option{fd}=@var{h} can be used to specify
630 the handle of an already opened host TAP interface. The default network 
631 configure script is @file{/etc/qemu-ifup} and the default network 
632 deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no} 
633 or @option{downscript=no} to disable script execution. Example:
635 @example
636 qemu linux.img -net nic -net tap
637 @end example
639 More complicated example (two NICs, each one connected to a TAP device)
640 @example
641 qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
642                -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
643 @end example
646 @item -net socket[,vlan=@var{n}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
648 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
649 machine using a TCP socket connection. If @option{listen} is
650 specified, QEMU waits for incoming connections on @var{port}
651 (@var{host} is optional). @option{connect} is used to connect to
652 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
653 specifies an already opened TCP socket.
655 Example:
656 @example
657 # launch a first QEMU instance
658 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
659                -net socket,listen=:1234
660 # connect the VLAN 0 of this instance to the VLAN 0
661 # of the first instance
662 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
663                -net socket,connect=127.0.0.1:1234
664 @end example
666 @item -net socket[,vlan=@var{n}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
668 Create a VLAN @var{n} shared with another QEMU virtual
669 machines using a UDP multicast socket, effectively making a bus for
670 every QEMU with same multicast address @var{maddr} and @var{port}.
671 NOTES:
672 @enumerate
673 @item
674 Several QEMU can be running on different hosts and share same bus (assuming
675 correct multicast setup for these hosts).
676 @item
677 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
678 @url{http://user-mode-linux.sf.net}.
679 @item
680 Use @option{fd=h} to specify an already opened UDP multicast socket.
681 @end enumerate
683 Example:
684 @example
685 # launch one QEMU instance
686 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
687                -net socket,mcast=230.0.0.1:1234
688 # launch another QEMU instance on same "bus"
689 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
690                -net socket,mcast=230.0.0.1:1234
691 # launch yet another QEMU instance on same "bus"
692 qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
693                -net socket,mcast=230.0.0.1:1234
694 @end example
696 Example (User Mode Linux compat.):
697 @example
698 # launch QEMU instance (note mcast address selected
699 # is UML's default)
700 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
701                -net socket,mcast=239.192.168.1:1102
702 # launch UML
703 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
704 @end example
706 @item -net vde[,vlan=@var{n}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
707 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
708 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
709 and MODE @var{octalmode} to change default ownership and permissions for
710 communication port. This option is available only if QEMU has been compiled
711 with vde support enabled.
713 Example:
714 @example
715 # launch vde switch
716 vde_switch -F -sock /tmp/myswitch
717 # launch QEMU instance
718 qemu linux.img -net nic -net vde,sock=/tmp/myswitch
719 @end example
721 @item -net none
722 Indicate that no network devices should be configured. It is used to
723 override the default configuration (@option{-net nic -net user}) which
724 is activated if no @option{-net} options are provided.
726 @item -tftp @var{dir}
727 When using the user mode network stack, activate a built-in TFTP
728 server. The files in @var{dir} will be exposed as the root of a TFTP server.
729 The TFTP client on the guest must be configured in binary mode (use the command
730 @code{bin} of the Unix TFTP client). The host IP address on the guest is as
731 usual 10.0.2.2.
733 @item -bootp @var{file}
734 When using the user mode network stack, broadcast @var{file} as the BOOTP
735 filename.  In conjunction with @option{-tftp}, this can be used to network boot
736 a guest from a local directory.
738 Example (using pxelinux):
739 @example
740 qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0
741 @end example
743 @item -smb @var{dir}
744 When using the user mode network stack, activate a built-in SMB
745 server so that Windows OSes can access to the host files in @file{@var{dir}}
746 transparently.
748 In the guest Windows OS, the line:
749 @example
750 10.0.2.4 smbserver
751 @end example
752 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
753 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
755 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
757 Note that a SAMBA server must be installed on the host OS in
758 @file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version
759 2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
761 @item -redir [tcp|udp]:@var{host-port}:[@var{guest-host}]:@var{guest-port}
763 When using the user mode network stack, redirect incoming TCP or UDP
764 connections to the host port @var{host-port} to the guest
765 @var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
766 is not specified, its value is 10.0.2.15 (default address given by the
767 built-in DHCP server).
769 For example, to redirect host X11 connection from screen 1 to guest
770 screen 0, use the following:
772 @example
773 # on the host
774 qemu -redir tcp:6001::6000 [...]
775 # this host xterm should open in the guest X11 server
776 xterm -display :1
777 @end example
779 To redirect telnet connections from host port 5555 to telnet port on
780 the guest, use the following:
782 @example
783 # on the host
784 qemu -redir tcp:5555::23 [...]
785 telnet localhost 5555
786 @end example
788 Then when you use on the host @code{telnet localhost 5555}, you
789 connect to the guest telnet server.
791 @end table
793 Bluetooth(R) options:
794 @table @option
796 @item -bt hci[...]
797 Defines the function of the corresponding Bluetooth HCI.  -bt options
798 are matched with the HCIs present in the chosen machine type.  For
799 example when emulating a machine with only one HCI built into it, only
800 the first @code{-bt hci[...]} option is valid and defines the HCI's
801 logic.  The Transport Layer is decided by the machine type.  Currently
802 the machines @code{n800} and @code{n810} have one HCI and all other
803 machines have none.
805 @anchor{bt-hcis}
806 The following three types are recognized:
808 @table @code
809 @item -bt hci,null
810 (default) The corresponding Bluetooth HCI assumes no internal logic
811 and will not respond to any HCI commands or emit events.
813 @item -bt hci,host[:@var{id}]
814 (@code{bluez} only) The corresponding HCI passes commands / events
815 to / from the physical HCI identified by the name @var{id} (default:
816 @code{hci0}) on the computer running QEMU.  Only available on @code{bluez}
817 capable systems like Linux.
819 @item -bt hci[,vlan=@var{n}]
820 Add a virtual, standard HCI that will participate in the Bluetooth
821 scatternet @var{n} (default @code{0}).  Similarly to @option{-net}
822 VLANs, devices inside a bluetooth network @var{n} can only communicate
823 with other devices in the same network (scatternet).
824 @end table
826 @item -bt vhci[,vlan=@var{n}]
827 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
828 to the host bluetooth stack instead of to the emulated target.  This
829 allows the host and target machines to participate in a common scatternet
830 and communicate.  Requires the Linux @code{vhci} driver installed.  Can
831 be used as following:
833 @example
834 qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
835 @end example
837 @item -bt device:@var{dev}[,vlan=@var{n}]
838 Emulate a bluetooth device @var{dev} and place it in network @var{n}
839 (default @code{0}).  QEMU can only emulate one type of bluetooth devices
840 currently:
842 @table @code
843 @item keyboard
844 Virtual wireless keyboard implementing the HIDP bluetooth profile.
845 @end table
847 @end table
849 Linux boot specific: When using these options, you can use a given
850 Linux kernel without installing it in the disk image. It can be useful
851 for easier testing of various kernels.
853 @table @option
855 @item -kernel @var{bzImage}
856 Use @var{bzImage} as kernel image.
858 @item -append @var{cmdline}
859 Use @var{cmdline} as kernel command line
861 @item -initrd @var{file}
862 Use @var{file} as initial ram disk.
864 @end table
866 Debug/Expert options:
867 @table @option
869 @item -serial @var{dev}
870 Redirect the virtual serial port to host character device
871 @var{dev}. The default device is @code{vc} in graphical mode and
872 @code{stdio} in non graphical mode.
874 This option can be used several times to simulate up to 4 serials
875 ports.
877 Use @code{-serial none} to disable all serial ports.
879 Available character devices are:
880 @table @code
881 @item vc[:WxH]
882 Virtual console. Optionally, a width and height can be given in pixel with
883 @example
884 vc:800x600
885 @end example
886 It is also possible to specify width or height in characters:
887 @example
888 vc:80Cx24C
889 @end example
890 @item pty
891 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
892 @item none
893 No device is allocated.
894 @item null
895 void device
896 @item /dev/XXX
897 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
898 parameters are set according to the emulated ones.
899 @item /dev/parport@var{N}
900 [Linux only, parallel port only] Use host parallel port
901 @var{N}. Currently SPP and EPP parallel port features can be used.
902 @item file:@var{filename}
903 Write output to @var{filename}. No character can be read.
904 @item stdio
905 [Unix only] standard input/output
906 @item pipe:@var{filename}
907 name pipe @var{filename}
908 @item COM@var{n}
909 [Windows only] Use host serial port @var{n}
910 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
911 This implements UDP Net Console.
912 When @var{remote_host} or @var{src_ip} are not specified
913 they default to @code{0.0.0.0}.
914 When not using a specified @var{src_port} a random port is automatically chosen.
916 If you just want a simple readonly console you can use @code{netcat} or
917 @code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
918 @code{nc -u -l -p 4555}. Any time qemu writes something to that port it
919 will appear in the netconsole session.
921 If you plan to send characters back via netconsole or you want to stop
922 and start qemu a lot of times, you should have qemu use the same
923 source port each time by using something like @code{-serial
924 udp::4555@@:4556} to qemu. Another approach is to use a patched
925 version of netcat which can listen to a TCP port and send and receive
926 characters via udp.  If you have a patched version of netcat which
927 activates telnet remote echo and single char transfer, then you can
928 use the following options to step up a netcat redirector to allow
929 telnet on port 5555 to access the qemu port.
930 @table @code
931 @item Qemu Options:
932 -serial udp::4555@@:4556
933 @item netcat options:
934 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
935 @item telnet options:
936 localhost 5555
937 @end table
940 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
941 The TCP Net Console has two modes of operation.  It can send the serial
942 I/O to a location or wait for a connection from a location.  By default
943 the TCP Net Console is sent to @var{host} at the @var{port}.  If you use
944 the @var{server} option QEMU will wait for a client socket application
945 to connect to the port before continuing, unless the @code{nowait}
946 option was specified.  The @code{nodelay} option disables the Nagle buffering
947 algorithm.  If @var{host} is omitted, 0.0.0.0 is assumed. Only
948 one TCP connection at a time is accepted. You can use @code{telnet} to
949 connect to the corresponding character device.
950 @table @code
951 @item Example to send tcp console to 192.168.0.2 port 4444
952 -serial tcp:192.168.0.2:4444
953 @item Example to listen and wait on port 4444 for connection
954 -serial tcp::4444,server
955 @item Example to not wait and listen on ip 192.168.0.100 port 4444
956 -serial tcp:192.168.0.100:4444,server,nowait
957 @end table
959 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
960 The telnet protocol is used instead of raw tcp sockets.  The options
961 work the same as if you had specified @code{-serial tcp}.  The
962 difference is that the port acts like a telnet server or client using
963 telnet option negotiation.  This will also allow you to send the
964 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
965 sequence.  Typically in unix telnet you do it with Control-] and then
966 type "send break" followed by pressing the enter key.
968 @item unix:@var{path}[,server][,nowait]
969 A unix domain socket is used instead of a tcp socket.  The option works the
970 same as if you had specified @code{-serial tcp} except the unix domain socket
971 @var{path} is used for connections.
973 @item mon:@var{dev_string}
974 This is a special option to allow the monitor to be multiplexed onto
975 another serial port.  The monitor is accessed with key sequence of
976 @key{Control-a} and then pressing @key{c}. See monitor access
977 @ref{pcsys_keys} in the -nographic section for more keys.
978 @var{dev_string} should be any one of the serial devices specified
979 above.  An example to multiplex the monitor onto a telnet server
980 listening on port 4444 would be:
981 @table @code
982 @item -serial mon:telnet::4444,server,nowait
983 @end table
985 @item braille
986 Braille device.  This will use BrlAPI to display the braille output on a real
987 or fake device.
989 @end table
991 @item -parallel @var{dev}
992 Redirect the virtual parallel port to host device @var{dev} (same
993 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
994 be used to use hardware devices connected on the corresponding host
995 parallel port.
997 This option can be used several times to simulate up to 3 parallel
998 ports.
1000 Use @code{-parallel none} to disable all parallel ports.
1002 @item -monitor @var{dev}
1003 Redirect the monitor to host device @var{dev} (same devices as the
1004 serial port).
1005 The default device is @code{vc} in graphical mode and @code{stdio} in
1006 non graphical mode.
1008 @item -echr numeric_ascii_value
1009 Change the escape character used for switching to the monitor when using
1010 monitor and serial sharing.  The default is @code{0x01} when using the
1011 @code{-nographic} option.  @code{0x01} is equal to pressing
1012 @code{Control-a}.  You can select a different character from the ascii
1013 control keys where 1 through 26 map to Control-a through Control-z.  For
1014 instance you could use the either of the following to change the escape
1015 character to Control-t.
1016 @table @code
1017 @item -echr 0x14
1018 @item -echr 20
1019 @end table
1021 @item -s
1022 Wait gdb connection to port 1234 (@pxref{gdb_usage}).
1023 @item -p @var{port}
1024 Change gdb connection port.  @var{port} can be either a decimal number
1025 to specify a TCP port, or a host device (same devices as the serial port).
1026 @item -S
1027 Do not start CPU at startup (you must type 'c' in the monitor).
1028 @item -d
1029 Output log in /tmp/qemu.log
1030 @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
1031 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
1032 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
1033 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
1034 all those parameters. This option is useful for old MS-DOS disk
1035 images.
1037 @item -L path
1038 Set the directory for the BIOS, VGA BIOS and keymaps.
1040 @item -vga @var{type}
1041 Select type of VGA card to emulate. Valid values for @var{type} are
1042 @table @code
1043 @item cirrus
1044 Cirrus Logic GD5446 Video card. All Windows versions starting from
1045 Windows 95 should recognize and use this graphic card. For optimal
1046 performances, use 16 bit color depth in the guest and the host OS.
1047 (This one is the default)
1048 @item std
1049 Standard VGA card with Bochs VBE extensions.  If your guest OS
1050 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
1051 to use high resolution modes (>= 1280x1024x16) then you should use
1052 this option.
1053 @item vmware
1054 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
1055 recent XFree86/XOrg server or Windows guest with a driver for this
1056 card.
1057 @end table
1059 @item -no-acpi
1060 Disable ACPI (Advanced Configuration and Power Interface) support. Use
1061 it if your guest OS complains about ACPI problems (PC target machine
1062 only).
1064 @item -no-reboot
1065 Exit instead of rebooting.
1067 @item -no-shutdown
1068 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
1069 This allows for instance switching to monitor to commit changes to the
1070 disk image.
1072 @item -loadvm file
1073 Start right away with a saved state (@code{loadvm} in monitor)
1075 @item -semihosting
1076 Enable semihosting syscall emulation (ARM and M68K target machines only).
1078 On ARM this implements the "Angel" interface.
1079 On M68K this implements the "ColdFire GDB" interface used by libgloss.
1081 Note that this allows guest direct access to the host filesystem,
1082 so should only be used with trusted guest OS.
1084 @item -icount [N|auto]
1085 Enable virtual instruction counter.  The virtual cpu will execute one
1086 instruction every 2^N ns of virtual time.  If @code{auto} is specified
1087 then the virtual cpu speed will be automatically adjusted to keep virtual
1088 time within a few seconds of real time.
1090 Note that while this option can give deterministic behavior, it does not
1091 provide cycle accurate emulation.  Modern CPUs contain superscalar out of
1092 order cores with complex cache hierarchies.  The number of instructions
1093 executed often has little or no correlation with actual performance.
1094 @end table
1096 @c man end
1098 @node pcsys_keys
1099 @section Keys
1101 @c man begin OPTIONS
1103 During the graphical emulation, you can use the following keys:
1104 @table @key
1105 @item Ctrl-Alt-f
1106 Toggle full screen
1108 @item Ctrl-Alt-n
1109 Switch to virtual console 'n'. Standard console mappings are:
1110 @table @emph
1111 @item 1
1112 Target system display
1113 @item 2
1114 Monitor
1115 @item 3
1116 Serial port
1117 @end table
1119 @item Ctrl-Alt
1120 Toggle mouse and keyboard grab.
1121 @end table
1123 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
1124 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
1126 During emulation, if you are using the @option{-nographic} option, use
1127 @key{Ctrl-a h} to get terminal commands:
1129 @table @key
1130 @item Ctrl-a h
1131 Print this help
1132 @item Ctrl-a x
1133 Exit emulator
1134 @item Ctrl-a s
1135 Save disk data back to file (if -snapshot)
1136 @item Ctrl-a t
1137 toggle console timestamps
1138 @item Ctrl-a b
1139 Send break (magic sysrq in Linux)
1140 @item Ctrl-a c
1141 Switch between console and monitor
1142 @item Ctrl-a Ctrl-a
1143 Send Ctrl-a
1144 @end table
1145 @c man end
1147 @ignore
1149 @c man begin SEEALSO
1150 The HTML documentation of QEMU for more precise information and Linux
1151 user mode emulator invocation.
1152 @c man end
1154 @c man begin AUTHOR
1155 Fabrice Bellard
1156 @c man end
1158 @end ignore
1160 @node pcsys_monitor
1161 @section QEMU Monitor
1163 The QEMU monitor is used to give complex commands to the QEMU
1164 emulator. You can use it to:
1166 @itemize @minus
1168 @item
1169 Remove or insert removable media images
1170 (such as CD-ROM or floppies).
1172 @item
1173 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
1174 from a disk file.
1176 @item Inspect the VM state without an external debugger.
1178 @end itemize
1180 @subsection Commands
1182 The following commands are available:
1184 @table @option
1186 @item help or ? [@var{cmd}]
1187 Show the help for all commands or just for command @var{cmd}.
1189 @item commit
1190 Commit changes to the disk images (if -snapshot is used).
1192 @item info @var{subcommand}
1193 Show various information about the system state.
1195 @table @option
1196 @item info network
1197 show the various VLANs and the associated devices
1198 @item info block
1199 show the block devices
1200 @item info registers
1201 show the cpu registers
1202 @item info history
1203 show the command line history
1204 @item info pci
1205 show emulated PCI device
1206 @item info usb
1207 show USB devices plugged on the virtual USB hub
1208 @item info usbhost
1209 show all USB host devices
1210 @item info capture
1211 show information about active capturing
1212 @item info snapshots
1213 show list of VM snapshots
1214 @item info mice
1215 show which guest mouse is receiving events
1216 @end table
1218 @item q or quit
1219 Quit the emulator.
1221 @item eject [-f] @var{device}
1222 Eject a removable medium (use -f to force it).
1224 @item change @var{device} @var{setting}
1226 Change the configuration of a device.
1228 @table @option
1229 @item change @var{diskdevice} @var{filename}
1230 Change the medium for a removable disk device to point to @var{filename}. eg
1232 @example
1233 (qemu) change ide1-cd0 /path/to/some.iso
1234 @end example
1236 @item change vnc @var{display},@var{options}
1237 Change the configuration of the VNC server. The valid syntax for @var{display}
1238 and @var{options} are described at @ref{sec_invocation}. eg
1240 @example
1241 (qemu) change vnc localhost:1
1242 @end example
1244 @item change vnc password
1246 Change the password associated with the VNC server. The monitor will prompt for
1247 the new password to be entered. VNC passwords are only significant upto 8 letters.
1250 @example
1251 (qemu) change vnc password
1252 Password: ********
1253 @end example
1255 @end table
1257 @item screendump @var{filename}
1258 Save screen into PPM image @var{filename}.
1260 @item mouse_move @var{dx} @var{dy} [@var{dz}]
1261 Move the active mouse to the specified coordinates @var{dx} @var{dy}
1262 with optional scroll axis @var{dz}.
1264 @item mouse_button @var{val}
1265 Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
1267 @item mouse_set @var{index}
1268 Set which mouse device receives events at given @var{index}, index
1269 can be obtained with
1270 @example
1271 info mice
1272 @end example
1274 @item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
1275 Capture audio into @var{filename}. Using sample rate @var{frequency}
1276 bits per sample @var{bits} and number of channels @var{channels}.
1278 Defaults:
1279 @itemize @minus
1280 @item Sample rate = 44100 Hz - CD quality
1281 @item Bits = 16
1282 @item Number of channels = 2 - Stereo
1283 @end itemize
1285 @item stopcapture @var{index}
1286 Stop capture with a given @var{index}, index can be obtained with
1287 @example
1288 info capture
1289 @end example
1291 @item log @var{item1}[,...]
1292 Activate logging of the specified items to @file{/tmp/qemu.log}.
1294 @item savevm [@var{tag}|@var{id}]
1295 Create a snapshot of the whole virtual machine. If @var{tag} is
1296 provided, it is used as human readable identifier. If there is already
1297 a snapshot with the same tag or ID, it is replaced. More info at
1298 @ref{vm_snapshots}.
1300 @item loadvm @var{tag}|@var{id}
1301 Set the whole virtual machine to the snapshot identified by the tag
1302 @var{tag} or the unique snapshot ID @var{id}.
1304 @item delvm @var{tag}|@var{id}
1305 Delete the snapshot identified by @var{tag} or @var{id}.
1307 @item stop
1308 Stop emulation.
1310 @item c or cont
1311 Resume emulation.
1313 @item gdbserver [@var{port}]
1314 Start gdbserver session (default @var{port}=1234)
1316 @item x/fmt @var{addr}
1317 Virtual memory dump starting at @var{addr}.
1319 @item xp /@var{fmt} @var{addr}
1320 Physical memory dump starting at @var{addr}.
1322 @var{fmt} is a format which tells the command how to format the
1323 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
1325 @table @var
1326 @item count
1327 is the number of items to be dumped.
1329 @item format
1330 can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
1331 c (char) or i (asm instruction).
1333 @item size
1334 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
1335 @code{h} or @code{w} can be specified with the @code{i} format to
1336 respectively select 16 or 32 bit code instruction size.
1338 @end table
1340 Examples:
1341 @itemize
1342 @item
1343 Dump 10 instructions at the current instruction pointer:
1344 @example
1345 (qemu) x/10i $eip
1346 0x90107063:  ret
1347 0x90107064:  sti
1348 0x90107065:  lea    0x0(%esi,1),%esi
1349 0x90107069:  lea    0x0(%edi,1),%edi
1350 0x90107070:  ret
1351 0x90107071:  jmp    0x90107080
1352 0x90107073:  nop
1353 0x90107074:  nop
1354 0x90107075:  nop
1355 0x90107076:  nop
1356 @end example
1358 @item
1359 Dump 80 16 bit values at the start of the video memory.
1360 @smallexample
1361 (qemu) xp/80hx 0xb8000
1362 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
1363 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
1364 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
1365 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
1366 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
1367 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
1368 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1369 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1370 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1371 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1372 @end smallexample
1373 @end itemize
1375 @item p or print/@var{fmt} @var{expr}
1377 Print expression value. Only the @var{format} part of @var{fmt} is
1378 used.
1380 @item sendkey @var{keys}
1382 Send @var{keys} to the emulator. @var{keys} could be the name of the
1383 key or @code{#} followed by the raw value in either decimal or hexadecimal
1384 format. Use @code{-} to press several keys simultaneously. Example:
1385 @example
1386 sendkey ctrl-alt-f1
1387 @end example
1389 This command is useful to send keys that your graphical user interface
1390 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
1392 @item system_reset
1394 Reset the system.
1396 @item boot_set @var{bootdevicelist}
1398 Define new values for the boot device list. Those values will override
1399 the values specified on the command line through the @code{-boot} option.
1401 The values that can be specified here depend on the machine type, but are
1402 the same that can be specified in the @code{-boot} command line option.
1404 @item usb_add @var{devname}
1406 Add the USB device @var{devname}.  For details of available devices see
1407 @ref{usb_devices}
1409 @item usb_del @var{devname}
1411 Remove the USB device @var{devname} from the QEMU virtual USB
1412 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
1413 command @code{info usb} to see the devices you can remove.
1415 @end table
1417 @subsection Integer expressions
1419 The monitor understands integers expressions for every integer
1420 argument. You can use register names to get the value of specifics
1421 CPU registers by prefixing them with @emph{$}.
1423 @node disk_images
1424 @section Disk Images
1426 Since version 0.6.1, QEMU supports many disk image formats, including
1427 growable disk images (their size increase as non empty sectors are
1428 written), compressed and encrypted disk images. Version 0.8.3 added
1429 the new qcow2 disk image format which is essential to support VM
1430 snapshots.
1432 @menu
1433 * disk_images_quickstart::    Quick start for disk image creation
1434 * disk_images_snapshot_mode:: Snapshot mode
1435 * vm_snapshots::              VM snapshots
1436 * qemu_img_invocation::       qemu-img Invocation
1437 * qemu_nbd_invocation::       qemu-nbd Invocation
1438 * host_drives::               Using host drives
1439 * disk_images_fat_images::    Virtual FAT disk images
1440 * disk_images_nbd::           NBD access
1441 @end menu
1443 @node disk_images_quickstart
1444 @subsection Quick start for disk image creation
1446 You can create a disk image with the command:
1447 @example
1448 qemu-img create myimage.img mysize
1449 @end example
1450 where @var{myimage.img} is the disk image filename and @var{mysize} is its
1451 size in kilobytes. You can add an @code{M} suffix to give the size in
1452 megabytes and a @code{G} suffix for gigabytes.
1454 See @ref{qemu_img_invocation} for more information.
1456 @node disk_images_snapshot_mode
1457 @subsection Snapshot mode
1459 If you use the option @option{-snapshot}, all disk images are
1460 considered as read only. When sectors in written, they are written in
1461 a temporary file created in @file{/tmp}. You can however force the
1462 write back to the raw disk images by using the @code{commit} monitor
1463 command (or @key{C-a s} in the serial console).
1465 @node vm_snapshots
1466 @subsection VM snapshots
1468 VM snapshots are snapshots of the complete virtual machine including
1469 CPU state, RAM, device state and the content of all the writable
1470 disks. In order to use VM snapshots, you must have at least one non
1471 removable and writable block device using the @code{qcow2} disk image
1472 format. Normally this device is the first virtual hard drive.
1474 Use the monitor command @code{savevm} to create a new VM snapshot or
1475 replace an existing one. A human readable name can be assigned to each
1476 snapshot in addition to its numerical ID.
1478 Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
1479 a VM snapshot. @code{info snapshots} lists the available snapshots
1480 with their associated information:
1482 @example
1483 (qemu) info snapshots
1484 Snapshot devices: hda
1485 Snapshot list (from hda):
1486 ID        TAG                 VM SIZE                DATE       VM CLOCK
1487 1         start                   41M 2006-08-06 12:38:02   00:00:14.954
1488 2                                 40M 2006-08-06 12:43:29   00:00:18.633
1489 3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
1490 @end example
1492 A VM snapshot is made of a VM state info (its size is shown in
1493 @code{info snapshots}) and a snapshot of every writable disk image.
1494 The VM state info is stored in the first @code{qcow2} non removable
1495 and writable block device. The disk image snapshots are stored in
1496 every disk image. The size of a snapshot in a disk image is difficult
1497 to evaluate and is not shown by @code{info snapshots} because the
1498 associated disk sectors are shared among all the snapshots to save
1499 disk space (otherwise each snapshot would need a full copy of all the
1500 disk images).
1502 When using the (unrelated) @code{-snapshot} option
1503 (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
1504 but they are deleted as soon as you exit QEMU.
1506 VM snapshots currently have the following known limitations:
1507 @itemize
1508 @item
1509 They cannot cope with removable devices if they are removed or
1510 inserted after a snapshot is done.
1511 @item
1512 A few device drivers still have incomplete snapshot support so their
1513 state is not saved or restored properly (in particular USB).
1514 @end itemize
1516 @node qemu_img_invocation
1517 @subsection @code{qemu-img} Invocation
1519 @include qemu-img.texi
1521 @node qemu_nbd_invocation
1522 @subsection @code{qemu-nbd} Invocation
1524 @include qemu-nbd.texi
1526 @node host_drives
1527 @subsection Using host drives
1529 In addition to disk image files, QEMU can directly access host
1530 devices. We describe here the usage for QEMU version >= 0.8.3.
1532 @subsubsection Linux
1534 On Linux, you can directly use the host device filename instead of a
1535 disk image filename provided you have enough privileges to access
1536 it. For example, use @file{/dev/cdrom} to access to the CDROM or
1537 @file{/dev/fd0} for the floppy.
1539 @table @code
1540 @item CD
1541 You can specify a CDROM device even if no CDROM is loaded. QEMU has
1542 specific code to detect CDROM insertion or removal. CDROM ejection by
1543 the guest OS is supported. Currently only data CDs are supported.
1544 @item Floppy
1545 You can specify a floppy device even if no floppy is loaded. Floppy
1546 removal is currently not detected accurately (if you change floppy
1547 without doing floppy access while the floppy is not loaded, the guest
1548 OS will think that the same floppy is loaded).
1549 @item Hard disks
1550 Hard disks can be used. Normally you must specify the whole disk
1551 (@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
1552 see it as a partitioned disk. WARNING: unless you know what you do, it
1553 is better to only make READ-ONLY accesses to the hard disk otherwise
1554 you may corrupt your host data (use the @option{-snapshot} command
1555 line option or modify the device permissions accordingly).
1556 @end table
1558 @subsubsection Windows
1560 @table @code
1561 @item CD
1562 The preferred syntax is the drive letter (e.g. @file{d:}). The
1563 alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
1564 supported as an alias to the first CDROM drive.
1566 Currently there is no specific code to handle removable media, so it
1567 is better to use the @code{change} or @code{eject} monitor commands to
1568 change or eject media.
1569 @item Hard disks
1570 Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
1571 where @var{N} is the drive number (0 is the first hard disk).
1573 WARNING: unless you know what you do, it is better to only make
1574 READ-ONLY accesses to the hard disk otherwise you may corrupt your
1575 host data (use the @option{-snapshot} command line so that the
1576 modifications are written in a temporary file).
1577 @end table
1580 @subsubsection Mac OS X
1582 @file{/dev/cdrom} is an alias to the first CDROM.
1584 Currently there is no specific code to handle removable media, so it
1585 is better to use the @code{change} or @code{eject} monitor commands to
1586 change or eject media.
1588 @node disk_images_fat_images
1589 @subsection Virtual FAT disk images
1591 QEMU can automatically create a virtual FAT disk image from a
1592 directory tree. In order to use it, just type:
1594 @example
1595 qemu linux.img -hdb fat:/my_directory
1596 @end example
1598 Then you access access to all the files in the @file{/my_directory}
1599 directory without having to copy them in a disk image or to export
1600 them via SAMBA or NFS. The default access is @emph{read-only}.
1602 Floppies can be emulated with the @code{:floppy:} option:
1604 @example
1605 qemu linux.img -fda fat:floppy:/my_directory
1606 @end example
1608 A read/write support is available for testing (beta stage) with the
1609 @code{:rw:} option:
1611 @example
1612 qemu linux.img -fda fat:floppy:rw:/my_directory
1613 @end example
1615 What you should @emph{never} do:
1616 @itemize
1617 @item use non-ASCII filenames ;
1618 @item use "-snapshot" together with ":rw:" ;
1619 @item expect it to work when loadvm'ing ;
1620 @item write to the FAT directory on the host system while accessing it with the guest system.
1621 @end itemize
1623 @node disk_images_nbd
1624 @subsection NBD access
1626 QEMU can access directly to block device exported using the Network Block Device
1627 protocol.
1629 @example
1630 qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
1631 @end example
1633 If the NBD server is located on the same host, you can use an unix socket instead
1634 of an inet socket:
1636 @example
1637 qemu linux.img -hdb nbd:unix:/tmp/my_socket
1638 @end example
1640 In this case, the block device must be exported using qemu-nbd:
1642 @example
1643 qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
1644 @end example
1646 The use of qemu-nbd allows to share a disk between several guests:
1647 @example
1648 qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
1649 @end example
1651 and then you can use it with two guests:
1652 @example
1653 qemu linux1.img -hdb nbd:unix:/tmp/my_socket
1654 qemu linux2.img -hdb nbd:unix:/tmp/my_socket
1655 @end example
1657 @node pcsys_network
1658 @section Network emulation
1660 QEMU can simulate several network cards (PCI or ISA cards on the PC
1661 target) and can connect them to an arbitrary number of Virtual Local
1662 Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1663 VLAN. VLAN can be connected between separate instances of QEMU to
1664 simulate large networks. For simpler usage, a non privileged user mode
1665 network stack can replace the TAP device to have a basic network
1666 connection.
1668 @subsection VLANs
1670 QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1671 connection between several network devices. These devices can be for
1672 example QEMU virtual Ethernet cards or virtual Host ethernet devices
1673 (TAP devices).
1675 @subsection Using TAP network interfaces
1677 This is the standard way to connect QEMU to a real network. QEMU adds
1678 a virtual network device on your host (called @code{tapN}), and you
1679 can then configure it as if it was a real ethernet card.
1681 @subsubsection Linux host
1683 As an example, you can download the @file{linux-test-xxx.tar.gz}
1684 archive and copy the script @file{qemu-ifup} in @file{/etc} and
1685 configure properly @code{sudo} so that the command @code{ifconfig}
1686 contained in @file{qemu-ifup} can be executed as root. You must verify
1687 that your host kernel supports the TAP network interfaces: the
1688 device @file{/dev/net/tun} must be present.
1690 See @ref{sec_invocation} to have examples of command lines using the
1691 TAP network interfaces.
1693 @subsubsection Windows host
1695 There is a virtual ethernet driver for Windows 2000/XP systems, called
1696 TAP-Win32. But it is not included in standard QEMU for Windows,
1697 so you will need to get it separately. It is part of OpenVPN package,
1698 so download OpenVPN from : @url{http://openvpn.net/}.
1700 @subsection Using the user mode network stack
1702 By using the option @option{-net user} (default configuration if no
1703 @option{-net} option is specified), QEMU uses a completely user mode
1704 network stack (you don't need root privilege to use the virtual
1705 network). The virtual network configuration is the following:
1707 @example
1709          QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
1710                            |          (10.0.2.2)
1711                            |
1712                            ---->  DNS server (10.0.2.3)
1713                            |
1714                            ---->  SMB server (10.0.2.4)
1715 @end example
1717 The QEMU VM behaves as if it was behind a firewall which blocks all
1718 incoming connections. You can use a DHCP client to automatically
1719 configure the network in the QEMU VM. The DHCP server assign addresses
1720 to the hosts starting from 10.0.2.15.
1722 In order to check that the user mode network is working, you can ping
1723 the address 10.0.2.2 and verify that you got an address in the range
1724 10.0.2.x from the QEMU virtual DHCP server.
1726 Note that @code{ping} is not supported reliably to the internet as it
1727 would require root privileges. It means you can only ping the local
1728 router (10.0.2.2).
1730 When using the built-in TFTP server, the router is also the TFTP
1731 server.
1733 When using the @option{-redir} option, TCP or UDP connections can be
1734 redirected from the host to the guest. It allows for example to
1735 redirect X11, telnet or SSH connections.
1737 @subsection Connecting VLANs between QEMU instances
1739 Using the @option{-net socket} option, it is possible to make VLANs
1740 that span several QEMU instances. See @ref{sec_invocation} to have a
1741 basic example.
1743 @node direct_linux_boot
1744 @section Direct Linux Boot
1746 This section explains how to launch a Linux kernel inside QEMU without
1747 having to make a full bootable image. It is very useful for fast Linux
1748 kernel testing.
1750 The syntax is:
1751 @example
1752 qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1753 @end example
1755 Use @option{-kernel} to provide the Linux kernel image and
1756 @option{-append} to give the kernel command line arguments. The
1757 @option{-initrd} option can be used to provide an INITRD image.
1759 When using the direct Linux boot, a disk image for the first hard disk
1760 @file{hda} is required because its boot sector is used to launch the
1761 Linux kernel.
1763 If you do not need graphical output, you can disable it and redirect
1764 the virtual serial port and the QEMU monitor to the console with the
1765 @option{-nographic} option. The typical command line is:
1766 @example
1767 qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1768      -append "root=/dev/hda console=ttyS0" -nographic
1769 @end example
1771 Use @key{Ctrl-a c} to switch between the serial console and the
1772 monitor (@pxref{pcsys_keys}).
1774 @node pcsys_usb
1775 @section USB emulation
1777 QEMU emulates a PCI UHCI USB controller. You can virtually plug
1778 virtual USB devices or real host USB devices (experimental, works only
1779 on Linux hosts).  Qemu will automatically create and connect virtual USB hubs
1780 as necessary to connect multiple USB devices.
1782 @menu
1783 * usb_devices::
1784 * host_usb_devices::
1785 @end menu
1786 @node usb_devices
1787 @subsection Connecting USB devices
1789 USB devices can be connected with the @option{-usbdevice} commandline option
1790 or the @code{usb_add} monitor command.  Available devices are:
1792 @table @code
1793 @item mouse
1794 Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
1795 @item tablet
1796 Pointer device that uses absolute coordinates (like a touchscreen).
1797 This means qemu is able to report the mouse position without having
1798 to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
1799 @item disk:@var{file}
1800 Mass storage device based on @var{file} (@pxref{disk_images})
1801 @item host:@var{bus.addr}
1802 Pass through the host device identified by @var{bus.addr}
1803 (Linux only)
1804 @item host:@var{vendor_id:product_id}
1805 Pass through the host device identified by @var{vendor_id:product_id}
1806 (Linux only)
1807 @item wacom-tablet
1808 Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
1809 above but it can be used with the tslib library because in addition to touch
1810 coordinates it reports touch pressure.
1811 @item keyboard
1812 Standard USB keyboard.  Will override the PS/2 keyboard (if present).
1813 @item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
1814 Serial converter. This emulates an FTDI FT232BM chip connected to host character
1815 device @var{dev}. The available character devices are the same as for the
1816 @code{-serial} option. The @code{vendorid} and @code{productid} options can be
1817 used to override the default 0403:6001. For instance, 
1818 @example
1819 usb_add serial:productid=FA00:tcp:192.168.0.2:4444
1820 @end example
1821 will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
1822 serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
1823 @item braille
1824 Braille device.  This will use BrlAPI to display the braille output on a real
1825 or fake device.
1826 @item net:@var{options}
1827 Network adapter that supports CDC ethernet and RNDIS protocols.  @var{options}
1828 specifies NIC options as with @code{-net nic,}@var{options} (see description).
1829 For instance, user-mode networking can be used with
1830 @example
1831 qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
1832 @end example
1833 Currently this cannot be used in machines that support PCI NICs.
1834 @item bt[:@var{hci-type}]
1835 Bluetooth dongle whose type is specified in the same format as with
1836 the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
1837 no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
1838 This USB device implements the USB Transport Layer of HCI.  Example
1839 usage:
1840 @example
1841 qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
1842 @end example
1843 @end table
1845 @node host_usb_devices
1846 @subsection Using host USB devices on a Linux host
1848 WARNING: this is an experimental feature. QEMU will slow down when
1849 using it. USB devices requiring real time streaming (i.e. USB Video
1850 Cameras) are not supported yet.
1852 @enumerate
1853 @item If you use an early Linux 2.4 kernel, verify that no Linux driver
1854 is actually using the USB device. A simple way to do that is simply to
1855 disable the corresponding kernel module by renaming it from @file{mydriver.o}
1856 to @file{mydriver.o.disabled}.
1858 @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1859 @example
1860 ls /proc/bus/usb
1861 001  devices  drivers
1862 @end example
1864 @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:
1865 @example
1866 chown -R myuid /proc/bus/usb
1867 @end example
1869 @item Launch QEMU and do in the monitor:
1870 @example
1871 info usbhost
1872   Device 1.2, speed 480 Mb/s
1873     Class 00: USB device 1234:5678, USB DISK
1874 @end example
1875 You should see the list of the devices you can use (Never try to use
1876 hubs, it won't work).
1878 @item Add the device in QEMU by using:
1879 @example
1880 usb_add host:1234:5678
1881 @end example
1883 Normally the guest OS should report that a new USB device is
1884 plugged. You can use the option @option{-usbdevice} to do the same.
1886 @item Now you can try to use the host USB device in QEMU.
1888 @end enumerate
1890 When relaunching QEMU, you may have to unplug and plug again the USB
1891 device to make it work again (this is a bug).
1893 @node vnc_security
1894 @section VNC security
1896 The VNC server capability provides access to the graphical console
1897 of the guest VM across the network. This has a number of security
1898 considerations depending on the deployment scenarios.
1900 @menu
1901 * vnc_sec_none::
1902 * vnc_sec_password::
1903 * vnc_sec_certificate::
1904 * vnc_sec_certificate_verify::
1905 * vnc_sec_certificate_pw::
1906 * vnc_generate_cert::
1907 @end menu
1908 @node vnc_sec_none
1909 @subsection Without passwords
1911 The simplest VNC server setup does not include any form of authentication.
1912 For this setup it is recommended to restrict it to listen on a UNIX domain
1913 socket only. For example
1915 @example
1916 qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1917 @end example
1919 This ensures that only users on local box with read/write access to that
1920 path can access the VNC server. To securely access the VNC server from a
1921 remote machine, a combination of netcat+ssh can be used to provide a secure
1922 tunnel.
1924 @node vnc_sec_password
1925 @subsection With passwords
1927 The VNC protocol has limited support for password based authentication. Since
1928 the protocol limits passwords to 8 characters it should not be considered
1929 to provide high security. The password can be fairly easily brute-forced by
1930 a client making repeat connections. For this reason, a VNC server using password
1931 authentication should be restricted to only listen on the loopback interface
1932 or UNIX domain sockets. Password authentication is requested with the @code{password}
1933 option, and then once QEMU is running the password is set with the monitor. Until
1934 the monitor is used to set the password all clients will be rejected.
1936 @example
1937 qemu [...OPTIONS...] -vnc :1,password -monitor stdio
1938 (qemu) change vnc password
1939 Password: ********
1940 (qemu)
1941 @end example
1943 @node vnc_sec_certificate
1944 @subsection With x509 certificates
1946 The QEMU VNC server also implements the VeNCrypt extension allowing use of
1947 TLS for encryption of the session, and x509 certificates for authentication.
1948 The use of x509 certificates is strongly recommended, because TLS on its
1949 own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1950 support provides a secure session, but no authentication. This allows any
1951 client to connect, and provides an encrypted session.
1953 @example
1954 qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1955 @end example
1957 In the above example @code{/etc/pki/qemu} should contain at least three files,
1958 @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1959 users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1960 NB the @code{server-key.pem} file should be protected with file mode 0600 to
1961 only be readable by the user owning it.
1963 @node vnc_sec_certificate_verify
1964 @subsection With x509 certificates and client verification
1966 Certificates can also provide a means to authenticate the client connecting.
1967 The server will request that the client provide a certificate, which it will
1968 then validate against the CA certificate. This is a good choice if deploying
1969 in an environment with a private internal certificate authority.
1971 @example
1972 qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1973 @end example
1976 @node vnc_sec_certificate_pw
1977 @subsection With x509 certificates, client verification and passwords
1979 Finally, the previous method can be combined with VNC password authentication
1980 to provide two layers of authentication for clients.
1982 @example
1983 qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1984 (qemu) change vnc password
1985 Password: ********
1986 (qemu)
1987 @end example
1989 @node vnc_generate_cert
1990 @subsection Generating certificates for VNC
1992 The GNU TLS packages provides a command called @code{certtool} which can
1993 be used to generate certificates and keys in PEM format. At a minimum it
1994 is neccessary to setup a certificate authority, and issue certificates to
1995 each server. If using certificates for authentication, then each client
1996 will also need to be issued a certificate. The recommendation is for the
1997 server to keep its certificates in either @code{/etc/pki/qemu} or for
1998 unprivileged users in @code{$HOME/.pki/qemu}.
2000 @menu
2001 * vnc_generate_ca::
2002 * vnc_generate_server::
2003 * vnc_generate_client::
2004 @end menu
2005 @node vnc_generate_ca
2006 @subsubsection Setup the Certificate Authority
2008 This step only needs to be performed once per organization / organizational
2009 unit. First the CA needs a private key. This key must be kept VERY secret
2010 and secure. If this key is compromised the entire trust chain of the certificates
2011 issued with it is lost.
2013 @example
2014 # certtool --generate-privkey > ca-key.pem
2015 @end example
2017 A CA needs to have a public certificate. For simplicity it can be a self-signed
2018 certificate, or one issue by a commercial certificate issuing authority. To
2019 generate a self-signed certificate requires one core piece of information, the
2020 name of the organization.
2022 @example
2023 # cat > ca.info <<EOF
2024 cn = Name of your organization
2026 cert_signing_key
2028 # certtool --generate-self-signed \
2029            --load-privkey ca-key.pem
2030            --template ca.info \
2031            --outfile ca-cert.pem
2032 @end example
2034 The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
2035 TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
2037 @node vnc_generate_server
2038 @subsubsection Issuing server certificates
2040 Each server (or host) needs to be issued with a key and certificate. When connecting
2041 the certificate is sent to the client which validates it against the CA certificate.
2042 The core piece of information for a server certificate is the hostname. This should
2043 be the fully qualified hostname that the client will connect with, since the client
2044 will typically also verify the hostname in the certificate. On the host holding the
2045 secure CA private key:
2047 @example
2048 # cat > server.info <<EOF
2049 organization = Name  of your organization
2050 cn = server.foo.example.com
2051 tls_www_server
2052 encryption_key
2053 signing_key
2055 # certtool --generate-privkey > server-key.pem
2056 # certtool --generate-certificate \
2057            --load-ca-certificate ca-cert.pem \
2058            --load-ca-privkey ca-key.pem \
2059            --load-privkey server server-key.pem \
2060            --template server.info \
2061            --outfile server-cert.pem
2062 @end example
2064 The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
2065 to the server for which they were generated. The @code{server-key.pem} is security
2066 sensitive and should be kept protected with file mode 0600 to prevent disclosure.
2068 @node vnc_generate_client
2069 @subsubsection Issuing client certificates
2071 If the QEMU VNC server is to use the @code{x509verify} option to validate client
2072 certificates as its authentication mechanism, each client also needs to be issued
2073 a certificate. The client certificate contains enough metadata to uniquely identify
2074 the client, typically organization, state, city, building, etc. On the host holding
2075 the secure CA private key:
2077 @example
2078 # cat > client.info <<EOF
2079 country = GB
2080 state = London
2081 locality = London
2082 organiazation = Name of your organization
2083 cn = client.foo.example.com
2084 tls_www_client
2085 encryption_key
2086 signing_key
2088 # certtool --generate-privkey > client-key.pem
2089 # certtool --generate-certificate \
2090            --load-ca-certificate ca-cert.pem \
2091            --load-ca-privkey ca-key.pem \
2092            --load-privkey client-key.pem \
2093            --template client.info \
2094            --outfile client-cert.pem
2095 @end example
2097 The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
2098 copied to the client for which they were generated.
2100 @node gdb_usage
2101 @section GDB usage
2103 QEMU has a primitive support to work with gdb, so that you can do
2104 'Ctrl-C' while the virtual machine is running and inspect its state.
2106 In order to use gdb, launch qemu with the '-s' option. It will wait for a
2107 gdb connection:
2108 @example
2109 > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
2110        -append "root=/dev/hda"
2111 Connected to host network interface: tun0
2112 Waiting gdb connection on port 1234
2113 @end example
2115 Then launch gdb on the 'vmlinux' executable:
2116 @example
2117 > gdb vmlinux
2118 @end example
2120 In gdb, connect to QEMU:
2121 @example
2122 (gdb) target remote localhost:1234
2123 @end example
2125 Then you can use gdb normally. For example, type 'c' to launch the kernel:
2126 @example
2127 (gdb) c
2128 @end example
2130 Here are some useful tips in order to use gdb on system code:
2132 @enumerate
2133 @item
2134 Use @code{info reg} to display all the CPU registers.
2135 @item
2136 Use @code{x/10i $eip} to display the code at the PC position.
2137 @item
2138 Use @code{set architecture i8086} to dump 16 bit code. Then use
2139 @code{x/10i $cs*16+$eip} to dump the code at the PC position.
2140 @end enumerate
2142 Advanced debugging options:
2144 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:
2145 @table @code
2146 @item maintenance packet qqemu.sstepbits
2148 This will display the MASK bits used to control the single stepping IE:
2149 @example
2150 (gdb) maintenance packet qqemu.sstepbits
2151 sending: "qqemu.sstepbits"
2152 received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
2153 @end example
2154 @item maintenance packet qqemu.sstep
2156 This will display the current value of the mask used when single stepping IE:
2157 @example
2158 (gdb) maintenance packet qqemu.sstep
2159 sending: "qqemu.sstep"
2160 received: "0x7"
2161 @end example
2162 @item maintenance packet Qqemu.sstep=HEX_VALUE
2164 This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
2165 @example
2166 (gdb) maintenance packet Qqemu.sstep=0x5
2167 sending: "qemu.sstep=0x5"
2168 received: "OK"
2169 @end example
2170 @end table
2172 @node pcsys_os_specific
2173 @section Target OS specific information
2175 @subsection Linux
2177 To have access to SVGA graphic modes under X11, use the @code{vesa} or
2178 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
2179 color depth in the guest and the host OS.
2181 When using a 2.6 guest Linux kernel, you should add the option
2182 @code{clock=pit} on the kernel command line because the 2.6 Linux
2183 kernels make very strict real time clock checks by default that QEMU
2184 cannot simulate exactly.
2186 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
2187 not activated because QEMU is slower with this patch. The QEMU
2188 Accelerator Module is also much slower in this case. Earlier Fedora
2189 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
2190 patch by default. Newer kernels don't have it.
2192 @subsection Windows
2194 If you have a slow host, using Windows 95 is better as it gives the
2195 best speed. Windows 2000 is also a good choice.
2197 @subsubsection SVGA graphic modes support
2199 QEMU emulates a Cirrus Logic GD5446 Video
2200 card. All Windows versions starting from Windows 95 should recognize
2201 and use this graphic card. For optimal performances, use 16 bit color
2202 depth in the guest and the host OS.
2204 If you are using Windows XP as guest OS and if you want to use high
2205 resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
2206 1280x1024x16), then you should use the VESA VBE virtual graphic card
2207 (option @option{-std-vga}).
2209 @subsubsection CPU usage reduction
2211 Windows 9x does not correctly use the CPU HLT
2212 instruction. The result is that it takes host CPU cycles even when
2213 idle. You can install the utility from
2214 @url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
2215 problem. Note that no such tool is needed for NT, 2000 or XP.
2217 @subsubsection Windows 2000 disk full problem
2219 Windows 2000 has a bug which gives a disk full problem during its
2220 installation. When installing it, use the @option{-win2k-hack} QEMU
2221 option to enable a specific workaround. After Windows 2000 is
2222 installed, you no longer need this option (this option slows down the
2223 IDE transfers).
2225 @subsubsection Windows 2000 shutdown
2227 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
2228 can. It comes from the fact that Windows 2000 does not automatically
2229 use the APM driver provided by the BIOS.
2231 In order to correct that, do the following (thanks to Struan
2232 Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
2233 Add/Troubleshoot a device => Add a new device & Next => No, select the
2234 hardware from a list & Next => NT Apm/Legacy Support & Next => Next
2235 (again) a few times. Now the driver is installed and Windows 2000 now
2236 correctly instructs QEMU to shutdown at the appropriate moment.
2238 @subsubsection Share a directory between Unix and Windows
2240 See @ref{sec_invocation} about the help of the option @option{-smb}.
2242 @subsubsection Windows XP security problem
2244 Some releases of Windows XP install correctly but give a security
2245 error when booting:
2246 @example
2247 A problem is preventing Windows from accurately checking the
2248 license for this computer. Error code: 0x800703e6.
2249 @end example
2251 The workaround is to install a service pack for XP after a boot in safe
2252 mode. Then reboot, and the problem should go away. Since there is no
2253 network while in safe mode, its recommended to download the full
2254 installation of SP1 or SP2 and transfer that via an ISO or using the
2255 vvfat block device ("-hdb fat:directory_which_holds_the_SP").
2257 @subsection MS-DOS and FreeDOS
2259 @subsubsection CPU usage reduction
2261 DOS does not correctly use the CPU HLT instruction. The result is that
2262 it takes host CPU cycles even when idle. You can install the utility
2263 from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
2264 problem.
2266 @node QEMU System emulator for non PC targets
2267 @chapter QEMU System emulator for non PC targets
2269 QEMU is a generic emulator and it emulates many non PC
2270 machines. Most of the options are similar to the PC emulator. The
2271 differences are mentioned in the following sections.
2273 @menu
2274 * QEMU PowerPC System emulator::
2275 * Sparc32 System emulator::
2276 * Sparc64 System emulator::
2277 * MIPS System emulator::
2278 * ARM System emulator::
2279 * ColdFire System emulator::
2280 @end menu
2282 @node QEMU PowerPC System emulator
2283 @section QEMU PowerPC System emulator
2285 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
2286 or PowerMac PowerPC system.
2288 QEMU emulates the following PowerMac peripherals:
2290 @itemize @minus
2291 @item
2292 UniNorth PCI Bridge
2293 @item
2294 PCI VGA compatible card with VESA Bochs Extensions
2295 @item
2296 2 PMAC IDE interfaces with hard disk and CD-ROM support
2297 @item
2298 NE2000 PCI adapters
2299 @item
2300 Non Volatile RAM
2301 @item
2302 VIA-CUDA with ADB keyboard and mouse.
2303 @end itemize
2305 QEMU emulates the following PREP peripherals:
2307 @itemize @minus
2308 @item
2309 PCI Bridge
2310 @item
2311 PCI VGA compatible card with VESA Bochs Extensions
2312 @item
2313 2 IDE interfaces with hard disk and CD-ROM support
2314 @item
2315 Floppy disk
2316 @item
2317 NE2000 network adapters
2318 @item
2319 Serial port
2320 @item
2321 PREP Non Volatile RAM
2322 @item
2323 PC compatible keyboard and mouse.
2324 @end itemize
2326 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
2327 @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
2329 @c man begin OPTIONS
2331 The following options are specific to the PowerPC emulation:
2333 @table @option
2335 @item -g WxH[xDEPTH]
2337 Set the initial VGA graphic mode. The default is 800x600x15.
2339 @end table
2341 @c man end
2344 More information is available at
2345 @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
2347 @node Sparc32 System emulator
2348 @section Sparc32 System emulator
2350 Use the executable @file{qemu-system-sparc} to simulate the following
2351 Sun4m architecture machines:
2352 @itemize @minus
2353 @item
2354 SPARCstation 4
2355 @item
2356 SPARCstation 5
2357 @item
2358 SPARCstation 10
2359 @item
2360 SPARCstation 20
2361 @item
2362 SPARCserver 600MP
2363 @item
2364 SPARCstation LX
2365 @item
2366 SPARCstation Voyager
2367 @item
2368 SPARCclassic
2369 @item
2370 SPARCbook
2371 @end itemize
2373 The emulation is somewhat complete. SMP up to 16 CPUs is supported,
2374 but Linux limits the number of usable CPUs to 4.
2376 It's also possible to simulate a SPARCstation 2 (sun4c architecture),
2377 SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
2378 emulators are not usable yet.
2380 QEMU emulates the following sun4m/sun4c/sun4d peripherals:
2382 @itemize @minus
2383 @item
2384 IOMMU or IO-UNITs
2385 @item
2386 TCX Frame buffer
2387 @item
2388 Lance (Am7990) Ethernet
2389 @item
2390 Non Volatile RAM M48T02/M48T08
2391 @item
2392 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2393 and power/reset logic
2394 @item
2395 ESP SCSI controller with hard disk and CD-ROM support
2396 @item
2397 Floppy drive (not on SS-600MP)
2398 @item
2399 CS4231 sound device (only on SS-5, not working yet)
2400 @end itemize
2402 The number of peripherals is fixed in the architecture.  Maximum
2403 memory size depends on the machine type, for SS-5 it is 256MB and for
2404 others 2047MB.
2406 Since version 0.8.2, QEMU uses OpenBIOS
2407 @url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
2408 firmware implementation. The goal is to implement a 100% IEEE
2409 1275-1994 (referred to as Open Firmware) compliant firmware.
2411 A sample Linux 2.6 series kernel and ram disk image are available on
2412 the QEMU web site. There are still issues with NetBSD and OpenBSD, but
2413 some kernel versions work. Please note that currently Solaris kernels
2414 don't work probably due to interface issues between OpenBIOS and
2415 Solaris.
2417 @c man begin OPTIONS
2419 The following options are specific to the Sparc32 emulation:
2421 @table @option
2423 @item -g WxHx[xDEPTH]
2425 Set the initial TCX graphic mode. The default is 1024x768x8, currently
2426 the only other possible mode is 1024x768x24.
2428 @item -prom-env string
2430 Set OpenBIOS variables in NVRAM, for example:
2432 @example
2433 qemu-system-sparc -prom-env 'auto-boot?=false' \
2434  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2435 @end example
2437 @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic|SPARCbook|SS-2|SS-1000|SS-2000]
2439 Set the emulated machine type. Default is SS-5.
2441 @end table
2443 @c man end
2445 @node Sparc64 System emulator
2446 @section Sparc64 System emulator
2448 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
2449 (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
2450 Niagara (T1) machine. The emulator is not usable for anything yet, but
2451 it can launch some kernels.
2453 QEMU emulates the following peripherals:
2455 @itemize @minus
2456 @item
2457 UltraSparc IIi APB PCI Bridge
2458 @item
2459 PCI VGA compatible card with VESA Bochs Extensions
2460 @item
2461 PS/2 mouse and keyboard
2462 @item
2463 Non Volatile RAM M48T59
2464 @item
2465 PC-compatible serial ports
2466 @item
2467 2 PCI IDE interfaces with hard disk and CD-ROM support
2468 @item
2469 Floppy disk
2470 @end itemize
2472 @c man begin OPTIONS
2474 The following options are specific to the Sparc64 emulation:
2476 @table @option
2478 @item -prom-env string
2480 Set OpenBIOS variables in NVRAM, for example:
2482 @example
2483 qemu-system-sparc64 -prom-env 'auto-boot?=false'
2484 @end example
2486 @item -M [sun4u|sun4v|Niagara]
2488 Set the emulated machine type. The default is sun4u.
2490 @end table
2492 @c man end
2494 @node MIPS System emulator
2495 @section MIPS System emulator
2497 Four executables cover simulation of 32 and 64-bit MIPS systems in
2498 both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2499 @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
2500 Five different machine types are emulated:
2502 @itemize @minus
2503 @item
2504 A generic ISA PC-like machine "mips"
2505 @item
2506 The MIPS Malta prototype board "malta"
2507 @item
2508 An ACER Pica "pica61". This machine needs the 64-bit emulator.
2509 @item
2510 MIPS emulator pseudo board "mipssim"
2511 @item
2512 A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
2513 @end itemize
2515 The generic emulation is supported by Debian 'Etch' and is able to
2516 install Debian into a virtual disk image. The following devices are
2517 emulated:
2519 @itemize @minus
2520 @item
2521 A range of MIPS CPUs, default is the 24Kf
2522 @item
2523 PC style serial port
2524 @item
2525 PC style IDE disk
2526 @item
2527 NE2000 network card
2528 @end itemize
2530 The Malta emulation supports the following devices:
2532 @itemize @minus
2533 @item
2534 Core board with MIPS 24Kf CPU and Galileo system controller
2535 @item
2536 PIIX4 PCI/USB/SMbus controller
2537 @item
2538 The Multi-I/O chip's serial device
2539 @item
2540 PCnet32 PCI network card
2541 @item
2542 Malta FPGA serial device
2543 @item
2544 Cirrus VGA graphics card
2545 @end itemize
2547 The ACER Pica emulation supports:
2549 @itemize @minus
2550 @item
2551 MIPS R4000 CPU
2552 @item
2553 PC-style IRQ and DMA controllers
2554 @item
2555 PC Keyboard
2556 @item
2557 IDE controller
2558 @end itemize
2560 The mipssim pseudo board emulation provides an environment similiar
2561 to what the proprietary MIPS emulator uses for running Linux.
2562 It supports:
2564 @itemize @minus
2565 @item
2566 A range of MIPS CPUs, default is the 24Kf
2567 @item
2568 PC style serial port
2569 @item
2570 MIPSnet network emulation
2571 @end itemize
2573 The MIPS Magnum R4000 emulation supports:
2575 @itemize @minus
2576 @item
2577 MIPS R4000 CPU
2578 @item
2579 PC-style IRQ controller
2580 @item
2581 PC Keyboard
2582 @item
2583 SCSI controller
2584 @item
2585 G364 framebuffer
2586 @end itemize
2589 @node ARM System emulator
2590 @section ARM System emulator
2592 Use the executable @file{qemu-system-arm} to simulate a ARM
2593 machine. The ARM Integrator/CP board is emulated with the following
2594 devices:
2596 @itemize @minus
2597 @item
2598 ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
2599 @item
2600 Two PL011 UARTs
2601 @item
2602 SMC 91c111 Ethernet adapter
2603 @item
2604 PL110 LCD controller
2605 @item
2606 PL050 KMI with PS/2 keyboard and mouse.
2607 @item
2608 PL181 MultiMedia Card Interface with SD card.
2609 @end itemize
2611 The ARM Versatile baseboard is emulated with the following devices:
2613 @itemize @minus
2614 @item
2615 ARM926E, ARM1136 or Cortex-A8 CPU
2616 @item
2617 PL190 Vectored Interrupt Controller
2618 @item
2619 Four PL011 UARTs
2620 @item
2621 SMC 91c111 Ethernet adapter
2622 @item
2623 PL110 LCD controller
2624 @item
2625 PL050 KMI with PS/2 keyboard and mouse.
2626 @item
2627 PCI host bridge.  Note the emulated PCI bridge only provides access to
2628 PCI memory space.  It does not provide access to PCI IO space.
2629 This means some devices (eg. ne2k_pci NIC) are not usable, and others
2630 (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
2631 mapped control registers.
2632 @item
2633 PCI OHCI USB controller.
2634 @item
2635 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
2636 @item
2637 PL181 MultiMedia Card Interface with SD card.
2638 @end itemize
2640 The ARM RealView Emulation baseboard is emulated with the following devices:
2642 @itemize @minus
2643 @item
2644 ARM926E, ARM1136, ARM11MPCORE(x4) or Cortex-A8 CPU
2645 @item
2646 ARM AMBA Generic/Distributed Interrupt Controller
2647 @item
2648 Four PL011 UARTs
2649 @item
2650 SMC 91c111 Ethernet adapter
2651 @item
2652 PL110 LCD controller
2653 @item
2654 PL050 KMI with PS/2 keyboard and mouse
2655 @item
2656 PCI host bridge
2657 @item
2658 PCI OHCI USB controller
2659 @item
2660 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
2661 @item
2662 PL181 MultiMedia Card Interface with SD card.
2663 @end itemize
2665 The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2666 and "Terrier") emulation includes the following peripherals:
2668 @itemize @minus
2669 @item
2670 Intel PXA270 System-on-chip (ARM V5TE core)
2671 @item
2672 NAND Flash memory
2673 @item
2674 IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2675 @item
2676 On-chip OHCI USB controller
2677 @item
2678 On-chip LCD controller
2679 @item
2680 On-chip Real Time Clock
2681 @item
2682 TI ADS7846 touchscreen controller on SSP bus
2683 @item
2684 Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2685 @item
2686 GPIO-connected keyboard controller and LEDs
2687 @item
2688 Secure Digital card connected to PXA MMC/SD host
2689 @item
2690 Three on-chip UARTs
2691 @item
2692 WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2693 @end itemize
2695 The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2696 following elements:
2698 @itemize @minus
2699 @item
2700 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2701 @item
2702 ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2703 @item
2704 On-chip LCD controller
2705 @item
2706 On-chip Real Time Clock
2707 @item
2708 TI TSC2102i touchscreen controller / analog-digital converter / Audio
2709 CODEC, connected through MicroWire and I@math{^2}S busses
2710 @item
2711 GPIO-connected matrix keypad
2712 @item
2713 Secure Digital card connected to OMAP MMC/SD host
2714 @item
2715 Three on-chip UARTs
2716 @end itemize
2718 Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2719 emulation supports the following elements:
2721 @itemize @minus
2722 @item
2723 Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2724 @item
2725 RAM and non-volatile OneNAND Flash memories
2726 @item
2727 Display connected to EPSON remote framebuffer chip and OMAP on-chip
2728 display controller and a LS041y3 MIPI DBI-C controller
2729 @item
2730 TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2731 driven through SPI bus
2732 @item
2733 National Semiconductor LM8323-controlled qwerty keyboard driven
2734 through I@math{^2}C bus
2735 @item
2736 Secure Digital card connected to OMAP MMC/SD host
2737 @item
2738 Three OMAP on-chip UARTs and on-chip STI debugging console
2739 @item
2740 A Bluetooth(R) transciever and HCI connected to an UART
2741 @item
2742 Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2743 TUSB6010 chip - only USB host mode is supported
2744 @item
2745 TI TMP105 temperature sensor driven through I@math{^2}C bus
2746 @item
2747 TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2748 @item
2749 Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2750 through CBUS
2751 @end itemize
2753 The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2754 devices:
2756 @itemize @minus
2757 @item
2758 Cortex-M3 CPU core.
2759 @item
2760 64k Flash and 8k SRAM.
2761 @item
2762 Timers, UARTs, ADC and I@math{^2}C interface.
2763 @item
2764 OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2765 @end itemize
2767 The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2768 devices:
2770 @itemize @minus
2771 @item
2772 Cortex-M3 CPU core.
2773 @item
2774 256k Flash and 64k SRAM.
2775 @item
2776 Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2777 @item
2778 OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2779 @end itemize
2781 The Freecom MusicPal internet radio emulation includes the following
2782 elements:
2784 @itemize @minus
2785 @item
2786 Marvell MV88W8618 ARM core.
2787 @item
2788 32 MB RAM, 256 KB SRAM, 8 MB flash.
2789 @item
2790 Up to 2 16550 UARTs
2791 @item
2792 MV88W8xx8 Ethernet controller
2793 @item
2794 MV88W8618 audio controller, WM8750 CODEC and mixer
2795 @item
2796 128×64 display with brightness control
2797 @item
2798 2 buttons, 2 navigation wheels with button function
2799 @end itemize
2801 A Linux 2.6 test image is available on the QEMU web site. More
2802 information is available in the QEMU mailing-list archive.
2804 @node ColdFire System emulator
2805 @section ColdFire System emulator
2807 Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2808 The emulator is able to boot a uClinux kernel.
2810 The M5208EVB emulation includes the following devices:
2812 @itemize @minus
2813 @item
2814 MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2815 @item
2816 Three Two on-chip UARTs.
2817 @item
2818 Fast Ethernet Controller (FEC)
2819 @end itemize
2821 The AN5206 emulation includes the following devices:
2823 @itemize @minus
2824 @item
2825 MCF5206 ColdFire V2 Microprocessor.
2826 @item
2827 Two on-chip UARTs.
2828 @end itemize
2830 @node QEMU User space emulator
2831 @chapter QEMU User space emulator
2833 @menu
2834 * Supported Operating Systems ::
2835 * Linux User space emulator::
2836 * Mac OS X/Darwin User space emulator ::
2837 * BSD User space emulator ::
2838 @end menu
2840 @node Supported Operating Systems
2841 @section Supported Operating Systems
2843 The following OS are supported in user space emulation:
2845 @itemize @minus
2846 @item
2847 Linux (referred as qemu-linux-user)
2848 @item
2849 Mac OS X/Darwin (referred as qemu-darwin-user)
2850 @item
2851 BSD (referred as qemu-bsd-user)
2852 @end itemize
2854 @node Linux User space emulator
2855 @section Linux User space emulator
2857 @menu
2858 * Quick Start::
2859 * Wine launch::
2860 * Command line options::
2861 * Other binaries::
2862 @end menu
2864 @node Quick Start
2865 @subsection Quick Start
2867 In order to launch a Linux process, QEMU needs the process executable
2868 itself and all the target (x86) dynamic libraries used by it.
2870 @itemize
2872 @item On x86, you can just try to launch any process by using the native
2873 libraries:
2875 @example
2876 qemu-i386 -L / /bin/ls
2877 @end example
2879 @code{-L /} tells that the x86 dynamic linker must be searched with a
2880 @file{/} prefix.
2882 @item Since QEMU is also a linux process, you can launch qemu with
2883 qemu (NOTE: you can only do that if you compiled QEMU from the sources):
2885 @example
2886 qemu-i386 -L / qemu-i386 -L / /bin/ls
2887 @end example
2889 @item On non x86 CPUs, you need first to download at least an x86 glibc
2890 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2891 @code{LD_LIBRARY_PATH} is not set:
2893 @example
2894 unset LD_LIBRARY_PATH
2895 @end example
2897 Then you can launch the precompiled @file{ls} x86 executable:
2899 @example
2900 qemu-i386 tests/i386/ls
2901 @end example
2902 You can look at @file{qemu-binfmt-conf.sh} so that
2903 QEMU is automatically launched by the Linux kernel when you try to
2904 launch x86 executables. It requires the @code{binfmt_misc} module in the
2905 Linux kernel.
2907 @item The x86 version of QEMU is also included. You can try weird things such as:
2908 @example
2909 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2910           /usr/local/qemu-i386/bin/ls-i386
2911 @end example
2913 @end itemize
2915 @node Wine launch
2916 @subsection Wine launch
2918 @itemize
2920 @item Ensure that you have a working QEMU with the x86 glibc
2921 distribution (see previous section). In order to verify it, you must be
2922 able to do:
2924 @example
2925 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2926 @end example
2928 @item Download the binary x86 Wine install
2929 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2931 @item Configure Wine on your account. Look at the provided script
2932 @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2933 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2935 @item Then you can try the example @file{putty.exe}:
2937 @example
2938 qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2939           /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2940 @end example
2942 @end itemize
2944 @node Command line options
2945 @subsection Command line options
2947 @example
2948 usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] program [arguments...]
2949 @end example
2951 @table @option
2952 @item -h
2953 Print the help
2954 @item -L path
2955 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2956 @item -s size
2957 Set the x86 stack size in bytes (default=524288)
2958 @item -cpu model
2959 Select CPU model (-cpu ? for list and additional feature selection)
2960 @end table
2962 Debug options:
2964 @table @option
2965 @item -d
2966 Activate log (logfile=/tmp/qemu.log)
2967 @item -p pagesize
2968 Act as if the host page size was 'pagesize' bytes
2969 @item -g port
2970 Wait gdb connection to port
2971 @end table
2973 Environment variables:
2975 @table @env
2976 @item QEMU_STRACE
2977 Print system calls and arguments similar to the 'strace' program
2978 (NOTE: the actual 'strace' program will not work because the user
2979 space emulator hasn't implemented ptrace).  At the moment this is
2980 incomplete.  All system calls that don't have a specific argument
2981 format are printed with information for six arguments.  Many
2982 flag-style arguments don't have decoders and will show up as numbers.
2983 @end table
2985 @node Other binaries
2986 @subsection Other binaries
2988 @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2989 binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2990 configurations), and arm-uclinux bFLT format binaries.
2992 @command{qemu-m68k} is capable of running semihosted binaries using the BDM
2993 (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2994 coldfire uClinux bFLT format binaries.
2996 The binary format is detected automatically.
2998 @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
3000 @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
3001 (Sparc64 CPU, 32 bit ABI).
3003 @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
3004 SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
3006 @node Mac OS X/Darwin User space emulator
3007 @section Mac OS X/Darwin User space emulator
3009 @menu
3010 * Mac OS X/Darwin Status::
3011 * Mac OS X/Darwin Quick Start::
3012 * Mac OS X/Darwin Command line options::
3013 @end menu
3015 @node Mac OS X/Darwin Status
3016 @subsection Mac OS X/Darwin Status
3018 @itemize @minus
3019 @item
3020 target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
3021 @item
3022 target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
3023 @item
3024 target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
3025 @item
3026 target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
3027 @end itemize
3029 [1] If you're host commpage can be executed by qemu.
3031 @node Mac OS X/Darwin Quick Start
3032 @subsection Quick Start
3034 In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
3035 itself and all the target dynamic libraries used by it. If you don't have the FAT
3036 libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
3037 CD or compile them by hand.
3039 @itemize
3041 @item On x86, you can just try to launch any process by using the native
3042 libraries:
3044 @example
3045 qemu-i386 /bin/ls
3046 @end example
3048 or to run the ppc version of the executable:
3050 @example
3051 qemu-ppc /bin/ls
3052 @end example
3054 @item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
3055 are installed:
3057 @example
3058 qemu-i386 -L /opt/x86_root/ /bin/ls
3059 @end example
3061 @code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
3062 @file{/opt/x86_root/usr/bin/dyld}.
3064 @end itemize
3066 @node Mac OS X/Darwin Command line options
3067 @subsection Command line options
3069 @example
3070 usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
3071 @end example
3073 @table @option
3074 @item -h
3075 Print the help
3076 @item -L path
3077 Set the library root path (default=/)
3078 @item -s size
3079 Set the stack size in bytes (default=524288)
3080 @end table
3082 Debug options:
3084 @table @option
3085 @item -d
3086 Activate log (logfile=/tmp/qemu.log)
3087 @item -p pagesize
3088 Act as if the host page size was 'pagesize' bytes
3089 @end table
3091 @node BSD User space emulator
3092 @section BSD User space emulator
3094 @menu
3095 * BSD Status::
3096 * BSD Quick Start::
3097 * BSD Command line options::
3098 @end menu
3100 @node BSD Status
3101 @subsection BSD Status
3103 @itemize @minus
3104 @item
3105 target Sparc64 on Sparc64: Some trivial programs work.
3106 @end itemize
3108 @node BSD Quick Start
3109 @subsection Quick Start
3111 In order to launch a BSD process, QEMU needs the process executable
3112 itself and all the target dynamic libraries used by it.
3114 @itemize
3116 @item On Sparc64, you can just try to launch any process by using the native
3117 libraries:
3119 @example
3120 qemu-sparc64 /bin/ls
3121 @end example
3123 @end itemize
3125 @node BSD Command line options
3126 @subsection Command line options
3128 @example
3129 usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
3130 @end example
3132 @table @option
3133 @item -h
3134 Print the help
3135 @item -L path
3136 Set the library root path (default=/)
3137 @item -s size
3138 Set the stack size in bytes (default=524288)
3139 @item -bsd type
3140 Set the type of the emulated BSD Operating system. Valid values are
3141 FreeBSD, NetBSD and OpenBSD (default).
3142 @end table
3144 Debug options:
3146 @table @option
3147 @item -d
3148 Activate log (logfile=/tmp/qemu.log)
3149 @item -p pagesize
3150 Act as if the host page size was 'pagesize' bytes
3151 @end table
3153 @node compilation
3154 @chapter Compilation from the sources
3156 @menu
3157 * Linux/Unix::
3158 * Windows::
3159 * Cross compilation for Windows with Linux::
3160 * Mac OS X::
3161 @end menu
3163 @node Linux/Unix
3164 @section Linux/Unix
3166 @subsection Compilation
3168 First you must decompress the sources:
3169 @example
3170 cd /tmp
3171 tar zxvf qemu-x.y.z.tar.gz
3172 cd qemu-x.y.z
3173 @end example
3175 Then you configure QEMU and build it (usually no options are needed):
3176 @example
3177 ./configure
3178 make
3179 @end example
3181 Then type as root user:
3182 @example
3183 make install
3184 @end example
3185 to install QEMU in @file{/usr/local}.
3187 @subsection GCC version
3189 In order to compile QEMU successfully, it is very important that you
3190 have the right tools. The most important one is gcc. On most hosts and
3191 in particular on x86 ones, @emph{gcc 4.x is not supported}. If your
3192 Linux distribution includes a gcc 4.x compiler, you can usually
3193 install an older version (it is invoked by @code{gcc32} or
3194 @code{gcc34}). The QEMU configure script automatically probes for
3195 these older versions so that usually you don't have to do anything.
3197 @node Windows
3198 @section Windows
3200 @itemize
3201 @item Install the current versions of MSYS and MinGW from
3202 @url{http://www.mingw.org/}. You can find detailed installation
3203 instructions in the download section and the FAQ.
3205 @item Download
3206 the MinGW development library of SDL 1.2.x
3207 (@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
3208 @url{http://www.libsdl.org}. Unpack it in a temporary place, and
3209 unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
3210 directory. Edit the @file{sdl-config} script so that it gives the
3211 correct SDL directory when invoked.
3213 @item Extract the current version of QEMU.
3215 @item Start the MSYS shell (file @file{msys.bat}).
3217 @item Change to the QEMU directory. Launch @file{./configure} and
3218 @file{make}.  If you have problems using SDL, verify that
3219 @file{sdl-config} can be launched from the MSYS command line.
3221 @item You can install QEMU in @file{Program Files/Qemu} by typing
3222 @file{make install}. Don't forget to copy @file{SDL.dll} in
3223 @file{Program Files/Qemu}.
3225 @end itemize
3227 @node Cross compilation for Windows with Linux
3228 @section Cross compilation for Windows with Linux
3230 @itemize
3231 @item
3232 Install the MinGW cross compilation tools available at
3233 @url{http://www.mingw.org/}.
3235 @item
3236 Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
3237 unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
3238 variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
3239 the QEMU configuration script.
3241 @item
3242 Configure QEMU for Windows cross compilation:
3243 @example
3244 ./configure --enable-mingw32
3245 @end example
3246 If necessary, you can change the cross-prefix according to the prefix
3247 chosen for the MinGW tools with --cross-prefix. You can also use
3248 --prefix to set the Win32 install path.
3250 @item You can install QEMU in the installation directory by typing
3251 @file{make install}. Don't forget to copy @file{SDL.dll} in the
3252 installation directory.
3254 @end itemize
3256 Note: Currently, Wine does not seem able to launch
3257 QEMU for Win32.
3259 @node Mac OS X
3260 @section Mac OS X
3262 The Mac OS X patches are not fully merged in QEMU, so you should look
3263 at the QEMU mailing list archive to have all the necessary
3264 information.
3266 @node Index
3267 @chapter Index
3268 @printindex cp
3270 @bye