Skip to content

Architecture overview

Chikuma is the iPod classic's retail firmware, taken apart and built again from the outside in. It is not a new operating system that happens to look like Apple's; it is Apple's, reproduced behaviour by behaviour, with the original kept alongside as the thing every answer is checked against.

That constraint shapes the whole codebase. Nothing here is designed. Where the original decides something - how a menu drills down, how a screen fades, how a track reaches the DAC - Chikuma reproduces that decision and proves it against the original running on the same emulated machine. Where the original does not decide something - what a source file is called, where shared code lives, how the port is laid out - the choice is Chikuma's, and it says so at the place it is made.

The shape of the system

The stack, from the metal up, is the same stack the device has, because structure follows the firmware, not our taste.

  • The boot chain. A reproduced mask boot ROM and a reproduced NOR bootloader hand off to the OS, all three in C, built from source and signed with Chikuma's own certificate chain. The same chain boots the original firmware too, which is the control that proves it. See the boot chain, in C.
  • The kernel. The firmware's own RTXC design: tasks, priorities, preemption, mutexes with priority inheritance, timers, slots and events, a heap with boundary tags, and a service dispatch. The task table carries the real names, ids and priorities. See Kernel.
  • Storage. An ATA driver, a partition layer, FAT16 and HFS+. The filesystem never calls the disk directly: it posts to a work queue and blocks, because that is how the device's own disk tasks are arranged. See Storage.
  • Display and UI. A compositor named Granite drives the panel and a hardware scaler; on top of it the view classes render screens that build themselves from the resource archive rather than being drawn in code. See Display and UI and the resource archive.
  • Media. Audio and video both go through hardware decoders on this device, so there is no Apple codec in the image to recover - only the contract with the hardware to reproduce. See Audio and video.
  • Devices. Every piece of hardware the firmware touches - the wheel, the PMU, the panel, the disk, the crypto blocks - has a model in the emulated machine, and a driver in Chikuma that talks to it. See the device models.
  • Accessories. The dock, the Apple accessory protocol, and USB. See Accessories and iAP.

How a claim earns its place

Three words run through this codebase and this documentation:

  • MEASURED - read from the image or observed on a live trace of the original.
  • INFERRED - reasoned on top of a measurement.
  • OURS - a stand-in, which declares itself in the file at the place it stands in, and names the behaviour that would replace it.

A page here that describes reproduced behaviour is describing something with a test behind it that fails if the behaviour changes. Where a subsystem is thin, the page says so rather than padding. The full, live account of what works and what does not is Status; this section explains how the pieces fit, at the level the object itself is arranged.

Not a byte-for-byte copy

Fidelity here is to behaviour, not to Apple's compiler output. Chikuma has to stay recompilable and changeable - that is the entire point of rebuilding it rather than patching the original - so it is not a byte-match of the shipped binary. It is the same behaviour, checked by subtraction against the original on the same machine. Some screens come out pixel-identical; where they do not, the differing pixel count is the number that gets quoted.

Libraries Apple did not write, Chikuma does not re-type

The image embeds several well-known open-source libraries. Chikuma uses them from upstream at the version the image advertises rather than re-deriving them:

  • FreeType for text rasterisation,
  • SQLite for the Genius queries,
  • zlib for inflate,
  • Vincent (a software OpenGL ES 1.1 implementation) for Cover Flow and the tilted album art.

Only the parts Apple grew onto these libraries are recovered, because those could have been different. The test is simple: could this line have been different if Apple had chosen differently? If yes, it is recovered. If it is an implementation of a public standard someone already wrote, it is taken from them. See the media page for how this plays out with the OpenGL ES stack.