The reports¶

The recovered detail lives in reports/, one file per subsystem. They are working notes rather than documentation: retractions, corrections and dead ends stay in, because knowing what was already tried is most of their value.

Two conventions:

• Read a whole file before appending to it. The head usually answers what the tail is about to go and dig up again.
• Superseded sections are marked, not deleted. A conclusion that later measurement reversed is more useful than a tidy file.

Querying the archive instead of guessing at it¶

Much of what a report would otherwise have to assert can be asked, and chikuma/build/archwalk is the whole query surface. It is built from the same readers the device runs, so what it prints is what the firmware would read:

./build/archwalk sections                    # the 27 fourcc sections
./build/archwalk screen 0x0DAD0CE6           # a screen's slots, geometry and records
./build/archwalk item 0x48 | str <id> | name <text> | lists | find <id>
./build/archwalk colours | ids <FOURCC> | refs <id> | bmap <id> | sorc <n>
ARCHIVE_BLOB=../firmware/extracted/osos-dec.dfu ./build/archwalk ...   # the whole image

It replaced a Python tool that reimplemented part of the parsing, so there is now one reader: the device's.

Where to start¶

By subsystem¶

Filesystem and data fs_layer.md, hfs_driver_worklist.md, itunesdb_reader.md, itunesdb_signature.md, artwork_reader.md, media_model.md, genius_re_report.md, genius_constraints.md, photos_re.md

UI: the largest group, and the one to read before touching a screen ui_view_base.md, ui_view_records.md, ui_menu_wiring.md, ui_split_view.md, ui_media_lists.md, ui_text_views.md, ui_image_views.md, ui_progress_view.md, ui_battery_statusbar.md, ui_battery_preview.md, ui_preview_panes.md, ui_pane_ownership.md, ui_property_context.md, ui_transitions.md, ui_transform.md, ui_archive_survey.md, ui_nowplaying_content.md, ui_settings_actions.md, wheel_scroll_rows.md

Audio and video sm1_spec.md (the specification), sm1_audio_engine.md (the investigation log), audio_hardware.md, audio_path.md, playback_path.md, m4a_decoder.md, video_path.md, video_player_re.md

Platform memory_map_rework.md, mmu_map.md, power_idle_state_machine.md, i2c_async_design.md, input_hold_gate.md, piezo_clicker.md, accessories.md, accessory_board.md, usb_disk_mode.md, retailos_panel_path.md, emu_display_and_time.md

Click-wheel games (see the games section) games_sandbox.md, eapp_format.md, eapp_api.md, eapp_slot_table.txt

Graphics stack gl_vincent.md, gl_binary_shaders.md, gl_port_plan.md, third_party_versions.md

Boot, security and protected content boot_chain.md, nor_contents.md (the ONB, module by module), onb_port_log.md (the C port's log), bootrom_crypto.md, bootrom_wtf_symbols.md, bootloader_target.md, onb_boot_screens.md, aupd_updater.md, ipod_debug_access.md, and the FairPlay series

Unsorted unknown_blocks.md: regions not yet attributed to anything, kept explicitly rather than ignored

Third-party components¶

third_party_versions.md records which parts of the image are somebody else's published work and at what version, because that decides what gets recovered and what gets vendored.

The OpenGL ES implementation is the worked example. The strings identify it as Vincent, and the advertised extension list is the stock fixed-point set, except for GL_APPLE_binary_shader, with its glRegisterBinaryShaderAPPLE and glUnregisterBinaryShaderAPPLE. So Vincent comes from upstream at the advertised version, and the Apple extension is recovered, because Apple wrote it and it could have been different.

Vendoring a library does not vendor the parts Apple grew onto it, and a file that takes one has to say which half it is.

Debug facilities on a real device¶

ipod_debug_access.md decodes about 37 firmware options, gated behind two empty files in iPod_Control/Device/: a master gate and a per-feature flag. With logging enabled the firmware writes an event log and a usage report to the device. Others include memory, FPS and voltage displays. This is Apple's own instrumentation, present in shipped firmware, and it needs no modification to switch on.