Ethernut Home Hardware Firmware Tools Download Community
 
Ethernuts  /  Ethernut 5  /  Linux
Search | Legals | Deutsch

Linux on Ethernut 5

This document will explain, how to build a U-Boot boot loader, a Linux kernel and the related root filesystem for Ethernut 5. No problem, if you are new to embedded Linux. I tried to provide a simple step by step guide. However, be prepared that the build process takes several hours and requires a powerful PC and an Internet connection. See the chapter Development Environment below.

If you only want to upgrade your board with existing binaries, then Ethernut 5 Boot Loading is the right document for you.

History

In the first place, Ethernut boards are typically tiny systems, designed to run Nut/OS. However, as the performance of CPUs and specifically the size of embedded memory increased dramatically, the latest member of our Ethernut family, board version 5, has sufficient power to run Linux.

In mid 2009, Ole Reinhardt, a long time supporter of Nut/OS, offered to develop a Linux Board Support Package for Ethernut 5, which had been finished and published a few months later by his company Embedded-IT, a subsidiary of ThermoTemp. The first version had been presented on Elektor Live 2009 in Eindhoven. Embedded-IT also offers commercial support as well as free board support packages for download.

Unfortunately, the production of Ethernut 5 was accompanied by bad luck of all kind. The hardware development started in September 2007 and the first production finally took place in May 2011. One of the last problems that significantly delayed its release was the missing Linux support for the selected NAND Flash chip. For me it was a steep learning curve, tracking down Linux flash filesystem problems with my vague knowledge of Linux in general. I'm sure, I pushed Ole's patience to the limits. Well, what did I learn during these 4 years? Never give up! :-)

Finally Linux is running fine on Ethernut 5. Right now there are still rough edges, but further development takes big steps and we are quite happy with the results. During the next weeks I hope I will be able to help you to get into Linux development with less pain than I experienced. Let me start with a basic document and refine it step by step.

Ångström, OpenEmbedded and BitBake

Before we start, let me explain a few basic things. Ångström is the name of a Linux distribution, like Redhat, Suse or Ubuntu. It uses OpenEmbedded for building the distribution, which in turn is a collection of BitBake recipes.

BitBake may be viewed as a tool like Make. It evaluates dependencies to build a specified target. In that figurative sense, OpenEmbedded is a collection of Makefiles, ready to build Linux boot loaders, kernels and root file system images. The great thing of all this is, that it builds almost everything from scratch, including the required tools and even complete cross compiler toolchains. All you need is, what typically comes with almost any Linux distribution. Finally, OpenEmbedded is able to create complete Linux distributions with packages, package manager, file system images etc. Ångström is one of them.

Development Environment

Well, umh... I lied a bit. The claim was, that BitBake will build everything it needs by itself. Actually, some additional tools are required, which, however, are quite easily installed with a few command lines on most Linux PCs.

The bad news for Windows and MAC OS X users is, that it will be quite hard to get this done under your preferred OS. It may work on Fink or Cygwin, but I'd recommend to use a real Linux OS. Not totally real, because it will work fine on a virtual machine, provided, that your PC has sufficient resources.

You will need at least 30 GBytes of free disk space, or 60 GBytes to feel comfortable, being able to build more than one version. 2 GBytes of RAM isn't much, but will work. And you need a fast machine with 4 or 8 cores. Otherwise you need time... a lot of time. On an i7 CPU, it may take about 3 to 6 hours to build U-Boot, Linux and the file system. On an older dual core this may take 18 hours and more. With virtualization, you should reserve enough power for the guest OS.

I recommend VirtualBox. On Windows 7 Ultimate 64-Bit, I used VirtualBox 4.1.8 with Ubuntu 10.04 32-bit (Lucid) as the guest system. On Mac OS X 10.6.7 I tried VirtualBox 4.0.8 running Ubuntu 11.04. I thought and wrote earlier, that this is not critical, and that more or less recent versions should work as well. This is not the case. Finally it failed while building the filesystem image. Michael Fischer reported, that Ubutnu 10.04 LTS runs well with VirtualBox 4.0.8 under OS X hosts. Also note, that not all tools are available for 64-bit Linux.

To conclude, Ubuntu 10.4 LTS 32-bit is the recommended environment to build an Ethernut 5 board support package.

Installing the Tools

I assume, that you setup Linux on your PC or virtual machine. Let's start with the additional tools we need to install. To make sure, that everything is available, execute the following command. 

sudo apt-get install sed wget cvs subversion git-core \
coreutils unzip texi2html texinfo libsdl1.2-dev docbook-utils \
gawk python-pysqlite2 diffstat help2man make gcc build-essential g++ \
desktop-file-utils chrpath python-progressbar python-ply

