Linuxstamp:Buildroot

Building a Toolchain and Kernel for the Linux Stamp using Buildroot

When the Linux Stamp boots, a tiny little loader called the Darren Loader fires up, which in terms passes control to U-Boot. U-Boot's job is to locate and pass control to the Linux Kernel, which is the piece of software that sticks around, interfacing to the hardware, but at the very beginning it it responsible for locating a root file system, mounting it, and then creating the initial userland processes.

In other words, there are two distinct pieces of code that you need to supply so that the Stamp can be up and running with Linux: these two are (i) the Linux Kernel and (ii) the Linux Root File System (i.e. all the files under "/").

To be able to build any of this stuff though, you can't use the compiler you have on your x86 machine. The gcc on your x86 machine will normally generate x86 code targeted at an x86 machine. Unfortunately, the Linux Stamp doesn't have an x86 processor - it has an ARM processor. To be able to get gcc to create code that will run on the ARM processor on the Linux Stamp, you will need a cross compiler (aka toolchain) i.e. something that runs on a HOST machine and compiles to a different architecture, called the TARGET architecture. In your case, the HOST architecture is presumably x86 and your TARGET architecture is arm (which is what the Linux Stamp has on it).

That brings out list of things we have to create up to three: (i) the cross compiling toolchain (ii) the linux kernel and (iii) the root file system.

For purposes of this discussion, I'm going to assume that your desktop or server (called the "HOST") where you are going to run the compiler is an x86 machine running Ubuntu (or some other Debian based) Linux. Specifically, these worked on my workstation, which is running Ubuntu 8.04 (Hardy Heron) with all the latest patches and updates. To be more accurate, I am actually running it on a virtual machine using the fabulous and free VirtualBox (available here: [1] ) from Sun, running on my MacBook Pro. I've found VirtualBox to be more stable and much faster than either VMWare's Fusion or Parallel's Desktop for Mac. What's more, VirtualBox is completely OpenSource, which means that support for it is outstanding (far better than I ever received from Parallels who still don't have full support for Ubuntu 8.04).

Getting to Hello World on your own custom kernel and file system

This page will try and get you to the point where you will create a "Hello World" executable that you can run on your newly customized and compiled Kernel and Root File System.

Before we can do that, recall that you will need to solve three problems: (i) toolchain (ii) kernel and (iii) root file system. Once you have all three, you will use that toolchain to (cross) compile your HelloWorld.c file into a HelloWorld ARM executable, which you can then transfer over to the Stamp's new file system and run it on the Stamp!

The beauty of Buildroot

Buildroot is a very cool set of makefiles and scripts that can do all three of these for you. For a variety of reasons though, we are going to use Buildroot to do just two of the three ... we'll use it to build the toolchain and to build the root file system. We'll build the kernel separately, because, well ... once you have the toolchain ready, recompiling the kernel is pretty straightforward and the tools that come with the kernel to build it are perfectly adequate, and it's nice to keep things simple when we can :-)

Buildroot, as the name suggests, allows you to build a root file system. What's nice about it is that it allows you to build the root file system in a self contained directory, and you wont need to build it as root! The only point where you may need to become root or use 'sudo' is to install any packages that you may not already have installed. One of the nicest things about buildroot is that it will create a corss compiler that uses the uClibc library, which is a super-slimmed down version of the usual glibc library. uClibc is designed for embedded systems, and dramatically reduces the size of the binaries that you create.

So, lets get started with that ... before you can use buildroot, you need to have a bunch of packages installed. On Ubuntu/Debian, you can do this as follows:

$ sudo apt-get install build-essential libncurses-dev bison flex texinfo zlib1g-dev gettext libssl-dev wget autoconf

While we're at it, let's grab a couple of utilities that will come in handy later on, though they aren't really needed for getting buildroot to work:

$ sudo apt-get install autoconf dropbear minicom lrzsz

Grabbing Buildroot

Getting Buildroot is easy ... provided you have subversion installed. Before you begin, create a new directory that will contain all the files and build environment for the stamp. I'm going to assume you will create a directory called stamp in your home directory, and we'll do all our work from within that directory.

