Building a uClinux System for the iPod

Introduction

Note: These instructions are somewhat of out date, please check the forums for more current details.

This short guide will take you through the procedure of building the uClinux system for your iPod. At present there is no binary distribution, this is intentional as currently it is quite experimental and not meant for general consumption. Hopefully the system will be stable enough shortly (and some usable applications will show up) so that a binary distribution makes sense.

This procedure is not simple, but hopefully is relatively easy to follow. Feedback for improving these instructions is welcome!

Please also note that these instructions do not use the newer bootloader that is available. If you would like to use the bootloader please check the bootloader documentation for further details.

Overview

Firstly, the requirements. These must be met (or work-arounds developed) in order to have any chance of success.

Next we will prepare the build environment. Since we need to compile programs that run on different hardware to our development machine (known as the host). The build environment is based on the GCC compiler toolchain.

Once the build environment is in place we will backup the firmware on the iPod. This backup should be stored in a safe place where a disk crash or other nastiness cannot corrupt it.

Next we will build the uClinux kernel for the iPod.

Following that we will install the kernel on the iPod. At this point you can see some results on your iPod.

However to run a program we still need to prepare the root file system, then create our system tools and then finally install them on the iPod.

For some useful links to some of the packages referenced here please see the download page.

Requirements

iPod (surprise!). iPod generation 1 (scroll wheel), generation 2 (touch wheel) are both well supported. Generation 3 (docking) iPods work although it is necessary to disable firewire support.
These instructions assume the iPod configured as "Windows", that is the filesystem is FAT32. HFS+ is supported in the CVS version of the kernel however there is no simple way to configure the user tools.
No reservations about the possibility of ruining your iPod. This would likely invalidate your warranty as well. You have been warned!
A toolchain to build the software.
Currently the build environment is Linux (Intel) based. If you have another system (e.g. a Mac) you are currently on your own. Please feel free to submit any success stories for inclusion here.
UMSDOS, FAT32 and firewire support in your kernel (or as modules).

Preparing the build Environment

The build environment requires a compiler that targets the ARM processor (the CPU on the iPod). Normally you can simply install a cross-compiling tool chain based on the GNU tools (that is binutils and gcc).

If you are running an Linux system on a x86 CPU then you can just download the toolchain as a binary. It likes to live in /usr/local/ so if that is okay on your system you can just untar it there.

On any other system you will need to build the tool chain from source. There are pointers on the Web to do this. Good luck :)

Please note, it seems that GCC version 2.95.3 should be used as later versions may have problems with the kernel build.

Once you binutils and gcc targeted for arm-elf you can proceed. Note, in order to build user tools you will also need a C runtime library (a "libc"). The above toolchain includes a binary for uClibc which is a small implementation of the C library.

Backing up your iPod firmware

The iPod "firmware" is a complex beast that actually consists of some code stored on flash ROM as well as code stored on the hard drive. A complete discussion of the boot process may be found here but for the moment suffice it to say that the hard drive contains the operating system and is started by a boot loader that lives in the flash ROM. We are only going to replace the OS portion and thus need to make a backup of that code.

The hard drive in the iPod is partitioned into two partitions. Normally these will be visible under Linux as /dev/sda1 and /dev/sda2. If you are currently using Linux tools to manage your music you would be familiar with the second partition as it is a FAT32 formatted partition and contains your music. (If this is the first time you have used your iPod with Linux you may need to do some tinkering to get IEEE1394 (firewire) working with you iPod).

Once you can successfully access your iPod from Linux (for example mount -t msdos /dev/sda2 /mnt/iPod) you can make a backup of your iPod OS partition.

dd if=/dev/sda1 of=iPod_fw_1_20

This will make a complete copy of the /dev/sda1 partition and save it to the file iPod_fw_1_20. You can modify the parameters to suite your local setup.

To restore this data to your iPod you would simply switch the if and of arguments. That is:

dd if=iPod_fw_1_20 of=/dev/sda1

Note, in order to do this you need to have your iPod in "diskmode". With the regular Apple firmware it would switch to this mode automatically when you insert the firwire cable, however with Linux this is not the case. In order to forcibly go to "diskmode" you need to reset the iPod by holding down the menu and play/pause for 10 seconds and then when the Apple icon appears hold down the fast forward and rewind buttons until the "OK to disconnect" message appears.

In this forced diskmode removing the firewire cable does not cause the iPod to reboot as it would normally. Again you need to reset by holding down the fast forward and rewind buttons. If you have reverted to the Apple firmware it should start shortly after the Apple icon appears.

Building the Kernel

To build the kernel:

