1 \input texinfo @c -*- texinfo -*-
3 @setfilename qemu-doc.info
4 @settitle QEMU Emulator User Documentation
12 @center @titlefont{QEMU Emulator}
14 @center @titlefont{User Documentation}
26 * QEMU PC System emulator::
27 * QEMU System emulator for non PC targets::
28 * QEMU User space emulator::
29 * compilation:: Compilation from the sources
40 * intro_features:: Features
46 QEMU is a FAST! processor emulator using dynamic translation to
47 achieve good emulation speed.
49 QEMU has two operating modes:
54 Full system emulation. In this mode, QEMU emulates a full system (for
55 example a PC), including one or several processors and various
56 peripherals. It can be used to launch different Operating Systems
57 without rebooting the PC or to debug system code.
60 User mode emulation. In this mode, QEMU can launch
61 processes compiled for one CPU on another CPU. It can be used to
62 launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
63 to ease cross-compilation and cross-debugging.
67 QEMU can run without an host kernel driver and yet gives acceptable
70 For system emulation, the following hardware targets are supported:
72 @item PC (x86 or x86_64 processor)
73 @item ISA PC (old style PC without PCI bus)
74 @item PREP (PowerPC processor)
75 @item G3 BW PowerMac (PowerPC processor)
76 @item Mac99 PowerMac (PowerPC processor, in progress)
77 @item Sun4m/Sun4c/Sun4d (32-bit Sparc processor)
78 @item Sun4u/Sun4v (64-bit Sparc processor, in progress)
79 @item Malta board (32-bit and 64-bit MIPS processors)
80 @item MIPS Magnum (64-bit MIPS processor)
81 @item ARM Integrator/CP (ARM)
82 @item ARM Versatile baseboard (ARM)
83 @item ARM RealView Emulation baseboard (ARM)
84 @item Spitz, Akita, Borzoi and Terrier PDAs (PXA270 processor)
85 @item Luminary Micro LM3S811EVB (ARM Cortex-M3)
86 @item Luminary Micro LM3S6965EVB (ARM Cortex-M3)
87 @item Freescale MCF5208EVB (ColdFire V2).
88 @item Arnewsh MCF5206 evaluation board (ColdFire V2).
89 @item Palm Tungsten|E PDA (OMAP310 processor)
90 @item N800 and N810 tablets (OMAP2420 processor)
91 @item MusicPal (MV88W8618 ARM processor)
94 For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported.
99 If you want to compile QEMU yourself, see @ref{compilation}.
102 * install_linux:: Linux
103 * install_windows:: Windows
104 * install_mac:: Macintosh
110 If a precompiled package is available for your distribution - you just
111 have to install it. Otherwise, see @ref{compilation}.
113 @node install_windows
116 Download the experimental binary installer at
117 @url{http://www.free.oszoo.org/@/download.html}.
122 Download the experimental binary installer at
123 @url{http://www.free.oszoo.org/@/download.html}.
125 @node QEMU PC System emulator
126 @chapter QEMU PC System emulator
129 * pcsys_introduction:: Introduction
130 * pcsys_quickstart:: Quick Start
131 * sec_invocation:: Invocation
133 * pcsys_monitor:: QEMU Monitor
134 * disk_images:: Disk Images
135 * pcsys_network:: Network emulation
136 * direct_linux_boot:: Direct Linux Boot
137 * pcsys_usb:: USB emulation
138 * vnc_security:: VNC security
139 * gdb_usage:: GDB usage
140 * pcsys_os_specific:: Target OS specific information
143 @node pcsys_introduction
144 @section Introduction
146 @c man begin DESCRIPTION
148 The QEMU PC System emulator simulates the
149 following peripherals:
153 i440FX host PCI bridge and PIIX3 PCI to ISA bridge
155 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
156 extensions (hardware level, including all non standard modes).
158 PS/2 mouse and keyboard
160 2 PCI IDE interfaces with hard disk and CD-ROM support
164 PCI/ISA PCI network adapters
168 Creative SoundBlaster 16 sound card
170 ENSONIQ AudioPCI ES1370 sound card
172 Intel 82801AA AC97 Audio compatible sound card
174 Adlib(OPL2) - Yamaha YM3812 compatible chip
176 Gravis Ultrasound GF1 sound card
178 CS4231A compatible sound card
180 PCI UHCI USB controller and a virtual USB hub.
183 SMP is supported with up to 255 CPUs.
185 Note that adlib, ac97, gus and cs4231a are only available when QEMU
186 was configured with --audio-card-list option containing the name(s) of
189 QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
192 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
194 QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
195 by Tibor "TS" Schütz.
197 CS4231A is the chip used in Windows Sound System and GUSMAX products
201 @node pcsys_quickstart
204 Download and uncompress the linux image (@file{linux.img}) and type:
210 Linux should boot and give you a prompt.
216 @c man begin SYNOPSIS
217 usage: qemu [options] [@var{disk_image}]
222 @var{disk_image} is a raw hard disk image for IDE hard disk 0.
226 @item -M @var{machine}
227 Select the emulated @var{machine} (@code{-M ?} for list)
229 @item -fda @var{file}
230 @item -fdb @var{file}
231 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
232 use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
234 @item -hda @var{file}
235 @item -hdb @var{file}
236 @item -hdc @var{file}
237 @item -hdd @var{file}
238 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
240 @item -cdrom @var{file}
241 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
242 @option{-cdrom} at the same time). You can use the host CD-ROM by
243 using @file{/dev/cdrom} as filename (@pxref{host_drives}).
245 @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
247 Define a new drive. Valid options are:
250 @item file=@var{file}
251 This option defines which disk image (@pxref{disk_images}) to use with
252 this drive. If the filename contains comma, you must double it
253 (for instance, "file=my,,file" to use file "my,file").
254 @item if=@var{interface}
255 This option defines on which type on interface the drive is connected.
256 Available types are: ide, scsi, sd, mtd, floppy, pflash.
257 @item bus=@var{bus},unit=@var{unit}
258 These options define where is connected the drive by defining the bus number and
260 @item index=@var{index}
261 This option defines where is connected the drive by using an index in the list
262 of available connectors of a given interface type.
263 @item media=@var{media}
264 This option defines the type of the media: disk or cdrom.
265 @item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
266 These options have the same definition as they have in @option{-hdachs}.
267 @item snapshot=@var{snapshot}
268 @var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
269 @item cache=@var{cache}
270 @var{cache} is "on" or "off" and allows to disable host cache to access data.
271 @item format=@var{format}
272 Specify which disk @var{format} will be used rather than detecting
273 the format. Can be used to specifiy format=raw to avoid interpreting
274 an untrusted format header.
275 @item boot=@var{boot}
276 @var{boot} if "on" enables extboot for a given drive so it can be used as a boot drive.
279 Instead of @option{-cdrom} you can use:
281 qemu -drive file=file,index=2,media=cdrom
284 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
287 qemu -drive file=file,index=0,media=disk
288 qemu -drive file=file,index=1,media=disk
289 qemu -drive file=file,index=2,media=disk
290 qemu -drive file=file,index=3,media=disk
293 You can connect a CDROM to the slave of ide0:
295 qemu -drive file=file,if=ide,index=1,media=cdrom
298 If you don't specify the "file=" argument, you define an empty drive:
300 qemu -drive if=ide,index=1,media=cdrom
303 You can connect a SCSI disk with unit ID 6 on the bus #0:
305 qemu -drive file=file,if=scsi,bus=0,unit=6
308 To boot from a SCSI disk, one would use:
311 qemu -drive file=file,if=scsi,boot=on
314 Instead of @option{-fda}, @option{-fdb}, you can use:
316 qemu -drive file=file,index=0,if=floppy
317 qemu -drive file=file,index=1,if=floppy
320 By default, @var{interface} is "ide" and @var{index} is automatically
323 qemu -drive file=a -drive file=b"
330 @item -boot [a|c|d|n]
331 Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot
335 Write to temporary files instead of disk image files. In this case,
336 the raw disk image you use is not written back. You can however force
337 the write back by pressing @key{C-a s} (@pxref{disk_images}).
340 Disable boot signature checking for floppy disks in Bochs BIOS. It may
341 be needed to boot from old floppy disks.
344 Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB. Optionally,
345 a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
346 gigabytes respectively.
348 @item -cpu @var{model}
349 Select CPU model (-cpu ? for list and additional feature selection)
352 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
353 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
358 Will show the audio subsystem help: list of drivers, tunable
361 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
363 Enable audio and selected sound hardware. Use ? to print all
364 available sound hardware.
367 qemu -soundhw sb16,adlib hda
368 qemu -soundhw es1370 hda
369 qemu -soundhw ac97 hda
370 qemu -soundhw all hda
374 Note that Linux's i810_audio OSS kernel (for AC97) module might
375 require manually specifying clocking.
378 modprobe i810_audio clocking=48000
382 Set the real time clock to local time (the default is to UTC
383 time). This option is needed to have correct date in MS-DOS or
386 @item -startdate @var{date}
387 Set the initial date of the real time clock. Valid format for
388 @var{date} are: @code{now} or @code{2006-06-17T16:01:21} or
389 @code{2006-06-17}. The default value is @code{now}.
391 @item -pidfile @var{file}
392 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
396 Daemonize the QEMU process after initialization. QEMU will not detach from
397 standard IO until it is ready to receive connections on any of its devices.
398 This option is a useful way for external programs to launch QEMU without having
399 to cope with initialization race conditions.
402 Use it when installing Windows 2000 to avoid a disk full bug. After
403 Windows 2000 is installed, you no longer need this option (this option
404 slows down the IDE transfers).
406 @item -option-rom @var{file}
407 Load the contents of @var{file} as an option ROM.
408 This option is useful to load things like EtherBoot.
410 @item -name @var{name}
411 Sets the @var{name} of the guest.
412 This name will be display in the SDL window caption.
413 The @var{name} will also be used for the VNC server.
422 Normally, QEMU uses SDL to display the VGA output. With this option,
423 you can totally disable graphical output so that QEMU is a simple
424 command line application. The emulated serial port is redirected on
425 the console. Therefore, you can still use QEMU to debug a Linux kernel
426 with a serial console.
430 Normally, QEMU uses SDL to display the VGA output. With this option,
431 QEMU can display the VGA output when in text mode using a
432 curses/ncurses interface. Nothing is displayed in graphical mode.
436 Do not use decorations for SDL windows and start them using the whole
437 available screen space. This makes the using QEMU in a dedicated desktop
438 workspace more convenient.
442 Disable SDL window close capability.
445 Start in full screen.
447 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
449 Normally, QEMU uses SDL to display the VGA output. With this option,
450 you can have QEMU listen on VNC display @var{display} and redirect the VGA
451 display over the VNC session. It is very useful to enable the usb
452 tablet device when using this option (option @option{-usbdevice
453 tablet}). When using the VNC display, you must use the @option{-k}
454 parameter to set the keyboard layout if you are not using en-us. Valid
455 syntax for the @var{display} is
459 @item @var{host}:@var{d}
461 TCP connections will only be allowed from @var{host} on display @var{d}.
462 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
463 be omitted in which case the server will accept connections from any host.
465 @item @code{unix}:@var{path}
467 Connections will be allowed over UNIX domain sockets where @var{path} is the
468 location of a unix socket to listen for connections on.
472 VNC is initialized but not started. The monitor @code{change} command
473 can be used to later start the VNC server.
477 Following the @var{display} value there may be one or more @var{option} flags
478 separated by commas. Valid options are
484 Connect to a listening VNC client via a ``reverse'' connection. The
485 client is specified by the @var{display}. For reverse network
486 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
487 is a TCP port number, not a display number.
491 Require that password based authentication is used for client connections.
492 The password must be set separately using the @code{change} command in the
497 Require that client use TLS when communicating with the VNC server. This
498 uses anonymous TLS credentials so is susceptible to a man-in-the-middle
499 attack. It is recommended that this option be combined with either the
500 @var{x509} or @var{x509verify} options.
502 @item x509=@var{/path/to/certificate/dir}
504 Valid if @option{tls} is specified. Require that x509 credentials are used
505 for negotiating the TLS session. The server will send its x509 certificate
506 to the client. It is recommended that a password be set on the VNC server
507 to provide authentication of the client when this is used. The path following
508 this option specifies where the x509 certificates are to be loaded from.
509 See the @ref{vnc_security} section for details on generating certificates.
511 @item x509verify=@var{/path/to/certificate/dir}
513 Valid if @option{tls} is specified. Require that x509 credentials are used
514 for negotiating the TLS session. The server will send its x509 certificate
515 to the client, and request that the client send its own x509 certificate.
516 The server will validate the client's certificate against the CA certificate,
517 and reject clients when validation fails. If the certificate authority is
518 trusted, this is a sufficient authentication mechanism. You may still wish
519 to set a password on the VNC server as a second authentication layer. The
520 path following this option specifies where the x509 certificates are to
521 be loaded from. See the @ref{vnc_security} section for details on generating
526 @item -k @var{language}
528 Use keyboard layout @var{language} (for example @code{fr} for
529 French). This option is only needed where it is not easy to get raw PC
530 keycodes (e.g. on Macs, with some X11 servers or with a VNC
531 display). You don't normally need to use it on PC/Linux or PC/Windows
534 The available layouts are:
536 ar de-ch es fo fr-ca hu ja mk no pt-br sv
537 da en-gb et fr fr-ch is lt nl pl ru th
538 de en-us fi fr-be hr it lv nl-be pt sl tr
541 The default is @code{en-us}.
549 Enable the USB driver (will be the default soon)
551 @item -usbdevice @var{devname}
552 Add the USB device @var{devname}. @xref{usb_devices}.
557 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
560 Pointer device that uses absolute coordinates (like a touchscreen). This
561 means qemu is able to report the mouse position without having to grab the
562 mouse. Also overrides the PS/2 mouse emulation when activated.
564 @item disk:[format=@var{format}]:file
565 Mass storage device based on file. The optional @var{format} argument
566 will be used rather than detecting the format. Can be used to specifiy
567 format=raw to avoid interpreting an untrusted format header.
570 Pass through the host device identified by bus.addr (Linux only).
572 @item host:vendor_id:product_id
573 Pass through the host device identified by vendor_id:product_id (Linux only).
575 @item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
576 Serial converter to host character device @var{dev}, see @code{-serial} for the
580 Braille device. This will use BrlAPI to display the braille output on a real
584 Network adapter that supports CDC ethernet and RNDIS protocols.
594 @item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}]
595 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
596 = 0 is the default). The NIC is an rtl8139 by default on the PC
597 target. Optionally, the MAC address can be changed. If no
598 @option{-net} option is specified, a single NIC is created.
599 Qemu can emulate several different models of network card.
600 Valid values for @var{type} are
601 @code{i82551}, @code{i82557b}, @code{i82559er},
602 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
603 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
604 Not all devices are supported on all targets. Use -net nic,model=?
605 for a list of available devices for your target.
607 @item -net user[,vlan=@var{n}][,hostname=@var{name}]
608 Use the user mode network stack which requires no administrator
609 privilege to run. @option{hostname=name} can be used to specify the client
610 hostname reported by the builtin DHCP server.
612 @item -net tap[,vlan=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}]
613 Connect the host TAP network interface @var{name} to VLAN @var{n} and
614 use the network script @var{file} to configure it. The default
615 network script is @file{/etc/qemu-ifup}. Use @option{script=no} to
616 disable script execution. If @var{name} is not
617 provided, the OS automatically provides one. @option{fd}=@var{h} can be
618 used to specify the handle of an already opened host TAP interface. Example:
621 qemu linux.img -net nic -net tap
624 More complicated example (two NICs, each one connected to a TAP device)
626 qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
627 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
631 @item -net socket[,vlan=@var{n}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
633 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
634 machine using a TCP socket connection. If @option{listen} is
635 specified, QEMU waits for incoming connections on @var{port}
636 (@var{host} is optional). @option{connect} is used to connect to
637 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
638 specifies an already opened TCP socket.
642 # launch a first QEMU instance
643 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
644 -net socket,listen=:1234
645 # connect the VLAN 0 of this instance to the VLAN 0
646 # of the first instance
647 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
648 -net socket,connect=127.0.0.1:1234
651 @item -net socket[,vlan=@var{n}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}]
653 Create a VLAN @var{n} shared with another QEMU virtual
654 machines using a UDP multicast socket, effectively making a bus for
655 every QEMU with same multicast address @var{maddr} and @var{port}.
659 Several QEMU can be running on different hosts and share same bus (assuming
660 correct multicast setup for these hosts).
662 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
663 @url{http://user-mode-linux.sf.net}.
665 Use @option{fd=h} to specify an already opened UDP multicast socket.
670 # launch one QEMU instance
671 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
672 -net socket,mcast=230.0.0.1:1234
673 # launch another QEMU instance on same "bus"
674 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
675 -net socket,mcast=230.0.0.1:1234
676 # launch yet another QEMU instance on same "bus"
677 qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
678 -net socket,mcast=230.0.0.1:1234
681 Example (User Mode Linux compat.):
683 # launch QEMU instance (note mcast address selected
685 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
686 -net socket,mcast=239.192.168.1:1102
688 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
691 @item -net vde[,vlan=@var{n}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
692 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
693 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
694 and MODE @var{octalmode} to change default ownership and permissions for
695 communication port. This option is available only if QEMU has been compiled
696 with vde support enabled.
701 vde_switch -F -sock /tmp/myswitch
702 # launch QEMU instance
703 qemu linux.img -net nic -net vde,sock=/tmp/myswitch
707 Indicate that no network devices should be configured. It is used to
708 override the default configuration (@option{-net nic -net user}) which
709 is activated if no @option{-net} options are provided.
711 @item -tftp @var{dir}
712 When using the user mode network stack, activate a built-in TFTP
713 server. The files in @var{dir} will be exposed as the root of a TFTP server.
714 The TFTP client on the guest must be configured in binary mode (use the command
715 @code{bin} of the Unix TFTP client). The host IP address on the guest is as
718 @item -bootp @var{file}
719 When using the user mode network stack, broadcast @var{file} as the BOOTP
720 filename. In conjunction with @option{-tftp}, this can be used to network boot
721 a guest from a local directory.
723 Example (using pxelinux):
725 qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0
729 When using the user mode network stack, activate a built-in SMB
730 server so that Windows OSes can access to the host files in @file{@var{dir}}
733 In the guest Windows OS, the line:
737 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
738 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
740 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
742 Note that a SAMBA server must be installed on the host OS in
743 @file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version
744 2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
746 @item -redir [tcp|udp]:@var{host-port}:[@var{guest-host}]:@var{guest-port}
748 When using the user mode network stack, redirect incoming TCP or UDP
749 connections to the host port @var{host-port} to the guest
750 @var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
751 is not specified, its value is 10.0.2.15 (default address given by the
752 built-in DHCP server).
754 For example, to redirect host X11 connection from screen 1 to guest
755 screen 0, use the following:
759 qemu -redir tcp:6001::6000 [...]
760 # this host xterm should open in the guest X11 server
764 To redirect telnet connections from host port 5555 to telnet port on
765 the guest, use the following:
769 qemu -redir tcp:5555::23 [...]
770 telnet localhost 5555
773 Then when you use on the host @code{telnet localhost 5555}, you
774 connect to the guest telnet server.
778 Linux boot specific: When using these options, you can use a given
779 Linux kernel without installing it in the disk image. It can be useful
780 for easier testing of various kernels.
784 @item -kernel @var{bzImage}
785 Use @var{bzImage} as kernel image.
787 @item -append @var{cmdline}
788 Use @var{cmdline} as kernel command line
790 @item -initrd @var{file}
791 Use @var{file} as initial ram disk.
795 Debug/Expert options:
798 @item -serial @var{dev}
799 Redirect the virtual serial port to host character device
800 @var{dev}. The default device is @code{vc} in graphical mode and
801 @code{stdio} in non graphical mode.
803 This option can be used several times to simulate up to 4 serials
806 Use @code{-serial none} to disable all serial ports.
808 Available character devices are:
811 Virtual console. Optionally, a width and height can be given in pixel with
815 It is also possible to specify width or height in characters:
820 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
822 No device is allocated.
826 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
827 parameters are set according to the emulated ones.
828 @item /dev/parport@var{N}
829 [Linux only, parallel port only] Use host parallel port
830 @var{N}. Currently SPP and EPP parallel port features can be used.
831 @item file:@var{filename}
832 Write output to @var{filename}. No character can be read.
834 [Unix only] standard input/output
835 @item pipe:@var{filename}
836 name pipe @var{filename}
838 [Windows only] Use host serial port @var{n}
839 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
840 This implements UDP Net Console.
841 When @var{remote_host} or @var{src_ip} are not specified
842 they default to @code{0.0.0.0}.
843 When not using a specified @var{src_port} a random port is automatically chosen.
845 If you just want a simple readonly console you can use @code{netcat} or
846 @code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
847 @code{nc -u -l -p 4555}. Any time qemu writes something to that port it
848 will appear in the netconsole session.
850 If you plan to send characters back via netconsole or you want to stop
851 and start qemu a lot of times, you should have qemu use the same
852 source port each time by using something like @code{-serial
853 udp::4555@@:4556} to qemu. Another approach is to use a patched
854 version of netcat which can listen to a TCP port and send and receive
855 characters via udp. If you have a patched version of netcat which
856 activates telnet remote echo and single char transfer, then you can
857 use the following options to step up a netcat redirector to allow
858 telnet on port 5555 to access the qemu port.
861 -serial udp::4555@@:4556
862 @item netcat options:
863 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
864 @item telnet options:
869 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
870 The TCP Net Console has two modes of operation. It can send the serial
871 I/O to a location or wait for a connection from a location. By default
872 the TCP Net Console is sent to @var{host} at the @var{port}. If you use
873 the @var{server} option QEMU will wait for a client socket application
874 to connect to the port before continuing, unless the @code{nowait}
875 option was specified. The @code{nodelay} option disables the Nagle buffering
876 algorithm. If @var{host} is omitted, 0.0.0.0 is assumed. Only
877 one TCP connection at a time is accepted. You can use @code{telnet} to
878 connect to the corresponding character device.
880 @item Example to send tcp console to 192.168.0.2 port 4444
881 -serial tcp:192.168.0.2:4444
882 @item Example to listen and wait on port 4444 for connection
883 -serial tcp::4444,server
884 @item Example to not wait and listen on ip 192.168.0.100 port 4444
885 -serial tcp:192.168.0.100:4444,server,nowait
888 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
889 The telnet protocol is used instead of raw tcp sockets. The options
890 work the same as if you had specified @code{-serial tcp}. The
891 difference is that the port acts like a telnet server or client using
892 telnet option negotiation. This will also allow you to send the
893 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
894 sequence. Typically in unix telnet you do it with Control-] and then
895 type "send break" followed by pressing the enter key.
897 @item unix:@var{path}[,server][,nowait]
898 A unix domain socket is used instead of a tcp socket. The option works the
899 same as if you had specified @code{-serial tcp} except the unix domain socket
900 @var{path} is used for connections.
902 @item mon:@var{dev_string}
903 This is a special option to allow the monitor to be multiplexed onto
904 another serial port. The monitor is accessed with key sequence of
905 @key{Control-a} and then pressing @key{c}. See monitor access
906 @ref{pcsys_keys} in the -nographic section for more keys.
907 @var{dev_string} should be any one of the serial devices specified
908 above. An example to multiplex the monitor onto a telnet server
909 listening on port 4444 would be:
911 @item -serial mon:telnet::4444,server,nowait
915 Braille device. This will use BrlAPI to display the braille output on a real
920 @item -parallel @var{dev}
921 Redirect the virtual parallel port to host device @var{dev} (same
922 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
923 be used to use hardware devices connected on the corresponding host
926 This option can be used several times to simulate up to 3 parallel
929 Use @code{-parallel none} to disable all parallel ports.
931 @item -monitor @var{dev}
932 Redirect the monitor to host device @var{dev} (same devices as the
934 The default device is @code{vc} in graphical mode and @code{stdio} in
937 @item -echr numeric_ascii_value
938 Change the escape character used for switching to the monitor when using
939 monitor and serial sharing. The default is @code{0x01} when using the
940 @code{-nographic} option. @code{0x01} is equal to pressing
941 @code{Control-a}. You can select a different character from the ascii
942 control keys where 1 through 26 map to Control-a through Control-z. For
943 instance you could use the either of the following to change the escape
944 character to Control-t.
951 Wait gdb connection to port 1234 (@pxref{gdb_usage}).
953 Change gdb connection port. @var{port} can be either a decimal number
954 to specify a TCP port, or a host device (same devices as the serial port).
956 Do not start CPU at startup (you must type 'c' in the monitor).
958 Output log in /tmp/qemu.log
959 @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
960 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
961 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
962 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
963 all those parameters. This option is useful for old MS-DOS disk
967 Set the directory for the BIOS, VGA BIOS and keymaps.
969 @item -vga @var{type}
970 Select type of VGA card to emulate. Valid values for @var{type} are
973 Cirrus Logic GD5446 Video card. All Windows versions starting from
974 Windows 95 should recognize and use this graphic card. For optimal
975 performances, use 16 bit color depth in the guest and the host OS.
976 (This one is the default)
978 Standard VGA card with Bochs VBE extensions. If your guest OS
979 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
980 to use high resolution modes (>= 1280x1024x16) then you should use
983 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
984 recent XFree86/XOrg server or Windows guest with a driver for this
989 Disable ACPI (Advanced Configuration and Power Interface) support. Use
990 it if your guest OS complains about ACPI problems (PC target machine
994 Exit instead of rebooting.
997 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
998 This allows for instance switching to monitor to commit changes to the
1002 Start right away with a saved state (@code{loadvm} in monitor)
1005 Enable semihosting syscall emulation (ARM and M68K target machines only).
1007 On ARM this implements the "Angel" interface.
1008 On M68K this implements the "ColdFire GDB" interface used by libgloss.
1010 Note that this allows guest direct access to the host filesystem,
1011 so should only be used with trusted guest OS.
1013 @item -icount [N|auto]
1014 Enable virtual instruction counter. The virtual cpu will execute one
1015 instruction every 2^N ns of virtual time. If @code{auto} is specified
1016 then the virtual cpu speed will be automatically adjusted to keep virtual
1017 time within a few seconds of real time.
1019 Note that while this option can give deterministic behavior, it does not
1020 provide cycle accurate emulation. Modern CPUs contain superscalar out of
1021 order cores with complex cache hierarchies. The number of instructions
1022 executed often has little or no correlation with actual performance.
1030 @c man begin OPTIONS
1032 During the graphical emulation, you can use the following keys:
1038 Switch to virtual console 'n'. Standard console mappings are:
1041 Target system display
1049 Toggle mouse and keyboard grab.
1052 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
1053 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
1055 During emulation, if you are using the @option{-nographic} option, use
1056 @key{Ctrl-a h} to get terminal commands:
1064 Save disk data back to file (if -snapshot)
1066 toggle console timestamps
1068 Send break (magic sysrq in Linux)
1070 Switch between console and monitor
1078 @c man begin SEEALSO
1079 The HTML documentation of QEMU for more precise information and Linux
1080 user mode emulator invocation.
1090 @section QEMU Monitor
1092 The QEMU monitor is used to give complex commands to the QEMU
1093 emulator. You can use it to:
1098 Remove or insert removable media images
1099 (such as CD-ROM or floppies).
1102 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
1105 @item Inspect the VM state without an external debugger.
1109 @subsection Commands
1111 The following commands are available:
1115 @item help or ? [@var{cmd}]
1116 Show the help for all commands or just for command @var{cmd}.
1119 Commit changes to the disk images (if -snapshot is used).
1121 @item info @var{subcommand}
1122 Show various information about the system state.
1126 show the various VLANs and the associated devices
1128 show the block devices
1129 @item info registers
1130 show the cpu registers
1132 show the command line history
1134 show emulated PCI device
1136 show USB devices plugged on the virtual USB hub
1138 show all USB host devices
1140 show information about active capturing
1141 @item info snapshots
1142 show list of VM snapshots
1144 show which guest mouse is receiving events
1150 @item eject [-f] @var{device}
1151 Eject a removable medium (use -f to force it).
1153 @item change @var{device} @var{setting}
1155 Change the configuration of a device.
1158 @item change @var{diskdevice} @var{filename}
1159 Change the medium for a removable disk device to point to @var{filename}. eg
1162 (qemu) change ide1-cd0 /path/to/some.iso
1165 @item change vnc @var{display},@var{options}
1166 Change the configuration of the VNC server. The valid syntax for @var{display}
1167 and @var{options} are described at @ref{sec_invocation}. eg
1170 (qemu) change vnc localhost:1
1173 @item change vnc password
1175 Change the password associated with the VNC server. The monitor will prompt for
1176 the new password to be entered. VNC passwords are only significant upto 8 letters.
1180 (qemu) change vnc password
1186 @item screendump @var{filename}
1187 Save screen into PPM image @var{filename}.
1189 @item mouse_move @var{dx} @var{dy} [@var{dz}]
1190 Move the active mouse to the specified coordinates @var{dx} @var{dy}
1191 with optional scroll axis @var{dz}.
1193 @item mouse_button @var{val}
1194 Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
1196 @item mouse_set @var{index}
1197 Set which mouse device receives events at given @var{index}, index
1198 can be obtained with
1203 @item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
1204 Capture audio into @var{filename}. Using sample rate @var{frequency}
1205 bits per sample @var{bits} and number of channels @var{channels}.
1209 @item Sample rate = 44100 Hz - CD quality
1211 @item Number of channels = 2 - Stereo
1214 @item stopcapture @var{index}
1215 Stop capture with a given @var{index}, index can be obtained with
1220 @item log @var{item1}[,...]
1221 Activate logging of the specified items to @file{/tmp/qemu.log}.
1223 @item savevm [@var{tag}|@var{id}]
1224 Create a snapshot of the whole virtual machine. If @var{tag} is
1225 provided, it is used as human readable identifier. If there is already
1226 a snapshot with the same tag or ID, it is replaced. More info at
1229 @item loadvm @var{tag}|@var{id}
1230 Set the whole virtual machine to the snapshot identified by the tag
1231 @var{tag} or the unique snapshot ID @var{id}.
1233 @item delvm @var{tag}|@var{id}
1234 Delete the snapshot identified by @var{tag} or @var{id}.
1242 @item gdbserver [@var{port}]
1243 Start gdbserver session (default @var{port}=1234)
1245 @item x/fmt @var{addr}
1246 Virtual memory dump starting at @var{addr}.
1248 @item xp /@var{fmt} @var{addr}
1249 Physical memory dump starting at @var{addr}.
1251 @var{fmt} is a format which tells the command how to format the
1252 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
1256 is the number of items to be dumped.
1259 can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
1260 c (char) or i (asm instruction).
1263 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
1264 @code{h} or @code{w} can be specified with the @code{i} format to
1265 respectively select 16 or 32 bit code instruction size.
1272 Dump 10 instructions at the current instruction pointer:
1277 0x90107065: lea 0x0(%esi,1),%esi
1278 0x90107069: lea 0x0(%edi,1),%edi
1280 0x90107071: jmp 0x90107080
1288 Dump 80 16 bit values at the start of the video memory.
1290 (qemu) xp/80hx 0xb8000
1291 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
1292 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
1293 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
1294 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
1295 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
1296 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
1297 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1298 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1299 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1300 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
1304 @item p or print/@var{fmt} @var{expr}
1306 Print expression value. Only the @var{format} part of @var{fmt} is
1309 @item sendkey @var{keys}
1311 Send @var{keys} to the emulator. @var{keys} could be the name of the
1312 key or @code{#} followed by the raw value in either decimal or hexadecimal
1313 format. Use @code{-} to press several keys simultaneously. Example:
1318 This command is useful to send keys that your graphical user interface
1319 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
1325 @item boot_set @var{bootdevicelist}
1327 Define new values for the boot device list. Those values will override
1328 the values specified on the command line through the @code{-boot} option.
1330 The values that can be specified here depend on the machine type, but are
1331 the same that can be specified in the @code{-boot} command line option.
1333 @item usb_add @var{devname}
1335 Add the USB device @var{devname}. For details of available devices see
1338 @item usb_del @var{devname}
1340 Remove the USB device @var{devname} from the QEMU virtual USB
1341 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
1342 command @code{info usb} to see the devices you can remove.
1346 @subsection Integer expressions
1348 The monitor understands integers expressions for every integer
1349 argument. You can use register names to get the value of specifics
1350 CPU registers by prefixing them with @emph{$}.
1353 @section Disk Images
1355 Since version 0.6.1, QEMU supports many disk image formats, including
1356 growable disk images (their size increase as non empty sectors are
1357 written), compressed and encrypted disk images. Version 0.8.3 added
1358 the new qcow2 disk image format which is essential to support VM
1362 * disk_images_quickstart:: Quick start for disk image creation
1363 * disk_images_snapshot_mode:: Snapshot mode
1364 * vm_snapshots:: VM snapshots
1365 * qemu_img_invocation:: qemu-img Invocation
1366 * qemu_nbd_invocation:: qemu-nbd Invocation
1367 * host_drives:: Using host drives
1368 * disk_images_fat_images:: Virtual FAT disk images
1369 * disk_images_nbd:: NBD access
1372 @node disk_images_quickstart
1373 @subsection Quick start for disk image creation
1375 You can create a disk image with the command:
1377 qemu-img create myimage.img mysize
1379 where @var{myimage.img} is the disk image filename and @var{mysize} is its
1380 size in kilobytes. You can add an @code{M} suffix to give the size in
1381 megabytes and a @code{G} suffix for gigabytes.
1383 See @ref{qemu_img_invocation} for more information.
1385 @node disk_images_snapshot_mode
1386 @subsection Snapshot mode
1388 If you use the option @option{-snapshot}, all disk images are
1389 considered as read only. When sectors in written, they are written in
1390 a temporary file created in @file{/tmp}. You can however force the
1391 write back to the raw disk images by using the @code{commit} monitor
1392 command (or @key{C-a s} in the serial console).
1395 @subsection VM snapshots
1397 VM snapshots are snapshots of the complete virtual machine including
1398 CPU state, RAM, device state and the content of all the writable
1399 disks. In order to use VM snapshots, you must have at least one non
1400 removable and writable block device using the @code{qcow2} disk image
1401 format. Normally this device is the first virtual hard drive.
1403 Use the monitor command @code{savevm} to create a new VM snapshot or
1404 replace an existing one. A human readable name can be assigned to each
1405 snapshot in addition to its numerical ID.
1407 Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
1408 a VM snapshot. @code{info snapshots} lists the available snapshots
1409 with their associated information:
1412 (qemu) info snapshots
1413 Snapshot devices: hda
1414 Snapshot list (from hda):
1415 ID TAG VM SIZE DATE VM CLOCK
1416 1 start 41M 2006-08-06 12:38:02 00:00:14.954
1417 2 40M 2006-08-06 12:43:29 00:00:18.633
1418 3 msys 40M 2006-08-06 12:44:04 00:00:23.514
1421 A VM snapshot is made of a VM state info (its size is shown in
1422 @code{info snapshots}) and a snapshot of every writable disk image.
1423 The VM state info is stored in the first @code{qcow2} non removable
1424 and writable block device. The disk image snapshots are stored in
1425 every disk image. The size of a snapshot in a disk image is difficult
1426 to evaluate and is not shown by @code{info snapshots} because the
1427 associated disk sectors are shared among all the snapshots to save
1428 disk space (otherwise each snapshot would need a full copy of all the
1431 When using the (unrelated) @code{-snapshot} option
1432 (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
1433 but they are deleted as soon as you exit QEMU.
1435 VM snapshots currently have the following known limitations:
1438 They cannot cope with removable devices if they are removed or
1439 inserted after a snapshot is done.
1441 A few device drivers still have incomplete snapshot support so their
1442 state is not saved or restored properly (in particular USB).
1445 @node qemu_img_invocation
1446 @subsection @code{qemu-img} Invocation
1448 @include qemu-img.texi
1450 @node qemu_nbd_invocation
1451 @subsection @code{qemu-nbd} Invocation
1453 @include qemu-nbd.texi
1456 @subsection Using host drives
1458 In addition to disk image files, QEMU can directly access host
1459 devices. We describe here the usage for QEMU version >= 0.8.3.
1461 @subsubsection Linux
1463 On Linux, you can directly use the host device filename instead of a
1464 disk image filename provided you have enough privileges to access
1465 it. For example, use @file{/dev/cdrom} to access to the CDROM or
1466 @file{/dev/fd0} for the floppy.
1470 You can specify a CDROM device even if no CDROM is loaded. QEMU has
1471 specific code to detect CDROM insertion or removal. CDROM ejection by
1472 the guest OS is supported. Currently only data CDs are supported.
1474 You can specify a floppy device even if no floppy is loaded. Floppy
1475 removal is currently not detected accurately (if you change floppy
1476 without doing floppy access while the floppy is not loaded, the guest
1477 OS will think that the same floppy is loaded).
1479 Hard disks can be used. Normally you must specify the whole disk
1480 (@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
1481 see it as a partitioned disk. WARNING: unless you know what you do, it
1482 is better to only make READ-ONLY accesses to the hard disk otherwise
1483 you may corrupt your host data (use the @option{-snapshot} command
1484 line option or modify the device permissions accordingly).
1487 @subsubsection Windows
1491 The preferred syntax is the drive letter (e.g. @file{d:}). The
1492 alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
1493 supported as an alias to the first CDROM drive.
1495 Currently there is no specific code to handle removable media, so it
1496 is better to use the @code{change} or @code{eject} monitor commands to
1497 change or eject media.
1499 Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
1500 where @var{N} is the drive number (0 is the first hard disk).
1502 WARNING: unless you know what you do, it is better to only make
1503 READ-ONLY accesses to the hard disk otherwise you may corrupt your
1504 host data (use the @option{-snapshot} command line so that the
1505 modifications are written in a temporary file).
1509 @subsubsection Mac OS X
1511 @file{/dev/cdrom} is an alias to the first CDROM.
1513 Currently there is no specific code to handle removable media, so it
1514 is better to use the @code{change} or @code{eject} monitor commands to
1515 change or eject media.
1517 @node disk_images_fat_images
1518 @subsection Virtual FAT disk images
1520 QEMU can automatically create a virtual FAT disk image from a
1521 directory tree. In order to use it, just type:
1524 qemu linux.img -hdb fat:/my_directory
1527 Then you access access to all the files in the @file{/my_directory}
1528 directory without having to copy them in a disk image or to export
1529 them via SAMBA or NFS. The default access is @emph{read-only}.
1531 Floppies can be emulated with the @code{:floppy:} option:
1534 qemu linux.img -fda fat:floppy:/my_directory
1537 A read/write support is available for testing (beta stage) with the
1541 qemu linux.img -fda fat:floppy:rw:/my_directory
1544 What you should @emph{never} do:
1546 @item use non-ASCII filenames ;
1547 @item use "-snapshot" together with ":rw:" ;
1548 @item expect it to work when loadvm'ing ;
1549 @item write to the FAT directory on the host system while accessing it with the guest system.
1552 @node disk_images_nbd
1553 @subsection NBD access
1555 QEMU can access directly to block device exported using the Network Block Device
1559 qemu linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
1562 If the NBD server is located on the same host, you can use an unix socket instead
1566 qemu linux.img -hdb nbd:unix:/tmp/my_socket
1569 In this case, the block device must be exported using qemu-nbd:
1572 qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
1575 The use of qemu-nbd allows to share a disk between several guests:
1577 qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
1580 and then you can use it with two guests:
1582 qemu linux1.img -hdb nbd:unix:/tmp/my_socket
1583 qemu linux2.img -hdb nbd:unix:/tmp/my_socket
1587 @section Network emulation
1589 QEMU can simulate several network cards (PCI or ISA cards on the PC
1590 target) and can connect them to an arbitrary number of Virtual Local
1591 Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1592 VLAN. VLAN can be connected between separate instances of QEMU to
1593 simulate large networks. For simpler usage, a non privileged user mode
1594 network stack can replace the TAP device to have a basic network
1599 QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1600 connection between several network devices. These devices can be for
1601 example QEMU virtual Ethernet cards or virtual Host ethernet devices
1604 @subsection Using TAP network interfaces
1606 This is the standard way to connect QEMU to a real network. QEMU adds
1607 a virtual network device on your host (called @code{tapN}), and you
1608 can then configure it as if it was a real ethernet card.
1610 @subsubsection Linux host
1612 As an example, you can download the @file{linux-test-xxx.tar.gz}
1613 archive and copy the script @file{qemu-ifup} in @file{/etc} and
1614 configure properly @code{sudo} so that the command @code{ifconfig}
1615 contained in @file{qemu-ifup} can be executed as root. You must verify
1616 that your host kernel supports the TAP network interfaces: the
1617 device @file{/dev/net/tun} must be present.
1619 See @ref{sec_invocation} to have examples of command lines using the
1620 TAP network interfaces.
1622 @subsubsection Windows host
1624 There is a virtual ethernet driver for Windows 2000/XP systems, called
1625 TAP-Win32. But it is not included in standard QEMU for Windows,
1626 so you will need to get it separately. It is part of OpenVPN package,
1627 so download OpenVPN from : @url{http://openvpn.net/}.
1629 @subsection Using the user mode network stack
1631 By using the option @option{-net user} (default configuration if no
1632 @option{-net} option is specified), QEMU uses a completely user mode
1633 network stack (you don't need root privilege to use the virtual
1634 network). The virtual network configuration is the following:
1638 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
1641 ----> DNS server (10.0.2.3)
1643 ----> SMB server (10.0.2.4)
1646 The QEMU VM behaves as if it was behind a firewall which blocks all
1647 incoming connections. You can use a DHCP client to automatically
1648 configure the network in the QEMU VM. The DHCP server assign addresses
1649 to the hosts starting from 10.0.2.15.
1651 In order to check that the user mode network is working, you can ping
1652 the address 10.0.2.2 and verify that you got an address in the range
1653 10.0.2.x from the QEMU virtual DHCP server.
1655 Note that @code{ping} is not supported reliably to the internet as it
1656 would require root privileges. It means you can only ping the local
1659 When using the built-in TFTP server, the router is also the TFTP
1662 When using the @option{-redir} option, TCP or UDP connections can be
1663 redirected from the host to the guest. It allows for example to
1664 redirect X11, telnet or SSH connections.
1666 @subsection Connecting VLANs between QEMU instances
1668 Using the @option{-net socket} option, it is possible to make VLANs
1669 that span several QEMU instances. See @ref{sec_invocation} to have a
1672 @node direct_linux_boot
1673 @section Direct Linux Boot
1675 This section explains how to launch a Linux kernel inside QEMU without
1676 having to make a full bootable image. It is very useful for fast Linux
1681 qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1684 Use @option{-kernel} to provide the Linux kernel image and
1685 @option{-append} to give the kernel command line arguments. The
1686 @option{-initrd} option can be used to provide an INITRD image.
1688 When using the direct Linux boot, a disk image for the first hard disk
1689 @file{hda} is required because its boot sector is used to launch the
1692 If you do not need graphical output, you can disable it and redirect
1693 the virtual serial port and the QEMU monitor to the console with the
1694 @option{-nographic} option. The typical command line is:
1696 qemu -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1697 -append "root=/dev/hda console=ttyS0" -nographic
1700 Use @key{Ctrl-a c} to switch between the serial console and the
1701 monitor (@pxref{pcsys_keys}).
1704 @section USB emulation
1706 QEMU emulates a PCI UHCI USB controller. You can virtually plug
1707 virtual USB devices or real host USB devices (experimental, works only
1708 on Linux hosts). Qemu will automatically create and connect virtual USB hubs
1709 as necessary to connect multiple USB devices.
1713 * host_usb_devices::
1716 @subsection Connecting USB devices
1718 USB devices can be connected with the @option{-usbdevice} commandline option
1719 or the @code{usb_add} monitor command. Available devices are:
1723 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
1725 Pointer device that uses absolute coordinates (like a touchscreen).
1726 This means qemu is able to report the mouse position without having
1727 to grab the mouse. Also overrides the PS/2 mouse emulation when activated.
1728 @item disk:@var{file}
1729 Mass storage device based on @var{file} (@pxref{disk_images})
1730 @item host:@var{bus.addr}
1731 Pass through the host device identified by @var{bus.addr}
1733 @item host:@var{vendor_id:product_id}
1734 Pass through the host device identified by @var{vendor_id:product_id}
1737 Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet}
1738 above but it can be used with the tslib library because in addition to touch
1739 coordinates it reports touch pressure.
1741 Standard USB keyboard. Will override the PS/2 keyboard (if present).
1742 @item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev}
1743 Serial converter. This emulates an FTDI FT232BM chip connected to host character
1744 device @var{dev}. The available character devices are the same as for the
1745 @code{-serial} option. The @code{vendorid} and @code{productid} options can be
1746 used to override the default 0403:6001. For instance,
1748 usb_add serial:productid=FA00:tcp:192.168.0.2:4444
1750 will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual
1751 serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00).
1753 Braille device. This will use BrlAPI to display the braille output on a real
1755 @item net:@var{options}
1756 Network adapter that supports CDC ethernet and RNDIS protocols. @var{options}
1757 specifies NIC options as with @code{-net nic,}@var{options} (see description).
1758 For instance, user-mode networking can be used with
1760 qemu [...OPTIONS...] -net user,vlan=0 -usbdevice net:vlan=0
1762 Currently this cannot be used in machines that support PCI NICs.
1765 @node host_usb_devices
1766 @subsection Using host USB devices on a Linux host
1768 WARNING: this is an experimental feature. QEMU will slow down when
1769 using it. USB devices requiring real time streaming (i.e. USB Video
1770 Cameras) are not supported yet.
1773 @item If you use an early Linux 2.4 kernel, verify that no Linux driver
1774 is actually using the USB device. A simple way to do that is simply to
1775 disable the corresponding kernel module by renaming it from @file{mydriver.o}
1776 to @file{mydriver.o.disabled}.
1778 @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1784 @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:
1786 chown -R myuid /proc/bus/usb
1789 @item Launch QEMU and do in the monitor:
1792 Device 1.2, speed 480 Mb/s
1793 Class 00: USB device 1234:5678, USB DISK
1795 You should see the list of the devices you can use (Never try to use
1796 hubs, it won't work).
1798 @item Add the device in QEMU by using:
1800 usb_add host:1234:5678
1803 Normally the guest OS should report that a new USB device is
1804 plugged. You can use the option @option{-usbdevice} to do the same.
1806 @item Now you can try to use the host USB device in QEMU.
1810 When relaunching QEMU, you may have to unplug and plug again the USB
1811 device to make it work again (this is a bug).
1814 @section VNC security
1816 The VNC server capability provides access to the graphical console
1817 of the guest VM across the network. This has a number of security
1818 considerations depending on the deployment scenarios.
1822 * vnc_sec_password::
1823 * vnc_sec_certificate::
1824 * vnc_sec_certificate_verify::
1825 * vnc_sec_certificate_pw::
1826 * vnc_generate_cert::
1829 @subsection Without passwords
1831 The simplest VNC server setup does not include any form of authentication.
1832 For this setup it is recommended to restrict it to listen on a UNIX domain
1833 socket only. For example
1836 qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1839 This ensures that only users on local box with read/write access to that
1840 path can access the VNC server. To securely access the VNC server from a
1841 remote machine, a combination of netcat+ssh can be used to provide a secure
1844 @node vnc_sec_password
1845 @subsection With passwords
1847 The VNC protocol has limited support for password based authentication. Since
1848 the protocol limits passwords to 8 characters it should not be considered
1849 to provide high security. The password can be fairly easily brute-forced by
1850 a client making repeat connections. For this reason, a VNC server using password
1851 authentication should be restricted to only listen on the loopback interface
1852 or UNIX domain sockets. Password authentication is requested with the @code{password}
1853 option, and then once QEMU is running the password is set with the monitor. Until
1854 the monitor is used to set the password all clients will be rejected.
1857 qemu [...OPTIONS...] -vnc :1,password -monitor stdio
1858 (qemu) change vnc password
1863 @node vnc_sec_certificate
1864 @subsection With x509 certificates
1866 The QEMU VNC server also implements the VeNCrypt extension allowing use of
1867 TLS for encryption of the session, and x509 certificates for authentication.
1868 The use of x509 certificates is strongly recommended, because TLS on its
1869 own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1870 support provides a secure session, but no authentication. This allows any
1871 client to connect, and provides an encrypted session.
1874 qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio
1877 In the above example @code{/etc/pki/qemu} should contain at least three files,
1878 @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1879 users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1880 NB the @code{server-key.pem} file should be protected with file mode 0600 to
1881 only be readable by the user owning it.
1883 @node vnc_sec_certificate_verify
1884 @subsection With x509 certificates and client verification
1886 Certificates can also provide a means to authenticate the client connecting.
1887 The server will request that the client provide a certificate, which it will
1888 then validate against the CA certificate. This is a good choice if deploying
1889 in an environment with a private internal certificate authority.
1892 qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio
1896 @node vnc_sec_certificate_pw
1897 @subsection With x509 certificates, client verification and passwords
1899 Finally, the previous method can be combined with VNC password authentication
1900 to provide two layers of authentication for clients.
1903 qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio
1904 (qemu) change vnc password
1909 @node vnc_generate_cert
1910 @subsection Generating certificates for VNC
1912 The GNU TLS packages provides a command called @code{certtool} which can
1913 be used to generate certificates and keys in PEM format. At a minimum it
1914 is neccessary to setup a certificate authority, and issue certificates to
1915 each server. If using certificates for authentication, then each client
1916 will also need to be issued a certificate. The recommendation is for the
1917 server to keep its certificates in either @code{/etc/pki/qemu} or for
1918 unprivileged users in @code{$HOME/.pki/qemu}.
1922 * vnc_generate_server::
1923 * vnc_generate_client::
1925 @node vnc_generate_ca
1926 @subsubsection Setup the Certificate Authority
1928 This step only needs to be performed once per organization / organizational
1929 unit. First the CA needs a private key. This key must be kept VERY secret
1930 and secure. If this key is compromised the entire trust chain of the certificates
1931 issued with it is lost.
1934 # certtool --generate-privkey > ca-key.pem
1937 A CA needs to have a public certificate. For simplicity it can be a self-signed
1938 certificate, or one issue by a commercial certificate issuing authority. To
1939 generate a self-signed certificate requires one core piece of information, the
1940 name of the organization.
1943 # cat > ca.info <<EOF
1944 cn = Name of your organization
1948 # certtool --generate-self-signed \
1949 --load-privkey ca-key.pem
1950 --template ca.info \
1951 --outfile ca-cert.pem
1954 The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize
1955 TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.
1957 @node vnc_generate_server
1958 @subsubsection Issuing server certificates
1960 Each server (or host) needs to be issued with a key and certificate. When connecting
1961 the certificate is sent to the client which validates it against the CA certificate.
1962 The core piece of information for a server certificate is the hostname. This should
1963 be the fully qualified hostname that the client will connect with, since the client
1964 will typically also verify the hostname in the certificate. On the host holding the
1965 secure CA private key:
1968 # cat > server.info <<EOF
1969 organization = Name of your organization
1970 cn = server.foo.example.com
1975 # certtool --generate-privkey > server-key.pem
1976 # certtool --generate-certificate \
1977 --load-ca-certificate ca-cert.pem \
1978 --load-ca-privkey ca-key.pem \
1979 --load-privkey server server-key.pem \
1980 --template server.info \
1981 --outfile server-cert.pem
1984 The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied
1985 to the server for which they were generated. The @code{server-key.pem} is security
1986 sensitive and should be kept protected with file mode 0600 to prevent disclosure.
1988 @node vnc_generate_client
1989 @subsubsection Issuing client certificates
1991 If the QEMU VNC server is to use the @code{x509verify} option to validate client
1992 certificates as its authentication mechanism, each client also needs to be issued
1993 a certificate. The client certificate contains enough metadata to uniquely identify
1994 the client, typically organization, state, city, building, etc. On the host holding
1995 the secure CA private key:
1998 # cat > client.info <<EOF
2002 organiazation = Name of your organization
2003 cn = client.foo.example.com
2008 # certtool --generate-privkey > client-key.pem
2009 # certtool --generate-certificate \
2010 --load-ca-certificate ca-cert.pem \
2011 --load-ca-privkey ca-key.pem \
2012 --load-privkey client-key.pem \
2013 --template client.info \
2014 --outfile client-cert.pem
2017 The @code{client-key.pem} and @code{client-cert.pem} files should now be securely
2018 copied to the client for which they were generated.
2023 QEMU has a primitive support to work with gdb, so that you can do
2024 'Ctrl-C' while the virtual machine is running and inspect its state.
2026 In order to use gdb, launch qemu with the '-s' option. It will wait for a
2029 > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
2030 -append "root=/dev/hda"
2031 Connected to host network interface: tun0
2032 Waiting gdb connection on port 1234
2035 Then launch gdb on the 'vmlinux' executable:
2040 In gdb, connect to QEMU:
2042 (gdb) target remote localhost:1234
2045 Then you can use gdb normally. For example, type 'c' to launch the kernel:
2050 Here are some useful tips in order to use gdb on system code:
2054 Use @code{info reg} to display all the CPU registers.
2056 Use @code{x/10i $eip} to display the code at the PC position.
2058 Use @code{set architecture i8086} to dump 16 bit code. Then use
2059 @code{x/10i $cs*16+$eip} to dump the code at the PC position.
2062 Advanced debugging options:
2064 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 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:
2066 @item maintenance packet qqemu.sstepbits
2068 This will display the MASK bits used to control the single stepping IE:
2070 (gdb) maintenance packet qqemu.sstepbits
2071 sending: "qqemu.sstepbits"
2072 received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
2074 @item maintenance packet qqemu.sstep
2076 This will display the current value of the mask used when single stepping IE:
2078 (gdb) maintenance packet qqemu.sstep
2079 sending: "qqemu.sstep"
2082 @item maintenance packet Qqemu.sstep=HEX_VALUE
2084 This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
2086 (gdb) maintenance packet Qqemu.sstep=0x5
2087 sending: "qemu.sstep=0x5"
2092 @node pcsys_os_specific
2093 @section Target OS specific information
2097 To have access to SVGA graphic modes under X11, use the @code{vesa} or
2098 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
2099 color depth in the guest and the host OS.
2101 When using a 2.6 guest Linux kernel, you should add the option
2102 @code{clock=pit} on the kernel command line because the 2.6 Linux
2103 kernels make very strict real time clock checks by default that QEMU
2104 cannot simulate exactly.
2106 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
2107 not activated because QEMU is slower with this patch. The QEMU
2108 Accelerator Module is also much slower in this case. Earlier Fedora
2109 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
2110 patch by default. Newer kernels don't have it.
2114 If you have a slow host, using Windows 95 is better as it gives the
2115 best speed. Windows 2000 is also a good choice.
2117 @subsubsection SVGA graphic modes support
2119 QEMU emulates a Cirrus Logic GD5446 Video
2120 card. All Windows versions starting from Windows 95 should recognize
2121 and use this graphic card. For optimal performances, use 16 bit color
2122 depth in the guest and the host OS.
2124 If you are using Windows XP as guest OS and if you want to use high
2125 resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
2126 1280x1024x16), then you should use the VESA VBE virtual graphic card
2127 (option @option{-std-vga}).
2129 @subsubsection CPU usage reduction
2131 Windows 9x does not correctly use the CPU HLT
2132 instruction. The result is that it takes host CPU cycles even when
2133 idle. You can install the utility from
2134 @url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
2135 problem. Note that no such tool is needed for NT, 2000 or XP.
2137 @subsubsection Windows 2000 disk full problem
2139 Windows 2000 has a bug which gives a disk full problem during its
2140 installation. When installing it, use the @option{-win2k-hack} QEMU
2141 option to enable a specific workaround. After Windows 2000 is
2142 installed, you no longer need this option (this option slows down the
2145 @subsubsection Windows 2000 shutdown
2147 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
2148 can. It comes from the fact that Windows 2000 does not automatically
2149 use the APM driver provided by the BIOS.
2151 In order to correct that, do the following (thanks to Struan
2152 Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
2153 Add/Troubleshoot a device => Add a new device & Next => No, select the
2154 hardware from a list & Next => NT Apm/Legacy Support & Next => Next
2155 (again) a few times. Now the driver is installed and Windows 2000 now
2156 correctly instructs QEMU to shutdown at the appropriate moment.
2158 @subsubsection Share a directory between Unix and Windows
2160 See @ref{sec_invocation} about the help of the option @option{-smb}.
2162 @subsubsection Windows XP security problem
2164 Some releases of Windows XP install correctly but give a security
2167 A problem is preventing Windows from accurately checking the
2168 license for this computer. Error code: 0x800703e6.
2171 The workaround is to install a service pack for XP after a boot in safe
2172 mode. Then reboot, and the problem should go away. Since there is no
2173 network while in safe mode, its recommended to download the full
2174 installation of SP1 or SP2 and transfer that via an ISO or using the
2175 vvfat block device ("-hdb fat:directory_which_holds_the_SP").
2177 @subsection MS-DOS and FreeDOS
2179 @subsubsection CPU usage reduction
2181 DOS does not correctly use the CPU HLT instruction. The result is that
2182 it takes host CPU cycles even when idle. You can install the utility
2183 from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
2186 @node QEMU System emulator for non PC targets
2187 @chapter QEMU System emulator for non PC targets
2189 QEMU is a generic emulator and it emulates many non PC
2190 machines. Most of the options are similar to the PC emulator. The
2191 differences are mentioned in the following sections.
2194 * QEMU PowerPC System emulator::
2195 * Sparc32 System emulator::
2196 * Sparc64 System emulator::
2197 * MIPS System emulator::
2198 * ARM System emulator::
2199 * ColdFire System emulator::
2202 @node QEMU PowerPC System emulator
2203 @section QEMU PowerPC System emulator
2205 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
2206 or PowerMac PowerPC system.
2208 QEMU emulates the following PowerMac peripherals:
2214 PCI VGA compatible card with VESA Bochs Extensions
2216 2 PMAC IDE interfaces with hard disk and CD-ROM support
2222 VIA-CUDA with ADB keyboard and mouse.
2225 QEMU emulates the following PREP peripherals:
2231 PCI VGA compatible card with VESA Bochs Extensions
2233 2 IDE interfaces with hard disk and CD-ROM support
2237 NE2000 network adapters
2241 PREP Non Volatile RAM
2243 PC compatible keyboard and mouse.
2246 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
2247 @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
2249 @c man begin OPTIONS
2251 The following options are specific to the PowerPC emulation:
2255 @item -g WxH[xDEPTH]
2257 Set the initial VGA graphic mode. The default is 800x600x15.
2264 More information is available at
2265 @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
2267 @node Sparc32 System emulator
2268 @section Sparc32 System emulator
2270 Use the executable @file{qemu-system-sparc} to simulate the following
2271 Sun4m architecture machines:
2286 SPARCstation Voyager
2293 The emulation is somewhat complete. SMP up to 16 CPUs is supported,
2294 but Linux limits the number of usable CPUs to 4.
2296 It's also possible to simulate a SPARCstation 2 (sun4c architecture),
2297 SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these
2298 emulators are not usable yet.
2300 QEMU emulates the following sun4m/sun4c/sun4d peripherals:
2308 Lance (Am7990) Ethernet
2310 Non Volatile RAM M48T02/M48T08
2312 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
2313 and power/reset logic
2315 ESP SCSI controller with hard disk and CD-ROM support
2317 Floppy drive (not on SS-600MP)
2319 CS4231 sound device (only on SS-5, not working yet)
2322 The number of peripherals is fixed in the architecture. Maximum
2323 memory size depends on the machine type, for SS-5 it is 256MB and for
2326 Since version 0.8.2, QEMU uses OpenBIOS
2327 @url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
2328 firmware implementation. The goal is to implement a 100% IEEE
2329 1275-1994 (referred to as Open Firmware) compliant firmware.
2331 A sample Linux 2.6 series kernel and ram disk image are available on
2332 the QEMU web site. There are still issues with NetBSD and OpenBSD, but
2333 some kernel versions work. Please note that currently Solaris kernels
2334 don't work probably due to interface issues between OpenBIOS and
2337 @c man begin OPTIONS
2339 The following options are specific to the Sparc32 emulation:
2343 @item -g WxHx[xDEPTH]
2345 Set the initial TCX graphic mode. The default is 1024x768x8, currently
2346 the only other possible mode is 1024x768x24.
2348 @item -prom-env string
2350 Set OpenBIOS variables in NVRAM, for example:
2353 qemu-system-sparc -prom-env 'auto-boot?=false' \
2354 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
2357 @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic|SPARCbook|SS-2|SS-1000|SS-2000]
2359 Set the emulated machine type. Default is SS-5.
2365 @node Sparc64 System emulator
2366 @section Sparc64 System emulator
2368 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
2369 (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
2370 Niagara (T1) machine. The emulator is not usable for anything yet, but
2371 it can launch some kernels.
2373 QEMU emulates the following peripherals:
2377 UltraSparc IIi APB PCI Bridge
2379 PCI VGA compatible card with VESA Bochs Extensions
2381 PS/2 mouse and keyboard
2383 Non Volatile RAM M48T59
2385 PC-compatible serial ports
2387 2 PCI IDE interfaces with hard disk and CD-ROM support
2392 @c man begin OPTIONS
2394 The following options are specific to the Sparc64 emulation:
2398 @item -prom-env string
2400 Set OpenBIOS variables in NVRAM, for example:
2403 qemu-system-sparc64 -prom-env 'auto-boot?=false'
2406 @item -M [sun4u|sun4v|Niagara]
2408 Set the emulated machine type. The default is sun4u.
2414 @node MIPS System emulator
2415 @section MIPS System emulator
2417 Four executables cover simulation of 32 and 64-bit MIPS systems in
2418 both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2419 @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
2420 Five different machine types are emulated:
2424 A generic ISA PC-like machine "mips"
2426 The MIPS Malta prototype board "malta"
2428 An ACER Pica "pica61". This machine needs the 64-bit emulator.
2430 MIPS emulator pseudo board "mipssim"
2432 A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
2435 The generic emulation is supported by Debian 'Etch' and is able to
2436 install Debian into a virtual disk image. The following devices are
2441 A range of MIPS CPUs, default is the 24Kf
2443 PC style serial port
2450 The Malta emulation supports the following devices:
2454 Core board with MIPS 24Kf CPU and Galileo system controller
2456 PIIX4 PCI/USB/SMbus controller
2458 The Multi-I/O chip's serial device
2460 PCnet32 PCI network card
2462 Malta FPGA serial device
2464 Cirrus VGA graphics card
2467 The ACER Pica emulation supports:
2473 PC-style IRQ and DMA controllers
2480 The mipssim pseudo board emulation provides an environment similiar
2481 to what the proprietary MIPS emulator uses for running Linux.
2486 A range of MIPS CPUs, default is the 24Kf
2488 PC style serial port
2490 MIPSnet network emulation
2493 The MIPS Magnum R4000 emulation supports:
2499 PC-style IRQ controller
2509 @node ARM System emulator
2510 @section ARM System emulator
2512 Use the executable @file{qemu-system-arm} to simulate a ARM
2513 machine. The ARM Integrator/CP board is emulated with the following
2518 ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
2522 SMC 91c111 Ethernet adapter
2524 PL110 LCD controller
2526 PL050 KMI with PS/2 keyboard and mouse.
2528 PL181 MultiMedia Card Interface with SD card.
2531 The ARM Versatile baseboard is emulated with the following devices:
2535 ARM926E, ARM1136 or Cortex-A8 CPU
2537 PL190 Vectored Interrupt Controller
2541 SMC 91c111 Ethernet adapter
2543 PL110 LCD controller
2545 PL050 KMI with PS/2 keyboard and mouse.
2547 PCI host bridge. Note the emulated PCI bridge only provides access to
2548 PCI memory space. It does not provide access to PCI IO space.
2549 This means some devices (eg. ne2k_pci NIC) are not usable, and others
2550 (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
2551 mapped control registers.
2553 PCI OHCI USB controller.
2555 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
2557 PL181 MultiMedia Card Interface with SD card.
2560 The ARM RealView Emulation baseboard is emulated with the following devices:
2564 ARM926E, ARM1136, ARM11MPCORE(x4) or Cortex-A8 CPU
2566 ARM AMBA Generic/Distributed Interrupt Controller
2570 SMC 91c111 Ethernet adapter
2572 PL110 LCD controller
2574 PL050 KMI with PS/2 keyboard and mouse
2578 PCI OHCI USB controller
2580 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
2582 PL181 MultiMedia Card Interface with SD card.
2585 The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2586 and "Terrier") emulation includes the following peripherals:
2590 Intel PXA270 System-on-chip (ARM V5TE core)
2594 IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2596 On-chip OHCI USB controller
2598 On-chip LCD controller
2600 On-chip Real Time Clock
2602 TI ADS7846 touchscreen controller on SSP bus
2604 Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2606 GPIO-connected keyboard controller and LEDs
2608 Secure Digital card connected to PXA MMC/SD host
2612 WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2615 The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2620 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2622 ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2624 On-chip LCD controller
2626 On-chip Real Time Clock
2628 TI TSC2102i touchscreen controller / analog-digital converter / Audio
2629 CODEC, connected through MicroWire and I@math{^2}S busses
2631 GPIO-connected matrix keypad
2633 Secure Digital card connected to OMAP MMC/SD host
2638 Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2639 emulation supports the following elements:
2643 Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2645 RAM and non-volatile OneNAND Flash memories
2647 Display connected to EPSON remote framebuffer chip and OMAP on-chip
2648 display controller and a LS041y3 MIPI DBI-C controller
2650 TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2651 driven through SPI bus
2653 National Semiconductor LM8323-controlled qwerty keyboard driven
2654 through I@math{^2}C bus
2656 Secure Digital card connected to OMAP MMC/SD host
2658 Three OMAP on-chip UARTs and on-chip STI debugging console
2660 Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2661 TUSB6010 chip - only USB host mode is supported
2663 TI TMP105 temperature sensor driven through I@math{^2}C bus
2665 TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2667 Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2671 The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2678 64k Flash and 8k SRAM.
2680 Timers, UARTs, ADC and I@math{^2}C interface.
2682 OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2685 The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2692 256k Flash and 64k SRAM.
2694 Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2696 OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2699 The Freecom MusicPal internet radio emulation includes the following
2704 Marvell MV88W8618 ARM core.
2706 32 MB RAM, 256 KB SRAM, 8 MB flash.
2710 MV88W8xx8 Ethernet controller
2712 MV88W8618 audio controller, WM8750 CODEC and mixer
2714 128×64 display with brightness control
2716 2 buttons, 2 navigation wheels with button function
2719 A Linux 2.6 test image is available on the QEMU web site. More
2720 information is available in the QEMU mailing-list archive.
2722 @node ColdFire System emulator
2723 @section ColdFire System emulator
2725 Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2726 The emulator is able to boot a uClinux kernel.
2728 The M5208EVB emulation includes the following devices:
2732 MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2734 Three Two on-chip UARTs.
2736 Fast Ethernet Controller (FEC)
2739 The AN5206 emulation includes the following devices:
2743 MCF5206 ColdFire V2 Microprocessor.
2748 @node QEMU User space emulator
2749 @chapter QEMU User space emulator
2752 * Supported Operating Systems ::
2753 * Linux User space emulator::
2754 * Mac OS X/Darwin User space emulator ::
2757 @node Supported Operating Systems
2758 @section Supported Operating Systems
2760 The following OS are supported in user space emulation:
2764 Linux (referred as qemu-linux-user)
2766 Mac OS X/Darwin (referred as qemu-darwin-user)
2769 @node Linux User space emulator
2770 @section Linux User space emulator
2775 * Command line options::
2780 @subsection Quick Start
2782 In order to launch a Linux process, QEMU needs the process executable
2783 itself and all the target (x86) dynamic libraries used by it.
2787 @item On x86, you can just try to launch any process by using the native
2791 qemu-i386 -L / /bin/ls
2794 @code{-L /} tells that the x86 dynamic linker must be searched with a
2797 @item Since QEMU is also a linux process, you can launch qemu with
2798 qemu (NOTE: you can only do that if you compiled QEMU from the sources):
2801 qemu-i386 -L / qemu-i386 -L / /bin/ls
2804 @item On non x86 CPUs, you need first to download at least an x86 glibc
2805 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2806 @code{LD_LIBRARY_PATH} is not set:
2809 unset LD_LIBRARY_PATH
2812 Then you can launch the precompiled @file{ls} x86 executable:
2815 qemu-i386 tests/i386/ls
2817 You can look at @file{qemu-binfmt-conf.sh} so that
2818 QEMU is automatically launched by the Linux kernel when you try to
2819 launch x86 executables. It requires the @code{binfmt_misc} module in the
2822 @item The x86 version of QEMU is also included. You can try weird things such as:
2824 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2825 /usr/local/qemu-i386/bin/ls-i386
2831 @subsection Wine launch
2835 @item Ensure that you have a working QEMU with the x86 glibc
2836 distribution (see previous section). In order to verify it, you must be
2840 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2843 @item Download the binary x86 Wine install
2844 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2846 @item Configure Wine on your account. Look at the provided script
2847 @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2848 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2850 @item Then you can try the example @file{putty.exe}:
2853 qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2854 /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2859 @node Command line options
2860 @subsection Command line options
2863 usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] program [arguments...]
2870 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2872 Set the x86 stack size in bytes (default=524288)
2874 Select CPU model (-cpu ? for list and additional feature selection)
2881 Activate log (logfile=/tmp/qemu.log)
2883 Act as if the host page size was 'pagesize' bytes
2885 Wait gdb connection to port
2888 Environment variables:
2892 Print system calls and arguments similar to the 'strace' program
2893 (NOTE: the actual 'strace' program will not work because the user
2894 space emulator hasn't implemented ptrace). At the moment this is
2895 incomplete. All system calls that don't have a specific argument
2896 format are printed with information for six arguments. Many
2897 flag-style arguments don't have decoders and will show up as numbers.
2900 @node Other binaries
2901 @subsection Other binaries
2903 @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2904 binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2905 configurations), and arm-uclinux bFLT format binaries.
2907 @command{qemu-m68k} is capable of running semihosted binaries using the BDM
2908 (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2909 coldfire uClinux bFLT format binaries.
2911 The binary format is detected automatically.
2913 @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2915 @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2916 (Sparc64 CPU, 32 bit ABI).
2918 @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2919 SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2921 @node Mac OS X/Darwin User space emulator
2922 @section Mac OS X/Darwin User space emulator
2925 * Mac OS X/Darwin Status::
2926 * Mac OS X/Darwin Quick Start::
2927 * Mac OS X/Darwin Command line options::
2930 @node Mac OS X/Darwin Status
2931 @subsection Mac OS X/Darwin Status
2935 target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]
2937 target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)
2939 target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]
2941 target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.
2944 [1] If you're host commpage can be executed by qemu.
2946 @node Mac OS X/Darwin Quick Start
2947 @subsection Quick Start
2949 In order to launch a Mac OS X/Darwin process, QEMU needs the process executable
2950 itself and all the target dynamic libraries used by it. If you don't have the FAT
2951 libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X
2952 CD or compile them by hand.
2956 @item On x86, you can just try to launch any process by using the native
2963 or to run the ppc version of the executable:
2969 @item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)
2973 qemu-i386 -L /opt/x86_root/ /bin/ls
2976 @code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in
2977 @file{/opt/x86_root/usr/bin/dyld}.
2981 @node Mac OS X/Darwin Command line options
2982 @subsection Command line options
2985 usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
2992 Set the library root path (default=/)
2994 Set the stack size in bytes (default=524288)
3001 Activate log (logfile=/tmp/qemu.log)
3003 Act as if the host page size was 'pagesize' bytes
3007 @chapter Compilation from the sources
3012 * Cross compilation for Windows with Linux::
3019 @subsection Compilation
3021 First you must decompress the sources:
3024 tar zxvf qemu-x.y.z.tar.gz
3028 Then you configure QEMU and build it (usually no options are needed):
3034 Then type as root user:
3038 to install QEMU in @file{/usr/local}.
3040 @subsection GCC version
3042 In order to compile QEMU successfully, it is very important that you
3043 have the right tools. The most important one is gcc. On most hosts and
3044 in particular on x86 ones, @emph{gcc 4.x is not supported}. If your
3045 Linux distribution includes a gcc 4.x compiler, you can usually
3046 install an older version (it is invoked by @code{gcc32} or
3047 @code{gcc34}). The QEMU configure script automatically probes for
3048 these older versions so that usually you don't have to do anything.
3054 @item Install the current versions of MSYS and MinGW from
3055 @url{http://www.mingw.org/}. You can find detailed installation
3056 instructions in the download section and the FAQ.
3059 the MinGW development library of SDL 1.2.x
3060 (@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from
3061 @url{http://www.libsdl.org}. Unpack it in a temporary place, and
3062 unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
3063 directory. Edit the @file{sdl-config} script so that it gives the
3064 correct SDL directory when invoked.
3066 @item Extract the current version of QEMU.
3068 @item Start the MSYS shell (file @file{msys.bat}).
3070 @item Change to the QEMU directory. Launch @file{./configure} and
3071 @file{make}. If you have problems using SDL, verify that
3072 @file{sdl-config} can be launched from the MSYS command line.
3074 @item You can install QEMU in @file{Program Files/Qemu} by typing
3075 @file{make install}. Don't forget to copy @file{SDL.dll} in
3076 @file{Program Files/Qemu}.
3080 @node Cross compilation for Windows with Linux
3081 @section Cross compilation for Windows with Linux
3085 Install the MinGW cross compilation tools available at
3086 @url{http://www.mingw.org/}.
3089 Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
3090 unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
3091 variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
3092 the QEMU configuration script.
3095 Configure QEMU for Windows cross compilation:
3097 ./configure --enable-mingw32
3099 If necessary, you can change the cross-prefix according to the prefix
3100 chosen for the MinGW tools with --cross-prefix. You can also use
3101 --prefix to set the Win32 install path.
3103 @item You can install QEMU in the installation directory by typing
3104 @file{make install}. Don't forget to copy @file{SDL.dll} in the
3105 installation directory.
3109 Note: Currently, Wine does not seem able to launch
3115 The Mac OS X patches are not fully merged in QEMU, so you should look
3116 at the QEMU mailing list archive to have all the necessary