Revision as of 08:40, 12 April 2012

QEMU is an open source processor emulator which can emulate several different CPU types, including the ARM on the gumstix boards. Using QEMU, you can test Gumstix flash images and other software on a normal computer, without access to physical hardware. QEMU can be unstable at times but is still a valuable tool for testing out software.

These instructions mainly apply to Ubuntu and Mint, but most (apart from installation) should work on other operating systems as well.

Quick Start

If you want to get started with QEMU as quickly as possible, simply run these commands:

sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu/ precise universe"
sudo apt-get update
sudo apt-get install qemu-kvm qemu-kvm-extras
wget http://releases.linaro.org/images/11.12/oneiric/alip/overo-alip.img.gz
gunzip overo-alip.img.gz
qemu-system-arm -M overo -m 256 -sd ./overo-alip.img -clock unix -serial stdio -device usb-mouse -device usb-kbd

If adding the precise repo doesn't work (qemu won't install due to conflicts), remove the repo and try this instead:

 sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu/ maverick universe"

Obtaining QEMU

QEMU is distributed in many different places as many different versions. Some support the Overo out of the box and others do not. Hopefully these instructions work for most people.

QEMU Binaries

For Ubuntu or Mint, the latest version of QEMU isn't in a stable repository. Thus we need to add the development repo by adding this line to /etc/apt/sources.list or to a package manager like Synaptic:

deb http://archive.ubuntu.com/ubuntu/ precise universe

If adding the precise repo doesn't work (qemu won't install due to conflicts), remove the repo and try this instead:

 sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu/ maverick universe"

Download the qemu-kvm and qemu-kvm-extras 1.0 or later packages:

sudo apt-get install qemu-kvm qemu-kvm-extras

QEMU Sources

ARM/Overo support is best in the Linaro branch of qemu. To grab their sources, you will need to obtain git (sudo apt-get install git).

git clone git://git.linaro.org/qemu/qemu-linaro.git

If you want to try out our experimental QEMU build with better support for our boards and a GUI interface for GPIOs, try the instructions at Gumstix Qemu Branch.

Next, install libsdl1.2-dev. SDL enables a graphical output from QEMU. Build QEMU for ARM using these commands:

./configure --target-list=arm-softmmu
make -j4
sudo make install

The "-j4" option allows "make" to use 4 cores, speeding up the build process. QEMU should now be installed.

Obtaining a Test Image

Pre-built

If you want a quick pre-built image to test with, you can grab a quick Linaro image here. Get the Overo version.

Custom QEMU Image

You can customize various components of the QEMU image such as the Linux kernel, u-boot, rootfs, and MLO. You need to first obtain these files from somewhere. You can try cumulus for a large repository of system files. For an Angstrom build, try here. Download the MLO, uImage, u-boot.bin, and omap3-desktop-nand-image-overo-booted.tar.bz2 files.

Next, you need to make a QEMU image from these files. Copy and paste this script into a file, such as makeimage.sh. Then run the following command to make the image:

sudo ./makeimage.sh test.img MLO u-boot.bin uImage omap3-desktop-nand-image-overo-booted.tar.bz2

Building the Kernel/U-boot/rootfs from Source

If you want to customize the Linux kernel (uImage), try the guide here. Building u-boot is a similar procedure. After building the kernel and obtaining uImage, follow the same instructions above.

To build the entire system, you will need all of OpenEmbedded. Try this guide.

Running QEMU

To run QEMU, use the following command:

qemu-system-arm -M overo -m 256 -sd ./test.img -clock unix -serial stdio -device usb-mouse -device usb-kbd

Replace "test.img" with whatever image you're using.

The system should boot, but some functionality will be missing. Type root to login. You should have access to basic networking (web browser and wget but NO ping). If networking doesn't work out of the box, try using:

ifconfig eth0 up
dhclient eth0

If you are using an Angstrom image, mouse and keyboard will NOT work. You need Linaro if you want to mess around with the GUI.

Network Bridging

While using QEMU's internal network stack, you might find some instabilities. Also, nothing from the outside world can connect to your virtual device, since QEMU has a virtual NAT filter. This network stack is why ping does not work for your emulated device. To work around this limitation, you can make a network bridge through TAP.

To set TAP up, your host system must have TAP networking enabled. Type this to verify:

grep CONFIG_TUN= /boot/config*

Check that /dev/net/tun exists. If not, run the following:

sudo mknod /dev/net/tun c 10 200

Next, make sure bridge-utils are installed:

sudo apt-get install bridge-utils

Next run the following commands as root:

/usr/sbin/brctl addbr br0
/sbin/ifconfig eth0 0.0.0.0 promisc up
/usr/sbin/brctl addif br0 eth0
/sbin/dhclient br0
/sbin/iptables -F FORWARD

Note that you may or may not need the prepended /usr/sbin/ and /sbin/ directories.

Add the following lines to a file named qemu-ifup.sh:

#!/bin/sh
/sbin/ifconfig $1 0.0.0.0 promisc up
/usr/sbin/brctl addif br0 $1

Next, start qemu with the following command:

sudo qemu-system-arm -M overo -m 256 -sd ./test.img -clock unix -serial stdio -net nic,vlan=0 -net tap,vlan=0,ifname=tap0,script=./qemu-ifup.sh -device usb-kbd -device usb-mouse

Networking should be enabled in the Overo emulation.

Keyboard and Mouse Support

If you are using an Overo Linaro build, adding -device usb-kbd -device usb-mouse to the qemu startup makes it work.

Changing Screen Size

Interrupt u-boot during startup. Then you can type various commands like setenv defaultdisplay lcd43, for example, and then boot to continue the startup. QEMU should automatically adjust its display settings to fit u-boot's.

Shared Guest/Host Folder

Sometimes you will need to transfer files to and from the guest operating system. One way to achieve this is through a shared folder through Samba.

First, on the guest system, type in "apt-get install samba". This takes a very long time but you only need to do it once. After it all finishes, edit /etc/samba/smb.conf (sudo vi /etc/samba/smb.conf). Then uncomment the lines

     interfaces = 127.0.0.0/8 eth0
     bind interfaces only = yes

Change this line:

#     security = user

To:

     security = share

(uncomment it too)

Then create a new share:

[Guest Share]
     comment = Guest access share
     path = /
     guest ok = yes
     read only = no

These lines go after the other sections, at the end of the file.

After this, test the configuration with testparm. Then type the following:

cd /etc/init.d/
stop smbd
start smbd

Typing in "reload" should work but it was giving me difficulties.

After these steps, type "ifconfig" to get the guest operating system's IP address (probably the address under eth0, e.g. 192.168.0.122). Then connect to it using nautilus in the host system. To do this, click "File->Connect to Server...". Under "Server:", type the IP address you just wrote down. Then under "Type", select "Windows Share" (samba emulates Windows' file sharing mechanisms). Then click "Connect". After this, a list of shares should show up. Click on "Guest Share" to browse the guest OS file system.

On subsequent sessions, you simply have to run "stop smbd" and "start smbd" to restart the samba server (no waiting an hour for samba to install).