Skip to content

j81: internal storage (ANS1) — install and launch Omarchy on the iPad Air 2 - #188

Open
ricktav wants to merge 4 commits into
OrchardLinux:mainfrom
ricktav:j81/ans1-storage
Open

ricktav wants to merge 4 commits into
OrchardLinux:mainfrom
ricktav:j81/ans1-storage

Conversation

@ricktav

@ricktav ricktav commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Summary

Internal storage on the iPad Air 2 (J81, A8X). With it, orchard install puts Omarchy A next to iPadOS, and orchard launch starts it from the iPad.

The A7, A8 and A8X keep their flash behind ANS1, an RTKit coprocessor with its own command protocol (not NVMe). This PR carries Nick Chan's ANS1 driver from HoolockLinux/linux (ans1, ed8528f), with the hardening from mattonik/ipad-nixos and micro23/ipadair2-omarchy. Of Hoolock's RTKit changes it keeps only what the J81 needs. Each patch names its origin commits and what changed.

Changes

  • Kernel (drivers/soc-apple 0025-0027, new drivers/block):
    • Mailbox binding and match: the ANS mailbox is the existing A7 IOP variant.
    • RTKit: an opt-in epmap_done callback, and decoding of the armv7 crashlog section (CrgA).
    • The ANS1 binding and the asp block driver.
    • CONFIG_APPLE_ASP=m in both configs.
  • Device tree (devices/t7001 0010-0011): ANS and mailbox nodes in t7001.dtsi, disabled there, and enabled on t7001-air2.
  • Install and boot:
    • The apple-4k initrd loads asp.
    • The installer takes asp<N>n1 (the user area) as the internal disk.
    • A udev rule gives asp* partitions /dev/disk/by-partuuid and by-uuid links. systemd's 60-persistent-storage.rules skips asp*, and without these links the installer's /boot fstab entry by PARTUUID timed out into emergency mode.
  • J81: storage_read and storage_write are working, and J81 is now installable. Includes the regenerated matrix and a CHANGELOG line.

Shared code

drivers/soc/apple is used by every Apple coprocessor driver, so the changes there are kept small and opt-in:

  • Mailbox: a new compatible, apple,akf-mailbox-v1, mapped to the existing A7 IOP variant. Nothing else matches it.
  • RTKit epmap_done: the ANS only reaches its power-on state once its app endpoint is started, and RTKit allows that only after boot. A driver that sets epmap_done may start its app endpoints when the endpoint map is complete. Drivers without the callback behave exactly as before.
  • Crash logs: the armv7 register section is decoded, and the armv8 section is decoded as before.
  • Left out: Hoolock's RTKit 10.0 support (protocol version split, 4-bit message types, HELLO reply, power-state changes). It changes behaviour for other RTKit 10.x firmware, and the J81's ANS reports RTKit 12. The driver uses the storage endpoint 0x20 (RTKit 11 and later). ANS firmware on RTKit 10 would need that support first.

Write safety

  • The auxiliary namespaces (firmware, NVRAM, ...) are read-only disks, and the driver refuses writes, flushes and admin output to them.
  • The user area is writable, as on the NVMe iPads.
  • The experimental read-only default and LBA write window from ipad-nixos are not carried. Following kernel/REVIEW.md, safety comes from the test order instead: RAM boot, then read-only, then read-write on the Linux partition, then the installer.

Not included

Nick's ANS nodes for s5l8960x (A7) and t7000 (A8) are left out because they are untested on hardware. Owners of those boards can add them with this driver, after checking which RTKit version their ANS firmware speaks.

Testing

  • iPad Air 2 Wi-Fi (J81, iPad5,3), iPadOS 15 with APFS shrunk to 16 GB. Host: Asahi Linux on a MacBook Air M2.
  • The read-only RAM boot and orchard install ran with earlier revisions of this driver. Those revisions passed a write window on the kernel command line; this PR drops that. The install wrote the GPT, XBOOTLDR and root, and the system booted to its desktop.
  • This exact revision: I built the apple-4k kernel from this branch's series (orchard build --device j81) and its platform layer (python -m orchard.image.platform apple-4k). I installed the layer on that system with boot-entries sync and started it with orchard launch. The asp.ko running on the device matches the one in the layer (sha256). Rebasing onto current main changed nothing under kernel/, platforms/ or system/ except the m1n1 fix from m1n1: ANS1: free the command queue once on shutdown #185, which the launch already used. Results:
    • dmesg: RTKit: Initializing (protocol version 12), ASP endpoint is 32, ASP block device 64000000000 bytes, partitions found. No new errors.
    • /proc/cmdline has no asp. options.
    • asp0n1 is ro=0, and asp0n2..asp0n10 are ro=1.
    • / (asp0n1p3, ext4) and /boot (asp0n1p2) are mounted rw, and a write/fsync/read test passed. /dev/disk/by-partuuid has the partitions.
    • systemctl is-system-running reports running with no failed units.
    • The desktop, touch and Wi-Fi work.
  • python -m unittest discover -s tests: everything passes except 5 tests in test_ram and test_cascadia_loader, which also fail on unmodified main on this host. kernel/audit-patches.py passes for apple-4k and apple-16k. tools/catalog/generate matrix --check passes.
  • Not tested: other Apple coprocessor drivers on other boards. They only see the new callback field, which they leave unset.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SFMaVe993UGYsK61nbtYhR

ricktav and others added 4 commits November 19, 2026 19:29
Add Nick Chan's ANS1 (asp) block driver from Hoolock, the mailbox match
it needs and a small opt-in RTKit hook, as a module in both configs:

- CONFIG_APPLE_ASP=m: the iPad Air 2 (J81, A8X) keeps its internal
  storage behind ANS1; the platform initrd loads it to find the root.
  apple-16k builds it too, as both configs carry the same options.
- RTKit gains an epmap_done callback (only drivers that set it see a
  change) and decodes armv7 crash logs. Hoolock's RTKit 10.0 support is
  left out: the J81's ANS speaks RTKit 12.0 and does not need it, and it
  would change behaviour for other RTKit firmware.

Each patch names its Hoolock origin and what changed on the way
(hardening from mattonik/ipad-nixos and micro23/ipadair2-omarchy; no
read-only default or LBA write window).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFMaVe993UGYsK61nbtYhR
Describe the A8X ANS coprocessor and its mailbox (disabled in t7001.dtsi)
and enable them on the iPad Air 2 with the firmware region m1n1 fills in
through the asp alias.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFMaVe993UGYsK61nbtYhR
- apple-4k's initrd loads asp instead of nvme: A7-A8X have no NVMe.
- The installer takes asp<N>n1, the ANS1 user area, as the internal disk.
- udev names asp partitions under /dev/disk/by-partuuid and by-uuid:
  systemd's 60-persistent-storage.rules skips asp*, so the installer's
  /boot fstab entry by PARTUUID timed out into emergency mode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFMaVe993UGYsK61nbtYhR
Seen on an iPad Air 2 Wi-Fi: orchard install wrote Omarchy A next to
iPadOS and orchard launch starts it from internal storage, root and
/boot read-write, desktop, touch and Wi-Fi working.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFMaVe993UGYsK61nbtYhR
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant