Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions devices/j96/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# iPad mini 4 (Wi-Fi), J96

Hardware identity, boot assets and the firmware recipe are in
[`device.toml`](device.toml). This file tracks what still needs testing,
open work, and contributed code that is not in the tree yet.

## Needs testing

**GPU (A8, PowerVR GX6450).** The board has the iPod touch 6's A8 GPU, and
its device tree enables it (`kernel/patches/devices/t7000/0012`). The
driver has only run on the iPod touch 6 (N102) so far. Test with
[`examples/ipod-gpu-drm`](../../examples/ipod-gpu-drm/README.md)
(`--device j96`) and report the output of `a8-gpu-drm-test probe` with
its kernel lines, and the ladder's `RESULT` lines.

## Unmerged code

None.
18 changes: 18 additions & 0 deletions devices/j97/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# iPad mini 4 (Cellular), J97

Hardware identity, boot assets and the firmware recipe are in
[`device.toml`](device.toml). This file tracks what still needs testing,
open work, and contributed code that is not in the tree yet.

## Needs testing

**GPU (A8, PowerVR GX6450).** The board has the iPod touch 6's A8 GPU, and
its device tree enables it (`kernel/patches/devices/t7000/0012`). The
driver has only run on the iPod touch 6 (N102) so far. Test with
[`examples/ipod-gpu-drm`](../../examples/ipod-gpu-drm/README.md)
(`--device j97`) and report the output of `a8-gpu-drm-test probe` with
its kernel lines, and the ladder's `RESULT` lines.

## Unmerged code

None.
38 changes: 38 additions & 0 deletions devices/n102/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# iPod touch 6, N102

Hardware identity, boot assets and the firmware recipe are in
[`device.toml`](device.toml). This file tracks what still needs testing,
open work, and contributed code that is not in the tree yet.

## Needs testing

**GPU (A8, PowerVR GX6450).** powervr's A8 variant
(`kernel/patches/drivers/gpu/0063`–`0073`, `devices/t7000/0011`) probes,
boots the GPU firmware and runs compute and render jobs on this board:
Vulkan 1.2 through Mesa's powervr driver and OpenGL ES 3.1 through Zink,
no faults over a 514k-job soak. Experimental: dEQP has not run, so the
chip has no `[gpu]` entry yet. Test with
[`examples/ipod-gpu-drm`](../../examples/ipod-gpu-drm/README.md).

## Internal storage

The flash sits behind ANS1, as on the iPad Air 2, with iOS 12.4's ANS
firmware (RTKit 10.2). `asp` shows the user area as `asp0n1` and the nine
auxiliary namespaces (LLB, firmware, NVRAM, SysCfg, ...) read-only. The
write unlock opens the whole controller, so the driver refuses every
command it does not need: only the user area is written.

To keep iOS, shrink its APFS container first (resize-apfs) and install
Orchard into the free space of `asp0n1`. A DFU restore brings iOS back; it
keeps SysCfg, which Linux never writes.

## Open work

- GPU: per-job firmware overhead, parameter-manager pool growth inside a
scene, and submitting a fragment job behind its geometry job
(`a8_joint`) by default.
- Touch, Wi-Fi and the battery gauge are not described yet.

## Unmerged code

