apb: change pbm_pci_host prefix functions to use sabre_pci prefix
[qemu/ar7.git] / qemu-doc.texi
blob3e9eb819a686912816820ad567d285b8c51c8228
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{https://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 @subsection Device URL Syntax
249 @c TODO merge this with section Disk Images
251 @c man begin NOTES
253 In addition to using normal file images for the emulated storage devices,
254 QEMU can also use networked resources such as iSCSI devices. These are
255 specified using a special URL syntax.
257 @table @option
258 @item iSCSI
259 iSCSI support allows QEMU to access iSCSI resources directly and use as
260 images for the guest storage. Both disk and cdrom images are supported.
262 Syntax for specifying iSCSI LUNs is
263 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
265 By default qemu will use the iSCSI initiator-name
266 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
267 line or a configuration file.
269 Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
270 stalled requests and force a reestablishment of the session. The timeout
271 is specified in seconds. The default is 0 which means no timeout. Libiscsi
272 1.15.0 or greater is required for this feature.
274 Example (without authentication):
275 @example
276 qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
277                  -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
278                  -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
279 @end example
281 Example (CHAP username/password via URL):
282 @example
283 qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
284 @end example
286 Example (CHAP username/password via environment variables):
287 @example
288 LIBISCSI_CHAP_USERNAME="user" \
289 LIBISCSI_CHAP_PASSWORD="password" \
290 qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
291 @end example
293 @item NBD
294 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
295 as Unix Domain Sockets.
297 Syntax for specifying a NBD device using TCP
298 ``nbd:<server-ip>:<port>[:exportname=<export>]''
300 Syntax for specifying a NBD device using Unix Domain Sockets
301 ``nbd:unix:<domain-socket>[:exportname=<export>]''
303 Example for TCP
304 @example
305 qemu-system-i386 --drive file=nbd:192.0.2.1:30000
306 @end example
308 Example for Unix Domain Sockets
309 @example
310 qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
311 @end example
313 @item SSH
314 QEMU supports SSH (Secure Shell) access to remote disks.
316 Examples:
317 @example
318 qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
319 qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
320 @end example
322 Currently authentication must be done using ssh-agent.  Other
323 authentication methods may be supported in future.
325 @item Sheepdog
326 Sheepdog is a distributed storage system for QEMU.
327 QEMU supports using either local sheepdog devices or remote networked
328 devices.
330 Syntax for specifying a sheepdog device
331 @example
332 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
333 @end example
335 Example
336 @example
337 qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
338 @end example
340 See also @url{https://sheepdog.github.io/sheepdog/}.
342 @item GlusterFS
343 GlusterFS is a user space distributed file system.
344 QEMU supports the use of GlusterFS volumes for hosting VM disk images using
345 TCP, Unix Domain Sockets and RDMA transport protocols.
347 Syntax for specifying a VM disk image on GlusterFS volume is
348 @example
350 URI:
351 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
353 JSON:
354 'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
355 @                                 "server":[@{"type":"tcp","host":"...","port":"..."@},
356 @                                           @{"type":"unix","socket":"..."@}]@}@}'
357 @end example
360 Example
361 @example
362 URI:
363 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
364 @                               file.debug=9,file.logfile=/var/log/qemu-gluster.log
366 JSON:
367 qemu-system-x86_64 'json:@{"driver":"qcow2",
368 @                          "file":@{"driver":"gluster",
369 @                                   "volume":"testvol","path":"a.img",
370 @                                   "debug":9,"logfile":"/var/log/qemu-gluster.log",
371 @                                   "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
372 @                                             @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
373 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
374 @                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log,
375 @                                      file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
376 @                                      file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
377 @end example
379 See also @url{http://www.gluster.org}.
381 @item HTTP/HTTPS/FTP/FTPS
382 QEMU supports read-only access to files accessed over http(s) and ftp(s).
384 Syntax using a single filename:
385 @example
386 <protocol>://[<username>[:<password>]@@]<host>/<path>
387 @end example
389 where:
390 @table @option
391 @item protocol
392 'http', 'https', 'ftp', or 'ftps'.
394 @item username
395 Optional username for authentication to the remote server.
397 @item password
398 Optional password for authentication to the remote server.
400 @item host
401 Address of the remote server.
403 @item path
404 Path on the remote server, including any query string.
405 @end table
407 The following options are also supported:
408 @table @option
409 @item url
410 The full URL when passing options to the driver explicitly.
412 @item readahead
413 The amount of data to read ahead with each range request to the remote server.
414 This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
415 does not have a suffix, it will be assumed to be in bytes. The value must be a
416 multiple of 512 bytes. It defaults to 256k.
418 @item sslverify
419 Whether to verify the remote server's certificate when connecting over SSL. It
420 can have the value 'on' or 'off'. It defaults to 'on'.
422 @item cookie
423 Send this cookie (it can also be a list of cookies separated by ';') with
424 each outgoing request.  Only supported when using protocols such as HTTP
425 which support cookies, otherwise ignored.
427 @item timeout
428 Set the timeout in seconds of the CURL connection. This timeout is the time
429 that CURL waits for a response from the remote server to get the size of the
430 image to be downloaded. If not set, the default timeout of 5 seconds is used.
431 @end table
433 Note that when passing options to qemu explicitly, @option{driver} is the value
434 of <protocol>.
436 Example: boot from a remote Fedora 20 live ISO image
437 @example
438 qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
440 qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
441 @end example
443 Example: boot from a remote Fedora 20 cloud image using a local overlay for
444 writes, copy-on-read, and a readahead of 64k
445 @example
446 qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
448 qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
449 @end example
451 Example: boot from an image stored on a VMware vSphere server with a self-signed
452 certificate using a local overlay for writes, a readahead of 64k and a timeout
453 of 10 seconds.
454 @example
455 qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
457 qemu-system-x86_64 -drive file=/tmp/test.qcow2
458 @end example
460 @end table
462 @c man end
464 @node pcsys_keys
465 @section Keys in the graphical frontends
467 @c man begin OPTIONS
469 During the graphical emulation, you can use special key combinations to change
470 modes. The default key mappings are shown below, but if you use @code{-alt-grab}
471 then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
472 @code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
474 @table @key
475 @item Ctrl-Alt-f
476 @kindex Ctrl-Alt-f
477 Toggle full screen
479 @item Ctrl-Alt-+
480 @kindex Ctrl-Alt-+
481 Enlarge the screen
483 @item Ctrl-Alt--
484 @kindex Ctrl-Alt--
485 Shrink the screen
487 @item Ctrl-Alt-u
488 @kindex Ctrl-Alt-u
489 Restore the screen's un-scaled dimensions
491 @item Ctrl-Alt-n
492 @kindex Ctrl-Alt-n
493 Switch to virtual console 'n'. Standard console mappings are:
494 @table @emph
495 @item 1
496 Target system display
497 @item 2
498 Monitor
499 @item 3
500 Serial port
501 @end table
503 @item Ctrl-Alt
504 @kindex Ctrl-Alt
505 Toggle mouse and keyboard grab.
506 @end table
508 @kindex Ctrl-Up
509 @kindex Ctrl-Down
510 @kindex Ctrl-PageUp
511 @kindex Ctrl-PageDown
512 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
513 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
515 @c man end
517 @node mux_keys
518 @section Keys in the character backend multiplexer
520 @c man begin OPTIONS
522 During emulation, if you are using a character backend multiplexer
523 (which is the default if you are using @option{-nographic}) then
524 several commands are available via an escape sequence. These
525 key sequences all start with an escape character, which is @key{Ctrl-a}
526 by default, but can be changed with @option{-echr}. The list below assumes
527 you're using the default.
529 @table @key
530 @item Ctrl-a h
531 @kindex Ctrl-a h
532 Print this help
533 @item Ctrl-a x
534 @kindex Ctrl-a x
535 Exit emulator
536 @item Ctrl-a s
537 @kindex Ctrl-a s
538 Save disk data back to file (if -snapshot)
539 @item Ctrl-a t
540 @kindex Ctrl-a t
541 Toggle console timestamps
542 @item Ctrl-a b
543 @kindex Ctrl-a b
544 Send break (magic sysrq in Linux)
545 @item Ctrl-a c
546 @kindex Ctrl-a c
547 Rotate between the frontends connected to the multiplexer (usually
548 this switches between the monitor and the console)
549 @item Ctrl-a Ctrl-a
550 @kindex Ctrl-a Ctrl-a
551 Send the escape character to the frontend
552 @end table
553 @c man end
555 @ignore
557 @c man begin SEEALSO
558 The HTML documentation of QEMU for more precise information and Linux
559 user mode emulator invocation.
560 @c man end
562 @c man begin AUTHOR
563 Fabrice Bellard
564 @c man end
566 @end ignore
568 @node pcsys_monitor
569 @section QEMU Monitor
570 @cindex QEMU monitor
572 The QEMU monitor is used to give complex commands to the QEMU
573 emulator. You can use it to:
575 @itemize @minus
577 @item
578 Remove or insert removable media images
579 (such as CD-ROM or floppies).
581 @item
582 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
583 from a disk file.
585 @item Inspect the VM state without an external debugger.
587 @end itemize
589 @subsection Commands
591 The following commands are available:
593 @include qemu-monitor.texi
595 @include qemu-monitor-info.texi
597 @subsection Integer expressions
599 The monitor understands integers expressions for every integer
600 argument. You can use register names to get the value of specifics
601 CPU registers by prefixing them with @emph{$}.
603 @node disk_images
604 @section Disk Images
606 QEMU supports many disk image formats, including growable disk images
607 (their size increase as non empty sectors are written), compressed and
608 encrypted disk images.
610 @menu
611 * disk_images_quickstart::    Quick start for disk image creation
612 * disk_images_snapshot_mode:: Snapshot mode
613 * vm_snapshots::              VM snapshots
614 * qemu_img_invocation::       qemu-img Invocation
615 * qemu_nbd_invocation::       qemu-nbd Invocation
616 * disk_images_formats::       Disk image file formats
617 * host_drives::               Using host drives
618 * disk_images_fat_images::    Virtual FAT disk images
619 * disk_images_nbd::           NBD access
620 * disk_images_sheepdog::      Sheepdog disk images
621 * disk_images_iscsi::         iSCSI LUNs
622 * disk_images_gluster::       GlusterFS disk images
623 * disk_images_ssh::           Secure Shell (ssh) disk images
624 * disk_image_locking::        Disk image file locking
625 @end menu
627 @node disk_images_quickstart
628 @subsection Quick start for disk image creation
630 You can create a disk image with the command:
631 @example
632 qemu-img create myimage.img mysize
633 @end example
634 where @var{myimage.img} is the disk image filename and @var{mysize} is its
635 size in kilobytes. You can add an @code{M} suffix to give the size in
636 megabytes and a @code{G} suffix for gigabytes.
638 See @ref{qemu_img_invocation} for more information.
640 @node disk_images_snapshot_mode
641 @subsection Snapshot mode
643 If you use the option @option{-snapshot}, all disk images are
644 considered as read only. When sectors in written, they are written in
645 a temporary file created in @file{/tmp}. You can however force the
646 write back to the raw disk images by using the @code{commit} monitor
647 command (or @key{C-a s} in the serial console).
649 @node vm_snapshots
650 @subsection VM snapshots
652 VM snapshots are snapshots of the complete virtual machine including
653 CPU state, RAM, device state and the content of all the writable
654 disks. In order to use VM snapshots, you must have at least one non
655 removable and writable block device using the @code{qcow2} disk image
656 format. Normally this device is the first virtual hard drive.
658 Use the monitor command @code{savevm} to create a new VM snapshot or
659 replace an existing one. A human readable name can be assigned to each
660 snapshot in addition to its numerical ID.
662 Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
663 a VM snapshot. @code{info snapshots} lists the available snapshots
664 with their associated information:
666 @example
667 (qemu) info snapshots
668 Snapshot devices: hda
669 Snapshot list (from hda):
670 ID        TAG                 VM SIZE                DATE       VM CLOCK
671 1         start                   41M 2006-08-06 12:38:02   00:00:14.954
672 2                                 40M 2006-08-06 12:43:29   00:00:18.633
673 3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
674 @end example
676 A VM snapshot is made of a VM state info (its size is shown in
677 @code{info snapshots}) and a snapshot of every writable disk image.
678 The VM state info is stored in the first @code{qcow2} non removable
679 and writable block device. The disk image snapshots are stored in
680 every disk image. The size of a snapshot in a disk image is difficult
681 to evaluate and is not shown by @code{info snapshots} because the
682 associated disk sectors are shared among all the snapshots to save
683 disk space (otherwise each snapshot would need a full copy of all the
684 disk images).
686 When using the (unrelated) @code{-snapshot} option
687 (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
688 but they are deleted as soon as you exit QEMU.
690 VM snapshots currently have the following known limitations:
691 @itemize
692 @item
693 They cannot cope with removable devices if they are removed or
694 inserted after a snapshot is done.
695 @item
696 A few device drivers still have incomplete snapshot support so their
697 state is not saved or restored properly (in particular USB).
698 @end itemize
700 @node qemu_img_invocation
701 @subsection @code{qemu-img} Invocation
703 @include qemu-img.texi
705 @node qemu_nbd_invocation
706 @subsection @code{qemu-nbd} Invocation
708 @include qemu-nbd.texi
710 @include docs/qemu-block-drivers.texi
712 @node pcsys_network
713 @section Network emulation
715 QEMU can simulate several network cards (PCI or ISA cards on the PC
716 target) and can connect them to an arbitrary number of Virtual Local
717 Area Networks (VLANs). Host TAP devices can be connected to any QEMU
718 VLAN. VLAN can be connected between separate instances of QEMU to
719 simulate large networks. For simpler usage, a non privileged user mode
720 network stack can replace the TAP device to have a basic network
721 connection.
723 @subsection VLANs
725 QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
726 connection between several network devices. These devices can be for
727 example QEMU virtual Ethernet cards or virtual Host ethernet devices
728 (TAP devices).
730 @subsection Using TAP network interfaces
732 This is the standard way to connect QEMU to a real network. QEMU adds
733 a virtual network device on your host (called @code{tapN}), and you
734 can then configure it as if it was a real ethernet card.
736 @subsubsection Linux host
738 As an example, you can download the @file{linux-test-xxx.tar.gz}
739 archive and copy the script @file{qemu-ifup} in @file{/etc} and
740 configure properly @code{sudo} so that the command @code{ifconfig}
741 contained in @file{qemu-ifup} can be executed as root. You must verify
742 that your host kernel supports the TAP network interfaces: the
743 device @file{/dev/net/tun} must be present.
745 See @ref{sec_invocation} to have examples of command lines using the
746 TAP network interfaces.
748 @subsubsection Windows host
750 There is a virtual ethernet driver for Windows 2000/XP systems, called
751 TAP-Win32. But it is not included in standard QEMU for Windows,
752 so you will need to get it separately. It is part of OpenVPN package,
753 so download OpenVPN from : @url{https://openvpn.net/}.
755 @subsection Using the user mode network stack
757 By using the option @option{-net user} (default configuration if no
758 @option{-net} option is specified), QEMU uses a completely user mode
759 network stack (you don't need root privilege to use the virtual
760 network). The virtual network configuration is the following:
762 @example
764          QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
765                            |          (10.0.2.2)
766                            |
767                            ---->  DNS server (10.0.2.3)
768                            |
769                            ---->  SMB server (10.0.2.4)
770 @end example
772 The QEMU VM behaves as if it was behind a firewall which blocks all
773 incoming connections. You can use a DHCP client to automatically
774 configure the network in the QEMU VM. The DHCP server assign addresses
775 to the hosts starting from 10.0.2.15.
777 In order to check that the user mode network is working, you can ping
778 the address 10.0.2.2 and verify that you got an address in the range
779 10.0.2.x from the QEMU virtual DHCP server.
781 Note that ICMP traffic in general does not work with user mode networking.
782 @code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
783 however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
784 ping sockets to allow @code{ping} to the Internet. The host admin has to set
785 the ping_group_range in order to grant access to those sockets. To allow ping
786 for GID 100 (usually users group):
788 @example
789 echo 100 100 > /proc/sys/net/ipv4/ping_group_range
790 @end example
792 When using the built-in TFTP server, the router is also the TFTP
793 server.
795 When using the @option{'-netdev user,hostfwd=...'} option, TCP or UDP
796 connections can be redirected from the host to the guest. It allows for
797 example to redirect X11, telnet or SSH connections.
799 @subsection Connecting VLANs between QEMU instances
801 Using the @option{-net socket} option, it is possible to make VLANs
802 that span several QEMU instances. See @ref{sec_invocation} to have a
803 basic example.
805 @node pcsys_other_devs
806 @section Other Devices
808 @subsection Inter-VM Shared Memory device
810 On Linux hosts, a shared memory device is available.  The basic syntax
813 @example
814 qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem}
815 @end example
817 where @var{hostmem} names a host memory backend.  For a POSIX shared
818 memory backend, use something like
820 @example
821 -object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
822 @end example
824 If desired, interrupts can be sent between guest VMs accessing the same shared
825 memory region.  Interrupt support requires using a shared memory server and
826 using a chardev socket to connect to it.  The code for the shared memory server
827 is qemu.git/contrib/ivshmem-server.  An example syntax when using the shared
828 memory server is:
830 @example
831 # First start the ivshmem server once and for all
832 ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}
834 # Then start your qemu instances with matching arguments
835 qemu-system-x86_64 -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
836                  -chardev socket,path=@var{path},id=@var{id}
837 @end example
839 When using the server, the guest will be assigned a VM ID (>=0) that allows guests
840 using the same server to communicate via interrupts.  Guests can read their
841 VM ID from a device register (see ivshmem-spec.txt).
843 @subsubsection Migration with ivshmem
845 With device property @option{master=on}, the guest will copy the shared
846 memory on migration to the destination host.  With @option{master=off},
847 the guest will not be able to migrate with the device attached.  In the
848 latter case, the device should be detached and then reattached after
849 migration using the PCI hotplug support.
851 At most one of the devices sharing the same memory can be master.  The
852 master must complete migration before you plug back the other devices.
854 @subsubsection ivshmem and hugepages
856 Instead of specifying the <shm size> using POSIX shm, you may specify
857 a memory backend that has hugepage support:
859 @example
860 qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
861                  -device ivshmem-plain,memdev=mb1
862 @end example
864 ivshmem-server also supports hugepages mount points with the
865 @option{-m} memory path argument.
867 @node direct_linux_boot
868 @section Direct Linux Boot
870 This section explains how to launch a Linux kernel inside QEMU without
871 having to make a full bootable image. It is very useful for fast Linux
872 kernel testing.
874 The syntax is:
875 @example
876 qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
877 @end example
879 Use @option{-kernel} to provide the Linux kernel image and
880 @option{-append} to give the kernel command line arguments. The
881 @option{-initrd} option can be used to provide an INITRD image.
883 When using the direct Linux boot, a disk image for the first hard disk
884 @file{hda} is required because its boot sector is used to launch the
885 Linux kernel.
887 If you do not need graphical output, you can disable it and redirect
888 the virtual serial port and the QEMU monitor to the console with the
889 @option{-nographic} option. The typical command line is:
890 @example
891 qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
892                  -append "root=/dev/hda console=ttyS0" -nographic
893 @end example
895 Use @key{Ctrl-a c} to switch between the serial console and the
896 monitor (@pxref{pcsys_keys}).
898 @node pcsys_usb
899 @section USB emulation
901 QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
902 plug virtual USB devices or real host USB devices (only works with certain
903 host operating systems). QEMU will automatically create and connect virtual
904 USB hubs as necessary to connect multiple USB devices.
906 @menu
907 * usb_devices::
908 * host_usb_devices::
909 @end menu
910 @node usb_devices
911 @subsection Connecting USB devices
913 USB devices can be connected with the @option{-device usb-...} command line
914 option or the @code{device_add} monitor command. Available devices are:
916 @table @code
917 @item usb-mouse
918 Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
919 @item usb-tablet
920 Pointer device that uses absolute coordinates (like a touchscreen).
921 This means QEMU is able to report the mouse position without having
922 to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
923 @item usb-storage,drive=@var{drive_id}
924 Mass storage device backed by @var{drive_id} (@pxref{disk_images})
925 @item usb-uas
926 USB attached SCSI device, see
927 @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
928 for details
929 @item usb-bot
930 Bulk-only transport storage device, see
931 @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
932 for details here, too
933 @item usb-mtp,x-root=@var{dir}
934 Media transfer protocol device, using @var{dir} as root of the file tree
935 that is presented to the guest.
936 @item usb-host,hostbus=@var{bus},hostaddr=@var{addr}
937 Pass through the host device identified by @var{bus} and @var{addr}
938 @item usb-host,vendorid=@var{vendor},productid=@var{product}
939 Pass through the host device identified by @var{vendor} and @var{product} ID
940 @item usb-wacom-tablet
941 Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
942 above but it can be used with the tslib library because in addition to touch
943 coordinates it reports touch pressure.
944 @item usb-kbd
945 Standard USB keyboard.  Will override the PS/2 keyboard (if present).
946 @item usb-serial,chardev=@var{id}
947 Serial converter. This emulates an FTDI FT232BM chip connected to host character
948 device @var{id}.
949 @item usb-braille,chardev=@var{id}
950 Braille device.  This will use BrlAPI to display the braille output on a real
951 or fake device referenced by @var{id}.
952 @item usb-net[,netdev=@var{id}]
953 Network adapter that supports CDC ethernet and RNDIS protocols.  @var{id}
954 specifies a netdev defined with @code{-netdev @dots{},id=@var{id}}.
955 For instance, user-mode networking can be used with
956 @example
957 qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
958 @end example
959 @item usb-ccid
960 Smartcard reader device
961 @item usb-audio
962 USB audio device
963 @item usb-bt-dongle
964 Bluetooth dongle for the transport layer of HCI. It is connected to HCI
965 scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}).
966 Note that the syntax for the @code{-device usb-bt-dongle} option is not as
967 useful yet as it was with the legacy @code{-usbdevice} option. So to
968 configure an USB bluetooth device, you might need to use
969 "@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a
970 bluetooth dongle whose type is specified in the same format as with
971 the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
972 no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
973 This USB device implements the USB Transport Layer of HCI.  Example
974 usage:
975 @example
976 @command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3
977 @end example
978 @end table
980 @node host_usb_devices
981 @subsection Using host USB devices on a Linux host
983 WARNING: this is an experimental feature. QEMU will slow down when
984 using it. USB devices requiring real time streaming (i.e. USB Video
985 Cameras) are not supported yet.
987 @enumerate
988 @item If you use an early Linux 2.4 kernel, verify that no Linux driver
989 is actually using the USB device. A simple way to do that is simply to
990 disable the corresponding kernel module by renaming it from @file{mydriver.o}
991 to @file{mydriver.o.disabled}.
993 @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
994 @example
995 ls /proc/bus/usb
996 001  devices  drivers
997 @end example
999 @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:
1000 @example
1001 chown -R myuid /proc/bus/usb
1002 @end example
1004 @item Launch QEMU and do in the monitor:
1005 @example
1006 info usbhost
1007   Device 1.2, speed 480 Mb/s
1008     Class 00: USB device 1234:5678, USB DISK
1009 @end example
1010 You should see the list of the devices you can use (Never try to use
1011 hubs, it won't work).
1013 @item Add the device in QEMU by using:
1014 @example
1015 device_add usb-host,vendorid=0x1234,productid=0x5678
1016 @end example
1018 Normally the guest OS should report that a new USB device is plugged.
1019 You can use the option @option{-device usb-host,...} to do the same.
1021 @item Now you can try to use the host USB device in QEMU.
1023 @end enumerate
1025 When relaunching QEMU, you may have to unplug and plug again the USB
1026 device to make it work again (this is a bug).
1028 @node vnc_security
1029 @section VNC security
1031 The VNC server capability provides access to the graphical console
1032 of the guest VM across the network. This has a number of security
1033 considerations depending on the deployment scenarios.
1035 @menu
1036 * vnc_sec_none::
1037 * vnc_sec_password::
1038 * vnc_sec_certificate::
1039 * vnc_sec_certificate_verify::
1040 * vnc_sec_certificate_pw::
1041 * vnc_sec_sasl::
1042 * vnc_sec_certificate_sasl::
1043 * vnc_generate_cert::
1044 * vnc_setup_sasl::
1045 @end menu
1046 @node vnc_sec_none
1047 @subsection Without passwords
1049 The simplest VNC server setup does not include any form of authentication.
1050 For this setup it is recommended to restrict it to listen on a UNIX domain
1051 socket only. For example
1053 @example
1054 qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1055 @end example
1057 This ensures that only users on local box with read/write access to that
1058 path can access the VNC server. To securely access the VNC server from a
1059 remote machine, a combination of netcat+ssh can be used to provide a secure
1060 tunnel.
1062 @node vnc_sec_password
1063 @subsection With passwords
1065 The VNC protocol has limited support for password based authentication. Since
1066 the protocol limits passwords to 8 characters it should not be considered
1067 to provide high security. The password can be fairly easily brute-forced by
1068 a client making repeat connections. For this reason, a VNC server using password
1069 authentication should be restricted to only listen on the loopback interface
1070 or UNIX domain sockets. Password authentication is not supported when operating
1071 in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
1072 authentication is requested with the @code{password} option, and then once QEMU
1073 is running the password is set with the monitor. Until the monitor is used to
1074 set the password all clients will be rejected.
1076 @example
1077 qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
1078 (qemu) change vnc password
1079 Password: ********
1080 (qemu)
1081 @end example
1083 @node vnc_sec_certificate
1084 @subsection With x509 certificates
1086 The QEMU VNC server also implements the VeNCrypt extension allowing use of
1087 TLS for encryption of the session, and x509 certificates for authentication.
1088 The use of x509 certificates is strongly recommended, because TLS on its
1089 own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1090 support provides a secure session, but no authentication. This allows any
1091 client to connect, and provides an encrypted session.
1093 @example
1094 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1095 @end example
1097 In the above example @code{/etc/pki/qemu} should contain at least three files,
1098 @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1099 users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1100 NB the @code{server-key.pem} file should be protected with file mode 0600 to
1101 only be readable by the user owning it.
1103 @node vnc_sec_certificate_verify
1104 @subsection With x509 certificates and client verification
1106 Certificates can also provide a means to authenticate the client connecting.
1107 The server will request that the client provide a certificate, which it will
1108 then validate against the CA certificate. This is a good choice if deploying
1109 in an environment with a private internal certificate authority.
1111 @example
1112 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1113 @end example
1116 @node vnc_sec_certificate_pw
1117 @subsection With x509 certificates, client verification and passwords
1119 Finally, the previous method can be combined with VNC password authentication
1120 to provide two layers of authentication for clients.
1122 @example
1123 qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1124 (qemu) change vnc password
1125 Password: ********
1126 (qemu)
1127 @end example
1130 @node vnc_sec_sasl
1131 @subsection With SASL authentication
1133 The SASL authentication method is a VNC extension, that provides an
1134 easily extendable, pluggable authentication method. This allows for
1135 integration with a wide range of authentication mechanisms, such as
1136 PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1137 The strength of the authentication depends on the exact mechanism
1138 configured. If the chosen mechanism also provides a SSF layer, then
1139 it will encrypt the datastream as well.
1141 Refer to the later docs on how to choose the exact SASL mechanism
1142 used for authentication, but assuming use of one supporting SSF,
1143 then QEMU can be launched with:
1145 @example
1146 qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
1147 @end example
1149 @node vnc_sec_certificate_sasl
1150 @subsection With x509 certificates and SASL authentication
1152 If the desired SASL authentication mechanism does not supported
1153 SSF layers, then it is strongly advised to run it in combination
1154 with TLS and x509 certificates. This provides securely encrypted
1155 data stream, avoiding risk of compromising of the security
1156 credentials. This can be enabled, by combining the 'sasl' option
1157 with the aforementioned TLS + x509 options:
1159 @example
1160 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
1161 @end example
1164 @node vnc_generate_cert
1165 @subsection Generating certificates for VNC
1167 The GNU TLS packages provides a command called @code{certtool} which can
1168 be used to generate certificates and keys in PEM format. At a minimum it
1169 is necessary to setup a certificate authority, and issue certificates to
1170 each server. If using certificates for authentication, then each client
1171 will also need to be issued a certificate. The recommendation is for the
1172 server to keep its certificates in either @code{/etc/pki/qemu} or for
1173 unprivileged users in @code{$HOME/.pki/qemu}.
1175 @menu
1176 * vnc_generate_ca::
1177 * vnc_generate_server::
1178 * vnc_generate_client::
1179 @end menu
1180 @node vnc_generate_ca
1181 @subsubsection Setup the Certificate Authority
1183 This step only needs to be performed once per organization / organizational
1184 unit. First the CA needs a private key. This key must be kept VERY secret
1185 and secure. If this key is compromised the entire trust chain of the certificates
1186 issued with it is lost.
1188 @example
1189 # certtool --generate-privkey > ca-key.pem
1190 @end example
1192 A CA needs to have a public certificate. For simplicity it can be a self-signed
1193 certificate, or one issue by a commercial certificate issuing authority. To
1194 generate a self-signed certificate requires one core piece of information, the
1195 name of the organization.
1197 @example
1198 # cat > ca.info <<EOF
1199 cn = Name of your organization
1201 cert_signing_key
1203 # certtool --generate-self-signed \
1204            --load-privkey ca-key.pem
1205            --template ca.info \
1206            --outfile ca-cert.pem
1207 @end example
1209 The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1210 TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1212 @node vnc_generate_server
1213 @subsubsection Issuing server certificates
1215 Each server (or host) needs to be issued with a key and certificate. When connecting
1216 the certificate is sent to the client which validates it against the CA certificate.
1217 The core piece of information for a server certificate is the hostname. This should
1218 be the fully qualified hostname that the client will connect with, since the client
1219 will typically also verify the hostname in the certificate. On the host holding the
1220 secure CA private key:
1222 @example
1223 # cat > server.info <<EOF
1224 organization = Name  of your organization
1225 cn = server.foo.example.com
1226 tls_www_server
1227 encryption_key
1228 signing_key
1230 # certtool --generate-privkey > server-key.pem
1231 # certtool --generate-certificate \
1232            --load-ca-certificate ca-cert.pem \
1233            --load-ca-privkey ca-key.pem \
1234            --load-privkey server-key.pem \
1235            --template server.info \
1236            --outfile server-cert.pem
1237 @end example
1239 The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1240 to the server for which they were generated. The @code{server-key.pem} is security
1241 sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1243 @node vnc_generate_client
1244 @subsubsection Issuing client certificates
1246 If the QEMU VNC server is to use the @code{x509verify} option to validate client
1247 certificates as its authentication mechanism, each client also needs to be issued
1248 a certificate. The client certificate contains enough metadata to uniquely identify
1249 the client, typically organization, state, city, building, etc. On the host holding
1250 the secure CA private key:
1252 @example
1253 # cat > client.info <<EOF
1254 country = GB
1255 state = London
1256 locality = London
1257 organization = Name of your organization
1258 cn = client.foo.example.com
1259 tls_www_client
1260 encryption_key
1261 signing_key
1263 # certtool --generate-privkey > client-key.pem
1264 # certtool --generate-certificate \
1265            --load-ca-certificate ca-cert.pem \
1266            --load-ca-privkey ca-key.pem \
1267            --load-privkey client-key.pem \
1268            --template client.info \
1269            --outfile client-cert.pem
1270 @end example
1272 The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1273 copied to the client for which they were generated.
1276 @node vnc_setup_sasl
1278 @subsection Configuring SASL mechanisms
1280 The following documentation assumes use of the Cyrus SASL implementation on a
1281 Linux host, but the principals should apply to any other SASL impl. When SASL
1282 is enabled, the mechanism configuration will be loaded from system default
1283 SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1284 unprivileged user, an environment variable SASL_CONF_PATH can be used
1285 to make it search alternate locations for the service config.
1287 If the TLS option is enabled for VNC, then it will provide session encryption,
1288 otherwise the SASL mechanism will have to provide encryption. In the latter
1289 case the list of possible plugins that can be used is drastically reduced. In
1290 fact only the GSSAPI SASL mechanism provides an acceptable level of security
1291 by modern standards. Previous versions of QEMU referred to the DIGEST-MD5
1292 mechanism, however, it has multiple serious flaws described in detail in
1293 RFC 6331 and thus should never be used any more. The SCRAM-SHA-1 mechanism
1294 provides a simple username/password auth facility similar to DIGEST-MD5, but
1295 does not support session encryption, so can only be used in combination with
1296 TLS.
1298 When not using TLS the recommended configuration is
1300 @example
1301 mech_list: gssapi
1302 keytab: /etc/qemu/krb5.tab
1303 @end example
1305 This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol, with
1306 the server principal stored in /etc/qemu/krb5.tab. For this to work the
1307 administrator of your KDC must generate a Kerberos principal for the server,
1308 with a name of 'qemu/somehost.example.com@@EXAMPLE.COM' replacing
1309 'somehost.example.com' with the fully qualified host name of the machine
1310 running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
1312 When using TLS, if username+password authentication is desired, then a
1313 reasonable configuration is
1315 @example
1316 mech_list: scram-sha-1
1317 sasldb_path: /etc/qemu/passwd.db
1318 @end example
1320 The saslpasswd2 program can be used to populate the passwd.db file with
1321 accounts.
1323 Other SASL configurations will be left as an exercise for the reader. Note that
1324 all mechanisms except GSSAPI, should be combined with use of TLS to ensure a
1325 secure data channel.
1327 @node gdb_usage
1328 @section GDB usage
1330 QEMU has a primitive support to work with gdb, so that you can do
1331 'Ctrl-C' while the virtual machine is running and inspect its state.
1333 In order to use gdb, launch QEMU with the '-s' option. It will wait for a
1334 gdb connection:
1335 @example
1336 qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1337                     -append "root=/dev/hda"
1338 Connected to host network interface: tun0
1339 Waiting gdb connection on port 1234
1340 @end example
1342 Then launch gdb on the 'vmlinux' executable:
1343 @example
1344 > gdb vmlinux
1345 @end example
1347 In gdb, connect to QEMU:
1348 @example
1349 (gdb) target remote localhost:1234
1350 @end example
1352 Then you can use gdb normally. For example, type 'c' to launch the kernel:
1353 @example
1354 (gdb) c
1355 @end example
1357 Here are some useful tips in order to use gdb on system code:
1359 @enumerate
1360 @item
1361 Use @code{info reg} to display all the CPU registers.
1362 @item
1363 Use @code{x/10i $eip} to display the code at the PC position.
1364 @item
1365 Use @code{set architecture i8086} to dump 16 bit code. Then use
1366 @code{x/10i $cs*16+$eip} to dump the code at the PC position.
1367 @end enumerate
1369 Advanced debugging options:
1371 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:
1372 @table @code
1373 @item maintenance packet qqemu.sstepbits
1375 This will display the MASK bits used to control the single stepping IE:
1376 @example
1377 (gdb) maintenance packet qqemu.sstepbits
1378 sending: "qqemu.sstepbits"
1379 received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1380 @end example
1381 @item maintenance packet qqemu.sstep
1383 This will display the current value of the mask used when single stepping IE:
1384 @example
1385 (gdb) maintenance packet qqemu.sstep
1386 sending: "qqemu.sstep"
1387 received: "0x7"
1388 @end example
1389 @item maintenance packet Qqemu.sstep=HEX_VALUE
1391 This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1392 @example
1393 (gdb) maintenance packet Qqemu.sstep=0x5
1394 sending: "qemu.sstep=0x5"
1395 received: "OK"
1396 @end example
1397 @end table
1399 @node pcsys_os_specific
1400 @section Target OS specific information
1402 @subsection Linux
1404 To have access to SVGA graphic modes under X11, use the @code{vesa} or
1405 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1406 color depth in the guest and the host OS.
1408 When using a 2.6 guest Linux kernel, you should add the option
1409 @code{clock=pit} on the kernel command line because the 2.6 Linux
1410 kernels make very strict real time clock checks by default that QEMU
1411 cannot simulate exactly.
1413 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1414 not activated because QEMU is slower with this patch. The QEMU
1415 Accelerator Module is also much slower in this case. Earlier Fedora
1416 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1417 patch by default. Newer kernels don't have it.
1419 @subsection Windows
1421 If you have a slow host, using Windows 95 is better as it gives the
1422 best speed. Windows 2000 is also a good choice.
1424 @subsubsection SVGA graphic modes support
1426 QEMU emulates a Cirrus Logic GD5446 Video
1427 card. All Windows versions starting from Windows 95 should recognize
1428 and use this graphic card. For optimal performances, use 16 bit color
1429 depth in the guest and the host OS.
1431 If you are using Windows XP as guest OS and if you want to use high
1432 resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
1433 1280x1024x16), then you should use the VESA VBE virtual graphic card
1434 (option @option{-std-vga}).
1436 @subsubsection CPU usage reduction
1438 Windows 9x does not correctly use the CPU HLT
1439 instruction. The result is that it takes host CPU cycles even when
1440 idle. You can install the utility from
1441 @url{https://web.archive.org/web/20060212132151/http://www.user.cityline.ru/~maxamn/amnhltm.zip}
1442 to solve this problem. Note that no such tool is needed for NT, 2000 or XP.
1444 @subsubsection Windows 2000 disk full problem
1446 Windows 2000 has a bug which gives a disk full problem during its
1447 installation. When installing it, use the @option{-win2k-hack} QEMU
1448 option to enable a specific workaround. After Windows 2000 is
1449 installed, you no longer need this option (this option slows down the
1450 IDE transfers).
1452 @subsubsection Windows 2000 shutdown
1454 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1455 can. It comes from the fact that Windows 2000 does not automatically
1456 use the APM driver provided by the BIOS.
1458 In order to correct that, do the following (thanks to Struan
1459 Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1460 Add/Troubleshoot a device => Add a new device & Next => No, select the
1461 hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1462 (again) a few times. Now the driver is installed and Windows 2000 now
1463 correctly instructs QEMU to shutdown at the appropriate moment.
1465 @subsubsection Share a directory between Unix and Windows
1467 See @ref{sec_invocation} about the help of the option
1468 @option{'-netdev user,smb=...'}.
1470 @subsubsection Windows XP security problem
1472 Some releases of Windows XP install correctly but give a security
1473 error when booting:
1474 @example
1475 A problem is preventing Windows from accurately checking the
1476 license for this computer. Error code: 0x800703e6.
1477 @end example
1479 The workaround is to install a service pack for XP after a boot in safe
1480 mode. Then reboot, and the problem should go away. Since there is no
1481 network while in safe mode, its recommended to download the full
1482 installation of SP1 or SP2 and transfer that via an ISO or using the
1483 vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1485 @subsection MS-DOS and FreeDOS
1487 @subsubsection CPU usage reduction
1489 DOS does not correctly use the CPU HLT instruction. The result is that
1490 it takes host CPU cycles even when idle. You can install the utility from
1491 @url{https://web.archive.org/web/20051222085335/http://www.vmware.com/software/dosidle210.zip}
1492 to solve this problem.
1494 @node QEMU System emulator for non PC targets
1495 @chapter QEMU System emulator for non PC targets
1497 QEMU is a generic emulator and it emulates many non PC
1498 machines. Most of the options are similar to the PC emulator. The
1499 differences are mentioned in the following sections.
1501 @menu
1502 * PowerPC System emulator::
1503 * Sparc32 System emulator::
1504 * Sparc64 System emulator::
1505 * MIPS System emulator::
1506 * ARM System emulator::
1507 * ColdFire System emulator::
1508 * Cris System emulator::
1509 * Microblaze System emulator::
1510 * SH4 System emulator::
1511 * Xtensa System emulator::
1512 @end menu
1514 @node PowerPC System emulator
1515 @section PowerPC System emulator
1516 @cindex system emulation (PowerPC)
1518 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1519 or PowerMac PowerPC system.
1521 QEMU emulates the following PowerMac peripherals:
1523 @itemize @minus
1524 @item
1525 UniNorth or Grackle PCI Bridge
1526 @item
1527 PCI VGA compatible card with VESA Bochs Extensions
1528 @item
1529 2 PMAC IDE interfaces with hard disk and CD-ROM support
1530 @item
1531 NE2000 PCI adapters
1532 @item
1533 Non Volatile RAM
1534 @item
1535 VIA-CUDA with ADB keyboard and mouse.
1536 @end itemize
1538 QEMU emulates the following PREP peripherals:
1540 @itemize @minus
1541 @item
1542 PCI Bridge
1543 @item
1544 PCI VGA compatible card with VESA Bochs Extensions
1545 @item
1546 2 IDE interfaces with hard disk and CD-ROM support
1547 @item
1548 Floppy disk
1549 @item
1550 NE2000 network adapters
1551 @item
1552 Serial port
1553 @item
1554 PREP Non Volatile RAM
1555 @item
1556 PC compatible keyboard and mouse.
1557 @end itemize
1559 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1560 @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
1562 Since version 0.9.1, QEMU uses OpenBIOS @url{https://www.openbios.org/}
1563 for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1564 v2) portable firmware implementation. The goal is to implement a 100%
1565 IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
1567 @c man begin OPTIONS
1569 The following options are specific to the PowerPC emulation:
1571 @table @option
1573 @item -g @var{W}x@var{H}[x@var{DEPTH}]
1575 Set the initial VGA graphic mode. The default is 800x600x32.
1577 @item -prom-env @var{string}
1579 Set OpenBIOS variables in NVRAM, for example:
1581 @example
1582 qemu-system-ppc -prom-env 'auto-boot?=false' \
1583  -prom-env 'boot-device=hd:2,\yaboot' \
1584  -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1585 @end example
1587 These variables are not used by Open Hack'Ware.
1589 @end table
1591 @c man end
1594 More information is available at
1595 @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1597 @node Sparc32 System emulator
1598 @section Sparc32 System emulator
1599 @cindex system emulation (Sparc32)
1601 Use the executable @file{qemu-system-sparc} to simulate the following
1602 Sun4m architecture machines:
1603 @itemize @minus
1604 @item
1605 SPARCstation 4
1606 @item
1607 SPARCstation 5
1608 @item
1609 SPARCstation 10
1610 @item
1611 SPARCstation 20
1612 @item
1613 SPARCserver 600MP
1614 @item
1615 SPARCstation LX
1616 @item
1617 SPARCstation Voyager
1618 @item
1619 SPARCclassic
1620 @item
1621 SPARCbook
1622 @end itemize
1624 The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1625 but Linux limits the number of usable CPUs to 4.
1627 QEMU emulates the following sun4m peripherals:
1629 @itemize @minus
1630 @item
1631 IOMMU
1632 @item
1633 TCX or cgthree Frame buffer
1634 @item
1635 Lance (Am7990) Ethernet
1636 @item
1637 Non Volatile RAM M48T02/M48T08
1638 @item
1639 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1640 and power/reset logic
1641 @item
1642 ESP SCSI controller with hard disk and CD-ROM support
1643 @item
1644 Floppy drive (not on SS-600MP)
1645 @item
1646 CS4231 sound device (only on SS-5, not working yet)
1647 @end itemize
1649 The number of peripherals is fixed in the architecture.  Maximum
1650 memory size depends on the machine type, for SS-5 it is 256MB and for
1651 others 2047MB.
1653 Since version 0.8.2, QEMU uses OpenBIOS
1654 @url{https://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1655 firmware implementation. The goal is to implement a 100% IEEE
1656 1275-1994 (referred to as Open Firmware) compliant firmware.
1658 A sample Linux 2.6 series kernel and ram disk image are available on
1659 the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1660 most kernel versions work. Please note that currently older Solaris kernels
1661 don't work probably due to interface issues between OpenBIOS and
1662 Solaris.
1664 @c man begin OPTIONS
1666 The following options are specific to the Sparc32 emulation:
1668 @table @option
1670 @item -g @var{W}x@var{H}x[x@var{DEPTH}]
1672 Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
1673 option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
1674 of 1152x900x8 for people who wish to use OBP.
1676 @item -prom-env @var{string}
1678 Set OpenBIOS variables in NVRAM, for example:
1680 @example
1681 qemu-system-sparc -prom-env 'auto-boot?=false' \
1682  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1683 @end example
1685 @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]
1687 Set the emulated machine type. Default is SS-5.
1689 @end table
1691 @c man end
1693 @node Sparc64 System emulator
1694 @section Sparc64 System emulator
1695 @cindex system emulation (Sparc64)
1697 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1698 (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1699 Niagara (T1) machine. The Sun4u emulator is mostly complete, being
1700 able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
1701 Sun4v emulator is still a work in progress.
1703 The Niagara T1 emulator makes use of firmware and OS binaries supplied in the S10image/ directory
1704 of the OpenSPARC T1 project @url{http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2}
1705 and is able to boot the disk.s10hw2 Solaris image.
1706 @example
1707 qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
1708                     -nographic -m 256 \
1709                     -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
1710 @end example
1713 QEMU emulates the following peripherals:
1715 @itemize @minus
1716 @item
1717 UltraSparc IIi APB PCI Bridge
1718 @item
1719 PCI VGA compatible card with VESA Bochs Extensions
1720 @item
1721 PS/2 mouse and keyboard
1722 @item
1723 Non Volatile RAM M48T59
1724 @item
1725 PC-compatible serial ports
1726 @item
1727 2 PCI IDE interfaces with hard disk and CD-ROM support
1728 @item
1729 Floppy disk
1730 @end itemize
1732 @c man begin OPTIONS
1734 The following options are specific to the Sparc64 emulation:
1736 @table @option
1738 @item -prom-env @var{string}
1740 Set OpenBIOS variables in NVRAM, for example:
1742 @example
1743 qemu-system-sparc64 -prom-env 'auto-boot?=false'
1744 @end example
1746 @item -M [sun4u|sun4v|niagara]
1748 Set the emulated machine type. The default is sun4u.
1750 @end table
1752 @c man end
1754 @node MIPS System emulator
1755 @section MIPS System emulator
1756 @cindex system emulation (MIPS)
1758 Four executables cover simulation of 32 and 64-bit MIPS systems in
1759 both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
1760 @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
1761 Five different machine types are emulated:
1763 @itemize @minus
1764 @item
1765 A generic ISA PC-like machine "mips"
1766 @item
1767 The MIPS Malta prototype board "malta"
1768 @item
1769 An ACER Pica "pica61". This machine needs the 64-bit emulator.
1770 @item
1771 MIPS emulator pseudo board "mipssim"
1772 @item
1773 A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
1774 @end itemize
1776 The generic emulation is supported by Debian 'Etch' and is able to
1777 install Debian into a virtual disk image. The following devices are
1778 emulated:
1780 @itemize @minus
1781 @item
1782 A range of MIPS CPUs, default is the 24Kf
1783 @item
1784 PC style serial port
1785 @item
1786 PC style IDE disk
1787 @item
1788 NE2000 network card
1789 @end itemize
1791 The Malta emulation supports the following devices:
1793 @itemize @minus
1794 @item
1795 Core board with MIPS 24Kf CPU and Galileo system controller
1796 @item
1797 PIIX4 PCI/USB/SMbus controller
1798 @item
1799 The Multi-I/O chip's serial device
1800 @item
1801 PCI network cards (PCnet32 and others)
1802 @item
1803 Malta FPGA serial device
1804 @item
1805 Cirrus (default) or any other PCI VGA graphics card
1806 @end itemize
1808 The ACER Pica emulation supports:
1810 @itemize @minus
1811 @item
1812 MIPS R4000 CPU
1813 @item
1814 PC-style IRQ and DMA controllers
1815 @item
1816 PC Keyboard
1817 @item
1818 IDE controller
1819 @end itemize
1821 The mipssim pseudo board emulation provides an environment similar
1822 to what the proprietary MIPS emulator uses for running Linux.
1823 It supports:
1825 @itemize @minus
1826 @item
1827 A range of MIPS CPUs, default is the 24Kf
1828 @item
1829 PC style serial port
1830 @item
1831 MIPSnet network emulation
1832 @end itemize
1834 The MIPS Magnum R4000 emulation supports:
1836 @itemize @minus
1837 @item
1838 MIPS R4000 CPU
1839 @item
1840 PC-style IRQ controller
1841 @item
1842 PC Keyboard
1843 @item
1844 SCSI controller
1845 @item
1846 G364 framebuffer
1847 @end itemize
1850 @node ARM System emulator
1851 @section ARM System emulator
1852 @cindex system emulation (ARM)
1854 Use the executable @file{qemu-system-arm} to simulate a ARM
1855 machine. The ARM Integrator/CP board is emulated with the following
1856 devices:
1858 @itemize @minus
1859 @item
1860 ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
1861 @item
1862 Two PL011 UARTs
1863 @item
1864 SMC 91c111 Ethernet adapter
1865 @item
1866 PL110 LCD controller
1867 @item
1868 PL050 KMI with PS/2 keyboard and mouse.
1869 @item
1870 PL181 MultiMedia Card Interface with SD card.
1871 @end itemize
1873 The ARM Versatile baseboard is emulated with the following devices:
1875 @itemize @minus
1876 @item
1877 ARM926E, ARM1136 or Cortex-A8 CPU
1878 @item
1879 PL190 Vectored Interrupt Controller
1880 @item
1881 Four PL011 UARTs
1882 @item
1883 SMC 91c111 Ethernet adapter
1884 @item
1885 PL110 LCD controller
1886 @item
1887 PL050 KMI with PS/2 keyboard and mouse.
1888 @item
1889 PCI host bridge.  Note the emulated PCI bridge only provides access to
1890 PCI memory space.  It does not provide access to PCI IO space.
1891 This means some devices (eg. ne2k_pci NIC) are not usable, and others
1892 (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
1893 mapped control registers.
1894 @item
1895 PCI OHCI USB controller.
1896 @item
1897 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
1898 @item
1899 PL181 MultiMedia Card Interface with SD card.
1900 @end itemize
1902 Several variants of the ARM RealView baseboard are emulated,
1903 including the EB, PB-A8 and PBX-A9.  Due to interactions with the
1904 bootloader, only certain Linux kernel configurations work out
1905 of the box on these boards.
1907 Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1908 enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board
1909 should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1910 disabled and expect 1024M RAM.
1912 The following devices are emulated:
1914 @itemize @minus
1915 @item
1916 ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
1917 @item
1918 ARM AMBA Generic/Distributed Interrupt Controller
1919 @item
1920 Four PL011 UARTs
1921 @item
1922 SMC 91c111 or SMSC LAN9118 Ethernet adapter
1923 @item
1924 PL110 LCD controller
1925 @item
1926 PL050 KMI with PS/2 keyboard and mouse
1927 @item
1928 PCI host bridge
1929 @item
1930 PCI OHCI USB controller
1931 @item
1932 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
1933 @item
1934 PL181 MultiMedia Card Interface with SD card.
1935 @end itemize
1937 The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
1938 and "Terrier") emulation includes the following peripherals:
1940 @itemize @minus
1941 @item
1942 Intel PXA270 System-on-chip (ARM V5TE core)
1943 @item
1944 NAND Flash memory
1945 @item
1946 IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
1947 @item
1948 On-chip OHCI USB controller
1949 @item
1950 On-chip LCD controller
1951 @item
1952 On-chip Real Time Clock
1953 @item
1954 TI ADS7846 touchscreen controller on SSP bus
1955 @item
1956 Maxim MAX1111 analog-digital converter on I@math{^2}C bus
1957 @item
1958 GPIO-connected keyboard controller and LEDs
1959 @item
1960 Secure Digital card connected to PXA MMC/SD host
1961 @item
1962 Three on-chip UARTs
1963 @item
1964 WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
1965 @end itemize
1967 The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
1968 following elements:
1970 @itemize @minus
1971 @item
1972 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1973 @item
1974 ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
1975 @item
1976 On-chip LCD controller
1977 @item
1978 On-chip Real Time Clock
1979 @item
1980 TI TSC2102i touchscreen controller / analog-digital converter / Audio
1981 CODEC, connected through MicroWire and I@math{^2}S busses
1982 @item
1983 GPIO-connected matrix keypad
1984 @item
1985 Secure Digital card connected to OMAP MMC/SD host
1986 @item
1987 Three on-chip UARTs
1988 @end itemize
1990 Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
1991 emulation supports the following elements:
1993 @itemize @minus
1994 @item
1995 Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
1996 @item
1997 RAM and non-volatile OneNAND Flash memories
1998 @item
1999 Display connected to EPSON remote framebuffer chip and OMAP on-chip
2000 display controller and a LS041y3 MIPI DBI-C controller
2001 @item
2002 TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2003 driven through SPI bus
2004 @item
2005 National Semiconductor LM8323-controlled qwerty keyboard driven
2006 through I@math{^2}C bus
2007 @item
2008 Secure Digital card connected to OMAP MMC/SD host
2009 @item
2010 Three OMAP on-chip UARTs and on-chip STI debugging console
2011 @item
2012 A Bluetooth(R) transceiver and HCI connected to an UART
2013 @item
2014 Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2015 TUSB6010 chip - only USB host mode is supported
2016 @item
2017 TI TMP105 temperature sensor driven through I@math{^2}C bus
2018 @item
2019 TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2020 @item
2021 Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2022 through CBUS
2023 @end itemize
2025 The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2026 devices:
2028 @itemize @minus
2029 @item
2030 Cortex-M3 CPU core.
2031 @item
2032 64k Flash and 8k SRAM.
2033 @item
2034 Timers, UARTs, ADC and I@math{^2}C interface.
2035 @item
2036 OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2037 @end itemize
2039 The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2040 devices:
2042 @itemize @minus
2043 @item
2044 Cortex-M3 CPU core.
2045 @item
2046 256k Flash and 64k SRAM.
2047 @item
2048 Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2049 @item
2050 OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2051 @end itemize
2053 The Freecom MusicPal internet radio emulation includes the following
2054 elements:
2056 @itemize @minus
2057 @item
2058 Marvell MV88W8618 ARM core.
2059 @item
2060 32 MB RAM, 256 KB SRAM, 8 MB flash.
2061 @item
2062 Up to 2 16550 UARTs
2063 @item
2064 MV88W8xx8 Ethernet controller
2065 @item
2066 MV88W8618 audio controller, WM8750 CODEC and mixer
2067 @item
2068 128×64 display with brightness control
2069 @item
2070 2 buttons, 2 navigation wheels with button function
2071 @end itemize
2073 The Siemens SX1 models v1 and v2 (default) basic emulation.
2074 The emulation includes the following elements:
2076 @itemize @minus
2077 @item
2078 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2079 @item
2080 ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2082 1 Flash of 16MB and 1 Flash of 8MB
2084 1 Flash of 32MB
2085 @item
2086 On-chip LCD controller
2087 @item
2088 On-chip Real Time Clock
2089 @item
2090 Secure Digital card connected to OMAP MMC/SD host
2091 @item
2092 Three on-chip UARTs
2093 @end itemize
2095 A Linux 2.6 test image is available on the QEMU web site. More
2096 information is available in the QEMU mailing-list archive.
2098 @c man begin OPTIONS
2100 The following options are specific to the ARM emulation:
2102 @table @option
2104 @item -semihosting
2105 Enable semihosting syscall emulation.
2107 On ARM this implements the "Angel" interface.
2109 Note that this allows guest direct access to the host filesystem,
2110 so should only be used with trusted guest OS.
2112 @end table
2114 @c man end
2116 @node ColdFire System emulator
2117 @section ColdFire System emulator
2118 @cindex system emulation (ColdFire)
2119 @cindex system emulation (M68K)
2121 Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2122 The emulator is able to boot a uClinux kernel.
2124 The M5208EVB emulation includes the following devices:
2126 @itemize @minus
2127 @item
2128 MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2129 @item
2130 Three Two on-chip UARTs.
2131 @item
2132 Fast Ethernet Controller (FEC)
2133 @end itemize
2135 The AN5206 emulation includes the following devices:
2137 @itemize @minus
2138 @item
2139 MCF5206 ColdFire V2 Microprocessor.
2140 @item
2141 Two on-chip UARTs.
2142 @end itemize
2144 @c man begin OPTIONS
2146 The following options are specific to the ColdFire emulation:
2148 @table @option
2150 @item -semihosting
2151 Enable semihosting syscall emulation.
2153 On M68K this implements the "ColdFire GDB" interface used by libgloss.
2155 Note that this allows guest direct access to the host filesystem,
2156 so should only be used with trusted guest OS.
2158 @end table
2160 @c man end
2162 @node Cris System emulator
2163 @section Cris System emulator
2164 @cindex system emulation (Cris)
2166 TODO
2168 @node Microblaze System emulator
2169 @section Microblaze System emulator
2170 @cindex system emulation (Microblaze)
2172 TODO
2174 @node SH4 System emulator
2175 @section SH4 System emulator
2176 @cindex system emulation (SH4)
2178 TODO
2180 @node Xtensa System emulator
2181 @section Xtensa System emulator
2182 @cindex system emulation (Xtensa)
2184 Two executables cover simulation of both Xtensa endian options,
2185 @file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
2186 Two different machine types are emulated:
2188 @itemize @minus
2189 @item
2190 Xtensa emulator pseudo board "sim"
2191 @item
2192 Avnet LX60/LX110/LX200 board
2193 @end itemize
2195 The sim pseudo board emulation provides an environment similar
2196 to one provided by the proprietary Tensilica ISS.
2197 It supports:
2199 @itemize @minus
2200 @item
2201 A range of Xtensa CPUs, default is the DC232B
2202 @item
2203 Console and filesystem access via semihosting calls
2204 @end itemize
2206 The Avnet LX60/LX110/LX200 emulation supports:
2208 @itemize @minus
2209 @item
2210 A range of Xtensa CPUs, default is the DC232B
2211 @item
2212 16550 UART
2213 @item
2214 OpenCores 10/100 Mbps Ethernet MAC
2215 @end itemize
2217 @c man begin OPTIONS
2219 The following options are specific to the Xtensa emulation:
2221 @table @option
2223 @item -semihosting
2224 Enable semihosting syscall emulation.
2226 Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2227 Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2229 Note that this allows guest direct access to the host filesystem,
2230 so should only be used with trusted guest OS.
2232 @end table
2234 @c man end
2236 @node QEMU Guest Agent
2237 @chapter QEMU Guest Agent invocation
2239 @include qemu-ga.texi
2241 @node QEMU User space emulator
2242 @chapter QEMU User space emulator
2244 @menu
2245 * Supported Operating Systems ::
2246 * Features::
2247 * Linux User space emulator::
2248 * BSD User space emulator ::
2249 @end menu
2251 @node Supported Operating Systems
2252 @section Supported Operating Systems
2254 The following OS are supported in user space emulation:
2256 @itemize @minus
2257 @item
2258 Linux (referred as qemu-linux-user)
2259 @item
2260 BSD (referred as qemu-bsd-user)
2261 @end itemize
2263 @node Features
2264 @section Features
2266 QEMU user space emulation has the following notable features:
2268 @table @strong
2269 @item System call translation:
2270 QEMU includes a generic system call translator.  This means that
2271 the parameters of the system calls can be converted to fix
2272 endianness and 32/64-bit mismatches between hosts and targets.
2273 IOCTLs can be converted too.
2275 @item POSIX signal handling:
2276 QEMU can redirect to the running program all signals coming from
2277 the host (such as @code{SIGALRM}), as well as synthesize signals from
2278 virtual CPU exceptions (for example @code{SIGFPE} when the program
2279 executes a division by zero).
2281 QEMU relies on the host kernel to emulate most signal system
2282 calls, for example to emulate the signal mask.  On Linux, QEMU
2283 supports both normal and real-time signals.
2285 @item Threading:
2286 On Linux, QEMU can emulate the @code{clone} syscall and create a real
2287 host thread (with a separate virtual CPU) for each emulated thread.
2288 Note that not all targets currently emulate atomic operations correctly.
2289 x86 and ARM use a global lock in order to preserve their semantics.
2290 @end table
2292 QEMU was conceived so that ultimately it can emulate itself. Although
2293 it is not very useful, it is an important test to show the power of the
2294 emulator.
2296 @node Linux User space emulator
2297 @section Linux User space emulator
2299 @menu
2300 * Quick Start::
2301 * Wine launch::
2302 * Command line options::
2303 * Other binaries::
2304 @end menu
2306 @node Quick Start
2307 @subsection Quick Start
2309 In order to launch a Linux process, QEMU needs the process executable
2310 itself and all the target (x86) dynamic libraries used by it.
2312 @itemize
2314 @item On x86, you can just try to launch any process by using the native
2315 libraries:
2317 @example
2318 qemu-i386 -L / /bin/ls
2319 @end example
2321 @code{-L /} tells that the x86 dynamic linker must be searched with a
2322 @file{/} prefix.
2324 @item Since QEMU is also a linux process, you can launch QEMU with
2325 QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
2327 @example
2328 qemu-i386 -L / qemu-i386 -L / /bin/ls
2329 @end example
2331 @item On non x86 CPUs, you need first to download at least an x86 glibc
2332 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2333 @code{LD_LIBRARY_PATH} is not set:
2335 @example
2336 unset LD_LIBRARY_PATH
2337 @end example
2339 Then you can launch the precompiled @file{ls} x86 executable:
2341 @example
2342 qemu-i386 tests/i386/ls
2343 @end example
2344 You can look at @file{scripts/qemu-binfmt-conf.sh} so that
2345 QEMU is automatically launched by the Linux kernel when you try to
2346 launch x86 executables. It requires the @code{binfmt_misc} module in the
2347 Linux kernel.
2349 @item The x86 version of QEMU is also included. You can try weird things such as:
2350 @example
2351 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2352           /usr/local/qemu-i386/bin/ls-i386
2353 @end example
2355 @end itemize
2357 @node Wine launch
2358 @subsection Wine launch
2360 @itemize
2362 @item Ensure that you have a working QEMU with the x86 glibc
2363 distribution (see previous section). In order to verify it, you must be
2364 able to do:
2366 @example
2367 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2368 @end example
2370 @item Download the binary x86 Wine install
2371 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2373 @item Configure Wine on your account. Look at the provided script
2374 @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2375 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2377 @item Then you can try the example @file{putty.exe}:
2379 @example
2380 qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2381           /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2382 @end example
2384 @end itemize
2386 @node Command line options
2387 @subsection Command line options
2389 @example
2390 @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}...]
2391 @end example
2393 @table @option
2394 @item -h
2395 Print the help
2396 @item -L path
2397 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2398 @item -s size
2399 Set the x86 stack size in bytes (default=524288)
2400 @item -cpu model
2401 Select CPU model (-cpu help for list and additional feature selection)
2402 @item -E @var{var}=@var{value}
2403 Set environment @var{var} to @var{value}.
2404 @item -U @var{var}
2405 Remove @var{var} from the environment.
2406 @item -B offset
2407 Offset guest address by the specified number of bytes.  This is useful when
2408 the address region required by guest applications is reserved on the host.
2409 This option is currently only supported on some hosts.
2410 @item -R size
2411 Pre-allocate a guest virtual address space of the given size (in bytes).
2412 "G", "M", and "k" suffixes may be used when specifying the size.
2413 @end table
2415 Debug options:
2417 @table @option
2418 @item -d item1,...
2419 Activate logging of the specified items (use '-d help' for a list of log items)
2420 @item -p pagesize
2421 Act as if the host page size was 'pagesize' bytes
2422 @item -g port
2423 Wait gdb connection to port
2424 @item -singlestep
2425 Run the emulation in single step mode.
2426 @end table
2428 Environment variables:
2430 @table @env
2431 @item QEMU_STRACE
2432 Print system calls and arguments similar to the 'strace' program
2433 (NOTE: the actual 'strace' program will not work because the user
2434 space emulator hasn't implemented ptrace).  At the moment this is
2435 incomplete.  All system calls that don't have a specific argument
2436 format are printed with information for six arguments.  Many
2437 flag-style arguments don't have decoders and will show up as numbers.
2438 @end table
2440 @node Other binaries
2441 @subsection Other binaries
2443 @cindex user mode (Alpha)
2444 @command{qemu-alpha} TODO.
2446 @cindex user mode (ARM)
2447 @command{qemu-armeb} TODO.
2449 @cindex user mode (ARM)
2450 @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2451 binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2452 configurations), and arm-uclinux bFLT format binaries.
2454 @cindex user mode (ColdFire)
2455 @cindex user mode (M68K)
2456 @command{qemu-m68k} is capable of running semihosted binaries using the BDM
2457 (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2458 coldfire uClinux bFLT format binaries.
2460 The binary format is detected automatically.
2462 @cindex user mode (Cris)
2463 @command{qemu-cris} TODO.
2465 @cindex user mode (i386)
2466 @command{qemu-i386} TODO.
2467 @command{qemu-x86_64} TODO.
2469 @cindex user mode (Microblaze)
2470 @command{qemu-microblaze} TODO.
2472 @cindex user mode (MIPS)
2473 @command{qemu-mips} TODO.
2474 @command{qemu-mipsel} TODO.
2476 @cindex user mode (NiosII)
2477 @command{qemu-nios2} TODO.
2479 @cindex user mode (PowerPC)
2480 @command{qemu-ppc64abi32} TODO.
2481 @command{qemu-ppc64} TODO.
2482 @command{qemu-ppc} TODO.
2484 @cindex user mode (SH4)
2485 @command{qemu-sh4eb} TODO.
2486 @command{qemu-sh4} TODO.
2488 @cindex user mode (SPARC)
2489 @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2491 @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2492 (Sparc64 CPU, 32 bit ABI).
2494 @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2495 SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2497 @node BSD User space emulator
2498 @section BSD User space emulator
2500 @menu
2501 * BSD Status::
2502 * BSD Quick Start::
2503 * BSD Command line options::
2504 @end menu
2506 @node BSD Status
2507 @subsection BSD Status
2509 @itemize @minus
2510 @item
2511 target Sparc64 on Sparc64: Some trivial programs work.
2512 @end itemize
2514 @node BSD Quick Start
2515 @subsection Quick Start
2517 In order to launch a BSD process, QEMU needs the process executable
2518 itself and all the target dynamic libraries used by it.
2520 @itemize
2522 @item On Sparc64, you can just try to launch any process by using the native
2523 libraries:
2525 @example
2526 qemu-sparc64 /bin/ls
2527 @end example
2529 @end itemize
2531 @node BSD Command line options
2532 @subsection Command line options
2534 @example
2535 @command{qemu-sparc64} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-bsd} @var{type}] @var{program} [@var{arguments}...]
2536 @end example
2538 @table @option
2539 @item -h
2540 Print the help
2541 @item -L path
2542 Set the library root path (default=/)
2543 @item -s size
2544 Set the stack size in bytes (default=524288)
2545 @item -ignore-environment
2546 Start with an empty environment. Without this option,
2547 the initial environment is a copy of the caller's environment.
2548 @item -E @var{var}=@var{value}
2549 Set environment @var{var} to @var{value}.
2550 @item -U @var{var}
2551 Remove @var{var} from the environment.
2552 @item -bsd type
2553 Set the type of the emulated BSD Operating system. Valid values are
2554 FreeBSD, NetBSD and OpenBSD (default).
2555 @end table
2557 Debug options:
2559 @table @option
2560 @item -d item1,...
2561 Activate logging of the specified items (use '-d help' for a list of log items)
2562 @item -p pagesize
2563 Act as if the host page size was 'pagesize' bytes
2564 @item -singlestep
2565 Run the emulation in single step mode.
2566 @end table
2569 @include qemu-tech.texi
2571 @node Deprecated features
2572 @appendix Deprecated features
2574 In general features are intended to be supported indefinitely once
2575 introduced into QEMU. In the event that a feature needs to be removed,
2576 it will be listed in this appendix. The feature will remain functional
2577 for 2 releases prior to actual removal. Deprecated features may also
2578 generate warnings on the console when QEMU starts up, or if activated
2579 via a monitor command, however, this is not a mandatory requirement.
2581 Prior to the 2.10.0 release there was no official policy on how
2582 long features would be deprecated prior to their removal, nor
2583 any documented list of which features were deprecated. Thus
2584 any features deprecated prior to 2.10.0 will be treated as if
2585 they were first deprecated in the 2.10.0 release.
2587 What follows is a list of all features currently marked as
2588 deprecated.
2590 @section Build options
2592 @subsection GTK 2.x
2594 Previously QEMU has supported building against both GTK 2.x
2595 and 3.x series APIs. Support for the GTK 2.x builds will be
2596 discontinued, so maintainers should switch to using GTK 3.x,
2597 which is the default.
2599 @section System emulator command line arguments
2601 @subsection -tdf (since 1.3.0)
2603 The ``-tdf'' argument is ignored. The behaviour implemented
2604 by this argument is now the default when using the KVM PIT,
2605 but can be requested explicitly using
2606 ``-global kvm-pit.lost_tick_policy=slew''.
2608 @subsection -no-kvm-pit-reinjection (since 1.3.0)
2610 The ``-no-kvm-pit-reinjection'' argument is now a
2611 synonym for setting ``-global kvm-pit.lost_tick_policy=discard''.
2613 @subsection -no-kvm-irqchip (since 1.3.0)
2615 The ``-no-kvm-irqchip'' argument is now a synonym for
2616 setting ``-machine kernel_irqchip=off''.
2618 @subsection -no-kvm (since 1.3.0)
2620 The ``-no-kvm'' argument is now a synonym for setting
2621 ``-machine accel=tcg''.
2623 @subsection -mon default=on (since 2.4.0)
2625 The ``default'' option to the ``-mon'' argument is
2626 now ignored. When multiple monitors were enabled, it
2627 indicated which monitor would receive log messages
2628 from the various subsystems. This feature is no longer
2629 required as messages are now only sent to the monitor
2630 in response to explicitly monitor commands.
2632 @subsection -vnc tls (since 2.5.0)
2634 The ``-vnc tls'' argument is now a synonym for setting
2635 ``-object tls-creds-anon,id=tls0'' combined with
2636 ``-vnc tls-creds=tls0'
2638 @subsection -vnc x509 (since 2.5.0)
2640 The ``-vnc x509=/path/to/certs'' argument is now a
2641 synonym for setting
2642 ``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=no''
2643 combined with ``-vnc tls-creds=tls0'
2645 @subsection -vnc x509verify (since 2.5.0)
2647 The ``-vnc x509verify=/path/to/certs'' argument is now a
2648 synonym for setting
2649 ``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=yes''
2650 combined with ``-vnc tls-creds=tls0'
2652 @subsection -tftp (since 2.6.0)
2654 The ``-tftp /some/dir'' argument is replaced by
2655 ``-netdev user,id=x,tftp=/some/dir'', either accompanied with
2656 ``-device ...,netdev=x'' (for pluggable NICs) or ``-net nic,netdev=x''
2657 (for embedded NICs). The new syntax allows different settings to be
2658 provided per NIC.
2660 @subsection -bootp (since 2.6.0)
2662 The ``-bootp /some/file'' argument is replaced by
2663 ``-netdev user,id=x,bootp=/some/file'', either accompanied with
2664 ``-device ...,netdev=x'' (for pluggable NICs) or ``-net nic,netdev=x''
2665 (for embedded NICs). The new syntax allows different settings to be
2666 provided per NIC.
2668 @subsection -redir (since 2.6.0)
2670 The ``-redir [tcp|udp]:hostport:[guestaddr]:guestport'' argument is
2671 replaced by ``-netdev
2672 user,id=x,hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport'',
2673 either accompanied with ``-device ...,netdev=x'' (for pluggable NICs) or
2674 ``-net nic,netdev=x'' (for embedded NICs). The new syntax allows different
2675 settings to be provided per NIC.
2677 @subsection -smb (since 2.6.0)
2679 The ``-smb /some/dir'' argument is replaced by
2680 ``-netdev user,id=x,smb=/some/dir'', either accompanied with
2681 ``-device ...,netdev=x'' (for pluggable NICs) or ``-net nic,netdev=x''
2682 (for embedded NICs). The new syntax allows different settings to be
2683 provided per NIC.
2685 @subsection -net vlan (since 2.9.0)
2687 The ``-net vlan=NN'' argument is partially replaced with the
2688 new ``-netdev'' argument. The remaining use cases will no
2689 longer be directly supported in QEMU.
2691 @subsection -drive if=scsi (since 2.9.0)
2693 The ``-drive if=scsi'' argument is replaced by the the
2694 ``-device BUS-TYPE'' argument combined with ``-drive if=none''.
2696 @subsection -drive cyls=...,heads=...,secs=...,trans=... (since 2.10.0)
2698 The drive geometry arguments are replaced by the the geometry arguments
2699 that can be specified with the ``-device'' parameter.
2701 @subsection -drive serial=... (since 2.10.0)
2703 The drive serial argument is replaced by the the serial argument
2704 that can be specified with the ``-device'' parameter.
2706 @subsection -drive addr=... (since 2.10.0)
2708 The drive addr argument is replaced by the the addr argument
2709 that can be specified with the ``-device'' parameter.
2711 @subsection -net dump (since 2.10.0)
2713 The ``--net dump'' argument is now replaced with the
2714 ``-object filter-dump'' argument which works in combination
2715 with the modern ``-netdev`` backends instead.
2717 @subsection -usbdevice (since 2.10.0)
2719 The ``-usbdevice DEV'' argument is now a synonym for setting
2720 the ``-device usb-DEV'' argument instead. The deprecated syntax
2721 would automatically enable USB support on the machine type.
2722 If using the new syntax, USB support must be explicitly
2723 enabled via the ``-machine usb=on'' argument.
2725 @subsection -nodefconfig (since 2.11.0)
2727 The ``-nodefconfig`` argument is a synonym for ``-no-user-config``.
2729 @subsection -machine s390-squash-mcss=on|off (since 2.12.0)
2731 The ``s390-squash-mcss=on`` property has been obsoleted by allowing the
2732 cssid to be chosen freely. Instead of squashing subchannels into the
2733 default channel subsystem image for guests that do not support multiple
2734 channel subsystems, all devices can be put into the default channel
2735 subsystem image.
2737 @subsection -fsdev handle (since 2.12.0)
2739 The ``handle'' fsdev backend does not support symlinks and causes the 9p
2740 filesystem in the guest to fail a fair amount of tests from the PJD POSIX
2741 filesystem test suite. Also it requires the CAP_DAC_READ_SEARCH capability,
2742 which is not the recommended way to run QEMU. This backend should not be
2743 used and it will be removed with no replacement.
2745 @section qemu-img command line arguments
2747 @subsection convert -s (since 2.0.0)
2749 The ``convert -s snapshot_id_or_name'' argument is obsoleted
2750 by the ``convert -l snapshot_param'' argument instead.
2752 @section System emulator human monitor commands
2754 @subsection host_net_add (since 2.10.0)
2756 The ``host_net_add'' command is replaced by the ``netdev_add'' command.
2758 @subsection host_net_remove (since 2.10.0)
2760 The ``host_net_remove'' command is replaced by the ``netdev_del'' command.
2762 @section System emulator devices
2764 @subsection ivshmem (since 2.6.0)
2766 The ``ivshmem'' device type is replaced by either the ``ivshmem-plain''
2767 or ``ivshmem-doorbell`` device types.
2769 @section System emulator machines
2771 @subsection Xilinx EP108 (since 2.11.0)
2773 The ``xlnx-ep108'' machine has been replaced by the ``xlnx-zcu102'' machine.
2774 The ``xlnx-zcu102'' machine has the same features and capabilites in QEMU.
2776 @node License
2777 @appendix License
2779 QEMU is a trademark of Fabrice Bellard.
2781 QEMU is released under the
2782 @url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
2783 version 2. Parts of QEMU have specific licenses, see file
2784 @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
2786 @node Index
2787 @appendix Index
2788 @menu
2789 * Concept Index::
2790 * Function Index::
2791 * Keystroke Index::
2792 * Program Index::
2793 * Data Type Index::
2794 * Variable Index::
2795 @end menu
2797 @node Concept Index
2798 @section Concept Index
2799 This is the main index. Should we combine all keywords in one index? TODO
2800 @printindex cp
2802 @node Function Index
2803 @section Function Index
2804 This index could be used for command line options and monitor functions.
2805 @printindex fn
2807 @node Keystroke Index
2808 @section Keystroke Index
2810 This is a list of all keystrokes which have a special function
2811 in system emulation.
2813 @printindex ky
2815 @node Program Index
2816 @section Program Index
2817 @printindex pg
2819 @node Data Type Index
2820 @section Data Type Index
2822 This index could be used for qdev device names and options.
2824 @printindex tp
2826 @node Variable Index
2827 @section Variable Index
2828 @printindex vr
2830 @bye