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

Yocto Project Support for 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.

For the older version using Ångström see Linux on Ethernut 5.

Yocto, OpenEmbedded and BitBake

Before we start, let me explain a few basic things. The Yocto Project provides templates, tools and methods to create a customized Linux distribution. It uses OpenEmbedded-Core 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-Core 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, Yocto is able to create complete Linux distributions with packages, package manager, file system images etc.

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 12.4 LTS 32-bit is the recommended environment to build an Ethernut 5 board support package. A list of Linux distributions supported by Yocto can be found here.

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 gawk wget git-core diffstat unzip texinfo \
build-essential chrpath libsdl1.2-dev xterm

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. See here for other distributions. Depending on the performance of your PC and your Internet connection, this may take 15 minutes.

Now you need to download and unpack Yocto:

tar -xjf poky-dylan-9.0.0.tar.bz2

The newly created directory ~/poky-dylan-9.0.0 contains bitbake and recipes for Openembedded-Core and Yocto. The next steps will be done in this directory:

cd ~/poky-dylan-9.0.0
Yocto does not include all packages, so we add a new layer with extra recipes:
git clone git://
cd meta-openembedded
git checkout remotes/origin/dylan
cd ..

Installing the Layer for Ethernut 5

Now you need a new directory with recipes specific to Ethernut 5 and a directory where you build the binaries:

cd ~/poky-dylan-9.0.0
tar -xjf meta-egnite-20130531.tar.bz2
tar -xjf build-ethernut5-3.8-20130531.tar.bz2

The directory meta-egnite contains recipes to build Linux, U-Boot and the filesystem. These recipes modify the recipes of Yocto with Patches for Ethernut 5.

We will use the directory build-ethernut5-3.8 to build the binaries.

Here is the final structure of important directories:

   +-- bitbake
   +-- build-ethernut5-3.8
   |      |
   |      +-- conf
   |      |
   |      +-- tmp
   +-- documentation
   +-- downloads
   +-- meta
   +-- meta-egnite
   |      |
   |      +-- conf
   |      |
   |      +-- recipes-bsp
   |      |
   |      +-- recipes-kernel
   |      |
   |      +-- recipes-multimedia
   +-- meta-hob
   +-- meta-skeleton
   +-- meta-yocto
   +-- meta-yocto-bsp
   +-- scripts
   +-- sstate-cache

The directory build-ethernut5-3.8 is the root directory for building Linux kernel 3.8.2, including the related boot loader and the Yocto based Linux 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/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 downloads will be created when starting the build process and will contain all downloaded files. The directory sstate-cache will be used by bitbake to cache outputs while building.

Building U-Boot

Change to the yocto directory. It contains a shell script to set the OpenEmbedded environment. Execute it in the current shell context, using the source command. It also needs to know which is your build directory.

cd ~/poky-dylan-9.0.0
source oe-init-build-env build-ethernut5-3.8

This will set the environment variables to provide the bitbake command. It also changes the current directory to build-ethernut5-3.8.

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.

In the end, you should find the resulting U-Boot binary in ~/poky-dylan-9.0.0/build-ethernut5-3.8/tmp/deploy/images/u-boot-ethernut5-2013.01.01-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 U-Boot also creates the file ~/poky-dylan-9.0.0/build-ethernut5-3.8/tmp/deploy/images/env-ethernut5.bin, which contains environment variables for U-Boot in binary form.

Building the Linux Kernel

If not already done, change to the build directory using oe-init-build-env.

cd ~/poky-dylan-9.0.0
source oe-init-build-env build-ethernut5-3.8

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.

The resulting images can be found in ~/poky-dylan-9.0.0/build-ethernut5-3.8/tmp/deploy/images/. The image you need for booting is uImage-ethernut5.itb. It contains the Kernel and the Device-Tree for Ethernut 5. The Device-Tree contains informations about the hardware and can also be found in uImage-ethernut5.dtb. The file uImage-ethernut5.bin contains the Linux Kernel without the Device-Tree.

Building the Root Filesystem

As usual, change to the build directory using oe-init-build-env.

cd ~/poky-dylan-9.0.0
source oe-init-build-env build-ethernut5-3.8

Build the root filesystem with

bitbake ethernut5-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 ~/poky-dylan-9.0.0/build-ethernut5-3.8/tmp/deploy/images/. The file ethernut5-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 ethernut5-image-ethernut5-20130507170249.rootfs.jffs2. Furthermore, there's a file named ethernut5-image-ethernut5.tar.bz2, linked to ethernut5-image-ethernut5-20130507170249.rootfs.tar.bz2. 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. Here is a list of other resources on the internet.

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


Castrop-Rauxel, 15th of July 2013.