Idiots Guide to the AVR32, Linux and Development Boards

...dives into details where other guides take shortcuts

This is an AVR32 & Linux guide for dummies. It will go through everything you need to know to get started with the AVR32 development boards and Linux. Where other guides take shortcuts, this guide takes a deep dive into the details, and let you actually get through the guide with only one question in mind: Where can I learn more?. So go put on a cup of coffee, get your seat back in a full upright position, take deep breath and read on...

1. Introduction to Linux

1.1 Linux

1.1.1 What is Linux

Linux is a Unix-like operating system (but Linux Is Not UniX). The Linux kernel is the core of the Linux operating system and often just referred to as the kernel. The kernel provides basic services for all other parts of the operating system and contains e.g. drivers for hardware interfacing, schedulers, interrupt handlers etc.

Linux is divided into user space and kernel space. All applications run in user space and do not have access to the hardware on the system. The kernel and drivers are located in the kernel space, and acts as the connection between user space and hardware. It provides applications simple interfaces to access hardware.

Linux is a very complete operating system and does have a graphical user interface (GUI), support for most general computer hardware and tons of free applications like web browsers, e-mail clients etc. In addition, it is very configurable and last, but not least, it is open source, hence free of charge.

1.1.2 Linux and the AVR32

Some of the processors within the AVR32 architecture are able to run Linux, and some are not. While the AP7 family are fully capable of running Linux, the UC3 family does not have an MMU (Memory Management Unit), which is something that Linux needs in order to, amongst other things, allocate memory on the fly to applications. Hence, the UC3 cannot run the Linux operating system.

The AP7 family. ...something...

1.1.3 Linux and My Desktop Computer

There are many different distributions of Linux, and the Atmel AVR32 development tools are precompiled for a handful of these distributions:

1.2 Cygwin

Cygwin is a Linux-like environment for Windows. It emulates the Linux API through dll files and recreates the Linux look-and-feel. Cygwin can be downloaded from http://www.cygwin.com/

1.3 Linux vs. Cygwin in the AVR32 World

The Cygwin environment is not a full flegded Linux-emulator. Because it is running in Windows user space, it is difficult to access hardware the same way that you can do in Linux. Also, in Windows and hence also in Cygwin, there is no difference between a filename in lower case or upper case. This can create a few errors when compiling large applications, where several files have the same names, but with a different case setting.

Therefore, for recompiling the AVR32 toolchain, one should use the Linux operating system, and not the Windows emulator. For normal development, however, Cygwin will do just fine.

1.4 The AVR32 Toolchain

The AVR32 toolchain was mentioned in the above section, hence, giving that this is the most thorough AVR32 guide to thi date, it will be explained in the following section. A toolchain is a blanket term for all the different tools that are needed (or available) for creating a development environment for a specific architecture. The AVR32 toolchains consists of modified versions of the tools in the GNU project (these tools are called the GNU toolchain). These tools include (amongst others) the Gnu C Compiler (GCC), binary utilities for manipulation of object code in various formats (binutils) and the GNU debugger (GDB).

2. Installation

This chapter explains all the steps that are needed to get started with the AVR32.

Prerequisites: A computer (with an internet connection), one of the AVR32 development boards and possibly a (legal) copy of MS Windows (if you don't like Linux).

2.1 Installing the AVR32 Tools in Linux

This section will give a brief description of how to install the tools needed for AVR32 onto your computer running Linux. This guide will not cover all the different Linux distributions available, but we will focus on Ubuntu, which has turned out to be one of the most common distributions. If you do not have Linux installed on your computer, but is eager to try it, we have also included download&install instructions for the Ubuntu distribution.

2.1.1 Installing Linux on my Desktop Computer

The Ubuntu distribution can be downloaded from http://www.ubuntu.com/. Download, burn the image to a CD with your favorite CD burning application, or get your neighbour to do it for you. If you want to use Ubuntu or Kubuntu etc. is up to you. The two different versions have different applications installed, which means that the GUI is different. It's a matter of taste.

Put the CD in your CD-ROM drive and reboot your computer. Make sure that it boots from the CD. The setup guide will follow you through the installation procedure.

2.1.2 Prerequisites for Using Linux and the AVR32 Tools

After you have installed Ubuntu, you will need some basic applications to be able to e.g. compile the toolchain. These applications include:

Lucky for you, you do not need to download and compile these applications all by themselves. Many of them are packed into one package called build-essential.

In Ubuntu, downloading and installing applications is quite easy throught the package system aptitude. To install the build-essential package, bring up the Linux console from the Applications menu, and at the command prompt, enter the following command:

 # sudo apt-get install build-essential

This package will then be downloaded from an official Ubuntu software server that keeps all the (un)popular applications. Not all applications are available on the standard software server, so we will have to add another software server to the list that aptitude reads everytime it's installing an application. This file is located in /etc/apt/ and is called sources.list.

At this point, we would normally tell you to open your favorite text editor and edit the file. In this case, however, will are going to edit a file that only the root user has access to. In Ubuntu, you have a small program called sudo. Appending sudo in front of the command that you want to run will give you root privileges for that single command as long as you specify the password set up with that user. E.g.

 # reboot
will only work as a root user, while 
 # sudo reboot
will work as a normal user.

The command

 # sudo gnome-text-editor
will open the standard gnome text editor in Ubuntu with root privileges, while 
 # sudo kate
will open the standard text editor in Kubuntu.

Open the file /etc/apt/sources.list and append the following lines at the end of the file:

 deb http://www.atmel.no/beta_ware/avr32/ubuntu/dapper binary/ 
 deb http://archive.ubuntu.com/ubuntu dapper main restricted universe multiverse

Save the file and close the text editor. Now it's time to let aptitude know that we have edited this file, and let it search for updateds and available packages. The following command will update _aptitude_'s local list of available packages:

 # sudo apt-get update

2.1.3 Installing the AVR32 Tools on Linux

With the aptitude package manager, it is very easy to download and install the AVR32 tools onto your Linux computer. As long as you have all the prerequisites as described in section 2.1.2, you can only execute this command from the console:

 # sudo apt-get install stk1000bsp

This will include all AVR32 tools, both for Linux and stand-alone development.

2.2 Installing the AVR32 Tools (including Cygwin) in Windows

This will install Cygwin on your computer, together with all the AVR32 specific tools. These will all be available from the Cygwin command line.

If you are a "1337 h4x0r" ("elite hacker", ref: LeetSpeak?. See ), and still want to rebuild the toolchain in Cygwin (remember that this will probably give you a few headaches during compiling), then you need to install a few other utilities. These can be found on http://www.cygwin.com/setup.exe. After pressing that (<---) link, you will get the Cygwin installation program up and running, and you can freely choose what packages to install. You will need (at least) the following packages (these are not AVR32 specific packages):

2.3 Installing AVR32 Studio

Installing AVR32 Studio should be straight forward. Go to the AVR32 Studio homepage (http://www.atmel.com/dyn/products/tools_card.asp?tool_id=4116), and click on the download links. If you have previously installed the toolchain (from the Board Support Package or similar) you might want to make sure that you have the newest version. As the homepages does not state what versions you need, you might as well download the full installer right away ( AVR32 Studio BETA Development Tools), so you won't have to spend your time downloading additional 80 MBytes. If you are really sure that you have the latest tools, then download the AVR32 Studio setup only. The AVR32 Studio installer for Windows will install the Cygwin Linux-like environment in addition to the AVR32 Studio IDE (Integrated Development Environment).

3. Development Boards

This chapter will give you a description of the different development boards from Atmel, including how to set them up for first time use. This includes jumper settings, connections etc.

3.1 STK1000/STK1002

The STK1000 development board is what is characterized as a Starter Kit. The reason for this is that you have the possibility to change the daugtherboard on the STK1000 (default is the STK1002) with other daugterboards that will be available in the future. The STK1002 that ships with the STK1000 contains the CPU AT32AP7000, which is the motherchip of the AP7000 family. It is expected that future STK100x will contain other chips in the AP7 family, like the AP7001 or AP7002.

3.2 Network Gateway

The Network Gateway (ATNGW100) is a reference design released by Atmel late March 2007. It contains an AP7000 soldered on to the board, two ethernet PHYs, MMC slot, 32MBytes of SDRAM, and 8Mbytes of both serial and parallell flash. The Network Gateway kit is a low cost kit (retail price is 69 USD), and comes with preinstalled bootloader, and filesystem with Linux in flash. The NGW100 also has alot of expansion headers for connecting the other modules on the AP7000.

The following files are the factory defaults for the Network Gateway:

4 Some Heading

4.1 How to set up the STK1000 to boot entirely from Flash

First of all, booting entirely from flash requires you to have both the bootloader, Linux kernel and the filesystem located in the flash. Putting the bootloader in the flash is not a big deal, neither is the Linux kernel, as these are just single files consisting of contious data. The filesystem, however, holds several files, and they must in some way be separated so they can be read/written to one by one. To do this, a filesystem structure is needed, and the particular structure used for flash devices is JFFS, or the Journaling Flash File System. The first version of this filesystem has been superseeded by version number two, so we'll be using the term JFFS2 from now on.

4.1.1 Creating the JFFS2 image that holds the files and directories

So, the first step is to create the filesystem. Luckily, there is an application Out There(TM) that can create this filesystem for us. The "mtd-tools" package contains several utilities for handling Memory Tecnology Devices, for example creating a filesystem for them.

We need to download this package, and compile it for the host computer (this is were we will create the filesystem, and we will just move it to the flash later on). We will later have to install this package on the AVR32 as well, but we'll get to that.

On most linux computers, this package is available from the distributions package system. If you are running e.g. Ubuntu, you can download and install the mtd-utils package with one single command:

 # sudo apt-get install mtd-tools

If you are running Cygwin, or you cannot install it throught the package system on your computer, please follow these steps to download and install the mtd-utils package:

Now that the tools for creating the filesystem image are installed, the filesystem itself can be populated. This is a fairly advanced job, as you need all the libraries for every application, you need the directory structure and you need device files so that applications can communicate with hardware (through the kernel and drivers).

To ease the job a bit, let's start with the filesystem included on the Board Support Package 2.0.0 by Atmel. For download instructions, see chapter 2.2 of this guide.

Let's start off with mounting the image as a folder on our local harddrive.

 # mkdir /path/to/root 
 # sudo mount -o loop /path/to/bsp-image.img /path/to/root

To create a JFFS2 filesystem image (let's say we want to call it root.img and put it in the folder"/path/to/images/") from a folder with a populated filesystem (let's say folder id called "root" and is located in "/path/to/"), this command will do the trick:

 # mkfs.jffs2 --output=/path/to/images/root.img --root=/path/to/root --big-endian --pagesize=4096 --eraseblock=65536

The "--big-endian" parameter specifies that the AVR32 is a big endian architecture, and is a critical attribute for the image to work. The "--pagesize=4096" and "--eraseblock=65536" matches the specification of the 8 MB NOR flash chip on the STK1000.

The file /path/to/images/root.img is now ready to be uploaded to the STK1000 flash.

4.1.2 Building the U-boot bootloader

In order to be able to run the filesystem and the Linux kernel off the on-board flash on the STK1000, we need to specify this to the bootloader. This can be done purely in the environment settings of the bootloader, so it is 1_not necessary to do this if you already have a working booloader on the target.

First, start off by copying the u-boot folder on the AVR32 Linux BSP CD to the local hard drive. This folder is located under the software folder.

 # cp -r /media/cdrom/software/u-boot/ ~/

Then, we need to extract the source code, patch the source with the AVR32 specific code that it needs to run on the AVR32, and finally compile the whole thing into a binary file that can run on the targert.

 # tar -xvjf  u-boot-1.1.4.tar.bz2
This will create a folder named u-boot-1.1.4. Enter this directory and patch the source: 

 # for i in `cat ../series`; do patch -p1 < ../$i; done

This will go through the file series in the folder above us and for each file name mentioned in that file, it will run the application called patch with that filename as parameter (../ denotes one level up in a folder hierarchy in Linux).

4.1.3 Compiling the Linux Kernel

4.1.4 Uploading the Bootloader, Kernel and Filesystem to the Flash on the STK1000.

For uploading the different parts, we will be using the application avr32program, which you downloaded in chapter 2.1.3. We'll start off with the bootloader:

 # sudo avr32program -cUSB program -vef 0,8MB ~/u-boot/u-boot-1.1.4/u-boot.bin

Then we continue with the Linux filesystem

4.2 How to set up the STK1000 to boot Linux from flash and run the filesystem from an SD card.

4.3 How to set up the STK1000 to boot entirely from Network.

4.4 How to set up the STK1000 to boot Linux from Network and run the filesystem from an SD card.