None.
43 changes: 43 additions & 0 deletions devices/n102/boot.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
{
"schema": 1,
"device": "iPod7,1",
"firmware": [
{
"ipsw": {
"version": "12.5.8",
"build": "16H88",
"url": "https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-28554/C3D5CA8F-8B6F-4B05-9456-C5E632723337/iPodtouch_12.5.8_16H88_Restore.ipsw",
"bytes": 2821634289,
"sha256": "53a645c03332cd132f52612ffdf2aba3e6908ca937ab7f6c7b81aa8e15a14ec6"
},
"selected_by": "firmware-recipe",
"inputs": {
"BuildManifest.plist": {
"ipsw": {
"zip": "BuildManifest.plist"
},
"sha256": "97fe52925b0fbc3c2062019f831a18db7d6aeba60742df4be74106b3ea33d0e3"
},
"iBSS": {
"ipsw": {
"zip": "Firmware/dfu/iBSS.n102.RELEASE.im4p"
},
"sha256": "874d5fc6384ffee72e18b89020f1396702735c879d39014f39314c7ce2b84aec"
},
"iBEC": {
"ipsw": {
"zip": "Firmware/dfu/iBEC.n102.RELEASE.im4p"
},
"sha256": "5715e383b1e3eced6202eb47d515b13f1b10c41348239c6a800019111493a07c"
},
"DeviceTree": {
"ipsw": {
"zip": "Firmware/all_flash/DeviceTree.n102ap.im4p"
},
"sha256": "f59b40ce4fa554f4bb24415201c61dd2e8a6767558ca6404a4afa74dd2ec2d35"
}
}
}
],
"methods": {}
}
59 changes: 59 additions & 0 deletions devices/n102/device.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# iPod touch 6 (N102): identity from public sources (tools/catalog/generate's read_firmware);
# A8/T7000 like the iPhone 6. Installs to its internal storage next to iOS; notes in README.md.
schema = 1
kind = "hardware.device"

[device]
profile = "n102"
name = "iPod touch 6"
apple_products = ["iPod7,1"]
dt_compatible = ["apple,n102"]

[match.dfu]
chip = 0x7000
board = 0x10

[boot]
methods = ["checkm8-pongo"] # checkra1n then PongoOS and m1n1, tethered.
entries = ["checkra1n"]

[kernel]
platform = "apple-4k"
dtb = "t7000-n102" # arch/arm64/boot/dts/apple/<dtb>.dtb

[firmware]
recipe = "firmware.json" # Pins this board's public IPSW; converts nothing yet.

[support]
status = "experimental"

# States: working, untested, missing, none (features.toml). "untested" means a driver
# binds in its device tree (tools/catalog/drivers.json), plus the display's boot console.
[features]
display = "untested"
screen_off = "missing"
backlight = "untested"
touch = "missing"
buttons = "untested"
accelerometer = "missing"
gyroscope = "missing"
light_sensor = "missing"
touch_id = "missing"
storage_read = "working" # ANS1 (asp) on RTKit 10.2: the user area asp0n1 and nine read-only auxiliary namespaces.
storage_write = "working" # The user area only; asp refuses every other namespace's writes. An install next to iOS wrote asp0n1 only.
wifi = "missing"
bluetooth_input = "missing"
bluetooth_audio = "missing"
cellular = "missing"
battery = "missing" # No fuel-gauge node in the ADT where the iPhone 6 has its HDQ gauge on uart5; how the iPod reads its battery is unknown.
charging = "missing"
charging_control = "missing"
suspend = "untested"
resume = "untested"
usb_serial = "working" # The RAM shell over USB serial (CDC ACM).
usb_network = "untested"
usb_host = "missing"
audio_output = "missing"
audio_input = "missing"
camera = "missing"
video_decode_hevc = "missing"
20 changes: 20 additions & 0 deletions devices/n102/firmware.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
{
"schema": 2,
"device": "iPod7,1",
"ipsw": {
"version": "12.5.8",
"build": "16H88",
"url": "https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-28554/C3D5CA8F-8B6F-4B05-9456-C5E632723337/iPodtouch_12.5.8_16H88_Restore.ipsw",
"bytes": 2821634289,
"sha256": "53a645c03332cd132f52612ffdf2aba3e6908ca937ab7f6c7b81aa8e15a14ec6"
},
"inputs": {
"DeviceTree.im4p": {
"ipsw": {
"zip": "Firmware/all_flash/DeviceTree.n102ap.im4p"
},
"sha256": "f59b40ce4fa554f4bb24415201c61dd2e8a6767558ca6404a4afa74dd2ec2d35"
}
},
"outputs": []
}
18 changes: 18 additions & 0 deletions devices/n56/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# iPhone 6 Plus, N56

Hardware identity, boot assets and the firmware recipe are in
[`device.toml`](device.toml). This file tracks what still needs testing,
open work, and contributed code that is not in the tree yet.

## Needs testing

