Introducing qcow2 extensions (Uri Lublin)
[qemu-kvm/fedora.git] / qemu-doc.texi
blob61a08eeae9521166ca2bb0bbcb84866e6302c488
1 \input texinfo @c -*- texinfo -*-
2 @c %**start of header
3 @setfilename qemu-doc.info
4 @settitle QEMU Emulator User Documentation
5 @exampleindent 0
6 @paragraphindent 0
7 @c %**end of header
9 @iftex
10 @titlepage
11 @sp 7
12 @center @titlefont{QEMU Emulator}
13 @sp 1
14 @center @titlefont{User Documentation}
15 @sp 3
16 @end titlepage
17 @end iftex
19 @ifnottex
20 @node Top
21 @top
23 @menu
24 * Introduction::
25 * Installation::
26 * QEMU PC System emulator::
27 * QEMU System emulator for non PC targets::
28 * QEMU User space emulator::
29 * compilation:: Compilation from the sources
30 * Index::
31 @end menu
32 @end ifnottex
34 @contents
36 @node Introduction
37 @chapter Introduction
39 @menu
40 * intro_features:: Features
41 @end menu
43 @node intro_features
44 @section Features
46 QEMU is a FAST! processor emulator using dynamic translation to
47 achieve good emulation speed.
49 QEMU has two operating modes:
51 @itemize @minus
53 @item
54 Full system emulation. In this mode, QEMU emulates a full system (for
55 example a PC), including one or several processors and various
56 peripherals. It can be used to launch different Operating Systems
57 without rebooting the PC or to debug system code.
59 @item
60 User mode emulation. In this mode, QEMU can launch
61 processes compiled for one CPU on another CPU. It can be used to
62 launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
63 to ease cross-compilation and cross-debugging.
65 @end itemize
67 QEMU can run without an host kernel driver and yet gives acceptable
68 performance.
70 For system emulation, the following hardware targets are supported:
71 @itemize
72 @item PC (x86 or x86_64 processor)
73 @item ISA PC (old style PC without PCI bus)
74 @item PREP (PowerPC processor)
75 @item G3 Beige PowerMac (PowerPC processor)
76 @item Mac99 PowerMac (PowerPC processor, in progress)
77 @item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
78 @item Sun4u/Sun4v (64-bit Sparc processor, in progress)
79 @item Malta board (32-bit and 64-bit MIPS processors)
80 @item MIPS Magnum (64-bit MIPS processor)
81 @item ARM Integrator/CP (ARM)
82 @item ARM Versatile baseboard (ARM)
83 @item ARM RealView Emulation baseboard (ARM)
84 @item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
85 @item Luminary Micro LM3S811EVB (ARM Cortex-M3)
86 @item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
87 @item Freescale MCF5208EVB (ColdFire V2).
88 @item Arnewsh MCF5206 evaluation board (ColdFire V2).
89 @item Palm Tungsten|E PDA (OMAP310 processor)
90 @item N800 and N810 tablets (OMAP2420 processor)
91 @item MusicPal (MV88W8618 ARM processor)
92 @item Gumstix "Connex" and "Verdex" motherboards (PXA255/270).
93 @item Siemens SX1 smartphone (OMAP310 processor)
94 @end itemize
96 For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
98 @node Installation
99 @chapter Installation
101 If you want to compile QEMU yourself, see @ref{compilation}.
103 @menu
104 * install_linux::   Linux
105 * install_windows:: Windows
106 * install_mac::     Macintosh
107 @end menu
109 @node install_linux
110 @section Linux
112 If a precompiled package is available for your distribution - you just
113 have to install it. Otherwise, see @ref{compilation}.
115 @node install_windows
116 @section Windows
118 Download the experimental binary installer at
119 @url{http://www.free.oszoo.org/@/download.html}.
121 @node install_mac
122 @section Mac OS X
124 Download the experimental binary installer at
125 @url{http://www.free.oszoo.org/@/download.html}.
127 @node QEMU PC System emulator
128 @chapter QEMU PC System emulator
130 @menu
131 * pcsys_introduction:: Introduction
132 * pcsys_quickstart::   Quick Start
133 * sec_invocation::     Invocation
134 * pcsys_keys::         Keys
135 * pcsys_monitor::      QEMU Monitor
136 * disk_images::        Disk Images
137 * pcsys_network::      Network emulation
138 * direct_linux_boot::  Direct Linux Boot
139 * pcsys_usb::          USB emulation
140 * vnc_security::       VNC security
141 * gdb_usage::          GDB usage
142 * pcsys_os_specific::  Target OS specific information
143 @end menu
145 @node pcsys_introduction
146 @section Introduction
148 @c man begin DESCRIPTION
150 The QEMU PC System emulator simulates the
151 following peripherals:
153 @itemize @minus
154 @item
155 i440FX host PCI bridge and PIIX3 PCI to ISA bridge
156 @item
157 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
158 extensions (hardware level, including all non standard modes).
159 @item
160 PS/2 mouse and keyboard
161 @item
162 2 PCI IDE interfaces with hard disk and CD-ROM support
163 @item
164 Floppy disk
165 @item
166 PCI/ISA PCI network adapters
167 @item
168 Serial ports
169 @item
170 Creative SoundBlaster 16 sound card
171 @item
172 ENSONIQ AudioPCI ES1370 sound card
173 @item
174 Intel 82801AA AC97 Audio compatible sound card
175 @item
176 Adlib(OPL2) - Yamaha YM3812 compatible chip
177 @item
178 Gravis Ultrasound GF1 sound card
179 @item
180 CS4231A compatible sound card
181 @item
182 PCI UHCI USB controller and a virtual USB hub.
183 @end itemize
185 SMP is supported with up to 255 CPUs.
187 Note that adlib, gus and cs4231a are only available when QEMU was
188 configured with --audio-card-list option containing the name(s) of
189 required card(s).
191 QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
192 VGA BIOS.
194 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
196 QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
197 by Tibor "TS" Schütz.
199 CS4231A is the chip used in Windows Sound System and GUSMAX products
201 @c man end
203 @node pcsys_quickstart
204 @section Quick Start
206 Download and uncompress the linux image (@file{linux.img}) and type:
208 @example
209 qemu linux.img
210 @end example
212 Linux should boot and give you a prompt.
214 @node sec_invocation
215 @section Invocation
217 @example
218 @c man begin SYNOPSIS
219 usage: qemu [options] [@var{disk_image}]
220 @c man end
221 @end example
223 @c man begin OPTIONS
224 @var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
225 targets do not need a disk image.
227 @include qemu-options.texi
229 @c man end
231 @node pcsys_keys
232 @section Keys
234 @c man begin OPTIONS
236 During the graphical emulation, you can use the following keys:
237 @table @key
238 @item Ctrl-Alt-f
239 Toggle full screen
241 @item Ctrl-Alt-n
242 Switch to virtual console 'n'. Standard console mappings are:
243 @table @emph
244 @item 1
245 Target system display
246 @item 2
247 Monitor
248 @item 3
249 Serial port
250 @end table
252 @item Ctrl-Alt
253 Toggle mouse and keyboard grab.
254 @end table
256 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
257 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
259 During emulation, if you are using the @option{-nographic} option, use
260 @key{Ctrl-a h} to get terminal commands:
262 @table @key
263 @item Ctrl-a h
264 @item Ctrl-a ?
265 Print this help
266 @item Ctrl-a x
267 Exit emulator
268 @item Ctrl-a s
269 Save disk data back to file (if -snapshot)
270 @item Ctrl-a t
271 Toggle console timestamps
272 @item Ctrl-a b
273 Send break (magic sysrq in Linux)
274 @item Ctrl-a c
275 Switch between console and monitor
276 @item Ctrl-a Ctrl-a
277 Send Ctrl-a
278 @end table
279 @c man end
281 @ignore
283 @c man begin SEEALSO
284 The HTML documentation of QEMU for more precise information and Linux
285 user mode emulator invocation.
286 @c man end
288 @c man begin AUTHOR
289 Fabrice Bellard
290 @c man end
292 @end ignore
294 @node pcsys_monitor
295 @section QEMU Monitor
297 The QEMU monitor is used to give complex commands to the QEMU
298 emulator. You can use it to:
300 @itemize @minus
302 @item
303 Remove or insert removable media images
304 (such as CD-ROM or floppies).
306 @item
307 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
308 from a disk file.
310 @item Inspect the VM state without an external debugger.
312 @end itemize
314 @subsection Commands
316 The following commands are available:
318 @table @option
320 @item help or ? [@var{cmd}]
321 Show the help for all commands or just for command @var{cmd}.
323 @item commit
324 Commit changes to the disk images (if -snapshot is used).
326 @item info @var{subcommand}
327 Show various information about the system state.
329 @table @option
330 @item info version
331 show the version of QEMU
332 @item info network
333 show the various VLANs and the associated devices
334 @item info chardev
335 show the character devices
336 @item info block
337 show the block devices
338 @item info block
339 show block device statistics
340 @item info registers
341 show the cpu registers
342 @item info cpus
343 show infos for each CPU
344 @item info history
345 show the command line history
346 @item info irq
347 show the interrupts statistics (if available)
348 @item info pic
349 show i8259 (PIC) state
350 @item info pci
351 show emulated PCI device info
352 @item info tlb
353 show virtual to physical memory mappings (i386 only)
354 @item info mem
355 show the active virtual memory mappings (i386 only)
356 @item info hpet
357 show state of HPET (i386 only)
358 @item info kqemu
359 show KQEMU information
360 @item info kvm
361 show KVM information
362 @item info usb
363 show USB devices plugged on the virtual USB hub
364 @item info usbhost
365 show all USB host devices
366 @item info profile
367 show profiling information
368 @item info capture
369 show information about active capturing
370 @item info snapshots
371 show list of VM snapshots
372 @item info status
373 show the current VM status (running|paused)
374 @item info pcmcia
375 show guest PCMCIA status
376 @item info mice
377 show which guest mouse is receiving events
378 @item info vnc
379 show the vnc server status
380 @item info name
381 show the current VM name
382 @item info uuid
383 show the current VM UUID
384 @item info cpustats
385 show CPU statistics
386 @item info slirp
387 show SLIRP statistics (if available)
388 @item info migrate
389 show migration status
390 @item info balloon
391 show balloon information
392 @end table
394 @item q or quit
395 Quit the emulator.
397 @item eject [-f] @var{device}
398 Eject a removable medium (use -f to force it).
400 @item change @var{device} @var{setting}
402 Change the configuration of a device.
404 @table @option
405 @item change @var{diskdevice} @var{filename} [@var{format}]
406 Change the medium for a removable disk device to point to @var{filename}. eg
408 @example
409 (qemu) change ide1-cd0 /path/to/some.iso
410 @end example
412 @var{format} is optional.
414 @item change vnc @var{display},@var{options}
415 Change the configuration of the VNC server. The valid syntax for @var{display}
416 and @var{options} are described at @ref{sec_invocation}. eg
418 @example
419 (qemu) change vnc localhost:1
420 @end example
422 @item change vnc password [@var{password}]
424 Change the password associated with the VNC server. If the new password is not
425 supplied, the monitor will prompt for it to be entered. VNC passwords are only
426 significant up to 8 letters. eg
428 @example
429 (qemu) change vnc password
430 Password: ********
431 @end example
433 @end table
435 @item acl @var{subcommand} @var{aclname} @var{match} @var{index}
437 Manage access control lists for network services. There are currently
438 two named access control lists, @var{vnc.x509dname} and @var{vnc.username}
439 matching on the x509 client certificate distinguished name, and SASL
440 username respectively.
442 @table @option
443 @item acl show <aclname>
444 list all the match rules in the access control list, and the default
445 policy
446 @item acl policy <aclname> @code{allow|deny}
447 set the default access control list policy, used in the event that
448 none of the explicit rules match. The default policy at startup is
449 always @code{deny}
450 @item acl allow <aclname> <match> [<index>]
451 add a match to the access control list, allowing access. The match will
452 normally be an exact username or x509 distinguished name, but can
453 optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to allow
454 all users in the @code{EXAMPLE.COM} kerberos realm. The match will
455 normally be appended to the end of the ACL, but can be inserted
456 earlier in the list if the optional @code{index} parameter is supplied.
457 @item acl deny <aclname> <match> [<index>]
458 add a match to the access control list, denying access. The match will
459 normally be an exact username or x509 distinguished name, but can
460 optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to allow
461 all users in the @code{EXAMPLE.COM} kerberos realm. The match will
462 normally be appended to the end of the ACL, but can be inserted
463 earlier in the list if the optional @code{index} parameter is supplied.
464 @item acl remove <aclname> <match>
465 remove the specified match rule from the access control list.
466 @item acl reset <aclname>
467 remove all matches from the access control list, and set the default
468 policy back to @code{deny}.
469 @end table
471 @item screendump @var{filename}
472 Save screen into PPM image @var{filename}.
474 @item logfile @var{filename}
475 Output logs to @var{filename}.
477 @item log @var{item1}[,...]
478 Activate logging of the specified items to @file{/tmp/qemu.log}.
480 @item savevm [@var{tag}|@var{id}]
481 Create a snapshot of the whole virtual machine. If @var{tag} is
482 provided, it is used as human readable identifier. If there is already
483 a snapshot with the same tag or ID, it is replaced. More info at
484 @ref{vm_snapshots}.
486 @item loadvm @var{tag}|@var{id}
487 Set the whole virtual machine to the snapshot identified by the tag
488 @var{tag} or the unique snapshot ID @var{id}.
490 @item delvm @var{tag}|@var{id}
491 Delete the snapshot identified by @var{tag} or @var{id}.
493 @item stop
494 Stop emulation.
496 @item c or cont
497 Resume emulation.
499 @item gdbserver [@var{port}]
500 Start gdbserver session (default @var{port}=1234)
502 @item x/fmt @var{addr}
503 Virtual memory dump starting at @var{addr}.
505 @item xp /@var{fmt} @var{addr}
506 Physical memory dump starting at @var{addr}.
508 @var{fmt} is a format which tells the command how to format the
509 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
511 @table @var
512 @item count
513 is the number of items to be dumped.
515 @item format
516 can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
517 c (char) or i (asm instruction).
519 @item size
520 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
521 @code{h} or @code{w} can be specified with the @code{i} format to
522 respectively select 16 or 32 bit code instruction size.
524 @end table
526 Examples:
527 @itemize
528 @item
529 Dump 10 instructions at the current instruction pointer:
530 @example
531 (qemu) x/10i $eip
532 0x90107063:  ret
533 0x90107064:  sti
534 0x90107065:  lea    0x0(%esi,1),%esi
535 0x90107069:  lea    0x0(%edi,1),%edi
536 0x90107070:  ret
537 0x90107071:  jmp    0x90107080
538 0x90107073:  nop
539 0x90107074:  nop
540 0x90107075:  nop
541 0x90107076:  nop
542 @end example
544 @item
545 Dump 80 16 bit values at the start of the video memory.
546 @smallexample
547 (qemu) xp/80hx 0xb8000
548 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
549 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
550 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
551 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
552 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
553 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
554 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
555 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
556 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
557 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
558 @end smallexample
559 @end itemize
561 @item p or print/@var{fmt} @var{expr}
563 Print expression value. Only the @var{format} part of @var{fmt} is
564 used.
566 @item sendkey @var{keys}
568 Send @var{keys} to the emulator. @var{keys} could be the name of the
569 key or @code{#} followed by the raw value in either decimal or hexadecimal
570 format. Use @code{-} to press several keys simultaneously. Example:
571 @example
572 sendkey ctrl-alt-f1
573 @end example
575 This command is useful to send keys that your graphical user interface
576 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
578 @item system_reset
580 Reset the system.
582 @item system_powerdown
584 Power down the system (if supported).
586 @item sum @var{addr} @var{size}
588 Compute the checksum of a memory region.
590 @item usb_add @var{devname}
592 Add the USB device @var{devname}.  For details of available devices see
593 @ref{usb_devices}
595 @item usb_del @var{devname}
597 Remove the USB device @var{devname} from the QEMU virtual USB
598 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
599 command @code{info usb} to see the devices you can remove.
601 @item mouse_move @var{dx} @var{dy} [@var{dz}]
602 Move the active mouse to the specified coordinates @var{dx} @var{dy}
603 with optional scroll axis @var{dz}.
605 @item mouse_button @var{val}
606 Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
608 @item mouse_set @var{index}
609 Set which mouse device receives events at given @var{index}, index
610 can be obtained with
611 @example
612 info mice
613 @end example
615 @item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
616 Capture audio into @var{filename}. Using sample rate @var{frequency}
617 bits per sample @var{bits} and number of channels @var{channels}.
619 Defaults:
620 @itemize @minus
621 @item Sample rate = 44100 Hz - CD quality
622 @item Bits = 16
623 @item Number of channels = 2 - Stereo
624 @end itemize
626 @item stopcapture @var{index}
627 Stop capture with a given @var{index}, index can be obtained with
628 @example
629 info capture
630 @end example
632 @item memsave @var{addr} @var{size} @var{file}
633 save to disk virtual memory dump starting at @var{addr} of size @var{size}.
635 @item pmemsave @var{addr} @var{size} @var{file}
636 save to disk physical memory dump starting at @var{addr} of size @var{size}.
638 @item boot_set @var{bootdevicelist}
640 Define new values for the boot device list. Those values will override
641 the values specified on the command line through the @code{-boot} option.
643 The values that can be specified here depend on the machine type, but are
644 the same that can be specified in the @code{-boot} command line option.
646 @item nmi @var{cpu}
647 Inject an NMI on the given CPU.
649 @item migrate [-d] @var{uri}
650 Migrate to @var{uri} (using -d to not wait for completion).
652 @item migrate_cancel
653 Cancel the current VM migration.
655 @item migrate_set_speed @var{value}
656 Set maximum speed to @var{value} (in bytes) for migrations.
658 @item balloon @var{value}
659 Request VM to change its memory allocation to @var{value} (in MB).
661 @item set_link @var{name} [up|down]
662 Set link @var{name} up or down.
664 @end table
666 @subsection Integer expressions
668 The monitor understands integers expressions for every integer
669 argument. You can use register names to get the value of specifics
670 CPU registers by prefixing them with @emph{$}.
672 @node disk_images
673 @section Disk Images
675 Since version 0.6.1, QEMU supports many disk image formats, including
676 growable disk images (their size increase as non empty sectors are
677 written), compressed and encrypted disk images. Version 0.8.3 added
678 the new qcow2 disk image format which is essential to support VM
679 snapshots.
681 @menu
682 * disk_images_quickstart::    Quick start for disk image creation
683 * disk_images_snapshot_mode:: Snapshot mode
684 * vm_snapshots::              VM snapshots
685 * qemu_img_invocation::       qemu-img Invocation
686 * qemu_nbd_invocation::       qemu-nbd Invocation
687 * host_drives::               Using host drives
688 * disk_images_fat_images::    Virtual FAT disk images
689 * disk_images_nbd::           NBD access
690 @end menu
692 @node disk_images_quickstart
693 @subsection Quick start for disk image creation
695 You can create a disk image with the command:
696 @example
697 qemu-img create myimage.img mysize
698 @end example
699 where @var{myimage.img} is the disk image filename and @var{mysize} is its
700 size in kilobytes. You can add an @code{M} suffix to give the size in
701 megabytes and a @code{G} suffix for gigabytes.
703 See @ref{qemu_img_invocation} for more information.
705 @node disk_images_snapshot_mode
706 @subsection Snapshot mode
708 If you use the option @option{-snapshot}, all disk images are
709 considered as read only. When sectors in written, they are written in
710 a temporary file created in @file{/tmp}. You can however force the
711 write back to the raw disk images by using the @code{commit} monitor
712 command (or @key{C-a s} in the serial console).
714 @node vm_snapshots
715 @subsection VM snapshots
717 VM snapshots are snapshots of the complete virtual machine including
718 CPU state, RAM, device state and the content of all the writable
719 disks. In order to use VM snapshots, you must have at least one non
720 removable and writable block device using the @code{qcow2} disk image
721 format. Normally this device is the first virtual hard drive.
723 Use the monitor command @code{savevm} to create a new VM snapshot or
724 replace an existing one. A human readable name can be assigned to each
725 snapshot in addition to its numerical ID.
727 Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
728 a VM snapshot. @code{info snapshots} lists the available snapshots
729 with their associated information:
731 @example
732 (qemu) info snapshots
733 Snapshot devices: hda
734 Snapshot list (from hda):
735 ID        TAG                 VM SIZE                DATE       VM CLOCK
736 1         start                   41M 2006-08-06 12:38:02   00:00:14.954
737 2                                 40M 2006-08-06 12:43:29   00:00:18.633
738 3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
739 @end example
741 A VM snapshot is made of a VM state info (its size is shown in
742 @code{info snapshots}) and a snapshot of every writable disk image.
743 The VM state info is stored in the first @code{qcow2} non removable
744 and writable block device. The disk image snapshots are stored in
745 every disk image. The size of a snapshot in a disk image is difficult
746 to evaluate and is not shown by @code{info snapshots} because the
747 associated disk sectors are shared among all the snapshots to save
748 disk space (otherwise each snapshot would need a full copy of all the
749 disk images).
751 When using the (unrelated) @code{-snapshot} option
752 (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
753 but they are deleted as soon as you exit QEMU.
755 VM snapshots currently have the following known limitations:
756 @itemize
757 @item
758 They cannot cope with removable devices if they are removed or
759 inserted after a snapshot is done.
760 @item
761 A few device drivers still have incomplete snapshot support so their
762 state is not saved or restored properly (in particular USB).
763 @end itemize
765 @node qemu_img_invocation
766 @subsection @code{qemu-img} Invocation
768 @include qemu-img.texi
770 @node qemu_nbd_invocation
771 @subsection @code{qemu-nbd} Invocation
773 @include qemu-nbd.texi
775 @node host_drives
776 @subsection Using host drives
778 In addition to disk image files, QEMU can directly access host
779 devices. We describe here the usage for QEMU version >= 0.8.3.
781 @subsubsection Linux
783 On Linux, you can directly use the host device filename instead of a
784 disk image filename provided you have enough privileges to access
785 it. For example, use @file{/dev/cdrom} to access to the CDROM or
786 @file{/dev/fd0} for the floppy.
788 @table @code
789 @item CD
790 You can specify a CDROM device even if no CDROM is loaded. QEMU has
791 specific code to detect CDROM insertion or removal. CDROM ejection by
792 the guest OS is supported. Currently only data CDs are supported.
793 @item Floppy
794 You can specify a floppy device even if no floppy is loaded. Floppy
795 removal is currently not detected accurately (if you change floppy
796 without doing floppy access while the floppy is not loaded, the guest
797 OS will think that the same floppy is loaded).
798 @item Hard disks
799 Hard disks can be used. Normally you must specify the whole disk
800 (@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
801 see it as a partitioned disk. WARNING: unless you know what you do, it
802 is better to only make READ-ONLY accesses to the hard disk otherwise
803 you may corrupt your host data (use the @option{-snapshot} command
804 line option or modify the device permissions accordingly).
805 @end table
807 @subsubsection Windows
809 @table @code
810 @item CD
811 The preferred syntax is the drive letter (e.g. @file{d:}). The
812 alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
813 supported as an alias to the first CDROM drive.
815 Currently there is no specific code to handle removable media, so it
816 is better to use the @code{change} or @code{eject} monitor commands to
817 change or eject media.
818 @item Hard disks
819 Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
820 where @var{N} is the drive number (0 is the first hard disk).
822 WARNING: unless you know what you do, it is better to only make
823 READ-ONLY accesses to the hard disk otherwise you may corrupt your
824 host data (use the @option{-snapshot} command line so that the
825 modifications are written in a temporary file).
826 @end table
829 @subsubsection Mac OS X
831 @file{/dev/cdrom} is an alias to the first CDROM.
833 Currently there is no specific code to handle removable media, so it
834 is better to use the @code{change} or @code{eject} monitor commands to
835 change or eject media.
837 @node disk_images_fat_images
838 @subsection Virtual FAT disk images
840 QEMU can automatically create a virtual FAT disk image from a
841 directory tree. In order to use it, just type:
843 @example
844 qemu linux.img -hdb fat:/my_directory
845 @end example
847 Then you access access to all the files in the @file{/my_directory}
848 directory without having to copy them in a disk image or to export
849 them via SAMBA or NFS. The default access is @emph{read-only}.
851 Floppies can be emulated with the @code{:floppy:} option:
853 @example
854 qemu linux.img -fda fat:floppy:/my_directory
855 @end example
857 A read/write support is available for testing (beta stage) with the
858 @code{:rw:} option:
860 @example
861 qemu linux.img -fda fat:floppy:rw:/my_directory
862 @end example
864 What you should @emph{never} do:
865 @itemize
866 @item use non-ASCII filenames ;
867 @item use "-snapshot" together with ":rw:" ;
868 @item expect it to work when loadvm'ing ;
869 @item write to the FAT directory on the host system while accessing it with the guest system.
870 @end itemize
872 @node disk_images_nbd
873 @subsection NBD access
875 QEMU can access directly to block device exported using the Network Block Device
876 protocol.
878 @example
879 qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
880 @end example
882 If the NBD server is located on the same host, you can use an unix socket instead
883 of an inet socket:
885 @example
886 qemu linux.img -hdb nbd:unix:/tmp/my_socket
887 @end example
889 In this case, the block device must be exported using qemu-nbd:
891 @example
892 qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
893 @end example
895 The use of qemu-nbd allows to share a disk between several guests:
896 @example
897 qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
898 @end example
900 and then you can use it with two guests:
901 @example
902 qemu linux1.img -hdb nbd:unix:/tmp/my_socket
903 qemu linux2.img -hdb nbd:unix:/tmp/my_socket
904 @end example
906 @node pcsys_network
907 @section Network emulation
909 QEMU can simulate several network cards (PCI or ISA cards on the PC
910 target) and can connect them to an arbitrary number of Virtual Local
911 Area Networks (VLANs). Host TAP devices can be connected to any QEMU
912 VLAN. VLAN can be connected between separate instances of QEMU to
913 simulate large networks. For simpler usage, a non privileged user mode
914 network stack can replace the TAP device to have a basic network
915 connection.
917 @subsection VLANs
919 QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
920 connection between several network devices. These devices can be for
921 example QEMU virtual Ethernet cards or virtual Host ethernet devices
922 (TAP devices).
924 @subsection Using TAP network interfaces
926 This is the standard way to connect QEMU to a real network. QEMU adds
927 a virtual network device on your host (called @code{tapN}), and you
928 can then configure it as if it was a real ethernet card.
930 @subsubsection Linux host
932 As an example, you can download the @file{linux-test-xxx.tar.gz}
933 archive and copy the script @file{qemu-ifup} in @file{/etc} and
934 configure properly @code{sudo} so that the command @code{ifconfig}
935 contained in @file{qemu-ifup} can be executed as root. You must verify
936 that your host kernel supports the TAP network interfaces: the
937 device @file{/dev/net/tun} must be present.
939 See @ref{sec_invocation} to have examples of command lines using the
940 TAP network interfaces.
942 @subsubsection Windows host
944 There is a virtual ethernet driver for Windows 2000/XP systems, called
945 TAP-Win32. But it is not included in standard QEMU for Windows,
946 so you will need to get it separately. It is part of OpenVPN package,
947 so download OpenVPN from : @url{http://openvpn.net/}.
949 @subsection Using the user mode network stack
951 By using the option @option{-net user} (default configuration if no
952 @option{-net} option is specified), QEMU uses a completely user mode
953 network stack (you don't need root privilege to use the virtual
954 network). The virtual network configuration is the following:
956 @example
958          QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
959                            |          (10.0.2.2)
960                            |
961                            ---->  DNS server (10.0.2.3)
962                            |
963                            ---->  SMB server (10.0.2.4)
964 @end example
966 The QEMU VM behaves as if it was behind a firewall which blocks all
967 incoming connections. You can use a DHCP client to automatically
968 configure the network in the QEMU VM. The DHCP server assign addresses
969 to the hosts starting from 10.0.2.15.
971 In order to check that the user mode network is working, you can ping
972 the address 10.0.2.2 and verify that you got an address in the range
973 10.0.2.x from the QEMU virtual DHCP server.
975 Note that @code{ping} is not supported reliably to the internet as it
976 would require root privileges. It means you can only ping the local
977 router (10.0.2.2).
979 When using the built-in TFTP server, the router is also the TFTP
980 server.
982 When using the @option{-redir} option, TCP or UDP connections can be
983 redirected from the host to the guest. It allows for example to
984 redirect X11, telnet or SSH connections.
986 @subsection Connecting VLANs between QEMU instances
988 Using the @option{-net socket} option, it is possible to make VLANs
989 that span several QEMU instances. See @ref{sec_invocation} to have a
990 basic example.
992 @node direct_linux_boot
993 @section Direct Linux Boot
995 This section explains how to launch a Linux kernel inside QEMU without
996 having to make a full bootable image. It is very useful for fast Linux
997 kernel testing.
999 The syntax is:
1000 @example
1001 qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1002 @end example
1004 Use @option{-kernel} to provide the Linux kernel image and
1005 @option{-append} to give the kernel command line arguments. The
1006 @option{-initrd} option can be used to provide an INITRD image.
1008 When using the direct Linux boot, a disk image for the first hard disk
1009 @file{hda} is required because its boot sector is used to launch the
1010 Linux kernel.
1012 If you do not need graphical output, you can disable it and redirect
1013 the virtual serial port and the QEMU monitor to the console with the
1014 @option{-nographic} option. The typical command line is:
1015 @example
1016 qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1017      -append "root=/dev/hda console=ttyS0" -nographic
1018 @end example
1020 Use @key{Ctrl-a c} to switch between the serial console and the
1021 monitor (@pxref{pcsys_keys}).
1023 @node pcsys_usb
1024 @section USB emulation
1026 QEMU emulates a PCI UHCI USB controller. You can virtually plug
1027 virtual USB devices or real host USB devices (experimental, works only
1028 on Linux hosts).  Qemu will automatically create and connect virtual USB hubs
1029 as necessary to connect multiple USB devices.
1031 @menu
1032 * usb_devices::
1033 * host_usb_devices::
1034 @end menu
1035 @node usb_devices
1036 @subsection Connecting USB devices
1038 USB devices can be connected with the @option{-usbdevice} commandline option
1039 or the @code{usb_add} monitor command.  Available devices are:
1041 @table @code
1042 @item mouse
1043 Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
1044 @item tablet
1045 Pointer device that uses absolute coordinates (like a touchscreen).
1046 This means qemu is able to report the mouse position without having
1047 to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
1048 @item disk:@var{file}
1049 Mass storage device based on @var{file} (@pxref{disk_images})
1050 @item host:@var{bus.addr}
1051 Pass through the host device identified by @var{bus.addr}
1052 (Linux only)
1053 @item host:@var{vendor_id:product_id}
1054 Pass through the host device identified by @var{vendor_id:product_id}
1055 (Linux only)
1056 @item wacom-tablet
1057 Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
1058 above but it can be used with the tslib library because in addition to touch
1059 coordinates it reports touch pressure.
1060 @item keyboard
1061 Standard USB keyboard.  Will override the PS/2 keyboard (if present).
1062 @item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
1063 Serial converter. This emulates an FTDI FT232BM chip connected to host character
1064 device @var{dev}. The available character devices are the same as for the
1065 @code{-serial} option. The @code{vendorid} and @code{productid} options can be
1066 used to override the default 0403:6001. For instance, 
1067 @example
1068 usb_add serial:productid=FA00:tcp:192.168.0.2:4444
1069 @end example
1070 will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
1071 serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
1072 @item braille
1073 Braille device.  This will use BrlAPI to display the braille output on a real
1074 or fake device.
1075 @item net:@var{options}
1076 Network adapter that supports CDC ethernet and RNDIS protocols.  @var{options}
1077 specifies NIC options as with @code{-net nic,}@var{options} (see description).
1078 For instance, user-mode networking can be used with
1079 @example
1080 qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
1081 @end example
1082 Currently this cannot be used in machines that support PCI NICs.
1083 @item bt[:@var{hci-type}]
1084 Bluetooth dongle whose type is specified in the same format as with
1085 the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
1086 no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
1087 This USB device implements the USB Transport Layer of HCI.  Example
1088 usage:
1089 @example
1090 qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
1091 @end example
1092 @end table
1094 @node host_usb_devices
1095 @subsection Using host USB devices on a Linux host
1097 WARNING: this is an experimental feature. QEMU will slow down when
1098 using it. USB devices requiring real time streaming (i.e. USB Video
1099 Cameras) are not supported yet.
1101 @enumerate
1102 @item If you use an early Linux 2.4 kernel, verify that no Linux driver
1103 is actually using the USB device. A simple way to do that is simply to
1104 disable the corresponding kernel module by renaming it from @file{mydriver.o}
1105 to @file{mydriver.o.disabled}.
1107 @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1108 @example
1109 ls /proc/bus/usb
1110 001  devices  drivers
1111 @end example
1113 @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:
1114 @example
1115 chown -R myuid /proc/bus/usb
1116 @end example
1118 @item Launch QEMU and do in the monitor:
1119 @example
1120 info usbhost
1121   Device 1.2, speed 480 Mb/s
1122     Class 00: USB device 1234:5678, USB DISK
1123 @end example
1124 You should see the list of the devices you can use (Never try to use
1125 hubs, it won't work).
1127 @item Add the device in QEMU by using:
1128 @example
1129 usb_add host:1234:5678
1130 @end example
1132 Normally the guest OS should report that a new USB device is
1133 plugged. You can use the option @option{-usbdevice} to do the same.
1135 @item Now you can try to use the host USB device in QEMU.
1137 @end enumerate
1139 When relaunching QEMU, you may have to unplug and plug again the USB
1140 device to make it work again (this is a bug).
1142 @node vnc_security
1143 @section VNC security
1145 The VNC server capability provides access to the graphical console
1146 of the guest VM across the network. This has a number of security
1147 considerations depending on the deployment scenarios.
1149 @menu
1150 * vnc_sec_none::
1151 * vnc_sec_password::
1152 * vnc_sec_certificate::
1153 * vnc_sec_certificate_verify::
1154 * vnc_sec_certificate_pw::
1155 * vnc_sec_sasl::
1156 * vnc_sec_certificate_sasl::
1157 * vnc_generate_cert::
1158 * vnc_setup_sasl::
1159 @end menu
1160 @node vnc_sec_none
1161 @subsection Without passwords
1163 The simplest VNC server setup does not include any form of authentication.
1164 For this setup it is recommended to restrict it to listen on a UNIX domain
1165 socket only. For example
1167 @example
1168 qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1169 @end example
1171 This ensures that only users on local box with read/write access to that
1172 path can access the VNC server. To securely access the VNC server from a
1173 remote machine, a combination of netcat+ssh can be used to provide a secure
1174 tunnel.
1176 @node vnc_sec_password
1177 @subsection With passwords
1179 The VNC protocol has limited support for password based authentication. Since
1180 the protocol limits passwords to 8 characters it should not be considered
1181 to provide high security. The password can be fairly easily brute-forced by
1182 a client making repeat connections. For this reason, a VNC server using password
1183 authentication should be restricted to only listen on the loopback interface
1184 or UNIX domain sockets. Password authentication is requested with the @code{password}
1185 option, and then once QEMU is running the password is set with the monitor. Until
1186 the monitor is used to set the password all clients will be rejected.
1188 @example
1189 qemu [...OPTIONS...] -vnc :1,password -monitor stdio
1190 (qemu) change vnc password
1191 Password: ********
1192 (qemu)
1193 @end example
1195 @node vnc_sec_certificate
1196 @subsection With x509 certificates
1198 The QEMU VNC server also implements the VeNCrypt extension allowing use of
1199 TLS for encryption of the session, and x509 certificates for authentication.
1200 The use of x509 certificates is strongly recommended, because TLS on its
1201 own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1202 support provides a secure session, but no authentication. This allows any
1203 client to connect, and provides an encrypted session.
1205 @example
1206 qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1207 @end example
1209 In the above example @code{/etc/pki/qemu} should contain at least three files,
1210 @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1211 users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1212 NB the @code{server-key.pem} file should be protected with file mode 0600 to
1213 only be readable by the user owning it.
1215 @node vnc_sec_certificate_verify
1216 @subsection With x509 certificates and client verification
1218 Certificates can also provide a means to authenticate the client connecting.
1219 The server will request that the client provide a certificate, which it will
1220 then validate against the CA certificate. This is a good choice if deploying
1221 in an environment with a private internal certificate authority.
1223 @example
1224 qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1225 @end example
1228 @node vnc_sec_certificate_pw
1229 @subsection With x509 certificates, client verification and passwords
1231 Finally, the previous method can be combined with VNC password authentication
1232 to provide two layers of authentication for clients.
1234 @example
1235 qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1236 (qemu) change vnc password
1237 Password: ********
1238 (qemu)
1239 @end example
1242 @node vnc_sec_sasl
1243 @subsection With SASL authentication
1245 The SASL authentication method is a VNC extension, that provides an
1246 easily extendable, pluggable authentication method. This allows for
1247 integration with a wide range of authentication mechanisms, such as
1248 PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1249 The strength of the authentication depends on the exact mechanism
1250 configured. If the chosen mechanism also provides a SSF layer, then
1251 it will encrypt the datastream as well.
1253 Refer to the later docs on how to choose the exact SASL mechanism
1254 used for authentication, but assuming use of one supporting SSF,
1255 then QEMU can be launched with:
1257 @example
1258 qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio
1259 @end example
1261 @node vnc_sec_certificate_sasl
1262 @subsection With x509 certificates and SASL authentication
1264 If the desired SASL authentication mechanism does not supported
1265 SSF layers, then it is strongly advised to run it in combination
1266 with TLS and x509 certificates. This provides securely encrypted
1267 data stream, avoiding risk of compromising of the security
1268 credentials. This can be enabled, by combining the 'sasl' option
1269 with the aforementioned TLS + x509 options:
1271 @example
1272 qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
1273 @end example
1276 @node vnc_generate_cert
1277 @subsection Generating certificates for VNC
1279 The GNU TLS packages provides a command called @code{certtool} which can
1280 be used to generate certificates and keys in PEM format. At a minimum it
1281 is neccessary to setup a certificate authority, and issue certificates to
1282 each server. If using certificates for authentication, then each client
1283 will also need to be issued a certificate. The recommendation is for the
1284 server to keep its certificates in either @code{/etc/pki/qemu} or for
1285 unprivileged users in @code{$HOME/.pki/qemu}.
1287 @menu
1288 * vnc_generate_ca::
1289 * vnc_generate_server::
1290 * vnc_generate_client::
1291 @end menu
1292 @node vnc_generate_ca
1293 @subsubsection Setup the Certificate Authority
1295 This step only needs to be performed once per organization / organizational
1296 unit. First the CA needs a private key. This key must be kept VERY secret
1297 and secure. If this key is compromised the entire trust chain of the certificates
1298 issued with it is lost.
1300 @example
1301 # certtool --generate-privkey > ca-key.pem
1302 @end example
1304 A CA needs to have a public certificate. For simplicity it can be a self-signed
1305 certificate, or one issue by a commercial certificate issuing authority. To
1306 generate a self-signed certificate requires one core piece of information, the
1307 name of the organization.
1309 @example
1310 # cat > ca.info <<EOF
1311 cn = Name of your organization
1313 cert_signing_key
1315 # certtool --generate-self-signed \
1316            --load-privkey ca-key.pem
1317            --template ca.info \
1318            --outfile ca-cert.pem
1319 @end example
1321 The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1322 TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1324 @node vnc_generate_server
1325 @subsubsection Issuing server certificates
1327 Each server (or host) needs to be issued with a key and certificate. When connecting
1328 the certificate is sent to the client which validates it against the CA certificate.
1329 The core piece of information for a server certificate is the hostname. This should
1330 be the fully qualified hostname that the client will connect with, since the client
1331 will typically also verify the hostname in the certificate. On the host holding the
1332 secure CA private key:
1334 @example
1335 # cat > server.info <<EOF
1336 organization = Name  of your organization
1337 cn = server.foo.example.com
1338 tls_www_server
1339 encryption_key
1340 signing_key
1342 # certtool --generate-privkey > server-key.pem
1343 # certtool --generate-certificate \
1344            --load-ca-certificate ca-cert.pem \
1345            --load-ca-privkey ca-key.pem \
1346            --load-privkey server server-key.pem \
1347            --template server.info \
1348            --outfile server-cert.pem
1349 @end example
1351 The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1352 to the server for which they were generated. The @code{server-key.pem} is security
1353 sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1355 @node vnc_generate_client
1356 @subsubsection Issuing client certificates
1358 If the QEMU VNC server is to use the @code{x509verify} option to validate client
1359 certificates as its authentication mechanism, each client also needs to be issued
1360 a certificate. The client certificate contains enough metadata to uniquely identify
1361 the client, typically organization, state, city, building, etc. On the host holding
1362 the secure CA private key:
1364 @example
1365 # cat > client.info <<EOF
1366 country = GB
1367 state = London
1368 locality = London
1369 organiazation = Name of your organization
1370 cn = client.foo.example.com
1371 tls_www_client
1372 encryption_key
1373 signing_key
1375 # certtool --generate-privkey > client-key.pem
1376 # certtool --generate-certificate \
1377            --load-ca-certificate ca-cert.pem \
1378            --load-ca-privkey ca-key.pem \
1379            --load-privkey client-key.pem \
1380            --template client.info \
1381            --outfile client-cert.pem
1382 @end example
1384 The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1385 copied to the client for which they were generated.
1388 @node vnc_setup_sasl
1390 @subsection Configuring SASL mechanisms
1392 The following documentation assumes use of the Cyrus SASL implementation on a
1393 Linux host, but the principals should apply to any other SASL impl. When SASL
1394 is enabled, the mechanism configuration will be loaded from system default
1395 SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1396 unprivileged user, an environment variable SASL_CONF_PATH can be used
1397 to make it search alternate locations for the service config.
1399 The default configuration might contain
1401 @example
1402 mech_list: digest-md5
1403 sasldb_path: /etc/qemu/passwd.db
1404 @end example
1406 This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
1407 Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
1408 in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
1409 command. While this mechanism is easy to configure and use, it is not
1410 considered secure by modern standards, so only suitable for developers /
1411 ad-hoc testing.
1413 A more serious deployment might use Kerberos, which is done with the 'gssapi'
1414 mechanism
1416 @example
1417 mech_list: gssapi
1418 keytab: /etc/qemu/krb5.tab
1419 @end example
1421 For this to work the administrator of your KDC must generate a Kerberos
1422 principal for the server, with a name of  'qemu/somehost.example.com@@EXAMPLE.COM'
1423 replacing 'somehost.example.com' with the fully qualified host name of the
1424 machine running QEMU, and 'EXAMPLE.COM' with the Keberos Realm.
1426 Other configurations will be left as an exercise for the reader. It should
1427 be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
1428 encryption. For all other mechanisms, VNC should always be configured to
1429 use TLS and x509 certificates to protect security credentials from snooping.
1431 @node gdb_usage
1432 @section GDB usage
1434 QEMU has a primitive support to work with gdb, so that you can do
1435 'Ctrl-C' while the virtual machine is running and inspect its state.
1437 In order to use gdb, launch qemu with the '-s' option. It will wait for a
1438 gdb connection:
1439 @example
1440 > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1441        -append "root=/dev/hda"
1442 Connected to host network interface: tun0
1443 Waiting gdb connection on port 1234
1444 @end example
1446 Then launch gdb on the 'vmlinux' executable:
1447 @example
1448 > gdb vmlinux
1449 @end example
1451 In gdb, connect to QEMU:
1452 @example
1453 (gdb) target remote localhost:1234
1454 @end example
1456 Then you can use gdb normally. For example, type 'c' to launch the kernel:
1457 @example
1458 (gdb) c
1459 @end example
1461 Here are some useful tips in order to use gdb on system code:
1463 @enumerate
1464 @item
1465 Use @code{info reg} to display all the CPU registers.
1466 @item
1467 Use @code{x/10i $eip} to display the code at the PC position.
1468 @item
1469 Use @code{set architecture i8086} to dump 16 bit code. Then use
1470 @code{x/10i $cs*16+$eip} to dump the code at the PC position.
1471 @end enumerate
1473 Advanced debugging options:
1475 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:
1476 @table @code
1477 @item maintenance packet qqemu.sstepbits
1479 This will display the MASK bits used to control the single stepping IE:
1480 @example
1481 (gdb) maintenance packet qqemu.sstepbits
1482 sending: "qqemu.sstepbits"
1483 received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1484 @end example
1485 @item maintenance packet qqemu.sstep
1487 This will display the current value of the mask used when single stepping IE:
1488 @example
1489 (gdb) maintenance packet qqemu.sstep
1490 sending: "qqemu.sstep"
1491 received: "0x7"
1492 @end example
1493 @item maintenance packet Qqemu.sstep=HEX_VALUE
1495 This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1496 @example
1497 (gdb) maintenance packet Qqemu.sstep=0x5
1498 sending: "qemu.sstep=0x5"
1499 received: "OK"
1500 @end example
1501 @end table
1503 @node pcsys_os_specific
1504 @section Target OS specific information
1506 @subsection Linux
1508 To have access to SVGA graphic modes under X11, use the @code{vesa} or
1509 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1510 color depth in the guest and the host OS.
1512 When using a 2.6 guest Linux kernel, you should add the option
1513 @code{clock=pit} on the kernel command line because the 2.6 Linux
1514 kernels make very strict real time clock checks by default that QEMU
1515 cannot simulate exactly.
1517 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1518 not activated because QEMU is slower with this patch. The QEMU
1519 Accelerator Module is also much slower in this case. Earlier Fedora
1520 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1521 patch by default. Newer kernels don't have it.
1523 @subsection Windows
1525 If you have a slow host, using Windows 95 is better as it gives the
1526 best speed. Windows 2000 is also a good choice.
1528 @subsubsection SVGA graphic modes support
1530 QEMU emulates a Cirrus Logic GD5446 Video
1531 card. All Windows versions starting from Windows 95 should recognize
1532 and use this graphic card. For optimal performances, use 16 bit color
1533 depth in the guest and the host OS.
1535 If you are using Windows XP as guest OS and if you want to use high
1536 resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
1537 1280x1024x16), then you should use the VESA VBE virtual graphic card
1538 (option @option{-std-vga}).
1540 @subsubsection CPU usage reduction
1542 Windows 9x does not correctly use the CPU HLT
1543 instruction. The result is that it takes host CPU cycles even when
1544 idle. You can install the utility from
1545 @url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1546 problem. Note that no such tool is needed for NT, 2000 or XP.
1548 @subsubsection Windows 2000 disk full problem
1550 Windows 2000 has a bug which gives a disk full problem during its
1551 installation. When installing it, use the @option{-win2k-hack} QEMU
1552 option to enable a specific workaround. After Windows 2000 is
1553 installed, you no longer need this option (this option slows down the
1554 IDE transfers).
1556 @subsubsection Windows 2000 shutdown
1558 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1559 can. It comes from the fact that Windows 2000 does not automatically
1560 use the APM driver provided by the BIOS.
1562 In order to correct that, do the following (thanks to Struan
1563 Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1564 Add/Troubleshoot a device => Add a new device & Next => No, select the
1565 hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1566 (again) a few times. Now the driver is installed and Windows 2000 now
1567 correctly instructs QEMU to shutdown at the appropriate moment.
1569 @subsubsection Share a directory between Unix and Windows
1571 See @ref{sec_invocation} about the help of the option @option{-smb}.
1573 @subsubsection Windows XP security problem
1575 Some releases of Windows XP install correctly but give a security
1576 error when booting:
1577 @example
1578 A problem is preventing Windows from accurately checking the
1579 license for this computer. Error code: 0x800703e6.
1580 @end example
1582 The workaround is to install a service pack for XP after a boot in safe
1583 mode. Then reboot, and the problem should go away. Since there is no
1584 network while in safe mode, its recommended to download the full
1585 installation of SP1 or SP2 and transfer that via an ISO or using the
1586 vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1588 @subsection MS-DOS and FreeDOS
1590 @subsubsection CPU usage reduction
1592 DOS does not correctly use the CPU HLT instruction. The result is that
1593 it takes host CPU cycles even when idle. You can install the utility
1594 from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1595 problem.
1597 @node QEMU System emulator for non PC targets
1598 @chapter QEMU System emulator for non PC targets
1600 QEMU is a generic emulator and it emulates many non PC
1601 machines. Most of the options are similar to the PC emulator. The
1602 differences are mentioned in the following sections.
1604 @menu
1605 * QEMU PowerPC System emulator::
1606 * Sparc32 System emulator::
1607 * Sparc64 System emulator::
1608 * MIPS System emulator::
1609 * ARM System emulator::
1610 * ColdFire System emulator::
1611 @end menu
1613 @node QEMU PowerPC System emulator
1614 @section QEMU PowerPC System emulator
1616 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1617 or PowerMac PowerPC system.
1619 QEMU emulates the following PowerMac peripherals:
1621 @itemize @minus
1622 @item
1623 UniNorth or Grackle PCI Bridge
1624 @item
1625 PCI VGA compatible card with VESA Bochs Extensions
1626 @item
1627 2 PMAC IDE interfaces with hard disk and CD-ROM support
1628 @item
1629 NE2000 PCI adapters
1630 @item
1631 Non Volatile RAM
1632 @item
1633 VIA-CUDA with ADB keyboard and mouse.
1634 @end itemize
1636 QEMU emulates the following PREP peripherals:
1638 @itemize @minus
1639 @item
1640 PCI Bridge
1641 @item
1642 PCI VGA compatible card with VESA Bochs Extensions
1643 @item
1644 2 IDE interfaces with hard disk and CD-ROM support
1645 @item
1646 Floppy disk
1647 @item
1648 NE2000 network adapters
1649 @item
1650 Serial port
1651 @item
1652 PREP Non Volatile RAM
1653 @item
1654 PC compatible keyboard and mouse.
1655 @end itemize
1657 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1658 @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
1660 Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
1661 for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1662 v2) portable firmware implementation. The goal is to implement a 100%
1663 IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
1665 @c man begin OPTIONS
1667 The following options are specific to the PowerPC emulation:
1669 @table @option
1671 @item -g WxH[xDEPTH]
1673 Set the initial VGA graphic mode. The default is 800x600x15.
1675 @item -prom-env string
1677 Set OpenBIOS variables in NVRAM, for example:
1679 @example
1680 qemu-system-ppc -prom-env 'auto-boot?=false' \
1681  -prom-env 'boot-device=hd:2,\yaboot' \
1682  -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1683 @end example
1685 These variables are not used by Open Hack'Ware.
1687 @end table
1689 @c man end
1692 More information is available at
1693 @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1695 @node Sparc32 System emulator
1696 @section Sparc32 System emulator
1698 Use the executable @file{qemu-system-sparc} to simulate the following
1699 Sun4m architecture machines:
1700 @itemize @minus
1701 @item
1702 SPARCstation 4
1703 @item
1704 SPARCstation 5
1705 @item
1706 SPARCstation 10
1707 @item
1708 SPARCstation 20
1709 @item
1710 SPARCserver 600MP
1711 @item
1712 SPARCstation LX
1713 @item
1714 SPARCstation Voyager
1715 @item
1716 SPARCclassic
1717 @item
1718 SPARCbook
1719 @end itemize
1721 The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1722 but Linux limits the number of usable CPUs to 4.
1724 It's also possible to simulate a SPARCstation 2 (sun4c architecture),
1725 SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
1726 emulators are not usable yet.
1728 QEMU emulates the following sun4m/sun4c/sun4d peripherals:
1730 @itemize @minus
1731 @item
1732 IOMMU or IO-UNITs
1733 @item
1734 TCX Frame buffer
1735 @item
1736 Lance (Am7990) Ethernet
1737 @item
1738 Non Volatile RAM M48T02/M48T08
1739 @item
1740 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1741 and power/reset logic
1742 @item
1743 ESP SCSI controller with hard disk and CD-ROM support
1744 @item
1745 Floppy drive (not on SS-600MP)
1746 @item
1747 CS4231 sound device (only on SS-5, not working yet)
1748 @end itemize
1750 The number of peripherals is fixed in the architecture.  Maximum
1751 memory size depends on the machine type, for SS-5 it is 256MB and for
1752 others 2047MB.
1754 Since version 0.8.2, QEMU uses OpenBIOS
1755 @url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1756 firmware implementation. The goal is to implement a 100% IEEE
1757 1275-1994 (referred to as Open Firmware) compliant firmware.
1759 A sample Linux 2.6 series kernel and ram disk image are available on
1760 the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1761 some kernel versions work. Please note that currently Solaris kernels
1762 don't work probably due to interface issues between OpenBIOS and
1763 Solaris.
1765 @c man begin OPTIONS
1767 The following options are specific to the Sparc32 emulation:
1769 @table @option
1771 @item -g WxHx[xDEPTH]
1773 Set the initial TCX graphic mode. The default is 1024x768x8, currently
1774 the only other possible mode is 1024x768x24.
1776 @item -prom-env string
1778 Set OpenBIOS variables in NVRAM, for example:
1780 @example
1781 qemu-system-sparc -prom-env 'auto-boot?=false' \
1782  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1783 @end example
1785 @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic|SPARCbook|SS-2|SS-1000|SS-2000]
1787 Set the emulated machine type. Default is SS-5.
1789 @end table
1791 @c man end
1793 @node Sparc64 System emulator
1794 @section Sparc64 System emulator
1796 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1797 (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1798 Niagara (T1) machine. The emulator is not usable for anything yet, but
1799 it can launch some kernels.
1801 QEMU emulates the following peripherals:
1803 @itemize @minus
1804 @item
1805 UltraSparc IIi APB PCI Bridge
1806 @item
1807 PCI VGA compatible card with VESA Bochs Extensions
1808 @item
1809 PS/2 mouse and keyboard
1810 @item
1811 Non Volatile RAM M48T59
1812 @item
1813 PC-compatible serial ports
1814 @item
1815 2 PCI IDE interfaces with hard disk and CD-ROM support
1816 @item
1817 Floppy disk
1818 @end itemize
1820 @c man begin OPTIONS
1822 The following options are specific to the Sparc64 emulation:
1824 @table @option
1826 @item -prom-env string
1828 Set OpenBIOS variables in NVRAM, for example:
1830 @example
1831 qemu-system-sparc64 -prom-env 'auto-boot?=false'
1832 @end example
1834 @item -M [sun4u|sun4v|Niagara]
1836 Set the emulated machine type. The default is sun4u.
1838 @end table
1840 @c man end
1842 @node MIPS System emulator
1843 @section MIPS System emulator
1845 Four executables cover simulation of 32 and 64-bit MIPS systems in
1846 both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
1847 @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
1848 Five different machine types are emulated:
1850 @itemize @minus
1851 @item
1852 A generic ISA PC-like machine "mips"
1853 @item
1854 The MIPS Malta prototype board "malta"
1855 @item
1856 An ACER Pica "pica61". This machine needs the 64-bit emulator.
1857 @item
1858 MIPS emulator pseudo board "mipssim"
1859 @item
1860 A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
1861 @end itemize
1863 The generic emulation is supported by Debian 'Etch' and is able to
1864 install Debian into a virtual disk image. The following devices are
1865 emulated:
1867 @itemize @minus
1868 @item
1869 A range of MIPS CPUs, default is the 24Kf
1870 @item
1871 PC style serial port
1872 @item
1873 PC style IDE disk
1874 @item
1875 NE2000 network card
1876 @end itemize
1878 The Malta emulation supports the following devices:
1880 @itemize @minus
1881 @item
1882 Core board with MIPS 24Kf CPU and Galileo system controller
1883 @item
1884 PIIX4 PCI/USB/SMbus controller
1885 @item
1886 The Multi-I/O chip's serial device
1887 @item
1888 PCnet32 PCI network card
1889 @item
1890 Malta FPGA serial device
1891 @item
1892 Cirrus (default) or any other PCI VGA graphics card
1893 @end itemize
1895 The ACER Pica emulation supports:
1897 @itemize @minus
1898 @item
1899 MIPS R4000 CPU
1900 @item
1901 PC-style IRQ and DMA controllers
1902 @item
1903 PC Keyboard
1904 @item
1905 IDE controller
1906 @end itemize
1908 The mipssim pseudo board emulation provides an environment similiar
1909 to what the proprietary MIPS emulator uses for running Linux.
1910 It supports:
1912 @itemize @minus
1913 @item
1914 A range of MIPS CPUs, default is the 24Kf
1915 @item
1916 PC style serial port
1917 @item
1918 MIPSnet network emulation
1919 @end itemize
1921 The MIPS Magnum R4000 emulation supports:
1923 @itemize @minus
1924 @item
1925 MIPS R4000 CPU
1926 @item
1927 PC-style IRQ controller
1928 @item
1929 PC Keyboard
1930 @item
1931 SCSI controller
1932 @item
1933 G364 framebuffer
1934 @end itemize
1937 @node ARM System emulator
1938 @section ARM System emulator
1940 Use the executable @file{qemu-system-arm} to simulate a ARM
1941 machine. The ARM Integrator/CP board is emulated with the following
1942 devices:
1944 @itemize @minus
1945 @item
1946 ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
1947 @item
1948 Two PL011 UARTs
1949 @item
1950 SMC 91c111 Ethernet adapter
1951 @item
1952 PL110 LCD controller
1953 @item
1954 PL050 KMI with PS/2 keyboard and mouse.
1955 @item
1956 PL181 MultiMedia Card Interface with SD card.
1957 @end itemize
1959 The ARM Versatile baseboard is emulated with the following devices:
1961 @itemize @minus
1962 @item
1963 ARM926E, ARM1136 or Cortex-A8 CPU
1964 @item
1965 PL190 Vectored Interrupt Controller
1966 @item
1967 Four PL011 UARTs
1968 @item
1969 SMC 91c111 Ethernet adapter
1970 @item
1971 PL110 LCD controller
1972 @item
1973 PL050 KMI with PS/2 keyboard and mouse.
1974 @item
1975 PCI host bridge.  Note the emulated PCI bridge only provides access to
1976 PCI memory space.  It does not provide access to PCI IO space.
1977 This means some devices (eg. ne2k_pci NIC) are not usable, and others
1978 (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
1979 mapped control registers.
1980 @item
1981 PCI OHCI USB controller.
1982 @item
1983 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
1984 @item
1985 PL181 MultiMedia Card Interface with SD card.
1986 @end itemize
1988 The ARM RealView Emulation baseboard is emulated with the following devices:
1990 @itemize @minus
1991 @item
1992 ARM926E, ARM1136, ARM11MPCORE(x4) or Cortex-A8 CPU
1993 @item
1994 ARM AMBA Generic/Distributed Interrupt Controller
1995 @item
1996 Four PL011 UARTs
1997 @item
1998 SMC 91c111 Ethernet adapter
1999 @item
2000 PL110 LCD controller
2001 @item
2002 PL050 KMI with PS/2 keyboard and mouse
2003 @item
2004 PCI host bridge
2005 @item
2006 PCI OHCI USB controller
2007 @item
2008 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
2009 @item
2010 PL181 MultiMedia Card Interface with SD card.
2011 @end itemize
2013 The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2014 and "Terrier") emulation includes the following peripherals:
2016 @itemize @minus
2017 @item
2018 Intel PXA270 System-on-chip (ARM V5TE core)
2019 @item
2020 NAND Flash memory
2021 @item
2022 IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2023 @item
2024 On-chip OHCI USB controller
2025 @item
2026 On-chip LCD controller
2027 @item
2028 On-chip Real Time Clock
2029 @item
2030 TI ADS7846 touchscreen controller on SSP bus
2031 @item
2032 Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2033 @item
2034 GPIO-connected keyboard controller and LEDs
2035 @item
2036 Secure Digital card connected to PXA MMC/SD host
2037 @item
2038 Three on-chip UARTs
2039 @item
2040 WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2041 @end itemize
2043 The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2044 following elements:
2046 @itemize @minus
2047 @item
2048 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2049 @item
2050 ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2051 @item
2052 On-chip LCD controller
2053 @item
2054 On-chip Real Time Clock
2055 @item
2056 TI TSC2102i touchscreen controller / analog-digital converter / Audio
2057 CODEC, connected through MicroWire and I@math{^2}S busses
2058 @item
2059 GPIO-connected matrix keypad
2060 @item
2061 Secure Digital card connected to OMAP MMC/SD host
2062 @item
2063 Three on-chip UARTs
2064 @end itemize
2066 Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2067 emulation supports the following elements:
2069 @itemize @minus
2070 @item
2071 Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2072 @item
2073 RAM and non-volatile OneNAND Flash memories
2074 @item
2075 Display connected to EPSON remote framebuffer chip and OMAP on-chip
2076 display controller and a LS041y3 MIPI DBI-C controller
2077 @item
2078 TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2079 driven through SPI bus
2080 @item
2081 National Semiconductor LM8323-controlled qwerty keyboard driven
2082 through I@math{^2}C bus
2083 @item
2084 Secure Digital card connected to OMAP MMC/SD host
2085 @item
2086 Three OMAP on-chip UARTs and on-chip STI debugging console
2087 @item
2088 A Bluetooth(R) transciever and HCI connected to an UART
2089 @item
2090 Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2091 TUSB6010 chip - only USB host mode is supported
2092 @item
2093 TI TMP105 temperature sensor driven through I@math{^2}C bus
2094 @item
2095 TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2096 @item
2097 Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2098 through CBUS
2099 @end itemize
2101 The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2102 devices:
2104 @itemize @minus
2105 @item
2106 Cortex-M3 CPU core.
2107 @item
2108 64k Flash and 8k SRAM.
2109 @item
2110 Timers, UARTs, ADC and I@math{^2}C interface.
2111 @item
2112 OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2113 @end itemize
2115 The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2116 devices:
2118 @itemize @minus
2119 @item
2120 Cortex-M3 CPU core.
2121 @item
2122 256k Flash and 64k SRAM.
2123 @item
2124 Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2125 @item
2126 OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2127 @end itemize
2129 The Freecom MusicPal internet radio emulation includes the following
2130 elements:
2132 @itemize @minus
2133 @item
2134 Marvell MV88W8618 ARM core.
2135 @item
2136 32 MB RAM, 256 KB SRAM, 8 MB flash.
2137 @item
2138 Up to 2 16550 UARTs
2139 @item
2140 MV88W8xx8 Ethernet controller
2141 @item
2142 MV88W8618 audio controller, WM8750 CODEC and mixer
2143 @item
2144 128×64 display with brightness control
2145 @item
2146 2 buttons, 2 navigation wheels with button function
2147 @end itemize
2149 The Siemens SX1 models v1 and v2 (default) basic emulation.
2150 The emulaton includes the following elements:
2152 @itemize @minus
2153 @item
2154 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2155 @item
2156 ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2158 1 Flash of 16MB and 1 Flash of 8MB
2160 1 Flash of 32MB
2161 @item
2162 On-chip LCD controller
2163 @item
2164 On-chip Real Time Clock
2165 @item
2166 Secure Digital card connected to OMAP MMC/SD host
2167 @item
2168 Three on-chip UARTs
2169 @end itemize
2171 A Linux 2.6 test image is available on the QEMU web site. More
2172 information is available in the QEMU mailing-list archive.
2174 @c man begin OPTIONS
2176 The following options are specific to the ARM emulation:
2178 @table @option
2180 @item -semihosting
2181 Enable semihosting syscall emulation.
2183 On ARM this implements the "Angel" interface.
2185 Note that this allows guest direct access to the host filesystem,
2186 so should only be used with trusted guest OS.
2188 @end table
2190 @node ColdFire System emulator
2191 @section ColdFire System emulator
2193 Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2194 The emulator is able to boot a uClinux kernel.
2196 The M5208EVB emulation includes the following devices:
2198 @itemize @minus
2199 @item
2200 MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2201 @item
2202 Three Two on-chip UARTs.
2203 @item
2204 Fast Ethernet Controller (FEC)
2205 @end itemize
2207 The AN5206 emulation includes the following devices:
2209 @itemize @minus
2210 @item
2211 MCF5206 ColdFire V2 Microprocessor.
2212 @item
2213 Two on-chip UARTs.
2214 @end itemize
2216 @c man begin OPTIONS
2218 The following options are specific to the ARM emulation:
2220 @table @option
2222 @item -semihosting
2223 Enable semihosting syscall emulation.
2225 On M68K this implements the "ColdFire GDB" interface used by libgloss.
2227 Note that this allows guest direct access to the host filesystem,
2228 so should only be used with trusted guest OS.
2230 @end table
2232 @node QEMU User space emulator
2233 @chapter QEMU User space emulator
2235 @menu
2236 * Supported Operating Systems ::
2237 * Linux User space emulator::
2238 * Mac OS X/Darwin User space emulator ::
2239 * BSD User space emulator ::
2240 @end menu
2242 @node Supported Operating Systems
2243 @section Supported Operating Systems
2245 The following OS are supported in user space emulation:
2247 @itemize @minus
2248 @item
2249 Linux (referred as qemu-linux-user)
2250 @item
2251 Mac OS X/Darwin (referred as qemu-darwin-user)
2252 @item
2253 BSD (referred as qemu-bsd-user)
2254 @end itemize
2256 @node Linux User space emulator
2257 @section Linux User space emulator
2259 @menu
2260 * Quick Start::
2261 * Wine launch::
2262 * Command line options::
2263 * Other binaries::
2264 @end menu
2266 @node Quick Start
2267 @subsection Quick Start
2269 In order to launch a Linux process, QEMU needs the process executable
2270 itself and all the target (x86) dynamic libraries used by it.
2272 @itemize
2274 @item On x86, you can just try to launch any process by using the native
2275 libraries:
2277 @example
2278 qemu-i386 -L / /bin/ls
2279 @end example
2281 @code{-L /} tells that the x86 dynamic linker must be searched with a
2282 @file{/} prefix.
2284 @item Since QEMU is also a linux process, you can launch qemu with
2285 qemu (NOTE: you can only do that if you compiled QEMU from the sources):
2287 @example
2288 qemu-i386 -L / qemu-i386 -L / /bin/ls
2289 @end example
2291 @item On non x86 CPUs, you need first to download at least an x86 glibc
2292 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2293 @code{LD_LIBRARY_PATH} is not set:
2295 @example
2296 unset LD_LIBRARY_PATH
2297 @end example
2299 Then you can launch the precompiled @file{ls} x86 executable:
2301 @example
2302 qemu-i386 tests/i386/ls
2303 @end example
2304 You can look at @file{qemu-binfmt-conf.sh} so that
2305 QEMU is automatically launched by the Linux kernel when you try to
2306 launch x86 executables. It requires the @code{binfmt_misc} module in the
2307 Linux kernel.
2309 @item The x86 version of QEMU is also included. You can try weird things such as:
2310 @example
2311 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2312           /usr/local/qemu-i386/bin/ls-i386
2313 @end example
2315 @end itemize
2317 @node Wine launch
2318 @subsection Wine launch
2320 @itemize
2322 @item Ensure that you have a working QEMU with the x86 glibc
2323 distribution (see previous section). In order to verify it, you must be
2324 able to do:
2326 @example
2327 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2328 @end example
2330 @item Download the binary x86 Wine install
2331 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2333 @item Configure Wine on your account. Look at the provided script
2334 @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2335 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2337 @item Then you can try the example @file{putty.exe}:
2339 @example
2340 qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2341           /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2342 @end example
2344 @end itemize
2346 @node Command line options
2347 @subsection Command line options
2349 @example
2350 usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] program [arguments...]
2351 @end example
2353 @table @option
2354 @item -h
2355 Print the help
2356 @item -L path
2357 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2358 @item -s size
2359 Set the x86 stack size in bytes (default=524288)
2360 @item -cpu model
2361 Select CPU model (-cpu ? for list and additional feature selection)
2362 @end table
2364 Debug options:
2366 @table @option
2367 @item -d
2368 Activate log (logfile=/tmp/qemu.log)
2369 @item -p pagesize
2370 Act as if the host page size was 'pagesize' bytes
2371 @item -g port
2372 Wait gdb connection to port
2373 @end table
2375 Environment variables:
2377 @table @env
2378 @item QEMU_STRACE
2379 Print system calls and arguments similar to the 'strace' program
2380 (NOTE: the actual 'strace' program will not work because the user
2381 space emulator hasn't implemented ptrace).  At the moment this is
2382 incomplete.  All system calls that don't have a specific argument
2383 format are printed with information for six arguments.  Many
2384 flag-style arguments don't have decoders and will show up as numbers.
2385 @end table
2387 @node Other binaries
2388 @subsection Other binaries
2390 @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2391 binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2392 configurations), and arm-uclinux bFLT format binaries.
2394 @command{qemu-m68k} is capable of running semihosted binaries using the BDM
2395 (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2396 coldfire uClinux bFLT format binaries.
2398 The binary format is detected automatically.
2400 @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2402 @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2403 (Sparc64 CPU, 32 bit ABI).
2405 @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2406 SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2408 @node Mac OS X/Darwin User space emulator
2409 @section Mac OS X/Darwin User space emulator
2411 @menu
2412 * Mac OS X/Darwin Status::
2413 * Mac OS X/Darwin Quick Start::
2414 * Mac OS X/Darwin Command line options::
2415 @end menu
2417 @node Mac OS X/Darwin Status
2418 @subsection Mac OS X/Darwin Status
2420 @itemize @minus
2421 @item
2422 target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
2423 @item
2424 target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
2425 @item
2426 target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
2427 @item
2428 target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
2429 @end itemize
2431 [1] If you're host commpage can be executed by qemu.
2433 @node Mac OS X/Darwin Quick Start
2434 @subsection Quick Start
2436 In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
2437 itself and all the target dynamic libraries used by it. If you don't have the FAT
2438 libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
2439 CD or compile them by hand.
2441 @itemize
2443 @item On x86, you can just try to launch any process by using the native
2444 libraries:
2446 @example
2447 qemu-i386 /bin/ls
2448 @end example
2450 or to run the ppc version of the executable:
2452 @example
2453 qemu-ppc /bin/ls
2454 @end example
2456 @item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
2457 are installed:
2459 @example
2460 qemu-i386 -L /opt/x86_root/ /bin/ls
2461 @end example
2463 @code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
2464 @file{/opt/x86_root/usr/bin/dyld}.
2466 @end itemize
2468 @node Mac OS X/Darwin Command line options
2469 @subsection Command line options
2471 @example
2472 usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
2473 @end example
2475 @table @option
2476 @item -h
2477 Print the help
2478 @item -L path
2479 Set the library root path (default=/)
2480 @item -s size
2481 Set the stack size in bytes (default=524288)
2482 @end table
2484 Debug options:
2486 @table @option
2487 @item -d
2488 Activate log (logfile=/tmp/qemu.log)
2489 @item -p pagesize
2490 Act as if the host page size was 'pagesize' bytes
2491 @end table
2493 @node BSD User space emulator
2494 @section BSD User space emulator
2496 @menu
2497 * BSD Status::
2498 * BSD Quick Start::
2499 * BSD Command line options::
2500 @end menu
2502 @node BSD Status
2503 @subsection BSD Status
2505 @itemize @minus
2506 @item
2507 target Sparc64 on Sparc64: Some trivial programs work.
2508 @end itemize
2510 @node BSD Quick Start
2511 @subsection Quick Start
2513 In order to launch a BSD process, QEMU needs the process executable
2514 itself and all the target dynamic libraries used by it.
2516 @itemize
2518 @item On Sparc64, you can just try to launch any process by using the native
2519 libraries:
2521 @example
2522 qemu-sparc64 /bin/ls
2523 @end example
2525 @end itemize
2527 @node BSD Command line options
2528 @subsection Command line options
2530 @example
2531 usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
2532 @end example
2534 @table @option
2535 @item -h
2536 Print the help
2537 @item -L path
2538 Set the library root path (default=/)
2539 @item -s size
2540 Set the stack size in bytes (default=524288)
2541 @item -bsd type
2542 Set the type of the emulated BSD Operating system. Valid values are
2543 FreeBSD, NetBSD and OpenBSD (default).
2544 @end table
2546 Debug options:
2548 @table @option
2549 @item -d
2550 Activate log (logfile=/tmp/qemu.log)
2551 @item -p pagesize
2552 Act as if the host page size was 'pagesize' bytes
2553 @end table
2555 @node compilation
2556 @chapter Compilation from the sources
2558 @menu
2559 * Linux/Unix::
2560 * Windows::
2561 * Cross compilation for Windows with Linux::
2562 * Mac OS X::
2563 @end menu
2565 @node Linux/Unix
2566 @section Linux/Unix
2568 @subsection Compilation
2570 First you must decompress the sources:
2571 @example
2572 cd /tmp
2573 tar zxvf qemu-x.y.z.tar.gz
2574 cd qemu-x.y.z
2575 @end example
2577 Then you configure QEMU and build it (usually no options are needed):
2578 @example
2579 ./configure
2580 make
2581 @end example
2583 Then type as root user:
2584 @example
2585 make install
2586 @end example
2587 to install QEMU in @file{/usr/local}.
2589 @subsection GCC version
2591 In order to compile QEMU successfully, it is very important that you
2592 have the right tools. The most important one is gcc. On most hosts and
2593 in particular on x86 ones, @emph{gcc 4.x is not supported}. If your
2594 Linux distribution includes a gcc 4.x compiler, you can usually
2595 install an older version (it is invoked by @code{gcc32} or
2596 @code{gcc34}). The QEMU configure script automatically probes for
2597 these older versions so that usually you don't have to do anything.
2599 @node Windows
2600 @section Windows
2602 @itemize
2603 @item Install the current versions of MSYS and MinGW from
2604 @url{http://www.mingw.org/}. You can find detailed installation
2605 instructions in the download section and the FAQ.
2607 @item Download
2608 the MinGW development library of SDL 1.2.x
2609 (@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
2610 @url{http://www.libsdl.org}. Unpack it in a temporary place, and
2611 unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
2612 directory. Edit the @file{sdl-config} script so that it gives the
2613 correct SDL directory when invoked.
2615 @item Extract the current version of QEMU.
2617 @item Start the MSYS shell (file @file{msys.bat}).
2619 @item Change to the QEMU directory. Launch @file{./configure} and
2620 @file{make}.  If you have problems using SDL, verify that
2621 @file{sdl-config} can be launched from the MSYS command line.
2623 @item You can install QEMU in @file{Program Files/Qemu} by typing
2624 @file{make install}. Don't forget to copy @file{SDL.dll} in
2625 @file{Program Files/Qemu}.
2627 @end itemize
2629 @node Cross compilation for Windows with Linux
2630 @section Cross compilation for Windows with Linux
2632 @itemize
2633 @item
2634 Install the MinGW cross compilation tools available at
2635 @url{http://www.mingw.org/}.
2637 @item
2638 Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
2639 unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
2640 variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
2641 the QEMU configuration script.
2643 @item
2644 Configure QEMU for Windows cross compilation:
2645 @example
2646 ./configure --enable-mingw32
2647 @end example
2648 If necessary, you can change the cross-prefix according to the prefix
2649 chosen for the MinGW tools with --cross-prefix. You can also use
2650 --prefix to set the Win32 install path.
2652 @item You can install QEMU in the installation directory by typing
2653 @file{make install}. Don't forget to copy @file{SDL.dll} in the
2654 installation directory.
2656 @end itemize
2658 Note: Currently, Wine does not seem able to launch
2659 QEMU for Win32.
2661 @node Mac OS X
2662 @section Mac OS X
2664 The Mac OS X patches are not fully merged in QEMU, so you should look
2665 at the QEMU mailing list archive to have all the necessary
2666 information.
2668 @node Index
2669 @chapter Index
2670 @printindex cp
2672 @bye