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 (v1.0 with v1.1 bootloaders) is available here:

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

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 IpodInstallationBeta page or 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/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 firmare (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.