qtest: Avoid passing raw strings through hmp()
[qemu.git] / qemu-doc.texi
blob4076226f399661ed8f3ec195e9fdc8d4e0cc47bb
1 \input texinfo @c -*- texinfo -*-
2 @c %**start of header
3 @setfilename qemu-doc.info
4 @include version.texi
6 @documentlanguage en
7 @documentencoding UTF-8
9 @settitle QEMU version @value{VERSION} User Documentation
10 @exampleindent 0
11 @paragraphindent 0
12 @c %**end of header
14 @ifinfo
15 @direntry
16 * QEMU: (qemu-doc).    The QEMU Emulator User Documentation.
17 @end direntry
18 @end ifinfo
20 @iftex
21 @titlepage
22 @sp 7
23 @center @titlefont{QEMU version @value{VERSION}}
24 @sp 1
25 @center @titlefont{User Documentation}
26 @sp 3
27 @end titlepage
28 @end iftex
30 @ifnottex
31 @node Top
32 @top
34 @menu
35 * Introduction::
36 * QEMU PC System emulator::
37 * QEMU System emulator for non PC targets::
38 * QEMU Guest Agent::
39 * QEMU User space emulator::
40 * Implementation notes::
41 * Deprecated features::
42 * License::
43 * Index::
44 @end menu
45 @end ifnottex
47 @contents
49 @node Introduction
50 @chapter Introduction
52 @menu
53 * intro_features:: Features
54 @end menu
56 @node intro_features
57 @section Features
59 QEMU is a FAST! processor emulator using dynamic translation to
60 achieve good emulation speed.
62 @cindex operating modes
63 QEMU has two operating modes:
65 @itemize
66 @cindex system emulation
67 @item Full system emulation. In this mode, QEMU emulates a full system (for
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.
72 @cindex user mode emulation
73 @item User mode emulation. In this mode, QEMU can launch
74 processes compiled for one CPU on another CPU. It can be used to
75 launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
76 to ease cross-compilation and cross-debugging.
78 @end itemize
80 QEMU has the following features:
82 @itemize
83 @item QEMU can run without a host kernel driver and yet gives acceptable
84 performance.  It uses dynamic translation to native code for reasonable speed,
85 with support for self-modifying code and precise exceptions.
87 @item It is portable to several operating systems (GNU/Linux, *BSD, Mac OS X,
88 Windows) and architectures.
90 @item It performs accurate software emulation of the FPU.
91 @end itemize
93 QEMU user mode emulation has the following features:
94 @itemize
95 @item Generic Linux system call converter, including most ioctls.
97 @item clone() emulation using native CPU clone() to use Linux scheduler for threads.
99 @item Accurate signal handling by remapping host signals to target signals.
100 @end itemize
102 QEMU full system emulation has the following features:
103 @itemize
104 @item
105 QEMU uses a full software MMU for maximum portability.
107 @item
108 QEMU can optionally use an in-kernel accelerator, like kvm. The accelerators 
109 execute most of the guest code natively, while
110 continuing to emulate the rest of the machine.
112 @item
113 Various hardware devices can be emulated and in some cases, host
114 devices (e.g. serial and parallel ports, USB, drives) can be used
115 transparently by the guest Operating System. Host device passthrough
116 can be used for talking to external physical peripherals (e.g. a
117 webcam, modem or tape drive).
119 @item
120 Symmetric multiprocessing (SMP) support.  Currently, an in-kernel
121 accelerator is required to use more than one host CPU for emulation.
123 @end itemize
126 @node QEMU PC System emulator
127 @chapter QEMU PC System emulator
128 @cindex system emulation (PC)
130 @menu
131 * pcsys_introduction:: Introduction
132 * pcsys_quickstart::   Quick Start
133 * sec_invocation::     Invocation
134 * pcsys_keys::         Keys in the graphical frontends
135 * mux_keys::           Keys in the character backend multiplexer
136 * pcsys_monitor::      QEMU Monitor
137 * disk_images::        Disk Images
138 * pcsys_network::      Network emulation
139 * pcsys_other_devs::   Other Devices
140 * direct_linux_boot::  Direct Linux Boot
141 * pcsys_usb::          USB emulation
142 * vnc_security::       VNC security
143 * gdb_usage::          GDB usage
144 * pcsys_os_specific::  Target OS specific information
145 @end menu
147 @node pcsys_introduction
148 @section Introduction
150 @c man begin DESCRIPTION
152 The QEMU PC System emulator simulates the
153 following peripherals:
155 @itemize @minus
156 @item
157 i440FX host PCI bridge and PIIX3 PCI to ISA bridge
158 @item
159 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
160 extensions (hardware level, including all non standard modes).
161 @item
162 PS/2 mouse and keyboard
163 @item
164 2 PCI IDE interfaces with hard disk and CD-ROM support
165 @item
166 Floppy disk
167 @item
168 PCI and ISA network adapters
169 @item
170 Serial ports
171 @item
172 IPMI BMC, either and internal or external one
173 @item
174 Creative SoundBlaster 16 sound card
175 @item
176 ENSONIQ AudioPCI ES1370 sound card
177 @item
178 Intel 82801AA AC97 Audio compatible sound card
179 @item
180 Intel HD Audio Controller and HDA codec
181 @item
182 Adlib (OPL2) - Yamaha YM3812 compatible chip
183 @item
184 Gravis Ultrasound GF1 sound card
185 @item
186 CS4231A compatible sound card
187 @item
188 PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.
189 @end itemize
191 SMP is supported with up to 255 CPUs.
193 QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
194 VGA BIOS.
196 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
198 QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
199 by Tibor "TS" Schütz.
201 Note that, by default, GUS shares IRQ(7) with parallel ports and so
202 QEMU must be told to not have parallel ports to have working GUS.
204 @example
205 qemu-system-i386 dos.img -soundhw gus -parallel none
206 @end example
208 Alternatively:
209 @example
210 qemu-system-i386 dos.img -device gus,irq=5
211 @end example
213 Or some other unclaimed IRQ.
215 CS4231A is the chip used in Windows Sound System and GUSMAX products
217 @c man end
219 @node pcsys_quickstart
220 @section Quick Start
221 @cindex quick start
223 Download and uncompress the linux image (@file{linux.img}) and type:
225 @example
226 qemu-system-i386 linux.img
227 @end example
229 Linux should boot and give you a prompt.
231 @node sec_invocation
232 @section Invocation
234 @example
235 @c man begin SYNOPSIS
236 @command{qemu-system-i386} [@var{options}] [@var{disk_image}]
237 @c man end
238 @end example
240 @c man begin OPTIONS
241 @var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
242 targets do not need a disk image.
244 @include qemu-options.texi
246 @c man end
248 @node pcsys_keys
249 @section Keys in the graphical frontends
251 @c man begin OPTIONS
253 During the graphical emulation, you can use special key combinations to change
254 modes. The default key mappings are shown below, but if you use @code{-alt-grab}
255 then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
256 @code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
258 @table @key
259 @item Ctrl-Alt-f
260 @kindex Ctrl-Alt-f
261 Toggle full screen
263 @item Ctrl-Alt-+
264 @kindex Ctrl-Alt-+
265 Enlarge the screen
267 @item Ctrl-Alt--
268 @kindex Ctrl-Alt--
269 Shrink the screen
271 @item Ctrl-Alt-u
272 @kindex Ctrl-Alt-u
273 Restore the screen's un-scaled dimensions
275 @item Ctrl-Alt-n
276 @kindex Ctrl-Alt-n
277 Switch to virtual console 'n'. Standard console mappings are:
278 @table @emph
279 @item 1
280 Target system display
281 @item 2
282 Monitor
283 @item 3
284 Serial port
285 @end table
287 @item Ctrl-Alt
288 @kindex Ctrl-Alt
289 Toggle mouse and keyboard grab.
290 @end table
292 @kindex Ctrl-Up
293 @kindex Ctrl-Down
294 @kindex Ctrl-PageUp
295 @kindex Ctrl-PageDown
296 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
297 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
299 @c man end
301 @node mux_keys
302 @section Keys in the character backend multiplexer
304 @c man begin OPTIONS
306 During emulation, if you are using a character backend multiplexer
307 (which is the default if you are using @option{-nographic}) then
308 several commands are available via an escape sequence. These
309 key sequences all start with an escape character, which is @key{Ctrl-a}
310 by default, but can be changed with @option{-echr}. The list below assumes
311 you're using the default.
313 @table @key
314 @item Ctrl-a h
315 @kindex Ctrl-a h
316 Print this help
317 @item Ctrl-a x
318 @kindex Ctrl-a x
319 Exit emulator
320 @item Ctrl-a s
321 @kindex Ctrl-a s
322 Save disk data back to file (if -snapshot)
323 @item Ctrl-a t
324 @kindex Ctrl-a t
325 Toggle console timestamps
326 @item Ctrl-a b
327 @kindex Ctrl-a b
328 Send break (magic sysrq in Linux)
329 @item Ctrl-a c
330 @kindex Ctrl-a c
331 Rotate between the frontends connected to the multiplexer (usually
332 this switches between the monitor and the console)
333 @item Ctrl-a Ctrl-a
334 @kindex Ctrl-a Ctrl-a
335 Send the escape character to the frontend
336 @end table
337 @c man end
339 @ignore
341 @c man begin SEEALSO
342 The HTML documentation of QEMU for more precise information and Linux
343 user mode emulator invocation.
344 @c man end
346 @c man begin AUTHOR
347 Fabrice Bellard
348 @c man end
350 @end ignore
352 @node pcsys_monitor
353 @section QEMU Monitor
354 @cindex QEMU monitor
356 The QEMU monitor is used to give complex commands to the QEMU
357 emulator. You can use it to:
359 @itemize @minus
361 @item
362 Remove or insert removable media images
363 (such as CD-ROM or floppies).
365 @item
366 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
367 from a disk file.
369 @item Inspect the VM state without an external debugger.
371 @end itemize
373 @subsection Commands
375 The following commands are available:
377 @include qemu-monitor.texi
379 @include qemu-monitor-info.texi
381 @subsection Integer expressions
383 The monitor understands integers expressions for every integer
384 argument. You can use register names to get the value of specifics
385 CPU registers by prefixing them with @emph{$}.
387 @node disk_images
388 @section Disk Images
390 QEMU supports many disk image formats, including growable disk images
391 (their size increase as non empty sectors are written), compressed and
392 encrypted disk images.
394 @menu
395 * disk_images_quickstart::    Quick start for disk image creation
396 * disk_images_snapshot_mode:: Snapshot mode
397 * vm_snapshots::              VM snapshots
398 * qemu_img_invocation::       qemu-img Invocation
399 * qemu_nbd_invocation::       qemu-nbd Invocation
400 * disk_images_formats::       Disk image file formats
401 * host_drives::               Using host drives
402 * disk_images_fat_images::    Virtual FAT disk images
403 * disk_images_nbd::           NBD access
404 * disk_images_sheepdog::      Sheepdog disk images
405 * disk_images_iscsi::         iSCSI LUNs
406 * disk_images_gluster::       GlusterFS disk images
407 * disk_images_ssh::           Secure Shell (ssh) disk images
408 @end menu
410 @node disk_images_quickstart
411 @subsection Quick start for disk image creation
413 You can create a disk image with the command:
414 @example
415 qemu-img create myimage.img mysize
416 @end example
417 where @var{myimage.img} is the disk image filename and @var{mysize} is its
418 size in kilobytes. You can add an @code{M} suffix to give the size in
419 megabytes and a @code{G} suffix for gigabytes.
421 See @ref{qemu_img_invocation} for more information.
423 @node disk_images_snapshot_mode
424 @subsection Snapshot mode
426 If you use the option @option{-snapshot}, all disk images are
427 considered as read only. When sectors in written, they are written in
428 a temporary file created in @file{/tmp}. You can however force the
429 write back to the raw disk images by using the @code{commit} monitor
430 command (or @key{C-a s} in the serial console).
432 @node vm_snapshots
433 @subsection VM snapshots
435 VM snapshots are snapshots of the complete virtual machine including
436 CPU state, RAM, device state and the content of all the writable
437 disks. In order to use VM snapshots, you must have at least one non
438 removable and writable block device using the @code{qcow2} disk image
439 format. Normally this device is the first virtual hard drive.
441 Use the monitor command @code{savevm} to create a new VM snapshot or
442 replace an existing one. A human readable name can be assigned to each
443 snapshot in addition to its numerical ID.
445 Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
446 a VM snapshot. @code{info snapshots} lists the available snapshots
447 with their associated information:
449 @example
450 (qemu) info snapshots
451 Snapshot devices: hda
452 Snapshot list (from hda):
453 ID        TAG                 VM SIZE                DATE       VM CLOCK
454 1         start                   41M 2006-08-06 12:38:02   00:00:14.954
455 2                                 40M 2006-08-06 12:43:29   00:00:18.633
456 3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
457 @end example
459 A VM snapshot is made of a VM state info (its size is shown in
460 @code{info snapshots}) and a snapshot of every writable disk image.
461 The VM state info is stored in the first @code{qcow2} non removable
462 and writable block device. The disk image snapshots are stored in
463 every disk image. The size of a snapshot in a disk image is difficult
464 to evaluate and is not shown by @code{info snapshots} because the
465 associated disk sectors are shared among all the snapshots to save
466 disk space (otherwise each snapshot would need a full copy of all the
467 disk images).
469 When using the (unrelated) @code{-snapshot} option
470 (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
471 but they are deleted as soon as you exit QEMU.
473 VM snapshots currently have the following known limitations:
474 @itemize
475 @item
476 They cannot cope with removable devices if they are removed or
477 inserted after a snapshot is done.
478 @item
479 A few device drivers still have incomplete snapshot support so their
480 state is not saved or restored properly (in particular USB).
481 @end itemize
483 @node qemu_img_invocation
484 @subsection @code{qemu-img} Invocation
486 @include qemu-img.texi
488 @node qemu_nbd_invocation
489 @subsection @code{qemu-nbd} Invocation
491 @include qemu-nbd.texi
493 @node disk_images_formats
494 @subsection Disk image file formats
496 QEMU supports many image file formats that can be used with VMs as well as with
497 any of the tools (like @code{qemu-img}). This includes the preferred formats
498 raw and qcow2 as well as formats that are supported for compatibility with
499 older QEMU versions or other hypervisors.
501 Depending on the image format, different options can be passed to
502 @code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.
503 This section describes each format and the options that are supported for it.
505 @table @option
506 @item raw
508 Raw disk image format. This format has the advantage of
509 being simple and easily exportable to all other emulators. If your
510 file system supports @emph{holes} (for example in ext2 or ext3 on
511 Linux or NTFS on Windows), then only the written sectors will reserve
512 space. Use @code{qemu-img info} to know the real size used by the
513 image or @code{ls -ls} on Unix/Linux.
515 Supported options:
516 @table @code
517 @item preallocation
518 Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
519 @code{falloc} mode preallocates space for image by calling posix_fallocate().
520 @code{full} mode preallocates space for image by writing zeros to underlying
521 storage.
522 @end table
524 @item qcow2
525 QEMU image format, the most versatile format. Use it to have smaller
526 images (useful if your filesystem does not supports holes, for example
527 on Windows), zlib based compression and support of multiple VM
528 snapshots.
530 Supported options:
531 @table @code
532 @item compat
533 Determines the qcow2 version to use. @code{compat=0.10} uses the
534 traditional image format that can be read by any QEMU since 0.10.
535 @code{compat=1.1} enables image format extensions that only QEMU 1.1 and
536 newer understand (this is the default). Amongst others, this includes
537 zero clusters, which allow efficient copy-on-read for sparse images.
539 @item backing_file
540 File name of a base image (see @option{create} subcommand)
541 @item backing_fmt
542 Image format of the base image
543 @item encryption
544 This option is deprecated and equivalent to @code{encrypt.format=aes}
546 @item encrypt.format
548 If this is set to @code{luks}, it requests that the qcow2 payload (not
549 qcow2 header) be encrypted using the LUKS format. The passphrase to
550 use to unlock the LUKS key slot is given by the @code{encrypt.key-secret}
551 parameter. LUKS encryption parameters can be tuned with the other
552 @code{encrypt.*} parameters.
554 If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.
555 The encryption key is given by the @code{encrypt.key-secret} parameter.
556 This encryption format is considered to be flawed by modern cryptography
557 standards, suffering from a number of design problems:
559 @itemize @minus
560 @item The AES-CBC cipher is used with predictable initialization vectors based
561 on the sector number. This makes it vulnerable to chosen plaintext attacks
562 which can reveal the existence of encrypted data.
563 @item The user passphrase is directly used as the encryption key. A poorly
564 chosen or short passphrase will compromise the security of the encryption.
565 @item In the event of the passphrase being compromised there is no way to
566 change the passphrase to protect data in any qcow images. The files must
567 be cloned, using a different encryption passphrase in the new file. The
568 original file must then be securely erased using a program like shred,
569 though even this is ineffective with many modern storage technologies.
570 @end itemize
572 The use of this is no longer supported in system emulators. Support only
573 remains in the command line utilities, for the purposes of data liberation
574 and interoperability with old versions of QEMU. The @code{luks} format
575 should be used instead.
577 @item encrypt.key-secret
579 Provides the ID of a @code{secret} object that contains the passphrase
580 (@code{encrypt.format=luks}) or encryption key (@code{encrypt.format=aes}).
582 @item encrypt.cipher-alg
584 Name of the cipher algorithm and key length. Currently defaults
585 to @code{aes-256}. Only used when @code{encrypt.format=luks}.
587 @item encrypt.cipher-mode
589 Name of the encryption mode to use. Currently defaults to @code{xts}.
590 Only used when @code{encrypt.format=luks}.
592 @item encrypt.ivgen-alg
594 Name of the initialization vector generator algorithm. Currently defaults
595 to @code{plain64}. Only used when @code{encrypt.format=luks}.
597 @item encrypt.ivgen-hash-alg
599 Name of the hash algorithm to use with the initialization vector generator
600 (if required). Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.
602 @item encrypt.hash-alg
604 Name of the hash algorithm to use for PBKDF algorithm
605 Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.
607 @item encrypt.iter-time
609 Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
610 Defaults to @code{2000}. Only used when @code{encrypt.format=luks}.
612 @item cluster_size
613 Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
614 sizes can improve the image file size whereas larger cluster sizes generally
615 provide better performance.
617 @item preallocation
618 Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},
619 @code{full}). An image with preallocated metadata is initially larger but can
620 improve performance when the image needs to grow. @code{falloc} and @code{full}
621 preallocations are like the same options of @code{raw} format, but sets up
622 metadata also.
624 @item lazy_refcounts
625 If this option is set to @code{on}, reference count updates are postponed with
626 the goal of avoiding metadata I/O and improving performance. This is
627 particularly interesting with @option{cache=writethrough} which doesn't batch
628 metadata updates. The tradeoff is that after a host crash, the reference count
629 tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
630 check -r all} is required, which may take some time.
632 This option can only be enabled if @code{compat=1.1} is specified.
634 @item nocow
635 If this option is set to @code{on}, it will turn off COW of the file. It's only
636 valid on btrfs, no effect on other file systems.
638 Btrfs has low performance when hosting a VM image file, even more when the guest
639 on the VM also using btrfs as file system. Turning off COW is a way to mitigate
640 this bad performance. Generally there are two ways to turn off COW on btrfs:
641 a) Disable it by mounting with nodatacow, then all newly created files will be
642 NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option
643 does.
645 Note: this option is only valid to new or empty files. If there is an existing
646 file which is COW and has data blocks already, it couldn't be changed to NOCOW
647 by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if
648 the NOCOW flag is set or not (Capital 'C' is NOCOW flag).
650 @end table
652 @item qed
653 Old QEMU image format with support for backing files and compact image files
654 (when your filesystem or transport medium does not support holes).
656 When converting QED images to qcow2, you might want to consider using the
657 @code{lazy_refcounts=on} option to get a more QED-like behaviour.
659 Supported options:
660 @table @code
661 @item backing_file
662 File name of a base image (see @option{create} subcommand).
663 @item backing_fmt
664 Image file format of backing file (optional).  Useful if the format cannot be
665 autodetected because it has no header, like some vhd/vpc files.
666 @item cluster_size
667 Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
668 cluster sizes can improve the image file size whereas larger cluster sizes
669 generally provide better performance.
670 @item table_size
671 Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
672 and 16).  There is normally no need to change this value but this option can be
673 used for performance benchmarking.
674 @end table
676 @item qcow
677 Old QEMU image format with support for backing files, compact image files,
678 encryption and compression.
680 Supported options:
681 @table @code
682 @item backing_file
683 File name of a base image (see @option{create} subcommand)
684 @item encryption
685 This option is deprecated and equivalent to @code{encrypt.format=aes}
687 @item encrypt.format
688 If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.
689 The encryption key is given by the @code{encrypt.key-secret} parameter.
690 This encryption format is considered to be flawed by modern cryptography
691 standards, suffering from a number of design problems enumerated previously
692 against the @code{qcow2} image format.
694 The use of this is no longer supported in system emulators. Support only
695 remains in the command line utilities, for the purposes of data liberation
696 and interoperability with old versions of QEMU.
698 Users requiring native encryption should use the @code{qcow2} format
699 instead with @code{encrypt.format=luks}.
701 @item encrypt.key-secret
703 Provides the ID of a @code{secret} object that contains the encryption
704 key (@code{encrypt.format=aes}).
706 @end table
708 @item luks
710 LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
712 Supported options:
713 @table @code
715 @item key-secret
717 Provides the ID of a @code{secret} object that contains the passphrase.
719 @item cipher-alg
721 Name of the cipher algorithm and key length. Currently defaults
722 to @code{aes-256}.
724 @item cipher-mode
726 Name of the encryption mode to use. Currently defaults to @code{xts}.
728 @item ivgen-alg
730 Name of the initialization vector generator algorithm. Currently defaults
731 to @code{plain64}.
733 @item ivgen-hash-alg
735 Name of the hash algorithm to use with the initialization vector generator
736 (if required). Defaults to @code{sha256}.
738 @item hash-alg
740 Name of the hash algorithm to use for PBKDF algorithm
741 Defaults to @code{sha256}.
743 @item iter-time
745 Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
746 Defaults to @code{2000}.
748 @end table
750 @item vdi
751 VirtualBox 1.1 compatible image format.
752 Supported options:
753 @table @code
754 @item static
755 If this option is set to @code{on}, the image is created with metadata
756 preallocation.
757 @end table
759 @item vmdk
760 VMware 3 and 4 compatible image format.
762 Supported options:
763 @table @code
764 @item backing_file
765 File name of a base image (see @option{create} subcommand).
766 @item compat6
767 Create a VMDK version 6 image (instead of version 4)
768 @item hwversion
769 Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
770 if hwversion is specified.
771 @item subformat
772 Specifies which VMDK subformat to use. Valid options are
773 @code{monolithicSparse} (default),
774 @code{monolithicFlat},
775 @code{twoGbMaxExtentSparse},
776 @code{twoGbMaxExtentFlat} and
777 @code{streamOptimized}.
778 @end table
780 @item vpc
781 VirtualPC compatible image format (VHD).
782 Supported options:
783 @table @code
784 @item subformat
785 Specifies which VHD subformat to use. Valid options are
786 @code{dynamic} (default) and @code{fixed}.
787 @end table
789 @item VHDX
790 Hyper-V compatible image format (VHDX).
791 Supported options:
792 @table @code
793 @item subformat
794 Specifies which VHDX subformat to use. Valid options are
795 @code{dynamic} (default) and @code{fixed}.
796 @item block_state_zero
797 Force use of payload blocks of type 'ZERO'.  Can be set to @code{on} (default)
798 or @code{off}.  When set to @code{off}, new blocks will be created as
799 @code{PAYLOAD_BLOCK_NOT_PRESENT}, which means parsers are free to return
800 arbitrary data for those blocks.  Do not set to @code{off} when using
801 @code{qemu-img convert} with @code{subformat=dynamic}.
802 @item block_size
803 Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on image size.
804 @item log_size
805 Log size; min 1 MB.
806 @end table
807 @end table
809 @subsubsection Read-only formats
810 More disk image file formats are supported in a read-only mode.
811 @table @option
812 @item bochs
813 Bochs images of @code{growing} type.
814 @item cloop
815 Linux Compressed Loop image, useful only to reuse directly compressed
816 CD-ROM images present for example in the Knoppix CD-ROMs.
817 @item dmg
818 Apple disk image.
819 @item parallels
820 Parallels disk image format.
821 @end table
824 @node host_drives
825 @subsection Using host drives
827 In addition to disk image files, QEMU can directly access host
828 devices. We describe here the usage for QEMU version >= 0.8.3.
830 @subsubsection Linux
832 On Linux, you can directly use the host device filename instead of a
833 disk image filename provided you have enough privileges to access
834 it. For example, use @file{/dev/cdrom} to access to the CDROM.
836 @table @code
837 @item CD
838 You can specify a CDROM device even if no CDROM is loaded. QEMU has
839 specific code to detect CDROM insertion or removal. CDROM ejection by
840 the guest OS is supported. Currently only data CDs are supported.
841 @item Floppy
842 You can specify a floppy device even if no floppy is loaded. Floppy
843 removal is currently not detected accurately (if you change floppy
844 without doing floppy access while the floppy is not loaded, the guest
845 OS will think that the same floppy is loaded).
846 Use of the host's floppy device is deprecated, and support for it will
847 be removed in a future release.
848 @item Hard disks
849 Hard disks can be used. Normally you must specify the whole disk
850 (@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
851 see it as a partitioned disk. WARNING: unless you know what you do, it
852 is better to only make READ-ONLY accesses to the hard disk otherwise
853 you may corrupt your host data (use the @option{-snapshot} command
854 line option or modify the device permissions accordingly).
855 @end table
857 @subsubsection Windows
859 @table @code
860 @item CD
861 The preferred syntax is the drive letter (e.g. @file{d:}). The
862 alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
863 supported as an alias to the first CDROM drive.
865 Currently there is no specific code to handle removable media, so it
866 is better to use the @code{change} or @code{eject} monitor commands to
867 change or eject media.
868 @item Hard disks
869 Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
870 where @var{N} is the drive number (0 is the first hard disk).
872 WARNING: unless you know what you do, it is better to only make
873 READ-ONLY accesses to the hard disk otherwise you may corrupt your
874 host data (use the @option{-snapshot} command line so that the
875 modifications are written in a temporary file).
876 @end table
879 @subsubsection Mac OS X
881 @file{/dev/cdrom} is an alias to the first CDROM.
883 Currently there is no specific code to handle removable media, so it
884 is better to use the @code{change} or @code{eject} monitor commands to
885 change or eject media.
887 @node disk_images_fat_images
888 @subsection Virtual FAT disk images
890 QEMU can automatically create a virtual FAT disk image from a
891 directory tree. In order to use it, just type:
893 @example
894 qemu-system-i386 linux.img -hdb fat:/my_directory
895 @end example
897 Then you access access to all the files in the @file{/my_directory}
898 directory without having to copy them in a disk image or to export
899 them via SAMBA or NFS. The default access is @emph{read-only}.
901 Floppies can be emulated with the @code{:floppy:} option:
903 @example
904 qemu-system-i386 linux.img -fda fat:floppy:/my_directory
905 @end example
907 A read/write support is available for testing (beta stage) with the
908 @code{:rw:} option:
910 @example
911 qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
912 @end example
914 What you should @emph{never} do:
915 @itemize
916 @item use non-ASCII filenames ;
917 @item use "-snapshot" together with ":rw:" ;
918 @item expect it to work when loadvm'ing ;
919 @item write to the FAT directory on the host system while accessing it with the guest system.
920 @end itemize
922 @node disk_images_nbd
923 @subsection NBD access
925 QEMU can access directly to block device exported using the Network Block Device
926 protocol.
928 @example
929 qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
930 @end example
932 If the NBD server is located on the same host, you can use an unix socket instead
933 of an inet socket:
935 @example
936 qemu-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket
937 @end example
939 In this case, the block device must be exported using qemu-nbd:
941 @example
942 qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
943 @end example
945 The use of qemu-nbd allows sharing of a disk between several guests:
946 @example
947 qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
948 @end example
950 @noindent
951 and then you can use it with two guests:
952 @example
953 qemu-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
954 qemu-system-i386 linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
955 @end example
957 If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
958 own embedded NBD server), you must specify an export name in the URI:
959 @example
960 qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst
961 qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
962 @end example
964 The URI syntax for NBD is supported since QEMU 1.3.  An alternative syntax is
965 also available.  Here are some example of the older syntax:
966 @example
967 qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
968 qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket
969 qemu-system-i386 -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
970 @end example
972 @node disk_images_sheepdog
973 @subsection Sheepdog disk images
975 Sheepdog is a distributed storage system for QEMU.  It provides highly
976 available block level storage volumes that can be attached to
977 QEMU-based virtual machines.
979 You can create a Sheepdog disk image with the command:
980 @example
981 qemu-img create sheepdog:///@var{image} @var{size}
982 @end example
983 where @var{image} is the Sheepdog image name and @var{size} is its
984 size.
986 To import the existing @var{filename} to Sheepdog, you can use a
987 convert command.
988 @example
989 qemu-img convert @var{filename} sheepdog:///@var{image}
990 @end example
992 You can boot from the Sheepdog disk image with the command:
993 @example
994 qemu-system-i386 sheepdog:///@var{image}
995 @end example
997 You can also create a snapshot of the Sheepdog image like qcow2.
998 @example
999 qemu-img snapshot -c @var{tag} sheepdog:///@var{image}
1000 @end example
1001 where @var{tag} is a tag name of the newly created snapshot.
1003 To boot from the Sheepdog snapshot, specify the tag name of the
1004 snapshot.
1005 @example
1006 qemu-system-i386 sheepdog:///@var{image}#@var{tag}
1007 @end example
1009 You can create a cloned image from the existing snapshot.
1010 @example
1011 qemu-img create -b sheepdog:///@var{base}#@var{tag} sheepdog:///@var{image}
1012 @end example
1013 where @var{base} is a image name of the source snapshot and @var{tag}
1014 is its tag name.
1016 You can use an unix socket instead of an inet socket:
1018 @example
1019 qemu-system-i386 sheepdog+unix:///@var{image}?socket=@var{path}
1020 @end example
1022 If the Sheepdog daemon doesn't run on the local host, you need to
1023 specify one of the Sheepdog servers to connect to.
1024 @example
1025 qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size}
1026 qemu-system-i386 sheepdog://@var{hostname}:@var{port}/@var{image}
1027 @end example
1029 @node disk_images_iscsi
1030 @subsection iSCSI LUNs
1032 iSCSI is a popular protocol used to access SCSI devices across a computer
1033 network.
1035 There are two different ways iSCSI devices can be used by QEMU.
1037 The first method is to mount the iSCSI LUN on the host, and make it appear as
1038 any other ordinary SCSI device on the host and then to access this device as a
1039 /dev/sd device from QEMU. How to do this differs between host OSes.
1041 The second method involves using the iSCSI initiator that is built into
1042 QEMU. This provides a mechanism that works the same way regardless of which
1043 host OS you are running QEMU on. This section will describe this second method
1044 of using iSCSI together with QEMU.
1046 In QEMU, iSCSI devices are described using special iSCSI URLs
1048 @example
1049 URL syntax:
1050 iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
1051 @end example
1053 Username and password are optional and only used if your target is set up
1054 using CHAP authentication for access control.
1055 Alternatively the username and password can also be set via environment
1056 variables to have these not show up in the process list
1058 @example
1059 export LIBISCSI_CHAP_USERNAME=<username>
1060 export LIBISCSI_CHAP_PASSWORD=<password>
1061 iscsi://<host>/<target-iqn-name>/<lun>
1062 @end example
1064 Various session related parameters can be set via special options, either
1065 in a configuration file provided via '-readconfig' or directly on the
1066 command line.
1068 If the initiator-name is not specified qemu will use a default name
1069 of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the
1070 virtual machine. If the UUID is not specified qemu will use
1071 'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
1072 virtual machine.
1074 @example
1075 Setting a specific initiator name to use when logging in to the target
1076 -iscsi initiator-name=iqn.qemu.test:my-initiator
1077 @end example
1079 @example
1080 Controlling which type of header digest to negotiate with the target
1081 -iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
1082 @end example
1084 These can also be set via a configuration file
1085 @example
1086 [iscsi]
1087   user = "CHAP username"
1088   password = "CHAP password"
1089   initiator-name = "iqn.qemu.test:my-initiator"
1090   # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
1091   header-digest = "CRC32C"
1092 @end example
1095 Setting the target name allows different options for different targets
1096 @example
1097 [iscsi "iqn.target.name"]
1098   user = "CHAP username"
1099   password = "CHAP password"
1100   initiator-name = "iqn.qemu.test:my-initiator"
1101   # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
1102   header-digest = "CRC32C"
1103 @end example
1106 Howto use a configuration file to set iSCSI configuration options:
1107 @example
1108 cat >iscsi.conf <<EOF
1109 [iscsi]
1110   user = "me"
1111   password = "my password"
1112   initiator-name = "iqn.qemu.test:my-initiator"
1113   header-digest = "CRC32C"
1116 qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
1117     -readconfig iscsi.conf
1118 @end example
1121 Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
1122 @example
1123 This example shows how to set up an iSCSI target with one CDROM and one DISK
1124 using the Linux STGT software target. This target is available on Red Hat based
1125 systems as the package 'scsi-target-utils'.
1127 tgtd --iscsi portal=127.0.0.1:3260
1128 tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
1129 tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
1130     -b /IMAGES/disk.img --device-type=disk
1131 tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
1132     -b /IMAGES/cd.iso --device-type=cd
1133 tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
1135 qemu-system-i386 -iscsi initiator-name=iqn.qemu.test:my-initiator \
1136     -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
1137     -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
1138 @end example
1140 @node disk_images_gluster
1141 @subsection GlusterFS disk images
1143 GlusterFS is a user space distributed file system.
1145 You can boot from the GlusterFS disk image with the command:
1146 @example
1147 URI:
1148 qemu-system-x86_64 -drive file=gluster[+@var{type}]://[@var{host}[:@var{port}]]/@var{volume}/@var{path}
1149                                [?socket=...][,file.debug=9][,file.logfile=...]
1151 JSON:
1152 qemu-system-x86_64 'json:@{"driver":"qcow2",
1153                            "file":@{"driver":"gluster",
1154                                     "volume":"testvol","path":"a.img","debug":9,"logfile":"...",
1155                                     "server":[@{"type":"tcp","host":"...","port":"..."@},
1156                                               @{"type":"unix","socket":"..."@}]@}@}'
1157 @end example
1159 @var{gluster} is the protocol.
1161 @var{type} specifies the transport type used to connect to gluster
1162 management daemon (glusterd). Valid transport types are
1163 tcp and unix. In the URI form, if a transport type isn't specified,
1164 then tcp type is assumed.
1166 @var{host} specifies the server where the volume file specification for
1167 the given volume resides. This can be either a hostname or an ipv4 address.
1168 If transport type is unix, then @var{host} field should not be specified.
1169 Instead @var{socket} field needs to be populated with the path to unix domain
1170 socket.
1172 @var{port} is the port number on which glusterd is listening. This is optional
1173 and if not specified, it defaults to port 24007. If the transport type is unix,
1174 then @var{port} should not be specified.
1176 @var{volume} is the name of the gluster volume which contains the disk image.
1178 @var{path} is the path to the actual disk image that resides on gluster volume.
1180 @var{debug} is the logging level of the gluster protocol driver. Debug levels
1181 are 0-9, with 9 being the most verbose, and 0 representing no debugging output.
1182 The default level is 4. The current logging levels defined in the gluster source
1183 are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning,
1184 6 - Notice, 7 - Info, 8 - Debug, 9 - Trace
1186 @var{logfile} is a commandline option to mention log file path which helps in
1187 logging to the specified file and also help in persisting the gfapi logs. The
1188 default is stderr.
1193 You can create a GlusterFS disk image with the command:
1194 @example
1195 qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size}
1196 @end example
1198 Examples
1199 @example
1200 qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img
1201 qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4/testvol/a.img
1202 qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
1203 qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
1204 qemu-system-x86_64 -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
1205 qemu-system-x86_64 -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
1206 qemu-system-x86_64 -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
1207 qemu-system-x86_64 -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
1208 qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
1209 qemu-system-x86_64 'json:@{"driver":"qcow2",
1210                            "file":@{"driver":"gluster",
1211                                     "volume":"testvol","path":"a.img",
1212                                     "debug":9,"logfile":"/var/log/qemu-gluster.log",
1213                                     "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
1214                                               @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
1215 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
1216                                        file.debug=9,file.logfile=/var/log/qemu-gluster.log,
1217                                        file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
1218                                        file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
1219 @end example
1221 @node disk_images_ssh
1222 @subsection Secure Shell (ssh) disk images
1224 You can access disk images located on a remote ssh server
1225 by using the ssh protocol:
1227 @example
1228 qemu-system-x86_64 -drive file=ssh://[@var{user}@@]@var{server}[:@var{port}]/@var{path}[?host_key_check=@var{host_key_check}]
1229 @end example
1231 Alternative syntax using properties:
1233 @example
1234 qemu-system-x86_64 -drive file.driver=ssh[,file.user=@var{user}],file.host=@var{server}[,file.port=@var{port}],file.path=@var{path}[,file.host_key_check=@var{host_key_check}]
1235 @end example
1237 @var{ssh} is the protocol.
1239 @var{user} is the remote user.  If not specified, then the local
1240 username is tried.
1242 @var{server} specifies the remote ssh server.  Any ssh server can be
1243 used, but it must implement the sftp-server protocol.  Most Unix/Linux
1244 systems should work without requiring any extra configuration.
1246 @var{port} is the port number on which sshd is listening.  By default
1247 the standard ssh port (22) is used.
1249 @var{path} is the path to the disk image.
1251 The optional @var{host_key_check} parameter controls how the remote
1252 host's key is checked.  The default is @code{yes} which means to use
1253 the local @file{.ssh/known_hosts} file.  Setting this to @code{no}
1254 turns off known-hosts checking.  Or you can check that the host key
1255 matches a specific fingerprint:
1256 @code{host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8}
1257 (@code{sha1:} can also be used as a prefix, but note that OpenSSH
1258 tools only use MD5 to print fingerprints).
1260 Currently authentication must be done using ssh-agent.  Other
1261 authentication methods may be supported in future.
1263 Note: Many ssh servers do not support an @code{fsync}-style operation.
1264 The ssh driver cannot guarantee that disk flush requests are
1265 obeyed, and this causes a risk of disk corruption if the remote
1266 server or network goes down during writes.  The driver will
1267 print a warning when @code{fsync} is not supported:
1269 warning: ssh server @code{ssh.example.com:22} does not support fsync
1271 With sufficiently new versions of libssh2 and OpenSSH, @code{fsync} is
1272 supported.
1274 @node pcsys_network
1275 @section Network emulation
1277 QEMU can simulate several network cards (PCI or ISA cards on the PC
1278 target) and can connect them to an arbitrary number of Virtual Local
1279 Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1280 VLAN. VLAN can be connected between separate instances of QEMU to
1281 simulate large networks. For simpler usage, a non privileged user mode
1282 network stack can replace the TAP device to have a basic network
1283 connection.
1285 @subsection VLANs
1287 QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1288 connection between several network devices. These devices can be for
1289 example QEMU virtual Ethernet cards or virtual Host ethernet devices
1290 (TAP devices).
1292 @subsection Using TAP network interfaces
1294 This is the standard way to connect QEMU to a real network. QEMU adds
1295 a virtual network device on your host (called @code{tapN}), and you
1296 can then configure it as if it was a real ethernet card.
1298 @subsubsection Linux host
1300 As an example, you can download the @file{linux-test-xxx.tar.gz}
1301 archive and copy the script @file{qemu-ifup} in @file{/etc} and
1302 configure properly @code{sudo} so that the command @code{ifconfig}
1303 contained in @file{qemu-ifup} can be executed as root. You must verify
1304 that your host kernel supports the TAP network interfaces: the
1305 device @file{/dev/net/tun} must be present.
1307 See @ref{sec_invocation} to have examples of command lines using the
1308 TAP network interfaces.
1310 @subsubsection Windows host
1312 There is a virtual ethernet driver for Windows 2000/XP systems, called
1313 TAP-Win32. But it is not included in standard QEMU for Windows,
1314 so you will need to get it separately. It is part of OpenVPN package,
1315 so download OpenVPN from : @url{http://openvpn.net/}.
1317 @subsection Using the user mode network stack
1319 By using the option @option{-net user} (default configuration if no
1320 @option{-net} option is specified), QEMU uses a completely user mode
1321 network stack (you don't need root privilege to use the virtual
1322 network). The virtual network configuration is the following:
1324 @example
1326          QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
1327                            |          (10.0.2.2)
1328                            |
1329                            ---->  DNS server (10.0.2.3)
1330                            |
1331                            ---->  SMB server (10.0.2.4)
1332 @end example
1334 The QEMU VM behaves as if it was behind a firewall which blocks all
1335 incoming connections. You can use a DHCP client to automatically
1336 configure the network in the QEMU VM. The DHCP server assign addresses
1337 to the hosts starting from 10.0.2.15.
1339 In order to check that the user mode network is working, you can ping
1340 the address 10.0.2.2 and verify that you got an address in the range
1341 10.0.2.x from the QEMU virtual DHCP server.
1343 Note that ICMP traffic in general does not work with user mode networking.
1344 @code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
1345 however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
1346 ping sockets to allow @code{ping} to the Internet. The host admin has to set
1347 the ping_group_range in order to grant access to those sockets. To allow ping
1348 for GID 100 (usually users group):
1350 @example
1351 echo 100 100 > /proc/sys/net/ipv4/ping_group_range
1352 @end example
1354 When using the built-in TFTP server, the router is also the TFTP
1355 server.
1357 When using the @option{'-netdev user,hostfwd=...'} option, TCP or UDP
1358 connections can be redirected from the host to the guest. It allows for
1359 example to redirect X11, telnet or SSH connections.
1361 @subsection Connecting VLANs between QEMU instances
1363 Using the @option{-net socket} option, it is possible to make VLANs
1364 that span several QEMU instances. See @ref{sec_invocation} to have a
1365 basic example.
1367 @node pcsys_other_devs
1368 @section Other Devices
1370 @subsection Inter-VM Shared Memory device
1372 On Linux hosts, a shared memory device is available.  The basic syntax
1375 @example
1376 qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem}
1377 @end example
1379 where @var{hostmem} names a host memory backend.  For a POSIX shared
1380 memory backend, use something like
1382 @example
1383 -object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
1384 @end example
1386 If desired, interrupts can be sent between guest VMs accessing the same shared
1387 memory region.  Interrupt support requires using a shared memory server and
1388 using a chardev socket to connect to it.  The code for the shared memory server
1389 is qemu.git/contrib/ivshmem-server.  An example syntax when using the shared
1390 memory server is:
1392 @example
1393 # First start the ivshmem server once and for all
1394 ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}
1396 # Then start your qemu instances with matching arguments
1397 qemu-system-x86_64 -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
1398                  -chardev socket,path=@var{path},id=@var{id}
1399 @end example
1401 When using the server, the guest will be assigned a VM ID (>=0) that allows guests
1402 using the same server to communicate via interrupts.  Guests can read their
1403 VM ID from a device register (see ivshmem-spec.txt).
1405 @subsubsection Migration with ivshmem
1407 With device property @option{master=on}, the guest will copy the shared
1408 memory on migration to the destination host.  With @option{master=off},
1409 the guest will not be able to migrate with the device attached.  In the
1410 latter case, the device should be detached and then reattached after
1411 migration using the PCI hotplug support.
1413 At most one of the devices sharing the same memory can be master.  The
1414 master must complete migration before you plug back the other devices.
1416 @subsubsection ivshmem and hugepages
1418 Instead of specifying the <shm size> using POSIX shm, you may specify
1419 a memory backend that has hugepage support:
1421 @example
1422 qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
1423                  -device ivshmem-plain,memdev=mb1
1424 @end example
1426 ivshmem-server also supports hugepages mount points with the
1427 @option{-m} memory path argument.
1429 @node direct_linux_boot
1430 @section Direct Linux Boot
1432 This section explains how to launch a Linux kernel inside QEMU without
1433 having to make a full bootable image. It is very useful for fast Linux
1434 kernel testing.
1436 The syntax is:
1437 @example
1438 qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1439 @end example
1441 Use @option{-kernel} to provide the Linux kernel image and
1442 @option{-append} to give the kernel command line arguments. The
1443 @option{-initrd} option can be used to provide an INITRD image.
1445 When using the direct Linux boot, a disk image for the first hard disk
1446 @file{hda} is required because its boot sector is used to launch the
1447 Linux kernel.
1449 If you do not need graphical output, you can disable it and redirect
1450 the virtual serial port and the QEMU monitor to the console with the
1451 @option{-nographic} option. The typical command line is:
1452 @example
1453 qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1454                  -append "root=/dev/hda console=ttyS0" -nographic
1455 @end example
1457 Use @key{Ctrl-a c} to switch between the serial console and the
1458 monitor (@pxref{pcsys_keys}).
1460 @node pcsys_usb
1461 @section USB emulation
1463 QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
1464 plug virtual USB devices or real host USB devices (only works with certain
1465 host operating systems). QEMU will automatically create and connect virtual
1466 USB hubs as necessary to connect multiple USB devices.
1468 @menu
1469 * usb_devices::
1470 * host_usb_devices::
1471 @end menu
1472 @node usb_devices
1473 @subsection Connecting USB devices
1475 USB devices can be connected with the @option{-device usb-...} command line
1476 option or the @code{device_add} monitor command. Available devices are:
1478 @table @code
1479 @item usb-mouse
1480 Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
1481 @item usb-tablet
1482 Pointer device that uses absolute coordinates (like a touchscreen).
1483 This means QEMU is able to report the mouse position without having
1484 to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
1485 @item usb-storage,drive=@var{drive_id}
1486 Mass storage device backed by @var{drive_id} (@pxref{disk_images})
1487 @item usb-uas
1488 USB attached SCSI device, see
1489 @url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
1490 for details
1491 @item usb-bot
1492 Bulk-only transport storage device, see
1493 @url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
1494 for details here, too
1495 @item usb-mtp,x-root=@var{dir}
1496 Media transfer protocol device, using @var{dir} as root of the file tree
1497 that is presented to the guest.
1498 @item usb-host,hostbus=@var{bus},hostaddr=@var{addr}
1499 Pass through the host device identified by @var{bus} and @var{addr}
1500 @item usb-host,vendorid=@var{vendor},productid=@var{product}
1501 Pass through the host device identified by @var{vendor} and @var{product} ID
1502 @item usb-wacom-tablet
1503 Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
1504 above but it can be used with the tslib library because in addition to touch
1505 coordinates it reports touch pressure.
1506 @item usb-kbd
1507 Standard USB keyboard.  Will override the PS/2 keyboard (if present).
1508 @item usb-serial,chardev=@var{id}
1509 Serial converter. This emulates an FTDI FT232BM chip connected to host character
1510 device @var{id}.
1511 @item usb-braille,chardev=@var{id}
1512 Braille device.  This will use BrlAPI to display the braille output on a real
1513 or fake device referenced by @var{id}.
1514 @item usb-net[,netdev=@var{id}]
1515 Network adapter that supports CDC ethernet and RNDIS protocols.  @var{id}
1516 specifies a netdev defined with @code{-netdev @dots{},id=@var{id}}.
1517 For instance, user-mode networking can be used with
1518 @example
1519 qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
1520 @end example
1521 @item usb-ccid
1522 Smartcard reader device
1523 @item usb-audio
1524 USB audio device
1525 @item usb-bt-dongle
1526 Bluetooth dongle for the transport layer of HCI. It is connected to HCI
1527 scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}).
1528 Note that the syntax for the @code{-device usb-bt-dongle} option is not as
1529 useful yet as it was with the legacy @code{-usbdevice} option. So to
1530 configure an USB bluetooth device, you might need to use
1531 "@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a
1532 bluetooth dongle whose type is specified in the same format as with
1533 the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
1534 no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
1535 This USB device implements the USB Transport Layer of HCI.  Example
1536 usage:
1537 @example
1538 @command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3
1539 @end example
1540 @end table
1542 @node host_usb_devices
1543 @subsection Using host USB devices on a Linux host
1545 WARNING: this is an experimental feature. QEMU will slow down when
1546 using it. USB devices requiring real time streaming (i.e. USB Video
1547 Cameras) are not supported yet.
1549 @enumerate
1550 @item If you use an early Linux 2.4 kernel, verify that no Linux driver
1551 is actually using the USB device. A simple way to do that is simply to
1552 disable the corresponding kernel module by renaming it from @file{mydriver.o}
1553 to @file{mydriver.o.disabled}.
1555 @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1556 @example
1557 ls /proc/bus/usb
1558 001  devices  drivers
1559 @end example
1561 @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:
1562 @example
1563 chown -R myuid /proc/bus/usb
1564 @end example
1566 @item Launch QEMU and do in the monitor:
1567 @example
1568 info usbhost
1569   Device 1.2, speed 480 Mb/s
1570     Class 00: USB device 1234:5678, USB DISK
1571 @end example
1572 You should see the list of the devices you can use (Never try to use
1573 hubs, it won't work).
1575 @item Add the device in QEMU by using:
1576 @example
1577 device_add usb-host,vendorid=0x1234,productid=0x5678
1578 @end example
1580 Normally the guest OS should report that a new USB device is plugged.
1581 You can use the option @option{-device usb-host,...} to do the same.
1583 @item Now you can try to use the host USB device in QEMU.
1585 @end enumerate
1587 When relaunching QEMU, you may have to unplug and plug again the USB
1588 device to make it work again (this is a bug).
1590 @node vnc_security
1591 @section VNC security
1593 The VNC server capability provides access to the graphical console
1594 of the guest VM across the network. This has a number of security
1595 considerations depending on the deployment scenarios.
1597 @menu
1598 * vnc_sec_none::
1599 * vnc_sec_password::
1600 * vnc_sec_certificate::
1601 * vnc_sec_certificate_verify::
1602 * vnc_sec_certificate_pw::
1603 * vnc_sec_sasl::
1604 * vnc_sec_certificate_sasl::
1605 * vnc_generate_cert::
1606 * vnc_setup_sasl::
1607 @end menu
1608 @node vnc_sec_none
1609 @subsection Without passwords
1611 The simplest VNC server setup does not include any form of authentication.
1612 For this setup it is recommended to restrict it to listen on a UNIX domain
1613 socket only. For example
1615 @example
1616 qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1617 @end example
1619 This ensures that only users on local box with read/write access to that
1620 path can access the VNC server. To securely access the VNC server from a
1621 remote machine, a combination of netcat+ssh can be used to provide a secure
1622 tunnel.
1624 @node vnc_sec_password
1625 @subsection With passwords
1627 The VNC protocol has limited support for password based authentication. Since
1628 the protocol limits passwords to 8 characters it should not be considered
1629 to provide high security. The password can be fairly easily brute-forced by
1630 a client making repeat connections. For this reason, a VNC server using password
1631 authentication should be restricted to only listen on the loopback interface
1632 or UNIX domain sockets. Password authentication is not supported when operating
1633 in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
1634 authentication is requested with the @code{password} option, and then once QEMU
1635 is running the password is set with the monitor. Until the monitor is used to
1636 set the password all clients will be rejected.
1638 @example
1639 qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
1640 (qemu) change vnc password
1641 Password: ********
1642 (qemu)
1643 @end example
1645 @node vnc_sec_certificate
1646 @subsection With x509 certificates
1648 The QEMU VNC server also implements the VeNCrypt extension allowing use of
1649 TLS for encryption of the session, and x509 certificates for authentication.
1650 The use of x509 certificates is strongly recommended, because TLS on its
1651 own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1652 support provides a secure session, but no authentication. This allows any
1653 client to connect, and provides an encrypted session.
1655 @example
1656 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1657 @end example
1659 In the above example @code{/etc/pki/qemu} should contain at least three files,
1660 @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1661 users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1662 NB the @code{server-key.pem} file should be protected with file mode 0600 to
1663 only be readable by the user owning it.
1665 @node vnc_sec_certificate_verify
1666 @subsection With x509 certificates and client verification
1668 Certificates can also provide a means to authenticate the client connecting.
1669 The server will request that the client provide a certificate, which it will
1670 then validate against the CA certificate. This is a good choice if deploying
1671 in an environment with a private internal certificate authority.
1673 @example
1674 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1675 @end example
1678 @node vnc_sec_certificate_pw
1679 @subsection With x509 certificates, client verification and passwords
1681 Finally, the previous method can be combined with VNC password authentication
1682 to provide two layers of authentication for clients.
1684 @example
1685 qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1686 (qemu) change vnc password
1687 Password: ********
1688 (qemu)
1689 @end example
1692 @node vnc_sec_sasl
1693 @subsection With SASL authentication
1695 The SASL authentication method is a VNC extension, that provides an
1696 easily extendable, pluggable authentication method. This allows for
1697 integration with a wide range of authentication mechanisms, such as
1698 PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1699 The strength of the authentication depends on the exact mechanism
1700 configured. If the chosen mechanism also provides a SSF layer, then
1701 it will encrypt the datastream as well.
1703 Refer to the later docs on how to choose the exact SASL mechanism
1704 used for authentication, but assuming use of one supporting SSF,
1705 then QEMU can be launched with:
1707 @example
1708 qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
1709 @end example
1711 @node vnc_sec_certificate_sasl
1712 @subsection With x509 certificates and SASL authentication
1714 If the desired SASL authentication mechanism does not supported
1715 SSF layers, then it is strongly advised to run it in combination
1716 with TLS and x509 certificates. This provides securely encrypted
1717 data stream, avoiding risk of compromising of the security
1718 credentials. This can be enabled, by combining the 'sasl' option
1719 with the aforementioned TLS + x509 options:
1721 @example
1722 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
1723 @end example
1726 @node vnc_generate_cert
1727 @subsection Generating certificates for VNC
1729 The GNU TLS packages provides a command called @code{certtool} which can
1730 be used to generate certificates and keys in PEM format. At a minimum it
1731 is necessary to setup a certificate authority, and issue certificates to
1732 each server. If using certificates for authentication, then each client
1733 will also need to be issued a certificate. The recommendation is for the
1734 server to keep its certificates in either @code{/etc/pki/qemu} or for
1735 unprivileged users in @code{$HOME/.pki/qemu}.
1737 @menu
1738 * vnc_generate_ca::
1739 * vnc_generate_server::
1740 * vnc_generate_client::
1741 @end menu
1742 @node vnc_generate_ca
1743 @subsubsection Setup the Certificate Authority
1745 This step only needs to be performed once per organization / organizational
1746 unit. First the CA needs a private key. This key must be kept VERY secret
1747 and secure. If this key is compromised the entire trust chain of the certificates
1748 issued with it is lost.
1750 @example
1751 # certtool --generate-privkey > ca-key.pem
1752 @end example
1754 A CA needs to have a public certificate. For simplicity it can be a self-signed
1755 certificate, or one issue by a commercial certificate issuing authority. To
1756 generate a self-signed certificate requires one core piece of information, the
1757 name of the organization.
1759 @example
1760 # cat > ca.info <<EOF
1761 cn = Name of your organization
1763 cert_signing_key
1765 # certtool --generate-self-signed \
1766            --load-privkey ca-key.pem
1767            --template ca.info \
1768            --outfile ca-cert.pem
1769 @end example
1771 The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1772 TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1774 @node vnc_generate_server
1775 @subsubsection Issuing server certificates
1777 Each server (or host) needs to be issued with a key and certificate. When connecting
1778 the certificate is sent to the client which validates it against the CA certificate.
1779 The core piece of information for a server certificate is the hostname. This should
1780 be the fully qualified hostname that the client will connect with, since the client
1781 will typically also verify the hostname in the certificate. On the host holding the
1782 secure CA private key:
1784 @example
1785 # cat > server.info <<EOF
1786 organization = Name  of your organization
1787 cn = server.foo.example.com
1788 tls_www_server
1789 encryption_key
1790 signing_key
1792 # certtool --generate-privkey > server-key.pem
1793 # certtool --generate-certificate \
1794            --load-ca-certificate ca-cert.pem \
1795            --load-ca-privkey ca-key.pem \
1796            --load-privkey server-key.pem \
1797            --template server.info \
1798            --outfile server-cert.pem
1799 @end example
1801 The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1802 to the server for which they were generated. The @code{server-key.pem} is security
1803 sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1805 @node vnc_generate_client
1806 @subsubsection Issuing client certificates
1808 If the QEMU VNC server is to use the @code{x509verify} option to validate client
1809 certificates as its authentication mechanism, each client also needs to be issued
1810 a certificate. The client certificate contains enough metadata to uniquely identify
1811 the client, typically organization, state, city, building, etc. On the host holding
1812 the secure CA private key:
1814 @example
1815 # cat > client.info <<EOF
1816 country = GB
1817 state = London
1818 locality = London
1819 organization = Name of your organization
1820 cn = client.foo.example.com
1821 tls_www_client
1822 encryption_key
1823 signing_key
1825 # certtool --generate-privkey > client-key.pem
1826 # certtool --generate-certificate \
1827            --load-ca-certificate ca-cert.pem \
1828            --load-ca-privkey ca-key.pem \
1829            --load-privkey client-key.pem \
1830            --template client.info \
1831            --outfile client-cert.pem
1832 @end example
1834 The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1835 copied to the client for which they were generated.
1838 @node vnc_setup_sasl
1840 @subsection Configuring SASL mechanisms
1842 The following documentation assumes use of the Cyrus SASL implementation on a
1843 Linux host, but the principals should apply to any other SASL impl. When SASL
1844 is enabled, the mechanism configuration will be loaded from system default
1845 SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1846 unprivileged user, an environment variable SASL_CONF_PATH can be used
1847 to make it search alternate locations for the service config.
1849 If the TLS option is enabled for VNC, then it will provide session encryption,
1850 otherwise the SASL mechanism will have to provide encryption. In the latter
1851 case the list of possible plugins that can be used is drastically reduced. In
1852 fact only the GSSAPI SASL mechanism provides an acceptable level of security
1853 by modern standards. Previous versions of QEMU referred to the DIGEST-MD5
1854 mechanism, however, it has multiple serious flaws described in detail in
1855 RFC 6331 and thus should never be used any more. The SCRAM-SHA-1 mechanism
1856 provides a simple username/password auth facility similar to DIGEST-MD5, but
1857 does not support session encryption, so can only be used in combination with
1858 TLS.
1860 When not using TLS the recommended configuration is
1862 @example
1863 mech_list: gssapi
1864 keytab: /etc/qemu/krb5.tab
1865 @end example
1867 This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol, with
1868 the server principal stored in /etc/qemu/krb5.tab. For this to work the
1869 administrator of your KDC must generate a Kerberos principal for the server,
1870 with a name of 'qemu/somehost.example.com@@EXAMPLE.COM' replacing
1871 'somehost.example.com' with the fully qualified host name of the machine
1872 running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
1874 When using TLS, if username+password authentication is desired, then a
1875 reasonable configuration is
1877 @example
1878 mech_list: scram-sha-1
1879 sasldb_path: /etc/qemu/passwd.db
1880 @end example
1882 The saslpasswd2 program can be used to populate the passwd.db file with
1883 accounts.
1885 Other SASL configurations will be left as an exercise for the reader. Note that
1886 all mechanisms except GSSAPI, should be combined with use of TLS to ensure a
1887 secure data channel.
1889 @node gdb_usage
1890 @section GDB usage
1892 QEMU has a primitive support to work with gdb, so that you can do
1893 'Ctrl-C' while the virtual machine is running and inspect its state.
1895 In order to use gdb, launch QEMU with the '-s' option. It will wait for a
1896 gdb connection:
1897 @example
1898 qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1899                     -append "root=/dev/hda"
1900 Connected to host network interface: tun0
1901 Waiting gdb connection on port 1234
1902 @end example
1904 Then launch gdb on the 'vmlinux' executable:
1905 @example
1906 > gdb vmlinux
1907 @end example
1909 In gdb, connect to QEMU:
1910 @example
1911 (gdb) target remote localhost:1234
1912 @end example
1914 Then you can use gdb normally. For example, type 'c' to launch the kernel:
1915 @example
1916 (gdb) c
1917 @end example
1919 Here are some useful tips in order to use gdb on system code:
1921 @enumerate
1922 @item
1923 Use @code{info reg} to display all the CPU registers.
1924 @item
1925 Use @code{x/10i $eip} to display the code at the PC position.
1926 @item
1927 Use @code{set architecture i8086} to dump 16 bit code. Then use
1928 @code{x/10i $cs*16+$eip} to dump the code at the PC position.
1929 @end enumerate
1931 Advanced debugging options:
1933 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 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:
1934 @table @code
1935 @item maintenance packet qqemu.sstepbits
1937 This will display the MASK bits used to control the single stepping IE:
1938 @example
1939 (gdb) maintenance packet qqemu.sstepbits
1940 sending: "qqemu.sstepbits"
1941 received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1942 @end example
1943 @item maintenance packet qqemu.sstep
1945 This will display the current value of the mask used when single stepping IE:
1946 @example
1947 (gdb) maintenance packet qqemu.sstep
1948 sending: "qqemu.sstep"
1949 received: "0x7"
1950 @end example
1951 @item maintenance packet Qqemu.sstep=HEX_VALUE
1953 This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1954 @example
1955 (gdb) maintenance packet Qqemu.sstep=0x5
1956 sending: "qemu.sstep=0x5"
1957 received: "OK"
1958 @end example
1959 @end table
1961 @node pcsys_os_specific
1962 @section Target OS specific information
1964 @subsection Linux
1966 To have access to SVGA graphic modes under X11, use the @code{vesa} or
1967 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1968 color depth in the guest and the host OS.
1970 When using a 2.6 guest Linux kernel, you should add the option
1971 @code{clock=pit} on the kernel command line because the 2.6 Linux
1972 kernels make very strict real time clock checks by default that QEMU
1973 cannot simulate exactly.
1975 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1976 not activated because QEMU is slower with this patch. The QEMU
1977 Accelerator Module is also much slower in this case. Earlier Fedora
1978 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1979 patch by default. Newer kernels don't have it.
1981 @subsection Windows
1983 If you have a slow host, using Windows 95 is better as it gives the
1984 best speed. Windows 2000 is also a good choice.
1986 @subsubsection SVGA graphic modes support
1988 QEMU emulates a Cirrus Logic GD5446 Video
1989 card. All Windows versions starting from Windows 95 should recognize
1990 and use this graphic card. For optimal performances, use 16 bit color
1991 depth in the guest and the host OS.
1993 If you are using Windows XP as guest OS and if you want to use high
1994 resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
1995 1280x1024x16), then you should use the VESA VBE virtual graphic card
1996 (option @option{-std-vga}).
1998 @subsubsection CPU usage reduction
2000 Windows 9x does not correctly use the CPU HLT
2001 instruction. The result is that it takes host CPU cycles even when
2002 idle. You can install the utility from
2003 @url{http://web.archive.org/web/20060212132151/http://www.user.cityline.ru/~maxamn/amnhltm.zip}
2004 to solve this problem. Note that no such tool is needed for NT, 2000 or XP.
2006 @subsubsection Windows 2000 disk full problem
2008 Windows 2000 has a bug which gives a disk full problem during its
2009 installation. When installing it, use the @option{-win2k-hack} QEMU
2010 option to enable a specific workaround. After Windows 2000 is
2011 installed, you no longer need this option (this option slows down the
2012 IDE transfers).
2014 @subsubsection Windows 2000 shutdown
2016 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
2017 can. It comes from the fact that Windows 2000 does not automatically
2018 use the APM driver provided by the BIOS.
2020 In order to correct that, do the following (thanks to Struan
2021 Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
2022 Add/Troubleshoot a device => Add a new device & Next => No, select the
2023 hardware from a list & Next => NT Apm/Legacy Support & Next => Next
2024 (again) a few times. Now the driver is installed and Windows 2000 now
2025 correctly instructs QEMU to shutdown at the appropriate moment.
2027 @subsubsection Share a directory between Unix and Windows
2029 See @ref{sec_invocation} about the help of the option
2030 @option{'-netdev user,smb=...'}.
2032 @subsubsection Windows XP security problem
2034 Some releases of Windows XP install correctly but give a security
2035 error when booting:
2036 @example
2037 A problem is preventing Windows from accurately checking the
2038 license for this computer. Error code: 0x800703e6.
2039 @end example
2041 The workaround is to install a service pack for XP after a boot in safe
2042 mode. Then reboot, and the problem should go away. Since there is no
2043 network while in safe mode, its recommended to download the full
2044 installation of SP1 or SP2 and transfer that via an ISO or using the
2045 vvfat block device ("-hdb fat:directory_which_holds_the_SP").
2047 @subsection MS-DOS and FreeDOS
2049 @subsubsection CPU usage reduction
2051 DOS does not correctly use the CPU HLT instruction. The result is that
2052 it takes host CPU cycles even when idle. You can install the utility from
2053 @url{http://web.archive.org/web/20051222085335/http://www.vmware.com/software/dosidle210.zip}
2054 to solve this problem.
2056 @node QEMU System emulator for non PC targets
2057 @chapter QEMU System emulator for non PC targets
2059 QEMU is a generic emulator and it emulates many non PC
2060 machines. Most of the options are similar to the PC emulator. The
2061 differences are mentioned in the following sections.
2063 @menu
2064 * PowerPC System emulator::
2065 * Sparc32 System emulator::
2066 * Sparc64 System emulator::
2067 * MIPS System emulator::
2068 * ARM System emulator::
2069 * ColdFire System emulator::
2070 * Cris System emulator::
2071 * Microblaze System emulator::
2072 * SH4 System emulator::
2073 * Xtensa System emulator::
2074 @end menu
2076 @node PowerPC System emulator
2077 @section PowerPC System emulator
2078 @cindex system emulation (PowerPC)
2080 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
2081 or PowerMac PowerPC system.
2083 QEMU emulates the following PowerMac peripherals:
2085 @itemize @minus
2086 @item
2087 UniNorth or Grackle PCI Bridge
2088 @item
2089 PCI VGA compatible card with VESA Bochs Extensions
2090 @item
2091 2 PMAC IDE interfaces with hard disk and CD-ROM support
2092 @item
2093 NE2000 PCI adapters
2094 @item
2095 Non Volatile RAM
2096 @item
2097 VIA-CUDA with ADB keyboard and mouse.
2098 @end itemize
2100 QEMU emulates the following PREP peripherals:
2102 @itemize @minus
2103 @item
2104 PCI Bridge
2105 @item
2106 PCI VGA compatible card with VESA Bochs Extensions
2107 @item
2108 2 IDE interfaces with hard disk and CD-ROM support
2109 @item
2110 Floppy disk
2111 @item
2112 NE2000 network adapters
2113 @item
2114 Serial port
2115 @item
2116 PREP Non Volatile RAM
2117 @item
2118 PC compatible keyboard and mouse.
2119 @end itemize
2121 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
2122 @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
2124 Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
2125 for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
2126 v2) portable firmware implementation. The goal is to implement a 100%
2127 IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
2129 @c man begin OPTIONS
2131 The following options are specific to the PowerPC emulation:
2133 @table @option
2135 @item -g @var{W}x@var{H}[x@var{DEPTH}]
2137 Set the initial VGA graphic mode. The default is 800x600x32.
2139 @item -prom-env @var{string}
2141 Set OpenBIOS variables in NVRAM, for example:
2143 @example
2144 qemu-system-ppc -prom-env 'auto-boot?=false' \
2145  -prom-env 'boot-device=hd:2,\yaboot' \
2146  -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
2147 @end example
2149 These variables are not used by Open Hack'Ware.
2151 @end table
2153 @c man end
2156 More information is available at
2157 @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
2159 @node Sparc32 System emulator
2160 @section Sparc32 System emulator
2161 @cindex system emulation (Sparc32)
2163 Use the executable @file{qemu-system-sparc} to simulate the following
2164 Sun4m architecture machines:
2165 @itemize @minus
2166 @item
2167 SPARCstation 4
2168 @item
2169 SPARCstation 5
2170 @item
2171 SPARCstation 10
2172 @item
2173 SPARCstation 20
2174 @item
2175 SPARCserver 600MP
2176 @item
2177 SPARCstation LX
2178 @item
2179 SPARCstation Voyager
2180 @item
2181 SPARCclassic
2182 @item
2183 SPARCbook
2184 @end itemize
2186 The emulation is somewhat complete. SMP up to 16 CPUs is supported,
2187 but Linux limits the number of usable CPUs to 4.
2189 QEMU emulates the following sun4m peripherals:
2191 @itemize @minus
2192 @item
2193 IOMMU
2194 @item
2195 TCX or cgthree Frame buffer
2196 @item
2197 Lance (Am7990) Ethernet
2198 @item
2199 Non Volatile RAM M48T02/M48T08
2200 @item
2201 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2202 and power/reset logic
2203 @item
2204 ESP SCSI controller with hard disk and CD-ROM support
2205 @item
2206 Floppy drive (not on SS-600MP)
2207 @item
2208 CS4231 sound device (only on SS-5, not working yet)
2209 @end itemize
2211 The number of peripherals is fixed in the architecture.  Maximum
2212 memory size depends on the machine type, for SS-5 it is 256MB and for
2213 others 2047MB.
2215 Since version 0.8.2, QEMU uses OpenBIOS
2216 @url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
2217 firmware implementation. The goal is to implement a 100% IEEE
2218 1275-1994 (referred to as Open Firmware) compliant firmware.
2220 A sample Linux 2.6 series kernel and ram disk image are available on
2221 the QEMU web site. There are still issues with NetBSD and OpenBSD, but
2222 most kernel versions work. Please note that currently older Solaris kernels
2223 don't work probably due to interface issues between OpenBIOS and
2224 Solaris.
2226 @c man begin OPTIONS
2228 The following options are specific to the Sparc32 emulation:
2230 @table @option
2232 @item -g @var{W}x@var{H}x[x@var{DEPTH}]
2234 Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
2235 option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
2236 of 1152x900x8 for people who wish to use OBP.
2238 @item -prom-env @var{string}
2240 Set OpenBIOS variables in NVRAM, for example:
2242 @example
2243 qemu-system-sparc -prom-env 'auto-boot?=false' \
2244  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2245 @end example
2247 @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]
2249 Set the emulated machine type. Default is SS-5.
2251 @end table
2253 @c man end
2255 @node Sparc64 System emulator
2256 @section Sparc64 System emulator
2257 @cindex system emulation (Sparc64)
2259 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
2260 (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
2261 Niagara (T1) machine. The Sun4u emulator is mostly complete, being
2262 able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
2263 Sun4v emulator is still a work in progress.
2265 The Niagara T1 emulator makes use of firmware and OS binaries supplied in the S10image/ directory
2266 of the OpenSPARC T1 project @url{http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2}
2267 and is able to boot the disk.s10hw2 Solaris image.
2268 @example
2269 qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
2270                     -nographic -m 256 \
2271                     -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
2272 @end example
2275 QEMU emulates the following peripherals:
2277 @itemize @minus
2278 @item
2279 UltraSparc IIi APB PCI Bridge
2280 @item
2281 PCI VGA compatible card with VESA Bochs Extensions
2282 @item
2283 PS/2 mouse and keyboard
2284 @item
2285 Non Volatile RAM M48T59
2286 @item
2287 PC-compatible serial ports
2288 @item
2289 2 PCI IDE interfaces with hard disk and CD-ROM support
2290 @item
2291 Floppy disk
2292 @end itemize
2294 @c man begin OPTIONS
2296 The following options are specific to the Sparc64 emulation:
2298 @table @option
2300 @item -prom-env @var{string}
2302 Set OpenBIOS variables in NVRAM, for example:
2304 @example
2305 qemu-system-sparc64 -prom-env 'auto-boot?=false'
2306 @end example
2308 @item -M [sun4u|sun4v|niagara]
2310 Set the emulated machine type. The default is sun4u.
2312 @end table
2314 @c man end
2316 @node MIPS System emulator
2317 @section MIPS System emulator
2318 @cindex system emulation (MIPS)
2320 Four executables cover simulation of 32 and 64-bit MIPS systems in
2321 both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2322 @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
2323 Five different machine types are emulated:
2325 @itemize @minus
2326 @item
2327 A generic ISA PC-like machine "mips"
2328 @item
2329 The MIPS Malta prototype board "malta"
2330 @item
2331 An ACER Pica "pica61". This machine needs the 64-bit emulator.
2332 @item
2333 MIPS emulator pseudo board "mipssim"
2334 @item
2335 A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
2336 @end itemize
2338 The generic emulation is supported by Debian 'Etch' and is able to
2339 install Debian into a virtual disk image. The following devices are
2340 emulated:
2342 @itemize @minus
2343 @item
2344 A range of MIPS CPUs, default is the 24Kf
2345 @item
2346 PC style serial port
2347 @item
2348 PC style IDE disk
2349 @item
2350 NE2000 network card
2351 @end itemize
2353 The Malta emulation supports the following devices:
2355 @itemize @minus
2356 @item
2357 Core board with MIPS 24Kf CPU and Galileo system controller
2358 @item
2359 PIIX4 PCI/USB/SMbus controller
2360 @item
2361 The Multi-I/O chip's serial device
2362 @item
2363 PCI network cards (PCnet32 and others)
2364 @item
2365 Malta FPGA serial device
2366 @item
2367 Cirrus (default) or any other PCI VGA graphics card
2368 @end itemize
2370 The ACER Pica emulation supports:
2372 @itemize @minus
2373 @item
2374 MIPS R4000 CPU
2375 @item
2376 PC-style IRQ and DMA controllers
2377 @item
2378 PC Keyboard
2379 @item
2380 IDE controller
2381 @end itemize
2383 The mipssim pseudo board emulation provides an environment similar
2384 to what the proprietary MIPS emulator uses for running Linux.
2385 It supports:
2387 @itemize @minus
2388 @item
2389 A range of MIPS CPUs, default is the 24Kf
2390 @item
2391 PC style serial port
2392 @item
2393 MIPSnet network emulation
2394 @end itemize
2396 The MIPS Magnum R4000 emulation supports:
2398 @itemize @minus
2399 @item
2400 MIPS R4000 CPU
2401 @item
2402 PC-style IRQ controller
2403 @item
2404 PC Keyboard
2405 @item
2406 SCSI controller
2407 @item
2408 G364 framebuffer
2409 @end itemize
2412 @node ARM System emulator
2413 @section ARM System emulator
2414 @cindex system emulation (ARM)
2416 Use the executable @file{qemu-system-arm} to simulate a ARM
2417 machine. The ARM Integrator/CP board is emulated with the following
2418 devices:
2420 @itemize @minus
2421 @item
2422 ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
2423 @item
2424 Two PL011 UARTs
2425 @item
2426 SMC 91c111 Ethernet adapter
2427 @item
2428 PL110 LCD controller
2429 @item
2430 PL050 KMI with PS/2 keyboard and mouse.
2431 @item
2432 PL181 MultiMedia Card Interface with SD card.
2433 @end itemize
2435 The ARM Versatile baseboard is emulated with the following devices:
2437 @itemize @minus
2438 @item
2439 ARM926E, ARM1136 or Cortex-A8 CPU
2440 @item
2441 PL190 Vectored Interrupt Controller
2442 @item
2443 Four PL011 UARTs
2444 @item
2445 SMC 91c111 Ethernet adapter
2446 @item
2447 PL110 LCD controller
2448 @item
2449 PL050 KMI with PS/2 keyboard and mouse.
2450 @item
2451 PCI host bridge.  Note the emulated PCI bridge only provides access to
2452 PCI memory space.  It does not provide access to PCI IO space.
2453 This means some devices (eg. ne2k_pci NIC) are not usable, and others
2454 (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
2455 mapped control registers.
2456 @item
2457 PCI OHCI USB controller.
2458 @item
2459 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
2460 @item
2461 PL181 MultiMedia Card Interface with SD card.
2462 @end itemize
2464 Several variants of the ARM RealView baseboard are emulated,
2465 including the EB, PB-A8 and PBX-A9.  Due to interactions with the
2466 bootloader, only certain Linux kernel configurations work out
2467 of the box on these boards.
2469 Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2470 enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board
2471 should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2472 disabled and expect 1024M RAM.
2474 The following devices are emulated:
2476 @itemize @minus
2477 @item
2478 ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
2479 @item
2480 ARM AMBA Generic/Distributed Interrupt Controller
2481 @item
2482 Four PL011 UARTs
2483 @item
2484 SMC 91c111 or SMSC LAN9118 Ethernet adapter
2485 @item
2486 PL110 LCD controller
2487 @item
2488 PL050 KMI with PS/2 keyboard and mouse
2489 @item
2490 PCI host bridge
2491 @item
2492 PCI OHCI USB controller
2493 @item
2494 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
2495 @item
2496 PL181 MultiMedia Card Interface with SD card.
2497 @end itemize
2499 The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2500 and "Terrier") emulation includes the following peripherals:
2502 @itemize @minus
2503 @item
2504 Intel PXA270 System-on-chip (ARM V5TE core)
2505 @item
2506 NAND Flash memory
2507 @item
2508 IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2509 @item
2510 On-chip OHCI USB controller
2511 @item
2512 On-chip LCD controller
2513 @item
2514 On-chip Real Time Clock
2515 @item
2516 TI ADS7846 touchscreen controller on SSP bus
2517 @item
2518 Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2519 @item
2520 GPIO-connected keyboard controller and LEDs
2521 @item
2522 Secure Digital card connected to PXA MMC/SD host
2523 @item
2524 Three on-chip UARTs
2525 @item
2526 WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2527 @end itemize
2529 The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2530 following elements:
2532 @itemize @minus
2533 @item
2534 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2535 @item
2536 ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2537 @item
2538 On-chip LCD controller
2539 @item
2540 On-chip Real Time Clock
2541 @item
2542 TI TSC2102i touchscreen controller / analog-digital converter / Audio
2543 CODEC, connected through MicroWire and I@math{^2}S busses
2544 @item
2545 GPIO-connected matrix keypad
2546 @item
2547 Secure Digital card connected to OMAP MMC/SD host
2548 @item
2549 Three on-chip UARTs
2550 @end itemize
2552 Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2553 emulation supports the following elements:
2555 @itemize @minus
2556 @item
2557 Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2558 @item
2559 RAM and non-volatile OneNAND Flash memories
2560 @item
2561 Display connected to EPSON remote framebuffer chip and OMAP on-chip
2562 display controller and a LS041y3 MIPI DBI-C controller
2563 @item
2564 TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2565 driven through SPI bus
2566 @item
2567 National Semiconductor LM8323-controlled qwerty keyboard driven
2568 through I@math{^2}C bus
2569 @item
2570 Secure Digital card connected to OMAP MMC/SD host
2571 @item
2572 Three OMAP on-chip UARTs and on-chip STI debugging console
2573 @item
2574 A Bluetooth(R) transceiver and HCI connected to an UART
2575 @item
2576 Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2577 TUSB6010 chip - only USB host mode is supported
2578 @item
2579 TI TMP105 temperature sensor driven through I@math{^2}C bus
2580 @item
2581 TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2582 @item
2583 Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2584 through CBUS
2585 @end itemize
2587 The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2588 devices:
2590 @itemize @minus
2591 @item
2592 Cortex-M3 CPU core.
2593 @item
2594 64k Flash and 8k SRAM.
2595 @item
2596 Timers, UARTs, ADC and I@math{^2}C interface.
2597 @item
2598 OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2599 @end itemize
2601 The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2602 devices:
2604 @itemize @minus
2605 @item
2606 Cortex-M3 CPU core.
2607 @item
2608 256k Flash and 64k SRAM.
2609 @item
2610 Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2611 @item
2612 OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2613 @end itemize
2615 The Freecom MusicPal internet radio emulation includes the following
2616 elements:
2618 @itemize @minus
2619 @item
2620 Marvell MV88W8618 ARM core.
2621 @item
2622 32 MB RAM, 256 KB SRAM, 8 MB flash.
2623 @item
2624 Up to 2 16550 UARTs
2625 @item
2626 MV88W8xx8 Ethernet controller
2627 @item
2628 MV88W8618 audio controller, WM8750 CODEC and mixer
2629 @item
2630 128×64 display with brightness control
2631 @item
2632 2 buttons, 2 navigation wheels with button function
2633 @end itemize
2635 The Siemens SX1 models v1 and v2 (default) basic emulation.
2636 The emulation includes the following elements:
2638 @itemize @minus
2639 @item
2640 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2641 @item
2642 ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2644 1 Flash of 16MB and 1 Flash of 8MB
2646 1 Flash of 32MB
2647 @item
2648 On-chip LCD controller
2649 @item
2650 On-chip Real Time Clock
2651 @item
2652 Secure Digital card connected to OMAP MMC/SD host
2653 @item
2654 Three on-chip UARTs
2655 @end itemize
2657 A Linux 2.6 test image is available on the QEMU web site. More
2658 information is available in the QEMU mailing-list archive.
2660 @c man begin OPTIONS
2662 The following options are specific to the ARM emulation:
2664 @table @option
2666 @item -semihosting
2667 Enable semihosting syscall emulation.
2669 On ARM this implements the "Angel" interface.
2671 Note that this allows guest direct access to the host filesystem,
2672 so should only be used with trusted guest OS.
2674 @end table
2676 @c man end
2678 @node ColdFire System emulator
2679 @section ColdFire System emulator
2680 @cindex system emulation (ColdFire)
2681 @cindex system emulation (M68K)
2683 Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2684 The emulator is able to boot a uClinux kernel.
2686 The M5208EVB emulation includes the following devices:
2688 @itemize @minus
2689 @item
2690 MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2691 @item
2692 Three Two on-chip UARTs.
2693 @item
2694 Fast Ethernet Controller (FEC)
2695 @end itemize
2697 The AN5206 emulation includes the following devices:
2699 @itemize @minus
2700 @item
2701 MCF5206 ColdFire V2 Microprocessor.
2702 @item
2703 Two on-chip UARTs.
2704 @end itemize
2706 @c man begin OPTIONS
2708 The following options are specific to the ColdFire emulation:
2710 @table @option
2712 @item -semihosting
2713 Enable semihosting syscall emulation.
2715 On M68K this implements the "ColdFire GDB" interface used by libgloss.
2717 Note that this allows guest direct access to the host filesystem,
2718 so should only be used with trusted guest OS.
2720 @end table
2722 @c man end
2724 @node Cris System emulator
2725 @section Cris System emulator
2726 @cindex system emulation (Cris)
2728 TODO
2730 @node Microblaze System emulator
2731 @section Microblaze System emulator
2732 @cindex system emulation (Microblaze)
2734 TODO
2736 @node SH4 System emulator
2737 @section SH4 System emulator
2738 @cindex system emulation (SH4)
2740 TODO
2742 @node Xtensa System emulator
2743 @section Xtensa System emulator
2744 @cindex system emulation (Xtensa)
2746 Two executables cover simulation of both Xtensa endian options,
2747 @file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
2748 Two different machine types are emulated:
2750 @itemize @minus
2751 @item
2752 Xtensa emulator pseudo board "sim"
2753 @item
2754 Avnet LX60/LX110/LX200 board
2755 @end itemize
2757 The sim pseudo board emulation provides an environment similar
2758 to one provided by the proprietary Tensilica ISS.
2759 It supports:
2761 @itemize @minus
2762 @item
2763 A range of Xtensa CPUs, default is the DC232B
2764 @item
2765 Console and filesystem access via semihosting calls
2766 @end itemize
2768 The Avnet LX60/LX110/LX200 emulation supports:
2770 @itemize @minus
2771 @item
2772 A range of Xtensa CPUs, default is the DC232B
2773 @item
2774 16550 UART
2775 @item
2776 OpenCores 10/100 Mbps Ethernet MAC
2777 @end itemize
2779 @c man begin OPTIONS
2781 The following options are specific to the Xtensa emulation:
2783 @table @option
2785 @item -semihosting
2786 Enable semihosting syscall emulation.
2788 Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2789 Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2791 Note that this allows guest direct access to the host filesystem,
2792 so should only be used with trusted guest OS.
2794 @end table
2796 @c man end
2798 @node QEMU Guest Agent
2799 @chapter QEMU Guest Agent invocation
2801 @include qemu-ga.texi
2803 @node QEMU User space emulator
2804 @chapter QEMU User space emulator
2806 @menu
2807 * Supported Operating Systems ::
2808 * Features::
2809 * Linux User space emulator::
2810 * BSD User space emulator ::
2811 @end menu
2813 @node Supported Operating Systems
2814 @section Supported Operating Systems
2816 The following OS are supported in user space emulation:
2818 @itemize @minus
2819 @item
2820 Linux (referred as qemu-linux-user)
2821 @item
2822 BSD (referred as qemu-bsd-user)
2823 @end itemize
2825 @node Features
2826 @section Features
2828 QEMU user space emulation has the following notable features:
2830 @table @strong
2831 @item System call translation:
2832 QEMU includes a generic system call translator.  This means that
2833 the parameters of the system calls can be converted to fix
2834 endianness and 32/64-bit mismatches between hosts and targets.
2835 IOCTLs can be converted too.
2837 @item POSIX signal handling:
2838 QEMU can redirect to the running program all signals coming from
2839 the host (such as @code{SIGALRM}), as well as synthesize signals from
2840 virtual CPU exceptions (for example @code{SIGFPE} when the program
2841 executes a division by zero).
2843 QEMU relies on the host kernel to emulate most signal system
2844 calls, for example to emulate the signal mask.  On Linux, QEMU
2845 supports both normal and real-time signals.
2847 @item Threading:
2848 On Linux, QEMU can emulate the @code{clone} syscall and create a real
2849 host thread (with a separate virtual CPU) for each emulated thread.
2850 Note that not all targets currently emulate atomic operations correctly.
2851 x86 and ARM use a global lock in order to preserve their semantics.
2852 @end table
2854 QEMU was conceived so that ultimately it can emulate itself. Although
2855 it is not very useful, it is an important test to show the power of the
2856 emulator.
2858 @node Linux User space emulator
2859 @section Linux User space emulator
2861 @menu
2862 * Quick Start::
2863 * Wine launch::
2864 * Command line options::
2865 * Other binaries::
2866 @end menu
2868 @node Quick Start
2869 @subsection Quick Start
2871 In order to launch a Linux process, QEMU needs the process executable
2872 itself and all the target (x86) dynamic libraries used by it.
2874 @itemize
2876 @item On x86, you can just try to launch any process by using the native
2877 libraries:
2879 @example
2880 qemu-i386 -L / /bin/ls
2881 @end example
2883 @code{-L /} tells that the x86 dynamic linker must be searched with a
2884 @file{/} prefix.
2886 @item Since QEMU is also a linux process, you can launch QEMU with
2887 QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
2889 @example
2890 qemu-i386 -L / qemu-i386 -L / /bin/ls
2891 @end example
2893 @item On non x86 CPUs, you need first to download at least an x86 glibc
2894 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2895 @code{LD_LIBRARY_PATH} is not set:
2897 @example
2898 unset LD_LIBRARY_PATH
2899 @end example
2901 Then you can launch the precompiled @file{ls} x86 executable:
2903 @example
2904 qemu-i386 tests/i386/ls
2905 @end example
2906 You can look at @file{scripts/qemu-binfmt-conf.sh} so that
2907 QEMU is automatically launched by the Linux kernel when you try to
2908 launch x86 executables. It requires the @code{binfmt_misc} module in the
2909 Linux kernel.
2911 @item The x86 version of QEMU is also included. You can try weird things such as:
2912 @example
2913 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2914           /usr/local/qemu-i386/bin/ls-i386
2915 @end example
2917 @end itemize
2919 @node Wine launch
2920 @subsection Wine launch
2922 @itemize
2924 @item Ensure that you have a working QEMU with the x86 glibc
2925 distribution (see previous section). In order to verify it, you must be
2926 able to do:
2928 @example
2929 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2930 @end example
2932 @item Download the binary x86 Wine install
2933 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2935 @item Configure Wine on your account. Look at the provided script
2936 @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2937 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2939 @item Then you can try the example @file{putty.exe}:
2941 @example
2942 qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2943           /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2944 @end example
2946 @end itemize
2948 @node Command line options
2949 @subsection Command line options
2951 @example
2952 @command{qemu-i386} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-cpu} @var{model}] [@option{-g} @var{port}] [@option{-B} @var{offset}] [@option{-R} @var{size}] @var{program} [@var{arguments}...]
2953 @end example
2955 @table @option
2956 @item -h
2957 Print the help
2958 @item -L path
2959 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2960 @item -s size
2961 Set the x86 stack size in bytes (default=524288)
2962 @item -cpu model
2963 Select CPU model (-cpu help for list and additional feature selection)
2964 @item -E @var{var}=@var{value}
2965 Set environment @var{var} to @var{value}.
2966 @item -U @var{var}
2967 Remove @var{var} from the environment.
2968 @item -B offset
2969 Offset guest address by the specified number of bytes.  This is useful when
2970 the address region required by guest applications is reserved on the host.
2971 This option is currently only supported on some hosts.
2972 @item -R size
2973 Pre-allocate a guest virtual address space of the given size (in bytes).
2974 "G", "M", and "k" suffixes may be used when specifying the size.
2975 @end table
2977 Debug options:
2979 @table @option
2980 @item -d item1,...
2981 Activate logging of the specified items (use '-d help' for a list of log items)
2982 @item -p pagesize
2983 Act as if the host page size was 'pagesize' bytes
2984 @item -g port
2985 Wait gdb connection to port
2986 @item -singlestep
2987 Run the emulation in single step mode.
2988 @end table
2990 Environment variables:
2992 @table @env
2993 @item QEMU_STRACE
2994 Print system calls and arguments similar to the 'strace' program
2995 (NOTE: the actual 'strace' program will not work because the user
2996 space emulator hasn't implemented ptrace).  At the moment this is
2997 incomplete.  All system calls that don't have a specific argument
2998 format are printed with information for six arguments.  Many
2999 flag-style arguments don't have decoders and will show up as numbers.
3000 @end table
3002 @node Other binaries
3003 @subsection Other binaries
3005 @cindex user mode (Alpha)
3006 @command{qemu-alpha} TODO.
3008 @cindex user mode (ARM)
3009 @command{qemu-armeb} TODO.
3011 @cindex user mode (ARM)
3012 @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
3013 binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
3014 configurations), and arm-uclinux bFLT format binaries.
3016 @cindex user mode (ColdFire)
3017 @cindex user mode (M68K)
3018 @command{qemu-m68k} is capable of running semihosted binaries using the BDM
3019 (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
3020 coldfire uClinux bFLT format binaries.
3022 The binary format is detected automatically.
3024 @cindex user mode (Cris)
3025 @command{qemu-cris} TODO.
3027 @cindex user mode (i386)
3028 @command{qemu-i386} TODO.
3029 @command{qemu-x86_64} TODO.
3031 @cindex user mode (Microblaze)
3032 @command{qemu-microblaze} TODO.
3034 @cindex user mode (MIPS)
3035 @command{qemu-mips} TODO.
3036 @command{qemu-mipsel} TODO.
3038 @cindex user mode (NiosII)
3039 @command{qemu-nios2} TODO.
3041 @cindex user mode (PowerPC)
3042 @command{qemu-ppc64abi32} TODO.
3043 @command{qemu-ppc64} TODO.
3044 @command{qemu-ppc} TODO.
3046 @cindex user mode (SH4)
3047 @command{qemu-sh4eb} TODO.
3048 @command{qemu-sh4} TODO.
3050 @cindex user mode (SPARC)
3051 @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
3053 @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
3054 (Sparc64 CPU, 32 bit ABI).
3056 @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
3057 SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
3059 @node BSD User space emulator
3060 @section BSD User space emulator
3062 @menu
3063 * BSD Status::
3064 * BSD Quick Start::
3065 * BSD Command line options::
3066 @end menu
3068 @node BSD Status
3069 @subsection BSD Status
3071 @itemize @minus
3072 @item
3073 target Sparc64 on Sparc64: Some trivial programs work.
3074 @end itemize
3076 @node BSD Quick Start
3077 @subsection Quick Start
3079 In order to launch a BSD process, QEMU needs the process executable
3080 itself and all the target dynamic libraries used by it.
3082 @itemize
3084 @item On Sparc64, you can just try to launch any process by using the native
3085 libraries:
3087 @example
3088 qemu-sparc64 /bin/ls
3089 @end example
3091 @end itemize
3093 @node BSD Command line options
3094 @subsection Command line options
3096 @example
3097 @command{qemu-sparc64} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-bsd} @var{type}] @var{program} [@var{arguments}...]
3098 @end example
3100 @table @option
3101 @item -h
3102 Print the help
3103 @item -L path
3104 Set the library root path (default=/)
3105 @item -s size
3106 Set the stack size in bytes (default=524288)
3107 @item -ignore-environment
3108 Start with an empty environment. Without this option,
3109 the initial environment is a copy of the caller's environment.
3110 @item -E @var{var}=@var{value}
3111 Set environment @var{var} to @var{value}.
3112 @item -U @var{var}
3113 Remove @var{var} from the environment.
3114 @item -bsd type
3115 Set the type of the emulated BSD Operating system. Valid values are
3116 FreeBSD, NetBSD and OpenBSD (default).
3117 @end table
3119 Debug options:
3121 @table @option
3122 @item -d item1,...
3123 Activate logging of the specified items (use '-d help' for a list of log items)
3124 @item -p pagesize
3125 Act as if the host page size was 'pagesize' bytes
3126 @item -singlestep
3127 Run the emulation in single step mode.
3128 @end table
3131 @include qemu-tech.texi
3133 @node Deprecated features
3134 @appendix Deprecated features
3136 In general features are intended to be supported indefinitely once
3137 introduced into QEMU. In the event that a feature needs to be removed,
3138 it will be listed in this appendix. The feature will remain functional
3139 for 2 releases prior to actual removal. Deprecated features may also
3140 generate warnings on the console when QEMU starts up, or if activated
3141 via a monitor command, however, this is not a mandatory requirement.
3143 Prior to the 2.10.0 release there was no official policy on how
3144 long features would be deprecated prior to their removal, nor
3145 any documented list of which features were deprecated. Thus
3146 any features deprecated prior to 2.10.0 will be treated as if
3147 they were first deprecated in the 2.10.0 release.
3149 What follows is a list of all features currently marked as
3150 deprecated.
3152 @section System emulator command line arguments
3154 @subsection -drive boot=on|off (since 1.3.0)
3156 The ``boot=on|off'' option to the ``-drive'' argument is
3157 ignored. Applications should use the ``bootindex=N'' parameter
3158 to set an absolute ordering between devices instead.
3160 @subsection -tdf (since 1.3.0)
3162 The ``-tdf'' argument is ignored. The behaviour implemented
3163 by this argument is now the default when using the KVM PIT,
3164 but can be requested explicitly using
3165 ``-global kvm-pit.lost_tick_policy=slew''.
3167 @subsection -no-kvm-pit-reinjection (since 1.3.0)
3169 The ``-no-kvm-pit-reinjection'' argument is now a
3170 synonym for setting ``-global kvm-pit.lost_tick_policy=discard''.
3172 @subsection -no-kvm-irqchip (since 1.3.0)
3174 The ``-no-kvm-irqchip'' argument is now a synonym for
3175 setting ``-machine kernel_irqchip=off''.
3177 @subsection -no-kvm-pit (since 1.3.0)
3179 The ``-no-kvm-pit'' argument is ignored. It is no longer
3180 possible to disable the KVM PIT directly.
3182 @subsection -no-kvm (since 1.3.0)
3184 The ``-no-kvm'' argument is now a synonym for setting
3185 ``-machine accel=tcg''.
3187 @subsection -mon default=on (since 2.4.0)
3189 The ``default'' option to the ``-mon'' argument is
3190 now ignored. When multiple monitors were enabled, it
3191 indicated which monitor would receive log messages
3192 from the various subsystems. This feature is no longer
3193 required as messages are now only sent to the monitor
3194 in response to explicitly monitor commands.
3196 @subsection -vnc tls (since 2.5.0)
3198 The ``-vnc tls'' argument is now a synonym for setting
3199 ``-object tls-creds-anon,id=tls0'' combined with
3200 ``-vnc tls-creds=tls0'
3202 @subsection -vnc x509 (since 2.5.0)
3204 The ``-vnc x509=/path/to/certs'' argument is now a
3205 synonym for setting
3206 ``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=no''
3207 combined with ``-vnc tls-creds=tls0'
3209 @subsection -vnc x509verify (since 2.5.0)
3211 The ``-vnc x509verify=/path/to/certs'' argument is now a
3212 synonym for setting
3213 ``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=yes''
3214 combined with ``-vnc tls-creds=tls0'
3216 @subsection -tftp (since 2.6.0)
3218 The ``-tftp /some/dir'' argument is now a synonym for setting
3219 the ``-netdev user,tftp=/some/dir' argument. The new syntax
3220 allows different settings to be provided per NIC.
3222 @subsection -bootp (since 2.6.0)
3224 The ``-bootp /some/file'' argument is now a synonym for setting
3225 the ``-netdev user,bootp=/some/file' argument. The new syntax
3226 allows different settings to be provided per NIC.
3228 @subsection -redir (since 2.6.0)
3230 The ``-redir ARGS'' argument is now a synonym for setting
3231 the ``-netdev user,hostfwd=ARGS'' argument instead. The new
3232 syntax allows different settings to be provided per NIC.
3234 @subsection -smb (since 2.6.0)
3236 The ``-smb /some/dir'' argument is now a synonym for setting
3237 the ``-netdev user,smb=/some/dir'' argument instead. The new
3238 syntax allows different settings to be provided per NIC.
3240 @subsection -net channel (since 2.6.0)
3242 The ``--net channel,ARGS'' argument is now a synonym for setting
3243 the ``-netdev user,guestfwd=ARGS'' argument instead.
3245 @subsection -net vlan (since 2.9.0)
3247 The ``-net vlan=NN'' argument is partially replaced with the
3248 new ``-netdev'' argument. The remaining use cases will no
3249 longer be directly supported in QEMU.
3251 @subsection -drive if=scsi (since 2.9.0)
3253 The ``-drive if=scsi'' argument is replaced by the the
3254 ``-device BUS-TYPE'' argument combined with ``-drive if=none''.
3256 @subsection -net dump (since 2.10.0)
3258 The ``--net dump'' argument is now replaced with the
3259 ``-object filter-dump'' argument which works in combination
3260 with the modern ``-netdev`` backends instead.
3262 @subsection -hdachs (since 2.10.0)
3264 The ``-hdachs'' argument is now a synonym for setting
3265 the ``cyls'', ``heads'', ``secs'', and ``trans'' properties
3266 on the ``ide-hd'' device using the ``-device'' argument.
3267 The new syntax allows different settings to be provided
3268 per disk.
3270 @subsection -usbdevice (since 2.10.0)
3272 The ``-usbdevice DEV'' argument is now a synonym for setting
3273 the ``-device usb-DEV'' argument instead. The deprecated syntax
3274 would automatically enable USB support on the machine type.
3275 If using the new syntax, USB support must be explicitly
3276 enabled via the ``-machine usb=on'' argument.
3278 @section qemu-img command line arguments
3280 @subsection convert -s (since 2.0.0)
3282 The ``convert -s snapshot_id_or_name'' argument is obsoleted
3283 by the ``convert -l snapshot_param'' argument instead.
3285 @section System emulator human monitor commands
3287 @subsection host_net_add (since 2.10.0)
3289 The ``host_net_add'' command is replaced by the ``netdev_add'' command.
3291 @subsection host_net_remove (since 2.10.0)
3293 The ``host_net_remove'' command is replaced by the ``netdev_del'' command.
3295 @subsection usb_add (since 2.10.0)
3297 The ``usb_add'' command is replaced by the ``device_add'' command.
3299 @subsection usb_del (since 2.10.0)
3301 The ``usb_del'' command is replaced by the ``device_del'' command.
3303 @section System emulator devices
3305 @subsection ivshmem (since 2.6.0)
3307 The ``ivshmem'' device type is replaced by either the ``ivshmem-plain''
3308 or ``ivshmem-doorbell`` device types.
3310 @subsection spapr-pci-vfio-host-bridge (since 2.6.0)
3312 The ``spapr-pci-vfio-host-bridge'' device type is replaced by
3313 the ``spapr-pci-host-bridge'' device type.
3315 @node License
3316 @appendix License
3318 QEMU is a trademark of Fabrice Bellard.
3320 QEMU is released under the
3321 @url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
3322 version 2. Parts of QEMU have specific licenses, see file
3323 @url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
3325 @node Index
3326 @appendix Index
3327 @menu
3328 * Concept Index::
3329 * Function Index::
3330 * Keystroke Index::
3331 * Program Index::
3332 * Data Type Index::
3333 * Variable Index::
3334 @end menu
3336 @node Concept Index
3337 @section Concept Index
3338 This is the main index. Should we combine all keywords in one index? TODO
3339 @printindex cp
3341 @node Function Index
3342 @section Function Index
3343 This index could be used for command line options and monitor functions.
3344 @printindex fn
3346 @node Keystroke Index
3347 @section Keystroke Index
3349 This is a list of all keystrokes which have a special function
3350 in system emulation.
3352 @printindex ky
3354 @node Program Index
3355 @section Program Index
3356 @printindex pg
3358 @node Data Type Index
3359 @section Data Type Index
3361 This index could be used for qdev device names and options.
3363 @printindex tp
3365 @node Variable Index
3366 @section Variable Index
3367 @printindex vr
3369 @bye