1 \input texinfo @c -*- texinfo -*-
4 @settitle QEMU CPU Emulator User Documentation
7 @center @titlefont{QEMU CPU Emulator User Documentation}
16 QEMU is a FAST! processor emulator using dynamic translation to
17 achieve good emulation speed.
19 QEMU has two operating modes:
24 Full system emulation. In this mode, QEMU emulates a full system (for
25 example a PC), including a processor and various peripherals. It can
26 be used to launch different Operating Systems without rebooting the
27 PC or to debug system code.
30 User mode emulation (Linux host only). In this mode, QEMU can launch
31 Linux processes compiled for one CPU on another CPU. It can be used to
32 launch the Wine Windows API emulator (@url{http://www.winehq.org}) or
33 to ease cross-compilation and cross-debugging.
37 QEMU can run without an host kernel driver and yet gives acceptable
40 For system emulation, the following hardware targets are supported:
42 @item PC (x86 or x86_64 processor)
43 @item PREP (PowerPC processor)
44 @item G3 BW PowerMac (PowerPC processor)
45 @item Mac99 PowerMac (PowerPC processor, in progress)
46 @item Sun4m (32-bit Sparc processor)
47 @item Sun4u (64-bit Sparc processor, in progress)
48 @item Malta board (32-bit MIPS processor, in progress)
51 For user emulation, x86, PowerPC, ARM, and Sparc32/64 CPUs are supported.
55 If you want to compile QEMU yourself, see @ref{compilation}.
59 If a precompiled package is available for your distribution - you just
60 have to install it. Otherwise, see @ref{compilation}.
64 Download the experimental binary installer at
65 @url{http://www.freeoszoo.org/download.php}.
69 Download the experimental binary installer at
70 @url{http://www.freeoszoo.org/download.php}.
72 @chapter QEMU PC System emulator invocation
76 @c man begin DESCRIPTION
78 The QEMU System emulator simulates the
79 following PC peripherals:
83 i440FX host PCI bridge and PIIX3 PCI to ISA bridge
85 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
86 extensions (hardware level, including all non standard modes).
88 PS/2 mouse and keyboard
90 2 PCI IDE interfaces with hard disk and CD-ROM support
94 NE2000 PCI network adapters
98 Creative SoundBlaster 16 sound card
100 ENSONIQ AudioPCI ES1370 sound card
102 Adlib(OPL2) - Yamaha YM3812 compatible chip
104 PCI UHCI USB controller and a virtual USB hub.
107 Note that adlib is only available when QEMU was configured with
110 QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
113 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
119 Download and uncompress the linux image (@file{linux.img}) and type:
125 Linux should boot and give you a prompt.
131 @c man begin SYNOPSIS
132 usage: qemu [options] [disk_image]
137 @var{disk_image} is a raw hard disk image for IDE hard disk 0.
142 Select the emulated machine (@code{-M ?} for list)
146 Use @var{file} as floppy disk 0/1 image (@xref{disk_images}). You can
147 use the host floppy by using @file{/dev/fd0} as filename.
153 Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}).
156 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and
157 @option{-cdrom} at the same time). You can use the host CD-ROM by
158 using @file{/dev/cdrom} as filename.
161 Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
165 Write to temporary files instead of disk image files. In this case,
166 the raw disk image you use is not written back. You can however force
167 the write back by pressing @key{C-a s} (@xref{disk_images}).
170 Set virtual RAM size to @var{megs} megabytes. Default is 128 MB.
174 Normally, QEMU uses SDL to display the VGA output. With this option,
175 you can totally disable graphical output so that QEMU is a simple
176 command line application. The emulated serial port is redirected on
177 the console. Therefore, you can still use QEMU to debug a Linux kernel
178 with a serial console.
182 Use keyboard layout @var{language} (for example @code{fr} for
183 French). This option is only needed where it is not easy to get raw PC
184 keycodes (e.g. on Macs or with some X11 servers). You don't need to
185 use it on PC/Linux or PC/Windows hosts.
187 The available layouts are:
189 ar de-ch es fo fr-ca hu ja mk no pt-br sv
190 da en-gb et fr fr-ch is lt nl pl ru th
191 de en-us fi fr-be hr it lv nl-be pt sl tr
194 The default is @code{en-us}.
198 Will enable audio and all the sound hardware QEMU was built with.
202 Will show the audio subsystem help: list of drivers, tunable
205 @item -soundhw card1,card2,...
207 Enable audio and selected sound hardware. Use ? to print all
208 available sound hardware.
211 qemu -soundhw sb16,adlib hda
212 qemu -soundhw es1370 hda
217 Set the real time clock to local time (the default is to UTC
218 time). This option is needed to have correct date in MS-DOS or
222 Start in full screen.
225 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
229 Use it when installing Windows 2000 to avoid a disk full bug. After
230 Windows 2000 is installed, you no longer need this option (this option
231 slows down the IDE transfers).
239 Enable the USB driver (will be the default soon)
241 @item -usbdevice devname
242 Add the USB device @var{devname}. See the monitor command
243 @code{usb_add} to have more information.
250 @item -net nic[,vlan=n][,macaddr=addr]
251 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
252 = 0 is the default). The NIC is currently an NE2000 on the PC
253 target. Optionally, the MAC address can be changed. If no
254 @option{-net} option is specified, a single NIC is created.
256 @item -net user[,vlan=n]
257 Use the user mode network stack which requires not administrator
258 priviledge to run. This is the default if no @option{-net} option is
261 @item -net tap[,vlan=n][,fd=h][,ifname=name][,script=file]
262 Connect the host TAP network interface @var{name} to VLAN @var{n} and
263 use the network script @var{file} to configure it. The default
264 network script is @file{/etc/qemu-ifup}. If @var{name} is not
265 provided, the OS automatically provides one. @option{fd=h} can be
266 used to specify the handle of an already opened host TAP interface. Example:
269 qemu linux.img -net nic -net tap
272 More complicated example (two NICs, each one connected to a TAP device)
274 qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
275 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
279 @item -net socket[,vlan=n][,fd=h][,listen=[host]:port][,connect=host:port]
281 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
282 machine using a TCP socket connection. If @option{listen} is
283 specified, QEMU waits for incoming connections on @var{port}
284 (@var{host} is optional). @option{connect} is used to connect to
285 another QEMU instance using the @option{listen} option. @option{fd=h}
286 specifies an already opened socket.
290 # launch a first QEMU instance
291 qemu linux.img -net nic -net socket,listen=:1234
292 # connect the VLAN 0 of this instance to the VLAN 0 of the first instance
293 qemu linux.img -net nic -net socket,connect=127.0.0.1:1234
297 Indicate that no network devices should be configured. It is used to
298 override the default configuration which is activated if no
299 @option{-net} options are provided.
302 When using the user mode network stack, activate a built-in TFTP
303 server. All filenames beginning with @var{prefix} can be downloaded
304 from the host to the guest using a TFTP client. The TFTP client on the
305 guest must be configured in binary mode (use the command @code{bin} of
306 the Unix TFTP client). The host IP address on the guest is as usual
310 When using the user mode network stack, activate a built-in SMB
311 server so that Windows OSes can access to the host files in @file{dir}
314 In the guest Windows OS, the line:
318 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
319 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
321 Then @file{dir} can be accessed in @file{\\smbserver\qemu}.
323 Note that a SAMBA server must be installed on the host OS in
324 @file{/usr/sbin/smbd}. QEMU was tested succesfully with smbd version
325 2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
327 @item -redir [tcp|udp]:host-port:[guest-host]:guest-port
329 When using the user mode network stack, redirect incoming TCP or UDP
330 connections to the host port @var{host-port} to the guest
331 @var{guest-host} on guest port @var{guest-port}. If @var{guest-host}
332 is not specified, its value is 10.0.2.15 (default address given by the
333 built-in DHCP server).
335 For example, to redirect host X11 connection from screen 1 to guest
336 screen 0, use the following:
340 qemu -redir tcp:6001::6000 [...]
341 # this host xterm should open in the guest X11 server
345 To redirect telnet connections from host port 5555 to telnet port on
346 the guest, use the following:
350 qemu -redir tcp:5555::23 [...]
351 telnet localhost 5555
354 Then when you use on the host @code{telnet localhost 5555}, you
355 connect to the guest telnet server.
359 Linux boot specific: When using these options, you can use a given
360 Linux kernel without installing it in the disk image. It can be useful
361 for easier testing of various kernels.
365 @item -kernel bzImage
366 Use @var{bzImage} as kernel image.
368 @item -append cmdline
369 Use @var{cmdline} as kernel command line
372 Use @var{file} as initial ram disk.
376 Debug/Expert options:
380 Redirect the virtual serial port to host device @var{dev}. Available
386 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
390 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
391 parameters are set according to the emulated ones.
393 [Linux only, parallel port only] Use host parallel port
394 @var{N}. Currently only SPP parallel port features can be used.
396 Write output to filename. No character can be read.
398 [Unix only] standard input/output
400 [Unix only] name pipe @var{filename}
402 The default device is @code{vc} in graphical mode and @code{stdio} in
405 This option can be used several times to simulate up to 4 serials
409 Redirect the virtual parallel port to host device @var{dev} (same
410 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
411 be used to use hardware devices connected on the corresponding host
414 This option can be used several times to simulate up to 3 parallel
418 Redirect the monitor to host device @var{dev} (same devices as the
420 The default device is @code{vc} in graphical mode and @code{stdio} in
424 Wait gdb connection to port 1234 (@xref{gdb_usage}).
426 Change gdb connection port.
428 Do not start CPU at startup (you must type 'c' in the monitor).
430 Output log in /tmp/qemu.log
431 @item -hdachs c,h,s,[,t]
432 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
433 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
434 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
435 all thoses parameters. This option is useful for old MS-DOS disk
439 Simulate a standard VGA card with Bochs VBE extensions (default is
440 Cirrus Logic GD5446 PCI VGA)
442 Start right away with a saved state (@code{loadvm} in monitor)
451 During the graphical emulation, you can use the following keys:
457 Switch to virtual console 'n'. Standard console mappings are:
460 Target system display
468 Toggle mouse and keyboard grab.
471 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
472 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
474 During emulation, if you are using the @option{-nographic} option, use
475 @key{Ctrl-a h} to get terminal commands:
483 Save disk data back to file (if -snapshot)
485 Send break (magic sysrq in Linux)
487 Switch between console and monitor
496 @settitle QEMU System Emulator
499 The HTML documentation of QEMU for more precise information and Linux
500 user mode emulator invocation.
511 @section QEMU Monitor
513 The QEMU monitor is used to give complex commands to the QEMU
514 emulator. You can use it to:
519 Remove or insert removable medias images
520 (such as CD-ROM or floppies)
523 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
526 @item Inspect the VM state without an external debugger.
532 The following commands are available:
536 @item help or ? [cmd]
537 Show the help for all commands or just for command @var{cmd}.
540 Commit changes to the disk images (if -snapshot is used)
542 @item info subcommand
543 show various information about the system state
547 show the various VLANs and the associated devices
549 show the block devices
551 show the cpu registers
553 show the command line history
555 show emulated PCI device
557 show USB devices plugged on the virtual USB hub
559 show all USB host devices
565 @item eject [-f] device
566 Eject a removable media (use -f to force it).
568 @item change device filename
569 Change a removable media.
571 @item screendump filename
572 Save screen into PPM image @var{filename}.
574 @item log item1[,...]
575 Activate logging of the specified items to @file{/tmp/qemu.log}.
577 @item savevm filename
578 Save the whole virtual machine state to @var{filename}.
580 @item loadvm filename
581 Restore the whole virtual machine state from @var{filename}.
589 @item gdbserver [port]
590 Start gdbserver session (default port=1234)
593 Virtual memory dump starting at @var{addr}.
596 Physical memory dump starting at @var{addr}.
598 @var{fmt} is a format which tells the command how to format the
599 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
603 is the number of items to be dumped.
606 can be x (hexa), d (signed decimal), u (unsigned decimal), o (octal),
607 c (char) or i (asm instruction).
610 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
611 @code{h} or @code{w} can be specified with the @code{i} format to
612 respectively select 16 or 32 bit code instruction size.
619 Dump 10 instructions at the current instruction pointer:
624 0x90107065: lea 0x0(%esi,1),%esi
625 0x90107069: lea 0x0(%edi,1),%edi
627 0x90107071: jmp 0x90107080
635 Dump 80 16 bit values at the start of the video memory.
637 (qemu) xp/80hx 0xb8000
638 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
639 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
640 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
641 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
642 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
643 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
644 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
645 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
646 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
647 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
651 @item p or print/fmt expr
653 Print expression value. Only the @var{format} part of @var{fmt} is
658 Send @var{keys} to the emulator. Use @code{-} to press several keys
659 simultaneously. Example:
664 This command is useful to send keys that your graphical user interface
665 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
671 @item usb_add devname
673 Plug the USB device devname to the QEMU virtual USB hub. @var{devname}
674 is either a virtual device name (for example @code{mouse}) or a host
675 USB device identifier. Host USB device identifiers have the following
676 syntax: @code{host:bus.addr} or @code{host:vendor_id:product_id}.
678 @item usb_del devname
680 Remove the USB device @var{devname} from the QEMU virtual USB
681 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
682 command @code{info usb} to see the devices you can remove.
686 @subsection Integer expressions
688 The monitor understands integers expressions for every integer
689 argument. You can use register names to get the value of specifics
690 CPU registers by prefixing them with @emph{$}.
695 Since version 0.6.1, QEMU supports many disk image formats, including
696 growable disk images (their size increase as non empty sectors are
697 written), compressed and encrypted disk images.
699 @subsection Quick start for disk image creation
701 You can create a disk image with the command:
703 qemu-img create myimage.img mysize
705 where @var{myimage.img} is the disk image filename and @var{mysize} is its
706 size in kilobytes. You can add an @code{M} suffix to give the size in
707 megabytes and a @code{G} suffix for gigabytes.
709 @xref{qemu_img_invocation} for more information.
711 @subsection Snapshot mode
713 If you use the option @option{-snapshot}, all disk images are
714 considered as read only. When sectors in written, they are written in
715 a temporary file created in @file{/tmp}. You can however force the
716 write back to the raw disk images by using the @code{commit} monitor
717 command (or @key{C-a s} in the serial console).
719 @node qemu_img_invocation
720 @subsection @code{qemu-img} Invocation
722 @include qemu-img.texi
724 @section Network emulation
726 QEMU can simulate several networks cards (NE2000 boards on the PC
727 target) and can connect them to an arbitrary number of Virtual Local
728 Area Networks (VLANs). Host TAP devices can be connected to any QEMU
729 VLAN. VLAN can be connected between separate instances of QEMU to
730 simulate large networks. For simpler usage, a non priviledged user mode
731 network stack can replace the TAP device to have a basic network
736 QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
737 connection between several network devices. These devices can be for
738 example QEMU virtual Ethernet cards or virtual Host ethernet devices
741 @subsection Using TAP network interfaces
743 This is the standard way to connect QEMU to a real network. QEMU adds
744 a virtual network device on your host (called @code{tapN}), and you
745 can then configure it as if it was a real ethernet card.
747 As an example, you can download the @file{linux-test-xxx.tar.gz}
748 archive and copy the script @file{qemu-ifup} in @file{/etc} and
749 configure properly @code{sudo} so that the command @code{ifconfig}
750 contained in @file{qemu-ifup} can be executed as root. You must verify
751 that your host kernel supports the TAP network interfaces: the
752 device @file{/dev/net/tun} must be present.
754 See @ref{direct_linux_boot} to have an example of network use with a
755 Linux distribution and @ref{sec_invocation} to have examples of
756 command lines using the TAP network interfaces.
758 @subsection Using the user mode network stack
760 By using the option @option{-net user} (default configuration if no
761 @option{-net} option is specified), QEMU uses a completely user mode
762 network stack (you don't need root priviledge to use the virtual
763 network). The virtual network configuration is the following:
767 QEMU VLAN <------> Firewall/DHCP server <-----> Internet
770 ----> DNS server (10.0.2.3)
772 ----> SMB server (10.0.2.4)
775 The QEMU VM behaves as if it was behind a firewall which blocks all
776 incoming connections. You can use a DHCP client to automatically
777 configure the network in the QEMU VM. The DHCP server assign addresses
778 to the hosts starting from 10.0.2.15.
780 In order to check that the user mode network is working, you can ping
781 the address 10.0.2.2 and verify that you got an address in the range
782 10.0.2.x from the QEMU virtual DHCP server.
784 Note that @code{ping} is not supported reliably to the internet as it
785 would require root priviledges. It means you can only ping the local
788 When using the built-in TFTP server, the router is also the TFTP
791 When using the @option{-redir} option, TCP or UDP connections can be
792 redirected from the host to the guest. It allows for example to
793 redirect X11, telnet or SSH connections.
795 @subsection Connecting VLANs between QEMU instances
797 Using the @option{-net socket} option, it is possible to make VLANs
798 that span several QEMU instances. See @ref{sec_invocation} to have a
801 @node direct_linux_boot
802 @section Direct Linux Boot
804 This section explains how to launch a Linux kernel inside QEMU without
805 having to make a full bootable image. It is very useful for fast Linux
806 kernel testing. The QEMU network configuration is also explained.
810 Download the archive @file{linux-test-xxx.tar.gz} containing a Linux
811 kernel and a disk image.
813 @item Optional: If you want network support (for example to launch X11 examples), you
814 must copy the script @file{qemu-ifup} in @file{/etc} and configure
815 properly @code{sudo} so that the command @code{ifconfig} contained in
816 @file{qemu-ifup} can be executed as root. You must verify that your host
817 kernel supports the TUN/TAP network interfaces: the device
818 @file{/dev/net/tun} must be present.
820 When network is enabled, there is a virtual network connection between
821 the host kernel and the emulated kernel. The emulated kernel is seen
822 from the host kernel at IP address 172.20.0.2 and the host kernel is
823 seen from the emulated kernel at IP address 172.20.0.1.
825 @item Launch @code{qemu.sh}. You should have the following output:
829 Connected to host network interface: tun0
830 Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
831 BIOS-provided physical RAM map:
832 BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
833 BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
834 32MB LOWMEM available.
835 On node 0 totalpages: 8192
839 Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0
840 ide_setup: ide2=noprobe
841 ide_setup: ide3=noprobe
842 ide_setup: ide4=noprobe
843 ide_setup: ide5=noprobe
845 Detected 2399.621 MHz processor.
846 Console: colour EGA 80x25
847 Calibrating delay loop... 4744.80 BogoMIPS
848 Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem)
849 Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
850 Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
851 Mount cache hash table entries: 512 (order: 0, 4096 bytes)
852 Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
853 Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
854 CPU: Intel Pentium Pro stepping 03
855 Checking 'hlt' instruction... OK.
856 POSIX conformance testing by UNIFIX
857 Linux NET4.0 for Linux 2.4
858 Based upon Swansea University Computer Society NET3.039
859 Initializing RT netlink socket
862 Journalled Block Device driver loaded
863 Detected PS/2 Mouse Port.
864 pty: 256 Unix98 ptys configured
865 Serial driver version 5.05c (2001-07-08) with no serial options enabled
866 ttyS00 at 0x03f8 (irq = 4) is a 16450
867 ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com)
868 Last modified Nov 1, 2000 by Paul Gortmaker
869 NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
870 eth0: NE2000 found at 0x300, using IRQ 9.
871 RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
872 Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
873 ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
874 hda: QEMU HARDDISK, ATA DISK drive
875 ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
876 hda: attached ide-disk driver.
877 hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
880 Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
881 NET4: Linux TCP/IP 1.0 for NET4.0
882 IP Protocols: ICMP, UDP, TCP, IGMP
883 IP: routing cache hash table of 512 buckets, 4Kbytes
884 TCP: Hash tables configured (established 2048 bind 4096)
885 NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
886 EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
887 VFS: Mounted root (ext2 filesystem).
888 Freeing unused kernel memory: 64k freed
890 Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
892 QEMU Linux test distribution (based on Redhat 9)
894 Type 'exit' to halt the system
900 Then you can play with the kernel inside the virtual serial console. You
901 can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help
902 about the keys you can type inside the virtual serial console. In
903 particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as
907 If the network is enabled, launch the script @file{/etc/linuxrc} in the
908 emulator (don't forget the leading dot):
913 Then enable X11 connections on your PC from the emulated Linux:
918 You can now launch @file{xterm} or @file{xlogo} and verify that you have
919 a real Virtual Linux system !
926 A 2.5.74 kernel is also included in the archive. Just
927 replace the bzImage in qemu.sh to try it.
930 In order to exit cleanly from qemu, you can do a @emph{shutdown} inside
931 qemu. qemu will automatically exit when the Linux shutdown is done.
934 You can boot slightly faster by disabling the probe of non present IDE
935 interfaces. To do so, add the following options on the kernel command
938 ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
942 The example disk image is a modified version of the one made by Kevin
943 Lawton for the plex86 Project (@url{www.plex86.org}).
947 @section USB emulation
949 QEMU emulates a PCI UHCI USB controller and a 8 port USB hub connected
950 to it. You can virtually plug to the hub virtual USB devices or real
951 host USB devices (experimental, works only on Linux hosts).
953 @subsection Using virtual USB devices
955 A virtual USB mouse device is available for testing in QEMU.
957 You can try it with the following monitor commands:
960 # add the mouse device
963 # show the virtual USB devices plugged on the QEMU Virtual USB hub
965 Device 0.3, speed 12 Mb/s
967 # after some time you can try to remove the mouse
971 The option @option{-usbdevice} is similar to the monitor command
974 @subsection Using host USB devices on a Linux host
976 WARNING: this is an experimental feature. QEMU will slow down when
977 using it. USB devices requiring real time streaming (i.e. USB Video
978 Cameras) are not supported yet.
981 @item If you use an early Linux 2.4 kernel, verify that no Linux driver
982 is actually using the USB device. A simple way to do that is simply to
983 disable the corresponding kernel module by renaming it from @file{mydriver.o}
984 to @file{mydriver.o.disabled}.
986 @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
992 @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:
994 chown -R myuid /proc/bus/usb
997 @item Launch QEMU and do in the monitor:
1000 Device 1.2, speed 480 Mb/s
1001 Class 00: USB device 1234:5678, USB DISK
1003 You should see the list of the devices you can use (Never try to use
1004 hubs, it won't work).
1006 @item Add the device in QEMU by using:
1008 usb_add host:1234:5678
1011 Normally the guest OS should report that a new USB device is
1012 plugged. You can use the option @option{-usbdevice} to do the same.
1014 @item Now you can try to use the host USB device in QEMU.
1018 When relaunching QEMU, you may have to unplug and plug again the USB
1019 device to make it work again (this is a bug).
1024 QEMU has a primitive support to work with gdb, so that you can do
1025 'Ctrl-C' while the virtual machine is running and inspect its state.
1027 In order to use gdb, launch qemu with the '-s' option. It will wait for a
1030 > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1031 Connected to host network interface: tun0
1032 Waiting gdb connection on port 1234
1035 Then launch gdb on the 'vmlinux' executable:
1040 In gdb, connect to QEMU:
1042 (gdb) target remote localhost:1234
1045 Then you can use gdb normally. For example, type 'c' to launch the kernel:
1050 Here are some useful tips in order to use gdb on system code:
1054 Use @code{info reg} to display all the CPU registers.
1056 Use @code{x/10i $eip} to display the code at the PC position.
1058 Use @code{set architecture i8086} to dump 16 bit code. Then use
1059 @code{x/10i $cs*16+*eip} to dump the code at the PC position.
1062 @section Target OS specific information
1066 To have access to SVGA graphic modes under X11, use the @code{vesa} or
1067 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1068 color depth in the guest and the host OS.
1070 When using a 2.6 guest Linux kernel, you should add the option
1071 @code{clock=pit} on the kernel command line because the 2.6 Linux
1072 kernels make very strict real time clock checks by default that QEMU
1073 cannot simulate exactly.
1075 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1076 not activated because QEMU is slower with this patch. The QEMU
1077 Accelerator Module is also much slower in this case. Earlier Fedora
1078 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this
1079 patch by default. Newer kernels don't have it.
1083 If you have a slow host, using Windows 95 is better as it gives the
1084 best speed. Windows 2000 is also a good choice.
1086 @subsubsection SVGA graphic modes support
1088 QEMU emulates a Cirrus Logic GD5446 Video
1089 card. All Windows versions starting from Windows 95 should recognize
1090 and use this graphic card. For optimal performances, use 16 bit color
1091 depth in the guest and the host OS.
1093 @subsubsection CPU usage reduction
1095 Windows 9x does not correctly use the CPU HLT
1096 instruction. The result is that it takes host CPU cycles even when
1097 idle. You can install the utility from
1098 @url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this
1099 problem. Note that no such tool is needed for NT, 2000 or XP.
1101 @subsubsection Windows 2000 disk full problem
1103 Windows 2000 has a bug which gives a disk full problem during its
1104 installation. When installing it, use the @option{-win2k-hack} QEMU
1105 option to enable a specific workaround. After Windows 2000 is
1106 installed, you no longer need this option (this option slows down the
1109 @subsubsection Windows 2000 shutdown
1111 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1112 can. It comes from the fact that Windows 2000 does not automatically
1113 use the APM driver provided by the BIOS.
1115 In order to correct that, do the following (thanks to Struan
1116 Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1117 Add/Troubleshoot a device => Add a new device & Next => No, select the
1118 hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1119 (again) a few times. Now the driver is installed and Windows 2000 now
1120 correctly instructs QEMU to shutdown at the appropriate moment.
1122 @subsubsection Share a directory between Unix and Windows
1124 See @ref{sec_invocation} about the help of the option @option{-smb}.
1126 @subsubsection Windows XP security problems
1128 Some releases of Windows XP install correctly but give a security
1131 A problem is preventing Windows from accurately checking the
1132 license for this computer. Error code: 0x800703e6.
1134 The only known workaround is to boot in Safe mode
1135 without networking support.
1137 Future QEMU releases are likely to correct this bug.
1139 @subsection MS-DOS and FreeDOS
1141 @subsubsection CPU usage reduction
1143 DOS does not correctly use the CPU HLT instruction. The result is that
1144 it takes host CPU cycles even when idle. You can install the utility
1145 from @url{http://www.vmware.com/software/dosidle210.zip} to solve this
1148 @chapter QEMU PowerPC System emulator invocation
1150 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1151 or PowerMac PowerPC system.
1153 QEMU emulates the following PowerMac peripherals:
1159 PCI VGA compatible card with VESA Bochs Extensions
1161 2 PMAC IDE interfaces with hard disk and CD-ROM support
1167 VIA-CUDA with ADB keyboard and mouse.
1170 QEMU emulates the following PREP peripherals:
1176 PCI VGA compatible card with VESA Bochs Extensions
1178 2 IDE interfaces with hard disk and CD-ROM support
1182 NE2000 network adapters
1186 PREP Non Volatile RAM
1188 PC compatible keyboard and mouse.
1191 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1192 @url{http://site.voila.fr/jmayer/OpenHackWare/index.htm}.
1194 You can read the qemu PC system emulation chapter to have more
1195 informations about QEMU usage.
1197 @c man begin OPTIONS
1199 The following options are specific to the PowerPC emulation:
1203 @item -g WxH[xDEPTH]
1205 Set the initial VGA graphic mode. The default is 800x600x15.
1212 More information is available at
1213 @url{http://jocelyn.mayer.free.fr/qemu-ppc/}.
1215 @chapter Sparc32 System emulator invocation
1217 Use the executable @file{qemu-system-sparc} to simulate a JavaStation
1218 (sun4m architecture). The emulation is somewhat complete.
1220 QEMU emulates the following sun4m peripherals:
1228 Lance (Am7990) Ethernet
1230 Non Volatile RAM M48T08
1232 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1233 and power/reset logic
1235 ESP SCSI controller with hard disk and CD-ROM support
1240 The number of peripherals is fixed in the architecture.
1242 QEMU uses the Proll, a PROM replacement available at
1243 @url{http://people.redhat.com/zaitcev/linux/}. The required
1244 QEMU-specific patches are included with the sources.
1246 A sample Linux 2.6 series kernel and ram disk image are available on
1247 the QEMU web site. Please note that currently neither Linux 2.4
1248 series, NetBSD, nor OpenBSD kernels work.
1250 @c man begin OPTIONS
1252 The following options are specific to the Sparc emulation:
1258 Set the initial TCX graphic mode. The default is 1024x768.
1264 @chapter Sparc64 System emulator invocation
1266 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine.
1267 The emulator is not usable for anything yet.
1269 QEMU emulates the following sun4u peripherals:
1273 UltraSparc IIi APB PCI Bridge
1275 PCI VGA compatible card with VESA Bochs Extensions
1277 Non Volatile RAM M48T59
1279 PC-compatible serial ports
1282 @chapter MIPS System emulator invocation
1284 Use the executable @file{qemu-system-mips} to simulate a MIPS machine.
1285 The emulator begins to launch a Linux kernel.
1287 @chapter QEMU User space emulator invocation
1289 @section Quick Start
1291 In order to launch a Linux process, QEMU needs the process executable
1292 itself and all the target (x86) dynamic libraries used by it.
1296 @item On x86, you can just try to launch any process by using the native
1300 qemu-i386 -L / /bin/ls
1303 @code{-L /} tells that the x86 dynamic linker must be searched with a
1306 @item Since QEMU is also a linux process, you can launch qemu with qemu (NOTE: you can only do that if you compiled QEMU from the sources):
1309 qemu-i386 -L / qemu-i386 -L / /bin/ls
1312 @item On non x86 CPUs, you need first to download at least an x86 glibc
1313 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
1314 @code{LD_LIBRARY_PATH} is not set:
1317 unset LD_LIBRARY_PATH
1320 Then you can launch the precompiled @file{ls} x86 executable:
1323 qemu-i386 tests/i386/ls
1325 You can look at @file{qemu-binfmt-conf.sh} so that
1326 QEMU is automatically launched by the Linux kernel when you try to
1327 launch x86 executables. It requires the @code{binfmt_misc} module in the
1330 @item The x86 version of QEMU is also included. You can try weird things such as:
1332 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1337 @section Wine launch
1341 @item Ensure that you have a working QEMU with the x86 glibc
1342 distribution (see previous section). In order to verify it, you must be
1346 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
1349 @item Download the binary x86 Wine install
1350 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
1352 @item Configure Wine on your account. Look at the provided script
1353 @file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous
1354 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
1356 @item Then you can try the example @file{putty.exe}:
1359 qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
1364 @section Command line options
1367 usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
1374 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
1376 Set the x86 stack size in bytes (default=524288)
1383 Activate log (logfile=/tmp/qemu.log)
1385 Act as if the host page size was 'pagesize' bytes
1389 @chapter Compilation from the sources
1393 @subsection Compilation
1395 First you must decompress the sources:
1398 tar zxvf qemu-x.y.z.tar.gz
1402 Then you configure QEMU and build it (usually no options are needed):
1408 Then type as root user:
1412 to install QEMU in @file{/usr/local}.
1414 @subsection Tested tool versions
1416 In order to compile QEMU succesfully, it is very important that you
1417 have the right tools. The most important one is gcc. I cannot guaranty
1418 that QEMU works if you do not use a tested gcc version. Look at
1419 'configure' and 'Makefile' if you want to make a different gcc
1423 host gcc binutils glibc linux distribution
1424 ----------------------------------------------------------------------
1425 x86 3.2 2.13.2 2.1.3 2.4.18
1426 2.96 2.11.93.0.2 2.2.5 2.4.18 Red Hat 7.3
1427 3.2.2 2.13.90.0.18 2.3.2 2.4.20 Red Hat 9
1429 PowerPC 3.3 [4] 2.13.90.0.18 2.3.1 2.4.20briq
1432 Alpha 3.3 [1] 2.14.90.0.4 2.2.5 2.2.20 [2] Debian 3.0
1434 Sparc32 2.95.4 2.12.90.0.1 2.2.5 2.4.18 Debian 3.0
1436 ARM 2.95.4 2.12.90.0.1 2.2.5 2.4.9 [3] Debian 3.0
1438 [1] On Alpha, QEMU needs the gcc 'visibility' attribute only available
1439 for gcc version >= 3.3.
1440 [2] Linux >= 2.4.20 is necessary for precise exception support
1442 [3] 2.4.9-ac10-rmk2-np1-cerf2
1444 [4] gcc 2.95.x generates invalid code when using too many register
1445 variables. You must use gcc 3.x on PowerPC.
1451 @item Install the current versions of MSYS and MinGW from
1452 @url{http://www.mingw.org/}. You can find detailed installation
1453 instructions in the download section and the FAQ.
1456 the MinGW development library of SDL 1.2.x
1457 (@file{SDL-devel-1.2.x-mingw32.tar.gz}) from
1458 @url{http://www.libsdl.org}. Unpack it in a temporary place, and
1459 unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool
1460 directory. Edit the @file{sdl-config} script so that it gives the
1461 correct SDL directory when invoked.
1463 @item Extract the current version of QEMU.
1465 @item Start the MSYS shell (file @file{msys.bat}).
1467 @item Change to the QEMU directory. Launch @file{./configure} and
1468 @file{make}. If you have problems using SDL, verify that
1469 @file{sdl-config} can be launched from the MSYS command line.
1471 @item You can install QEMU in @file{Program Files/Qemu} by typing
1472 @file{make install}. Don't forget to copy @file{SDL.dll} in
1473 @file{Program Files/Qemu}.
1477 @section Cross compilation for Windows with Linux
1481 Install the MinGW cross compilation tools available at
1482 @url{http://www.mingw.org/}.
1485 Install the Win32 version of SDL (@url{http://www.libsdl.org}) by
1486 unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment
1487 variable so that @file{i386-mingw32msvc-sdl-config} can be launched by
1488 the QEMU configuration script.
1491 Configure QEMU for Windows cross compilation:
1493 ./configure --enable-mingw32
1495 If necessary, you can change the cross-prefix according to the prefix
1496 choosen for the MinGW tools with --cross-prefix. You can also use
1497 --prefix to set the Win32 install path.
1499 @item You can install QEMU in the installation directory by typing
1500 @file{make install}. Don't forget to copy @file{SDL.dll} in the
1501 installation directory.
1505 Note: Currently, Wine does not seem able to launch
1510 The Mac OS X patches are not fully merged in QEMU, so you should look
1511 at the QEMU mailing list archive to have all the necessary