build.shtml

<!--#include file="include/iplHeader.html"-->

<h1>Building a uClinux System for the iPod</h1>


<h2>Introduction</h2>

<p><b>Note:</b> These instructions are somewhat of out date, please check the forums for more current details.

<p>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.

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

<p>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.


<h2>Overview</h2>

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

<p>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.

<p>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.

<p>Next we will build the uClinux kernel for the iPod.

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

<p>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.

<p>For some useful links to some of the packages referenced here please see the <a href="download.shtml">download</a> page.

<h2>Requirements</h2>

<ol>
<li>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.

<li>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.

<li>No reservations about the possibility of ruining your iPod.  This would likely invalidate your warranty as well.  You have been warned!

<li>A toolchain to build the software.

<li>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.

<li>UMSDOS, FAT32 and firewire support in your kernel (or as modules).

</ol>



<h2>Preparing the build Environment</h2>

<p>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).

<p>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 <code>/usr/local/</code> so if that is okay on your system you can just untar it there.

<p>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 :)

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

<p>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.


<h2>Backing up your iPod firmware</h2>

<p>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 <a href="techdetails.shtml">here</a> 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.

<p>The hard drive in the iPod is partitioned into two partitions.  Normally these will be visible under Linux as <code>/dev/sda1</code> and <code>/dev/sda2</code>.  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 <a href="firewire.shtml">tinkering</a> to get IEEE1394 (firewire) working with you iPod).

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

<p><blockquote><code>dd if=/dev/sda1 of=iPod_fw_1_20</code></blockquote>

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

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

<p><blockquote><code>dd if=iPod_fw_1_20 of=/dev/sda1</code></blockquote>

<p>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.

<p>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.


<h2>Building the Kernel</h2>

<p>To build the kernel:

<ol>
<li>Unpack the sources
	<blockquote>
	<code>
	tar zxf linux-2.4.20.tar.gz<br>
	cd linux-2.4.20
	</code>
	</blockquote>

<li>Apply the uClinux patch
	<blockquote><code>
	gzip -d -c uClinux-2.4.20-uc0.diff.gz | patch -p1
	</code></blockquote>

<li>Apply the iPodLinux patch (read <a href="#cvs">below</a> for CVS details.)
	<blockquote><code>
	gzip -d -c ipodlinux-2.4.20-0.1.diff.gzip | patch -p0
	</code></blockquote>

<li>Configure the kernel
	<blockquote><code>
	cp arch/armnommu/def-configs/ipod .config<br>
	make oldconfig
	</code></blockquote>

<li>Compile the kernel
	<blockquote><code>
	make dep && make && make modules
	</code></blockquote>
</ol>

<h2><a name="cvs">CVS Information</h2>

<p>The CVS <a href="http://sourceforge.net/cvs/?group_id=73079">respository</a> 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.

<p>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.

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

<p>You can then continue on with steps 4 and 5.

<p>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.


<h2>Installing the Kernel</h2>

<p>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 <a href="kernel_pad.S">kernel_pad.S</a> file is simply an ARM exception table and some padding, I hope to find a cleaner solution than this hack.

<p>The steps in this process are as follows:

<ol>
<li>convert the kernel to a raw binary image
	<blockquote><code>
	arm-elf-as kernel_pad.S -o kernel_pad<br>
	arm-elf-objcopy -O binary kernel_pad kernel_pad.bin<br>
	arm-elf-objcopy -O binary linux linux_tmp.bin<br>
	cat kernel_pad.bin linux_tmp.bin &gt; linux.bin<br>
	rm linux_tmp.bin kernel_pad kernel_pad.bin
	</code></blockquote>

<li>patch in the raw binary image (<code>linux.bin</code>) into the OS partition data
	<blockquote><code>
	cp iPod_fw_1_20 iPod_fw_1_20.patched<br>
	patch_fw iPod_fw_1_20.patched linux.bin
	</code></blockquote>

<li>copy the OS partition data back to the iPod
	<blockquote><code>
	dd if=iPod_fw_1_20.patched of=/dev/sda1</code>
	</code></blockquote>
</ol>

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

<p>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").

<!--
Sorry at the moment you cant!

you can press the action key to soft reboot to diskmode in order to install some user tools.
-->


<h2>Preparing the root partition</h2>

<p>Please note there is a short <a href="partitioning.shtml">HOWTO</a> describing how you can setup a not UMSDOS root parition.

<p>The kernel will mount <code>/dev/sda2</code> 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.

<p>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.

<p>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 <code>/dev/sda2</code>) and unzip the root file system (<code>ipod_rootfs.zip</code>).  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.

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

<!--
 However in order for that to work you need to firstly build and install Busybox with the shell and echo applets.

<!--

<p>As root mount the iPod partition on your host system and prepare a directory for the Linux pseudo-root:

<p><code>
mount -t umsdos /dev/sda2 /mnt/ipod<br>
mkdir /mnt/ipod/linux<br>
touch -- /mnt/ipod/linux/--linux-.---<br>
umount /mnt/ipod<br>
</code>

<p>Remount the iPod partition (to recognise the UMDOS file just created) and create the the file system structure.  Note, you need to be root to create the device files with mknod.

