![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to qemu-doc.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Qemu by Fabrice Bellard] / qemu|
Return to qemu-doc.texi CVS log | Up to [Qemu by Fabrice Bellard] / qemu |
1.1 root 1: \input texinfo @c -*- texinfo -*-
1.1.1.3 root 2: @c %**start of header
3: @setfilename qemu-doc.info
1.1.1.5 root 4: @settitle QEMU Emulator User Documentation
1.1.1.3 root 5: @exampleindent 0
6: @paragraphindent 0
7: @c %**end of header
1.1 root 8:
9: @iftex
10: @titlepage
11: @sp 7
1.1.1.5 root 12: @center @titlefont{QEMU Emulator}
1.1.1.3 root 13: @sp 1
14: @center @titlefont{User Documentation}
1.1 root 15: @sp 3
16: @end titlepage
17: @end iftex
18:
1.1.1.3 root 19: @ifnottex
20: @node Top
21: @top
22:
23: @menu
24: * Introduction::
25: * Installation::
26: * QEMU PC System emulator::
27: * QEMU System emulator for non PC targets::
1.1.1.5 root 28: * QEMU User space emulator::
1.1.1.3 root 29: * compilation:: Compilation from the sources
30: * Index::
31: @end menu
32: @end ifnottex
33:
34: @contents
35:
36: @node Introduction
1.1 root 37: @chapter Introduction
38:
1.1.1.3 root 39: @menu
40: * intro_features:: Features
41: @end menu
42:
43: @node intro_features
1.1 root 44: @section Features
45:
46: QEMU is a FAST! processor emulator using dynamic translation to
47: achieve good emulation speed.
48:
49: QEMU has two operating modes:
50:
51: @itemize @minus
52:
1.1.1.6 root 53: @item
1.1 root 54: Full system emulation. In this mode, QEMU emulates a full system (for
1.1.1.2 root 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.
1.1 root 58:
1.1.1.6 root 59: @item
1.1.1.5 root 60: User mode emulation. In this mode, QEMU can launch
61: processes compiled for one CPU on another CPU. It can be used to
1.1 root 62: launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
63: to ease cross-compilation and cross-debugging.
64:
65: @end itemize
66:
67: QEMU can run without an host kernel driver and yet gives acceptable
1.1.1.6 root 68: performance.
1.1 root 69:
70: For system emulation, the following hardware targets are supported:
71: @itemize
72: @item PC (x86 or x86_64 processor)
1.1.1.2 root 73: @item ISA PC (old style PC without PCI bus)
1.1 root 74: @item PREP (PowerPC processor)
1.1.1.7 root 75: @item G3 Beige PowerMac (PowerPC processor)
1.1 root 76: @item Mac99 PowerMac (PowerPC processor, in progress)
1.1.1.6 root 77: @item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
1.1.1.7 root 78: @item Sun4u/Sun4v (64-bit Sparc processor, in progress)
1.1.1.6 root 79: @item Malta board (32-bit and 64-bit MIPS processors)
1.1.1.7 root 80: @item MIPS Magnum (64-bit MIPS processor)
1.1.1.6 root 81: @item ARM Integrator/CP (ARM)
82: @item ARM Versatile baseboard (ARM)
83: @item ARM RealView Emulation baseboard (ARM)
1.1.1.7 root 84: @item Spitz, Akita, Borzoi, Terrier and Tosa PDAs (PXA270 processor)
1.1.1.6 root 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)
1.1.1.7 root 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)
1.1.1.9 ! root 94: @item Syborg SVP base model (ARM Cortex-A8).
! 95: @item AXIS-Devboard88 (CRISv32 ETRAX-FS).
! 96: @item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze).
1.1 root 97: @end itemize
98:
1.1.1.9 ! root 99: For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported.
1.1 root 100:
1.1.1.3 root 101: @node Installation
1.1 root 102: @chapter Installation
103:
104: If you want to compile QEMU yourself, see @ref{compilation}.
105:
1.1.1.3 root 106: @menu
107: * install_linux:: Linux
108: * install_windows:: Windows
109: * install_mac:: Macintosh
110: @end menu
111:
112: @node install_linux
1.1 root 113: @section Linux
114:
115: If a precompiled package is available for your distribution - you just
116: have to install it. Otherwise, see @ref{compilation}.
117:
1.1.1.3 root 118: @node install_windows
1.1 root 119: @section Windows
120:
121: Download the experimental binary installer at
1.1.1.3 root 122: @url{http://www.free.oszoo.org/@/download.html}.
1.1 root 123:
1.1.1.3 root 124: @node install_mac
1.1 root 125: @section Mac OS X
126:
127: Download the experimental binary installer at
1.1.1.3 root 128: @url{http://www.free.oszoo.org/@/download.html}.
1.1 root 129:
1.1.1.3 root 130: @node QEMU PC System emulator
1.1.1.2 root 131: @chapter QEMU PC System emulator
1.1 root 132:
1.1.1.3 root 133: @menu
134: * pcsys_introduction:: Introduction
135: * pcsys_quickstart:: Quick Start
136: * sec_invocation:: Invocation
137: * pcsys_keys:: Keys
138: * pcsys_monitor:: QEMU Monitor
139: * disk_images:: Disk Images
140: * pcsys_network:: Network emulation
141: * direct_linux_boot:: Direct Linux Boot
142: * pcsys_usb:: USB emulation
1.1.1.6 root 143: * vnc_security:: VNC security
1.1.1.3 root 144: * gdb_usage:: GDB usage
145: * pcsys_os_specific:: Target OS specific information
146: @end menu
147:
148: @node pcsys_introduction
1.1 root 149: @section Introduction
150:
151: @c man begin DESCRIPTION
152:
1.1.1.2 root 153: The QEMU PC System emulator simulates the
154: following peripherals:
1.1 root 155:
156: @itemize @minus
1.1.1.6 root 157: @item
1.1 root 158: i440FX host PCI bridge and PIIX3 PCI to ISA bridge
159: @item
160: Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
161: extensions (hardware level, including all non standard modes).
162: @item
163: PS/2 mouse and keyboard
1.1.1.6 root 164: @item
1.1 root 165: 2 PCI IDE interfaces with hard disk and CD-ROM support
166: @item
167: Floppy disk
1.1.1.6 root 168: @item
1.1.1.9 ! root 169: PCI and ISA network adapters
1.1 root 170: @item
171: Serial ports
172: @item
1.1.1.2 root 173: Creative SoundBlaster 16 sound card
174: @item
175: ENSONIQ AudioPCI ES1370 sound card
176: @item
1.1.1.7 root 177: Intel 82801AA AC97 Audio compatible sound card
178: @item
1.1.1.2 root 179: Adlib(OPL2) - Yamaha YM3812 compatible chip
180: @item
1.1.1.7 root 181: Gravis Ultrasound GF1 sound card
182: @item
183: CS4231A compatible sound card
184: @item
1.1.1.2 root 185: PCI UHCI USB controller and a virtual USB hub.
1.1 root 186: @end itemize
187:
1.1.1.2 root 188: SMP is supported with up to 255 CPUs.
189:
1.1.1.7 root 190: Note that adlib, gus and cs4231a are only available when QEMU was
191: configured with --audio-card-list option containing the name(s) of
192: required card(s).
1.1.1.2 root 193:
1.1 root 194: QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
195: VGA BIOS.
196:
1.1.1.2 root 197: QEMU uses YM3812 emulation by Tatsuyuki Satoh.
198:
1.1.1.7 root 199: QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
200: by Tibor "TS" Schütz.
201:
202: CS4231A is the chip used in Windows Sound System and GUSMAX products
203:
1.1 root 204: @c man end
205:
1.1.1.3 root 206: @node pcsys_quickstart
1.1 root 207: @section Quick Start
208:
209: Download and uncompress the linux image (@file{linux.img}) and type:
210:
211: @example
212: qemu linux.img
213: @end example
214:
215: Linux should boot and give you a prompt.
216:
217: @node sec_invocation
218: @section Invocation
219:
220: @example
221: @c man begin SYNOPSIS
1.1.1.6 root 222: usage: qemu [options] [@var{disk_image}]
1.1 root 223: @c man end
224: @end example
225:
226: @c man begin OPTIONS
1.1.1.7 root 227: @var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
228: targets do not need a disk image.
1.1 root 229:
1.1.1.9 ! root 230: @include qemu-options.texi
1.1 root 231:
232: @c man end
233:
1.1.1.3 root 234: @node pcsys_keys
1.1 root 235: @section Keys
236:
237: @c man begin OPTIONS
238:
239: During the graphical emulation, you can use the following keys:
240: @table @key
241: @item Ctrl-Alt-f
242: Toggle full screen
243:
244: @item Ctrl-Alt-n
245: Switch to virtual console 'n'. Standard console mappings are:
246: @table @emph
247: @item 1
248: Target system display
249: @item 2
250: Monitor
251: @item 3
252: Serial port
253: @end table
254:
255: @item Ctrl-Alt
256: Toggle mouse and keyboard grab.
257: @end table
258:
259: In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
260: @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
261:
262: During emulation, if you are using the @option{-nographic} option, use
263: @key{Ctrl-a h} to get terminal commands:
264:
265: @table @key
266: @item Ctrl-a h
1.1.1.7 root 267: @item Ctrl-a ?
1.1 root 268: Print this help
1.1.1.6 root 269: @item Ctrl-a x
1.1.1.5 root 270: Exit emulator
1.1.1.6 root 271: @item Ctrl-a s
1.1 root 272: Save disk data back to file (if -snapshot)
1.1.1.6 root 273: @item Ctrl-a t
1.1.1.7 root 274: Toggle console timestamps
1.1 root 275: @item Ctrl-a b
276: Send break (magic sysrq in Linux)
277: @item Ctrl-a c
278: Switch between console and monitor
279: @item Ctrl-a Ctrl-a
280: Send Ctrl-a
281: @end table
282: @c man end
283:
284: @ignore
285:
286: @c man begin SEEALSO
287: The HTML documentation of QEMU for more precise information and Linux
288: user mode emulator invocation.
289: @c man end
290:
291: @c man begin AUTHOR
292: Fabrice Bellard
293: @c man end
294:
295: @end ignore
296:
1.1.1.3 root 297: @node pcsys_monitor
1.1 root 298: @section QEMU Monitor
299:
300: The QEMU monitor is used to give complex commands to the QEMU
301: emulator. You can use it to:
302:
303: @itemize @minus
304:
305: @item
1.1.1.6 root 306: Remove or insert removable media images
307: (such as CD-ROM or floppies).
1.1 root 308:
1.1.1.6 root 309: @item
1.1 root 310: Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
311: from a disk file.
312:
313: @item Inspect the VM state without an external debugger.
314:
315: @end itemize
316:
317: @subsection Commands
318:
319: The following commands are available:
320:
1.1.1.9 ! root 321: @include qemu-monitor.texi
1.1 root 322:
323: @subsection Integer expressions
324:
325: The monitor understands integers expressions for every integer
326: argument. You can use register names to get the value of specifics
327: CPU registers by prefixing them with @emph{$}.
328:
329: @node disk_images
330: @section Disk Images
331:
332: Since version 0.6.1, QEMU supports many disk image formats, including
333: growable disk images (their size increase as non empty sectors are
1.1.1.5 root 334: written), compressed and encrypted disk images. Version 0.8.3 added
335: the new qcow2 disk image format which is essential to support VM
336: snapshots.
1.1 root 337:
1.1.1.3 root 338: @menu
339: * disk_images_quickstart:: Quick start for disk image creation
340: * disk_images_snapshot_mode:: Snapshot mode
1.1.1.5 root 341: * vm_snapshots:: VM snapshots
1.1.1.3 root 342: * qemu_img_invocation:: qemu-img Invocation
1.1.1.7 root 343: * qemu_nbd_invocation:: qemu-nbd Invocation
1.1.1.5 root 344: * host_drives:: Using host drives
1.1.1.3 root 345: * disk_images_fat_images:: Virtual FAT disk images
1.1.1.7 root 346: * disk_images_nbd:: NBD access
1.1.1.3 root 347: @end menu
348:
349: @node disk_images_quickstart
1.1 root 350: @subsection Quick start for disk image creation
351:
352: You can create a disk image with the command:
353: @example
354: qemu-img create myimage.img mysize
355: @end example
356: where @var{myimage.img} is the disk image filename and @var{mysize} is its
357: size in kilobytes. You can add an @code{M} suffix to give the size in
358: megabytes and a @code{G} suffix for gigabytes.
359:
1.1.1.3 root 360: See @ref{qemu_img_invocation} for more information.
1.1 root 361:
1.1.1.3 root 362: @node disk_images_snapshot_mode
1.1 root 363: @subsection Snapshot mode
364:
365: If you use the option @option{-snapshot}, all disk images are
366: considered as read only. When sectors in written, they are written in
367: a temporary file created in @file{/tmp}. You can however force the
368: write back to the raw disk images by using the @code{commit} monitor
369: command (or @key{C-a s} in the serial console).
370:
1.1.1.5 root 371: @node vm_snapshots
372: @subsection VM snapshots
373:
374: VM snapshots are snapshots of the complete virtual machine including
375: CPU state, RAM, device state and the content of all the writable
376: disks. In order to use VM snapshots, you must have at least one non
377: removable and writable block device using the @code{qcow2} disk image
378: format. Normally this device is the first virtual hard drive.
379:
380: Use the monitor command @code{savevm} to create a new VM snapshot or
381: replace an existing one. A human readable name can be assigned to each
382: snapshot in addition to its numerical ID.
383:
384: Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
385: a VM snapshot. @code{info snapshots} lists the available snapshots
386: with their associated information:
387:
388: @example
389: (qemu) info snapshots
390: Snapshot devices: hda
391: Snapshot list (from hda):
392: ID TAG VM SIZE DATE VM CLOCK
393: 1 start 41M 2006-08-06 12:38:02 00:00:14.954
394: 2 40M 2006-08-06 12:43:29 00:00:18.633
395: 3 msys 40M 2006-08-06 12:44:04 00:00:23.514
396: @end example
397:
398: A VM snapshot is made of a VM state info (its size is shown in
399: @code{info snapshots}) and a snapshot of every writable disk image.
400: The VM state info is stored in the first @code{qcow2} non removable
401: and writable block device. The disk image snapshots are stored in
402: every disk image. The size of a snapshot in a disk image is difficult
403: to evaluate and is not shown by @code{info snapshots} because the
404: associated disk sectors are shared among all the snapshots to save
405: disk space (otherwise each snapshot would need a full copy of all the
406: disk images).
407:
408: When using the (unrelated) @code{-snapshot} option
409: (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
410: but they are deleted as soon as you exit QEMU.
411:
412: VM snapshots currently have the following known limitations:
413: @itemize
1.1.1.6 root 414: @item
1.1.1.5 root 415: They cannot cope with removable devices if they are removed or
416: inserted after a snapshot is done.
1.1.1.6 root 417: @item
1.1.1.5 root 418: A few device drivers still have incomplete snapshot support so their
419: state is not saved or restored properly (in particular USB).
420: @end itemize
421:
1.1 root 422: @node qemu_img_invocation
423: @subsection @code{qemu-img} Invocation
424:
425: @include qemu-img.texi
426:
1.1.1.7 root 427: @node qemu_nbd_invocation
428: @subsection @code{qemu-nbd} Invocation
429:
430: @include qemu-nbd.texi
431:
1.1.1.5 root 432: @node host_drives
433: @subsection Using host drives
434:
435: In addition to disk image files, QEMU can directly access host
436: devices. We describe here the usage for QEMU version >= 0.8.3.
437:
438: @subsubsection Linux
439:
440: On Linux, you can directly use the host device filename instead of a
1.1.1.6 root 441: disk image filename provided you have enough privileges to access
1.1.1.5 root 442: it. For example, use @file{/dev/cdrom} to access to the CDROM or
443: @file{/dev/fd0} for the floppy.
444:
445: @table @code
446: @item CD
447: You can specify a CDROM device even if no CDROM is loaded. QEMU has
448: specific code to detect CDROM insertion or removal. CDROM ejection by
449: the guest OS is supported. Currently only data CDs are supported.
450: @item Floppy
451: You can specify a floppy device even if no floppy is loaded. Floppy
452: removal is currently not detected accurately (if you change floppy
453: without doing floppy access while the floppy is not loaded, the guest
454: OS will think that the same floppy is loaded).
455: @item Hard disks
456: Hard disks can be used. Normally you must specify the whole disk
457: (@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
458: see it as a partitioned disk. WARNING: unless you know what you do, it
459: is better to only make READ-ONLY accesses to the hard disk otherwise
460: you may corrupt your host data (use the @option{-snapshot} command
461: line option or modify the device permissions accordingly).
462: @end table
463:
464: @subsubsection Windows
465:
466: @table @code
467: @item CD
1.1.1.6 root 468: The preferred syntax is the drive letter (e.g. @file{d:}). The
1.1.1.5 root 469: alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
470: supported as an alias to the first CDROM drive.
471:
1.1.1.6 root 472: Currently there is no specific code to handle removable media, so it
1.1.1.5 root 473: is better to use the @code{change} or @code{eject} monitor commands to
474: change or eject media.
475: @item Hard disks
1.1.1.6 root 476: Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
1.1.1.5 root 477: where @var{N} is the drive number (0 is the first hard disk).
478:
479: WARNING: unless you know what you do, it is better to only make
480: READ-ONLY accesses to the hard disk otherwise you may corrupt your
481: host data (use the @option{-snapshot} command line so that the
482: modifications are written in a temporary file).
483: @end table
484:
485:
486: @subsubsection Mac OS X
487:
1.1.1.6 root 488: @file{/dev/cdrom} is an alias to the first CDROM.
1.1.1.5 root 489:
1.1.1.6 root 490: Currently there is no specific code to handle removable media, so it
1.1.1.5 root 491: is better to use the @code{change} or @code{eject} monitor commands to
492: change or eject media.
493:
1.1.1.3 root 494: @node disk_images_fat_images
1.1.1.2 root 495: @subsection Virtual FAT disk images
496:
497: QEMU can automatically create a virtual FAT disk image from a
498: directory tree. In order to use it, just type:
499:
1.1.1.6 root 500: @example
1.1.1.2 root 501: qemu linux.img -hdb fat:/my_directory
502: @end example
503:
504: Then you access access to all the files in the @file{/my_directory}
505: directory without having to copy them in a disk image or to export
506: them via SAMBA or NFS. The default access is @emph{read-only}.
1.1 root 507:
1.1.1.2 root 508: Floppies can be emulated with the @code{:floppy:} option:
1.1 root 509:
1.1.1.6 root 510: @example
1.1.1.2 root 511: qemu linux.img -fda fat:floppy:/my_directory
512: @end example
1.1 root 513:
1.1.1.2 root 514: A read/write support is available for testing (beta stage) with the
515: @code{:rw:} option:
516:
1.1.1.6 root 517: @example
1.1.1.2 root 518: qemu linux.img -fda fat:floppy:rw:/my_directory
519: @end example
520:
521: What you should @emph{never} do:
522: @itemize
523: @item use non-ASCII filenames ;
524: @item use "-snapshot" together with ":rw:" ;
525: @item expect it to work when loadvm'ing ;
526: @item write to the FAT directory on the host system while accessing it with the guest system.
527: @end itemize
528:
1.1.1.7 root 529: @node disk_images_nbd
530: @subsection NBD access
531:
532: QEMU can access directly to block device exported using the Network Block Device
533: protocol.
534:
535: @example
536: qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
537: @end example
538:
539: If the NBD server is located on the same host, you can use an unix socket instead
540: of an inet socket:
541:
542: @example
543: qemu linux.img -hdb nbd:unix:/tmp/my_socket
544: @end example
545:
546: In this case, the block device must be exported using qemu-nbd:
547:
548: @example
549: qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
550: @end example
551:
552: The use of qemu-nbd allows to share a disk between several guests:
553: @example
554: qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
555: @end example
556:
557: and then you can use it with two guests:
558: @example
559: qemu linux1.img -hdb nbd:unix:/tmp/my_socket
560: qemu linux2.img -hdb nbd:unix:/tmp/my_socket
561: @end example
562:
1.1.1.3 root 563: @node pcsys_network
1.1.1.2 root 564: @section Network emulation
565:
1.1.1.6 root 566: QEMU can simulate several network cards (PCI or ISA cards on the PC
1.1.1.2 root 567: target) and can connect them to an arbitrary number of Virtual Local
568: Area Networks (VLANs). Host TAP devices can be connected to any QEMU
569: VLAN. VLAN can be connected between separate instances of QEMU to
1.1.1.6 root 570: simulate large networks. For simpler usage, a non privileged user mode
1.1.1.2 root 571: network stack can replace the TAP device to have a basic network
572: connection.
573:
574: @subsection VLANs
575:
576: QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
577: connection between several network devices. These devices can be for
578: example QEMU virtual Ethernet cards or virtual Host ethernet devices
579: (TAP devices).
580:
581: @subsection Using TAP network interfaces
582:
583: This is the standard way to connect QEMU to a real network. QEMU adds
584: a virtual network device on your host (called @code{tapN}), and you
585: can then configure it as if it was a real ethernet card.
1.1 root 586:
1.1.1.5 root 587: @subsubsection Linux host
588:
1.1 root 589: As an example, you can download the @file{linux-test-xxx.tar.gz}
590: archive and copy the script @file{qemu-ifup} in @file{/etc} and
591: configure properly @code{sudo} so that the command @code{ifconfig}
592: contained in @file{qemu-ifup} can be executed as root. You must verify
1.1.1.2 root 593: that your host kernel supports the TAP network interfaces: the
1.1 root 594: device @file{/dev/net/tun} must be present.
595:
1.1.1.5 root 596: See @ref{sec_invocation} to have examples of command lines using the
597: TAP network interfaces.
598:
599: @subsubsection Windows host
600:
601: There is a virtual ethernet driver for Windows 2000/XP systems, called
602: TAP-Win32. But it is not included in standard QEMU for Windows,
603: so you will need to get it separately. It is part of OpenVPN package,
604: so download OpenVPN from : @url{http://openvpn.net/}.
1.1 root 605:
606: @subsection Using the user mode network stack
607:
1.1.1.2 root 608: By using the option @option{-net user} (default configuration if no
609: @option{-net} option is specified), QEMU uses a completely user mode
1.1.1.6 root 610: network stack (you don't need root privilege to use the virtual
1.1.1.2 root 611: network). The virtual network configuration is the following:
1.1 root 612:
613: @example
614:
1.1.1.2 root 615: QEMU VLAN <------> Firewall/DHCP server <-----> Internet
616: | (10.0.2.2)
1.1 root 617: |
618: ----> DNS server (10.0.2.3)
1.1.1.6 root 619: |
1.1 root 620: ----> SMB server (10.0.2.4)
621: @end example
622:
623: The QEMU VM behaves as if it was behind a firewall which blocks all
624: incoming connections. You can use a DHCP client to automatically
1.1.1.2 root 625: configure the network in the QEMU VM. The DHCP server assign addresses
626: to the hosts starting from 10.0.2.15.
1.1 root 627:
628: In order to check that the user mode network is working, you can ping
629: the address 10.0.2.2 and verify that you got an address in the range
630: 10.0.2.x from the QEMU virtual DHCP server.
631:
632: Note that @code{ping} is not supported reliably to the internet as it
1.1.1.6 root 633: would require root privileges. It means you can only ping the local
1.1 root 634: router (10.0.2.2).
635:
636: When using the built-in TFTP server, the router is also the TFTP
637: server.
638:
639: When using the @option{-redir} option, TCP or UDP connections can be
640: redirected from the host to the guest. It allows for example to
641: redirect X11, telnet or SSH connections.
642:
1.1.1.2 root 643: @subsection Connecting VLANs between QEMU instances
644:
645: Using the @option{-net socket} option, it is possible to make VLANs
646: that span several QEMU instances. See @ref{sec_invocation} to have a
647: basic example.
648:
1.1 root 649: @node direct_linux_boot
650: @section Direct Linux Boot
651:
652: This section explains how to launch a Linux kernel inside QEMU without
653: having to make a full bootable image. It is very useful for fast Linux
1.1.1.5 root 654: kernel testing.
1.1 root 655:
1.1.1.5 root 656: The syntax is:
1.1 root 657: @example
1.1.1.5 root 658: qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1.1 root 659: @end example
660:
1.1.1.5 root 661: Use @option{-kernel} to provide the Linux kernel image and
662: @option{-append} to give the kernel command line arguments. The
663: @option{-initrd} option can be used to provide an INITRD image.
1.1 root 664:
1.1.1.5 root 665: When using the direct Linux boot, a disk image for the first hard disk
666: @file{hda} is required because its boot sector is used to launch the
667: Linux kernel.
1.1 root 668:
1.1.1.5 root 669: If you do not need graphical output, you can disable it and redirect
670: the virtual serial port and the QEMU monitor to the console with the
671: @option{-nographic} option. The typical command line is:
1.1 root 672: @example
1.1.1.5 root 673: qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
674: -append "root=/dev/hda console=ttyS0" -nographic
1.1 root 675: @end example
676:
1.1.1.5 root 677: Use @key{Ctrl-a c} to switch between the serial console and the
678: monitor (@pxref{pcsys_keys}).
1.1 root 679:
1.1.1.3 root 680: @node pcsys_usb
1.1.1.2 root 681: @section USB emulation
682:
1.1.1.4 root 683: QEMU emulates a PCI UHCI USB controller. You can virtually plug
684: virtual USB devices or real host USB devices (experimental, works only
685: on Linux hosts). Qemu will automatically create and connect virtual USB hubs
1.1.1.5 root 686: as necessary to connect multiple USB devices.
1.1.1.2 root 687:
1.1.1.4 root 688: @menu
689: * usb_devices::
690: * host_usb_devices::
691: @end menu
692: @node usb_devices
693: @subsection Connecting USB devices
1.1.1.2 root 694:
1.1.1.4 root 695: USB devices can be connected with the @option{-usbdevice} commandline option
696: or the @code{usb_add} monitor command. Available devices are:
1.1.1.2 root 697:
1.1.1.7 root 698: @table @code
699: @item mouse
1.1.1.4 root 700: Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1.1.1.7 root 701: @item tablet
1.1.1.5 root 702: Pointer device that uses absolute coordinates (like a touchscreen).
1.1.1.4 root 703: This means qemu is able to report the mouse position without having
704: to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
1.1.1.7 root 705: @item disk:@var{file}
1.1.1.4 root 706: Mass storage device based on @var{file} (@pxref{disk_images})
1.1.1.7 root 707: @item host:@var{bus.addr}
1.1.1.4 root 708: Pass through the host device identified by @var{bus.addr}
709: (Linux only)
1.1.1.7 root 710: @item host:@var{vendor_id:product_id}
1.1.1.4 root 711: Pass through the host device identified by @var{vendor_id:product_id}
712: (Linux only)
1.1.1.7 root 713: @item wacom-tablet
1.1.1.6 root 714: Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
715: above but it can be used with the tslib library because in addition to touch
716: coordinates it reports touch pressure.
1.1.1.7 root 717: @item keyboard
1.1.1.6 root 718: Standard USB keyboard. Will override the PS/2 keyboard (if present).
1.1.1.7 root 719: @item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
720: Serial converter. This emulates an FTDI FT232BM chip connected to host character
721: device @var{dev}. The available character devices are the same as for the
722: @code{-serial} option. The @code{vendorid} and @code{productid} options can be
723: used to override the default 0403:6001. For instance,
724: @example
725: usb_add serial:productid=FA00:tcp:192.168.0.2:4444
726: @end example
727: will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
728: serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
729: @item braille
730: Braille device. This will use BrlAPI to display the braille output on a real
731: or fake device.
732: @item net:@var{options}
733: Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
734: specifies NIC options as with @code{-net nic,}@var{options} (see description).
735: For instance, user-mode networking can be used with
736: @example
737: qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
738: @end example
739: Currently this cannot be used in machines that support PCI NICs.
740: @item bt[:@var{hci-type}]
741: Bluetooth dongle whose type is specified in the same format as with
742: the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If
743: no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
744: This USB device implements the USB Transport Layer of HCI. Example
745: usage:
746: @example
747: qemu [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
748: @end example
1.1.1.4 root 749: @end table
1.1.1.2 root 750:
1.1.1.4 root 751: @node host_usb_devices
1.1.1.2 root 752: @subsection Using host USB devices on a Linux host
753:
754: WARNING: this is an experimental feature. QEMU will slow down when
755: using it. USB devices requiring real time streaming (i.e. USB Video
756: Cameras) are not supported yet.
757:
758: @enumerate
1.1.1.6 root 759: @item If you use an early Linux 2.4 kernel, verify that no Linux driver
1.1.1.2 root 760: is actually using the USB device. A simple way to do that is simply to
761: disable the corresponding kernel module by renaming it from @file{mydriver.o}
762: to @file{mydriver.o.disabled}.
763:
764: @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
765: @example
766: ls /proc/bus/usb
767: 001 devices drivers
768: @end example
769:
770: @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:
771: @example
772: chown -R myuid /proc/bus/usb
773: @end example
774:
775: @item Launch QEMU and do in the monitor:
1.1.1.6 root 776: @example
1.1.1.2 root 777: info usbhost
778: Device 1.2, speed 480 Mb/s
779: Class 00: USB device 1234:5678, USB DISK
780: @end example
781: You should see the list of the devices you can use (Never try to use
782: hubs, it won't work).
783:
784: @item Add the device in QEMU by using:
1.1.1.6 root 785: @example
1.1.1.2 root 786: usb_add host:1234:5678
787: @end example
788:
789: Normally the guest OS should report that a new USB device is
790: plugged. You can use the option @option{-usbdevice} to do the same.
791:
792: @item Now you can try to use the host USB device in QEMU.
793:
794: @end enumerate
795:
796: When relaunching QEMU, you may have to unplug and plug again the USB
797: device to make it work again (this is a bug).
798:
1.1.1.6 root 799: @node vnc_security
800: @section VNC security
801:
802: The VNC server capability provides access to the graphical console
803: of the guest VM across the network. This has a number of security
804: considerations depending on the deployment scenarios.
805:
806: @menu
807: * vnc_sec_none::
808: * vnc_sec_password::
809: * vnc_sec_certificate::
810: * vnc_sec_certificate_verify::
811: * vnc_sec_certificate_pw::
1.1.1.9 ! root 812: * vnc_sec_sasl::
! 813: * vnc_sec_certificate_sasl::
1.1.1.6 root 814: * vnc_generate_cert::
1.1.1.9 ! root 815: * vnc_setup_sasl::
1.1.1.6 root 816: @end menu
817: @node vnc_sec_none
818: @subsection Without passwords
819:
820: The simplest VNC server setup does not include any form of authentication.
821: For this setup it is recommended to restrict it to listen on a UNIX domain
822: socket only. For example
823:
824: @example
825: qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
826: @end example
827:
828: This ensures that only users on local box with read/write access to that
829: path can access the VNC server. To securely access the VNC server from a
830: remote machine, a combination of netcat+ssh can be used to provide a secure
831: tunnel.
832:
833: @node vnc_sec_password
834: @subsection With passwords
835:
836: The VNC protocol has limited support for password based authentication. Since
837: the protocol limits passwords to 8 characters it should not be considered
838: to provide high security. The password can be fairly easily brute-forced by
839: a client making repeat connections. For this reason, a VNC server using password
840: authentication should be restricted to only listen on the loopback interface
1.1.1.7 root 841: or UNIX domain sockets. Password authentication is requested with the @code{password}
1.1.1.6 root 842: option, and then once QEMU is running the password is set with the monitor. Until
843: the monitor is used to set the password all clients will be rejected.
844:
845: @example
846: qemu [...OPTIONS...] -vnc :1,password -monitor stdio
847: (qemu) change vnc password
848: Password: ********
849: (qemu)
850: @end example
851:
852: @node vnc_sec_certificate
853: @subsection With x509 certificates
854:
855: The QEMU VNC server also implements the VeNCrypt extension allowing use of
856: TLS for encryption of the session, and x509 certificates for authentication.
857: The use of x509 certificates is strongly recommended, because TLS on its
858: own is susceptible to man-in-the-middle attacks. Basic x509 certificate
859: support provides a secure session, but no authentication. This allows any
860: client to connect, and provides an encrypted session.
861:
862: @example
863: qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
864: @end example
865:
866: In the above example @code{/etc/pki/qemu} should contain at least three files,
867: @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
868: users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
869: NB the @code{server-key.pem} file should be protected with file mode 0600 to
870: only be readable by the user owning it.
871:
872: @node vnc_sec_certificate_verify
873: @subsection With x509 certificates and client verification
874:
875: Certificates can also provide a means to authenticate the client connecting.
876: The server will request that the client provide a certificate, which it will
877: then validate against the CA certificate. This is a good choice if deploying
878: in an environment with a private internal certificate authority.
879:
880: @example
881: qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
882: @end example
883:
884:
885: @node vnc_sec_certificate_pw
886: @subsection With x509 certificates, client verification and passwords
887:
888: Finally, the previous method can be combined with VNC password authentication
889: to provide two layers of authentication for clients.
890:
891: @example
892: qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
893: (qemu) change vnc password
894: Password: ********
895: (qemu)
896: @end example
897:
1.1.1.9 ! root 898:
! 899: @node vnc_sec_sasl
! 900: @subsection With SASL authentication
! 901:
! 902: The SASL authentication method is a VNC extension, that provides an
! 903: easily extendable, pluggable authentication method. This allows for
! 904: integration with a wide range of authentication mechanisms, such as
! 905: PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
! 906: The strength of the authentication depends on the exact mechanism
! 907: configured. If the chosen mechanism also provides a SSF layer, then
! 908: it will encrypt the datastream as well.
! 909:
! 910: Refer to the later docs on how to choose the exact SASL mechanism
! 911: used for authentication, but assuming use of one supporting SSF,
! 912: then QEMU can be launched with:
! 913:
! 914: @example
! 915: qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio
! 916: @end example
! 917:
! 918: @node vnc_sec_certificate_sasl
! 919: @subsection With x509 certificates and SASL authentication
! 920:
! 921: If the desired SASL authentication mechanism does not supported
! 922: SSF layers, then it is strongly advised to run it in combination
! 923: with TLS and x509 certificates. This provides securely encrypted
! 924: data stream, avoiding risk of compromising of the security
! 925: credentials. This can be enabled, by combining the 'sasl' option
! 926: with the aforementioned TLS + x509 options:
! 927:
! 928: @example
! 929: qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
! 930: @end example
! 931:
! 932:
1.1.1.6 root 933: @node vnc_generate_cert
934: @subsection Generating certificates for VNC
935:
936: The GNU TLS packages provides a command called @code{certtool} which can
937: be used to generate certificates and keys in PEM format. At a minimum it
938: is neccessary to setup a certificate authority, and issue certificates to
939: each server. If using certificates for authentication, then each client
940: will also need to be issued a certificate. The recommendation is for the
941: server to keep its certificates in either @code{/etc/pki/qemu} or for
942: unprivileged users in @code{$HOME/.pki/qemu}.
943:
944: @menu
945: * vnc_generate_ca::
946: * vnc_generate_server::
947: * vnc_generate_client::
948: @end menu
949: @node vnc_generate_ca
950: @subsubsection Setup the Certificate Authority
951:
952: This step only needs to be performed once per organization / organizational
953: unit. First the CA needs a private key. This key must be kept VERY secret
954: and secure. If this key is compromised the entire trust chain of the certificates
955: issued with it is lost.
956:
957: @example
958: # certtool --generate-privkey > ca-key.pem
959: @end example
960:
961: A CA needs to have a public certificate. For simplicity it can be a self-signed
962: certificate, or one issue by a commercial certificate issuing authority. To
963: generate a self-signed certificate requires one core piece of information, the
964: name of the organization.
965:
966: @example
967: # cat > ca.info <<EOF
968: cn = Name of your organization
969: ca
970: cert_signing_key
971: EOF
972: # certtool --generate-self-signed \
973: --load-privkey ca-key.pem
974: --template ca.info \
975: --outfile ca-cert.pem
976: @end example
977:
978: The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
979: TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
980:
981: @node vnc_generate_server
982: @subsubsection Issuing server certificates
983:
984: Each server (or host) needs to be issued with a key and certificate. When connecting
985: the certificate is sent to the client which validates it against the CA certificate.
986: The core piece of information for a server certificate is the hostname. This should
987: be the fully qualified hostname that the client will connect with, since the client
988: will typically also verify the hostname in the certificate. On the host holding the
989: secure CA private key:
990:
991: @example
992: # cat > server.info <<EOF
993: organization = Name of your organization
994: cn = server.foo.example.com
995: tls_www_server
996: encryption_key
997: signing_key
998: EOF
999: # certtool --generate-privkey > server-key.pem
1000: # certtool --generate-certificate \
1001: --load-ca-certificate ca-cert.pem \
1002: --load-ca-privkey ca-key.pem \
1003: --load-privkey server server-key.pem \
1004: --template server.info \
1005: --outfile server-cert.pem
1006: @end example
1007:
1008: The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1009: to the server for which they were generated. The @code{server-key.pem} is security
1010: sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1011:
1012: @node vnc_generate_client
1013: @subsubsection Issuing client certificates
1014:
1015: If the QEMU VNC server is to use the @code{x509verify} option to validate client
1016: certificates as its authentication mechanism, each client also needs to be issued
1017: a certificate. The client certificate contains enough metadata to uniquely identify
1018: the client, typically organization, state, city, building, etc. On the host holding
1019: the secure CA private key:
1020:
1021: @example
1022: # cat > client.info <<EOF
1023: country = GB
1024: state = London
1025: locality = London
1026: organiazation = Name of your organization
1027: cn = client.foo.example.com
1028: tls_www_client
1029: encryption_key
1030: signing_key
1031: EOF
1032: # certtool --generate-privkey > client-key.pem
1033: # certtool --generate-certificate \
1034: --load-ca-certificate ca-cert.pem \
1035: --load-ca-privkey ca-key.pem \
1036: --load-privkey client-key.pem \
1037: --template client.info \
1038: --outfile client-cert.pem
1039: @end example
1040:
1041: The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1042: copied to the client for which they were generated.
1043:
1.1.1.9 ! root 1044:
! 1045: @node vnc_setup_sasl
! 1046:
! 1047: @subsection Configuring SASL mechanisms
! 1048:
! 1049: The following documentation assumes use of the Cyrus SASL implementation on a
! 1050: Linux host, but the principals should apply to any other SASL impl. When SASL
! 1051: is enabled, the mechanism configuration will be loaded from system default
! 1052: SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
! 1053: unprivileged user, an environment variable SASL_CONF_PATH can be used
! 1054: to make it search alternate locations for the service config.
! 1055:
! 1056: The default configuration might contain
! 1057:
! 1058: @example
! 1059: mech_list: digest-md5
! 1060: sasldb_path: /etc/qemu/passwd.db
! 1061: @end example
! 1062:
! 1063: This says to use the 'Digest MD5' mechanism, which is similar to the HTTP
! 1064: Digest-MD5 mechanism. The list of valid usernames & passwords is maintained
! 1065: in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2
! 1066: command. While this mechanism is easy to configure and use, it is not
! 1067: considered secure by modern standards, so only suitable for developers /
! 1068: ad-hoc testing.
! 1069:
! 1070: A more serious deployment might use Kerberos, which is done with the 'gssapi'
! 1071: mechanism
! 1072:
! 1073: @example
! 1074: mech_list: gssapi
! 1075: keytab: /etc/qemu/krb5.tab
! 1076: @end example
! 1077:
! 1078: For this to work the administrator of your KDC must generate a Kerberos
! 1079: principal for the server, with a name of 'qemu/somehost.example.com@@EXAMPLE.COM'
! 1080: replacing 'somehost.example.com' with the fully qualified host name of the
! 1081: machine running QEMU, and 'EXAMPLE.COM' with the Keberos Realm.
! 1082:
! 1083: Other configurations will be left as an exercise for the reader. It should
! 1084: be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data
! 1085: encryption. For all other mechanisms, VNC should always be configured to
! 1086: use TLS and x509 certificates to protect security credentials from snooping.
! 1087:
1.1 root 1088: @node gdb_usage
1089: @section GDB usage
1090:
1091: QEMU has a primitive support to work with gdb, so that you can do
1092: 'Ctrl-C' while the virtual machine is running and inspect its state.
1093:
1094: In order to use gdb, launch qemu with the '-s' option. It will wait for a
1095: gdb connection:
1096: @example
1.1.1.3 root 1097: > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1098: -append "root=/dev/hda"
1.1 root 1099: Connected to host network interface: tun0
1100: Waiting gdb connection on port 1234
1101: @end example
1102:
1103: Then launch gdb on the 'vmlinux' executable:
1104: @example
1105: > gdb vmlinux
1106: @end example
1107:
1108: In gdb, connect to QEMU:
1109: @example
1110: (gdb) target remote localhost:1234
1111: @end example
1112:
1113: Then you can use gdb normally. For example, type 'c' to launch the kernel:
1114: @example
1115: (gdb) c
1116: @end example
1117:
1118: Here are some useful tips in order to use gdb on system code:
1119:
1120: @enumerate
1121: @item
1122: Use @code{info reg} to display all the CPU registers.
1123: @item
1124: Use @code{x/10i $eip} to display the code at the PC position.
1125: @item
1126: Use @code{set architecture i8086} to dump 16 bit code. Then use
1.1.1.4 root 1127: @code{x/10i $cs*16+$eip} to dump the code at the PC position.
1.1 root 1128: @end enumerate
1129:
1.1.1.7 root 1130: Advanced debugging options:
1131:
1132: 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:
1133: @table @code
1134: @item maintenance packet qqemu.sstepbits
1135:
1136: This will display the MASK bits used to control the single stepping IE:
1137: @example
1138: (gdb) maintenance packet qqemu.sstepbits
1139: sending: "qqemu.sstepbits"
1140: received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1141: @end example
1142: @item maintenance packet qqemu.sstep
1143:
1144: This will display the current value of the mask used when single stepping IE:
1145: @example
1146: (gdb) maintenance packet qqemu.sstep
1147: sending: "qqemu.sstep"
1148: received: "0x7"
1149: @end example
1150: @item maintenance packet Qqemu.sstep=HEX_VALUE
1151:
1152: This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1153: @example
1154: (gdb) maintenance packet Qqemu.sstep=0x5
1155: sending: "qemu.sstep=0x5"
1156: received: "OK"
1157: @end example
1158: @end table
1159:
1.1.1.3 root 1160: @node pcsys_os_specific
1.1 root 1161: @section Target OS specific information
1162:
1163: @subsection Linux
1164:
1165: To have access to SVGA graphic modes under X11, use the @code{vesa} or
1166: the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1167: color depth in the guest and the host OS.
1168:
1169: When using a 2.6 guest Linux kernel, you should add the option
1170: @code{clock=pit} on the kernel command line because the 2.6 Linux
1171: kernels make very strict real time clock checks by default that QEMU
1172: cannot simulate exactly.
1173:
1174: When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1175: not activated because QEMU is slower with this patch. The QEMU
1176: Accelerator Module is also much slower in this case. Earlier Fedora
1.1.1.6 root 1177: Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1.1 root 1178: patch by default. Newer kernels don't have it.
1179:
1180: @subsection Windows
1181:
1182: If you have a slow host, using Windows 95 is better as it gives the
1183: best speed. Windows 2000 is also a good choice.
1184:
1185: @subsubsection SVGA graphic modes support
1186:
1187: QEMU emulates a Cirrus Logic GD5446 Video
1188: card. All Windows versions starting from Windows 95 should recognize
1189: and use this graphic card. For optimal performances, use 16 bit color
1190: depth in the guest and the host OS.
1191:
1.1.1.4 root 1192: If you are using Windows XP as guest OS and if you want to use high
1193: resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
1194: 1280x1024x16), then you should use the VESA VBE virtual graphic card
1195: (option @option{-std-vga}).
1196:
1.1 root 1197: @subsubsection CPU usage reduction
1198:
1199: Windows 9x does not correctly use the CPU HLT
1200: instruction. The result is that it takes host CPU cycles even when
1201: idle. You can install the utility from
1202: @url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1203: problem. Note that no such tool is needed for NT, 2000 or XP.
1204:
1205: @subsubsection Windows 2000 disk full problem
1206:
1207: Windows 2000 has a bug which gives a disk full problem during its
1208: installation. When installing it, use the @option{-win2k-hack} QEMU
1209: option to enable a specific workaround. After Windows 2000 is
1210: installed, you no longer need this option (this option slows down the
1211: IDE transfers).
1212:
1213: @subsubsection Windows 2000 shutdown
1214:
1215: Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1216: can. It comes from the fact that Windows 2000 does not automatically
1217: use the APM driver provided by the BIOS.
1218:
1219: In order to correct that, do the following (thanks to Struan
1220: Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1221: Add/Troubleshoot a device => Add a new device & Next => No, select the
1222: hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1223: (again) a few times. Now the driver is installed and Windows 2000 now
1.1.1.6 root 1224: correctly instructs QEMU to shutdown at the appropriate moment.
1.1 root 1225:
1226: @subsubsection Share a directory between Unix and Windows
1227:
1228: See @ref{sec_invocation} about the help of the option @option{-smb}.
1229:
1.1.1.5 root 1230: @subsubsection Windows XP security problem
1.1 root 1231:
1232: Some releases of Windows XP install correctly but give a security
1233: error when booting:
1234: @example
1235: A problem is preventing Windows from accurately checking the
1236: license for this computer. Error code: 0x800703e6.
1237: @end example
1238:
1.1.1.5 root 1239: The workaround is to install a service pack for XP after a boot in safe
1240: mode. Then reboot, and the problem should go away. Since there is no
1241: network while in safe mode, its recommended to download the full
1242: installation of SP1 or SP2 and transfer that via an ISO or using the
1243: vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1.1 root 1244:
1245: @subsection MS-DOS and FreeDOS
1246:
1247: @subsubsection CPU usage reduction
1248:
1249: DOS does not correctly use the CPU HLT instruction. The result is that
1250: it takes host CPU cycles even when idle. You can install the utility
1251: from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1252: problem.
1253:
1.1.1.3 root 1254: @node QEMU System emulator for non PC targets
1.1.1.2 root 1255: @chapter QEMU System emulator for non PC targets
1256:
1257: QEMU is a generic emulator and it emulates many non PC
1258: machines. Most of the options are similar to the PC emulator. The
1.1.1.6 root 1259: differences are mentioned in the following sections.
1.1.1.2 root 1260:
1.1.1.3 root 1261: @menu
1262: * QEMU PowerPC System emulator::
1.1.1.6 root 1263: * Sparc32 System emulator::
1264: * Sparc64 System emulator::
1265: * MIPS System emulator::
1266: * ARM System emulator::
1267: * ColdFire System emulator::
1.1.1.3 root 1268: @end menu
1269:
1270: @node QEMU PowerPC System emulator
1.1.1.2 root 1271: @section QEMU PowerPC System emulator
1.1 root 1272:
1273: Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1274: or PowerMac PowerPC system.
1275:
1276: QEMU emulates the following PowerMac peripherals:
1277:
1278: @itemize @minus
1.1.1.6 root 1279: @item
1.1.1.7 root 1280: UniNorth or Grackle PCI Bridge
1.1 root 1281: @item
1282: PCI VGA compatible card with VESA Bochs Extensions
1.1.1.6 root 1283: @item
1.1 root 1284: 2 PMAC IDE interfaces with hard disk and CD-ROM support
1.1.1.6 root 1285: @item
1.1 root 1286: NE2000 PCI adapters
1287: @item
1288: Non Volatile RAM
1289: @item
1290: VIA-CUDA with ADB keyboard and mouse.
1291: @end itemize
1292:
1293: QEMU emulates the following PREP peripherals:
1294:
1295: @itemize @minus
1.1.1.6 root 1296: @item
1.1 root 1297: PCI Bridge
1298: @item
1299: PCI VGA compatible card with VESA Bochs Extensions
1.1.1.6 root 1300: @item
1.1 root 1301: 2 IDE interfaces with hard disk and CD-ROM support
1302: @item
1303: Floppy disk
1.1.1.6 root 1304: @item
1.1 root 1305: NE2000 network adapters
1306: @item
1307: Serial port
1308: @item
1309: PREP Non Volatile RAM
1310: @item
1311: PC compatible keyboard and mouse.
1312: @end itemize
1313:
1314: QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1.1.1.2 root 1315: @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
1.1 root 1316:
1.1.1.7 root 1317: Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
1318: for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1319: v2) portable firmware implementation. The goal is to implement a 100%
1320: IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
1321:
1.1 root 1322: @c man begin OPTIONS
1323:
1324: The following options are specific to the PowerPC emulation:
1325:
1326: @table @option
1327:
1.1.1.6 root 1328: @item -g WxH[xDEPTH]
1.1 root 1329:
1330: Set the initial VGA graphic mode. The default is 800x600x15.
1331:
1.1.1.7 root 1332: @item -prom-env string
1333:
1334: Set OpenBIOS variables in NVRAM, for example:
1335:
1336: @example
1337: qemu-system-ppc -prom-env 'auto-boot?=false' \
1338: -prom-env 'boot-device=hd:2,\yaboot' \
1339: -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1340: @end example
1341:
1342: These variables are not used by Open Hack'Ware.
1343:
1.1 root 1344: @end table
1345:
1.1.1.6 root 1346: @c man end
1.1 root 1347:
1348:
1349: More information is available at
1.1.1.2 root 1350: @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1.1 root 1351:
1.1.1.6 root 1352: @node Sparc32 System emulator
1353: @section Sparc32 System emulator
1.1 root 1354:
1.1.1.7 root 1355: Use the executable @file{qemu-system-sparc} to simulate the following
1356: Sun4m architecture machines:
1357: @itemize @minus
1358: @item
1359: SPARCstation 4
1360: @item
1361: SPARCstation 5
1362: @item
1363: SPARCstation 10
1364: @item
1365: SPARCstation 20
1366: @item
1367: SPARCserver 600MP
1368: @item
1369: SPARCstation LX
1370: @item
1371: SPARCstation Voyager
1372: @item
1373: SPARCclassic
1374: @item
1375: SPARCbook
1376: @end itemize
1377:
1378: The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1379: but Linux limits the number of usable CPUs to 4.
1.1 root 1380:
1.1.1.7 root 1381: It's also possible to simulate a SPARCstation 2 (sun4c architecture),
1382: SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
1383: emulators are not usable yet.
1384:
1385: QEMU emulates the following sun4m/sun4c/sun4d peripherals:
1.1 root 1386:
1387: @itemize @minus
1388: @item
1.1.1.6 root 1389: IOMMU or IO-UNITs
1.1 root 1390: @item
1391: TCX Frame buffer
1.1.1.6 root 1392: @item
1.1 root 1393: Lance (Am7990) Ethernet
1394: @item
1.1.1.7 root 1395: Non Volatile RAM M48T02/M48T08
1.1 root 1396: @item
1397: Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1398: and power/reset logic
1399: @item
1400: ESP SCSI controller with hard disk and CD-ROM support
1401: @item
1.1.1.6 root 1402: Floppy drive (not on SS-600MP)
1403: @item
1404: CS4231 sound device (only on SS-5, not working yet)
1.1 root 1405: @end itemize
1406:
1.1.1.6 root 1407: The number of peripherals is fixed in the architecture. Maximum
1408: memory size depends on the machine type, for SS-5 it is 256MB and for
1409: others 2047MB.
1.1 root 1410:
1.1.1.4 root 1411: Since version 0.8.2, QEMU uses OpenBIOS
1412: @url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1413: firmware implementation. The goal is to implement a 100% IEEE
1414: 1275-1994 (referred to as Open Firmware) compliant firmware.
1.1 root 1415:
1416: A sample Linux 2.6 series kernel and ram disk image are available on
1.1.1.7 root 1417: the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1418: some kernel versions work. Please note that currently Solaris kernels
1419: don't work probably due to interface issues between OpenBIOS and
1420: Solaris.
1.1 root 1421:
1422: @c man begin OPTIONS
1423:
1.1.1.6 root 1424: The following options are specific to the Sparc32 emulation:
1.1 root 1425:
1426: @table @option
1427:
1.1.1.6 root 1428: @item -g WxHx[xDEPTH]
1429:
1430: Set the initial TCX graphic mode. The default is 1024x768x8, currently
1431: the only other possible mode is 1024x768x24.
1432:
1433: @item -prom-env string
1.1 root 1434:
1.1.1.6 root 1435: Set OpenBIOS variables in NVRAM, for example:
1436:
1437: @example
1438: qemu-system-sparc -prom-env 'auto-boot?=false' \
1439: -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1440: @end example
1441:
1.1.1.7 root 1442: @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic|SPARCbook|SS-2|SS-1000|SS-2000]
1.1.1.6 root 1443:
1444: Set the emulated machine type. Default is SS-5.
1.1 root 1445:
1446: @end table
1447:
1.1.1.6 root 1448: @c man end
1.1 root 1449:
1.1.1.6 root 1450: @node Sparc64 System emulator
1451: @section Sparc64 System emulator
1.1 root 1452:
1.1.1.7 root 1453: Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1454: (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1455: Niagara (T1) machine. The emulator is not usable for anything yet, but
1456: it can launch some kernels.
1.1 root 1457:
1.1.1.7 root 1458: QEMU emulates the following peripherals:
1.1 root 1459:
1460: @itemize @minus
1461: @item
1.1.1.6 root 1462: UltraSparc IIi APB PCI Bridge
1.1 root 1463: @item
1464: PCI VGA compatible card with VESA Bochs Extensions
1465: @item
1.1.1.7 root 1466: PS/2 mouse and keyboard
1467: @item
1.1 root 1468: Non Volatile RAM M48T59
1469: @item
1470: PC-compatible serial ports
1.1.1.7 root 1471: @item
1472: 2 PCI IDE interfaces with hard disk and CD-ROM support
1473: @item
1474: Floppy disk
1.1 root 1475: @end itemize
1476:
1.1.1.7 root 1477: @c man begin OPTIONS
1478:
1479: The following options are specific to the Sparc64 emulation:
1480:
1481: @table @option
1482:
1483: @item -prom-env string
1484:
1485: Set OpenBIOS variables in NVRAM, for example:
1486:
1487: @example
1488: qemu-system-sparc64 -prom-env 'auto-boot?=false'
1489: @end example
1490:
1491: @item -M [sun4u|sun4v|Niagara]
1492:
1493: Set the emulated machine type. The default is sun4u.
1494:
1495: @end table
1496:
1497: @c man end
1498:
1.1.1.6 root 1499: @node MIPS System emulator
1500: @section MIPS System emulator
1501:
1502: Four executables cover simulation of 32 and 64-bit MIPS systems in
1503: both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
1504: @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
1.1.1.7 root 1505: Five different machine types are emulated:
1.1.1.6 root 1506:
1507: @itemize @minus
1508: @item
1509: A generic ISA PC-like machine "mips"
1510: @item
1511: The MIPS Malta prototype board "malta"
1512: @item
1513: An ACER Pica "pica61". This machine needs the 64-bit emulator.
1514: @item
1515: MIPS emulator pseudo board "mipssim"
1.1.1.7 root 1516: @item
1517: A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
1.1.1.6 root 1518: @end itemize
1.1 root 1519:
1.1.1.6 root 1520: The generic emulation is supported by Debian 'Etch' and is able to
1521: install Debian into a virtual disk image. The following devices are
1522: emulated:
1.1.1.2 root 1523:
1524: @itemize @minus
1.1.1.6 root 1525: @item
1526: A range of MIPS CPUs, default is the 24Kf
1.1.1.2 root 1527: @item
1528: PC style serial port
1529: @item
1.1.1.6 root 1530: PC style IDE disk
1531: @item
1.1.1.2 root 1532: NE2000 network card
1533: @end itemize
1534:
1.1.1.6 root 1535: The Malta emulation supports the following devices:
1536:
1537: @itemize @minus
1538: @item
1539: Core board with MIPS 24Kf CPU and Galileo system controller
1540: @item
1541: PIIX4 PCI/USB/SMbus controller
1542: @item
1543: The Multi-I/O chip's serial device
1544: @item
1.1.1.9 ! root 1545: PCI network cards (PCnet32 and others)
1.1.1.6 root 1546: @item
1547: Malta FPGA serial device
1548: @item
1.1.1.7 root 1549: Cirrus (default) or any other PCI VGA graphics card
1.1.1.6 root 1550: @end itemize
1551:
1552: The ACER Pica emulation supports:
1553:
1554: @itemize @minus
1555: @item
1556: MIPS R4000 CPU
1557: @item
1558: PC-style IRQ and DMA controllers
1559: @item
1560: PC Keyboard
1561: @item
1562: IDE controller
1563: @end itemize
1.1.1.2 root 1564:
1.1.1.6 root 1565: The mipssim pseudo board emulation provides an environment similiar
1566: to what the proprietary MIPS emulator uses for running Linux.
1567: It supports:
1568:
1569: @itemize @minus
1570: @item
1571: A range of MIPS CPUs, default is the 24Kf
1572: @item
1573: PC style serial port
1574: @item
1575: MIPSnet network emulation
1576: @end itemize
1577:
1.1.1.7 root 1578: The MIPS Magnum R4000 emulation supports:
1579:
1580: @itemize @minus
1581: @item
1582: MIPS R4000 CPU
1583: @item
1584: PC-style IRQ controller
1585: @item
1586: PC Keyboard
1587: @item
1588: SCSI controller
1589: @item
1590: G364 framebuffer
1591: @end itemize
1592:
1593:
1.1.1.6 root 1594: @node ARM System emulator
1595: @section ARM System emulator
1.1.1.2 root 1596:
1597: Use the executable @file{qemu-system-arm} to simulate a ARM
1598: machine. The ARM Integrator/CP board is emulated with the following
1599: devices:
1600:
1601: @itemize @minus
1602: @item
1.1.1.6 root 1603: ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
1.1.1.2 root 1604: @item
1605: Two PL011 UARTs
1.1.1.6 root 1606: @item
1.1.1.2 root 1607: SMC 91c111 Ethernet adapter
1.1.1.4 root 1608: @item
1609: PL110 LCD controller
1610: @item
1611: PL050 KMI with PS/2 keyboard and mouse.
1.1.1.6 root 1612: @item
1613: PL181 MultiMedia Card Interface with SD card.
1.1.1.4 root 1614: @end itemize
1615:
1616: The ARM Versatile baseboard is emulated with the following devices:
1617:
1618: @itemize @minus
1619: @item
1.1.1.6 root 1620: ARM926E, ARM1136 or Cortex-A8 CPU
1.1.1.4 root 1621: @item
1622: PL190 Vectored Interrupt Controller
1623: @item
1624: Four PL011 UARTs
1.1.1.6 root 1625: @item
1.1.1.4 root 1626: SMC 91c111 Ethernet adapter
1627: @item
1628: PL110 LCD controller
1629: @item
1630: PL050 KMI with PS/2 keyboard and mouse.
1631: @item
1632: PCI host bridge. Note the emulated PCI bridge only provides access to
1633: PCI memory space. It does not provide access to PCI IO space.
1.1.1.6 root 1634: This means some devices (eg. ne2k_pci NIC) are not usable, and others
1635: (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
1.1.1.4 root 1636: mapped control registers.
1637: @item
1638: PCI OHCI USB controller.
1639: @item
1640: LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
1.1.1.6 root 1641: @item
1642: PL181 MultiMedia Card Interface with SD card.
1643: @end itemize
1644:
1645: The ARM RealView Emulation baseboard is emulated with the following devices:
1646:
1647: @itemize @minus
1648: @item
1649: ARM926E, ARM1136, ARM11MPCORE(x4) or Cortex-A8 CPU
1650: @item
1651: ARM AMBA Generic/Distributed Interrupt Controller
1652: @item
1653: Four PL011 UARTs
1654: @item
1655: SMC 91c111 Ethernet adapter
1656: @item
1657: PL110 LCD controller
1658: @item
1659: PL050 KMI with PS/2 keyboard and mouse
1660: @item
1661: PCI host bridge
1662: @item
1663: PCI OHCI USB controller
1664: @item
1665: LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
1666: @item
1667: PL181 MultiMedia Card Interface with SD card.
1668: @end itemize
1669:
1670: The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
1671: and "Terrier") emulation includes the following peripherals:
1672:
1673: @itemize @minus
1674: @item
1675: Intel PXA270 System-on-chip (ARM V5TE core)
1676: @item
1677: NAND Flash memory
1678: @item
1679: IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
1680: @item
1681: On-chip OHCI USB controller
1682: @item
1683: On-chip LCD controller
1684: @item
1685: On-chip Real Time Clock
1686: @item
1687: TI ADS7846 touchscreen controller on SSP bus
1688: @item
1689: Maxim MAX1111 analog-digital converter on I@math{^2}C bus
1690: @item
1691: GPIO-connected keyboard controller and LEDs
1692: @item
1693: Secure Digital card connected to PXA MMC/SD host
1694: @item
1695: Three on-chip UARTs
1696: @item
1697: WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
1698: @end itemize
1699:
1700: The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
1701: following elements:
1702:
1703: @itemize @minus
1704: @item
1705: Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1706: @item
1707: ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
1708: @item
1709: On-chip LCD controller
1710: @item
1711: On-chip Real Time Clock
1712: @item
1713: TI TSC2102i touchscreen controller / analog-digital converter / Audio
1714: CODEC, connected through MicroWire and I@math{^2}S busses
1715: @item
1716: GPIO-connected matrix keypad
1717: @item
1718: Secure Digital card connected to OMAP MMC/SD host
1719: @item
1720: Three on-chip UARTs
1721: @end itemize
1722:
1.1.1.7 root 1723: Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
1724: emulation supports the following elements:
1725:
1726: @itemize @minus
1727: @item
1728: Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
1729: @item
1730: RAM and non-volatile OneNAND Flash memories
1731: @item
1732: Display connected to EPSON remote framebuffer chip and OMAP on-chip
1733: display controller and a LS041y3 MIPI DBI-C controller
1734: @item
1735: TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
1736: driven through SPI bus
1737: @item
1738: National Semiconductor LM8323-controlled qwerty keyboard driven
1739: through I@math{^2}C bus
1740: @item
1741: Secure Digital card connected to OMAP MMC/SD host
1742: @item
1743: Three OMAP on-chip UARTs and on-chip STI debugging console
1744: @item
1745: A Bluetooth(R) transciever and HCI connected to an UART
1746: @item
1747: Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
1748: TUSB6010 chip - only USB host mode is supported
1749: @item
1750: TI TMP105 temperature sensor driven through I@math{^2}C bus
1751: @item
1752: TI TWL92230C power management companion with an RTC on I@math{^2}C bus
1753: @item
1754: Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
1755: through CBUS
1756: @end itemize
1757:
1.1.1.6 root 1758: The Luminary Micro Stellaris LM3S811EVB emulation includes the following
1759: devices:
1760:
1761: @itemize @minus
1762: @item
1763: Cortex-M3 CPU core.
1764: @item
1765: 64k Flash and 8k SRAM.
1766: @item
1767: Timers, UARTs, ADC and I@math{^2}C interface.
1768: @item
1769: OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
1770: @end itemize
1771:
1772: The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
1773: devices:
1774:
1775: @itemize @minus
1776: @item
1777: Cortex-M3 CPU core.
1778: @item
1779: 256k Flash and 64k SRAM.
1780: @item
1781: Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
1782: @item
1783: OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
1.1.1.2 root 1784: @end itemize
1785:
1.1.1.7 root 1786: The Freecom MusicPal internet radio emulation includes the following
1787: elements:
1788:
1789: @itemize @minus
1790: @item
1791: Marvell MV88W8618 ARM core.
1792: @item
1793: 32 MB RAM, 256 KB SRAM, 8 MB flash.
1794: @item
1795: Up to 2 16550 UARTs
1796: @item
1797: MV88W8xx8 Ethernet controller
1798: @item
1799: MV88W8618 audio controller, WM8750 CODEC and mixer
1800: @item
1801: 128�64 display with brightness control
1802: @item
1803: 2 buttons, 2 navigation wheels with button function
1804: @end itemize
1805:
1806: The Siemens SX1 models v1 and v2 (default) basic emulation.
1807: The emulaton includes the following elements:
1808:
1809: @itemize @minus
1810: @item
1811: Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1812: @item
1813: ROM and RAM memories (ROM firmware image can be loaded with -pflash)
1814: V1
1815: 1 Flash of 16MB and 1 Flash of 8MB
1816: V2
1817: 1 Flash of 32MB
1818: @item
1819: On-chip LCD controller
1820: @item
1821: On-chip Real Time Clock
1822: @item
1823: Secure Digital card connected to OMAP MMC/SD host
1824: @item
1825: Three on-chip UARTs
1826: @end itemize
1827:
1.1.1.9 ! root 1828: The "Syborg" Symbian Virtual Platform base model includes the following
! 1829: elements:
! 1830:
! 1831: @itemize @minus
! 1832: @item
! 1833: ARM Cortex-A8 CPU
! 1834: @item
! 1835: Interrupt controller
! 1836: @item
! 1837: Timer
! 1838: @item
! 1839: Real Time Clock
! 1840: @item
! 1841: Keyboard
! 1842: @item
! 1843: Framebuffer
! 1844: @item
! 1845: Touchscreen
! 1846: @item
! 1847: UARTs
! 1848: @end itemize
! 1849:
1.1.1.2 root 1850: A Linux 2.6 test image is available on the QEMU web site. More
1851: information is available in the QEMU mailing-list archive.
1.1 root 1852:
1.1.1.7 root 1853: @c man begin OPTIONS
1854:
1855: The following options are specific to the ARM emulation:
1856:
1857: @table @option
1858:
1859: @item -semihosting
1860: Enable semihosting syscall emulation.
1861:
1862: On ARM this implements the "Angel" interface.
1863:
1864: Note that this allows guest direct access to the host filesystem,
1865: so should only be used with trusted guest OS.
1866:
1867: @end table
1868:
1.1.1.6 root 1869: @node ColdFire System emulator
1870: @section ColdFire System emulator
1871:
1872: Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
1873: The emulator is able to boot a uClinux kernel.
1874:
1875: The M5208EVB emulation includes the following devices:
1876:
1877: @itemize @minus
1878: @item
1879: MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
1880: @item
1881: Three Two on-chip UARTs.
1882: @item
1883: Fast Ethernet Controller (FEC)
1884: @end itemize
1885:
1886: The AN5206 emulation includes the following devices:
1887:
1888: @itemize @minus
1889: @item
1890: MCF5206 ColdFire V2 Microprocessor.
1891: @item
1892: Two on-chip UARTs.
1893: @end itemize
1894:
1.1.1.7 root 1895: @c man begin OPTIONS
1896:
1897: The following options are specific to the ARM emulation:
1898:
1899: @table @option
1900:
1901: @item -semihosting
1902: Enable semihosting syscall emulation.
1903:
1904: On M68K this implements the "ColdFire GDB" interface used by libgloss.
1905:
1906: Note that this allows guest direct access to the host filesystem,
1907: so should only be used with trusted guest OS.
1908:
1909: @end table
1910:
1.1.1.6 root 1911: @node QEMU User space emulator
1912: @chapter QEMU User space emulator
1.1.1.5 root 1913:
1914: @menu
1915: * Supported Operating Systems ::
1916: * Linux User space emulator::
1917: * Mac OS X/Darwin User space emulator ::
1.1.1.7 root 1918: * BSD User space emulator ::
1.1.1.5 root 1919: @end menu
1920:
1921: @node Supported Operating Systems
1922: @section Supported Operating Systems
1923:
1924: The following OS are supported in user space emulation:
1925:
1926: @itemize @minus
1927: @item
1.1.1.6 root 1928: Linux (referred as qemu-linux-user)
1.1.1.5 root 1929: @item
1.1.1.6 root 1930: Mac OS X/Darwin (referred as qemu-darwin-user)
1.1.1.7 root 1931: @item
1932: BSD (referred as qemu-bsd-user)
1.1.1.5 root 1933: @end itemize
1934:
1935: @node Linux User space emulator
1936: @section Linux User space emulator
1.1 root 1937:
1.1.1.3 root 1938: @menu
1939: * Quick Start::
1940: * Wine launch::
1941: * Command line options::
1.1.1.4 root 1942: * Other binaries::
1.1.1.3 root 1943: @end menu
1944:
1945: @node Quick Start
1.1.1.5 root 1946: @subsection Quick Start
1.1 root 1947:
1948: In order to launch a Linux process, QEMU needs the process executable
1.1.1.6 root 1949: itself and all the target (x86) dynamic libraries used by it.
1.1 root 1950:
1951: @itemize
1952:
1953: @item On x86, you can just try to launch any process by using the native
1954: libraries:
1955:
1.1.1.6 root 1956: @example
1.1 root 1957: qemu-i386 -L / /bin/ls
1958: @end example
1959:
1960: @code{-L /} tells that the x86 dynamic linker must be searched with a
1961: @file{/} prefix.
1962:
1.1.1.6 root 1963: @item Since QEMU is also a linux process, you can launch qemu with
1964: qemu (NOTE: you can only do that if you compiled QEMU from the sources):
1.1 root 1965:
1.1.1.6 root 1966: @example
1.1 root 1967: qemu-i386 -L / qemu-i386 -L / /bin/ls
1968: @end example
1969:
1970: @item On non x86 CPUs, you need first to download at least an x86 glibc
1971: (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
1972: @code{LD_LIBRARY_PATH} is not set:
1973:
1974: @example
1.1.1.6 root 1975: unset LD_LIBRARY_PATH
1.1 root 1976: @end example
1977:
1978: Then you can launch the precompiled @file{ls} x86 executable:
1979:
1980: @example
1981: qemu-i386 tests/i386/ls
1982: @end example
1983: You can look at @file{qemu-binfmt-conf.sh} so that
1984: QEMU is automatically launched by the Linux kernel when you try to
1985: launch x86 executables. It requires the @code{binfmt_misc} module in the
1986: Linux kernel.
1987:
1988: @item The x86 version of QEMU is also included. You can try weird things such as:
1989: @example
1.1.1.3 root 1990: qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
1991: /usr/local/qemu-i386/bin/ls-i386
1.1 root 1992: @end example
1993:
1994: @end itemize
1995:
1.1.1.3 root 1996: @node Wine launch
1.1.1.5 root 1997: @subsection Wine launch
1.1 root 1998:
1999: @itemize
2000:
2001: @item Ensure that you have a working QEMU with the x86 glibc
2002: distribution (see previous section). In order to verify it, you must be
2003: able to do:
2004:
2005: @example
2006: qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2007: @end example
2008:
2009: @item Download the binary x86 Wine install
1.1.1.6 root 2010: (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
1.1 root 2011:
2012: @item Configure Wine on your account. Look at the provided script
1.1.1.3 root 2013: @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
1.1 root 2014: @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2015:
2016: @item Then you can try the example @file{putty.exe}:
2017:
2018: @example
1.1.1.3 root 2019: qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2020: /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
1.1 root 2021: @end example
2022:
2023: @end itemize
2024:
1.1.1.3 root 2025: @node Command line options
1.1.1.5 root 2026: @subsection Command line options
1.1 root 2027:
2028: @example
1.1.1.7 root 2029: usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] program [arguments...]
1.1 root 2030: @end example
2031:
2032: @table @option
2033: @item -h
2034: Print the help
1.1.1.6 root 2035: @item -L path
1.1 root 2036: Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2037: @item -s size
2038: Set the x86 stack size in bytes (default=524288)
1.1.1.7 root 2039: @item -cpu model
2040: Select CPU model (-cpu ? for list and additional feature selection)
1.1 root 2041: @end table
2042:
2043: Debug options:
2044:
2045: @table @option
2046: @item -d
2047: Activate log (logfile=/tmp/qemu.log)
2048: @item -p pagesize
2049: Act as if the host page size was 'pagesize' bytes
1.1.1.7 root 2050: @item -g port
2051: Wait gdb connection to port
1.1.1.9 ! root 2052: @item -singlestep
! 2053: Run the emulation in single step mode.
1.1 root 2054: @end table
2055:
1.1.1.6 root 2056: Environment variables:
2057:
2058: @table @env
2059: @item QEMU_STRACE
2060: Print system calls and arguments similar to the 'strace' program
2061: (NOTE: the actual 'strace' program will not work because the user
2062: space emulator hasn't implemented ptrace). At the moment this is
2063: incomplete. All system calls that don't have a specific argument
2064: format are printed with information for six arguments. Many
2065: flag-style arguments don't have decoders and will show up as numbers.
2066: @end table
2067:
1.1.1.4 root 2068: @node Other binaries
1.1.1.5 root 2069: @subsection Other binaries
1.1.1.4 root 2070:
2071: @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2072: binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2073: configurations), and arm-uclinux bFLT format binaries.
2074:
1.1.1.5 root 2075: @command{qemu-m68k} is capable of running semihosted binaries using the BDM
2076: (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2077: coldfire uClinux bFLT format binaries.
2078:
1.1.1.4 root 2079: The binary format is detected automatically.
2080:
1.1.1.7 root 2081: @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2082:
1.1.1.6 root 2083: @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2084: (Sparc64 CPU, 32 bit ABI).
2085:
2086: @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2087: SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2088:
1.1.1.5 root 2089: @node Mac OS X/Darwin User space emulator
2090: @section Mac OS X/Darwin User space emulator
2091:
2092: @menu
2093: * Mac OS X/Darwin Status::
2094: * Mac OS X/Darwin Quick Start::
2095: * Mac OS X/Darwin Command line options::
2096: @end menu
2097:
2098: @node Mac OS X/Darwin Status
2099: @subsection Mac OS X/Darwin Status
2100:
2101: @itemize @minus
2102: @item
2103: target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
2104: @item
2105: target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
2106: @item
1.1.1.6 root 2107: target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
1.1.1.5 root 2108: @item
2109: target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
2110: @end itemize
2111:
2112: [1] If you're host commpage can be executed by qemu.
2113:
2114: @node Mac OS X/Darwin Quick Start
2115: @subsection Quick Start
2116:
2117: In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
2118: itself and all the target dynamic libraries used by it. If you don't have the FAT
2119: libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
2120: CD or compile them by hand.
2121:
2122: @itemize
2123:
2124: @item On x86, you can just try to launch any process by using the native
2125: libraries:
2126:
1.1.1.6 root 2127: @example
2128: qemu-i386 /bin/ls
1.1.1.5 root 2129: @end example
2130:
2131: or to run the ppc version of the executable:
2132:
1.1.1.6 root 2133: @example
2134: qemu-ppc /bin/ls
1.1.1.5 root 2135: @end example
2136:
2137: @item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
2138: are installed:
2139:
1.1.1.6 root 2140: @example
2141: qemu-i386 -L /opt/x86_root/ /bin/ls
1.1.1.5 root 2142: @end example
2143:
2144: @code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
2145: @file{/opt/x86_root/usr/bin/dyld}.
2146:
2147: @end itemize
2148:
2149: @node Mac OS X/Darwin Command line options
2150: @subsection Command line options
2151:
2152: @example
1.1.1.6 root 2153: usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
1.1.1.5 root 2154: @end example
2155:
2156: @table @option
2157: @item -h
2158: Print the help
1.1.1.6 root 2159: @item -L path
1.1.1.5 root 2160: Set the library root path (default=/)
2161: @item -s size
2162: Set the stack size in bytes (default=524288)
2163: @end table
2164:
2165: Debug options:
2166:
2167: @table @option
2168: @item -d
2169: Activate log (logfile=/tmp/qemu.log)
2170: @item -p pagesize
2171: Act as if the host page size was 'pagesize' bytes
1.1.1.9 ! root 2172: @item -singlestep
! 2173: Run the emulation in single step mode.
1.1.1.5 root 2174: @end table
2175:
1.1.1.7 root 2176: @node BSD User space emulator
2177: @section BSD User space emulator
2178:
2179: @menu
2180: * BSD Status::
2181: * BSD Quick Start::
2182: * BSD Command line options::
2183: @end menu
2184:
2185: @node BSD Status
2186: @subsection BSD Status
2187:
2188: @itemize @minus
2189: @item
2190: target Sparc64 on Sparc64: Some trivial programs work.
2191: @end itemize
2192:
2193: @node BSD Quick Start
2194: @subsection Quick Start
2195:
2196: In order to launch a BSD process, QEMU needs the process executable
2197: itself and all the target dynamic libraries used by it.
2198:
2199: @itemize
2200:
2201: @item On Sparc64, you can just try to launch any process by using the native
2202: libraries:
2203:
2204: @example
2205: qemu-sparc64 /bin/ls
2206: @end example
2207:
2208: @end itemize
2209:
2210: @node BSD Command line options
2211: @subsection Command line options
2212:
2213: @example
2214: usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
2215: @end example
2216:
2217: @table @option
2218: @item -h
2219: Print the help
2220: @item -L path
2221: Set the library root path (default=/)
2222: @item -s size
2223: Set the stack size in bytes (default=524288)
2224: @item -bsd type
2225: Set the type of the emulated BSD Operating system. Valid values are
2226: FreeBSD, NetBSD and OpenBSD (default).
2227: @end table
2228:
2229: Debug options:
2230:
2231: @table @option
2232: @item -d
2233: Activate log (logfile=/tmp/qemu.log)
2234: @item -p pagesize
2235: Act as if the host page size was 'pagesize' bytes
1.1.1.9 ! root 2236: @item -singlestep
! 2237: Run the emulation in single step mode.
1.1.1.7 root 2238: @end table
2239:
1.1 root 2240: @node compilation
2241: @chapter Compilation from the sources
2242:
1.1.1.3 root 2243: @menu
2244: * Linux/Unix::
2245: * Windows::
2246: * Cross compilation for Windows with Linux::
2247: * Mac OS X::
2248: @end menu
2249:
2250: @node Linux/Unix
1.1 root 2251: @section Linux/Unix
2252:
2253: @subsection Compilation
2254:
2255: First you must decompress the sources:
2256: @example
2257: cd /tmp
2258: tar zxvf qemu-x.y.z.tar.gz
2259: cd qemu-x.y.z
2260: @end example
2261:
2262: Then you configure QEMU and build it (usually no options are needed):
2263: @example
2264: ./configure
2265: make
2266: @end example
2267:
2268: Then type as root user:
2269: @example
2270: make install
2271: @end example
2272: to install QEMU in @file{/usr/local}.
2273:
1.1.1.3 root 2274: @node Windows
1.1 root 2275: @section Windows
2276:
2277: @itemize
2278: @item Install the current versions of MSYS and MinGW from
2279: @url{http://www.mingw.org/}. You can find detailed installation
2280: instructions in the download section and the FAQ.
2281:
1.1.1.6 root 2282: @item Download
1.1 root 2283: the MinGW development library of SDL 1.2.x
1.1.1.3 root 2284: (@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
1.1 root 2285: @url{http://www.libsdl.org}. Unpack it in a temporary place, and
2286: unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
2287: directory. Edit the @file{sdl-config} script so that it gives the
2288: correct SDL directory when invoked.
2289:
2290: @item Extract the current version of QEMU.
1.1.1.6 root 2291:
1.1 root 2292: @item Start the MSYS shell (file @file{msys.bat}).
2293:
1.1.1.6 root 2294: @item Change to the QEMU directory. Launch @file{./configure} and
1.1 root 2295: @file{make}. If you have problems using SDL, verify that
2296: @file{sdl-config} can be launched from the MSYS command line.
2297:
1.1.1.6 root 2298: @item You can install QEMU in @file{Program Files/Qemu} by typing
1.1 root 2299: @file{make install}. Don't forget to copy @file{SDL.dll} in
2300: @file{Program Files/Qemu}.
2301:
2302: @end itemize
2303:
1.1.1.3 root 2304: @node Cross compilation for Windows with Linux
1.1 root 2305: @section Cross compilation for Windows with Linux
2306:
2307: @itemize
2308: @item
2309: Install the MinGW cross compilation tools available at
2310: @url{http://www.mingw.org/}.
2311:
1.1.1.6 root 2312: @item
1.1 root 2313: Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
2314: unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
2315: variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
2316: the QEMU configuration script.
2317:
1.1.1.6 root 2318: @item
1.1 root 2319: Configure QEMU for Windows cross compilation:
2320: @example
2321: ./configure --enable-mingw32
2322: @end example
2323: If necessary, you can change the cross-prefix according to the prefix
1.1.1.6 root 2324: chosen for the MinGW tools with --cross-prefix. You can also use
1.1 root 2325: --prefix to set the Win32 install path.
2326:
1.1.1.6 root 2327: @item You can install QEMU in the installation directory by typing
1.1 root 2328: @file{make install}. Don't forget to copy @file{SDL.dll} in the
1.1.1.6 root 2329: installation directory.
1.1 root 2330:
2331: @end itemize
2332:
2333: Note: Currently, Wine does not seem able to launch
2334: QEMU for Win32.
2335:
1.1.1.3 root 2336: @node Mac OS X
1.1 root 2337: @section Mac OS X
2338:
2339: The Mac OS X patches are not fully merged in QEMU, so you should look
2340: at the QEMU mailing list archive to have all the necessary
2341: information.
2342:
1.1.1.3 root 2343: @node Index
2344: @chapter Index
2345: @printindex cp
2346:
2347: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.