Running HelenOS in QEMU

This page describes how to use ​QEMU to run various HelenOS images you either ​downloaded or built yourself.

The following text describes how to run the emulator manually. That is necessary if you download the image, but if you build the image by yourself, you may use our wrapper script instead. The script is started using following command:

./tools/ew.py

It detects used configuration (e.g. whether you built for ia32 or mips) and start the appropriate emulator (for some architectures, it would also set-up networking in the emulator). Please note that this does not work for ​downloaded images.

Basics

ia32

For QEMU 1.0.1 and newer:

qemu-system-i386 -cdrom image.iso

For QEMU 1.0.0 and older:

qemu -cdrom image.iso

amd64

qemu-system-x86_64 -cdrom image.iso

arm32

qemu-system-arm -kernel image.boot

ppc32

qemu-system-ppc -cdrom image.iso -boot d

sparc64

qemu-system-sparc64 -cdrom image.iso -boot d

mips32

HelenOS currently does not support a QEMU-supported machine. Try using one of the other simulators. See also ticket #417.

Serial ports

TODO write this section

Networking

For general information about networking in HelenOS, please see UsersGuide/Networking

To use networking, a network interface card must be presented to the guest system.

To add a virtual network card, add one of the following command-line options:

Device	Option
Intel PRO/1000	-device e1000,vlan=0
Realtek RTL8139	-device rtl8139,vlan=0
NE 2000	-device ne2k_isa,irq=5,vlan=0

QEMU guest may be presented with QEMU's user mode network stack (SLIRP) or directly bridged host's network interface. For more information about QEMU networking options, see ​QEMU Networking Documentation

Using user mode network stack

To activate user mode network stack, add -net user option to qemu command line. QEMU will then create a virtual network 10.0.2.0/24. You may use 10.0.2.15 as the IP for the guest computer. To redirect traffic to guest network use -redir option:

-redir udp:8080::8080 -redir tcp:8181::8181

A script to run QEMU this way is present in source:mainline/contrib/conf/net-qe.sh

Bridging virtual network device with host's network interface

See NetworkBridging.

USB

To make use of the UHCI host controller built-into QEMU, add -usb option to the command line. That only initializes the USB but no devices would be present. QEMU emulates some of USB devices by its own or you can bridge real USB device from the host system. Plugging and unplugging can be specified either at the command line or from QEMU console at runtime.

Bridging of host devices

The following example assume you are running Linux box and you are able to pin-point the device you want to bridge to QEMU in lsusb output. The lsusb output can look like this

Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 074: ID 04f2:0403 Chicony Electronics Co., Ltd KU-0420 keyboard

If you want to bridge the Chicony keyboard, you add another option -usbdevice with parameter host:2.74 where 2 denotes bus number and 74 device number. Notice that the delimiter is a period instead of colon that is used when filtering lsusb output.

qemu-system-x86_64 -cdrom image.iso -usb -usbdevice host:2.74

Depending on your OS settings, you may need to run QEMU with higher privileges.

QEMU will grab the device from your OS and you will no longer be able to use it in the host system (rather do not try it). When QEMU terminates, it releases the control. Depending on your OS and QEMU version you are using, it might be needed to physically reattach the device, before the host OS can work with it again.

Emulated devices

QEMU by itself is able to emulate keyboard, mouse, tablet and a mass storage backed by a file representing disk image. To use emulated keyboard and mouse, run QEMU like this.

qemu-system-x86_64 -cdrom image.iso -usb -usbdevice keyboard -usbdevice mouse

Note that using the emulated USB keyboard disables the standard AT keyboard, thus you will not be able to use kernel console (more details at discontinued ​USB Trac).

The disk image is specified as disk:filename. Following command shall create an illusion that image.iso is on a mass storage device plugged to the machine:

qemu-system-x86_64 -cdrom image.iso -usb -usbdevice disk:image.iso

Working with USB devices in the control console

TODO