<p><code>
mount -t umsdos /dev/sda2 /mnt/ipod<br>
mkdir /mnt/ipod/linux/bin<br>
mkdir /mnt/ipod/linux/dev<br>
mkdir /mnt/ipod/linux/etc<br>
mkdir /mnt/ipod/linux/etc/init.d<br>
mkdir /mnt/ipod/linux/sbin<br>
mkdir /mnt/ipod/linux/tmp<br>
mkdir /mnt/ipod/linux/usr<br>
mkdir /mnt/ipod/linux/usr/bin<br>
mknod /mnt/ipod/linux/dev/mem c 1 1<br>
mknod /mnt/ipod/linux/dev/kmem c 1 2<br>
mknod /mnt/ipod/linux/dev/null c 1 3<br>
mknod /mnt/ipod/linux/dev/zero c 1 5<br>
mknod /mnt/ipod/linux/dev/hda b 3 0<br>
mknod /mnt/ipod/linux/dev/hda1 b 3 1<br>
mknod /mnt/ipod/linux/dev/hda2 b 3 2<br>
mknod /mnt/ipod/linux/dev/tty0 c 4 0<br>
mknod /mnt/ipod/linux/dev/tty1 c 4 1<br>
mknod /mnt/ipod/linux/dev/ttyS0 c 4 64<br>
mknod /mnt/ipod/linux/dev/ttyS0 c 4 65<br>
mknod /mnt/ipod/linux/dev/tty c 5 0<br>
mknod /mnt/ipod/linux/dev/console c 5 1<br>
mknod /mnt/ipod/linux/dev/mixer c 14 0<br>
mknod /mnt/ipod/linux/dev/dsp c 14 3<br>
chmod 1777 /mnt/ipod/linux/tmp<br>
umount /mnt/ipod<br>
</code>

<p>With the filesystem in place you need some binaries to get things rolling.

-->

<h2>Building User Tools</h2>

<p>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.

<p>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.

<h3>uClinux Distribution</h3>

<p>The full source distribution can be downloaded from the <a href="http://www.uclinux.org/pub/uClinux/dist/">here</a>.  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 <a href="http://cvs.uclinux.org/">cvs server</a>, this also allows you to only download the parts you need and keep up to date with changes as they are released.

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

<p>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.

<p>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".

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

<!--

<h3>Building Busybox</h3>

<p><a href="http://www.busybox.net">Busybox</a> is a good place to start as it provides a number of useful binaries for your system.

<p>To build the stable version of Busybox you need to edit Config.h to select the applets you want to build and then modify the Makefile to use the cross compiler and right compile options.

<p>In Config.h you should only enable a few of the applets such as <code>BB_ECHO</code>, <code>BB_MSH</code>.  Also define <code>BB_FEATURE_SH_IS_MSH</code> and undefine the other <code>SH_IS_XXX</code> options.

<p>Makefile changes;

<p>Change <code>CFLAGS_EXTRA</code> to <code>CFLAGS_EXTRA = -elf2flt -D__uClinux__</code>

<p>Change <code>DOSTATIC = false</code> to <code>DOSTATIC = true</code>

<p>Change <code>CROSS</code> to <code>CROSS = arm-elf-</code>

<p>Change <code>LDFLAGS += -s -Wl,-warn-common</code> to <code>LDFLAGS += -s -Wl,-warn-common -elf2flt</code>

<p>You can then build the binary with <code>make</code>.  Once compiled you should modify the stack for the binary with the command;

<p><code>flthdr -s 50000</code>

-->


<!--
<h3>Building /sbin/init</h3>

<p>The current stable version of BusyBox doesn't work too well (on uClinux at least) as an init so included is a simple wrapper that simply starts a shell script.  That shell script will then be used to start any user applications.

<p><code>
#include &lt;stdio.h&gt;<br>
<br>
int main(int argc, char **argv)<br>
{<br>
&nbsp;&nbsp;&nbsp;&nbsp;printf("/sbin/init starting\n");<br>
<br>
&nbsp;&nbsp;&nbsp;&nbsp;execl("/bin/sh", "sh", "/etc/init.d/rcS", 0);<br>
}<br>
</code>

<p>You can find this as <code>dummy_init.c</code> along with the tools.  Also note the <code>Makefile</code> which shows how applications can be built for the iPod.


<h3>Creating /etc/init.d/rcS</h3>

<p>The simple init program above will start the shell script /etc/init.d/rcS (this strange name is compatible with the BusyBox init program).  This shell script can then execute your user applications.  The shell script can be anything you like.  Here is an example.

<p><code>
#!/bin/sh<br>
<br>
echo "iPod running uClinux!"<br>
</code>

<p>Note that since this script will exit the system will panic.  This is okay as the this allows the system to reboot into disk mode.
-->

<!--

<h2>Installing User Tools</h2>

<p>Installation of the user tools is simply a matter of copying the binaries onto the iPod.  In the first case since we are installing BusyBox we will also setup the symbolic links for the applets.

<p>
<blockquote><code>
mount -t umsdos /dev/sda2 /mnt/ipod<br>
cp init/init /mnt/ipod/sbin<br>
chmod 755 /mnt/ipod/sbin/init<br>
cp init/rcS /mnt/ipod/etc/init.d<br>
chmod 755 /mnt/ipod/etc/init.d/rcS<br>
cp busybox-0.60.5/busybox /mnt/ipod/bin<br>
chmod 755 /mnt/ipod/bin<br>
(cd /mnt/ipod/bin; ln -s busybox sh; ln -s busybox msh; ln -s busybox echo)<br>
umount /mnt/ipod<br>
</code></blockquote>

<p>At this point you should be able to reboot the iPod and it should come up with the Linux console output and finally display the message from your rcS script.  If not something went wrong.  Reboot your iPod to diskmode and take a look at the setup on the partition.  If everything looks okay head over to the <a href="support.shtml">support</a> section to try find some further pointers.

-->

<!--

<h2>Where to from here?</h2>

<p>Now that you have a basic system up an running you can experiment further with other applications.  The MP3 player MAD is a good place to start!  Just remember to use the cross compiler and right compile options (usually <code>CC=arm-elf-gcc CFLAGS=-elf2flt</code> does the trick).

-->


<!--#include file="include/iplFooter.html"-->