Note, that I'm using apt-get for installing the packages. Of course, you can use any other package tool that is available with your Linux distribution. Depending on the performance of your PC and your Internet connection, this may take 15 minutes.

The following tools are not essential, but helpful. Specifically python-psyco will significantly speed up the build process. 

sudo apt-get install libxml2-utils xmlto python-psyco

On Ubuntu 11.04 I got the advice to install python-psyco to increase the performance, although it seems to have been installed without error. I have no idea, why. It later turned out, that more things are not working on the Ubuntu 11 release. Furthermore, python-psyco is not available for 64-bit systems.

Now we create a new directory, where all our Ethernut 5 Linux related stuff will go. It's a good idea to define an environment variable containing the path to this directory. 

export OEBASE=${HOME}/nutoe
mkdir $OEBASE

After changing to this new directory, we will first install BitBake. But this time we will not and should not use any package manager. It is important to install it manually. This is quite simple: 

cd $OEBASE
wget http://downloads.yoctoproject.org/releases/bitbake/bitbake-1.12.0.tar.gz
tar -xvzf bitbake-1.12.0.tar.gz
ln -s bitbake-1.12.0 bitbake

As a result, the directory ~/nutoe/bitbake/ contains the basic BitBake recipes and configuration files. For some time BitBake version 1.14.0 is available, so far I didn't test that one.

In the next step OpenEmbedded will be installed. 

cd $OEBASE
wget http://cgit.openembedded.org/cgit.cgi/openembedded/snapshot/release-2011.03.tar.bz2
tar -xjf release-2011.03.tar.bz2
ln -s release-2011.03 openembedded

That's it. We have all tools required to install Linux for one of the officially supported target boards. Right now, Ethernut 5 is not yet included and we need to apply a few patches.

You may now ask, where's Ångström? You already installed the related recipes, because they are included in the OpenEmbedded package.

Installing an Overlay for Ethernut 5

We will not touch the contents of the newly installed directories $OEBASE/bitbake and $OEBASE/openembedded. Instead we will create two additional directories. One of them will be the build directory, where we are going to build the Linux kernel. The other one will contain a so called overlay tree. This means, that any file in this directory will be automatically added to $OEBASE/openembedded. If both directories contain the same file, BitBake will use the one located in the overlay tree and ignore the original file in $OEBASE/openembedded.

Both directories are simply created by downloading two archives and unpack them in $OEBASE/. 

cd $OEBASE
wget http://www.ethernut.de/arc/egnite-oe-overlay-20120328.tar.bz2
tar -xjf egnite-oe-overlay-20120328.tar.bz2
wget http://www.ethernut.de/arc/egnite-oe-build-3.2.9-20120328.tar.bz2
tar -xjf egnite-oe-build-3.2.9-20120328.tar.bz2

Here is the final directory structure, up to the third level: 

nutoe
   |
   +-- bitbake
   |      |
   |      +-- bin
   |      |
   |      +-- classes
   |      |
   |      +-- conf
   |      |
   |      +-- contrib
   |      |
   |      +-- doc
   |      |
   |      +-- lib
   |
   +-- openembedded
   |      |
   |      +-- bin
   |      |
   |      +-- classes
   |      |
   |      +-- conf
   |      |
   |      +-- contrib
   |      |
   |      +-- docs
   |      |
   |      +-- files
   |      |
   |      +-- lib
   |      |
   |      +-- recipes
   |      |
   |      +-- site
   |
   +-- egnite
   |      |
   |      +-- recipes
   |
   +-- build-3.2.9
   |      |
   |      +-- conf
   |      |
   |      +-- tmp
   |
   +-- sources

Directory bitbake is the basis, complemented by openembedded, which in turn is complemented by egnite. All Ethernut 5 specifc files are located in the latter, including patches. Note, that any recipe provided by egnite will replace any with the same file name in openembedded and/or bitbake.

The directory build-3.2.9 is the root directory for building Linux kernel 3.2.9, including the related boot loader and the Ångström distribution. We will change to this directory before starting the build. The directory conf contains, you guessed it, a few configuration files, while directory tmp will be created during the build, containing all the results. Its name may mislead you to remove it to get back more disk space, which is a very bad idea. Beside the final images (in tmp/deploy/eglibc/images) it will also keep all the executables of the required tools, like the cross compiler toolchain. If you remove them, BitBake must re-create them, which takes most of the time during the first run.

The directory sources will be created when starting the build process and will contain all downloaded files.

As always, there is a gap between theory and reality. Although I told you, that we will not touch the directory openembedded, we have to. Alternatively, we may override the related files, but this is tricky because of many dependencies. So we decided to provide two small patches. To apply them, use 