$ mkdir ~/stamp
$ cd ~/stamp
$ svn co svn://uclibc.org/trunk/buildroot

You should see a LOT of output as the files are pulled across the network. When all is done, and if all goes well, you should have a new subdirectory called buildroot ... let's switch to that directory:

$ cd buildroot

You are now ready to configure and build the toolchain and your root file system!

Building the Root File System

Buildroot allows you to very carefully finetune just what goes on your root file system. You can build a very comprehensive root file system that includes a compiler and a full development toolchain, or, you can build a very minimal root file system that can boot linux and do very little else!

The decisions on what to include and what not to include, are up to you, but the process of deciding that can be a little overwhelming to begin with. Fortunately, buildroot is designed so it saves the specific choices on what and how to build in a file called '.config'. To save yourself the hassle of building a configuration from scratch, I have created and saved a few config files for you. I have tried most of them, so they should work on your system as well.

The appropriately named 'busybox' utility could also do with a linux-stamp custom configuration, so we'll use a slightly customized version of that config utility as well.

Grab the collection of config files that I have created for the Linux Stamp so far (I'll keep adding to this as I create other interesting configurations) and untar it

$ wget http://homepage.mac.com/vvaidy/linuxstamp/downloads/linuxstamp-br-configs.tar.gz
$ wget http://homepage.mac.com/vvaidy/linuxstamp/downloads/linuxstamp-bb-configs.tar.gz
$ tar xzvf http://homepage.mac.com/vvaidy/linuxstamp/downloads/linuxstamp-br-configs.tar.gz
$ tar xzvf http://homepage.mac.com/vvaidy/linuxstamp/downloads/linuxstamp-bb-configs.tar.gz

Start out with the simplest of configurations, usually called something like Stamp-config-Stable001 (it may be 002 or higher by the time you read this). Let's use this as our starting config file, and update the Buildroot config with it.

$ cp Stamp-config-Stable001 .config
$ make oldconfig

If you want to take a look at what options this config file includes, you can look at it using the 'menuconfig' or 'xconfig' utilities. I'd suggest you resist the temptation to make any changes though, you'll have plenty of time to do that later. Even seemingly simple changes can case the build to fail, so at least when you are starting out, try and use the simple configuration to get you going.

$ make menuconfig

The only item that you may want to change, depending on your setup, is under 'Build Options' and then 'Number of jobs to run simultaneously'. I have set the default to 4, which should work well on most dual core cpus. If you are compiling on a relatively low-horse-power cpu, you may want to change this back to 1

Once you have had a chance to look around, exit the menuconfig utility.

Note: if you made unintended changes, make sure you do NOT save your changes. Even if you do inadvertently change something and save it, you can always copy back the Stamp-config-stable001 file and run 'make oldconfig' again.

Now you are ready to build ... and all that involves is doing a 'make'

$ make

This would be a good time for you to take a break and grab a cup of coffee or a different beverage of your choice, since this could take a little while. Buildroot will figure out what files it needs to download, grab them, unpack them and compile them. Depending on your machine and the bandwidth you have available, it can take anything from 15 minutes up to an hour or even longer. Don't worry - it'll take this long only the first time around. The next time you do a rebuild, it'll be a lot faster, even if you start from scratch, since the Buildroot downloads the files just once and keeps them around in the 'dl' subdirectory.

If all goes well, it should complete without any errors and would have created your shiny new root file system in your 'binaries/Stamp' directory. For instance, here is what my directory looks like:

vvaidy@vhardy:~/stamp/buildroot$ ls -sl binaries/Stamp/
total 6080
6080 -rw-r--r-- 1 vijay vijay 6213120 2008-08-15 12:44 rootfs.arm.cpio
vvaidy@vhardy:~/stamp/buildroot$ 

Congratulations! You have built a toolchain and used it to build your own distribution of Linux. Before we can use this distribution though, we'll do a little customization before we proceed. We'll handle that next. In the meanwhile, if something went wrong, check out the Troubleshooting section below. Unless you've been successful in creating this root file system, there really is little point in continuing, so you're going to have to fix it now.

(this is a work in progress ... to be continued)