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