cd $OEBASE/release-2011.03
patch -p1 < ../egnite/openembedded-2011.3.patch
patch -p1 < ../build-3.2.9/openembedded-linux-3.2.patch

This patch will mainly update package checksums.

Solving Problems with Ubuntu

Typically the dash shell is used by default, but some scripts may fail with this shell. You can check the currently used shell with 

ls -l /bin/sh

To switch to the Bash shell, enter 

sudo dpkg-reconfigure dash

and answer the following question with NO.

Another problem is, that BitBake expects the lower memory limit to be zero. Use 

sudo sysctl -w vm.mmap_min_addr=0

to fulfill this requirement.

ply progressbar

Building U-Boot

Change to the build directory. It contains a shell script to set the OpenEmbedded environment. Execute it in the current shell context, using the source command. 

cd ~/nutoe/build-3.2.9
source setenv.sh

This will also set the environment variable OEBASE, which we previously set manually. If you are using a different path, you need to modify setenv.sh. Note, that you must call those two commands above each time you open a new command line shell.

For the most simple case we tell BitBake to build U-Boot, using 

bitbake u-boot

When running this little command for the first time, it will have a significant impact and may take hours to execute. It will download the source code not only of U-Boot, but also of the required GNU toolchain and any related tool that may be additionally required.

As explained above, BitBake will retrieve any required source code including patches from the Internet and store this in nutoe/sources. Over the time URLs may change, files may vanish or servers may become unavailable. You should first try the bitbake command once again. If BitBake still fails due to a missing download, you can google for an alternative source and download it manually, including its related md5 file. For example, the ncurses-5.7 patch wasn't available recently, because ncurses-5.7 has been removed from ftp site invisible-island.net in favor of version 5.9. This could be fixed with 

cd $OEBASE/sources/
wget ftp://ftp.koansoftware.com/public/oe/sources/ncurses-5.7-20100424-patch.sh.bz2
wget ftp://ftp.koansoftware.com/public/oe/sources/ncurses-5.7-20100424-patch.sh.bz2.md5
wget ftp://ftp.koansoftware.com/public/oe/sources/ncurses-5.7-20110108-patch.sh.bz2
wget ftp://ftp.koansoftware.com/public/oe/sources/ncurses-5.7-20110108-patch.sh.bz2.md5

Then return to the build folder and start BitBake again. It will almost continue where it had been interrupted by the failure. So nothing is lost. 

cd $OEBASE/build-3.2.9
bitbake u-boot

In the end, you should find the resulting U-Boot binary in $OEBASE/build-3.2.9/tmp/deploy/eglibc/images/ethernut5/u-boot-ethernut5-2011.03-r1.bin and a link named u-boot-ethernut5.bin, which points to the same file. The latter should be used for booting Ethernut 5.

Building the Linux Kernel

If not already done, change to the build directory and set the OpenEmbedded environment. 

cd ~/nutoe/build-3.2.9
source setenv.sh

It is required to have U-Boot built, because the kernel image will be stored in uImage format, for which uboot-mkimage is required. Alternatively you may install this tool as a binary package.

Build the kernel with 

bitbake linux

As most of the tools had been build for U-Boot already, this will not take much time. Depending on your computing power and Internet link, may be 10 to 30 minutes.

Building the Root Filesystem

As usual, change to the build directory and set the OpenEmbedded environment, if not already done. 

cd ~/nutoe/build-3.2.9
source setenv.sh

Build the root filesystem with 

bitbake console-image

This image will contain a large number of executables. Therefore, building it takes much more time than any of the images we build previously.

The result can be found again in nutoe/tmp/deploy/images/ethernut5. The file console-image-ethernut5.jffs2 contains a file system in JFFS2 format and can be directly used for uploading to U-Boot, which is able to write it to the NAND Flash. It is linked to a more descriptive file named Angstrom-console-image-eglibc-ipk-next-ethernut5.rootfs.jffs2. Furthermore, there's a file named console-image-ethernut5.tar.bz2, linked to Angstrom-console-image-eglibc-ipk-next-ethernut5.rootfs.jffs2. This can be unpacked on an existing file system like a memory card or stick or an NFS share.

What to do next?

You probably want to modify the current images, most probably the content of the file system or the kernel configuration. Or may be you want to strip down U-Boot to make it fit in the AT91SAM9XE's internal Flash? All this can be done, but requires specific procedures to do it right. During the next weeks I'll try to provide more help. For the time being you may check existing resources in the Internet.

Ethernut 5 Boot Loading discusses different ways to upload the images to the target board.

Enjoy!

Castrop-Rauxel, 13th of June 2011.