Frankenchroot

Subpages:

Introduction

A frankenchroot is the act of chrooting into a directory on a host system (typically x86-64bit) which contains a foreign architecture (such as arm-32bit or arm-64bit) and having it all magically work thanks to the power of QEMU. While this may seem like it should not work at all (thus the name "frankenchroot", like the Frankenstein monster,) it actually happens to work -- and work well -- and it is a very useful trick. This page will guide you through the process of setting up a frankenchroot on your own system.

Benefits of Frankenchroot

There are several benefits to setting up a frankenchroot. The primary benefit is that it is a compelling alternative to the two other options one has available for building stuff on lower-powered (in terms of CPU performance as well as power utilization) embedded CPUs. Until now, the only options available have been compiling the software on the embedded CPU itself, or setting up a cross-compile environment, which can be complex and problematic.

Building on the embedded CPU can be fine, but for many embedded systems and packages can be slow, and it's common to run into limitations related to available CPU power and RAM, as well as IO speed on embedded storage. By using a frankenchroot, these limitations can be completely eliminated.

Types of Frankenchroot

Simple Frankenchroot

A "simple" frankenchroot is very similar to doing a regular chroot. One scenario would look like this. Let's say you wanted to test and arm-32bit stage3 tarball on your fast x86 workstation. You would create a directory, extract the stage3 into this directory, perform some setup to enable frankenchroot, and then you could chroot into this arm-32bit environment and it would work just like you chrooted into a native x86 stage3. You could then perform some test emerge commands which would take advantage of all your x86 CPU cores, memory and IO.

Live Frankenchroot

There is another cool thing you can do with a frankenchroot, and that is to set up a live frankenchoot. In this configuration, you would use something like a Raspberry Pi 3 and export its filesystems using NFS. These filesystems would then get mounted on a host x86 system via NFS. The host x86 system would then frankenchroot into this NFS-based filesystem -- even though the Raspberry Pi 3 is booted and running! In fact, it is quite possible -- and safe -- to run an emerge command on your x86 live frankenchroot while your Raspberry Pi does other things.

The benefit here is that you can use your x86 system to emerge lots of packages, and it doesn't even require shutting down your Raspberry Pi and removing the MicroSD card, which can be inconvenient and requires the Raspberry Pi to be turned off.

Frankenchroot Setup

Up-to-date Frankenchroot setup steps can be found on the code.funtoo.org frankenchroot page.

How It Works

A frankenchroot works by leveraging a static QEMU executable as the "handler" for any binaries that are built for your embedded device. Then, when you are in the chroot and the kernel attempts to run one of these binaries, it will call QEMU to execute the binary, and QEMU will interpret the machine code in the binary and run it transparently. The "handler" mechanism used is the Linux kernel binfmt_misc functionality.

So, the steps in the frankenchroot work as follows:

Linux kernel encounters foreign binary.
Linux kernel sees that this is a foreign binary and that a static binary QEMU is registered to "handle" it.
Linux kernel runs QEMU and essentially passes the foreign binary to QEMU as an argument. QEMU runs fine since it is compiled for your workstation's architecture rather than the foreign architecture. So QEMU runs happily on your local CPU.
QEMU does its thing and interprets the contents of the foreign binary so that it performs all calculations and actions as if it were running on native hardware. Any kernel calls contained in the foreign binary are either translated by QEMU so that they can run using your host's kernel or emulated.