**GPU (A8, PowerVR GX6450).** The board has the iPod touch 6's A8 GPU, and
its device tree enables it (`kernel/patches/devices/t7000/0012`). The
driver has only run on the iPod touch 6 (N102) so far. Test with
[`examples/ipod-gpu-drm`](../../examples/ipod-gpu-drm/README.md)
(`--device n56`) and report the output of `a8-gpu-drm-test probe` with
its kernel lines, and the ladder's `RESULT` lines.

## Unmerged code

None.
18 changes: 18 additions & 0 deletions devices/n61/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# iPhone 6, N61

Hardware identity, boot assets and the firmware recipe are in
[`device.toml`](device.toml). This file tracks what still needs testing,
open work, and contributed code that is not in the tree yet.

## Needs testing

**GPU (A8, PowerVR GX6450).** The board has the iPod touch 6's A8 GPU, and
its device tree enables it (`kernel/patches/devices/t7000/0012`). The
driver has only run on the iPod touch 6 (N102) so far. Test with
[`examples/ipod-gpu-drm`](../../examples/ipod-gpu-drm/README.md)
(`--device n61`) and report the output of `a8-gpu-drm-test probe` with
its kernel lines, and the ladder's `RESULT` lines.

## Unmerged code

None.
7 changes: 6 additions & 1 deletion docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Generated by `tools/catalog/generate matrix` from `devices/`, `chips/` and `meth
| A6 | S5L8950X | `0x8950` | – | – | apple-armv7 | iBSS + iBEC | – | 4 | 0 | 0 |
| A6X | S5L8955X | `0x8955` | – | – | apple-armv7 | iBSS + iBEC | – | 3 | 0 | 0 |
| A7 | S5L8960X | `0x8960` | cyclone | 4096 | apple-4k | iBSS + iBEC | – | 10 | 10 | 10 |
| A8 | T7000 | `0x7000` | typhoon | 4096 | apple-4k | iBSS + iBEC | – | 4 | 4 | 4 |
| A8 | T7000 | `0x7000` | typhoon | 4096 | apple-4k | iBSS + iBEC | – | 5 | 5 | 5 |
| A8X | T7001 | `0x7001` | typhoon | 4096 | apple-4k | iBSS + iBEC | – | 2 | 2 | 2 |
| A9 | S8000 | `0x8000` | twister | 16384 | apple-16k | iBSS + iBEC | – | 5 | 5 | 5 |
| A9 | S8003 | `0x8003` | twister | 16384 | apple-16k | iBSS + iBEC | – | 5 | 5 | 5 |
Expand Down Expand Up @@ -65,6 +65,7 @@ Generated by `tools/catalog/generate matrix` from `devices/`, `chips/` and `meth
| A7 | `n53` | iPhone 5s (Global) | iPhone6,2 | experimental | – | checkm8-pongo | yes | yes | 16H88 |
| A8 | `j96` | iPad mini 4 (Wi-Fi) | iPad5,1 | experimental | – | checkm8-pongo | yes | yes | 19H422 |
| A8 | `j97` | iPad mini 4 (Cellular) | iPad5,2 | experimental | – | checkm8-pongo | yes | yes | 19H422 |
| A8 | `n102` | iPod touch 6 | iPod7,1 | experimental | yes | checkm8-pongo | yes | yes | 16H88 |
| A8 | `n56` | iPhone 6+ | iPhone7,1 | experimental | – | checkm8-pongo | yes | yes | 16H88 |
| A8 | `n61` | iPhone 6 | iPhone7,2 | experimental | – | checkm8-pongo | yes | yes | 16H22 |
| A8X | `j81` | iPad Air 2 (Wi-Fi) | iPad5,3 | experimental | yes | checkm8-pongo | yes | yes | 19H422 |
Expand Down Expand Up @@ -152,6 +153,7 @@ Boards Orchard builds for. States: working, untested, missing, none (no such har
| `n53` | untested | missing | untested | missing | untested | missing | missing | missing | missing | missing | missing | missing | missing | missing | missing | missing | missing | missing | untested | untested | untested | untested | missing | missing | missing | missing | missing |
| `j96` | working | missing | working | untested | working | missing | missing | missing | missing | missing | missing | working | missing | missing | none | working | missing | missing | untested | untested | working | working | missing | missing | missing | missing | missing |
| `j97` | untested | missing | untested | untested | untested | missing | missing | missing | missing | missing | missing | untested | missing | missing | missing | untested | missing | missing | untested | untested | untested | untested | missing | missing | missing | missing | missing |
| `n102` | untested | missing | untested | missing | untested | missing | missing | missing | missing | working | working | missing | missing | missing | missing | missing | missing | missing | untested | untested | working | untested | missing | missing | missing | missing | missing |
| `n56` | untested | missing | untested | missing | untested | missing | missing | missing | missing | missing | missing | missing | missing | missing | missing | untested | missing | missing | untested | untested | untested | untested | missing | missing | missing | missing | missing |
| `n61` | working | untested | untested | working | untested | missing | missing | missing | missing | missing | missing | missing | missing | missing | missing | untested | missing | missing | untested | untested | working | untested | missing | missing | missing | missing | missing |
| `j81` | working | untested | working | working | working | missing | missing | missing | missing | working | working | working | untested | untested | none | working | missing | missing | untested | untested | working | working | missing | missing | missing | missing | missing |
Expand Down Expand Up @@ -207,6 +209,7 @@ A yes means an enabled device tree node binds a driver in `7.3.0-rc1-orchard-app
| `n53` | experimental | yes | – | yes | – | – | – | – | – | – | – | – | – | – | yes | yes | – | – | – | – |
| `j96` | experimental | yes | yes | yes | – | – | – | – | – | yes | – | – | yes | – | yes | yes | – | – | – | – |
| `j97` | experimental | yes | yes | yes | – | – | – | – | – | yes | – | – | yes | – | yes | yes | – | – | – | – |
| `n102` | experimental | yes | – | yes | – | – | – | – | – | – | – | – | – | – | yes | yes | – | – | – | – |
| `n56` | experimental | yes | – | yes | – | – | – | – | – | – | – | – | yes | – | yes | yes | – | – | – | – |
| `n61` | experimental | yes | yes | yes | – | – | – | – | – | – | – | – | yes | – | yes | yes | – | – | – | – |
| `j81` | experimental | yes | yes | yes | – | – | – | – | – | yes | yes | yes | yes | – | yes | yes | – | – | – | – |
Expand Down Expand Up @@ -248,6 +251,8 @@ A yes means an enabled device tree node binds a driver in `7.3.0-rc1-orchard-app

| Board | Feature | |
| --- | --- | --- |
| `n102` | Internal storage read | working, but no driver binds |
| `n102` | Internal storage write | working, but no driver binds |
| `j81` | Internal storage read | working, but no driver binds |
| `j81` | Internal storage write | working, but no driver binds |
| `j71s` | Microphone | untested, but no driver binds |
Expand Down
5 changes: 5 additions & 0 deletions examples/ipod-gpu-drm/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
out/
rootfs/usr/bin/a8-gpu-drm
rootfs/usr/share/a8-gpu-drm/
rootfs/lib/firmware/
rootfs/opt/
79 changes: 79 additions & 0 deletions examples/ipod-gpu-drm/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# ipod-gpu-drm

A RAM payload that tests the A8 (T7000) GPU, a PowerVR GX6450, through powervr's A8 variant
(`kernel/patches/drivers/gpu/0063`–`0073`, `devices/t7000/0011` and `0012`). It is `minimal-boot` with a
constant USB serial number (`a8-gpu-drm`, so macOS does not ask to allow the accessory on every boot),
the kernel's modules, the GPU firmware, a test script and, optionally, a Vulkan bundle built from
OrchardLinux/mesa.

It builds for every A8 board: the iPod touch 6 (`n102`, where the GPU has been tested), the iPad mini 4
(`j96`, `j97`) and the iPhone 6 and 6 Plus (`n61`, `n56`). The A8X (iPad Air 2) has a different GPU.

## Build

Use the `orchard` launcher of this checkout (`bin/orchard`): the nightly `orchard` on PATH does not carry
the A8 GPU patches. `BOARD` below is one of the boards above.

1. Kernel: `bin/orchard build examples/minimal-boot --device BOARD`. This builds the apple-4k kernel in
Orchard's shared tree, `~/.cache/orchard/kernel-work/apple-4k-<pin>/`.
2. Optional, for the `vk` step, the Vulkan ladder and vkmark: build the bundle on aarch64 Linux (an
Arch Linux ARM container works) with `vk/make-bundle.sh MESA_BUILD OUT`. `MESA_BUILD` is a meson build
of OrchardLinux/mesa's A8 branch with `-Dvulkan-drivers=imagination`; the script's header has the
meson line. It also packs vkmark if the `vkmark` package is installed there.
3. Stage the payload's files:

```sh
A8_VK_DIR=/path/to/OUT examples/ipod-gpu-drm/build.sh ~/.cache/orchard/kernel-work/apple-4k-<pin>
```

`build.sh` runs `tools/extract-fw.py`, which reads the iPod touch 6's iOS 12.4 (16G77) kernelcache
from Apple's public IPSW over HTTP ranges (about 15 MB, not the whole IPSW) and writes
`gfx-t7000.bin` (the GPU firmware) and `gfx-t7000-border.bin` (its border colour table). Use that
firmware on every A8 board: it is the one the driver was tested with. `tools/extract-fw.py DIR --ipsw
URL BYTES BOARD` takes another IPSW, e.g. the iPad mini 4's, and warns when the firmware is not the
tested one. Nothing from Apple is stored in this repository; everything `build.sh` writes is
git-ignored.
4. `bin/orchard build examples/ipod-gpu-drm --device BOARD`

## Run

1. Put the device in DFU mode, then `bin/orchard run examples/ipod-gpu-drm --device BOARD --no-build`
(checkm8, PongoOS, m1n1, Linux; RAM only, nothing is written to the device).
2. Open the USB serial console. powervr is not loaded at boot.
3. `a8-gpu-drm-test probe` loads powervr (`exp_hw_support=1`). The probe powers the GPU, reads its ID and
boots the firmware to its alive event; the render node then reports BVNC 3.10.4.5. Every step prints
one `RESULT` line, runs under a 30 s hardware watchdog (a frozen SoC resets) and saves its kernel lines
to `/run/a8-gpu-drm/STEP.txt`. After a failed step nothing more runs until the next boot.
4. `a8-gpu-drm-test vk`: Vulkan probe, compute and a triangle through Mesa.
5. The Vulkan ladder, every pixel checked on the CPU:

```sh
/opt/a8vk/a8-vk-ladder.sh list
for r in $(/opt/a8vk/a8-vk-ladder.sh list | awk 'NR>1 && /^ /{print $1}'); do /opt/a8vk/a8-vk-ladder.sh $r; done
```

6. vkmark: `/opt/a8vk/vkmark.sh --size 256x256` and `--size 750x1334`.
7. A soak: `a8-gpu-soak 1000 0` runs the `vk` step 1000 times.

The `compute` and `triangle` steps replay two Mesa recordings from the bring-up through the DRM ioctls
(`src/a8-gpu-drm.c`). They need `A8_RECORDINGS` at build time, which this example does not provide;
without it `a8-gpu-drm-test all` skips them.

## Reporting

On a board other than the iPod touch 6, report the board, the output of `a8-gpu-drm-test probe` with
its kernel lines (`/run/a8-gpu-drm/probe.txt`, or `dmesg` if the device froze and the serial log is all
there is), and the ladder's `RESULT` lines. If the probe freezes the device, the last kernel lines
streamed over the serial console show how far it got.

## Files

| Path | What |
|---|---|
| `init` | PID 1: `minimal-boot` with the constant USB serial number |
| `rootfs/usr/bin/a8-gpu-drm-test` | the test steps: `probe`, `compute`, `triangle`, `vk`, `all` |
| `rootfs/usr/bin/a8-gpu-soak` | repeats the `vk` and `triangle` steps |
| `src/a8-gpu-drm.c` | the DRM replay program: static aarch64, no libc |
| `tools/extract-fw.py` | the GPU firmware and border table from an Apple kernelcache |
| `tools/gen-replay.py` | packs a Mesa recording into a replay file |
| `vk/` | the Vulkan smoke test, the Vulkan ladder and `make-bundle.sh` |
Loading
Loading