QEMU User Emulation

This page describes how to setup and use QEMU user emulation in a "transparent" fashion, allowing to run non-native target executables just like native ones (./program).

In this text, "target" means the system being emulated, and "host" means the system where QEMU is running.

Note: this text depends on features that are not available in official Debian qemu package as of 2006-02-26. See [http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=306637 this bug report] for details.

Note this setup is incompatible with Scratchbox (both use the binfmt_misc module to register the same binaries), so it's recommended to remove [http://www.scratchbox.org Scratchbox] (or stop its init script) before continuing.

Installing binfmt-support

The binfmt-support package contains a helper script to easily register/unregister binary formats with the kernel using the [http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html binfmt_misc] module.

  1. Install the binfmt-support package (used by qemu to register the supported binary formats):

    # apt-get install binfmt-support
  2. Check whether the binfmt entries were successfully registered:

    # update-binfmts --display

The last command should print entries for each supported target user emulator, except for the host system.

Installing QEMU

Finally, install the qemu package:

# apt-get install qemu

There is also a qemu-user-static package that contains statically linked versions of the user mode emulators. Install it if you want to chroot into target filesystems (see Appendix below).

Running dynamically linked executables

With the instructions above, you should be able to run statically linked target executables. To be able to run dynamically linked binaries, QEMU needs to have access to the target ELF interpreter. For convenience, the default search path for the ELF interpreter was setup to the same directory used by dpkg-cross for installing converted target packages for cross-compilation.

Installing the target C libraries with dpkg-cross

The libc6 package contains the target's ELF interpreter used by QEMU. The target Debian package cannot be installed directly on the host, so we need to use [http://packages.debian.org/unstable/utils/dpkg-cross dpkg-cross] to "cross-install" the package.

For example purposes, let's assume the target system is "arm".

  1. Install the dpkg-cross package:

    # apt-get install dpkg-cross
  2. Now download the target libc6 package from one of the Debian mirrors and install it using dpkg-cross:

    # wget http://http.us.debian.org/debian/pool/main/g/glibc/libc6_2.3.5-6_arm.deb
    # dpkg-cross -i -a arm libc6_2.3.5-6_arm.deb

Testing the emulation environment

We will use the "hello" ARM Debian package to test the new environment.

  1. Download the hello package (e.g. from

http://http.us.debian.org/debian/pool/main/h/hello/hello_2.1.1-4_arm.deb).

  1. Unpack it with the command:

    $ dpkg -x hello_2.1.1-4_arm.deb /tmp/hello_arm
  2. Finally, run the hello executable with:

    $ /tmp/hello_arm/usr/bin/hello

It should print "Hello, world!".

That's it! You can now run non-native executables transparently, as long as QEMU supports the system calls used by it.

Appendix: chrooting into target filesystems

To be able to chroot into a target filesystem, the qemu emulator for the target CPU needs to be accessible from inside the chroot jail. For this to work, you need first to install the qemu-user-static package:

# apt-get install qemu-user-static

You cannot use the dynamically linked qemu because the host libraries will not be accessible from inside the chroot.

Next, copy the the relevant emulator to the same path as registered by binfmt-support. For example, for an ARM target filesystem, you need to do the following:

# cp /usr/bin/qemu-arm-static /target_fs/usr/bin/qemu-arm

Now you are able to chroot into the filesystem:

# chroot /target_fs/

TODO