s390x/tcg: initialize machine check queue
[qemu/ar7.git] / qemu-doc.texi
blobecd186a15973fc82023d1de99294f4c61c4d9dfa
1 \input texinfo @c -*- texinfo -*-
2 @c %**start of header
3 @setfilename qemu-doc.info
4 @include version.texi
6 @documentlanguage en
7 @documentencoding UTF-8
9 @settitle QEMU version @value{VERSION} User Documentation
10 @exampleindent 0
11 @paragraphindent 0
12 @c %**end of header
14 @ifinfo
15 @direntry
16 * QEMU: (qemu-doc).    The QEMU Emulator User Documentation.
17 @end direntry
18 @end ifinfo
20 @iftex
21 @titlepage
22 @sp 7
23 @center @titlefont{QEMU version @value{VERSION}}
24 @sp 1
25 @center @titlefont{User Documentation}
26 @sp 3
27 @end titlepage
28 @end iftex
30 @ifnottex
31 @node Top
32 @top
34 @menu
35 * Introduction::
36 * QEMU PC System emulator::
37 * QEMU System emulator for non PC targets::
38 * QEMU Guest Agent::
39 * QEMU User space emulator::
40 * Implementation notes::
41 * Deprecated features::
42 * License::
43 * Index::
44 @end menu
45 @end ifnottex
47 @contents
49 @node Introduction
50 @chapter Introduction
52 @menu
53 * intro_features:: Features
54 @end menu
56 @node intro_features
57 @section Features
59 QEMU is a FAST! processor emulator using dynamic translation to
60 achieve good emulation speed.
62 @cindex operating modes
63 QEMU has two operating modes:
65 @itemize
66 @cindex system emulation
67 @item Full system emulation. In this mode, QEMU emulates a full system (for
68 example a PC), including one or several processors and various
69 peripherals. It can be used to launch different Operating Systems
70 without rebooting the PC or to debug system code.
72 @cindex user mode emulation
73 @item User mode emulation. In this mode, QEMU can launch
74 processes compiled for one CPU on another CPU. It can be used to
75 launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
76 to ease cross-compilation and cross-debugging.
78 @end itemize
80 QEMU has the following features:
82 @itemize
83 @item QEMU can run without a host kernel driver and yet gives acceptable
84 performance.  It uses dynamic translation to native code for reasonable speed,
85 with support for self-modifying code and precise exceptions.
87 @item It is portable to several operating systems (GNU/Linux, *BSD, Mac OS X,
88 Windows) and architectures.
90 @item It performs accurate software emulation of the FPU.
91 @end itemize
93 QEMU user mode emulation has the following features:
94 @itemize
95 @item Generic Linux system call converter, including most ioctls.
97 @item clone() emulation using native CPU clone() to use Linux scheduler for threads.
99 @item Accurate signal handling by remapping host signals to target signals.
100 @end itemize
102 QEMU full system emulation has the following features:
103 @itemize
104 @item
105 QEMU uses a full software MMU for maximum portability.
107 @item
108 QEMU can optionally use an in-kernel accelerator, like kvm. The accelerators 
109 execute most of the guest code natively, while
110 continuing to emulate the rest of the machine.
112 @item
113 Various hardware devices can be emulated and in some cases, host
114 devices (e.g. serial and parallel ports, USB, drives) can be used
115 transparently by the guest Operating System. Host device passthrough
116 can be used for talking to external physical peripherals (e.g. a
117 webcam, modem or tape drive).
119 @item
120 Symmetric multiprocessing (SMP) support.  Currently, an in-kernel
121 accelerator is required to use more than one host CPU for emulation.
123 @end itemize
126 @node QEMU PC System emulator
127 @chapter QEMU PC System emulator
128 @cindex system emulation (PC)
130 @menu
131 * pcsys_introduction:: Introduction
132 * pcsys_quickstart::   Quick Start
133 * sec_invocation::     Invocation
134 * pcsys_keys::         Keys in the graphical frontends
135 * mux_keys::           Keys in the character backend multiplexer
136 * pcsys_monitor::      QEMU Monitor
137 * disk_images::        Disk Images
138 * pcsys_network::      Network emulation
139 * pcsys_other_devs::   Other Devices
140 * direct_linux_boot::  Direct Linux Boot
141 * pcsys_usb::          USB emulation
142 * vnc_security::       VNC security
143 * gdb_usage::          GDB usage
144 * pcsys_os_specific::  Target OS specific information
145 @end menu
147 @node pcsys_introduction
148 @section Introduction
150 @c man begin DESCRIPTION
152 The QEMU PC System emulator simulates the
153 following peripherals:
155 @itemize @minus
156 @item
157 i440FX host PCI bridge and PIIX3 PCI to ISA bridge
158 @item
159 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
160 extensions (hardware level, including all non standard modes).
161 @item
162 PS/2 mouse and keyboard
163 @item
164 2 PCI IDE interfaces with hard disk and CD-ROM support
165 @item
166 Floppy disk
167 @item
168 PCI and ISA network adapters
169 @item
170 Serial ports
171 @item
172 IPMI BMC, either and internal or external one
173 @item
174 Creative SoundBlaster 16 sound card
175 @item
176 ENSONIQ AudioPCI ES1370 sound card
177 @item
178 Intel 82801AA AC97 Audio compatible sound card
179 @item
180 Intel HD Audio Controller and HDA codec
181 @item
182 Adlib (OPL2) - Yamaha YM3812 compatible chip
183 @item
184 Gravis Ultrasound GF1 sound card
185 @item
186 CS4231A compatible sound card
187 @item
188 PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.
189 @end itemize
191 SMP is supported with up to 255 CPUs.
193 QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
194 VGA BIOS.
196 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
198 QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
199 by Tibor "TS" Schütz.
201 Note that, by default, GUS shares IRQ(7) with parallel ports and so
202 QEMU must be told to not have parallel ports to have working GUS.
204 @example
205 qemu-system-i386 dos.img -soundhw gus -parallel none
206 @end example
208 Alternatively:
209 @example
210 qemu-system-i386 dos.img -device gus,irq=5
211 @end example
213 Or some other unclaimed IRQ.
215 CS4231A is the chip used in Windows Sound System and GUSMAX products
217 @c man end
219 @node pcsys_quickstart
220 @section Quick Start
221 @cindex quick start
223 Download and uncompress the linux image (@file{linux.img}) and type:
225 @example
226 qemu-system-i386 linux.img
227 @end example
229 Linux should boot and give you a prompt.
231 @node sec_invocation
232 @section Invocation
234 @example
235 @c man begin SYNOPSIS
236 @command{qemu-system-i386} [@var{options}] [@var{disk_image}]
237 @c man end
238 @end example
240 @c man begin OPTIONS
241 @var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
242 targets do not need a disk image.
244 @include qemu-options.texi
246 @c man end
248 @node pcsys_keys
249 @section Keys in the graphical frontends
251 @c man begin OPTIONS
253 During the graphical emulation, you can use special key combinations to change
254 modes. The default key mappings are shown below, but if you use @code{-alt-grab}
255 then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
256 @code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
258 @table @key
259 @item Ctrl-Alt-f
260 @kindex Ctrl-Alt-f
261 Toggle full screen
263 @item Ctrl-Alt-+
264 @kindex Ctrl-Alt-+
265 Enlarge the screen
267 @item Ctrl-Alt--
268 @kindex Ctrl-Alt--
269 Shrink the screen
271 @item Ctrl-Alt-u
272 @kindex Ctrl-Alt-u
273 Restore the screen's un-scaled dimensions
275 @item Ctrl-Alt-n
276 @kindex Ctrl-Alt-n
277 Switch to virtual console 'n'. Standard console mappings are:
278 @table @emph
279 @item 1
280 Target system display
281 @item 2
282 Monitor
283 @item 3
284 Serial port
285 @end table
287 @item Ctrl-Alt
288 @kindex Ctrl-Alt
289 Toggle mouse and keyboard grab.
290 @end table
292 @kindex Ctrl-Up
293 @kindex Ctrl-Down
294 @kindex Ctrl-PageUp
295 @kindex Ctrl-PageDown
296 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
297 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
299 @c man end
301 @node mux_keys
302 @section Keys in the character backend multiplexer
304 @c man begin OPTIONS
306 During emulation, if you are using a character backend multiplexer
307 (which is the default if you are using @option{-nographic}) then
308 several commands are available via an escape sequence. These
309 key sequences all start with an escape character, which is @key{Ctrl-a}
310 by default, but can be changed with @option{-echr}. The list below assumes
311 you're using the default.
313 @table @key
314 @item Ctrl-a h
315 @kindex Ctrl-a h
316 Print this help
317 @item Ctrl-a x
318 @kindex Ctrl-a x
319 Exit emulator
320 @item Ctrl-a s
321 @kindex Ctrl-a s
322 Save disk data back to file (if -snapshot)
323 @item Ctrl-a t
324 @kindex Ctrl-a t
325 Toggle console timestamps
326 @item Ctrl-a b
327 @kindex Ctrl-a b
328 Send break (magic sysrq in Linux)
329 @item Ctrl-a c
330 @kindex Ctrl-a c
331 Rotate between the frontends connected to the multiplexer (usually
332 this switches between the monitor and the console)
333 @item Ctrl-a Ctrl-a
334 @kindex Ctrl-a Ctrl-a
335 Send the escape character to the frontend
336 @end table
337 @c man end
339 @ignore
341 @c man begin SEEALSO
342 The HTML documentation of QEMU for more precise information and Linux
343 user mode emulator invocation.
344 @c man end
346 @c man begin AUTHOR
347 Fabrice Bellard
348 @c man end
350 @end ignore
352 @node pcsys_monitor
353 @section QEMU Monitor
354 @cindex QEMU monitor
356 The QEMU monitor is used to give complex commands to the QEMU
357 emulator. You can use it to:
359 @itemize @minus
361 @item
362 Remove or insert removable media images
363 (such as CD-ROM or floppies).
365 @item
366 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
367 from a disk file.
369 @item Inspect the VM state without an external debugger.
371 @end itemize
373 @subsection Commands
375 The following commands are available:
377 @include qemu-monitor.texi
379 @include qemu-monitor-info.texi
381 @subsection Integer expressions
383 The monitor understands integers expressions for every integer
384 argument. You can use register names to get the value of specifics
385 CPU registers by prefixing them with @emph{$}.
387 @node disk_images
388 @section Disk Images
390 QEMU supports many disk image formats, including growable disk images
391 (their size increase as non empty sectors are written), compressed and
392 encrypted disk images.
394 @menu
395 * disk_images_quickstart::    Quick start for disk image creation
396 * disk_images_snapshot_mode:: Snapshot mode
397 * vm_snapshots::              VM snapshots
398 * qemu_img_invocation::       qemu-img Invocation
399 * qemu_nbd_invocation::       qemu-nbd Invocation
400 * disk_images_formats::       Disk image file formats
401 * host_drives::               Using host drives
402 * disk_images_fat_images::    Virtual FAT disk images
403 * disk_images_nbd::           NBD access
404 * disk_images_sheepdog::      Sheepdog disk images
405 * disk_images_iscsi::         iSCSI LUNs
406 * disk_images_gluster::       GlusterFS disk images
407 * disk_images_ssh::           Secure Shell (ssh) disk images
408 @end menu
410 @node disk_images_quickstart
411 @subsection Quick start for disk image creation
413 You can create a disk image with the command:
414 @example
415 qemu-img create myimage.img mysize
416 @end example
417 where @var{myimage.img} is the disk image filename and @var{mysize} is its
418 size in kilobytes. You can add an @code{M} suffix to give the size in
419 megabytes and a @code{G} suffix for gigabytes.
421 See @ref{qemu_img_invocation} for more information.
423 @node disk_images_snapshot_mode
424 @subsection Snapshot mode
426 If you use the option @option{-snapshot}, all disk images are
427 considered as read only. When sectors in written, they are written in
428 a temporary file created in @file{/tmp}. You can however force the
429 write back to the raw disk images by using the @code{commit} monitor
430 command (or @key{C-a s} in the serial console).
432 @node vm_snapshots
433 @subsection VM snapshots
435 VM snapshots are snapshots of the complete virtual machine including
436 CPU state, RAM, device state and the content of all the writable
437 disks. In order to use VM snapshots, you must have at least one non
438 removable and writable block device using the @code{qcow2} disk image
439 format. Normally this device is the first virtual hard drive.
441 Use the monitor command @code{savevm} to create a new VM snapshot or
442 replace an existing one. A human readable name can be assigned to each
443 snapshot in addition to its numerical ID.
445 Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
446 a VM snapshot. @code{info snapshots} lists the available snapshots
447 with their associated information:
449 @example
450 (qemu) info snapshots
451 Snapshot devices: hda
452 Snapshot list (from hda):
453 ID        TAG                 VM SIZE                DATE       VM CLOCK
454 1         start                   41M 2006-08-06 12:38:02   00:00:14.954
455 2                                 40M 2006-08-06 12:43:29   00:00:18.633
456 3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
457 @end example
459 A VM snapshot is made of a VM state info (its size is shown in
460 @code{info snapshots}) and a snapshot of every writable disk image.
461 The VM state info is stored in the first @code{qcow2} non removable
462 and writable block device. The disk image snapshots are stored in
463 every disk image. The size of a snapshot in a disk image is difficult
464 to evaluate and is not shown by @code{info snapshots} because the
465 associated disk sectors are shared among all the snapshots to save
466 disk space (otherwise each snapshot would need a full copy of all the
467 disk images).
469 When using the (unrelated) @code{-snapshot} option
470 (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
471 but they are deleted as soon as you exit QEMU.
473 VM snapshots currently have the following known limitations:
474 @itemize
475 @item
476 They cannot cope with removable devices if they are removed or
477 inserted after a snapshot is done.
478 @item
479 A few device drivers still have incomplete snapshot support so their
480 state is not saved or restored properly (in particular USB).
481 @end itemize
483 @node qemu_img_invocation
484 @subsection @code{qemu-img} Invocation
486 @include qemu-img.texi
488 @node qemu_nbd_invocation
489 @subsection @code{qemu-nbd} Invocation
491 @include qemu-nbd.texi
493 @include docs/qemu-block-drivers.texi
495 @node pcsys_network
496 @section Network emulation
498 QEMU can simulate several network cards (PCI or ISA cards on the PC
499 target) and can connect them to an arbitrary number of Virtual Local
500 Area Networks (VLANs). Host TAP devices can be connected to any QEMU
501 VLAN. VLAN can be connected between separate instances of QEMU to
502 simulate large networks. For simpler usage, a non privileged user mode
503 network stack can replace the TAP device to have a basic network
504 connection.
506 @subsection VLANs
508 QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
509 connection between several network devices. These devices can be for
510 example QEMU virtual Ethernet cards or virtual Host ethernet devices
511 (TAP devices).
513 @subsection Using TAP network interfaces
515 This is the standard way to connect QEMU to a real network. QEMU adds
516 a virtual network device on your host (called @code{tapN}), and you
517 can then configure it as if it was a real ethernet card.
519 @subsubsection Linux host
521 As an example, you can download the @file{linux-test-xxx.tar.gz}
522 archive and copy the script @file{qemu-ifup} in @file{/etc} and
523 configure properly @code{sudo} so that the command @code{ifconfig}
524 contained in @file{qemu-ifup} can be executed as root. You must verify
525 that your host kernel supports the TAP network interfaces: the
526 device @file{/dev/net/tun} must be present.
528 See @ref{sec_invocation} to have examples of command lines using the
529 TAP network interfaces.
531 @subsubsection Windows host
533 There is a virtual ethernet driver for Windows 2000/XP systems, called
534 TAP-Win32. But it is not included in standard QEMU for Windows,
535 so you will need to get it separately. It is part of OpenVPN package,
536 so download OpenVPN from : @url{http://openvpn.net/}.
538 @subsection Using the user mode network stack
540 By using the option @option{-net user} (default configuration if no
541 @option{-net} option is specified), QEMU uses a completely user mode
542 network stack (you don't need root privilege to use the virtual
543 network). The virtual network configuration is the following:
545 @example
547          QEMU VLAN      <------>  Firewall/DHCP server <-----> Internet
548                            |          (10.0.2.2)
549                            |
550                            ---->  DNS server (10.0.2.3)
551                            |
552                            ---->  SMB server (10.0.2.4)
553 @end example
555 The QEMU VM behaves as if it was behind a firewall which blocks all
556 incoming connections. You can use a DHCP client to automatically
557 configure the network in the QEMU VM. The DHCP server assign addresses
558 to the hosts starting from 10.0.2.15.
560 In order to check that the user mode network is working, you can ping
561 the address 10.0.2.2 and verify that you got an address in the range
562 10.0.2.x from the QEMU virtual DHCP server.
564 Note that ICMP traffic in general does not work with user mode networking.
565 @code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
566 however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
567 ping sockets to allow @code{ping} to the Internet. The host admin has to set
568 the ping_group_range in order to grant access to those sockets. To allow ping
569 for GID 100 (usually users group):
571 @example
572 echo 100 100 > /proc/sys/net/ipv4/ping_group_range
573 @end example
575 When using the built-in TFTP server, the router is also the TFTP
576 server.
578 When using the @option{'-netdev user,hostfwd=...'} option, TCP or UDP
579 connections can be redirected from the host to the guest. It allows for
580 example to redirect X11, telnet or SSH connections.
582 @subsection Connecting VLANs between QEMU instances
584 Using the @option{-net socket} option, it is possible to make VLANs
585 that span several QEMU instances. See @ref{sec_invocation} to have a
586 basic example.
588 @node pcsys_other_devs
589 @section Other Devices
591 @subsection Inter-VM Shared Memory device
593 On Linux hosts, a shared memory device is available.  The basic syntax
596 @example
597 qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem}
598 @end example
600 where @var{hostmem} names a host memory backend.  For a POSIX shared
601 memory backend, use something like
603 @example
604 -object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
605 @end example
607 If desired, interrupts can be sent between guest VMs accessing the same shared
608 memory region.  Interrupt support requires using a shared memory server and
609 using a chardev socket to connect to it.  The code for the shared memory server
610 is qemu.git/contrib/ivshmem-server.  An example syntax when using the shared
611 memory server is:
613 @example
614 # First start the ivshmem server once and for all
615 ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}
617 # Then start your qemu instances with matching arguments
618 qemu-system-x86_64 -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
619                  -chardev socket,path=@var{path},id=@var{id}
620 @end example
622 When using the server, the guest will be assigned a VM ID (>=0) that allows guests
623 using the same server to communicate via interrupts.  Guests can read their
624 VM ID from a device register (see ivshmem-spec.txt).
626 @subsubsection Migration with ivshmem
628 With device property @option{master=on}, the guest will copy the shared
629 memory on migration to the destination host.  With @option{master=off},
630 the guest will not be able to migrate with the device attached.  In the
631 latter case, the device should be detached and then reattached after
632 migration using the PCI hotplug support.
634 At most one of the devices sharing the same memory can be master.  The
635 master must complete migration before you plug back the other devices.
637 @subsubsection ivshmem and hugepages
639 Instead of specifying the <shm size> using POSIX shm, you may specify
640 a memory backend that has hugepage support:
642 @example
643 qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
644                  -device ivshmem-plain,memdev=mb1
645 @end example
647 ivshmem-server also supports hugepages mount points with the
648 @option{-m} memory path argument.
650 @node direct_linux_boot
651 @section Direct Linux Boot
653 This section explains how to launch a Linux kernel inside QEMU without
654 having to make a full bootable image. It is very useful for fast Linux
655 kernel testing.
657 The syntax is:
658 @example
659 qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
660 @end example
662 Use @option{-kernel} to provide the Linux kernel image and
663 @option{-append} to give the kernel command line arguments. The
664 @option{-initrd} option can be used to provide an INITRD image.
666 When using the direct Linux boot, a disk image for the first hard disk
667 @file{hda} is required because its boot sector is used to launch the
668 Linux kernel.
670 If you do not need graphical output, you can disable it and redirect
671 the virtual serial port and the QEMU monitor to the console with the
672 @option{-nographic} option. The typical command line is:
673 @example
674 qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
675                  -append "root=/dev/hda console=ttyS0" -nographic
676 @end example
678 Use @key{Ctrl-a c} to switch between the serial console and the
679 monitor (@pxref{pcsys_keys}).
681 @node pcsys_usb
682 @section USB emulation
684 QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
685 plug virtual USB devices or real host USB devices (only works with certain
686 host operating systems). QEMU will automatically create and connect virtual
687 USB hubs as necessary to connect multiple USB devices.
689 @menu
690 * usb_devices::
691 * host_usb_devices::
692 @end menu
693 @node usb_devices
694 @subsection Connecting USB devices
696 USB devices can be connected with the @option{-device usb-...} command line
697 option or the @code{device_add} monitor command. Available devices are:
699 @table @code
700 @item usb-mouse
701 Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
702 @item usb-tablet
703 Pointer device that uses absolute coordinates (like a touchscreen).
704 This means QEMU is able to report the mouse position without having
705 to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
706 @item usb-storage,drive=@var{drive_id}
707 Mass storage device backed by @var{drive_id} (@pxref{disk_images})
708 @item usb-uas
709 USB attached SCSI device, see
710 @url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
711 for details
712 @item usb-bot
713 Bulk-only transport storage device, see
714 @url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
715 for details here, too
716 @item usb-mtp,x-root=@var{dir}
717 Media transfer protocol device, using @var{dir} as root of the file tree
718 that is presented to the guest.
719 @item usb-host,hostbus=@var{bus},hostaddr=@var{addr}
720 Pass through the host device identified by @var{bus} and @var{addr}
721 @item usb-host,vendorid=@var{vendor},productid=@var{product}
722 Pass through the host device identified by @var{vendor} and @var{product} ID
723 @item usb-wacom-tablet
724 Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
725 above but it can be used with the tslib library because in addition to touch
726 coordinates it reports touch pressure.
727 @item usb-kbd
728 Standard USB keyboard.  Will override the PS/2 keyboard (if present).
729 @item usb-serial,chardev=@var{id}
730 Serial converter. This emulates an FTDI FT232BM chip connected to host character
731 device @var{id}.
732 @item usb-braille,chardev=@var{id}
733 Braille device.  This will use BrlAPI to display the braille output on a real
734 or fake device referenced by @var{id}.
735 @item usb-net[,netdev=@var{id}]
736 Network adapter that supports CDC ethernet and RNDIS protocols.  @var{id}
737 specifies a netdev defined with @code{-netdev @dots{},id=@var{id}}.
738 For instance, user-mode networking can be used with
739 @example
740 qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
741 @end example
742 @item usb-ccid
743 Smartcard reader device
744 @item usb-audio
745 USB audio device
746 @item usb-bt-dongle
747 Bluetooth dongle for the transport layer of HCI. It is connected to HCI
748 scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}).
749 Note that the syntax for the @code{-device usb-bt-dongle} option is not as
750 useful yet as it was with the legacy @code{-usbdevice} option. So to
751 configure an USB bluetooth device, you might need to use
752 "@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a
753 bluetooth dongle whose type is specified in the same format as with
754 the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
755 no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
756 This USB device implements the USB Transport Layer of HCI.  Example
757 usage:
758 @example
759 @command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3
760 @end example
761 @end table
763 @node host_usb_devices
764 @subsection Using host USB devices on a Linux host
766 WARNING: this is an experimental feature. QEMU will slow down when
767 using it. USB devices requiring real time streaming (i.e. USB Video
768 Cameras) are not supported yet.
770 @enumerate
771 @item If you use an early Linux 2.4 kernel, verify that no Linux driver
772 is actually using the USB device. A simple way to do that is simply to
773 disable the corresponding kernel module by renaming it from @file{mydriver.o}
774 to @file{mydriver.o.disabled}.
776 @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
777 @example
778 ls /proc/bus/usb
779 001  devices  drivers
780 @end example
782 @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:
783 @example
784 chown -R myuid /proc/bus/usb
785 @end example
787 @item Launch QEMU and do in the monitor:
788 @example
789 info usbhost
790   Device 1.2, speed 480 Mb/s
791     Class 00: USB device 1234:5678, USB DISK
792 @end example
793 You should see the list of the devices you can use (Never try to use
794 hubs, it won't work).
796 @item Add the device in QEMU by using:
797 @example
798 device_add usb-host,vendorid=0x1234,productid=0x5678
799 @end example
801 Normally the guest OS should report that a new USB device is plugged.
802 You can use the option @option{-device usb-host,...} to do the same.
804 @item Now you can try to use the host USB device in QEMU.
806 @end enumerate
808 When relaunching QEMU, you may have to unplug and plug again the USB
809 device to make it work again (this is a bug).
811 @node vnc_security
812 @section VNC security
814 The VNC server capability provides access to the graphical console
815 of the guest VM across the network. This has a number of security
816 considerations depending on the deployment scenarios.
818 @menu
819 * vnc_sec_none::
820 * vnc_sec_password::
821 * vnc_sec_certificate::
822 * vnc_sec_certificate_verify::
823 * vnc_sec_certificate_pw::
824 * vnc_sec_sasl::
825 * vnc_sec_certificate_sasl::
826 * vnc_generate_cert::
827 * vnc_setup_sasl::
828 @end menu
829 @node vnc_sec_none
830 @subsection Without passwords
832 The simplest VNC server setup does not include any form of authentication.
833 For this setup it is recommended to restrict it to listen on a UNIX domain
834 socket only. For example
836 @example
837 qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
838 @end example
840 This ensures that only users on local box with read/write access to that
841 path can access the VNC server. To securely access the VNC server from a
842 remote machine, a combination of netcat+ssh can be used to provide a secure
843 tunnel.
845 @node vnc_sec_password
846 @subsection With passwords
848 The VNC protocol has limited support for password based authentication. Since
849 the protocol limits passwords to 8 characters it should not be considered
850 to provide high security. The password can be fairly easily brute-forced by
851 a client making repeat connections. For this reason, a VNC server using password
852 authentication should be restricted to only listen on the loopback interface
853 or UNIX domain sockets. Password authentication is not supported when operating
854 in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
855 authentication is requested with the @code{password} option, and then once QEMU
856 is running the password is set with the monitor. Until the monitor is used to
857 set the password all clients will be rejected.
859 @example
860 qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
861 (qemu) change vnc password
862 Password: ********
863 (qemu)
864 @end example
866 @node vnc_sec_certificate
867 @subsection With x509 certificates
869 The QEMU VNC server also implements the VeNCrypt extension allowing use of
870 TLS for encryption of the session, and x509 certificates for authentication.
871 The use of x509 certificates is strongly recommended, because TLS on its
872 own is susceptible to man-in-the-middle attacks. Basic x509 certificate
873 support provides a secure session, but no authentication. This allows any
874 client to connect, and provides an encrypted session.
876 @example
877 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
878 @end example
880 In the above example @code{/etc/pki/qemu} should contain at least three files,
881 @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
882 users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
883 NB the @code{server-key.pem} file should be protected with file mode 0600 to
884 only be readable by the user owning it.
886 @node vnc_sec_certificate_verify
887 @subsection With x509 certificates and client verification
889 Certificates can also provide a means to authenticate the client connecting.
890 The server will request that the client provide a certificate, which it will
891 then validate against the CA certificate. This is a good choice if deploying
892 in an environment with a private internal certificate authority.
894 @example
895 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
896 @end example
899 @node vnc_sec_certificate_pw
900 @subsection With x509 certificates, client verification and passwords
902 Finally, the previous method can be combined with VNC password authentication
903 to provide two layers of authentication for clients.
905 @example
906 qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
907 (qemu) change vnc password
908 Password: ********
909 (qemu)
910 @end example
913 @node vnc_sec_sasl
914 @subsection With SASL authentication
916 The SASL authentication method is a VNC extension, that provides an
917 easily extendable, pluggable authentication method. This allows for
918 integration with a wide range of authentication mechanisms, such as
919 PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
920 The strength of the authentication depends on the exact mechanism
921 configured. If the chosen mechanism also provides a SSF layer, then
922 it will encrypt the datastream as well.
924 Refer to the later docs on how to choose the exact SASL mechanism
925 used for authentication, but assuming use of one supporting SSF,
926 then QEMU can be launched with:
928 @example
929 qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
930 @end example
932 @node vnc_sec_certificate_sasl
933 @subsection With x509 certificates and SASL authentication
935 If the desired SASL authentication mechanism does not supported
936 SSF layers, then it is strongly advised to run it in combination
937 with TLS and x509 certificates. This provides securely encrypted
938 data stream, avoiding risk of compromising of the security
939 credentials. This can be enabled, by combining the 'sasl' option
940 with the aforementioned TLS + x509 options:
942 @example
943 qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio
944 @end example
947 @node vnc_generate_cert
948 @subsection Generating certificates for VNC
950 The GNU TLS packages provides a command called @code{certtool} which can
951 be used to generate certificates and keys in PEM format. At a minimum it
952 is necessary to setup a certificate authority, and issue certificates to
953 each server. If using certificates for authentication, then each client
954 will also need to be issued a certificate. The recommendation is for the
955 server to keep its certificates in either @code{/etc/pki/qemu} or for
956 unprivileged users in @code{$HOME/.pki/qemu}.
958 @menu
959 * vnc_generate_ca::
960 * vnc_generate_server::
961 * vnc_generate_client::
962 @end menu
963 @node vnc_generate_ca
964 @subsubsection Setup the Certificate Authority
966 This step only needs to be performed once per organization / organizational
967 unit. First the CA needs a private key. This key must be kept VERY secret
968 and secure. If this key is compromised the entire trust chain of the certificates
969 issued with it is lost.
971 @example
972 # certtool --generate-privkey > ca-key.pem
973 @end example
975 A CA needs to have a public certificate. For simplicity it can be a self-signed
976 certificate, or one issue by a commercial certificate issuing authority. To
977 generate a self-signed certificate requires one core piece of information, the
978 name of the organization.
980 @example
981 # cat > ca.info <<EOF
982 cn = Name of your organization
984 cert_signing_key
986 # certtool --generate-self-signed \
987            --load-privkey ca-key.pem
988            --template ca.info \
989            --outfile ca-cert.pem
990 @end example
992 The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
993 TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
995 @node vnc_generate_server
996 @subsubsection Issuing server certificates
998 Each server (or host) needs to be issued with a key and certificate. When connecting
999 the certificate is sent to the client which validates it against the CA certificate.
1000 The core piece of information for a server certificate is the hostname. This should
1001 be the fully qualified hostname that the client will connect with, since the client
1002 will typically also verify the hostname in the certificate. On the host holding the
1003 secure CA private key:
1005 @example
1006 # cat > server.info <<EOF
1007 organization = Name  of your organization
1008 cn = server.foo.example.com
1009 tls_www_server
1010 encryption_key
1011 signing_key
1013 # certtool --generate-privkey > server-key.pem
1014 # certtool --generate-certificate \
1015            --load-ca-certificate ca-cert.pem \
1016            --load-ca-privkey ca-key.pem \
1017            --load-privkey server-key.pem \
1018            --template server.info \
1019            --outfile server-cert.pem
1020 @end example
1022 The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1023 to the server for which they were generated. The @code{server-key.pem} is security
1024 sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1026 @node vnc_generate_client
1027 @subsubsection Issuing client certificates
1029 If the QEMU VNC server is to use the @code{x509verify} option to validate client
1030 certificates as its authentication mechanism, each client also needs to be issued
1031 a certificate. The client certificate contains enough metadata to uniquely identify
1032 the client, typically organization, state, city, building, etc. On the host holding
1033 the secure CA private key:
1035 @example
1036 # cat > client.info <<EOF
1037 country = GB
1038 state = London
1039 locality = London
1040 organization = Name of your organization
1041 cn = client.foo.example.com
1042 tls_www_client
1043 encryption_key
1044 signing_key
1046 # certtool --generate-privkey > client-key.pem
1047 # certtool --generate-certificate \
1048            --load-ca-certificate ca-cert.pem \
1049            --load-ca-privkey ca-key.pem \
1050            --load-privkey client-key.pem \
1051            --template client.info \
1052            --outfile client-cert.pem
1053 @end example
1055 The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
1056 copied to the client for which they were generated.
1059 @node vnc_setup_sasl
1061 @subsection Configuring SASL mechanisms
1063 The following documentation assumes use of the Cyrus SASL implementation on a
1064 Linux host, but the principals should apply to any other SASL impl. When SASL
1065 is enabled, the mechanism configuration will be loaded from system default
1066 SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1067 unprivileged user, an environment variable SASL_CONF_PATH can be used
1068 to make it search alternate locations for the service config.
1070 If the TLS option is enabled for VNC, then it will provide session encryption,
1071 otherwise the SASL mechanism will have to provide encryption. In the latter
1072 case the list of possible plugins that can be used is drastically reduced. In
1073 fact only the GSSAPI SASL mechanism provides an acceptable level of security
1074 by modern standards. Previous versions of QEMU referred to the DIGEST-MD5
1075 mechanism, however, it has multiple serious flaws described in detail in
1076 RFC 6331 and thus should never be used any more. The SCRAM-SHA-1 mechanism
1077 provides a simple username/password auth facility similar to DIGEST-MD5, but
1078 does not support session encryption, so can only be used in combination with
1079 TLS.
1081 When not using TLS the recommended configuration is
1083 @example
1084 mech_list: gssapi
1085 keytab: /etc/qemu/krb5.tab
1086 @end example
1088 This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol, with
1089 the server principal stored in /etc/qemu/krb5.tab. For this to work the
1090 administrator of your KDC must generate a Kerberos principal for the server,
1091 with a name of 'qemu/somehost.example.com@@EXAMPLE.COM' replacing
1092 'somehost.example.com' with the fully qualified host name of the machine
1093 running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
1095 When using TLS, if username+password authentication is desired, then a
1096 reasonable configuration is
1098 @example
1099 mech_list: scram-sha-1
1100 sasldb_path: /etc/qemu/passwd.db
1101 @end example
1103 The saslpasswd2 program can be used to populate the passwd.db file with
1104 accounts.
1106 Other SASL configurations will be left as an exercise for the reader. Note that
1107 all mechanisms except GSSAPI, should be combined with use of TLS to ensure a
1108 secure data channel.
1110 @node gdb_usage
1111 @section GDB usage
1113 QEMU has a primitive support to work with gdb, so that you can do
1114 'Ctrl-C' while the virtual machine is running and inspect its state.
1116 In order to use gdb, launch QEMU with the '-s' option. It will wait for a
1117 gdb connection:
1118 @example
1119 qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1120                     -append "root=/dev/hda"
1121 Connected to host network interface: tun0
1122 Waiting gdb connection on port 1234
1123 @end example
1125 Then launch gdb on the 'vmlinux' executable:
1126 @example
1127 > gdb vmlinux
1128 @end example
1130 In gdb, connect to QEMU:
1131 @example
1132 (gdb) target remote localhost:1234
1133 @end example
1135 Then you can use gdb normally. For example, type 'c' to launch the kernel:
1136 @example
1137 (gdb) c
1138 @end example
1140 Here are some useful tips in order to use gdb on system code:
1142 @enumerate
1143 @item
1144 Use @code{info reg} to display all the CPU registers.
1145 @item
1146 Use @code{x/10i $eip} to display the code at the PC position.
1147 @item
1148 Use @code{set architecture i8086} to dump 16 bit code. Then use
1149 @code{x/10i $cs*16+$eip} to dump the code at the PC position.
1150 @end enumerate
1152 Advanced debugging options:
1154 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:
1155 @table @code
1156 @item maintenance packet qqemu.sstepbits
1158 This will display the MASK bits used to control the single stepping IE:
1159 @example
1160 (gdb) maintenance packet qqemu.sstepbits
1161 sending: "qqemu.sstepbits"
1162 received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1163 @end example
1164 @item maintenance packet qqemu.sstep
1166 This will display the current value of the mask used when single stepping IE:
1167 @example
1168 (gdb) maintenance packet qqemu.sstep
1169 sending: "qqemu.sstep"
1170 received: "0x7"
1171 @end example
1172 @item maintenance packet Qqemu.sstep=HEX_VALUE
1174 This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1175 @example
1176 (gdb) maintenance packet Qqemu.sstep=0x5
1177 sending: "qemu.sstep=0x5"
1178 received: "OK"
1179 @end example
1180 @end table
1182 @node pcsys_os_specific
1183 @section Target OS specific information
1185 @subsection Linux
1187 To have access to SVGA graphic modes under X11, use the @code{vesa} or
1188 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1189 color depth in the guest and the host OS.
1191 When using a 2.6 guest Linux kernel, you should add the option
1192 @code{clock=pit} on the kernel command line because the 2.6 Linux
1193 kernels make very strict real time clock checks by default that QEMU
1194 cannot simulate exactly.
1196 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1197 not activated because QEMU is slower with this patch. The QEMU
1198 Accelerator Module is also much slower in this case. Earlier Fedora
1199 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1200 patch by default. Newer kernels don't have it.
1202 @subsection Windows
1204 If you have a slow host, using Windows 95 is better as it gives the
1205 best speed. Windows 2000 is also a good choice.
1207 @subsubsection SVGA graphic modes support
1209 QEMU emulates a Cirrus Logic GD5446 Video
1210 card. All Windows versions starting from Windows 95 should recognize
1211 and use this graphic card. For optimal performances, use 16 bit color
1212 depth in the guest and the host OS.
1214 If you are using Windows XP as guest OS and if you want to use high
1215 resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
1216 1280x1024x16), then you should use the VESA VBE virtual graphic card
1217 (option @option{-std-vga}).
1219 @subsubsection CPU usage reduction
1221 Windows 9x does not correctly use the CPU HLT
1222 instruction. The result is that it takes host CPU cycles even when
1223 idle. You can install the utility from
1224 @url{http://web.archive.org/web/20060212132151/http://www.user.cityline.ru/~maxamn/amnhltm.zip}
1225 to solve this problem. Note that no such tool is needed for NT, 2000 or XP.
1227 @subsubsection Windows 2000 disk full problem
1229 Windows 2000 has a bug which gives a disk full problem during its
1230 installation. When installing it, use the @option{-win2k-hack} QEMU
1231 option to enable a specific workaround. After Windows 2000 is
1232 installed, you no longer need this option (this option slows down the
1233 IDE transfers).
1235 @subsubsection Windows 2000 shutdown
1237 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1238 can. It comes from the fact that Windows 2000 does not automatically
1239 use the APM driver provided by the BIOS.
1241 In order to correct that, do the following (thanks to Struan
1242 Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1243 Add/Troubleshoot a device => Add a new device & Next => No, select the
1244 hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1245 (again) a few times. Now the driver is installed and Windows 2000 now
1246 correctly instructs QEMU to shutdown at the appropriate moment.
1248 @subsubsection Share a directory between Unix and Windows
1250 See @ref{sec_invocation} about the help of the option
1251 @option{'-netdev user,smb=...'}.
1253 @subsubsection Windows XP security problem
1255 Some releases of Windows XP install correctly but give a security
1256 error when booting:
1257 @example
1258 A problem is preventing Windows from accurately checking the
1259 license for this computer. Error code: 0x800703e6.
1260 @end example
1262 The workaround is to install a service pack for XP after a boot in safe
1263 mode. Then reboot, and the problem should go away. Since there is no
1264 network while in safe mode, its recommended to download the full
1265 installation of SP1 or SP2 and transfer that via an ISO or using the
1266 vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1268 @subsection MS-DOS and FreeDOS
1270 @subsubsection CPU usage reduction
1272 DOS does not correctly use the CPU HLT instruction. The result is that
1273 it takes host CPU cycles even when idle. You can install the utility from
1274 @url{http://web.archive.org/web/20051222085335/http://www.vmware.com/software/dosidle210.zip}
1275 to solve this problem.
1277 @node QEMU System emulator for non PC targets
1278 @chapter QEMU System emulator for non PC targets
1280 QEMU is a generic emulator and it emulates many non PC
1281 machines. Most of the options are similar to the PC emulator. The
1282 differences are mentioned in the following sections.
1284 @menu
1285 * PowerPC System emulator::
1286 * Sparc32 System emulator::
1287 * Sparc64 System emulator::
1288 * MIPS System emulator::
1289 * ARM System emulator::
1290 * ColdFire System emulator::
1291 * Cris System emulator::
1292 * Microblaze System emulator::
1293 * SH4 System emulator::
1294 * Xtensa System emulator::
1295 @end menu
1297 @node PowerPC System emulator
1298 @section PowerPC System emulator
1299 @cindex system emulation (PowerPC)
1301 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1302 or PowerMac PowerPC system.
1304 QEMU emulates the following PowerMac peripherals:
1306 @itemize @minus
1307 @item
1308 UniNorth or Grackle PCI Bridge
1309 @item
1310 PCI VGA compatible card with VESA Bochs Extensions
1311 @item
1312 2 PMAC IDE interfaces with hard disk and CD-ROM support
1313 @item
1314 NE2000 PCI adapters
1315 @item
1316 Non Volatile RAM
1317 @item
1318 VIA-CUDA with ADB keyboard and mouse.
1319 @end itemize
1321 QEMU emulates the following PREP peripherals:
1323 @itemize @minus
1324 @item
1325 PCI Bridge
1326 @item
1327 PCI VGA compatible card with VESA Bochs Extensions
1328 @item
1329 2 IDE interfaces with hard disk and CD-ROM support
1330 @item
1331 Floppy disk
1332 @item
1333 NE2000 network adapters
1334 @item
1335 Serial port
1336 @item
1337 PREP Non Volatile RAM
1338 @item
1339 PC compatible keyboard and mouse.
1340 @end itemize
1342 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1343 @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
1345 Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}
1346 for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1347 v2) portable firmware implementation. The goal is to implement a 100%
1348 IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
1350 @c man begin OPTIONS
1352 The following options are specific to the PowerPC emulation:
1354 @table @option
1356 @item -g @var{W}x@var{H}[x@var{DEPTH}]
1358 Set the initial VGA graphic mode. The default is 800x600x32.
1360 @item -prom-env @var{string}
1362 Set OpenBIOS variables in NVRAM, for example:
1364 @example
1365 qemu-system-ppc -prom-env 'auto-boot?=false' \
1366  -prom-env 'boot-device=hd:2,\yaboot' \
1367  -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1368 @end example
1370 These variables are not used by Open Hack'Ware.
1372 @end table
1374 @c man end
1377 More information is available at
1378 @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1380 @node Sparc32 System emulator
1381 @section Sparc32 System emulator
1382 @cindex system emulation (Sparc32)
1384 Use the executable @file{qemu-system-sparc} to simulate the following
1385 Sun4m architecture machines:
1386 @itemize @minus
1387 @item
1388 SPARCstation 4
1389 @item
1390 SPARCstation 5
1391 @item
1392 SPARCstation 10
1393 @item
1394 SPARCstation 20
1395 @item
1396 SPARCserver 600MP
1397 @item
1398 SPARCstation LX
1399 @item
1400 SPARCstation Voyager
1401 @item
1402 SPARCclassic
1403 @item
1404 SPARCbook
1405 @end itemize
1407 The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1408 but Linux limits the number of usable CPUs to 4.
1410 QEMU emulates the following sun4m peripherals:
1412 @itemize @minus
1413 @item
1414 IOMMU
1415 @item
1416 TCX or cgthree Frame buffer
1417 @item
1418 Lance (Am7990) Ethernet
1419 @item
1420 Non Volatile RAM M48T02/M48T08
1421 @item
1422 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1423 and power/reset logic
1424 @item
1425 ESP SCSI controller with hard disk and CD-ROM support
1426 @item
1427 Floppy drive (not on SS-600MP)
1428 @item
1429 CS4231 sound device (only on SS-5, not working yet)
1430 @end itemize
1432 The number of peripherals is fixed in the architecture.  Maximum
1433 memory size depends on the machine type, for SS-5 it is 256MB and for
1434 others 2047MB.
1436 Since version 0.8.2, QEMU uses OpenBIOS
1437 @url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1438 firmware implementation. The goal is to implement a 100% IEEE
1439 1275-1994 (referred to as Open Firmware) compliant firmware.
1441 A sample Linux 2.6 series kernel and ram disk image are available on
1442 the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1443 most kernel versions work. Please note that currently older Solaris kernels
1444 don't work probably due to interface issues between OpenBIOS and
1445 Solaris.
1447 @c man begin OPTIONS
1449 The following options are specific to the Sparc32 emulation:
1451 @table @option
1453 @item -g @var{W}x@var{H}x[x@var{DEPTH}]
1455 Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
1456 option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
1457 of 1152x900x8 for people who wish to use OBP.
1459 @item -prom-env @var{string}
1461 Set OpenBIOS variables in NVRAM, for example:
1463 @example
1464 qemu-system-sparc -prom-env 'auto-boot?=false' \
1465  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1466 @end example
1468 @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]
1470 Set the emulated machine type. Default is SS-5.
1472 @end table
1474 @c man end
1476 @node Sparc64 System emulator
1477 @section Sparc64 System emulator
1478 @cindex system emulation (Sparc64)
1480 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1481 (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1482 Niagara (T1) machine. The Sun4u emulator is mostly complete, being
1483 able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
1484 Sun4v emulator is still a work in progress.
1486 The Niagara T1 emulator makes use of firmware and OS binaries supplied in the S10image/ directory
1487 of the OpenSPARC T1 project @url{http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2}
1488 and is able to boot the disk.s10hw2 Solaris image.
1489 @example
1490 qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
1491                     -nographic -m 256 \
1492                     -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
1493 @end example
1496 QEMU emulates the following peripherals:
1498 @itemize @minus
1499 @item
1500 UltraSparc IIi APB PCI Bridge
1501 @item
1502 PCI VGA compatible card with VESA Bochs Extensions
1503 @item
1504 PS/2 mouse and keyboard
1505 @item
1506 Non Volatile RAM M48T59
1507 @item
1508 PC-compatible serial ports
1509 @item
1510 2 PCI IDE interfaces with hard disk and CD-ROM support
1511 @item
1512 Floppy disk
1513 @end itemize
1515 @c man begin OPTIONS
1517 The following options are specific to the Sparc64 emulation:
1519 @table @option
1521 @item -prom-env @var{string}
1523 Set OpenBIOS variables in NVRAM, for example:
1525 @example
1526 qemu-system-sparc64 -prom-env 'auto-boot?=false'
1527 @end example
1529 @item -M [sun4u|sun4v|niagara]
1531 Set the emulated machine type. The default is sun4u.
1533 @end table
1535 @c man end
1537 @node MIPS System emulator
1538 @section MIPS System emulator
1539 @cindex system emulation (MIPS)
1541 Four executables cover simulation of 32 and 64-bit MIPS systems in
1542 both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
1543 @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
1544 Five different machine types are emulated:
1546 @itemize @minus
1547 @item
1548 A generic ISA PC-like machine "mips"
1549 @item
1550 The MIPS Malta prototype board "malta"
1551 @item
1552 An ACER Pica "pica61". This machine needs the 64-bit emulator.
1553 @item
1554 MIPS emulator pseudo board "mipssim"
1555 @item
1556 A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
1557 @end itemize
1559 The generic emulation is supported by Debian 'Etch' and is able to
1560 install Debian into a virtual disk image. The following devices are
1561 emulated:
1563 @itemize @minus
1564 @item
1565 A range of MIPS CPUs, default is the 24Kf
1566 @item
1567 PC style serial port
1568 @item
1569 PC style IDE disk
1570 @item
1571 NE2000 network card
1572 @end itemize
1574 The Malta emulation supports the following devices:
1576 @itemize @minus
1577 @item
1578 Core board with MIPS 24Kf CPU and Galileo system controller
1579 @item
1580 PIIX4 PCI/USB/SMbus controller
1581 @item
1582 The Multi-I/O chip's serial device
1583 @item
1584 PCI network cards (PCnet32 and others)
1585 @item
1586 Malta FPGA serial device
1587 @item
1588 Cirrus (default) or any other PCI VGA graphics card
1589 @end itemize
1591 The ACER Pica emulation supports:
1593 @itemize @minus
1594 @item
1595 MIPS R4000 CPU
1596 @item
1597 PC-style IRQ and DMA controllers
1598 @item
1599 PC Keyboard
1600 @item
1601 IDE controller
1602 @end itemize
1604 The mipssim pseudo board emulation provides an environment similar
1605 to what the proprietary MIPS emulator uses for running Linux.
1606 It supports:
1608 @itemize @minus
1609 @item
1610 A range of MIPS CPUs, default is the 24Kf
1611 @item
1612 PC style serial port
1613 @item
1614 MIPSnet network emulation
1615 @end itemize
1617 The MIPS Magnum R4000 emulation supports:
1619 @itemize @minus
1620 @item
1621 MIPS R4000 CPU
1622 @item
1623 PC-style IRQ controller
1624 @item
1625 PC Keyboard
1626 @item
1627 SCSI controller
1628 @item
1629 G364 framebuffer
1630 @end itemize
1633 @node ARM System emulator
1634 @section ARM System emulator
1635 @cindex system emulation (ARM)
1637 Use the executable @file{qemu-system-arm} to simulate a ARM
1638 machine. The ARM Integrator/CP board is emulated with the following
1639 devices:
1641 @itemize @minus
1642 @item
1643 ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
1644 @item
1645 Two PL011 UARTs
1646 @item
1647 SMC 91c111 Ethernet adapter
1648 @item
1649 PL110 LCD controller
1650 @item
1651 PL050 KMI with PS/2 keyboard and mouse.
1652 @item
1653 PL181 MultiMedia Card Interface with SD card.
1654 @end itemize
1656 The ARM Versatile baseboard is emulated with the following devices:
1658 @itemize @minus
1659 @item
1660 ARM926E, ARM1136 or Cortex-A8 CPU
1661 @item
1662 PL190 Vectored Interrupt Controller
1663 @item
1664 Four PL011 UARTs
1665 @item
1666 SMC 91c111 Ethernet adapter
1667 @item
1668 PL110 LCD controller
1669 @item
1670 PL050 KMI with PS/2 keyboard and mouse.
1671 @item
1672 PCI host bridge.  Note the emulated PCI bridge only provides access to
1673 PCI memory space.  It does not provide access to PCI IO space.
1674 This means some devices (eg. ne2k_pci NIC) are not usable, and others
1675 (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
1676 mapped control registers.
1677 @item
1678 PCI OHCI USB controller.
1679 @item
1680 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
1681 @item
1682 PL181 MultiMedia Card Interface with SD card.
1683 @end itemize
1685 Several variants of the ARM RealView baseboard are emulated,
1686 including the EB, PB-A8 and PBX-A9.  Due to interactions with the
1687 bootloader, only certain Linux kernel configurations work out
1688 of the box on these boards.
1690 Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1691 enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board
1692 should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
1693 disabled and expect 1024M RAM.
1695 The following devices are emulated:
1697 @itemize @minus
1698 @item
1699 ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
1700 @item
1701 ARM AMBA Generic/Distributed Interrupt Controller
1702 @item
1703 Four PL011 UARTs
1704 @item
1705 SMC 91c111 or SMSC LAN9118 Ethernet adapter
1706 @item
1707 PL110 LCD controller
1708 @item
1709 PL050 KMI with PS/2 keyboard and mouse
1710 @item
1711 PCI host bridge
1712 @item
1713 PCI OHCI USB controller
1714 @item
1715 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
1716 @item
1717 PL181 MultiMedia Card Interface with SD card.
1718 @end itemize
1720 The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
1721 and "Terrier") emulation includes the following peripherals:
1723 @itemize @minus
1724 @item
1725 Intel PXA270 System-on-chip (ARM V5TE core)
1726 @item
1727 NAND Flash memory
1728 @item
1729 IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
1730 @item
1731 On-chip OHCI USB controller
1732 @item
1733 On-chip LCD controller
1734 @item
1735 On-chip Real Time Clock
1736 @item
1737 TI ADS7846 touchscreen controller on SSP bus
1738 @item
1739 Maxim MAX1111 analog-digital converter on I@math{^2}C bus
1740 @item
1741 GPIO-connected keyboard controller and LEDs
1742 @item
1743 Secure Digital card connected to PXA MMC/SD host
1744 @item
1745 Three on-chip UARTs
1746 @item
1747 WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
1748 @end itemize
1750 The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
1751 following elements:
1753 @itemize @minus
1754 @item
1755 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1756 @item
1757 ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
1758 @item
1759 On-chip LCD controller
1760 @item
1761 On-chip Real Time Clock
1762 @item
1763 TI TSC2102i touchscreen controller / analog-digital converter / Audio
1764 CODEC, connected through MicroWire and I@math{^2}S busses
1765 @item
1766 GPIO-connected matrix keypad
1767 @item
1768 Secure Digital card connected to OMAP MMC/SD host
1769 @item
1770 Three on-chip UARTs
1771 @end itemize
1773 Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
1774 emulation supports the following elements:
1776 @itemize @minus
1777 @item
1778 Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
1779 @item
1780 RAM and non-volatile OneNAND Flash memories
1781 @item
1782 Display connected to EPSON remote framebuffer chip and OMAP on-chip
1783 display controller and a LS041y3 MIPI DBI-C controller
1784 @item
1785 TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
1786 driven through SPI bus
1787 @item
1788 National Semiconductor LM8323-controlled qwerty keyboard driven
1789 through I@math{^2}C bus
1790 @item
1791 Secure Digital card connected to OMAP MMC/SD host
1792 @item
1793 Three OMAP on-chip UARTs and on-chip STI debugging console
1794 @item
1795 A Bluetooth(R) transceiver and HCI connected to an UART
1796 @item
1797 Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
1798 TUSB6010 chip - only USB host mode is supported
1799 @item
1800 TI TMP105 temperature sensor driven through I@math{^2}C bus
1801 @item
1802 TI TWL92230C power management companion with an RTC on I@math{^2}C bus
1803 @item
1804 Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
1805 through CBUS
1806 @end itemize
1808 The Luminary Micro Stellaris LM3S811EVB emulation includes the following
1809 devices:
1811 @itemize @minus
1812 @item
1813 Cortex-M3 CPU core.
1814 @item
1815 64k Flash and 8k SRAM.
1816 @item
1817 Timers, UARTs, ADC and I@math{^2}C interface.
1818 @item
1819 OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
1820 @end itemize
1822 The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
1823 devices:
1825 @itemize @minus
1826 @item
1827 Cortex-M3 CPU core.
1828 @item
1829 256k Flash and 64k SRAM.
1830 @item
1831 Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
1832 @item
1833 OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
1834 @end itemize
1836 The Freecom MusicPal internet radio emulation includes the following
1837 elements:
1839 @itemize @minus
1840 @item
1841 Marvell MV88W8618 ARM core.
1842 @item
1843 32 MB RAM, 256 KB SRAM, 8 MB flash.
1844 @item
1845 Up to 2 16550 UARTs
1846 @item
1847 MV88W8xx8 Ethernet controller
1848 @item
1849 MV88W8618 audio controller, WM8750 CODEC and mixer
1850 @item
1851 128×64 display with brightness control
1852 @item
1853 2 buttons, 2 navigation wheels with button function
1854 @end itemize
1856 The Siemens SX1 models v1 and v2 (default) basic emulation.
1857 The emulation includes the following elements:
1859 @itemize @minus
1860 @item
1861 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
1862 @item
1863 ROM and RAM memories (ROM firmware image can be loaded with -pflash)
1865 1 Flash of 16MB and 1 Flash of 8MB
1867 1 Flash of 32MB
1868 @item
1869 On-chip LCD controller
1870 @item
1871 On-chip Real Time Clock
1872 @item
1873 Secure Digital card connected to OMAP MMC/SD host
1874 @item
1875 Three on-chip UARTs
1876 @end itemize
1878 A Linux 2.6 test image is available on the QEMU web site. More
1879 information is available in the QEMU mailing-list archive.
1881 @c man begin OPTIONS
1883 The following options are specific to the ARM emulation:
1885 @table @option
1887 @item -semihosting
1888 Enable semihosting syscall emulation.
1890 On ARM this implements the "Angel" interface.
1892 Note that this allows guest direct access to the host filesystem,
1893 so should only be used with trusted guest OS.
1895 @end table
1897 @c man end
1899 @node ColdFire System emulator
1900 @section ColdFire System emulator
1901 @cindex system emulation (ColdFire)
1902 @cindex system emulation (M68K)
1904 Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
1905 The emulator is able to boot a uClinux kernel.
1907 The M5208EVB emulation includes the following devices:
1909 @itemize @minus
1910 @item
1911 MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
1912 @item
1913 Three Two on-chip UARTs.
1914 @item
1915 Fast Ethernet Controller (FEC)
1916 @end itemize
1918 The AN5206 emulation includes the following devices:
1920 @itemize @minus
1921 @item
1922 MCF5206 ColdFire V2 Microprocessor.
1923 @item
1924 Two on-chip UARTs.
1925 @end itemize
1927 @c man begin OPTIONS
1929 The following options are specific to the ColdFire emulation:
1931 @table @option
1933 @item -semihosting
1934 Enable semihosting syscall emulation.
1936 On M68K this implements the "ColdFire GDB" interface used by libgloss.
1938 Note that this allows guest direct access to the host filesystem,
1939 so should only be used with trusted guest OS.
1941 @end table
1943 @c man end
1945 @node Cris System emulator
1946 @section Cris System emulator
1947 @cindex system emulation (Cris)
1949 TODO
1951 @node Microblaze System emulator
1952 @section Microblaze System emulator
1953 @cindex system emulation (Microblaze)
1955 TODO
1957 @node SH4 System emulator
1958 @section SH4 System emulator
1959 @cindex system emulation (SH4)
1961 TODO
1963 @node Xtensa System emulator
1964 @section Xtensa System emulator
1965 @cindex system emulation (Xtensa)
1967 Two executables cover simulation of both Xtensa endian options,
1968 @file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
1969 Two different machine types are emulated:
1971 @itemize @minus
1972 @item
1973 Xtensa emulator pseudo board "sim"
1974 @item
1975 Avnet LX60/LX110/LX200 board
1976 @end itemize
1978 The sim pseudo board emulation provides an environment similar
1979 to one provided by the proprietary Tensilica ISS.
1980 It supports:
1982 @itemize @minus
1983 @item
1984 A range of Xtensa CPUs, default is the DC232B
1985 @item
1986 Console and filesystem access via semihosting calls
1987 @end itemize
1989 The Avnet LX60/LX110/LX200 emulation supports:
1991 @itemize @minus
1992 @item
1993 A range of Xtensa CPUs, default is the DC232B
1994 @item
1995 16550 UART
1996 @item
1997 OpenCores 10/100 Mbps Ethernet MAC
1998 @end itemize
2000 @c man begin OPTIONS
2002 The following options are specific to the Xtensa emulation:
2004 @table @option
2006 @item -semihosting
2007 Enable semihosting syscall emulation.
2009 Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2010 Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2012 Note that this allows guest direct access to the host filesystem,
2013 so should only be used with trusted guest OS.
2015 @end table
2017 @c man end
2019 @node QEMU Guest Agent
2020 @chapter QEMU Guest Agent invocation
2022 @include qemu-ga.texi
2024 @node QEMU User space emulator
2025 @chapter QEMU User space emulator
2027 @menu
2028 * Supported Operating Systems ::
2029 * Features::
2030 * Linux User space emulator::
2031 * BSD User space emulator ::
2032 @end menu
2034 @node Supported Operating Systems
2035 @section Supported Operating Systems
2037 The following OS are supported in user space emulation:
2039 @itemize @minus
2040 @item
2041 Linux (referred as qemu-linux-user)
2042 @item
2043 BSD (referred as qemu-bsd-user)
2044 @end itemize
2046 @node Features
2047 @section Features
2049 QEMU user space emulation has the following notable features:
2051 @table @strong
2052 @item System call translation:
2053 QEMU includes a generic system call translator.  This means that
2054 the parameters of the system calls can be converted to fix
2055 endianness and 32/64-bit mismatches between hosts and targets.
2056 IOCTLs can be converted too.
2058 @item POSIX signal handling:
2059 QEMU can redirect to the running program all signals coming from
2060 the host (such as @code{SIGALRM}), as well as synthesize signals from
2061 virtual CPU exceptions (for example @code{SIGFPE} when the program
2062 executes a division by zero).
2064 QEMU relies on the host kernel to emulate most signal system
2065 calls, for example to emulate the signal mask.  On Linux, QEMU
2066 supports both normal and real-time signals.
2068 @item Threading:
2069 On Linux, QEMU can emulate the @code{clone} syscall and create a real
2070 host thread (with a separate virtual CPU) for each emulated thread.
2071 Note that not all targets currently emulate atomic operations correctly.
2072 x86 and ARM use a global lock in order to preserve their semantics.
2073 @end table
2075 QEMU was conceived so that ultimately it can emulate itself. Although
2076 it is not very useful, it is an important test to show the power of the
2077 emulator.
2079 @node Linux User space emulator
2080 @section Linux User space emulator
2082 @menu
2083 * Quick Start::
2084 * Wine launch::
2085 * Command line options::
2086 * Other binaries::
2087 @end menu
2089 @node Quick Start
2090 @subsection Quick Start
2092 In order to launch a Linux process, QEMU needs the process executable
2093 itself and all the target (x86) dynamic libraries used by it.
2095 @itemize
2097 @item On x86, you can just try to launch any process by using the native
2098 libraries:
2100 @example
2101 qemu-i386 -L / /bin/ls
2102 @end example
2104 @code{-L /} tells that the x86 dynamic linker must be searched with a
2105 @file{/} prefix.
2107 @item Since QEMU is also a linux process, you can launch QEMU with
2108 QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
2110 @example
2111 qemu-i386 -L / qemu-i386 -L / /bin/ls
2112 @end example
2114 @item On non x86 CPUs, you need first to download at least an x86 glibc
2115 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2116 @code{LD_LIBRARY_PATH} is not set:
2118 @example
2119 unset LD_LIBRARY_PATH
2120 @end example
2122 Then you can launch the precompiled @file{ls} x86 executable:
2124 @example
2125 qemu-i386 tests/i386/ls
2126 @end example
2127 You can look at @file{scripts/qemu-binfmt-conf.sh} so that
2128 QEMU is automatically launched by the Linux kernel when you try to
2129 launch x86 executables. It requires the @code{binfmt_misc} module in the
2130 Linux kernel.
2132 @item The x86 version of QEMU is also included. You can try weird things such as:
2133 @example
2134 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2135           /usr/local/qemu-i386/bin/ls-i386
2136 @end example
2138 @end itemize
2140 @node Wine launch
2141 @subsection Wine launch
2143 @itemize
2145 @item Ensure that you have a working QEMU with the x86 glibc
2146 distribution (see previous section). In order to verify it, you must be
2147 able to do:
2149 @example
2150 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2151 @end example
2153 @item Download the binary x86 Wine install
2154 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2156 @item Configure Wine on your account. Look at the provided script
2157 @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2158 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2160 @item Then you can try the example @file{putty.exe}:
2162 @example
2163 qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2164           /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2165 @end example
2167 @end itemize
2169 @node Command line options
2170 @subsection Command line options
2172 @example
2173 @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}...]
2174 @end example
2176 @table @option
2177 @item -h
2178 Print the help
2179 @item -L path
2180 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2181 @item -s size
2182 Set the x86 stack size in bytes (default=524288)
2183 @item -cpu model
2184 Select CPU model (-cpu help for list and additional feature selection)
2185 @item -E @var{var}=@var{value}
2186 Set environment @var{var} to @var{value}.
2187 @item -U @var{var}
2188 Remove @var{var} from the environment.
2189 @item -B offset
2190 Offset guest address by the specified number of bytes.  This is useful when
2191 the address region required by guest applications is reserved on the host.
2192 This option is currently only supported on some hosts.
2193 @item -R size
2194 Pre-allocate a guest virtual address space of the given size (in bytes).
2195 "G", "M", and "k" suffixes may be used when specifying the size.
2196 @end table
2198 Debug options:
2200 @table @option
2201 @item -d item1,...
2202 Activate logging of the specified items (use '-d help' for a list of log items)
2203 @item -p pagesize
2204 Act as if the host page size was 'pagesize' bytes
2205 @item -g port
2206 Wait gdb connection to port
2207 @item -singlestep
2208 Run the emulation in single step mode.
2209 @end table
2211 Environment variables:
2213 @table @env
2214 @item QEMU_STRACE
2215 Print system calls and arguments similar to the 'strace' program
2216 (NOTE: the actual 'strace' program will not work because the user
2217 space emulator hasn't implemented ptrace).  At the moment this is
2218 incomplete.  All system calls that don't have a specific argument
2219 format are printed with information for six arguments.  Many
2220 flag-style arguments don't have decoders and will show up as numbers.
2221 @end table
2223 @node Other binaries
2224 @subsection Other binaries
2226 @cindex user mode (Alpha)
2227 @command{qemu-alpha} TODO.
2229 @cindex user mode (ARM)
2230 @command{qemu-armeb} TODO.
2232 @cindex user mode (ARM)
2233 @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2234 binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2235 configurations), and arm-uclinux bFLT format binaries.
2237 @cindex user mode (ColdFire)
2238 @cindex user mode (M68K)
2239 @command{qemu-m68k} is capable of running semihosted binaries using the BDM
2240 (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2241 coldfire uClinux bFLT format binaries.
2243 The binary format is detected automatically.
2245 @cindex user mode (Cris)
2246 @command{qemu-cris} TODO.
2248 @cindex user mode (i386)
2249 @command{qemu-i386} TODO.
2250 @command{qemu-x86_64} TODO.
2252 @cindex user mode (Microblaze)
2253 @command{qemu-microblaze} TODO.
2255 @cindex user mode (MIPS)
2256 @command{qemu-mips} TODO.
2257 @command{qemu-mipsel} TODO.
2259 @cindex user mode (NiosII)
2260 @command{qemu-nios2} TODO.
2262 @cindex user mode (PowerPC)
2263 @command{qemu-ppc64abi32} TODO.
2264 @command{qemu-ppc64} TODO.
2265 @command{qemu-ppc} TODO.
2267 @cindex user mode (SH4)
2268 @command{qemu-sh4eb} TODO.
2269 @command{qemu-sh4} TODO.
2271 @cindex user mode (SPARC)
2272 @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2274 @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2275 (Sparc64 CPU, 32 bit ABI).
2277 @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2278 SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2280 @node BSD User space emulator
2281 @section BSD User space emulator
2283 @menu
2284 * BSD Status::
2285 * BSD Quick Start::
2286 * BSD Command line options::
2287 @end menu
2289 @node BSD Status
2290 @subsection BSD Status
2292 @itemize @minus
2293 @item
2294 target Sparc64 on Sparc64: Some trivial programs work.
2295 @end itemize
2297 @node BSD Quick Start
2298 @subsection Quick Start
2300 In order to launch a BSD process, QEMU needs the process executable
2301 itself and all the target dynamic libraries used by it.
2303 @itemize
2305 @item On Sparc64, you can just try to launch any process by using the native
2306 libraries:
2308 @example
2309 qemu-sparc64 /bin/ls
2310 @end example
2312 @end itemize
2314 @node BSD Command line options
2315 @subsection Command line options
2317 @example
2318 @command{qemu-sparc64} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-bsd} @var{type}] @var{program} [@var{arguments}...]
2319 @end example
2321 @table @option
2322 @item -h
2323 Print the help
2324 @item -L path
2325 Set the library root path (default=/)
2326 @item -s size
2327 Set the stack size in bytes (default=524288)
2328 @item -ignore-environment
2329 Start with an empty environment. Without this option,
2330 the initial environment is a copy of the caller's environment.
2331 @item -E @var{var}=@var{value}
2332 Set environment @var{var} to @var{value}.
2333 @item -U @var{var}
2334 Remove @var{var} from the environment.
2335 @item -bsd type
2336 Set the type of the emulated BSD Operating system. Valid values are
2337 FreeBSD, NetBSD and OpenBSD (default).
2338 @end table
2340 Debug options:
2342 @table @option
2343 @item -d item1,...
2344 Activate logging of the specified items (use '-d help' for a list of log items)
2345 @item -p pagesize
2346 Act as if the host page size was 'pagesize' bytes
2347 @item -singlestep
2348 Run the emulation in single step mode.
2349 @end table
2352 @include qemu-tech.texi
2354 @node Deprecated features
2355 @appendix Deprecated features
2357 In general features are intended to be supported indefinitely once
2358 introduced into QEMU. In the event that a feature needs to be removed,
2359 it will be listed in this appendix. The feature will remain functional
2360 for 2 releases prior to actual removal. Deprecated features may also
2361 generate warnings on the console when QEMU starts up, or if activated
2362 via a monitor command, however, this is not a mandatory requirement.
2364 Prior to the 2.10.0 release there was no official policy on how
2365 long features would be deprecated prior to their removal, nor
2366 any documented list of which features were deprecated. Thus
2367 any features deprecated prior to 2.10.0 will be treated as if
2368 they were first deprecated in the 2.10.0 release.
2370 What follows is a list of all features currently marked as
2371 deprecated.
2373 @section System emulator command line arguments
2375 @subsection -drive boot=on|off (since 1.3.0)
2377 The ``boot=on|off'' option to the ``-drive'' argument is
2378 ignored. Applications should use the ``bootindex=N'' parameter
2379 to set an absolute ordering between devices instead.
2381 @subsection -tdf (since 1.3.0)
2383 The ``-tdf'' argument is ignored. The behaviour implemented
2384 by this argument is now the default when using the KVM PIT,
2385 but can be requested explicitly using
2386 ``-global kvm-pit.lost_tick_policy=slew''.
2388 @subsection -no-kvm-pit-reinjection (since 1.3.0)
2390 The ``-no-kvm-pit-reinjection'' argument is now a
2391 synonym for setting ``-global kvm-pit.lost_tick_policy=discard''.
2393 @subsection -no-kvm-irqchip (since 1.3.0)
2395 The ``-no-kvm-irqchip'' argument is now a synonym for
2396 setting ``-machine kernel_irqchip=off''.
2398 @subsection -no-kvm-pit (since 1.3.0)
2400 The ``-no-kvm-pit'' argument is ignored. It is no longer
2401 possible to disable the KVM PIT directly.
2403 @subsection -no-kvm (since 1.3.0)
2405 The ``-no-kvm'' argument is now a synonym for setting
2406 ``-machine accel=tcg''.
2408 @subsection -mon default=on (since 2.4.0)
2410 The ``default'' option to the ``-mon'' argument is
2411 now ignored. When multiple monitors were enabled, it
2412 indicated which monitor would receive log messages
2413 from the various subsystems. This feature is no longer
2414 required as messages are now only sent to the monitor
2415 in response to explicitly monitor commands.
2417 @subsection -vnc tls (since 2.5.0)
2419 The ``-vnc tls'' argument is now a synonym for setting
2420 ``-object tls-creds-anon,id=tls0'' combined with
2421 ``-vnc tls-creds=tls0'
2423 @subsection -vnc x509 (since 2.5.0)
2425 The ``-vnc x509=/path/to/certs'' argument is now a
2426 synonym for setting
2427 ``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=no''
2428 combined with ``-vnc tls-creds=tls0'
2430 @subsection -vnc x509verify (since 2.5.0)
2432 The ``-vnc x509verify=/path/to/certs'' argument is now a
2433 synonym for setting
2434 ``-object tls-creds-x509,dir=/path/to/certs,id=tls0,verify-peer=yes''
2435 combined with ``-vnc tls-creds=tls0'
2437 @subsection -tftp (since 2.6.0)
2439 The ``-tftp /some/dir'' argument is now a synonym for setting
2440 the ``-netdev user,tftp=/some/dir' argument. The new syntax
2441 allows different settings to be provided per NIC.
2443 @subsection -bootp (since 2.6.0)
2445 The ``-bootp /some/file'' argument is now a synonym for setting
2446 the ``-netdev user,bootp=/some/file' argument. The new syntax
2447 allows different settings to be provided per NIC.
2449 @subsection -redir (since 2.6.0)
2451 The ``-redir ARGS'' argument is now a synonym for setting
2452 the ``-netdev user,hostfwd=ARGS'' argument instead. The new
2453 syntax allows different settings to be provided per NIC.
2455 @subsection -smb (since 2.6.0)
2457 The ``-smb /some/dir'' argument is now a synonym for setting
2458 the ``-netdev user,smb=/some/dir'' argument instead. The new
2459 syntax allows different settings to be provided per NIC.
2461 @subsection -net channel (since 2.6.0)
2463 The ``--net channel,ARGS'' argument is now a synonym for setting
2464 the ``-netdev user,guestfwd=ARGS'' argument instead.
2466 @subsection -net vlan (since 2.9.0)
2468 The ``-net vlan=NN'' argument is partially replaced with the
2469 new ``-netdev'' argument. The remaining use cases will no
2470 longer be directly supported in QEMU.
2472 @subsection -drive if=scsi (since 2.9.0)
2474 The ``-drive if=scsi'' argument is replaced by the the
2475 ``-device BUS-TYPE'' argument combined with ``-drive if=none''.
2477 @subsection -net dump (since 2.10.0)
2479 The ``--net dump'' argument is now replaced with the
2480 ``-object filter-dump'' argument which works in combination
2481 with the modern ``-netdev`` backends instead.
2483 @subsection -hdachs (since 2.10.0)
2485 The ``-hdachs'' argument is now a synonym for setting
2486 the ``cyls'', ``heads'', ``secs'', and ``trans'' properties
2487 on the ``ide-hd'' device using the ``-device'' argument.
2488 The new syntax allows different settings to be provided
2489 per disk.
2491 @subsection -usbdevice (since 2.10.0)
2493 The ``-usbdevice DEV'' argument is now a synonym for setting
2494 the ``-device usb-DEV'' argument instead. The deprecated syntax
2495 would automatically enable USB support on the machine type.
2496 If using the new syntax, USB support must be explicitly
2497 enabled via the ``-machine usb=on'' argument.
2499 @section qemu-img command line arguments
2501 @subsection convert -s (since 2.0.0)
2503 The ``convert -s snapshot_id_or_name'' argument is obsoleted
2504 by the ``convert -l snapshot_param'' argument instead.
2506 @section System emulator human monitor commands
2508 @subsection host_net_add (since 2.10.0)
2510 The ``host_net_add'' command is replaced by the ``netdev_add'' command.
2512 @subsection host_net_remove (since 2.10.0)
2514 The ``host_net_remove'' command is replaced by the ``netdev_del'' command.
2516 @subsection usb_add (since 2.10.0)
2518 The ``usb_add'' command is replaced by the ``device_add'' command.
2520 @subsection usb_del (since 2.10.0)
2522 The ``usb_del'' command is replaced by the ``device_del'' command.
2524 @section System emulator devices
2526 @subsection ivshmem (since 2.6.0)
2528 The ``ivshmem'' device type is replaced by either the ``ivshmem-plain''
2529 or ``ivshmem-doorbell`` device types.
2531 @subsection spapr-pci-vfio-host-bridge (since 2.6.0)
2533 The ``spapr-pci-vfio-host-bridge'' device type is replaced by
2534 the ``spapr-pci-host-bridge'' device type.
2536 @node License
2537 @appendix License
2539 QEMU is a trademark of Fabrice Bellard.
2541 QEMU is released under the
2542 @url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
2543 version 2. Parts of QEMU have specific licenses, see file
2544 @url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
2546 @node Index
2547 @appendix Index
2548 @menu
2549 * Concept Index::
2550 * Function Index::
2551 * Keystroke Index::
2552 * Program Index::
2553 * Data Type Index::
2554 * Variable Index::
2555 @end menu
2557 @node Concept Index
2558 @section Concept Index
2559 This is the main index. Should we combine all keywords in one index? TODO
2560 @printindex cp
2562 @node Function Index
2563 @section Function Index
2564 This index could be used for command line options and monitor functions.
2565 @printindex fn
2567 @node Keystroke Index
2568 @section Keystroke Index
2570 This is a list of all keystrokes which have a special function
2571 in system emulation.
2573 @printindex ky
2575 @node Program Index
2576 @section Program Index
2577 @printindex pg
2579 @node Data Type Index
2580 @section Data Type Index
2582 This index could be used for qdev device names and options.
2584 @printindex tp
2586 @node Variable Index
2587 @section Variable Index
2588 @printindex vr
2590 @bye