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