virtio: check VirtQueue Vring object is set
[qemu/ar7.git] / qemu-doc.texi
blobdb2351c74607156d81983984f1cdd1e282341f7d
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 @node pcsys_keys
249 @section Keys in the graphical frontends
251 @c man begin OPTIONS
253 During the graphical emulation, you can use special key combinations to change
254 modes. The default key mappings are shown below, but if you use @code{-alt-grab}
255 then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
256 @code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
258 @table @key
259 @item Ctrl-Alt-f
260 @kindex Ctrl-Alt-f
261 Toggle full screen
263 @item Ctrl-Alt-+
264 @kindex Ctrl-Alt-+
265 Enlarge the screen
267 @item Ctrl-Alt--
268 @kindex Ctrl-Alt--
269 Shrink the screen
271 @item Ctrl-Alt-u
272 @kindex Ctrl-Alt-u
273 Restore the screen's un-scaled dimensions
275 @item Ctrl-Alt-n
276 @kindex Ctrl-Alt-n
277 Switch to virtual console 'n'. Standard console mappings are:
278 @table @emph
279 @item 1
280 Target system display
281 @item 2
282 Monitor
283 @item 3
284 Serial port
285 @end table
287 @item Ctrl-Alt
288 @kindex Ctrl-Alt
289 Toggle mouse and keyboard grab.
290 @end table
292 @kindex Ctrl-Up
293 @kindex Ctrl-Down
294 @kindex Ctrl-PageUp
295 @kindex Ctrl-PageDown
296 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
297 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
299 @c man end
301 @node mux_keys
302 @section Keys in the character backend multiplexer
304 @c man begin OPTIONS
306 During emulation, if you are using a character backend multiplexer
307 (which is the default if you are using @option{-nographic}) then
308 several commands are available via an escape sequence. These
309 key sequences all start with an escape character, which is @key{Ctrl-a}
310 by default, but can be changed with @option{-echr}. The list below assumes
311 you're using the default.
313 @table @key
314 @item Ctrl-a h
315 @kindex Ctrl-a h
316 Print this help
317 @item Ctrl-a x
318 @kindex Ctrl-a x
319 Exit emulator
320 @item Ctrl-a s
321 @kindex Ctrl-a s
322 Save disk data back to file (if -snapshot)
323 @item Ctrl-a t
324 @kindex Ctrl-a t
325 Toggle console timestamps
326 @item Ctrl-a b
327 @kindex Ctrl-a b
328 Send break (magic sysrq in Linux)
329 @item Ctrl-a c
330 @kindex Ctrl-a c
331 Rotate between the frontends connected to the multiplexer (usually
332 this switches between the monitor and the console)
333 @item Ctrl-a Ctrl-a
334 @kindex Ctrl-a Ctrl-a
335 Send the escape character to the frontend
336 @end table
337 @c man end
339 @ignore
341 @c man begin SEEALSO
342 The HTML documentation of QEMU for more precise information and Linux
343 user mode emulator invocation.
344 @c man end
346 @c man begin AUTHOR
347 Fabrice Bellard
348 @c man end
350 @end ignore
352 @node pcsys_monitor
353 @section QEMU Monitor
354 @cindex QEMU monitor
356 The QEMU monitor is used to give complex commands to the QEMU
357 emulator. You can use it to:
359 @itemize @minus
361 @item
362 Remove or insert removable media images
363 (such as CD-ROM or floppies).
365 @item
366 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
367 from a disk file.
369 @item Inspect the VM state without an external debugger.
371 @end itemize
373 @subsection Commands
375 The following commands are available:
377 @include qemu-monitor.texi
379 @include qemu-monitor-info.texi
381 @subsection Integer expressions
383 The monitor understands integers expressions for every integer
384 argument. You can use register names to get the value of specifics
385 CPU registers by prefixing them with @emph{$}.
387 @node disk_images
388 @section Disk Images
390 QEMU supports many disk image formats, including growable disk images
391 (their size increase as non empty sectors are written), compressed and
392 encrypted disk images.
394 @menu
395 * disk_images_quickstart::    Quick start for disk image creation
396 * disk_images_snapshot_mode:: Snapshot mode
397 * vm_snapshots::              VM snapshots
398 * qemu_img_invocation::       qemu-img Invocation
399 * qemu_nbd_invocation::       qemu-nbd Invocation
400 * disk_images_formats::       Disk image file formats
401 * host_drives::               Using host drives
402 * disk_images_fat_images::    Virtual FAT disk images
403 * disk_images_nbd::           NBD access
404 * disk_images_sheepdog::      Sheepdog disk images
405 * disk_images_iscsi::         iSCSI LUNs
406 * disk_images_gluster::       GlusterFS disk images
407 * disk_images_ssh::           Secure Shell (ssh) disk images
408 * disk_image_locking::        Disk image file locking
409 @end menu
411 @node disk_images_quickstart
412 @subsection Quick start for disk image creation
414 You can create a disk image with the command:
415 @example
416 qemu-img create myimage.img mysize
417 @end example
418 where @var{myimage.img} is the disk image filename and @var{mysize} is its
419 size in kilobytes. You can add an @code{M} suffix to give the size in
420 megabytes and a @code{G} suffix for gigabytes.
422 See @ref{qemu_img_invocation} for more information.
424 @node disk_images_snapshot_mode
425 @subsection Snapshot mode
427 If you use the option @option{-snapshot}, all disk images are
428 considered as read only. When sectors in written, they are written in
429 a temporary file created in @file{/tmp}. You can however force the
430 write back to the raw disk images by using the @code{commit} monitor
431 command (or @key{C-a s} in the serial console).
433 @node vm_snapshots
434 @subsection VM snapshots
436 VM snapshots are snapshots of the complete virtual machine including
437 CPU state, RAM, device state and the content of all the writable
438 disks. In order to use VM snapshots, you must have at least one non
439 removable and writable block device using the @code{qcow2} disk image
440 format. Normally this device is the first virtual hard drive.
442 Use the monitor command @code{savevm} to create a new VM snapshot or
443 replace an existing one. A human readable name can be assigned to each
444 snapshot in addition to its numerical ID.
446 Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
447 a VM snapshot. @code{info snapshots} lists the available snapshots
448 with their associated information:
450 @example
451 (qemu) info snapshots
452 Snapshot devices: hda
453 Snapshot list (from hda):
454 ID        TAG                 VM SIZE                DATE       VM CLOCK
455 1         start                   41M 2006-08-06 12:38:02   00:00:14.954
456 2                                 40M 2006-08-06 12:43:29   00:00:18.633
457 3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
458 @end example
460 A VM snapshot is made of a VM state info (its size is shown in
461 @code{info snapshots}) and a snapshot of every writable disk image.
462 The VM state info is stored in the first @code{qcow2} non removable
463 and writable block device. The disk image snapshots are stored in
464 every disk image. The size of a snapshot in a disk image is difficult
465 to evaluate and is not shown by @code{info snapshots} because the
466 associated disk sectors are shared among all the snapshots to save
467 disk space (otherwise each snapshot would need a full copy of all the
468 disk images).
470 When using the (unrelated) @code{-snapshot} option
471 (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
472 but they are deleted as soon as you exit QEMU.
474 VM snapshots currently have the following known limitations:
475 @itemize
476 @item
477 They cannot cope with removable devices if they are removed or
478 inserted after a snapshot is done.
479 @item
480 A few device drivers still have incomplete snapshot support so their
481 state is not saved or restored properly (in particular USB).
482 @end itemize
484 @node qemu_img_invocation
485 @subsection @code{qemu-img} Invocation
487 @include qemu-img.texi
489 @node qemu_nbd_invocation
490 @subsection @code{qemu-nbd} Invocation
492 @include qemu-nbd.texi
494 @include docs/qemu-block-drivers.texi
496 @node pcsys_network
497 @section Network emulation
499 QEMU can simulate several network cards (PCI or ISA cards on the PC
500 target) and can connect them to an arbitrary number of Virtual Local
501 Area Networks (VLANs). Host TAP devices can be connected to any QEMU
502 VLAN. VLAN can be connected between separate instances of QEMU to
503 simulate large networks. For simpler usage, a non privileged user mode
504 network stack can replace the TAP device to have a basic network
505 connection.
507 @subsection VLANs
509 QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
510 connection between several network devices. These devices can be for
511 example QEMU virtual Ethernet cards or virtual Host ethernet devices
512 (TAP devices).
514 @subsection Using TAP network interfaces
516 This is the standard way to connect QEMU to a real network. QEMU adds
517 a virtual network device on your host (called @code{tapN}), and you
518 can then configure it as if it was a real ethernet card.
520 @subsubsection Linux host
522 As an example, you can download the @file{linux-test-xxx.tar.gz}
523 archive and copy the script @file{qemu-ifup} in @file{/etc} and
524 configure properly @code{sudo} so that the command @code{ifconfig}
525 contained in @file{qemu-ifup} can be executed as root. You must verify
526 that your host kernel supports the TAP network interfaces: the
527 device @file{/dev/net/tun} must be present.
529 See @ref{sec_invocation} to have examples of command lines using the
530 TAP network interfaces.
532 @subsubsection Windows host
534 There is a virtual ethernet driver for Windows 2000/XP systems, called
535 TAP-Win32. But it is not included in standard QEMU for Windows,
536 so you will need to get it separately. It is part of OpenVPN package,
537 so download OpenVPN from : @url{https://openvpn.net/}.
539 @subsection Using the user mode network stack
541 By using the option @option{-net user} (default configuration if no
542 @option{-net} option is specified), QEMU uses a completely user mode
543 network stack (you don't need root privilege to use the virtual
544 network). The virtual network configuration is the following:
546 @example
548          QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
549                            |          (10.0.2.2)
550                            |
551                            ---->  DNS server (10.0.2.3)
552                            |
553                            ---->  SMB server (10.0.2.4)
554 @end example
556 The QEMU VM behaves as if it was behind a firewall which blocks all
557 incoming connections. You can use a DHCP client to automatically
558 configure the network in the QEMU VM. The DHCP server assign addresses
559 to the hosts starting from 10.0.2.15.
561 In order to check that the user mode network is working, you can ping
562 the address 10.0.2.2 and verify that you got an address in the range
563 10.0.2.x from the QEMU virtual DHCP server.
565 Note that ICMP traffic in general does not work with user mode networking.
566 @code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
567 however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
568 ping sockets to allow @code{ping} to the Internet. The host admin has to set
569 the ping_group_range in order to grant access to those sockets. To allow ping
570 for GID 100 (usually users group):
572 @example
573 echo 100 100 > /proc/sys/net/ipv4/ping_group_range
574 @end example
576 When using the built-in TFTP server, the router is also the TFTP
577 server.
579 When using the @option{'-netdev user,hostfwd=...'} option, TCP or UDP
580 connections can be redirected from the host to the guest. It allows for
581 example to redirect X11, telnet or SSH connections.
583 @subsection Connecting VLANs between QEMU instances
585 Using the @option{-net socket} option, it is possible to make VLANs
586 that span several QEMU instances. See @ref{sec_invocation} to have a
587 basic example.
589 @node pcsys_other_devs
590 @section Other Devices
592 @subsection Inter-VM Shared Memory device
594 On Linux hosts, a shared memory device is available.  The basic syntax
597 @example
598 qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem}
599 @end example
601 where @var{hostmem} names a host memory backend.  For a POSIX shared
602 memory backend, use something like
604 @example
605 -object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
606 @end example
608 If desired, interrupts can be sent between guest VMs accessing the same shared
609 memory region.  Interrupt support requires using a shared memory server and
610 using a chardev socket to connect to it.  The code for the shared memory server
611 is qemu.git/contrib/ivshmem-server.  An example syntax when using the shared
612 memory server is:
614 @example
615 # First start the ivshmem server once and for all
616 ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}
618 # Then start your qemu instances with matching arguments
619 qemu-system-x86_64 -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
620                  -chardev socket,path=@var{path},id=@var{id}
621 @end example
623 When using the server, the guest will be assigned a VM ID (>=0) that allows guests
624 using the same server to communicate via interrupts.  Guests can read their
625 VM ID from a device register (see ivshmem-spec.txt).
627 @subsubsection Migration with ivshmem
629 With device property @option{master=on}, the guest will copy the shared
630 memory on migration to the destination host.  With @option{master=off},
631 the guest will not be able to migrate with the device attached.  In the
632 latter case, the device should be detached and then reattached after
633 migration using the PCI hotplug support.
635 At most one of the devices sharing the same memory can be master.  The
636 master must complete migration before you plug back the other devices.
638 @subsubsection ivshmem and hugepages
640 Instead of specifying the <shm size> using POSIX shm, you may specify
641 a memory backend that has hugepage support:
643 @example
644 qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
645                  -device ivshmem-plain,memdev=mb1
646 @end example
648 ivshmem-server also supports hugepages mount points with the
649 @option{-m} memory path argument.
651 @node direct_linux_boot
652 @section Direct Linux Boot
654 This section explains how to launch a Linux kernel inside QEMU without
655 having to make a full bootable image. It is very useful for fast Linux
656 kernel testing.
658 The syntax is:
659 @example
660 qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
661 @end example
663 Use @option{-kernel} to provide the Linux kernel image and
664 @option{-append} to give the kernel command line arguments. The
665 @option{-initrd} option can be used to provide an INITRD image.
667 When using the direct Linux boot, a disk image for the first hard disk
668 @file{hda} is required because its boot sector is used to launch the
669 Linux kernel.
671 If you do not need graphical output, you can disable it and redirect
672 the virtual serial port and the QEMU monitor to the console with the
673 @option{-nographic} option. The typical command line is:
674 @example
675 qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
676                  -append "root=/dev/hda console=ttyS0" -nographic
677 @end example
679 Use @key{Ctrl-a c} to switch between the serial console and the
680 monitor (@pxref{pcsys_keys}).
682 @node pcsys_usb
683 @section USB emulation
685 QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
686 plug virtual USB devices or real host USB devices (only works with certain
687 host operating systems). QEMU will automatically create and connect virtual
688 USB hubs as necessary to connect multiple USB devices.
690 @menu
691 * usb_devices::
692 * host_usb_devices::
693 @end menu
694 @node usb_devices
695 @subsection Connecting USB devices
697 USB devices can be connected with the @option{-device usb-...} command line
698 option or the @code{device_add} monitor command. Available devices are:
700 @table @code
701 @item usb-mouse
702 Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
703 @item usb-tablet
704 Pointer device that uses absolute coordinates (like a touchscreen).
705 This means QEMU is able to report the mouse position without having
706 to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
707 @item usb-storage,drive=@var{drive_id}
708 Mass storage device backed by @var{drive_id} (@pxref{disk_images})
709 @item usb-uas
710 USB attached SCSI device, see
711 @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
712 for details
713 @item usb-bot
714 Bulk-only transport storage device, see
715 @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
716 for details here, too
717 @item usb-mtp,x-root=@var{dir}
718 Media transfer protocol device, using @var{dir} as root of the file tree
719 that is presented to the guest.
720 @item usb-host,hostbus=@var{bus},hostaddr=@var{addr}
721 Pass through the host device identified by @var{bus} and @var{addr}
722 @item usb-host,vendorid=@var{vendor},productid=@var{product}
723 Pass through the host device identified by @var{vendor} and @var{product} ID
724 @item usb-wacom-tablet
725 Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
726 above but it can be used with the tslib library because in addition to touch
727 coordinates it reports touch pressure.
728 @item usb-kbd
729 Standard USB keyboard.  Will override the PS/2 keyboard (if present).
730 @item usb-serial,chardev=@var{id}
731 Serial converter. This emulates an FTDI FT232BM chip connected to host character
732 device @var{id}.
733 @item usb-braille,chardev=@var{id}
734 Braille device.  This will use BrlAPI to display the braille output on a real
735 or fake device referenced by @var{id}.
736 @item usb-net[,netdev=@var{id}]
737 Network adapter that supports CDC ethernet and RNDIS protocols.  @var{id}
738 specifies a netdev defined with @code{-netdev @dots{},id=@var{id}}.
739 For instance, user-mode networking can be used with
740 @example
741 qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
742 @end example
743 @item usb-ccid
744 Smartcard reader device
745 @item usb-audio
746 USB audio device
747 @item usb-bt-dongle
748 Bluetooth dongle for the transport layer of HCI. It is connected to HCI
749 scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}).
750 Note that the syntax for the @code{-device usb-bt-dongle} option is not as
751 useful yet as it was with the legacy @code{-usbdevice} option. So to
752 configure an USB bluetooth device, you might need to use
753 "@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a
754 bluetooth dongle whose type is specified in the same format as with
755 the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
756 no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
757 This USB device implements the USB Transport Layer of HCI.  Example
758 usage:
759 @example
760 @command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3
761 @end example
762 @end table
764 @node host_usb_devices
765 @subsection Using host USB devices on a Linux host
767 WARNING: this is an experimental feature. QEMU will slow down when
768 using it. USB devices requiring real time streaming (i.e. USB Video
769 Cameras) are not supported yet.
771 @enumerate
772 @item If you use an early Linux 2.4 kernel, verify that no Linux driver
773 is actually using the USB device. A simple way to do that is simply to
774 disable the corresponding kernel module by renaming it from @file{mydriver.o}
775 to @file{mydriver.o.disabled}.
777 @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
778 @example
779 ls /proc/bus/usb
780 001  devices  drivers
781 @end example
783 @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:
784 @example
785 chown -R myuid /proc/bus/usb
786 @end example
788 @item Launch QEMU and do in the monitor:
789 @example
790 info usbhost
791   Device 1.2, speed 480 Mb/s
792     Class 00: USB device 1234:5678, USB DISK
793 @end example
794 You should see the list of the devices you can use (Never try to use
795 hubs, it won't work).
797 @item Add the device in QEMU by using:
798 @example
799 device_add usb-host,vendorid=0x1234,productid=0x5678
800 @end example
802 Normally the guest OS should report that a new USB device is plugged.
803 You can use the option @option{-device usb-host,...} to do the same.
805 @item Now you can try to use the host USB device in QEMU.
807 @end enumerate
809 When relaunching QEMU, you may have to unplug and plug again the USB
810 device to make it work again (this is a bug).
812 @node vnc_security
813 @section VNC security
815 The VNC server capability provides access to the graphical console
816 of the guest VM across the network. This has a number of security
817 considerations depending on the deployment scenarios.
819 @menu
820 * vnc_sec_none::
821 * vnc_sec_password::
822 * vnc_sec_certificate::
823 * vnc_sec_certificate_verify::
824 * vnc_sec_certificate_pw::
825 * vnc_sec_sasl::
826 * vnc_sec_certificate_sasl::
827 * vnc_generate_cert::
828 * vnc_setup_sasl::
829 @end menu
830 @node vnc_sec_none
831 @subsection Without passwords
833 The simplest VNC server setup does not include any form of authentication.
834 For this setup it is recommended to restrict it to listen on a UNIX domain
835 socket only. For example
837 @example
838 qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
839 @end example
841 This ensures that only users on local box with read/write access to that
842 path can access the VNC server. To securely access the VNC server from a
843 remote machine, a combination of netcat+ssh can be used to provide a secure
844 tunnel.
846 @node vnc_sec_password
847 @subsection With passwords
849 The VNC protocol has limited support for password based authentication. Since
850 the protocol limits passwords to 8 characters it should not be considered
851 to provide high security. The password can be fairly easily brute-forced by
852 a client making repeat connections. For this reason, a VNC server using password
853 authentication should be restricted to only listen on the loopback interface
854 or UNIX domain sockets. Password authentication is not supported when operating
855 in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
856 authentication is requested with the @code{password} option, and then once QEMU
857 is running the password is set with the monitor. Until the monitor is used to
858 set the password all clients will be rejected.
860 @example
861 qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
862 (qemu) change vnc password
863 Password: ********
864 (qemu)
865 @end example
867 @node vnc_sec_certificate
868 @subsection With x509 certificates
870 The QEMU VNC server also implements the VeNCrypt extension allowing use of
871 TLS for encryption of the session, and x509 certificates for authentication.
872 The use of x509 certificates is strongly recommended, because TLS on its
873 own is susceptible to man-in-the-middle attacks. Basic x509 certificate
874 support provides a secure session, but no authentication. This allows any
875 client to connect, and provides an encrypted session.
877 @example
878 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
879 @end example
881 In the above example @code{/etc/pki/qemu} should contain at least three files,
882 @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
883 users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
884 NB the @code{server-key.pem} file should be protected with file mode 0600 to
885 only be readable by the user owning it.
887 @node vnc_sec_certificate_verify
888 @subsection With x509 certificates and client verification
890 Certificates can also provide a means to authenticate the client connecting.
891 The server will request that the client provide a certificate, which it will
892 then validate against the CA certificate. This is a good choice if deploying
893 in an environment with a private internal certificate authority.
895 @example
896 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
897 @end example
900 @node vnc_sec_certificate_pw
901 @subsection With x509 certificates, client verification and passwords
903 Finally, the previous method can be combined with VNC password authentication
904 to provide two layers of authentication for clients.
906 @example
907 qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
908 (qemu) change vnc password
909 Password: ********
910 (qemu)
911 @end example
914 @node vnc_sec_sasl
915 @subsection With SASL authentication
917 The SASL authentication method is a VNC extension, that provides an
918 easily extendable, pluggable authentication method. This allows for
919 integration with a wide range of authentication mechanisms, such as
920 PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
921 The strength of the authentication depends on the exact mechanism
922 configured. If the chosen mechanism also provides a SSF layer, then
923 it will encrypt the datastream as well.
925 Refer to the later docs on how to choose the exact SASL mechanism
926 used for authentication, but assuming use of one supporting SSF,
927 then QEMU can be launched with:
929 @example
930 qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
931 @end example
933 @node vnc_sec_certificate_sasl
934 @subsection With x509 certificates and SASL authentication
936 If the desired SASL authentication mechanism does not supported
937 SSF layers, then it is strongly advised to run it in combination
938 with TLS and x509 certificates. This provides securely encrypted
939 data stream, avoiding risk of compromising of the security
940 credentials. This can be enabled, by combining the 'sasl' option
941 with the aforementioned TLS + x509 options:
943 @example
944 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
945 @end example
948 @node vnc_generate_cert
949 @subsection Generating certificates for VNC
951 The GNU TLS packages provides a command called @code{certtool} which can
952 be used to generate certificates and keys in PEM format. At a minimum it
953 is necessary to setup a certificate authority, and issue certificates to
954 each server. If using certificates for authentication, then each client
955 will also need to be issued a certificate. The recommendation is for the
956 server to keep its certificates in either @code{/etc/pki/qemu} or for
957 unprivileged users in @code{$HOME/.pki/qemu}.
959 @menu
960 * vnc_generate_ca::
961 * vnc_generate_server::
962 * vnc_generate_client::
963 @end menu
964 @node vnc_generate_ca
965 @subsubsection Setup the Certificate Authority
967 This step only needs to be performed once per organization / organizational
968 unit. First the CA needs a private key. This key must be kept VERY secret
969 and secure. If this key is compromised the entire trust chain of the certificates
970 issued with it is lost.
972 @example
973 # certtool --generate-privkey > ca-key.pem
974 @end example
976 A CA needs to have a public certificate. For simplicity it can be a self-signed
977 certificate, or one issue by a commercial certificate issuing authority. To
978 generate a self-signed certificate requires one core piece of information, the
979 name of the organization.
981 @example
982 # cat > ca.info <<EOF
983 cn = Name of your organization
985 cert_signing_key
987 # certtool --generate-self-signed \
988            --load-privkey ca-key.pem
989            --template ca.info \
990            --outfile ca-cert.pem
991 @end example
993 The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
994 TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
996 @node vnc_generate_server
997 @subsubsection Issuing server certificates
999 Each server (or host) needs to be issued with a key and certificate. When connecting
1000 the certificate is sent to the client which validates it against the CA certificate.
1001 The core piece of information for a server certificate is the hostname. This should
1002 be the fully qualified hostname that the client will connect with, since the client
1003 will typically also verify the hostname in the certificate. On the host holding the
1004 secure CA private key:
1006 @example
1007 # cat > server.info <<EOF
1008 organization = Name  of your organization
1009 cn = server.foo.example.com
1010 tls_www_server
1011 encryption_key
1012 signing_key
1014 # certtool --generate-privkey > server-key.pem
1015 # certtool --generate-certificate \
1016            --load-ca-certificate ca-cert.pem \
1017            --load-ca-privkey ca-key.pem \
1018            --load-privkey server-key.pem \
1019            --template server.info \
1020            --outfile server-cert.pem
1021 @end example
1023 The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1024 to the server for which they were generated. The @code{server-key.pem} is security
1025 sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1027 @node vnc_generate_client
1028 @subsubsection Issuing client certificates
1030 If the QEMU VNC server is to use the @code{x509verify} option to validate client
1031 certificates as its authentication mechanism, each client also needs to be issued
1032 a certificate. The client certificate contains enough metadata to uniquely identify
1033 the client, typically organization, state, city, building, etc. On the host holding
1034 the secure CA private key:
1036 @example
1037 # cat > client.info <<EOF
1038 country = GB
1039 state = London
1040 locality = London
1041 organization = Name of your organization
1042 cn = client.foo.example.com
1043 tls_www_client
1044 encryption_key
1045 signing_key
1047 # certtool --generate-privkey > client-key.pem
1048 # certtool --generate-certificate \
1049            --load-ca-certificate ca-cert.pem \
1050            --load-ca-privkey ca-key.pem \
1051            --load-privkey client-key.pem \
1052            --template client.info \
1053            --outfile client-cert.pem
1054 @end example
1056 The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1057 copied to the client for which they were generated.
1060 @node vnc_setup_sasl
1062 @subsection Configuring SASL mechanisms
1064 The following documentation assumes use of the Cyrus SASL implementation on a
1065 Linux host, but the principals should apply to any other SASL impl. When SASL
1066 is enabled, the mechanism configuration will be loaded from system default
1067 SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1068 unprivileged user, an environment variable SASL_CONF_PATH can be used
1069 to make it search alternate locations for the service config.
1071 If the TLS option is enabled for VNC, then it will provide session encryption,
1072 otherwise the SASL mechanism will have to provide encryption. In the latter
1073 case the list of possible plugins that can be used is drastically reduced. In
1074 fact only the GSSAPI SASL mechanism provides an acceptable level of security
1075 by modern standards. Previous versions of QEMU referred to the DIGEST-MD5
1076 mechanism, however, it has multiple serious flaws described in detail in
1077 RFC 6331 and thus should never be used any more. The SCRAM-SHA-1 mechanism
1078 provides a simple username/password auth facility similar to DIGEST-MD5, but
1079 does not support session encryption, so can only be used in combination with
1080 TLS.
1082 When not using TLS the recommended configuration is
1084 @example
1085 mech_list: gssapi
1086 keytab: /etc/qemu/krb5.tab
1087 @end example
1089 This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol, with
1090 the server principal stored in /etc/qemu/krb5.tab. For this to work the
1091 administrator of your KDC must generate a Kerberos principal for the server,
1092 with a name of 'qemu/somehost.example.com@@EXAMPLE.COM' replacing
1093 'somehost.example.com' with the fully qualified host name of the machine
1094 running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
1096 When using TLS, if username+password authentication is desired, then a
1097 reasonable configuration is
1099 @example
1100 mech_list: scram-sha-1
1101 sasldb_path: /etc/qemu/passwd.db
1102 @end example
1104 The saslpasswd2 program can be used to populate the passwd.db file with
1105 accounts.
1107 Other SASL configurations will be left as an exercise for the reader. Note that
1108 all mechanisms except GSSAPI, should be combined with use of TLS to ensure a
1109 secure data channel.
1111 @node gdb_usage
1112 @section GDB usage
1114 QEMU has a primitive support to work with gdb, so that you can do
1115 'Ctrl-C' while the virtual machine is running and inspect its state.
1117 In order to use gdb, launch QEMU with the '-s' option. It will wait for a
1118 gdb connection:
1119 @example
1120 qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1121                     -append "root=/dev/hda"
1122 Connected to host network interface: tun0
1123 Waiting gdb connection on port 1234
1124 @end example
1126 Then launch gdb on the 'vmlinux' executable:
1127 @example
1128 > gdb vmlinux
1129 @end example
1131 In gdb, connect to QEMU:
1132 @example
1133 (gdb) target remote localhost:1234
1134 @end example
1136 Then you can use gdb normally. For example, type 'c' to launch the kernel:
1137 @example
1138 (gdb) c
1139 @end example
1141 Here are some useful tips in order to use gdb on system code:
1143 @enumerate
1144 @item
1145 Use @code{info reg} to display all the CPU registers.
1146 @item
1147 Use @code{x/10i $eip} to display the code at the PC position.
1148 @item
1149 Use @code{set architecture i8086} to dump 16 bit code. Then use
1150 @code{x/10i $cs*16+$eip} to dump the code at the PC position.
1151 @end enumerate
1153 Advanced debugging options:
1155 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:
1156 @table @code
1157 @item maintenance packet qqemu.sstepbits
1159 This will display the MASK bits used to control the single stepping IE:
1160 @example
1161 (gdb) maintenance packet qqemu.sstepbits
1162 sending: "qqemu.sstepbits"
1163 received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1164 @end example
1165 @item maintenance packet qqemu.sstep
1167 This will display the current value of the mask used when single stepping IE:
1168 @example
1169 (gdb) maintenance packet qqemu.sstep
1170 sending: "qqemu.sstep"
1171 received: "0x7"
1172 @end example
1173 @item maintenance packet Qqemu.sstep=HEX_VALUE
1175 This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1176 @example
1177 (gdb) maintenance packet Qqemu.sstep=0x5
1178 sending: "qemu.sstep=0x5"
1179 received: "OK"
1180 @end example
1181 @end table
1183 @node pcsys_os_specific
1184 @section Target OS specific information
1186 @subsection Linux
1188 To have access to SVGA graphic modes under X11, use the @code{vesa} or
1189 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1190 color depth in the guest and the host OS.
1192 When using a 2.6 guest Linux kernel, you should add the option
1193 @code{clock=pit} on the kernel command line because the 2.6 Linux
1194 kernels make very strict real time clock checks by default that QEMU
1195 cannot simulate exactly.
1197 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1198 not activated because QEMU is slower with this patch. The QEMU
1199 Accelerator Module is also much slower in this case. Earlier Fedora
1200 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1201 patch by default. Newer kernels don't have it.
1203 @subsection Windows
1205 If you have a slow host, using Windows 95 is better as it gives the
1206 best speed. Windows 2000 is also a good choice.
1208 @subsubsection SVGA graphic modes support
1210 QEMU emulates a Cirrus Logic GD5446 Video
1211 card. All Windows versions starting from Windows 95 should recognize
1212 and use this graphic card. For optimal performances, use 16 bit color
1213 depth in the guest and the host OS.
1215 If you are using Windows XP as guest OS and if you want to use high
1216 resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
1217 1280x1024x16), then you should use the VESA VBE virtual graphic card
1218 (option @option{-std-vga}).
1220 @subsubsection CPU usage reduction
1222 Windows 9x does not correctly use the CPU HLT
1223 instruction. The result is that it takes host CPU cycles even when
1224 idle. You can install the utility from
1225 @url{https://web.archive.org/web/20060212132151/http://www.user.cityline.ru/~maxamn/amnhltm.zip}
1226 to solve this problem. Note that no such tool is needed for NT, 2000 or XP.
1228 @subsubsection Windows 2000 disk full problem
1230 Windows 2000 has a bug which gives a disk full problem during its
1231 installation. When installing it, use the @option{-win2k-hack} QEMU
1232 option to enable a specific workaround. After Windows 2000 is
1233 installed, you no longer need this option (this option slows down the
1234 IDE transfers).
1236 @subsubsection Windows 2000 shutdown
1238 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1239 can. It comes from the fact that Windows 2000 does not automatically
1240 use the APM driver provided by the BIOS.
1242 In order to correct that, do the following (thanks to Struan
1243 Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1244 Add/Troubleshoot a device => Add a new device & Next => No, select the
1245 hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1246 (again) a few times. Now the driver is installed and Windows 2000 now
1247 correctly instructs QEMU to shutdown at the appropriate moment.
1249 @subsubsection Share a directory between Unix and Windows
1251 See @ref{sec_invocation} about the help of the option
1252 @option{'-netdev user,smb=...'}.
1254 @subsubsection Windows XP security problem
1256 Some releases of Windows XP install correctly but give a security
1257 error when booting:
1258 @example
1259 A problem is preventing Windows from accurately checking the
1260 license for this computer. Error code: 0x800703e6.
1261 @end example
1263 The workaround is to install a service pack for XP after a boot in safe
1264 mode. Then reboot, and the problem should go away. Since there is no
1265 network while in safe mode, its recommended to download the full
1266 installation of SP1 or SP2 and transfer that via an ISO or using the
1267 vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1269 @subsection MS-DOS and FreeDOS
1271 @subsubsection CPU usage reduction
1273 DOS does not correctly use the CPU HLT instruction. The result is that
1274 it takes host CPU cycles even when idle. You can install the utility from
1275 @url{https://web.archive.org/web/20051222085335/http://www.vmware.com/software/dosidle210.zip}
1276 to solve this problem.
1278 @node QEMU System emulator for non PC targets
1279 @chapter QEMU System emulator for non PC targets
1281 QEMU is a generic emulator and it emulates many non PC
1282 machines. Most of the options are similar to the PC emulator. The
1283 differences are mentioned in the following sections.
1285 @menu
1286 * PowerPC System emulator::
1287 * Sparc32 System emulator::
1288 * Sparc64 System emulator::
1289 * MIPS System emulator::
1290 * ARM System emulator::
1291 * ColdFire System emulator::
1292 * Cris System emulator::
1293 * Microblaze System emulator::
1294 * SH4 System emulator::
1295 * Xtensa System emulator::
1296 @end menu
1298 @node PowerPC System emulator
1299 @section PowerPC System emulator
1300 @cindex system emulation (PowerPC)
1302 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1303 or PowerMac PowerPC system.
1305 QEMU emulates the following PowerMac peripherals:
1307 @itemize @minus
1308 @item
1309 UniNorth or Grackle PCI Bridge
1310 @item
1311 PCI VGA compatible card with VESA Bochs Extensions
1312 @item
1313 2 PMAC IDE interfaces with hard disk and CD-ROM support
1314 @item
1315 NE2000 PCI adapters
1316 @item
1317 Non Volatile RAM
1318 @item
1319 VIA-CUDA with ADB keyboard and mouse.
1320 @end itemize
1322 QEMU emulates the following PREP peripherals:
1324 @itemize @minus
1325 @item
1326 PCI Bridge
1327 @item
1328 PCI VGA compatible card with VESA Bochs Extensions
1329 @item
1330 2 IDE interfaces with hard disk and CD-ROM support
1331 @item
1332 Floppy disk
1333 @item
1334 NE2000 network adapters
1335 @item
1336 Serial port
1337 @item
1338 PREP Non Volatile RAM
1339 @item
1340 PC compatible keyboard and mouse.
1341 @end itemize
1343 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1344 @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
1346 Since version 0.9.1, QEMU uses OpenBIOS @url{https://www.openbios.org/}
1347 for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1348 v2) portable firmware implementation. The goal is to implement a 100%
1349 IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
1351 @c man begin OPTIONS
1353 The following options are specific to the PowerPC emulation:
1355 @table @option
1357 @item -g @var{W}x@var{H}[x@var{DEPTH}]
1359 Set the initial VGA graphic mode. The default is 800x600x32.
1361 @item -prom-env @var{string}
1363 Set OpenBIOS variables in NVRAM, for example:
1365 @example
1366 qemu-system-ppc -prom-env 'auto-boot?=false' \
1367  -prom-env 'boot-device=hd:2,\yaboot' \
1368  -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1369 @end example
1371 These variables are not used by Open Hack'Ware.
1373 @end table
1375 @c man end
1378 More information is available at
1379 @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1381 @node Sparc32 System emulator
1382 @section Sparc32 System emulator
1383 @cindex system emulation (Sparc32)
1385 Use the executable @file{qemu-system-sparc} to simulate the following
1386 Sun4m architecture machines:
1387 @itemize @minus
1388 @item
1389 SPARCstation 4
1390 @item
1391 SPARCstation 5
1392 @item
1393 SPARCstation 10
1394 @item
1395 SPARCstation 20
1396 @item
1397 SPARCserver 600MP
1398 @item
1399 SPARCstation LX
1400 @item
1401 SPARCstation Voyager
1402 @item
1403 SPARCclassic
1404 @item
1405 SPARCbook
1406 @end itemize
1408 The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1409 but Linux limits the number of usable CPUs to 4.
1411 QEMU emulates the following sun4m peripherals:
1413 @itemize @minus
1414 @item
1415 IOMMU
1416 @item
1417 TCX or cgthree Frame buffer
1418 @item
1419 Lance (Am7990) Ethernet
1420 @item
1421 Non Volatile RAM M48T02/M48T08
1422 @item
1423 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1424 and power/reset logic
1425 @item
1426 ESP SCSI controller with hard disk and CD-ROM support
1427 @item
1428 Floppy drive (not on SS-600MP)
1429 @item
1430 CS4231 sound device (only on SS-5, not working yet)
1431 @end itemize
1433 The number of peripherals is fixed in the architecture.  Maximum
1434 memory size depends on the machine type, for SS-5 it is 256MB and for
1435 others 2047MB.
1437 Since version 0.8.2, QEMU uses OpenBIOS
1438 @url{https://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1439 firmware implementation. The goal is to implement a 100% IEEE
1440 1275-1994 (referred to as Open Firmware) compliant firmware.
1442 A sample Linux 2.6 series kernel and ram disk image are available on
1443 the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1444 most kernel versions work. Please note that currently older Solaris kernels
1445 don't work probably due to interface issues between OpenBIOS and
1446 Solaris.
1448 @c man begin OPTIONS
1450 The following options are specific to the Sparc32 emulation:
1452 @table @option
1454 @item -g @var{W}x@var{H}x[x@var{DEPTH}]
1456 Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
1457 option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
1458 of 1152x900x8 for people who wish to use OBP.
1460 @item -prom-env @var{string}
1462 Set OpenBIOS variables in NVRAM, for example:
1464 @example
1465 qemu-system-sparc -prom-env 'auto-boot?=false' \
1466  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1467 @end example
1469 @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]
1471 Set the emulated machine type. Default is SS-5.
1473 @end table
1475 @c man end
1477 @node Sparc64 System emulator
1478 @section Sparc64 System emulator
1479 @cindex system emulation (Sparc64)
1481 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1482 (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1483 Niagara (T1) machine. The Sun4u emulator is mostly complete, being
1484 able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
1485 Sun4v emulator is still a work in progress.
1487 The Niagara T1 emulator makes use of firmware and OS binaries supplied in the S10image/ directory
1488 of the OpenSPARC T1 project @url{http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2}
1489 and is able to boot the disk.s10hw2 Solaris image.
1490 @example
1491 qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
1492                     -nographic -m 256 \
1493                     -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
1494 @end example
1497 QEMU emulates the following peripherals:
1499 @itemize @minus
1500 @item
1501 UltraSparc IIi APB PCI Bridge
1502 @item
1503 PCI VGA compatible card with VESA Bochs Extensions
1504 @item
1505 PS/2 mouse and keyboard
1506 @item
1507 Non Volatile RAM M48T59
1508 @item
1509 PC-compatible serial ports
1510 @item
1511 2 PCI IDE interfaces with hard disk and CD-ROM support
1512 @item
1513 Floppy disk
1514 @end itemize
1516 @c man begin OPTIONS
1518 The following options are specific to the Sparc64 emulation:
1520 @table @option
1522 @item -prom-env @var{string}
1524 Set OpenBIOS variables in NVRAM, for example:
1526 @example
1527 qemu-system-sparc64 -prom-env 'auto-boot?=false'
1528 @end example
1530 @item -M [sun4u|sun4v|niagara]
1532 Set the emulated machine type. The default is sun4u.
1534 @end table
1536 @c man end
1538 @node MIPS System emulator
1539 @section MIPS System emulator
1540 @cindex system emulation (MIPS)
1542 Four executables cover simulation of 32 and 64-bit MIPS systems in
1543 both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
1544 @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
1545 Five different machine types are emulated:
1547 @itemize @minus
1548 @item
1549 A generic ISA PC-like machine "mips"
1550 @item
1551 The MIPS Malta prototype board "malta"
1552 @item
1553 An ACER Pica "pica61". This machine needs the 64-bit emulator.
1554 @item
1555 MIPS emulator pseudo board "mipssim"
1556 @item
1557 A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
1558 @end itemize
1560 The generic emulation is supported by Debian 'Etch' and is able to
1561 install Debian into a virtual disk image. The following devices are
1562 emulated:
1564 @itemize @minus
1565 @item
1566 A range of MIPS CPUs, default is the 24Kf
1567 @item
1568 PC style serial port
1569 @item
1570 PC style IDE disk
1571 @item
1572 NE2000 network card
1573 @end itemize
1575 The Malta emulation supports the following devices:
1577 @itemize @minus
1578 @item
1579 Core board with MIPS 24Kf CPU and Galileo system controller
1580 @item
1581 PIIX4 PCI/USB/SMbus controller
1582 @item
1583 The Multi-I/O chip's serial device
1584 @item
1585 PCI network cards (PCnet32 and others)
1586 @item
1587 Malta FPGA serial device
1588 @item
1589 Cirrus (default) or any other PCI VGA graphics card
1590 @end itemize
1592 The ACER Pica emulation supports:
1594 @itemize @minus
1595 @item
1596 MIPS R4000 CPU
1597 @item
1598 PC-style IRQ and DMA controllers
1599 @item
1600 PC Keyboard
1601 @item
1602 IDE controller
1603 @end itemize
1605 The mipssim pseudo board emulation provides an environment similar
1606 to what the proprietary MIPS emulator uses for running Linux.
1607 It supports:
1609 @itemize @minus
1610 @item
1611 A range of MIPS CPUs, default is the 24Kf
1612 @item
1613 PC style serial port
1614 @item
1615 MIPSnet network emulation
1616 @end itemize
1618 The MIPS Magnum R4000 emulation supports:
1620 @itemize @minus
1621 @item
1622 MIPS R4000 CPU
1623 @item
1624 PC-style IRQ controller
1625 @item
1626 PC Keyboard
1627 @item
1628 SCSI controller
1629 @item
1630 G364 framebuffer
1631 @end itemize
1634 @node ARM System emulator
1635 @section ARM System emulator
1636 @cindex system emulation (ARM)
1638 Use the executable @file{qemu-system-arm} to simulate a ARM
1639 machine. The ARM Integrator/CP board is emulated with the following
1640 devices:
1642 @itemize @minus
1643 @item
1644 ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
1645 @item
1646 Two PL011 UARTs
1647 @item
1648 SMC 91c111 Ethernet adapter
1649 @item
1650 PL110 LCD controller
1651 @item
1652 PL050 KMI with PS/2 keyboard and mouse.
1653 @item
1654 PL181 MultiMedia Card Interface with SD card.
1655 @end itemize
1657 The ARM Versatile baseboard is emulated with the following devices:
1659 @itemize @minus
1660 @item
1661 ARM926E, ARM1136 or Cortex-A8 CPU
1662 @item
1663 PL190 Vectored Interrupt Controller
1664 @item
1665 Four PL011 UARTs
1666 @item
1667 SMC 91c111 Ethernet adapter
1668 @item
1669 PL110 LCD controller
1670 @item
1671 PL050 KMI with PS/2 keyboard and mouse.
1672 @item
1673 PCI host bridge.  Note the emulated PCI bridge only provides access to
1674 PCI memory space.  It does not provide access to PCI IO space.
1675 This means some devices (eg. ne2k_pci NIC) are not usable, and others
1676 (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
1677 mapped control registers.
1678 @item
1679 PCI OHCI USB controller.
1680 @item
1681 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
1682 @item
1683 PL181 MultiMedia Card Interface with SD card.
1684 @end itemize
1686 Several variants of the ARM RealView baseboard are emulated,
1687 including the EB, PB-A8 and PBX-A9.  Due to interactions with the
1688 bootloader, only certain Linux kernel configurations work out
1689 of the box on these boards.
1691 Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1692 enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board
1693 should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1694 disabled and expect 1024M RAM.
1696 The following devices are emulated:
1698 @itemize @minus
1699 @item
1700 ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
1701 @item
1702 ARM AMBA Generic/Distributed Interrupt Controller
1703 @item
1704 Four PL011 UARTs
1705 @item
1706 SMC 91c111 or SMSC LAN9118 Ethernet adapter
1707 @item
1708 PL110 LCD controller
1709 @item
1710 PL050 KMI with PS/2 keyboard and mouse
1711 @item
1712 PCI host bridge
1713 @item
1714 PCI OHCI USB controller
1715 @item
1716 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
1717 @item
1718 PL181 MultiMedia Card Interface with SD card.
1719 @end itemize
1721 The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
1722 and "Terrier") emulation includes the following peripherals:
1724 @itemize @minus
1725 @item
1726 Intel PXA270 System-on-chip (ARM V5TE core)
1727 @item
1728 NAND Flash memory
1729 @item
1730 IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
1731 @item
1732 On-chip OHCI USB controller
1733 @item
1734 On-chip LCD controller
1735 @item
1736 On-chip Real Time Clock
1737 @item
1738 TI ADS7846 touchscreen controller on SSP bus
1739 @item
1740 Maxim MAX1111 analog-digital converter on I@math{^2}C bus
1741 @item
1742 GPIO-connected keyboard controller and LEDs
1743 @item
1744 Secure Digital card connected to PXA MMC/SD host
1745 @item
1746 Three on-chip UARTs
1747 @item
1748 WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
1749 @end itemize
1751 The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
1752 following elements:
1754 @itemize @minus
1755 @item
1756 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1757 @item
1758 ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
1759 @item
1760 On-chip LCD controller
1761 @item
1762 On-chip Real Time Clock
1763 @item
1764 TI TSC2102i touchscreen controller / analog-digital converter / Audio
1765 CODEC, connected through MicroWire and I@math{^2}S busses
1766 @item
1767 GPIO-connected matrix keypad
1768 @item
1769 Secure Digital card connected to OMAP MMC/SD host
1770 @item
1771 Three on-chip UARTs
1772 @end itemize
1774 Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
1775 emulation supports the following elements:
1777 @itemize @minus
1778 @item
1779 Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
1780 @item
1781 RAM and non-volatile OneNAND Flash memories
1782 @item
1783 Display connected to EPSON remote framebuffer chip and OMAP on-chip
1784 display controller and a LS041y3 MIPI DBI-C controller
1785 @item
1786 TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
1787 driven through SPI bus
1788 @item
1789 National Semiconductor LM8323-controlled qwerty keyboard driven
1790 through I@math{^2}C bus
1791 @item
1792 Secure Digital card connected to OMAP MMC/SD host
1793 @item
1794 Three OMAP on-chip UARTs and on-chip STI debugging console
1795 @item
1796 A Bluetooth(R) transceiver and HCI connected to an UART
1797 @item
1798 Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
1799 TUSB6010 chip - only USB host mode is supported
1800 @item
1801 TI TMP105 temperature sensor driven through I@math{^2}C bus
1802 @item
1803 TI TWL92230C power management companion with an RTC on I@math{^2}C bus
1804 @item
1805 Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
1806 through CBUS
1807 @end itemize
1809 The Luminary Micro Stellaris LM3S811EVB emulation includes the following
1810 devices:
1812 @itemize @minus
1813 @item
1814 Cortex-M3 CPU core.
1815 @item
1816 64k Flash and 8k SRAM.
1817 @item
1818 Timers, UARTs, ADC and I@math{^2}C interface.
1819 @item
1820 OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
1821 @end itemize
1823 The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
1824 devices:
1826 @itemize @minus
1827 @item
1828 Cortex-M3 CPU core.
1829 @item
1830 256k Flash and 64k SRAM.
1831 @item
1832 Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
1833 @item
1834 OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
1835 @end itemize
1837 The Freecom MusicPal internet radio emulation includes the following
1838 elements:
1840 @itemize @minus
1841 @item
1842 Marvell MV88W8618 ARM core.
1843 @item
1844 32 MB RAM, 256 KB SRAM, 8 MB flash.
1845 @item
1846 Up to 2 16550 UARTs
1847 @item
1848 MV88W8xx8 Ethernet controller
1849 @item
1850 MV88W8618 audio controller, WM8750 CODEC and mixer
1851 @item
1852 128×64 display with brightness control
1853 @item
1854 2 buttons, 2 navigation wheels with button function
1855 @end itemize
1857 The Siemens SX1 models v1 and v2 (default) basic emulation.
1858 The emulation includes the following elements:
1860 @itemize @minus
1861 @item
1862 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1863 @item
1864 ROM and RAM memories (ROM firmware image can be loaded with -pflash)
1866 1 Flash of 16MB and 1 Flash of 8MB
1868 1 Flash of 32MB
1869 @item
1870 On-chip LCD controller
1871 @item
1872 On-chip Real Time Clock
1873 @item
1874 Secure Digital card connected to OMAP MMC/SD host
1875 @item
1876 Three on-chip UARTs
1877 @end itemize
1879 A Linux 2.6 test image is available on the QEMU web site. More
1880 information is available in the QEMU mailing-list archive.
1882 @c man begin OPTIONS
1884 The following options are specific to the ARM emulation:
1886 @table @option
1888 @item -semihosting
1889 Enable semihosting syscall emulation.
1891 On ARM this implements the "Angel" interface.
1893 Note that this allows guest direct access to the host filesystem,
1894 so should only be used with trusted guest OS.
1896 @end table
1898 @c man end
1900 @node ColdFire System emulator
1901 @section ColdFire System emulator
1902 @cindex system emulation (ColdFire)
1903 @cindex system emulation (M68K)
1905 Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
1906 The emulator is able to boot a uClinux kernel.
1908 The M5208EVB emulation includes the following devices:
1910 @itemize @minus
1911 @item
1912 MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
1913 @item
1914 Three Two on-chip UARTs.
1915 @item
1916 Fast Ethernet Controller (FEC)
1917 @end itemize
1919 The AN5206 emulation includes the following devices:
1921 @itemize @minus
1922 @item
1923 MCF5206 ColdFire V2 Microprocessor.
1924 @item
1925 Two on-chip UARTs.
1926 @end itemize
1928 @c man begin OPTIONS
1930 The following options are specific to the ColdFire emulation:
1932 @table @option
1934 @item -semihosting
1935 Enable semihosting syscall emulation.
1937 On M68K this implements the "ColdFire GDB" interface used by libgloss.
1939 Note that this allows guest direct access to the host filesystem,
1940 so should only be used with trusted guest OS.
1942 @end table
1944 @c man end
1946 @node Cris System emulator
1947 @section Cris System emulator
1948 @cindex system emulation (Cris)
1950 TODO
1952 @node Microblaze System emulator
1953 @section Microblaze System emulator
1954 @cindex system emulation (Microblaze)
1956 TODO
1958 @node SH4 System emulator
1959 @section SH4 System emulator
1960 @cindex system emulation (SH4)
1962 TODO
1964 @node Xtensa System emulator
1965 @section Xtensa System emulator
1966 @cindex system emulation (Xtensa)
1968 Two executables cover simulation of both Xtensa endian options,
1969 @file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
1970 Two different machine types are emulated:
1972 @itemize @minus
1973 @item
1974 Xtensa emulator pseudo board "sim"
1975 @item
1976 Avnet LX60/LX110/LX200 board
1977 @end itemize
1979 The sim pseudo board emulation provides an environment similar
1980 to one provided by the proprietary Tensilica ISS.
1981 It supports:
1983 @itemize @minus
1984 @item
1985 A range of Xtensa CPUs, default is the DC232B
1986 @item
1987 Console and filesystem access via semihosting calls
1988 @end itemize
1990 The Avnet LX60/LX110/LX200 emulation supports:
1992 @itemize @minus
1993 @item
1994 A range of Xtensa CPUs, default is the DC232B
1995 @item
1996 16550 UART
1997 @item
1998 OpenCores 10/100 Mbps Ethernet MAC
1999 @end itemize
2001 @c man begin OPTIONS
2003 The following options are specific to the Xtensa emulation:
2005 @table @option
2007 @item -semihosting
2008 Enable semihosting syscall emulation.
2010 Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2011 Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2013 Note that this allows guest direct access to the host filesystem,
2014 so should only be used with trusted guest OS.
2016 @end table
2018 @c man end
2020 @node QEMU Guest Agent
2021 @chapter QEMU Guest Agent invocation
2023 @include qemu-ga.texi
2025 @node QEMU User space emulator
2026 @chapter QEMU User space emulator
2028 @menu
2029 * Supported Operating Systems ::
2030 * Features::
2031 * Linux User space emulator::
2032 * BSD User space emulator ::
2033 @end menu
2035 @node Supported Operating Systems
2036 @section Supported Operating Systems
2038 The following OS are supported in user space emulation:
2040 @itemize @minus
2041 @item
2042 Linux (referred as qemu-linux-user)
2043 @item
2044 BSD (referred as qemu-bsd-user)
2045 @end itemize
2047 @node Features
2048 @section Features
2050 QEMU user space emulation has the following notable features:
2052 @table @strong
2053 @item System call translation:
2054 QEMU includes a generic system call translator.  This means that
2055 the parameters of the system calls can be converted to fix
2056 endianness and 32/64-bit mismatches between hosts and targets.
2057 IOCTLs can be converted too.
2059 @item POSIX signal handling:
2060 QEMU can redirect to the running program all signals coming from
2061 the host (such as @code{SIGALRM}), as well as synthesize signals from
2062 virtual CPU exceptions (for example @code{SIGFPE} when the program
2063 executes a division by zero).
2065 QEMU relies on the host kernel to emulate most signal system
2066 calls, for example to emulate the signal mask.  On Linux, QEMU
2067 supports both normal and real-time signals.
2069 @item Threading:
2070 On Linux, QEMU can emulate the @code{clone} syscall and create a real
2071 host thread (with a separate virtual CPU) for each emulated thread.
2072 Note that not all targets currently emulate atomic operations correctly.
2073 x86 and ARM use a global lock in order to preserve their semantics.
2074 @end table
2076 QEMU was conceived so that ultimately it can emulate itself. Although
2077 it is not very useful, it is an important test to show the power of the
2078 emulator.
2080 @node Linux User space emulator
2081 @section Linux User space emulator
2083 @menu
2084 * Quick Start::
2085 * Wine launch::
2086 * Command line options::
2087 * Other binaries::
2088 @end menu
2090 @node Quick Start
2091 @subsection Quick Start
2093 In order to launch a Linux process, QEMU needs the process executable
2094 itself and all the target (x86) dynamic libraries used by it.
2096 @itemize
2098 @item On x86, you can just try to launch any process by using the native
2099 libraries:
2101 @example
2102 qemu-i386 -L / /bin/ls
2103 @end example
2105 @code{-L /} tells that the x86 dynamic linker must be searched with a
2106 @file{/} prefix.
2108 @item Since QEMU is also a linux process, you can launch QEMU with
2109 QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
2111 @example
2112 qemu-i386 -L / qemu-i386 -L / /bin/ls
2113 @end example
2115 @item On non x86 CPUs, you need first to download at least an x86 glibc
2116 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2117 @code{LD_LIBRARY_PATH} is not set:
2119 @example
2120 unset LD_LIBRARY_PATH
2121 @end example
2123 Then you can launch the precompiled @file{ls} x86 executable:
2125 @example
2126 qemu-i386 tests/i386/ls
2127 @end example
2128 You can look at @file{scripts/qemu-binfmt-conf.sh} so that
2129 QEMU is automatically launched by the Linux kernel when you try to
2130 launch x86 executables. It requires the @code{binfmt_misc} module in the
2131 Linux kernel.
2133 @item The x86 version of QEMU is also included. You can try weird things such as:
2134 @example
2135 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2136           /usr/local/qemu-i386/bin/ls-i386
2137 @end example
2139 @end itemize
2141 @node Wine launch
2142 @subsection Wine launch
2144 @itemize
2146 @item Ensure that you have a working QEMU with the x86 glibc
2147 distribution (see previous section). In order to verify it, you must be
2148 able to do:
2150 @example
2151 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2152 @end example
2154 @item Download the binary x86 Wine install
2155 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2157 @item Configure Wine on your account. Look at the provided script
2158 @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2159 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2161 @item Then you can try the example @file{putty.exe}:
2163 @example
2164 qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2165           /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2166 @end example
2168 @end itemize
2170 @node Command line options
2171 @subsection Command line options
2173 @example
2174 @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}...]
2175 @end example
2177 @table @option
2178 @item -h
2179 Print the help
2180 @item -L path
2181 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2182 @item -s size
2183 Set the x86 stack size in bytes (default=524288)
2184 @item -cpu model
2185 Select CPU model (-cpu help for list and additional feature selection)
2186 @item -E @var{var}=@var{value}
2187 Set environment @var{var} to @var{value}.
2188 @item -U @var{var}
2189 Remove @var{var} from the environment.
2190 @item -B offset
2191 Offset guest address by the specified number of bytes.  This is useful when
2192 the address region required by guest applications is reserved on the host.
2193 This option is currently only supported on some hosts.
2194 @item -R size
2195 Pre-allocate a guest virtual address space of the given size (in bytes).
2196 "G", "M", and "k" suffixes may be used when specifying the size.
2197 @end table
2199 Debug options:
2201 @table @option
2202 @item -d item1,...
2203 Activate logging of the specified items (use '-d help' for a list of log items)
2204 @item -p pagesize
2205 Act as if the host page size was 'pagesize' bytes
2206 @item -g port
2207 Wait gdb connection to port
2208 @item -singlestep
2209 Run the emulation in single step mode.
2210 @end table
2212 Environment variables:
2214 @table @env
2215 @item QEMU_STRACE
2216 Print system calls and arguments similar to the 'strace' program
2217 (NOTE: the actual 'strace' program will not work because the user
2218 space emulator hasn't implemented ptrace).  At the moment this is
2219 incomplete.  All system calls that don't have a specific argument
2220 format are printed with information for six arguments.  Many
2221 flag-style arguments don't have decoders and will show up as numbers.
2222 @end table
2224 @node Other binaries
2225 @subsection Other binaries
2227 @cindex user mode (Alpha)
2228 @command{qemu-alpha} TODO.
2230 @cindex user mode (ARM)
2231 @command{qemu-armeb} TODO.
2233 @cindex user mode (ARM)
2234 @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2235 binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2236 configurations), and arm-uclinux bFLT format binaries.
2238 @cindex user mode (ColdFire)
2239 @cindex user mode (M68K)
2240 @command{qemu-m68k} is capable of running semihosted binaries using the BDM
2241 (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2242 coldfire uClinux bFLT format binaries.
2244 The binary format is detected automatically.
2246 @cindex user mode (Cris)
2247 @command{qemu-cris} TODO.
2249 @cindex user mode (i386)
2250 @command{qemu-i386} TODO.
2251 @command{qemu-x86_64} TODO.
2253 @cindex user mode (Microblaze)
2254 @command{qemu-microblaze} TODO.
2256 @cindex user mode (MIPS)
2257 @command{qemu-mips} TODO.
2258 @command{qemu-mipsel} TODO.
2260 @cindex user mode (NiosII)
2261 @command{qemu-nios2} TODO.
2263 @cindex user mode (PowerPC)
2264 @command{qemu-ppc64abi32} TODO.
2265 @command{qemu-ppc64} TODO.
2266 @command{qemu-ppc} TODO.
2268 @cindex user mode (SH4)
2269 @command{qemu-sh4eb} TODO.
2270 @command{qemu-sh4} TODO.
2272 @cindex user mode (SPARC)
2273 @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2275 @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2276 (Sparc64 CPU, 32 bit ABI).
2278 @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2279 SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2281 @node BSD User space emulator
2282 @section BSD User space emulator
2284 @menu
2285 * BSD Status::
2286 * BSD Quick Start::
2287 * BSD Command line options::
2288 @end menu
2290 @node BSD Status
2291 @subsection BSD Status
2293 @itemize @minus
2294 @item
2295 target Sparc64 on Sparc64: Some trivial programs work.
2296 @end itemize
2298 @node BSD Quick Start
2299 @subsection Quick Start
2301 In order to launch a BSD process, QEMU needs the process executable
2302 itself and all the target dynamic libraries used by it.
2304 @itemize
2306 @item On Sparc64, you can just try to launch any process by using the native
2307 libraries:
2309 @example
2310 qemu-sparc64 /bin/ls
2311 @end example
2313 @end itemize
2315 @node BSD Command line options
2316 @subsection Command line options
2318 @example
2319 @command{qemu-sparc64} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-bsd} @var{type}] @var{program} [@var{arguments}...]
2320 @end example
2322 @table @option
2323 @item -h
2324 Print the help
2325 @item -L path
2326 Set the library root path (default=/)
2327 @item -s size
2328 Set the stack size in bytes (default=524288)
2329 @item -ignore-environment
2330 Start with an empty environment. Without this option,
2331 the initial environment is a copy of the caller's environment.
2332 @item -E @var{var}=@var{value}
2333 Set environment @var{var} to @var{value}.
2334 @item -U @var{var}
2335 Remove @var{var} from the environment.
2336 @item -bsd type
2337 Set the type of the emulated BSD Operating system. Valid values are
2338 FreeBSD, NetBSD and OpenBSD (default).
2339 @end table
2341 Debug options:
2343 @table @option
2344 @item -d item1,...
2345 Activate logging of the specified items (use '-d help' for a list of log items)
2346 @item -p pagesize
2347 Act as if the host page size was 'pagesize' bytes
2348 @item -singlestep
2349 Run the emulation in single step mode.
2350 @end table
2353 @include qemu-tech.texi
2355 @node Deprecated features
2356 @appendix Deprecated features
2358 In general features are intended to be supported indefinitely once
2359 introduced into QEMU. In the event that a feature needs to be removed,
2360 it will be listed in this appendix. The feature will remain functional
2361 for 2 releases prior to actual removal. Deprecated features may also
2362 generate warnings on the console when QEMU starts up, or if activated
2363 via a monitor command, however, this is not a mandatory requirement.
2365 Prior to the 2.10.0 release there was no official policy on how
2366 long features would be deprecated prior to their removal, nor
2367 any documented list of which features were deprecated. Thus
2368 any features deprecated prior to 2.10.0 will be treated as if
2369 they were first deprecated in the 2.10.0 release.
2371 What follows is a list of all features currently marked as
2372 deprecated.
2374 @section System emulator command line arguments
2376 @subsection -drive boot=on|off (since 1.3.0)
2378 The ``boot=on|off'' option to the ``-drive'' argument is
2379 ignored. Applications should use the ``bootindex=N'' parameter
2380 to set an absolute ordering between devices instead.
2382 @subsection -tdf (since 1.3.0)
2384 The ``-tdf'' argument is ignored. The behaviour implemented
2385 by this argument is now the default when using the KVM PIT,
2386 but can be requested explicitly using
2387 ``-global kvm-pit.lost_tick_policy=slew''.
2389 @subsection -no-kvm-pit-reinjection (since 1.3.0)
2391 The ``-no-kvm-pit-reinjection'' argument is now a
2392 synonym for setting ``-global kvm-pit.lost_tick_policy=discard''.
2394 @subsection -no-kvm-irqchip (since 1.3.0)
2396 The ``-no-kvm-irqchip'' argument is now a synonym for
2397 setting ``-machine kernel_irqchip=off''.
2399 @subsection -no-kvm-pit (since 1.3.0)
2401 The ``-no-kvm-pit'' argument is ignored. It is no longer
2402 possible to disable the KVM PIT directly.
2404 @subsection -no-kvm (since 1.3.0)
2406 The ``-no-kvm'' argument is now a synonym for setting
2407 ``-machine accel=tcg''.
2409 @subsection -mon default=on (since 2.4.0)
2411 The ``default'' option to the ``-mon'' argument is
2412 now ignored. When multiple monitors were enabled, it
2413 indicated which monitor would receive log messages
2414 from the various subsystems. This feature is no longer
2415 required as messages are now only sent to the monitor
2416 in response to explicitly monitor commands.
2418 @subsection -vnc tls (since 2.5.0)
2420 The ``-vnc tls'' argument is now a synonym for setting
2421 ``-object tls-creds-anon,id=tls0'' combined with
2422 ``-vnc tls-creds=tls0'
2424 @subsection -vnc x509 (since 2.5.0)
2426 The ``-vnc x509=/path/to/certs'' argument is now a
2427 synonym for setting
2428 ``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=no''
2429 combined with ``-vnc tls-creds=tls0'
2431 @subsection -vnc x509verify (since 2.5.0)
2433 The ``-vnc x509verify=/path/to/certs'' argument is now a
2434 synonym for setting
2435 ``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=yes''
2436 combined with ``-vnc tls-creds=tls0'
2438 @subsection -tftp (since 2.6.0)
2440 The ``-tftp /some/dir'' argument is now a synonym for setting
2441 the ``-netdev user,tftp=/some/dir' argument. The new syntax
2442 allows different settings to be provided per NIC.
2444 @subsection -bootp (since 2.6.0)
2446 The ``-bootp /some/file'' argument is now a synonym for setting
2447 the ``-netdev user,bootp=/some/file' argument. The new syntax
2448 allows different settings to be provided per NIC.
2450 @subsection -redir (since 2.6.0)
2452 The ``-redir ARGS'' argument is now a synonym for setting
2453 the ``-netdev user,hostfwd=ARGS'' argument instead. The new
2454 syntax allows different settings to be provided per NIC.
2456 @subsection -smb (since 2.6.0)
2458 The ``-smb /some/dir'' argument is now a synonym for setting
2459 the ``-netdev user,smb=/some/dir'' argument instead. The new
2460 syntax allows different settings to be provided per NIC.
2462 @subsection -net channel (since 2.6.0)
2464 The ``--net channel,ARGS'' argument is now a synonym for setting
2465 the ``-netdev user,guestfwd=ARGS'' argument instead.
2467 @subsection -net vlan (since 2.9.0)
2469 The ``-net vlan=NN'' argument is partially replaced with the
2470 new ``-netdev'' argument. The remaining use cases will no
2471 longer be directly supported in QEMU.
2473 @subsection -drive if=scsi (since 2.9.0)
2475 The ``-drive if=scsi'' argument is replaced by the the
2476 ``-device BUS-TYPE'' argument combined with ``-drive if=none''.
2478 @subsection -net dump (since 2.10.0)
2480 The ``--net dump'' argument is now replaced with the
2481 ``-object filter-dump'' argument which works in combination
2482 with the modern ``-netdev`` backends instead.
2484 @subsection -hdachs (since 2.10.0)
2486 The ``-hdachs'' argument is now a synonym for setting
2487 the ``cyls'', ``heads'', ``secs'', and ``trans'' properties
2488 on the ``ide-hd'' device using the ``-device'' argument.
2489 The new syntax allows different settings to be provided
2490 per disk.
2492 @subsection -usbdevice (since 2.10.0)
2494 The ``-usbdevice DEV'' argument is now a synonym for setting
2495 the ``-device usb-DEV'' argument instead. The deprecated syntax
2496 would automatically enable USB support on the machine type.
2497 If using the new syntax, USB support must be explicitly
2498 enabled via the ``-machine usb=on'' argument.
2500 @subsection -nodefconfig (since 2.11.0)
2502 The ``-nodefconfig`` argument is a synonym for ``-no-user-config``.
2504 @section qemu-img command line arguments
2506 @subsection convert -s (since 2.0.0)
2508 The ``convert -s snapshot_id_or_name'' argument is obsoleted
2509 by the ``convert -l snapshot_param'' argument instead.
2511 @section System emulator human monitor commands
2513 @subsection host_net_add (since 2.10.0)
2515 The ``host_net_add'' command is replaced by the ``netdev_add'' command.
2517 @subsection host_net_remove (since 2.10.0)
2519 The ``host_net_remove'' command is replaced by the ``netdev_del'' command.
2521 @subsection usb_add (since 2.10.0)
2523 The ``usb_add'' command is replaced by the ``device_add'' command.
2525 @subsection usb_del (since 2.10.0)
2527 The ``usb_del'' command is replaced by the ``device_del'' command.
2529 @section System emulator devices
2531 @subsection ivshmem (since 2.6.0)
2533 The ``ivshmem'' device type is replaced by either the ``ivshmem-plain''
2534 or ``ivshmem-doorbell`` device types.
2536 @subsection spapr-pci-vfio-host-bridge (since 2.6.0)
2538 The ``spapr-pci-vfio-host-bridge'' device type is replaced by
2539 the ``spapr-pci-host-bridge'' device type.
2541 @section System emulator machines
2543 @subsection Xilinx EP108 (since 2.11.0)
2545 The ``xlnx-ep108'' machine has been replaced by the ``xlnx-zcu102'' machine.
2546 The ``xlnx-zcu102'' machine has the same features and capabilites in QEMU.
2548 @node License
2549 @appendix License
2551 QEMU is a trademark of Fabrice Bellard.
2553 QEMU is released under the
2554 @url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
2555 version 2. Parts of QEMU have specific licenses, see file
2556 @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
2558 @node Index
2559 @appendix Index
2560 @menu
2561 * Concept Index::
2562 * Function Index::
2563 * Keystroke Index::
2564 * Program Index::
2565 * Data Type Index::
2566 * Variable Index::
2567 @end menu
2569 @node Concept Index
2570 @section Concept Index
2571 This is the main index. Should we combine all keywords in one index? TODO
2572 @printindex cp
2574 @node Function Index
2575 @section Function Index
2576 This index could be used for command line options and monitor functions.
2577 @printindex fn
2579 @node Keystroke Index
2580 @section Keystroke Index
2582 This is a list of all keystrokes which have a special function
2583 in system emulation.
2585 @printindex ky
2587 @node Program Index
2588 @section Program Index
2589 @printindex pg
2591 @node Data Type Index
2592 @section Data Type Index
2594 This index could be used for qdev device names and options.
2596 @printindex tp
2598 @node Variable Index
2599 @section Variable Index
2600 @printindex vr
2602 @bye