adm5120 toolchain, kernel & root fs HOWTO


Tom Wilms, tom AT nations DOT nl

2005-08-09

It boots :)

Table of contents

1. Introduction
2. Disclamier
3. Prerequisites
4. Configuring and building buildroot
5. Configuring and compiling the kernel
6. To do
7. Working firmware available for download
8. Files available for download


1. Introduction

This documents describes how to set up a cross compiler environment for mips32 using buildroot and uclibc.

Furthermore, it is shown how to build a quick and dirty 2.6.12rc1 kernel with an embedded root filesystem for use on an amd5120 board. About each step that has to be done to achieve this is described below.
Note that I won't go in to USB support since it really doesn't bother me.

I hope that this howto will be a basic help to get linux running on an adm5120, since it took me a while to figure out how to do so.
I wrote it rather quickly, so don't expect to much :).

Comments, questions etc are welcome at: tom AT nations DOT nl

2. Disclaimer

A lot of similar documents seem to have one, so here is something:

This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY, without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

What it comes down to is that I cannot be held responsible if you screw up something ;)

Copyright (c) 2005 by Tom Wilms.

3. Prerequisites

- a linux system with a working gcc toolchain etc or something similar

I also assume that you already have a working serial port on your adm5120 board and know how to upload a firmware using the xmodem protocol.

4. Configuring and building buildroot

Buildroot is a very handy tool that automates the process of building a cross-compilation toolchain and root filesystem for a certain target system using the uClibc C library. See http://www.buildroot.org for more information.

This chapter describes how to get a working toolchain and root filesystem.

4.1 Obtaining buildroot
I suggest you do a svn checkout in order to retreive to most recent version. See http://www.buildroot.org for details.
Another option is to download a daily snapshot, available here.

The version that will be used in this document is a svn checkout that I did on 2005-08-07 with some minor changes because of a bug regarding fakeroot. If you like to use this version, it is available here.

4.2 Unpacking, configuring and compiling buildroot
Note: you don't have to be root in order to perform the following steps

1. Save buildroot somewhere you like and unpack it:
tom@linux:~/adm5120> pwd
/home/tom/adm5120
tom@linux:~/adm5120> ls
buildroot-20050807-ext2rootfix.tar.bz2
tom@linux:~/adm5120> tar xjf buildroot*.bz2
tom@linux:~/adm5120> cd buil*
tom@linux:~/adm5120/buildroot>

2. Next, run 'make' to get a menuconfig:
tom@linux:~/adm5120/buildroot> make
...

3. You now have to configure buildroot. In order to quickly get a working configuration, choose the following options:
Target achitecture: mipsel
Toolchain options:
- Kernel headers 2.6.12
- don't use a daily snapshot of uclibc
- disable ccache support
- disable multilib support
- disable large file support
- enable include target utils in toolchain
Package selection for the target
- busybox
- don't use a daily snapshot of busybox
- Furthermore select what you like. You don't need to select any other packages in order to get a working system. (see note below)
Save the configuration and exit.

4. Next run 'make':
tom@linux:~/adm5120/buildroot> make
... and relax a bit while buildroot downloads and compiles packages :)

When buildroot ask for it, choose the following options:
- Target processor architecture: 5. MIPS32
- Target processor endianness: 1. Little Endian
- Target CPU has a memory management unit (MMU): y

When compiling is done, you should have a working cross toolchain and a root fs.

4.3 Notes
- Leave the 'buildroot' directory in place, since some paths are hardcoded in the executables that buildroot created
- It is possible to select other packages in the buildroot configuration; the above is only meant to quickly get a working configuration.
- Tip: If you select 'dropbear_sshd' (a tiny ssh daemon) in the buildroot config, make sure you enable 'Use /dev/urandom (low entropy systems only)?'
- It is possible to customize the target root filesystems after the build. However, I suggest you leave it untouched for now; we will be handling it in chapter five of this tutorial. More information on customizing it is provided in the buildroot documentation.
- BusyBox configuration can be customized. However, it is not needed in this tutorial. More information is provided in the buildroot documentation.

5. Configuring and compiling the kernel

This chapter describes how to build a 2.6 kernel for the adm5120 board with an embedded root filesystem.

5.1 Obtaining the kernel
For information on obtaining a linux-mips kernel, please refer to www.linux-mips.org

I will use a mipscvs snapshot 2.6.12rc1 kernel, which is available for download here.

5.2 Unpacking the kernel
The following steps will be performed as root in order to avoid problems concerning the root filesystem (there might be a better solution to do this, but the this works for me).

