Introduction

ipodpatcher is a cross-platform (tested on Mac OS X, Linux, BSD and Windows) command-line tool for modifying ipod firmware partitions. It was written to enable the installation of the Rockbox bootloader but also has uses as a general-purpose ipod tool, with the ability to backup and restore the firmware partition and install the IpodLinux bootloader.

It supports modifying the firmware on both Winpods (i.e. FAT32 format with a DOS partition table) and Macpods (i.e. HFS+ format with an Apple Partition Map). Although Rockbox itself will only work on FAT32 formatted ipods.

To compile ipodpatcher with embedded bootloaders, read and follow the instructions at the top of the Makefile.

Rockbox bootloader installation

Running ipodpatcher without any arguments will start it in an interactive Rockbox installation mode. This allows users to launch it directly from a GUI file manager. ipodpatcher will search for an attached ipod, and if exactly one ipod is found, will prompt the user to install the bootloader from the set embedded in the ipodpatcher executable.

Overview of the ipod firmware partition

The main ipod firmware (excluding the Apple bootloader / emergency disk mode / diagnostics mode code which is in flash ROM) is stored in hidden partition on the ipod's disk. ipodpatcher directly modifies the content of this firmware partition to enable users to attach extra code (i.e. a bootloader) to the existing Apple firmware, or to completely replace it with a new firmware such as Rockbox or the IpodLinux kernel.

The firmware partition is organised as a simple directory containing a number of individual images. An ipod will typically contain up to four such images:

OSOS - the main firmware image.

RSRC - a resource image. Only present on the ipod video, where it contains the firmware for the Broadcom video processor and on the ipod Nano, where it contains datafiles for use with the Nike accessory.

AUPD - encrypted version of the ipod's flash ROM. An original Apple firmware image (the ones installed by itunes when you upgrade/restore an ipod) contains a flag to indicate that the contents need to be written to the flash. Once the contents are written (which happens the first time you boot after installing such an image), the flag is cleared.

HIBE - an hibernation image. Only present on the ipod video and Nano, which hibernate after a period of inactivity and store the contents of the ipod's RAM in this image.

Each firmware image has a header containing (amongst others) the following fields

Load Address - the RAM address the image should be loaded to

Length - the size of the image

Checksum - a simple checksum of the image

Entry Point - the offset of the entry point (i..e the first instruction executed) in the image. This is zero for all Apple firmwares to date.

ipodpatcher allows the addition of a bootloader to the main OSOS image. This works by appending the bootloader binary to the end of the OSOS image (moving the other images further down the disk to make space), adjusting the length/checksum fields and changing the Entry Point from zero to the entry point of the bootloader.

.ipod files

The ".ipod" format is used by both ipodpatcher and Rockbox for firmware and bootloader binaries.

It consists of an 8-byte header (a 32-bit checksum and a 4 character ipod model identifier) followed by the firmware or bootloader.

Advanced usage

General syntax: ipodpatcher [device] action [filename]

The [device] parameter is optional. If it is not provided, then ipodpatcher will scan your computer for an ipod, and if exactly one is found, will use that device.

The following actions are possible:

--add-bootloader (-a) filename.ipod

Add (or replace, if a bootloader is already installed) a bootloader to the main firmware (OSOS) image. The bootloader must be in .ipod format with a model name in the header which matches the ipod you are trying to install it onto.

--add-bootloader-bin (-ab) filename.bin

Add (or replace, if a bootloader is already installed) a bootloader to the main firmware (OSOS) image. The bootloader must be a raw binary file with no header.

--delete-bootloader

Remove a bootloader from the main firmware (OSOS) image.

--read-partition (-r) filename.img

Backup the firmware partition to a file.

--write-partition (-w) filename.img

Restore a backup of the firmware partition. This can also be used to install a Firmware-X.Y.X firmware upgrade from Apple.

--read-firmware (-rf) filename.ipod

Read the main firmware image (excluding any bootloader) and store it in the filename.ipod file.

Rockbox users can use this command to extract the main Apple firmware to a file. When instructed to load the Apple firmware (via the hold switch or MENU button), the Rockbox bootloader looks for such a file (with the name apple_os.ipod) in the root of your FAT32 partition, and will load that firmware in preference to any firmware in the OSOS image.

--write-firmware (-wf) filename.ipod

This command can be used to completely replace the Apple firmware in the OSOS image with either the Rockbox bootloader or the main rockbox.ipod file.

--write-firmware-bin (-wfb) filename.bin

Replace the Apple firmware with a raw binary firmware file.

--list

List the contents of the firmware partition, including whether a bootloader is currently installed.

Advanced Rockbox install methods with ipodpatcher

Note: The Nano 2G requires an extra step, you must encrypt the rockbox.ipod file with crypt_firmware. Open the rockbox.ipod with crypt_firmware on your Nano 2G and a rockbox.ipodx file will be created, use this file in place of rockbox.ipod file in the install methods below.

There are several different ways that Rockbox can be installed on an ipod, which differ in what data is placed in the OSOS image: there are advantages and disadvantages to each configuration. Advanced users may wish to install manually using one of these configurations rather than using rbutil for automatic installation. Please be sure to back up the contents of your ipod before attempting this: while it is not possible to permanently damage the ipod in this way, restoring the ipod using iTunes after a failed firmware installation will require you to format it.

If you have used one of these advanced installation methods, or are attempting to use one and encounter problems, please be sure to specify exactly which method you are using in any request for help - but note that by using one of these methods you are accepting that you are assumed to know what you are doing, and it is not anyone else's fault if something has gone wrong.

1) OSOS contains Apple firmware and the Rockbox bootloader

This is the normal way to install Rockbox: rbutil does this for you, and ipodpatcher will do this by default if you run it with no arguments.

Advantages

Standard configuration, well tested, officially supported, rbutil can do it automatically.

You can dual boot the Apple firmware with the hold switch or by holding down Menu.

Disadvantages

Slowest way to boot Rockbox.

2) OSOS contains Rockbox and the Rockbox bootloader

This method is only possible if you build the bootloader yourself from svn. The bootloader included in ipodpatcher (and in rbutil) will not work.

4) OSOS contains only Rockbox

This method is the fastest way of running Rockbox, but does not allow dual booting.

Advantages

Rockbox boots faster than all the other methods (about 3 seconds faster than standard on an ipod video 80GB).

Stable builds are supported.

Disadvantages

Installation is manual and making a mistake can result in having to restore the ipod.

Updating Rockbox requires that you re-run ipodpatcher - forgetting to do this will result in the old version of Rockbox running, which may cause compatibility problems with the files in .rockbox from the newer version.

Dual booting is not possible: you will be unable to run the Apple firmware (though emergency disk mode still works).

Instructions

Back up the Apple firmware! Run ipodpatcher -rf apple_os.ipod and save the file apple_os.ipod somewhere safe. You can restore this later with ipodpatcher -wf apple_os.ipod if something goes wrong.

Unzip your Rockbox build to .rockbox on the ipod as usual.

Install your copy of Rockbox to the OSOS image with ipodpatcher -wf rockbox.ipod

Reboot the ipod. Dual booting will not function, but Rockbox will load faster.

To update Rockbox, follow the same instructions except for step 1 (as once you've already installed Rockbox to OSOS, that command would back up Rockbox, not the Apple firmware).