Linux on iPod at SourceForge.
Building a uClinux System for the iPod
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.
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.
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
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
Once you can successfully access your iPod from Linux (for example
This will make a complete copy of the
To restore this data to your iPod you would simply switch the
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:
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.
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:
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
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
This file system has a dummy init that will start the script
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.
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.