Gumstix Emulation for QEMU

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).

Old (Verdex/Connex) Instructions

The instructions below are outdated and likely no longer work. They are left here in case any of the above instructions fail.

QEMU Sources

Gumstix verdex and connex support has found its way into the CVS version of QEMU. Update: It seems to also now be in the main trunk. The precompiled binaries I obtained had verdex support. Follow the instructions http://fabrice.bellard.free.fr/qemu/ to get and compile the CVS code for arm targets. It seems that the sources have made Note that the machine name has changed from gumstix to verdex or connex, respectively.

• Example usage is now (where "flash" is the file containing the flash filesystem):

qemu-system-arm -M verdex -pflash flash -monitor null -nographic -m 289

Obsolete sources

Obsolete source code is available at http://www.bitmux.org/qemu.html, along with basic build and execution instructions which I won't repeat here.

• The download page lists the build command as

./configure --target-list=arm-softmmu

On a Debian linux box, I needed to do this:

sudo apt-get install gcc-3.4
./configure --target-list=arm-softmmu --cc=gcc-3.4 --disable-gfx-check

Tips and tricks

• This seems to no longer be an issue: The default U-Boot boot command runs the mmcinit command, which as far as I can tell hangs the emulator. The workaround is to hit a key before the default boot command runs, and either run a command by hand (fsload && bootm is usually enough), or set a new bootcmd and saveenv it.

• If you've got a buildroot and want to build a new flash image for QEMU, execute these commands (these commands also work with the precompiled downloads on Gumstix's Sourceforge Page[1]):

rm flash
dd of=flash bs=1k count=16k if=/dev/zero
dd of=flash bs=1k conv=notrunc if=u-boot.bin
dd of=flash bs=1k conv=notrunc seek=256 if=rootfs.arm_nofpu.jffs2

If the compiled version of u-boot.bin is version 1.2.0, also execute this command:

dd of=flash bs=1k conv=notrunc seek=15360 if=uImage

Then you can run the emulator with this new flash.

• It seems that in newer models of Gumstix some things (including where uboot thinks the kernel is at) have changed. If when using QEMU to simulate a verdex (and using recent 1.20 or higher uImage), you keep getting u-boot errors about finding a "bad magic number" and are unable to boot into Linux then try this command instead:

dd of=flash bs=1k conv=notrunc seek=31744 if=uImage

31744 is 0x01f00000 (you'll notice that number in your uboot error) divided by 1024 (bytes into kilobytes) and turned into a decimal number. It works for me (I can login as root, make and save a file, and view it after Qemu has shutdown or rebooted the machine. Previously, uboot could not even boot into Linux. I get many, many errors about unimplemented flash write commands but things seem to mostly work).

• If you have bluetooth enabled, the /etc/init.d/S30bluetooth script will never complete (Starting 32khz clock... will just print dots forever.) However, Control-c will interrupt it and you can then log in. This will cause all the following init.d scripts not to run, so I recommend removing this script. If your gumstix doesn't have bluetooth, then you might as well just disable bluetooth completely from menuconfig. If you do this, you'll probably also need to remove the file from build_arm_nofpu/root/ so it won't be in the next image you build.

• http://www.cnpbagwell.com/QEMU/HomePage is the most concise description I've seen of how to set up networking.

• Control-a h prints some magic keys you can use from inside the emulator. Control-a x to exit is the most useful one.