1. Unpack the kernel and create a symlink:
linux:/home/tom/adm5120 # pwd
/home/tom/adm5120
linux:/home/tom/adm5120 # ls
.  ..  buildroot  buildroot-20050807-ext2rootfix.tar.bz2  
linux-2.6.12-rc1-mipscvs-20050403.tar.bz2
linux:/home/tom/adm5120 # tar xjf linux*.bz2
linux:/home/tom/adm5120 # ln -s linux-2.6.12-rc1-mipscvs-20050403 linux
5.3 Downloading a patch and patching the kernel for adm5120 support
1. Download a adm5120 kernel patch:
A patch for the 2.6.12rc1 kernel is available here.
Patches for a few other kernel versions can be found at the author's site.

2. Patch the kernel:
(we're still in the same directory)
linux:/home/tom/adm5120 # patch -p0 < linux-2.6.12-rc1-adm.diff
patching file linux/Makefile
patching file linux/arch/mips/Kconfig
...
5.4 Configuring the kernel
1. Configure the kernel:
Do a 'make menuconfig' and choose the options you want, or download a working .config here.
linux:/home/tom/adm5120 # cd linux
linux:/home/tom/adm5120/linux # wget http://www.student.tue.nl/Q/t.f.a.wilms/adm5120/files/kernelconfig-2.6.12-rc1 -O .config
...
5.5 Customize the root filesystem
1. First, cd to the usr directory and create a folder root. We will mount the root filesystem that was created by buildroot here.
linux:/home/tom/adm5120/linux # cd usr
linux:/home/tom/adm5120/linux/usr # mkdir root
linux:/home/tom/adm5120/linux/usr #
2. Next, mount the root fs image:
linux:/home/tom/adm5120/linux/usr # mount  /home/tom/adm5120/buildroot/root_fs_mipsel.ext2 ./root -o loop
linux:/home/tom/adm5120/linux/usr #
3. You can now customize the root filesystem if you like. You should at least do the following to get things to work:
linux:/home/tom/adm5120/linux/usr # cd root
linux:/home/tom/adm5120/linux/usr/root # rm linuxrc
linux:/home/tom/adm5120/linux/usr/root # ln -s bin/busybox init
linux:/home/tom/adm5120/linux/usr/root #
4. Now change dir to the 'etc' directory and create a new inittab file or modify the existing one so that its contents are as follows:
# Mount filesystems
null::sysinit:/bin/mount -t proc proc /proc
null::sysinit:/bin/mount -t devpts devpts /dev/pts

# Start a sh shell
::askfirst:/bin/sh
5.6 Compiling the kernel
1. Make sure the mipsel-linux-gcc crosscompiler that buildroot created is in your path and compile the kernel:
linux:/home/tom/adm5120/linux/usr/root/etc # cd ../../../
linux:/home/tom/adm5120/linux # export PATH=/home/tom/adm5120/buildroot/build_mipsel/staging_dir/bin:$PATH
linux:/home/tom/adm5120/linux # make CROSS_COMPILE=mipsel-linux- 
...
2. Finally, make vmlinuz:
linux:/home/tom/adm5120/linux # make vmlinuz
...
You can now upload vmlinuz to your adm5120's sdram using the serial console and enjoy your working kernel + root filesystem! :)

Note: If you want to create a firmware image that can be stored in the adm5120's flash, you're not quite finished yet:

5.7 Creating a firmware image (optional)
1. Get this tool and compile it:
linux:/home/tom/adm5120/linux # wget http://www.student.tue.nl/Q/t.f.a.wilms/adm5120/files/mksyshdr.c
...
linux:/home/tom/adm5120/linux # gcc mksyshdr.c -o mksyshdr
if you like, you can save this file somewhere else of course

2. Create the firmware image:
linux:/home/tom/adm5120/linux # ./mksyshdr csys vmlinuz
linux:/home/tom/adm5120/linux # cat csys vmlinuz > firmware.img
linux:/home/tom/adm5120/linux #
Load firmware.img in to your adm5120's flash and have fun :)

To do

Probably a lot ;)

Comments, questions, suggestions etc are greatly welcomed at: tom AT nations DOT nl

Working firmware available for download

The firmware that I built during the writing of this howto is available here:
http://www.student.tue.nl/Q/t.f.a.wilms/adm5120/files/fw-20050809.img
The compressed kernel + root fs is also available:
http://www.student.tue.nl/Q/t.f.a.wilms/adm5120/files/fw/vmlinuz-20050809
This firmware has a 2.6.12-rc1 kernel and a basic busybox root fs.

Files available for download

Version of buildroot used in this tutorial:
buildroot-20050807-ext2rootfix.tar.bz2
Kernel configuration used in this tutorial:
kernelconfig-2.6.12-rc1
adm5120 patch for kernel 2.6.12-rc1:
linux-2.6.12-rc1-adm.diff
Kernel used in this tutorial: 2.6.12-rc1-mipscvs-20050403
linux-2.6.12-rc1-mipscvs-20050403.tar.bz2
Tool for generating csys header:
mksyshdr.c