ipodpatcher

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.

ipodpatcher is Free Software and can be shared and modified according to the terms of the GNU GPL.

Download

The latest release of ipodpatcher (v5.0 with v4.0 bootloaders) is available here:

Operating System	Download link
Mac OS X (Universal Binary)	ipodpatcher.dmg
Windows	ipodpatcher.exe
Linux (32-bit x86)	ipodpatcher
Linux (64-bit AMD64)	ipodpatcher

Source code is available in the Rockbox SVN (see UsingSVN). To download the source code use the command:

svn co svn://svn.rockbox.org/rockbox/trunk/rbutil/ipodpatcher ipodpatcher

If you need a precompiled, standalone bootloader, look here.

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.

For the full Rockbox installation procedure, see the Rockbox Manual.

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.

A fuller description of the format of the ipod firmware partition can be found at http://ipodlinux.org/wiki/Firmware.

.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. The Nano 2G does not use this style of install; its normal install method resembles 3) below.

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 does not work on the Nano 2G, and you must use at least version 5.0 of ipodpatcher.

Advantages

• Rockbox boots faster (over 2 seconds faster than standard on an ipod video 80GB).
• Dual booting the Apple firmware works as usual (hold switch or Menu button).

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 remove the 2 second boot time improvement, but your new version of Rockbox will still run.
• Booting the Apple firmware is slightly slower than usual.

Instructions

1. 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.
2. Unzip your Rockbox build to .rockbox on the ipod as usual.
3. Place a copy of apple_os.ipod in the .rockbox directory (this enables dual booting).
4. Install your copy of Rockbox to the OSOS image with ipodpatcher -wf rockbox.ipod
5. Append the Rockbox bootloader to the OSOS image with ipodpatcher -a bootloader-youripodmodel.ipod (this must be a development build of the bootloader, not the one included in ipodpatcher).
6. Delete or rename rockbox.ipod in the .rockbox directory. The bootloader will always load Rockbox from the main partition if it's present.
7. Reboot the ipod. Dual booting should function as before, but Rockbox should 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).

3) OSOS contains only the Rockbox bootloader

The Nano 2G's default install method resembles this method.

Advantages

• Rockbox boots a little faster (over 1 second faster than standard on an ipod video 80GB).
• Dual booting the Apple firmware works as usual (hold switch or Menu button).
• Updating Rockbox requires no special steps.

Disadvantages

• Installation is manual and making a mistake can result in having to restore the ipod.
• Booting Rockbox is not as fast as with method 2.
• Booting the Apple firmware is slightly slower than usual.

Instructions

1. 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.
2. Unzip your Rockbox build to .rockbox on the ipod as usual.
3. Place a copy of apple_os.ipod in the .rockbox directory (this enables dual booting).
4. Install the Rockbox bootloader to the OSOS image with ipodpatcher -wf bootloader-youripodmodel.ipod
5. Reboot the ipod. Dual booting should function as before, but Rockbox should load faster.

Updating Rockbox simply requires unzipping the .rockbox directory onto the ipod as usual.

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

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

1. 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.
2. Unzip your Rockbox build to .rockbox on the ipod as usual.
3. Install your copy of Rockbox to the OSOS image with ipodpatcher -wf rockbox.ipod
4. 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).