= Running HelenOS in QEMU = [[PageOutline(2-3)]] This page describes how to use [http://qemu.org QEMU] to run various HelenOS images you either [wiki:Download downloaded] or [wiki:UsersGuide/CompilingFromSource built yourself]. Here you will learn how to start the emulator manually, which is necessary if you download the image. But if you build the image by yourself, you may use our emulator wrapper script instead. The script is started using the following command: {{{ ./tools/ew.py }}} It detects emulator options to use from the used HelenOS configuration (e.g. whether you built for `ia32` or `mips`) and starts the appropriate emulator. For some architectures, it also determines networking, sound, USB and disk options. See `./tools/ew.py -h` for more information. Please note that this ''does not work'' for the prebuilt [wiki:Download images]. We are assuming a sufficiently recent version of QEMU, such as 2.5.0 and newer. Older versions may or may not work. You should be able to install a prepackaged version of QEMU from your distribution or you can build QEMU from scratch using a simple [browser:mainline/contrib/qemu/build-from-scratch.sh script] which comes with HelenOS sources: {{{ ./contrib/qemu/build-from-scratch.sh }}} == KVM == QEMU supports two modes of operation: binary translation and hardware virtualization. It uses [http://www.linux-kvm.org/page/Main_Page KVM] for the latter. If circumstances are right, it is possible to choose the second mode and benefit from better performance by appending the `-enable-kvm` option to the QEMU command lines below. In general, KVM can only be used, if the following criteria are met: * KVM is supported by the host operating system, e.g. Linux * the host CPU supports hardware virtualization and this support is enabled in it * hardware virtualization is not already in use, i.e. there is no running instance of !VirtualBox or Xen * the guest and host CPUs are compatible (ia32 vs. amd64 is okay) == Basic usage == The following subsections show the minimum QEMU command lines needed to run HelenOS on the respective QEMU machine. When spawned like this, the simulated QEMU machine may be missing some hardware which limits what hardware HelenOS can detect on it and in turn what you can do with it. The later sections will show you how to configure additional hardware. === amd64 === QEMU can emulate a generic PC equipped with a 64-bit processor. For an `image.iso` built for the '''amd64''' or '''ia32''' profile, simply run: {{{ qemu-system-x86_64 -cdrom image.iso }}} === arm32 === QEMU can emulate [http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0159b/Cegeadbj.html ARM Integrator/CP]. For an `image.boot` built for the '''arm32/integratorcp''' profile, do: {{{ qemu-system-arm -M integratorcp -kernel image.boot }}} === ia32 === QEMU can emulate a generic PC. For an `image.iso` built for the '''ia32''' profile, just run: {{{ qemu-system-i386 -cdrom image.iso }}} === mips32 === QEMU can emulate [https://www.linux-mips.org/wiki/MIPS_Malta MIPS Malta] and HelenOS has limited support for it. For big-endian Malta, do: {{{ qemu-system-mips -cpu 4Kc -kernel image.boot -nographic }}} For little-endian Malta, do: {{{ qemu-system-mipsel -cpu 4Kc -kernel image.boot -nographic }}} `image.boot` is the image built for the '''mips32/malte-be''' or '''mips32/malta-le''' profiles, respectively. === ppc32 === QEMU can emulate [https://support.apple.com/kb/SP130 Power Macintosh G3]. For an `image.iso` built for the '''ppc32''' profile, do: {{{ qemu-system-ppc -cdrom image.iso -boot d -m 256 }}} === sparc64 === QEMU can emulate a custom sun4u [http://qemu.weilnetz.de/qemu-doc.html#Sparc64-System-emulator machine] and HelenOS partially supports it. For an `image.iso` built for the '''sparc64/ultra''' profile, do: {{{ qemu-system-sparc64 -cdrom image.iso -boot d }}} Note that the system will boot into a GUI, but it will not be possible to control it using mouse or keyboard. == Serial ports == TODO write this section == Networking == For general information about networking in HelenOS, please see [wiki: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 [http://wiki.qemu.org/Documentation/Networking 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 }}} === Bridging virtual network device with host's network interface === See [wiki: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 [https://sourceforge.net/apps/trac/helenos-usb/ticket/33 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