View source for 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 [http://releases.linaro.org/images/11.12/oneiric/alip/ 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 [http://cumulus.gumstix.org/ cumulus] for a large repository of system files.  For an Angstrom build, try [http://cumulus.gumstix.org/images/angstrom/factory/2011-08-30-1058/ 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 [http://wiki.gumstix.org/index.php?title=Overo_qemu_script 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 [http://gumstix.org/basic-cross-compilation.html 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 [http://gumstix.org/software-development/open-embedded/61-using-the-open-embedded-build-system.html 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 Overo Instructions =

__TOC__
[[Category:How to - qemu]]

Ash Charles has been working with Riku from the Qemu-linaro team to get support for the Overo hardware working in Qemu!

==Pre-Compiled Images==

Here are Ash's steps for working with pre-compiled images:

* binary executable for qemu available here (for x86_64):
::http://dl.dropbox.com/u/211887/qemu-system-arm
::MD5:c375b7d0338e3e8cd7009e69f3aaae74

* overo angstrom image with a kernel, MLO, u-boot packed:
::http://dl.dropbox.com/u/211887/overo.img.gz
::MD5:3545dbd2e7ffac3d352a7bc9e92373bf

* download, gunzip the overo.img.gz and run with:
::<code># ./qemu-system-arm -M overo -m 256 -sd ./overo.img -clock unix -serial stdio</code>
::(mouse & keyboard don't work currently but the console session is usable)

==From Sources==

* build your overo image using bitbake/OE as usual:
::<code>$ cd $OVEROTOP</code>
::<code>$ bitbake omap3-console-image</code>

* build the MLO program:
::<code>$ bitbake x-load</code>

* get the sources for and build qemu with overo support:
::<code>$ cd $OVEROTOP</code>
::<code>$ git clone git://git.linaro.org/qemu/qemu-linaro.git</code>
::<code>$ cd qemu</code>
::<code>$ ./configure --prefix=$OVEROTOP/local --target-list=arm-softmmu</code>
::<code>$ make install</code>
::<code>$ export PATH=$OVEROTOP/local/bin:$PATH</code>

* there are numerous ways to generate the qemu image file:
::<code># export OEDONE=$OETMP/deploy/glibc/images/overo</code>
** Ash Charles [[Overo_qemu_script|wrote a script]] specifically for generating Overo qemu images:
::<code># assemble-image.sh $OVEROTOP/overo.img $OEDONE/MLO-overo $OEDONE/u-boot-overo.bin $OEDONE/uImage-overo.bin $OEDONE/omap3-console-image-overo.tar.bz2</code>
** or using a more [https://github.com/twoerner/qemu-image-builder general-purpose script] for generating qemu images which includes support for Overo:
::<code># mkqemuimg.sh --partpercents 5 --format ",mkfs.ext3" --bootarm "$OEDONE/MLO-overo,$OEDONE/u-boot-overo.bin,$OEDONE/uImage-overo.bin" 1073741824 $OVEROTOP/overo.img ",$OEDONE/omap3-console-image-overo.tar.bz2"

* then run the image under qemu:
::<code># qemu-system-arm -M overo -m 256 -sd $OVEROTOP/overo.img -clock unix -serial stdio -net user -device usb-kbd -device usb-mouse</code>


= Ancient (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 <code>mmcinit</code> 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 (<code>fsload && bootm</code> is usually enough), or set a new <code>bootcmd</code> and <code>saveenv</code> 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[http://sourceforge.net/projects/gumstix/]):
 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 <code>/etc/init.d/S30bluetooth</code> script will never complete (<code>Starting 32khz clock...</code> 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 <code>build_arm_nofpu/root/</code> 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.