Unpack the sources
tar zxf linux-2.4.20.tar.gz cd linux-2.4.20
Apply the uClinux patch
gzip -d -c uClinux-2.4.20-uc0.diff.gz | patch -p1
Apply the iPodLinux patch (read below for CVS details.)
gzip -d -c ipodlinux-2.4.20-0.1.diff.gzip | patch -p0
Configure the kernel
cp arch/armnommu/def-configs/ipod .config make oldconfig
Compile the kernel
make dep && make && make modules

CVS Information

The CVS respository maintained on SourceForge contains the latest versions of the iPod Linux patches (relative to the standard uClinux distributed patch). If you would prefer to work from CVS rather than the released patches you can simply checkout the changes from this site on top of a uClinux patched kernel.

For example, following the above steps for building the kernel, perform steps 1 and 2 as normal however at step 3 you will checkout the current code rather than use patch.

cd .. cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ipodlinux login cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/ipodlinux co linux cp -r linux/* linux-2.4.20

You can then continue on with steps 4 and 5.

Note, if you try and check out the code over an existing linux directory you will get CVS "in the way" errors. The copy method above avoids this problem.

Installing the Kernel

In this step the ELF format kernel is patched into the current firmware image. To do this we first need to prepare the kernel image by converting it to a binary format. The kernel_pad.S file is simply an ARM exception table and some padding, I hope to find a cleaner solution than this hack.

The steps in this process are as follows:

convert the kernel to a raw binary image
arm-elf-as kernel_pad.S -o kernel_pad arm-elf-objcopy -O binary kernel_pad kernel_pad.bin arm-elf-objcopy -O binary linux linux_tmp.bin cat kernel_pad.bin linux_tmp.bin > linux.bin rm linux_tmp.bin kernel_pad kernel_pad.bin
patch in the raw binary image (linux.bin) into the OS partition data
cp iPod_fw_1_20 iPod_fw_1_20.patched patch_fw iPod_fw_1_20.patched linux.bin
copy the OS partition data back to the iPod
dd if=iPod_fw_1_20.patched of=/dev/sda1

Note, its not necessary to copy the entire 30MB patched file back, it is just necessary to copy back the modified portion.

Once you have installed the kernel you can test it by resetting your iPod. You should see the kernel startup messages displayed on the LCD. Since you do not have any user tools installed the kernel will likely panic. This is expected, you will need to reset your iPod back into diskmode in order to install some user tools (see the details in "Backing up your iPod firmware").

Preparing the root partition

Please note there is a short HOWTO describing how you can setup a not UMSDOS root parition.

The kernel will mount /dev/sda2 as the root partition. Although in theory you could use any Linux supported filesystem on this partition it is recommended at this point to stick to the existing FAT32 partition. You should have compiled the kernel with support for UMSDOS which allows you to have a Linux root partition on a FAT partition.

To create the filesystem you have two choices, roll your own or just go with the default (essentialy empty) one provided. To roll your own you need UMSDOS support in your running kernel.

The pre-canned root file system contains the UMSDOS extensions that allow the directory structure to behave as a Unix-like file system. To install on your iPod simply connect your iPod, mount its "user" file system (usually /dev/sda2) and unzip the root file system (ipod_rootfs.zip). This will create a linux directory and then a unix looking directory structure under that. Note, at this point use the msdos file system not umsdos.

This file system has a dummy init that will start the script /etc/init.d/rcS which loads the ethernet module and starts inetd.

Building User Tools

User tools can be built and then installed on the iPod by simply mounting the filesystem using UMSDOS (as above). It is important to mount the filesystem as UMSDOS and not simply DOS in order to keep the file attributes consistent.

Its possible to just download the individual tools, compile them and then install using the firewire diskmode however a simpler approach is to just grab the uClinux distribution and build that. The download is quite large with a lot of extraneous (at least for the moment!) tools however it does provide a very qutomated build environment with known working versions of the various applications.

uClinux Distribution

The full source distribution can be downloaded from the here. This version actually includes both the 2.0.39 and 2.4.20 kernel sources so its not a small download. Alternatively you can use CVS to get the latest release from their cvs server, this also allows you to only download the parts you need and keep up to date with changes as they are released.

If you go the CVS route, just checkout the ucLinux-dist portion of the tree.

Once you have the build tree you will need to provide a link back to the kernel you have setup above (ln -s YOUR_KERNEL_TREE linux-2.4.x does the trick). If you downloaded the full source kit just remove the original and create the link.

Then you will need to add the build information for the iPod. You will need to download the "vendor" files for the uClinux distribution from the download area (currently only available from CVS). Just extract the files into the uClinux tree (a new directory vendors/Apple/iPod will be created) and you are set. Now you can just perform the standard uClinux build. Run "make menuconfig" or "make xconfig" and select the vendors/Apple/iPod, then "make dep && make".

The output of this fairly lengthy process will be a romfs directory containing all the binaries ready to run on your iPod.