1 \input texinfo @c -*- texinfo -*-
3 @setfilename qemu-doc.info
7 @documentencoding UTF-8
9 @settitle QEMU version @value{VERSION} User Documentation
16 * QEMU: (qemu-doc). The QEMU Emulator User Documentation.
23 @center @titlefont{QEMU version @value{VERSION}}
25 @center @titlefont{User Documentation}
36 * QEMU PC System emulator::
37 * QEMU System emulator for non PC targets::
39 * QEMU User space emulator::
40 * Implementation notes::
41 * Deprecated features::
53 * intro_features:: 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:
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.
80 QEMU has the following features:
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.
93 QEMU user mode emulation has the following features:
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.
102 QEMU full system emulation has the following features:
105 QEMU uses a full software MMU for maximum portability.
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.
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).
120 Symmetric multiprocessing (SMP) support. Currently, an in-kernel
121 accelerator is required to use more than one host CPU for emulation.
126 @node QEMU PC System emulator
127 @chapter QEMU PC System emulator
128 @cindex system emulation (PC)
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
147 @node pcsys_introduction
148 @section Introduction
150 @c man begin DESCRIPTION
152 The QEMU PC System emulator simulates the
153 following peripherals:
157 i440FX host PCI bridge and PIIX3 PCI to ISA bridge
159 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
160 extensions (hardware level, including all non standard modes).
162 PS/2 mouse and keyboard
164 2 PCI IDE interfaces with hard disk and CD-ROM support
168 PCI and ISA network adapters
172 IPMI BMC, either and internal or external one
174 Creative SoundBlaster 16 sound card
176 ENSONIQ AudioPCI ES1370 sound card
178 Intel 82801AA AC97 Audio compatible sound card
180 Intel HD Audio Controller and HDA codec
182 Adlib (OPL2) - Yamaha YM3812 compatible chip
184 Gravis Ultrasound GF1 sound card
186 CS4231A compatible sound card
188 PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.
191 SMP is supported with up to 255 CPUs.
193 QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
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.
205 qemu-system-i386 dos.img -soundhw gus -parallel none
210 qemu-system-i386 dos.img -device gus,irq=5
213 Or some other unclaimed IRQ.
215 CS4231A is the chip used in Windows Sound System and GUSMAX products
219 @node pcsys_quickstart
223 Download and uncompress the linux image (@file{linux.img}) and type:
226 qemu-system-i386 linux.img
229 Linux should boot and give you a prompt.
235 @c man begin SYNOPSIS
236 @command{qemu-system-i386} [@var{options}] [@var{disk_image}]
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
248 @subsection Device URL Syntax
249 @c TODO merge this with section Disk Images
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.
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):
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
281 Example (CHAP username/password via URL):
283 qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
286 Example (CHAP username/password via environment variables):
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
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>]''
305 qemu-system-i386 --drive file=nbd:192.0.2.1:30000
308 Example for Unix Domain Sockets
310 qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
314 QEMU supports SSH (Secure Shell) access to remote disks.
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
322 Currently authentication must be done using ssh-agent. Other
323 authentication methods may be supported in future.
326 Sheepdog is a distributed storage system for QEMU.
327 QEMU supports using either local sheepdog devices or remote networked
330 Syntax for specifying a sheepdog device
332 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
337 qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
340 See also @url{https://sheepdog.github.io/sheepdog/}.
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
351 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
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":"..."@}]@}@}'
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
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
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:
386 <protocol>://[<username>[:<password>]@@]<host>/<path>
392 'http', 'https', 'ftp', or 'ftps'.
395 Optional username for authentication to the remote server.
398 Optional password for authentication to the remote server.
401 Address of the remote server.
404 Path on the remote server, including any query string.
407 The following options are also supported:
410 The full URL when passing options to the driver explicitly.
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.
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'.
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.
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.
433 Note that when passing options to qemu explicitly, @option{driver} is the value
436 Example: boot from a remote Fedora 20 live ISO image
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
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
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
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
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
465 @section Keys in the graphical frontends
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):
489 Restore the screen's un-scaled dimensions
493 Switch to virtual console 'n'. Standard console mappings are:
496 Target system display
505 Toggle mouse and keyboard grab.
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.
518 @section Keys in the character backend multiplexer
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.
538 Save disk data back to file (if -snapshot)
541 Toggle console timestamps
544 Send break (magic sysrq in Linux)
547 Rotate between the frontends connected to the multiplexer (usually
548 this switches between the monitor and the console)
550 @kindex Ctrl-a Ctrl-a
551 Send the escape character to the frontend
558 The HTML documentation of QEMU for more precise information and Linux
559 user mode emulator invocation.
569 @section QEMU Monitor
572 The QEMU monitor is used to give complex commands to the QEMU
573 emulator. You can use it to:
578 Remove or insert removable media images
579 (such as CD-ROM or floppies).
582 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
585 @item Inspect the VM state without an external debugger.
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{$}.
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.
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
627 @node disk_images_quickstart
628 @subsection Quick start for disk image creation
630 You can create a disk image with the command:
632 qemu-img create myimage.img mysize
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).
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:
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
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
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:
693 They cannot cope with removable devices if they are removed or
694 inserted after a snapshot is done.
696 A few device drivers still have incomplete snapshot support so their
697 state is not saved or restored properly (in particular USB).
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
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
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
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:
764 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
767 ----> DNS server (10.0.2.3)
769 ----> SMB server (10.0.2.4)
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):
789 echo 100 100 > /proc/sys/net/ipv4/ping_group_range
792 When using the built-in TFTP server, the router is also the TFTP
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
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
814 qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem}
817 where @var{hostmem} names a host memory backend. For a POSIX shared
818 memory backend, use something like
821 -object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
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
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}
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:
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
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
876 qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
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
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:
891 qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
892 -append "root=/dev/hda console=ttyS0" -nographic
895 Use @key{Ctrl-a c} to switch between the serial console and the
896 monitor (@pxref{pcsys_keys}).
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.
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:
918 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
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})
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}
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.
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
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
957 qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
960 Smartcard reader device
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
976 @command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3
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.
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:
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:
1001 chown -R myuid /proc/bus/usb
1004 @item Launch QEMU and do in the monitor:
1007 Device 1.2, speed 480 Mb/s
1008 Class 00: USB device 1234:5678, USB DISK
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:
1015 device_add usb-host,vendorid=0x1234,productid=0x5678
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.
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).
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.
1037 * vnc_sec_password::
1038 * vnc_sec_certificate::
1039 * vnc_sec_certificate_verify::
1040 * vnc_sec_certificate_pw::
1042 * vnc_sec_certificate_sasl::
1043 * vnc_generate_cert::
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
1054 qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
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
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.
1077 qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
1078 (qemu) change vnc password
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.
1094 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
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.
1112 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
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.
1123 qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1124 (qemu) change vnc password
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:
1146 qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
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:
1160 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
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}.
1177 * vnc_generate_server::
1178 * vnc_generate_client::
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.
1189 # certtool --generate-privkey > ca-key.pem
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.
1198 # cat > ca.info <<EOF
1199 cn = Name of your organization
1203 # certtool --generate-self-signed \
1204 --load-privkey ca-key.pem
1205 --template ca.info \
1206 --outfile ca-cert.pem
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:
1223 # cat > server.info <<EOF
1224 organization = Name of your organization
1225 cn = server.foo.example.com
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
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:
1253 # cat > client.info <<EOF
1257 organization = Name of your organization
1258 cn = client.foo.example.com
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
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
1298 When not using TLS the recommended configuration is
1302 keytab: /etc/qemu/krb5.tab
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
1316 mech_list: scram-sha-1
1317 sasldb_path: /etc/qemu/passwd.db
1320 The saslpasswd2 program can be used to populate the passwd.db file with
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.
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
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
1342 Then launch gdb on the 'vmlinux' executable:
1347 In gdb, connect to QEMU:
1349 (gdb) target remote localhost:1234
1352 Then you can use gdb normally. For example, type 'c' to launch the kernel:
1357 Here are some useful tips in order to use gdb on system code:
1361 Use @code{info reg} to display all the CPU registers.
1363 Use @code{x/10i $eip} to display the code at the PC position.
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.
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:
1373 @item maintenance packet qqemu.sstepbits
1375 This will display the MASK bits used to control the single stepping IE:
1377 (gdb) maintenance packet qqemu.sstepbits
1378 sending: "qqemu.sstepbits"
1379 received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1381 @item maintenance packet qqemu.sstep
1383 This will display the current value of the mask used when single stepping IE:
1385 (gdb) maintenance packet qqemu.sstep
1386 sending: "qqemu.sstep"
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:
1393 (gdb) maintenance packet Qqemu.sstep=0x5
1394 sending: "qemu.sstep=0x5"
1399 @node pcsys_os_specific
1400 @section Target OS specific information
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.
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
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
1475 A problem is preventing Windows from accurately checking the
1476 license for this computer. Error code: 0x800703e6.
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.
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::
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:
1525 UniNorth or Grackle PCI Bridge
1527 PCI VGA compatible card with VESA Bochs Extensions
1529 2 PMAC IDE interfaces with hard disk and CD-ROM support
1535 VIA-CUDA with ADB keyboard and mouse.
1538 QEMU emulates the following PREP peripherals:
1544 PCI VGA compatible card with VESA Bochs Extensions
1546 2 IDE interfaces with hard disk and CD-ROM support
1550 NE2000 network adapters
1554 PREP Non Volatile RAM
1556 PC compatible keyboard and mouse.
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:
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:
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'
1587 These variables are not used by Open Hack'Ware.
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:
1617 SPARCstation Voyager
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:
1633 TCX or cgthree Frame buffer
1635 Lance (Am7990) Ethernet
1637 Non Volatile RAM M48T02/M48T08
1639 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1640 and power/reset logic
1642 ESP SCSI controller with hard disk and CD-ROM support
1644 Floppy drive (not on SS-600MP)
1646 CS4231 sound device (only on SS-5, not working yet)
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
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
1664 @c man begin OPTIONS
1666 The following options are specific to the Sparc32 emulation:
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:
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'
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.
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.
1707 qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
1709 -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
1713 QEMU emulates the following peripherals:
1717 UltraSparc IIi APB PCI Bridge
1719 PCI VGA compatible card with VESA Bochs Extensions
1721 PS/2 mouse and keyboard
1723 Non Volatile RAM M48T59
1725 PC-compatible serial ports
1727 2 PCI IDE interfaces with hard disk and CD-ROM support
1732 @c man begin OPTIONS
1734 The following options are specific to the Sparc64 emulation:
1738 @item -prom-env @var{string}
1740 Set OpenBIOS variables in NVRAM, for example:
1743 qemu-system-sparc64 -prom-env 'auto-boot?=false'
1746 @item -M [sun4u|sun4v|niagara]
1748 Set the emulated machine type. The default is sun4u.
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:
1765 A generic ISA PC-like machine "mips"
1767 The MIPS Malta prototype board "malta"
1769 An ACER Pica "pica61". This machine needs the 64-bit emulator.
1771 MIPS emulator pseudo board "mipssim"
1773 A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
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
1782 A range of MIPS CPUs, default is the 24Kf
1784 PC style serial port
1791 The Malta emulation supports the following devices:
1795 Core board with MIPS 24Kf CPU and Galileo system controller
1797 PIIX4 PCI/USB/SMbus controller
1799 The Multi-I/O chip's serial device
1801 PCI network cards (PCnet32 and others)
1803 Malta FPGA serial device
1805 Cirrus (default) or any other PCI VGA graphics card
1808 The ACER Pica emulation supports:
1814 PC-style IRQ and DMA controllers
1821 The mipssim pseudo board emulation provides an environment similar
1822 to what the proprietary MIPS emulator uses for running Linux.
1827 A range of MIPS CPUs, default is the 24Kf
1829 PC style serial port
1831 MIPSnet network emulation
1834 The MIPS Magnum R4000 emulation supports:
1840 PC-style IRQ controller
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
1860 ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
1864 SMC 91c111 Ethernet adapter
1866 PL110 LCD controller
1868 PL050 KMI with PS/2 keyboard and mouse.
1870 PL181 MultiMedia Card Interface with SD card.
1873 The ARM Versatile baseboard is emulated with the following devices:
1877 ARM926E, ARM1136 or Cortex-A8 CPU
1879 PL190 Vectored Interrupt Controller
1883 SMC 91c111 Ethernet adapter
1885 PL110 LCD controller
1887 PL050 KMI with PS/2 keyboard and mouse.
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.
1895 PCI OHCI USB controller.
1897 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
1899 PL181 MultiMedia Card Interface with SD card.
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:
1916 ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
1918 ARM AMBA Generic/Distributed Interrupt Controller
1922 SMC 91c111 or SMSC LAN9118 Ethernet adapter
1924 PL110 LCD controller
1926 PL050 KMI with PS/2 keyboard and mouse
1930 PCI OHCI USB controller
1932 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
1934 PL181 MultiMedia Card Interface with SD card.
1937 The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
1938 and "Terrier") emulation includes the following peripherals:
1942 Intel PXA270 System-on-chip (ARM V5TE core)
1946 IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
1948 On-chip OHCI USB controller
1950 On-chip LCD controller
1952 On-chip Real Time Clock
1954 TI ADS7846 touchscreen controller on SSP bus
1956 Maxim MAX1111 analog-digital converter on I@math{^2}C bus
1958 GPIO-connected keyboard controller and LEDs
1960 Secure Digital card connected to PXA MMC/SD host
1964 WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
1967 The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
1972 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1974 ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
1976 On-chip LCD controller
1978 On-chip Real Time Clock
1980 TI TSC2102i touchscreen controller / analog-digital converter / Audio
1981 CODEC, connected through MicroWire and I@math{^2}S busses
1983 GPIO-connected matrix keypad
1985 Secure Digital card connected to OMAP MMC/SD host
1990 Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
1991 emulation supports the following elements:
1995 Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
1997 RAM and non-volatile OneNAND Flash memories
1999 Display connected to EPSON remote framebuffer chip and OMAP on-chip
2000 display controller and a LS041y3 MIPI DBI-C controller
2002 TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2003 driven through SPI bus
2005 National Semiconductor LM8323-controlled qwerty keyboard driven
2006 through I@math{^2}C bus
2008 Secure Digital card connected to OMAP MMC/SD host
2010 Three OMAP on-chip UARTs and on-chip STI debugging console
2012 A Bluetooth(R) transceiver and HCI connected to an UART
2014 Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2015 TUSB6010 chip - only USB host mode is supported
2017 TI TMP105 temperature sensor driven through I@math{^2}C bus
2019 TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2021 Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2025 The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2032 64k Flash and 8k SRAM.
2034 Timers, UARTs, ADC and I@math{^2}C interface.
2036 OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2039 The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2046 256k Flash and 64k SRAM.
2048 Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2050 OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2053 The Freecom MusicPal internet radio emulation includes the following
2058 Marvell MV88W8618 ARM core.
2060 32 MB RAM, 256 KB SRAM, 8 MB flash.
2064 MV88W8xx8 Ethernet controller
2066 MV88W8618 audio controller, WM8750 CODEC and mixer
2068 128×64 display with brightness control
2070 2 buttons, 2 navigation wheels with button function
2073 The Siemens SX1 models v1 and v2 (default) basic emulation.
2074 The emulation includes the following elements:
2078 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2080 ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2082 1 Flash of 16MB and 1 Flash of 8MB
2086 On-chip LCD controller
2088 On-chip Real Time Clock
2090 Secure Digital card connected to OMAP MMC/SD host
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:
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.
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:
2128 MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2130 Three Two on-chip UARTs.
2132 Fast Ethernet Controller (FEC)
2135 The AN5206 emulation includes the following devices:
2139 MCF5206 ColdFire V2 Microprocessor.
2144 @c man begin OPTIONS
2146 The following options are specific to the ColdFire emulation:
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.
2162 @node Cris System emulator
2163 @section Cris System emulator
2164 @cindex system emulation (Cris)
2168 @node Microblaze System emulator
2169 @section Microblaze System emulator
2170 @cindex system emulation (Microblaze)
2174 @node SH4 System emulator
2175 @section SH4 System emulator
2176 @cindex system emulation (SH4)
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:
2190 Xtensa emulator pseudo board "sim"
2192 Avnet LX60/LX110/LX200 board
2195 The sim pseudo board emulation provides an environment similar
2196 to one provided by the proprietary Tensilica ISS.
2201 A range of Xtensa CPUs, default is the DC232B
2203 Console and filesystem access via semihosting calls
2206 The Avnet LX60/LX110/LX200 emulation supports:
2210 A range of Xtensa CPUs, default is the DC232B
2214 OpenCores 10/100 Mbps Ethernet MAC
2217 @c man begin OPTIONS
2219 The following options are specific to the Xtensa emulation:
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.
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
2245 * Supported Operating Systems ::
2247 * Linux User space emulator::
2248 * BSD User space emulator ::
2251 @node Supported Operating Systems
2252 @section Supported Operating Systems
2254 The following OS are supported in user space emulation:
2258 Linux (referred as qemu-linux-user)
2260 BSD (referred as qemu-bsd-user)
2266 QEMU user space emulation has the following notable features:
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.
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.
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
2296 @node Linux User space emulator
2297 @section Linux User space emulator
2302 * Command line options::
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.
2314 @item On x86, you can just try to launch any process by using the native
2318 qemu-i386 -L / /bin/ls
2321 @code{-L /} tells that the x86 dynamic linker must be searched with a
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):
2328 qemu-i386 -L / qemu-i386 -L / /bin/ls
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:
2336 unset LD_LIBRARY_PATH
2339 Then you can launch the precompiled @file{ls} x86 executable:
2342 qemu-i386 tests/i386/ls
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
2349 @item The x86 version of QEMU is also included. You can try weird things such as:
2351 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2352 /usr/local/qemu-i386/bin/ls-i386
2358 @subsection Wine launch
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
2367 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
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}:
2380 qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2381 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2386 @node Command line options
2387 @subsection Command line options
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}...]
2397 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2399 Set the x86 stack size in bytes (default=524288)
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}.
2405 Remove @var{var} from the environment.
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.
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.
2419 Activate logging of the specified items (use '-d help' for a list of log items)
2421 Act as if the host page size was 'pagesize' bytes
2423 Wait gdb connection to port
2425 Run the emulation in single step mode.
2428 Environment variables:
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.
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
2503 * BSD Command line options::
2507 @subsection BSD Status
2511 target Sparc64 on Sparc64: Some trivial programs work.
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.
2522 @item On Sparc64, you can just try to launch any process by using the native
2526 qemu-sparc64 /bin/ls
2531 @node BSD Command line options
2532 @subsection Command line options
2535 @command{qemu-sparc64} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-bsd} @var{type}] @var{program} [@var{arguments}...]
2542 Set the library root path (default=/)
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}.
2551 Remove @var{var} from the environment.
2553 Set the type of the emulated BSD Operating system. Valid values are
2554 FreeBSD, NetBSD and OpenBSD (default).
2561 Activate logging of the specified items (use '-d help' for a list of log items)
2563 Act as if the host page size was 'pagesize' bytes
2565 Run the emulation in single step mode.
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
2590 @section System emulator command line arguments
2592 @subsection -drive boot=on|off (since 1.3.0)
2594 The ``boot=on|off'' option to the ``-drive'' argument is
2595 ignored. Applications should use the ``bootindex=N'' parameter
2596 to set an absolute ordering between devices instead.
2598 @subsection -tdf (since 1.3.0)
2600 The ``-tdf'' argument is ignored. The behaviour implemented
2601 by this argument is now the default when using the KVM PIT,
2602 but can be requested explicitly using
2603 ``-global kvm-pit.lost_tick_policy=slew''.
2605 @subsection -no-kvm-pit-reinjection (since 1.3.0)
2607 The ``-no-kvm-pit-reinjection'' argument is now a
2608 synonym for setting ``-global kvm-pit.lost_tick_policy=discard''.
2610 @subsection -no-kvm-irqchip (since 1.3.0)
2612 The ``-no-kvm-irqchip'' argument is now a synonym for
2613 setting ``-machine kernel_irqchip=off''.
2615 @subsection -no-kvm (since 1.3.0)
2617 The ``-no-kvm'' argument is now a synonym for setting
2618 ``-machine accel=tcg''.
2620 @subsection -mon default=on (since 2.4.0)
2622 The ``default'' option to the ``-mon'' argument is
2623 now ignored. When multiple monitors were enabled, it
2624 indicated which monitor would receive log messages
2625 from the various subsystems. This feature is no longer
2626 required as messages are now only sent to the monitor
2627 in response to explicitly monitor commands.
2629 @subsection -vnc tls (since 2.5.0)
2631 The ``-vnc tls'' argument is now a synonym for setting
2632 ``-object tls-creds-anon,id=tls0'' combined with
2633 ``-vnc tls-creds=tls0'
2635 @subsection -vnc x509 (since 2.5.0)
2637 The ``-vnc x509=/path/to/certs'' argument is now a
2639 ``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=no''
2640 combined with ``-vnc tls-creds=tls0'
2642 @subsection -vnc x509verify (since 2.5.0)
2644 The ``-vnc x509verify=/path/to/certs'' argument is now a
2646 ``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=yes''
2647 combined with ``-vnc tls-creds=tls0'
2649 @subsection -tftp (since 2.6.0)
2651 The ``-tftp /some/dir'' argument is now a synonym for setting
2652 the ``-netdev user,tftp=/some/dir' argument. The new syntax
2653 allows different settings to be provided per NIC.
2655 @subsection -bootp (since 2.6.0)
2657 The ``-bootp /some/file'' argument is now a synonym for setting
2658 the ``-netdev user,bootp=/some/file' argument. The new syntax
2659 allows different settings to be provided per NIC.
2661 @subsection -redir (since 2.6.0)
2663 The ``-redir ARGS'' argument is now a synonym for setting
2664 the ``-netdev user,hostfwd=ARGS'' argument instead. The new
2665 syntax allows different settings to be provided per NIC.
2667 @subsection -smb (since 2.6.0)
2669 The ``-smb /some/dir'' argument is now a synonym for setting
2670 the ``-netdev user,smb=/some/dir'' argument instead. The new
2671 syntax allows different settings to be provided per NIC.
2673 @subsection -net channel (since 2.6.0)
2675 The ``--net channel,ARGS'' argument is now a synonym for setting
2676 the ``-netdev user,guestfwd=ARGS'' argument instead.
2678 @subsection -net vlan (since 2.9.0)
2680 The ``-net vlan=NN'' argument is partially replaced with the
2681 new ``-netdev'' argument. The remaining use cases will no
2682 longer be directly supported in QEMU.
2684 @subsection -drive if=scsi (since 2.9.0)
2686 The ``-drive if=scsi'' argument is replaced by the the
2687 ``-device BUS-TYPE'' argument combined with ``-drive if=none''.
2689 @subsection -net dump (since 2.10.0)
2691 The ``--net dump'' argument is now replaced with the
2692 ``-object filter-dump'' argument which works in combination
2693 with the modern ``-netdev`` backends instead.
2695 @subsection -hdachs (since 2.10.0)
2697 The ``-hdachs'' argument is now a synonym for setting
2698 the ``cyls'', ``heads'', ``secs'', and ``trans'' properties
2699 on the ``ide-hd'' device using the ``-device'' argument.
2700 The new syntax allows different settings to be provided
2703 @subsection -usbdevice (since 2.10.0)
2705 The ``-usbdevice DEV'' argument is now a synonym for setting
2706 the ``-device usb-DEV'' argument instead. The deprecated syntax
2707 would automatically enable USB support on the machine type.
2708 If using the new syntax, USB support must be explicitly
2709 enabled via the ``-machine usb=on'' argument.
2711 @subsection -nodefconfig (since 2.11.0)
2713 The ``-nodefconfig`` argument is a synonym for ``-no-user-config``.
2715 @subsection -machine s390-squash-mcss=on|off (since 2.12.0)
2717 The ``s390-squash-mcss=on`` property has been obsoleted by allowing the
2718 cssid to be chosen freely. Instead of squashing subchannels into the
2719 default channel subsystem image for guests that do not support multiple
2720 channel subsystems, all devices can be put into the default channel
2723 @section qemu-img command line arguments
2725 @subsection convert -s (since 2.0.0)
2727 The ``convert -s snapshot_id_or_name'' argument is obsoleted
2728 by the ``convert -l snapshot_param'' argument instead.
2730 @section System emulator human monitor commands
2732 @subsection host_net_add (since 2.10.0)
2734 The ``host_net_add'' command is replaced by the ``netdev_add'' command.
2736 @subsection host_net_remove (since 2.10.0)
2738 The ``host_net_remove'' command is replaced by the ``netdev_del'' command.
2740 @section System emulator devices
2742 @subsection ivshmem (since 2.6.0)
2744 The ``ivshmem'' device type is replaced by either the ``ivshmem-plain''
2745 or ``ivshmem-doorbell`` device types.
2747 @subsection spapr-pci-vfio-host-bridge (since 2.6.0)
2749 The ``spapr-pci-vfio-host-bridge'' device type is replaced by
2750 the ``spapr-pci-host-bridge'' device type.
2752 @section System emulator machines
2754 @subsection Xilinx EP108 (since 2.11.0)
2756 The ``xlnx-ep108'' machine has been replaced by the ``xlnx-zcu102'' machine.
2757 The ``xlnx-zcu102'' machine has the same features and capabilites in QEMU.
2762 QEMU is a trademark of Fabrice Bellard.
2764 QEMU is released under the
2765 @url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
2766 version 2. Parts of QEMU have specific licenses, see file
2767 @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
2781 @section Concept Index
2782 This is the main index. Should we combine all keywords in one index? TODO
2785 @node Function Index
2786 @section Function Index
2787 This index could be used for command line options and monitor functions.
2790 @node Keystroke Index
2791 @section Keystroke Index
2793 This is a list of all keystrokes which have a special function
2794 in system emulation.
2799 @section Program Index
2802 @node Data Type Index
2803 @section Data Type Index
2805 This index could be used for qdev device names and options.
2809 @node Variable Index
2810 @section Variable Index