Skip to content

Running it on the device

Read this first

There is no release build of Chikuma and no supported install path. What follows describes developer plumbing that exists in the repository, so that nobody has to reconstruct it, and so that the risky parts are labelled as risky.

The safe path loads Chikuma into RAM. The unsafe path writes flash. They are not the same operation and the difference is whether a mistake costs you a power cycle or a device that no longer boots. These iPods are not manufactured any more.

The safe path: DFU into RAM

The iPod's bootROM has a DFU mode. wInd3x, from the freemyipod project, exploits it to accept an unsigned image.

The important property is that the exploit patches the bootROM in RAM. It is temporary. It does not survive a power cycle, and a power cycle restores normal boot -- which is exactly why this is the path to develop on: an image that hangs, faults, or paints garbage costs you a reset, not the device.

Roughly:

  1. Put the iPod in DFU mode -- connect USB, hold Menu and Enter until the Apple logo appears and then the screen goes blank. It enumerates as a USB DFU device.
  2. Run the wInd3x haxed-DFU step, which is what makes the bootROM accept an unsigned payload.
  3. Upload retailos_re/payload.elf.

Nothing in that sequence writes to the device.

The unsafe path: writing flash

The repository also carries a two-stage installer (installer/, a small ARM payload with its own SPI, ATA and FAT16 code) and a bundle format, aimed at a device that can be updated without a host holding its hand. That work writes SPI NOR.

It is not a product, it has not been through the project's own gates as one, and it is not recommended to anyone. It is documented in the repository (install.md, BUNDLES.md, DFU_REBOOT.md) as a design under development, and several of the pieces there are plans with proposed code rather than measured, shipped behaviour. Treat them accordingly.

Why a DFU reboot is wanted at all

Because the exploit does not stick, every RAM load today needs the manual DFU entry above. The firmware already reboots into named modes -- the image carries a table of reboot reason strings, with diskmode for USB mass storage and softupdt for software update among them -- so the idea under investigation is to extend that mechanism with a mode that comes back up in DFU. That would make each subsequent load a single command without a permanent modification anywhere.

Status: a plan with the relevant firmware functions located, not a shipped feature.

What Chikuma will not ask of your device

  • It does not need Apple's servers.
  • It does not need your iPod's disk reformatted; it reads the volume layout the device already has.
  • It does not touch content that is not already on the device you own.

And a standing rule from this project's own history

A test library was once written over a real iPod because a script looked for a disk image with a glob that matched the device first. Twenty megabytes of database, a hundred megabytes of Genius data and every thumbnail, gone, and only a full re-sync brought it back.

So: tools here address volumes by the node the mount returned, never by name, and the image mounts at a path of its own that refuses anything else. If you write tooling around this project, do the same.