Technical information about the Rockbox iPod port (for developers)
Driver status
The following table shows the current status of the various drivers required to be implemented before Rockbox is fully functional on the ipod.
Device |
Status |
Task scheduler (threading) |
Done |
Kernel (messaging and tick timer) |
Done |
Interrupt handling core code |
Done |
Panic handler |
0% |
LCD driver |
Done |
Backlight |
Done |
ATA driver |
Done |
ADC driver (SPI) |
0% |
Button driver |
Done |
USB handler |
Done USB insertion detected |
Power handling |
75% Deep sleep mode implemented, most targets get close to OF battery life |
RTC driver |
Done |
I2C driver |
Done |
I2S driver |
0% |
CPU frequency changing |
95% CPU boosting works, but further improvements in power savings may be possible |
Audio ADC/DAC driver |
75% Audio playback in SVN. |
iPodLinux
The iPods are based around the
PortalPlayer system-on-a-chip. Despite the fact that no official documentation is available publically for these devices, the
iPodLinux project has made extensive progress in writing open source Linux drivers for most of the hardware in the various different versions of the iPod. The source code released by this project is the main source of information about iPod hardware.
Basic hardware comparison
Model comparison
To date, Apple has released the following range of iPods. For more details on the differences between models, see the Generations page at the
iPodLinux Wiki.
iPod |
Hardware Revision(s) |
CPU |
LCD |
Keypad |
Backlight |
Piezo |
ATA |
1st Gen (scroll wheel) |
0x10000 0x10001 0x10002 |
PP5002 |
2 bit greyscale 160x128 |
Type 1 |
Type 1 |
Type 1 |
Type 1 |
2nd Gen (touch wheel) |
0x20000 0x20001 |
PP5002 |
2 bit greyscale 160x128 |
Type 1 |
Type 1 |
Type 1 |
Type 1 |
3rd Gen (docking) |
0x30000 0x30001 |
PP5002 |
2 bit greyscale 160x128 |
Type 1 |
Type 1 |
Type 1 |
Type 1 |
Mini 1G |
0x40000 |
PP5020 |
2 bit greyscale 138x110 |
Type 2 |
Type 2 |
Type 2 |
Type 2 |
Mini 2G |
0x70000 |
PP5022 |
2 bit greyscale 138x110 |
Type 3 |
Type 2 |
Type 2 |
Type 2 |
4th Gen |
0x50000 |
PP5020 |
2 bit greyscale 160x128 |
Type 3 |
Type 3 |
Type 2 |
Type 2 |
Color/Photo |
0x60000 0x60004 |
PP5020 |
16 bit colour 220x176 - type 0 |
Type 3 |
Type 3 |
Type 2 |
Type 2 |
Color (Aug 2005 onwards) |
0x60004 |
PP5020E |
16 bit colour 220x176 - type 1 |
Type 3 |
Type 3 |
Type 2 |
Type 2 |
Nano 1st gen |
0xC0000 |
PP5021C-TDF |
16 bit colour 176x132 |
Type 3 |
Type 4 |
???? |
Type 2 |
Video (5g) |
0xB0000 |
PP5021C-TDF |
16 bit colour 320x240 |
Type 3 |
Type 4 |
???? |
Type 2 |
Note that the hardware revision can be read at run-time from memory location 0x2084 (32-bit integer). "Type X" in the above table is used to indicate where code branches exists in the iPodLinux source.
Samsung-based iPods
The iPod video (5G/5.5G) was the last
PortalPlayer-based iPod. Starting with the iPod nano 2nd generation, Apple has switched over to using
SoC's designed by Samsung. These newer designs contain much more powerful CPUs and hardware.
iPod |
Hardware Revision(s) |
CPU |
LCD |
Keypad |
Backlight |
Piezo |
ATA |
Nano 2nd gen |
???? |
S5L8701 |
16 bit colour 176x132 |
???? |
???? |
???? |
???? |
Classic (6th Gen) |
???? |
S5L8702 |
16 bit colour 320x240 |
???? |
???? |
???? |
???? |
Classic (6.5 Gen) |
???? |
???? |
16 bit colour 320x240 |
???? |
???? |
???? |
???? |
Nano 3rd Gen |
???? |
S5L8702 |
16 bit colour 320x240 |
???? |
???? |
???? |
???? |
Nano 4th Gen |
???? |
???? |
16 bit colour 240x320 |
???? |
???? |
???? |
???? |
Potential Rockbox Targets (OLD!)
In order to eliminate wasted code and data in Rockbox builds for the iPod, it is necessary (as a minimum) to split targets by LCD type. It can be seen from the above table that splitting by LCD type will also eliminate the need for run-time detection of most other differences between the different iPods. This approach will give the following targets:
- Ipod 1st-3rd Gen - The PP5002 based iPods. Note that this CPU is significantly slower than the PP5020.
- Ipod Mini (1st and 2nd Gen) - PP5020 with small greyscale LCD. There are minor differences between the two mini versions which can be detected at runtime.
- Ipod 4th Gen - PP5020 with large greyscale LCD
- Ipod Photo/Color - PP5020 with colour LCD. There are two slightly different LCDs used in these iPods, and it is not possible for a user to tell the difference. Therefore, Rockbox should target these devices as one and perform run-time detection of the exact LCD type - known as "type 0" and "type 1" in IPL.
- Ipod Nano 1st gen- Very similar to the Ipod Photo/Color - the same LCD driver as "type 1" Color ipods is used in IPL.
- Ipod Video - The CPU (PP5021) is the same as the Nano 1st gen, so a lot of code will work the same (ATA driver, I2C driver, interrupts, memory mapping etc) but new drivers are needed for audio and the LCD. A slow (but usable) LCD driver has been developed by the iPodLinux project which has been incorporated into Rockbox.
Running Code on the Target
Overview
Apple has not made it difficult for users to run their own code on the iPods. The Apple firmware is in two parts - a bootloader (along with a USB/Firewire "disk mode" and a "diagnostics mode") are stored in flash, and the main firmware is stored in a small (typically 40MB) boot partition on the hard drive.
The flash bootloader simply loads the firmware from the boot partition into RAM (at the address specified in the firmware header in the boot partition) and jumps to the entry point (also specified in the header). The only security measure is a checksum stored in the header, and this is documented in the iPodLinux utility
make_fw.c. Using make_fw.c it is possible to replace the Apple firmware with another application, which will then be loaded and executed by the iPod's own bootloader.
Fortunately, this is not a risky operation - the iPods have a hardware reset which is invoked by a combination of key presses (on the 4G models, this involves holding down MENU and ACTION for 4 seconds). A user can then enter the flash disk mode by immediately pressing another key combination (ACTION and PLAY) and restore the original Apple software. So when our replacement firmware crashes, we can simply reboot, enter disk mode and try again.
iPodLinux Bootloader
The bootloader approach adopted by iPodLinux is to replace the Apple firmware in the boot partition with a new firmware image containing a small bootloader, a copy of the original Apple firmware, and a copy of the Linux kernel. The flash bootloader loads this large image into RAM, and executes the iPodLinux bootloader code. This secondary bootloader relocates itself out of the main RAM to the 96KB of IRAM and then (depending on a the presence of a keypress) copies either the Apple firmware or Linux kernel to its final destination address and jumps to its entry point.
Rockbox Bootloader
The iPodLinux approach has one major drawback - a user needs to run the make_fw utility and then write the resultant image file directly to a raw disk partition in order to update to new kernel versions.
The approach proposed for Rockbox will follow the model of the
iriver bootloader, with the Rockbox firmware itself being loaded from a file stored on the iPod's FAT32 partition. The bootloader itself is a stripped-down version of Rockbox and will contain LCD, button, ATA and FAT32 drivers.
The iTunes/iPod Databases
Summary
The Apple iPod firmware does not include a directory browser - music is only accessed via the "iTunes Database" stored on the hard disk.
All music and data are stored in the iPod_Control directory on a standard FAT32 (or HFS for Mac-formatted iPods) partition. On a desktop computer, the iTunes database is an XML file. The version on the iPod is binary. The binary iPod version is documented by the iPodLinux project at
http://ipodlinux.org/ITunesDB.
Audio files are stored in the /iPod_Control/Music directory as files of the form F01/NHQA.m4a. Files from the same album are not stored in the same directory. Therefore, Rockbox's normal file browser will not be helpful in browsing these files.
The .m4a metadata is retained in the audio files copied to the iPod.
Available Software:
Links
Copyright © by the contributing authors.