QEMU is a FAST! processor emulator using dynamic translation to achieve good emulation speed.

QEMU has two operating modes:

Full system emulation. In this mode, QEMU emulates a full system (for example a PC), including a processor and various peripherals. It can be used to launch different Operating Systems without rebooting the PC or to debug system code. User mode emulation (Linux host only). In this mode, QEMU can launch Linux processes compiled for one CPU on another CPU. It can be used to launch the Wine Windows API emulator (http://www.winehq.org) or to ease cross-compilation and cross-debugging. QEMU can run without an host kernel driver and yet gives acceptable performance

2. Installation

If you want to compile QEMU yourself, see section 9. Compilation from the sources.

2.1 Linux If a precompiled package is available for your distribution - you just have to install it. Otherwise, see section 9. Compilation from the sources.

2.2 Windows Download the experimental binary installer at http://www.freeoszoo.org/download.php.

2.3 Mac OS X Download the experimental binary installer at http://www.freeoszoo.org/download.php.

3. QEMU PC System emulator invocation

3.1 Introduction The QEMU System emulator simulates the following PC peripherals:

QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL VGA BIOS.

3.2 Quick Start Download and uncompress the linux image (`linux.img') and type:

Linux should boot and give you a prompt.

3.3 Invocation

usage: qemu [options] [disk_image]

disk_image is a raw hard disk image for IDE hard disk 0.

3.3 Invocation usage: qemu [options] [disk_image]

disk_image is a raw hard disk image for IDE hard disk 0.

General options:

-fd* file' * = a or b Use file as floppy disk 0/1 image (See section 3.6 Disk Images). You can use the host floppy by using /dev/fd0' as filename.

`-hd* file' * = a,b,c or d Use file as hard disk 0, 1, 2 or 3 image .

-cdrom file' Use file as CD-ROM image (you cannot use {{{-hdc' and and -cdrom' at the same time). You can use the host CD-ROM by using }}}/dev/cdrom' as filename.

`-boot [a|c|d]' Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is the default.

`-snapshot' Write to temporary files instead of disk image files. In this case, the raw disk image you use is not written back. You can however force the write back by pressing C-a s (See section 3.6 Disk Images).

`-m megs' Set virtual RAM size to megs megabytes. Default is 128 MB.

`-nographic' Normally, QEMU uses SDL to display the VGA output. With this option, you can totally disable graphical output so that QEMU is a simple command line application. The emulated serial port is redirected on the console. Therefore, you can still use QEMU to debug a Linux kernel with a serial console.

`-k language' Use keyboard layout language (for example fr for French). This option is only needed where it is not easy to get raw PC keycodes (e.g. on Macs or with some X11 servers). You don't need to use it on PC/Linux or PC/Windows hosts. The available layouts are: ar de-ch es fo fr-ca hu ja mk no pt-br sv da en-gb et fr fr-ch is lt nl pl ru th de en-us fi fr-be hr it lv nl-be pt sl tr

The default is en-us.

`-enable-audio' The SB16 emulation is disabled by default as it may give problems with Windows. You can enable it manually with this option.

`-localtime' Set the real time clock to local time (the default is to UTC time). This option is needed to have correct date in MS-DOS or Windows.

`-full-screen' Start in full screen.

Linux boot specific. When using this options, you can use a given Linux kernel without installing it in the disk image. It can be useful for easier testing of various kernels.

`-kernel bzImage' Use bzImage as kernel image.

`-append cmdline' Use cmdline as kernel command line

`-initrd file' Use file as initial ram disk.

3.4 Keys During the graphical emulation, you can use the following keys:

Ctrl-Alt-f Toggle full screen

Ctrl-Alt-n Switch to virtual console 'n'. Standard console mappings are: 1 Target system display 2 Monitor 3 Serial port

Ctrl-Alt Toggle mouse and keyboard grab.

In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp and Ctrl-PageDown to move in the back log.

If you want to send a key to the system, switch to the monitor virtual console and type : 

sendkey key_to_be_sended_name

For example : 

sendkey ctrl-alt-delete

to shutdown the kernel, or 

sendkey ctrl-alt-f2

to switch to the second virtual console of the emulated system, which is not the monitor console of qemu.

Notice that this send the key to the emulated system, but does not intercept the actual key which is still managed by the native system.

3.5 QEMU Monitor

The QEMU Monitor is used to give complex commands to the QEMU Emulator. You can use it to:

3.5.1 Commands

The following commands, between others, are available:

`help or ? [cmd]' Show the help for all commands or just for command cmd.

`q or quit' Quit the emulator.

3.6 Disk Images Since version 0.6.1, QEMU supports many disk image formats, including growable disk images (their size increase as non empty sectors are written), compressed and encrypted disk images.

3.6.1 Quick start for disk image creation You can create a disk image with the command:

qemu-img create myimage.img mysize

where myimage.img is the disk image filename and mysize is its size in kilobytes. You can add an M suffix to give the size in megabytes and a G suffix for gigabytes.

See section 3.6.3 qemu-img Invocation for more information.

3.6.2 Snapshot mode If you use the option -snapshot', all disk images are considered as read only. When sectors in written, they are written in a temporary file created in /tmp'. You can however force the write back to the raw disk images by using the commit monitor command (or C-a s in the serial console).

3.6.3 qemu-img Invocation usage: qemu-img command [command options]

The following commands are supported:

create [-e] [-b base_image] [-f fmt] filename [size]' commit [-f fmt] filename' convert [-c] [-e] [-f fmt] filename [-O output_fmt] output_filename' info [-f fmt] filename' Command parameters:

filename is a disk image filename

base_image is the read-only disk image which is used as base for a copy on write image; the copy on write image only stores the modified data

fmt is the disk image format. It is guessed automatically in most cases. The following formats are supported: * raw Raw disk image format (default). This format has the advantage of being simple and easily exportable to all other emulators. If your file system supports holes (for example in ext2 or ext3 on Linux), then only the written sectors will reserve space. Use qemu-img info to know the real size used by the image or ls -ls on Unix/Linux.

QEMU image format, the most versatile format. Use it to have smaller images (useful if your filesystem does not supports holes, for example on Windows), optional AES encryption and zlib based compression.

User Mode Linux Copy On Write image format. Used to be the only growable image format in QEMU. It is supported only for compatibility with previous versions. It does not work on win32.

VMware 3 and 4 compatible image format.

Linux Compressed Loop image, useful only to reuse directly compressed CD-ROM images present for example in the Knoppix CD-ROMs.

is the disk image size in kilobytes. Optional suffixes M (megabyte) and G (gigabyte) are supported

output_filename is the destination disk image filename

output_fmt is the destination format

-c indicates that target image must be compressed (qcow format only)

-e indicates that the target image must be encrypted (qcow format only) Command description:

`create [-e] [-b base_image] [-f fmt] filename [size]' Create the new disk image filename of size size and format fmt. If base_image is specified, then the image will record only the differences from base_image. No size needs to be specified in this case. base_image will never be modified unless you use the commit monitor command.

`commit [-f fmt] filename' Commit the changes recorded in filename in its base image.

`convert [-c] [-e] [-f fmt] filename [-O output_fmt] output_filename' Convert the disk image filename to disk image output_filename using format output_fmt. It can be optionnaly encrypted (-e option) or compressed (-c option). Only the format qcow supports encryption or compression. The compression is read-only. It means that if a compressed sector is rewritten, then it is rewritten as uncompressed data. Encryption uses the AES format which is very secure (128 bit keys). Use a long password (16 characters) to get maximum protection. Image conversion is also useful to get smaller image when using a growable format such as qcow or cow: the empty sectors are detected and suppressed from the destination image.

`info [-f fmt] filename' Give information about the disk image filename. Use it in particular to know the size reserved on disk which can be different from the displayed size.

3.8 Direct Linux Boot This section explains how to launch a Linux kernel inside QEMU without having to make a full bootable image. It is very useful for fast Linux kernel testing. The QEMU network configuration is also explained.

Download the archive `linux-test-xxx.tar.gz' containing a Linux kernel and a disk image. Optional: If you want network support (for example to launch X11 examples), you must copy the script qemu-ifup' in /etc' and configure properly sudo so that the command ifconfig contained in qemu-ifup' can be executed as root. You must verify that your host kernel supports the TUN/TAP network interfaces: the device /dev/net/tun' must be present. When network is enabled, there is a virtual network connection between the host kernel and the emulated kernel. The emulated kernel is seen from the host kernel at IP address 172.20.0.2 and the host kernel is seen from the emulated kernel at IP address 172.20.0.1. Launch qemu.sh Type 'exit' to halt the system

sh-2.05b#

Then you can play with the kernel inside the virtual serial console. You can launch ls for example. Type Ctrl-a h to have an help about the keys you can type inside the virtual serial console. In particular, use Ctrl-a x to exit QEMU and use Ctrl-a b as the Magic SysRq key. If the network is enabled, launch the script `/etc/linuxrc' in the emulator (don't forget the leading dot): . /etc/linuxrc

Then enable X11 connections on your PC from the emulated Linux: xhost +172.20.0.2

You can now launch xterm' or xlogo' and verify that you have a real Virtual Linux system ! NOTES:

A 2.5.74 kernel is also included in the archive. Just replace the bzImage in qemu.sh to try it. In order to exit cleanly from qemu, you can do a shutdown inside qemu. qemu will automatically exit when the Linux shutdown is done. You can boot slightly faster by disabling the probe of non present IDE interfaces. To do so, add the following options on the kernel command line: ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe

The example disk image is a modified version of the one made by Kevin Lawton for the plex86 Project (www.plex86.org).

Summary User Documentation (last edited 2007-09-12 14:39:37 by alecto)