Kernel Building
From wikiPodLinux
This short guide will take you through the procedure of building the uClinux kernel for an iPod. Most ordinary users will be fine with the prebuilt binaries, but this how-to exists for budding kernel developers.
| Table of contents |
Overview
To compile the kernel for the iPod you're going to need to install an ARM cross-compiler toolchain. The stock kernel needs to be patched with uClinux patches and a unique patchset for the iPod, built and then deployed. This document also covers the rudimentary setup of a userland root filesystem.
Note: Also have a look at the Experimental Kernel page where you can find an improved version of the kernel to build.
If you want to understand how the Kernel works, see Kernel Internals.
Prerequisites
- Connectivity to your iPod
- This guide assumes you can access your iPod as a disk from your host machine. On Mac OS X and Windows this usually isn't a problem, but check other guides for getting it working under Linux.
- No reservations about ruining your iPod.
- We've not heard of anyone irrevocably damaging their iPod through software hacks, but that doesn't mean it can't happen. We're not responsible for any damage to your iPod. Always have backups of everything that's on there in case you need to run the Apple restore utility.
- A UNIX based system to build on.
- This includes Linux and Mac OS X - the instructions may work but are untested on Cygwin.
Required Source Code
To avoid conflicts, create a new directory first and then download the following parts all into that directory:
- linux-2.4.24 (http://kernel.org/pub/linux/kernel/v2.4/linux-2.4.24.tar.gz) - vanilla kernel
- uClinux-2.4.24-uc0.diff (http://www.uclinux.org/pub/uClinux/uClinux-2.4.x/uClinux-2.4.24-uc0.diff.gz) - uClinux patch
- ipodloader (https://sourceforge.net/project/showfiles.php?group_id=73079&package_id=101451) - creates firmware images for loading of linux (think of it as lilo/grub for your ipod)
- uclinux-2.4.24-ipod2.patch (http://prdownloads.sourceforge.net/ipodlinux/uclinux-2.4.24-ipod2.patch.gz?download) - uClinux iPod specific patch (not required if using CVS, see below)
The CVS respository 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 only the missing and changed files:
$ cvs -d:pserver:anonymous@ipodlinux.cvs.sourceforge.net:/cvsroot/ipodlinux login $ cvs -z3 -d:pserver:anonymous@ipodlinux.cvs.sourceforge.net:/cvsroot/ipodlinux co linux
Note, if you try and check out the code over an existing linux directory you will get CVS "in the way" errors. See the below instructions on how to apply them to a kernel tree.
Installing the Toolchain
For most iPodLinux applications, you compile using the arm-uclinux-elf 3.4.3 toolchain. However, the kernel needs to be built using the older arm-elf 2.95 toolchain. You can install both toolchains at once without major problems.
(An alternative is to update the kernel to compile with the 3.4.3 toolchain - see the Experimental Kernel page for a solution to this)
See the Toolchain page for information on how to install the 2.95 toolchain, then continue to Building the Kernel.
- Note: If you have installed both the 2.95 and the 3.4 toolchains, you may need to change the Makefile so that it uses the correct toolchain. To do that, modify the Makefile so that the line
- CROSS_COMPILE = arm-elf-
- becomes
- CROSS_COMPILE = /usr/local/arm-elf/bin/arm-elf-
- This assumes that you had copied all your arm-elf-files from /usr/local/bin to /usr/local/arm-elf/bin/ after you have installed the 2.95 toolchain. Otherwise, re-install the 2.95 toolchain if you get errors such as a missing objcopy tool when building the kernel.
Building the Kernel
It's handy to have all the files in one directory.
1. Unpack Linux source
$ tar zxf linux-2.4.24.tar.gz $ cd linux-2.4.24
2. Apply the uClinux patch
$ zcat uClinux-2.4.24-uc0.diff.gz | patch -p1
(If you get the error zcat: uClinux-2.4.24-uc0.diff.gz.Z: No such file or directory, then rename the file so that it ends in .gz.Z to make zcat happy. Note: This happens on OSX with zcat 1.3.5 but not with zcat 1.2.4)
3. IF
using the released uClinux iPod patch, apply it
$ zcat uclinux-2.4.24-ipod2.patch.gz | patch -p0
ELSE IF using checked out CVS uClinux iPod files, copy them over the kernel tree
$ cd .. $ ls linux linux-2.4.24.tar.gz linux-2.4.24 uClinux-2.4.24-uc0.diff.gz $ cp -r linux/* linux-2.4.24/ $ cd linux-2.4.24
4. Configure the kernel
$ cp arch/armnommu/def-configs/ipod .config $ make oldconfig
Answer 'y' if anything pops up, it's most likely a new addition in CVS.
4b. (Mac OSX only)
Mac OS X's expr does not work correctly (you will early get expr: syntax error), so either update expr or fix the root Makefile (linux-2.4.24/Makefile) by replacing:
@expr length "$(KERNELRELEASE)" \<= $(uts_len) > /dev/null || \
with
@expr `expr "$(KERNELRELEASE)" : ".*"` \<= $(uts_len) > /dev/null || \
If you then still get a warning about KERNELRELEASE exceeding 64 characters, simply remove the above and its following line altogether (it's only a safeguard which is not really necessary here).
5. Compile the kernel
First, make sure you have the correct toolchain active by typing
$ arm-elf-gcc --version
It should print 2.95.3 and not 3.4.3 or similar
Then you can build it:
$ make dep && make boot && make modules
Caution: The kernel image file you need is NOT the "linux" file in the main folder! It is: arch/armnommu/boot/Image
If the compile fails, you can try this command:
$ make clean
Then re-run the first command.
Known issues & troubleshooting
- When using make xconfig and quitting with "save and exit", even if no explicit changes were made, make does not work successfully any more:
- include/linux/autoconf.h will cause warnings about duplicate definitions (these are harmless and can be ignored, though)
- build fails at link time because of some missing symbols in function ret_from_exception
- moral of this story: do not use make xconfig. Instead, use make menuconfig.
- If you have somehow messed up your configuration, try these commands for a fresh start:
- cp arch/armnommu/def-configs/ipod .config && make oldconfig && make dep
Installing the Kernel
- Note: This section is a bit outdated. It explains how the kernel can be inserted into the firmware partition that also holds Apple's iPod software and the bootloader for iPodLinux. The modern way to install a kernel is to use Loader 2, which allows you to store the kernel on your music or linux partition by simply copying it to your mounted iPod as a file called "linux.bin" (see here).
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. The hard disk contains the operating system and is started by a boot loader that lives in the flash ROM. iPL doesn't touch the flash, it alters the firmware partition on the disk. It is therefore a good idea to back this up. To do this, you need to know how your iPod is laid out.
Before continuing, make sure your iPod is in disk mode (flashing 'Do not disconnect' sign) and connected to your host machine.
Below is a diagram listing the default locations of the various partitions. If you have other disks attached, it may not be sda or disk1, but rather sdb or disk2. 'dmesg' should point you to the right one.
Linux : Mac OS X .----------------------, : | Partition Map | <-- /dev/sda : /dev/disk1s1 |----------------------| : | Firmware Partition | <-- /dev/sda1 : /dev/disk1s2 |______________________| : | | : | | : | Data Partition | <-- /dev/sda2 : /dev/disk1s3 | (FAT or HFS+) | : | | : '----------------------' :
NOTE: The guide will assume from now on that the iPod is at /dev/sda, adjust this for your system from this point onwards.
1. Go into your ipodloader directory:
$ cd ~/ipodlinux/ipodloader
2. Backup your firmware partition:
$ dd if=/dev/sda1 of=ipod_os_partition_backup
This should take around a minute. If later you wish to restore your iPod, just reverse the command like this:
$ dd if=ipod_os_partition_backup of=/dev/sda1
3. Extract the Apple Firmware from the backup image:
$ ./make_fw -o apple_os.bin -e 0 ipod_os_partition_backup
(the make_fw tool is in the ipodloader package)
4. Create a new image that boots Linux and the Apple Firmware:
You can either have Linux as the default OS:
$ ./make_fw -o my_sw.bin -l linux-2.4.24/arch/armnommu/boot/Image -i apple_os.bin loader.bin (for 1g thru 3g) $ ./make_fw -3 -o my_sw.bin -l linux-2.4.24/arch/armnommu/boot/Image -i apple_os.bin loader.bin (for 4g, mini, and photo)
Or the Apple OS as the default OS:
$ ./make_fw -o my_sw.bin -i apple_os.bin -l linux-2.4.24/arch/armnommu/boot/Image loader.bin (for 1g thru 3g) $ ./make_fw -3 -o my_sw.bin -i apple_os.bin -l linux-2.4.24/arch/armnommu/boot/Image loader.bin (for 4g, mini, and photo)
It doesn't matter which one you choose, as you can boot into the other OS(whatever that may be) by holding down rewind during a reset.
If you are using a 4g or 5g ipod refer to the install notes for that revision ( 5g notes )
5. Copy the new image (which is about 4-5 MB in size) back to your iPod.
$ dd if=my_sw.bin of=/dev/sda1
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 most likely panic. This is expected, you will need to reset your iPod back into disk mode in order to install a root filesystem.
Preparing a root Filesystem
This is covered under the different installation pages. If you have a FAT formatted iPod, you'll need to read up on partitioning and then userland installation. If you have a HFS+ formatted iPod, you needn't worry about the partitioning - just prepare the userland
