Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Keep the guest's Metal shader caches across a reboot

Arbifox00ee15fd160a
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index c5504a2b..45ff0932 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -806,6 +806,7 @@ do NOT execute these).
| 26 | No binary change: both spawn hooks insert `libdevicehubfix.dylib` into `cryptexd`, the DDI's `dtremotedisplayd` and `dtdeviceinfod`, and `avconferenced`. In `cryptexd` it interposes `fcntl` and reports an `EPERM` from `F_SETPROTECTIONCLASS` as `ENOTSUP`; in `dtremotedisplayd` it interposes `MediaStreamSupportedFeatures.current` (answers `0x8c`) and `CurrentDevice.isCustomerRestricted` (answers false) from the DDI's `CoreDeviceUtilities`; in `dtdeviceinfod` it interposes `MGCopyAnswer` and fills a missing `FramebufferIdentifier` for `phone11` chrome; in `avconferenced` it replaces `VCPSideCarMetal`'s two band reads through the Objective-C runtime and runs one synchronous scaler transform before the first read of each frame — **all bases** | none (new guest dylib `VPhoneGuestComponents/DeviceHubFix/libdevicehubfix.c`, installed at `/usr/lib/libdevicehubfix.dylib`) | **Let Xcode 27's DeviceHub show the guest's screen.** On iOS 27 `cryptexd` stages each DDI asset with `open(O_RDWR)` + `fcntl(F_SETPROTECTIONCLASS, 4)` and accepts only `ENOTSUP` as a failure; a guest answers `EPERM` (`set protection class: [1: Operation not permitted]`, `staging failed`), so CoreDevice shows the device as "connected (no DDI)" for good. With the DDI mounted, DeviceHub asks `dtremotedisplayd` for its media stream features and gets 0 from CoreDeviceUtilities' policy: `isCustomerRestricted` (`isProductionFused && !hasInternalOSBuild && hasInternalDDI == false`) refuses every pre-27.0 device, and remote control is limited to iPhone, Apple Watch and Apple TV, which refuses every iPad. `0x8c` is what a Mac host reports for itself (mirrored primary display 0x4, system audio 0x8, display information 0x80). The 27.x iPhone guest reports `phone11` chrome with no `FramebufferIdentifier`, so DeviceHub drew the screen over the bezel corners; the hook answers only that missing key with Xcode's matching mask `4E5532ED-1470-47D1-BDF4-7AA90C26957A` from `/Library/Developer/DeviceKit/chrome_map.plist`. Interposing reaches all of them because `cryptexd`, `dtremotedisplayd`, `dtdeviceinfod` and `CoreDeviceUtilities` are standalone images; the two Swift symbols are weak flat-namespace imports, resolving to nothing outside `dtremotedisplayd`. On 27.x the view also needs row 11's conditional dispatch, or the capture display stays black. A stream that splits each frame into four bands (`tilesPerFrame` 4) deadlocked the host GPU within 16–35 s of screen activity: `VCPSideCarMetal` reads every frame once per band while the paravirtual scaler's write of that frame can still be unregistered on the host, and a band read that registers the first of the frame's two planes before the write and the second after it waits on the write, which waits on it (`Timeout in timestamp wait`, the guest loses its GPU). Waiting for one synchronous transform puts the band reads behind the frame's write. `VideoProcessing` is in the shared cache, so this part is a method replacement, not an interpose. Ships with `system-launchdaemons-boot-environment`; an existing guest gets it from the environment update. Details: `Research/Guest/devicehub_screen_viewing.md`. **Validated (2026-10-06/07):** `iPad16,1 26.6.2 (23G90)`: DeviceHub receives `supportedFeatures: 140`, `MediaStreamStart` succeeds and the view shows the live home screen. `iPhone17,3 27.0.1 (24A446)`: the DDI mounts (`F_SETPROTECTIONCLASS EPERM, reported as ENOTSUP`), and with row 11's conditional dispatch DeviceHub shows the home screen and Settings live, clipped inside the chrome (`Found FramebufferMaskIdentifier from displayInfo`). **Band reads validated (2026-10-07/08, `iPhone17,3 27.0.1 (24A446)`):** a four-band stream with screen activity deadlocked after 18 s without the barrier and ran 60, 180 and 300 s with it without a GPU error; in the host trace of the 180 s run no IOSurface access waited, and every band read of 6258 frames registered after the frame's write was released, a median 0.76 ms after it. Open: latency that grows over a long session and occasional stalls after a cold start, both upstream of the Mac receiver. | Y | Y | Y |
| 27 | No binary change: both spawn hooks insert `libdevicename.dylib` into `configd` and `lockdownd` (after `libmisfix.dylib`, the first process to take two inserted libraries). In `configd` it interposes `SCDynamicStoreSetMultiple` and `SCDynamicStoreSetValue` and pins `Setup:/System`'s `ComputerName`; in `lockdownd` it interposes `SCPreferencesSetComputerName`, `SCPreferencesSetHostName` and `SCPreferencesSetLocalHostName` and refuses every rename with `kSCStatusAccessError`. Inert unless `/var/db/vphone/devicename.plist` holds a valid `DeviceName` — **all bases** | none (new guest dylib `VPhoneGuestComponents/DeviceName/libdevicename.c`, installed at `/usr/lib/libdevicename.dylib`; vphoned `device.name.get`/`device.name.set`) | **Pin the guest's device name to the VM's name.** The name is `System/System/ComputerName` in `preferences.plist`; configd's PreferencesMonitor (`updateConfiguration`, 24A435 `0x100062098`) flattens it into `Setup:/System` with one `SCDynamicStoreSetMultiple`, and every reader (`SCDynamicStoreCopyComputerName` in lockdownd's `copy_device_name`, MobileGestalt `UserAssignedDeviceName`, `UIDevice.name`) reads the store. The hook rewrites that publication, not the preferences read: the monitor's model-change path (`sub_10006155c`) writes the `kSCPrefSystem` value it reads back to disk, and the publication route leaves `preferences.plist` with the guest's own name. A publication that leaves `Setup:/System` out as unchanged gets the store's value pinned; one that removes it gets the pinned name instead. `vphone-vm` sends the VM's name to vphoned's `device.name.set` after every connect; vphoned writes the file (one rename, 0644) and applies the preferences unchanged, so configd publishes again and the new pin, or the guest's own name when the file is removed, is live within a second. The file outlives a reboot, so configd's first publication at boot carries it. The library re-reads the file when its inode, size or mtime change. lockdownd's `set_device_name` (`0x1000073b0`) is the only caller of the three setters; it logs their failure and still commits, and the `SetValue DeviceName` handler ignores the result, so a host rename reports success and the name stays. The pinned name itself is refused too: lockdownd runs `set_device_name(copy_device_name())` whenever it starts, and a lockdownd restarted after configd published would otherwise write the pinned name and derived host names into `preferences.plist` (seen once). An NVRAM variable was the first channel and never reached the guest: iBoot keeps only the variables it knows (even `vphone-vm`'s `boot-args` write is replaced). Interposing works because both daemons are standalone images. Ships with `system-launchdaemons-boot-environment` and the environment update; takes effect at the next boot. Verified on iOS 27.0 (24A435) on 2026-10-07: pin at boot and live, host rename refused, `vm rename` followed, preferences untouched. CoreDevice (`devicectl`, DeviceHub) reads the name when the device appears and can lag one boot after a rename. Details: `Research/Guest/device_name_pinning.md`. | Y | Y | Y |
| 28 | `cbz`/`cbnz` -> `b` at the four compact-command choices in `-[PGSerializerRenderCommandEncoder drawIndexedPrimitives:…]` (`0x140b0`, `0x1421c`, `0x143b4`, `0x143c4` in 23E5207q) — **cloudOS 26.4** | `AppleParavirtGPUMetalIOGPUFamily` (`/System/Library/Extensions/AppleParavirtGPUMetalIOGPUFamily.bundle`) | **Heap index buffer fix.** The compact command stores `parentResourceOffset + indexBufferOffset` in 16 bits but is chosen by testing `indexBufferOffset` alone, so an index buffer 64 KiB or more into an `MTLHeap` is read from the wrong address and meshes (Unity games) draw with another mesh's indices. Every indexed draw takes the 64-bit command instead. `system-paravirt_gpu-cfw-heap_index_offset`; see "Heap index buffers reach the host whole (2026-10-14)" and `Research/Guest/gpu_acceleration.md` | Y | Y | Y |
+| 29 | No binary change: SystemHook calls `setenv("FS_CACHE_REUSE_ON_REBOOT", "1", 0)` first thing in its constructor, in every process it is inserted into, while `/usr/lib/vphone-metal-cache-reuse` exists — **all bases** | none (`VPhoneGuestComponents/SystemHook/SystemHook-vphone.c`; marker written by `cfw install` / `cfw update-environment`) | **Keep the guest's Metal shader caches across a reboot.** `libCoreFSCache` stamps each cache with `kern.bootsessionuuid` and resets it at the next boot unless the variable is set; on the paravirtual GPU CoreAnimation's precompiled pipelines are disabled, so backboardd rebuilt every pipeline after every boot. `system-systemhook-cfw-metal_cache_reuse`; see "Guest Metal caches survive a reboot (2026-10-19)" | Y | Y | Y |
### Swift port status — the eight DSC patchers (2026-09-23)
@@ -3235,3 +3236,22 @@ in `fw patch`. The SEP firmware (`sep-firmware.vphone600.RELEASE.im4p`, sent as
before keep Apple's SEP ROM; `vm config --seprom opensep|apple` switches one
without a restore. `Firmware/opensep_sep_rom.md` has the contract and the
validation.
+
+## Guest Metal caches survive a reboot (2026-10-19)
+
+Row 29. `system-systemhook-cfw-metal_cache_reuse`, declared in the Guest
+System set, is on in `standard` and `experimental` and blocked in both Apple TV
+presets (they carry no SystemHook). Its target is the marker
+`/usr/lib/vphone-metal-cache-reuse`: `cfw install` and `cfw update-environment`
+write it when the patch is selected and remove it when it is not, so it is
+revertible. While the marker exists, SystemHook's constructor sets
+`FS_CACHE_REUSE_ON_REBOOT=1` before anything else, so `libCoreFSCache` keeps
+each Metal cache stamped by an earlier boot instead of resetting it. No system
+binary, shared cache or kernel byte changes.
+
+Verified on `Lychee` (iPhone, iOS 27.0.1, cloudOS 26.4) with real reboots:
+backboardd's `functions.list` keeps its boot UUID header and size across three
+boots, guest compiles for backboardd during five Settings rounds fall from
+about 145 to 0, no GPU restart, and the first go-home goes from about 31% to
+37–44% on time. Numbers and method: `Guest/gpu_acceleration.md`, "Real reboots
+with the patch (2026-10-19)".
diff --git a/Research/Guest/gpu_acceleration.md b/Research/Guest/gpu_acceleration.md
index 05851793..0a4d1704 100644
--- a/Research/Guest/gpu_acceleration.md
+++ b/Research/Guest/gpu_acceleration.md
@@ -222,6 +222,290 @@ recompile is therefore a limitation of the host paravirtual GPU, not a guest
patch we can write. (A per-app `MTLBinaryArchive` inside a guest app would
persist that app's own pipelines, but that is an app change, not a VM one.)
+### Seeding the cache from the host (2026-10-18)
+
+The section above concluded that only Apple's framework could fix the misses.
+The cache is plain files in a user-owned directory, so a host process can write
+into it before a task opens it. That works. A seed is safe only when it holds
+what **the same guest process** compiled in an earlier boot. A seed that mixes
+entries from several processes hangs the guest GPU. The safe form works, but
+it buys little: about two points of on-time frames. So nothing ships.
+
+Measured on `Lychee` (iPhone, iOS 27.0.1, cloudOS 26.4 (23E5207q) driver,
+macOS 27.0.1 host, bundle 2.10.1).
+
+#### What the host checks on a hit
+
+`-[ParavirtualizedGraphicsGPUTask handshakeWithTaskRoot:…cachePath:cacheExtension:reply:]`
+in `com.apple.gpusw.ParavirtualizedGraphicsGPUTask` consumes the sandbox
+extension and calls `MTLSetShaderCachePath(cachePath)`. Without a path it sets
+`FS_CACHE_SIZE=0`. Everything after that is Metal's ordinary per-process
+function cache, `MTLCompilerFSCache` under `MultiLevelBinaryFSCache` in
+`Metal.framework`. PG adds no format and no check of its own.
+
+`MTLCompilerFSCache::getElementImpl(MTLUINT256_t, void**, size_t*)` looks up the
+key, requires the entry to be longer than 64 bytes, and compares the first 32
+bytes with `SHA-256` of the body and the next 32 with the key it asked for. A
+mismatch calls `invalidateCache()`, and a match returns the body. That is the
+whole check. Nothing on a hit names a process, a device or a driver. A
+well-formed entry is used as it is, whatever task wrote it.
+
+PG then builds the pipeline with
+`newComputePipelineStateWithDescriptor:options:0 reflection:nil error:`, after
+`setResourceIndex:` and `setForceResourceIndex:YES` from the guest's command.
+On failure it logs `Failed to create compute pipeline: …` to its host log.
+
+#### File layout
+
+- `com.apple.paravirtualizedgraphics-<ecid in decimal>/task-<random>/<arch>/functions.{list,data}`,
+ `<arch>` being `16777235_530` here. A task's directory goes away when its
+ process exits. The framework leaves a directory that no task owns where it
+ is: ten made by earlier experiments outlived many boots.
+- `functions.list`: a 32-byte constant header, then for each entry its fields
+ and its key, then 8 zero bytes. The first entry's fields are `u32` tag, `u64`
+ 0, `u64` size, `u64` offset; the others' are `u64` 0, `u64` size, `u64`
+ offset. A key is 32 bytes and comes *after* its entry's fields.
+- `functions.data`: the entries, 8-byte aligned, padded to a multiple of 64 KiB.
+ An entry is `SHA-256(body)`, its own key, then the body. `size` counts all
+ three.
+- Bodies are of two kinds. A Mach-O (`feedfacf`) holds an AGX binary with
+ `__TEXT,__text` and `__GPU_METADATA`, `__GPU_LD_MD`, `__GPU_STATS_MD`,
+ and the rest. A blob starting `ef13c710` carries argument names
+ (`mvp_matrix`, `view_matrix`, `Params_t`…), which looks like reflection.
+ These are the "pairs" seen earlier. In the 656-entry task, 400 are Mach-O
+ and 256 are blobs.
+
+#### Why a mixed seed breaks
+
+The same key holds different bytes in different processes. Every
+cross-process difference found (44 shared keys over six tasks of one boot)
+falls in one of three places:
+
+- `__GPU_STATS_MD`: the compile time. Harmless.
+- One `u32` in `__GPU_LD_MD`, in the record `0x0c, 0x10, ID, 0, 0, len, name`
+ (the name being the AGX function's, such as `fca15dhmha4` or `eot`). In one
+ task the ID follows the order of compilation: entries 29 to 43 carry 29 to
+ 43. Each binary therefore embeds a per-process compile counter.
+- One or two words in the reflection blobs (for example 121 against 123).
+
+Rewriting every Mach-O ID to `1000000 + n`, with the SHA-256 recomputed, did
+**not** stop the failure on its own. The ID is not the whole story, and what
+else ties an entry to its process was not pinned down.
+
+The failure itself, now with both logs:
+
+- Host (`log stream` for the GPU task and `MTLCompilerService`): every compile
+ in backboardd's task succeeds, and no `Failed to create compute pipeline`
+ is logged. `downsample_4_compute` is never sent to the compiler: it is a hit.
+- Guest (`logs.syslog` for backboardd, taken while Camera launches): within
+ about 2 s, backboardd's CoreAnimation command buffers end with
+ `Caused GPU Hang Error (00000003:kIOGPUCommandBufferCallbackErrorHang)`.
+ The GPU restarts, and only then does the next `newComputePipelineState…`
+ fail. That failure is the `Compilation failed` abort in
+ `CA::OGL::MetalContext::get_compute_pipeline` under
+ `BlurStateCompute::downsample_box_4`.
+
+So a hit is not rejected. It is *executed*, and the binary from another process
+hangs the GPU. The ddmin pair from earlier, list positions 34 and 35, turns out
+to be AGX's own blit kernel `blit_uber_buf_to_tex_uint`, not a CoreAnimation
+kernel. The oracle was also flaky. Neither result was worth chasing.
+
+#### Seeding a task with its own entries
+
+The first task the guest creates after start, about 7 s in, is backboardd's.
+That is its render server: a backboardd crash takes down that host task.
+`prefill` here fills only that task's directory, with the files the same task
+had at the end of the previous boot.
+
+| Seed for backboardd's task | Boot, unlock, launch Camera | Result |
+| --- | --- | --- |
+| Its own files from a previous cold boot | 3 runs | 0 restarts each |
+| The `boot1` union of every task | 2 runs | 14 and 393 restarts |
+| The `boot1` union with every ID rewritten | 1 run | 105 restarts |
+
+The full test then ran as three pairs: a cold boot, then a boot whose backboardd
+task was seeded with that cold boot's backboardd files. Each boot launched all
+eleven apps, Camera included. Compile CPU is the per-process delta of host
+`MTLCompilerService` CPU time across the workload.
+
+| Run | GPU restarts | New backboardd / cameracaptured crashes | Host compile CPU | Compiles, all (backboardd) |
+| --- | --- | --- | --- | --- |
+| cold 1 | 0 | 0 | 3.86 s | 640 (374) |
+| seeded 1 | 0 | 0 | 1.58 s | 270 (4) |
+| cold 2 | 0 | 0 | 3.76 s | 632 (373) |
+| seeded 2 | 0 | 0 | 1.58 s | 273 (7) |
+| cold 3 | 0 | 0 | 3.89 s | 640 (374) |
+| seeded 3 | 0 | 0 | 1.82 s | 313 (27) |
+
+These runs also reported frame pacing. Those numbers are void, for two
+reasons. They came from `AppUsage.lastSubmittedTime` of the host task's
+`AGXDeviceUserClient`, which was later seen not to move at all during
+animations. And the workload's `{"t":"home"}` is not a command
+(`unknown command: home`; the home button is `{"t":"key","name":"home"}`),
+so the apps opened on top of each other and the stores never held the
+go-home animation.
+
+Two more seeded runs went wrong because the harness picked a leftover union
+directory instead of backboardd's task. They gave 1010 restarts each, which
+confirms the mixed case once more.
+
+#### Where the first-use lag is
+
+The complaint, reproduced: after a boot, opening Settings and going home is
+choppy, and it smooths out after a few rounds. Frames here come from the guest:
+a launchd job polls QuartzCore's exported `CARenderServerGetFrameCounter(0)`
+every 0.5 ms and logs each change. Lychee renders at 60 Hz (gaps cluster at
+14–17 ms). "On time" is a gap of 20 ms or less. Each window is the 3 s after
+`apps.launch` of Settings (open) or the home key (close), five rounds, starting
+about 14 s after the VM is up.
+
+| Window | Cold A on time (bb compiles, Settings compiles) | Cold B | backboardd seeded from cold B |
+| --- | --- | --- | --- |
+| open1 | 69.8% (29, 23) | 68.3% (31, 20 in open2) | 75.6% (0, 15) |
+| close1 | **36.1%** (57) | **43.6%** (61) | **38.1%** (0) |
+| open2 | 76.1% (19) | 51.1% (20) | 81.6% (0) |
+| close2 | 80.0% (2) | 73.3% (1) | 74.4% (1) |
+| open3–5 | 83–86% | 78–87% | 80–86% |
+| close3–5 | 79–84% | 69–77% | 70–78% |
+
+Seeding backboardd's host task removed every **host** compile, and the first
+go-home was still as choppy (38%). There is a second compile stage, in the
+guest, and that is where the remaining first-use cost sits.
+
+#### The guest's own shader cache is thrown away at every boot
+
+Per round, on a cold boot (guest `processes.list` CPU at each window edge, host
+`proc_pid_rusage` of the VM service and the GPU tasks): the first go-home differs
+from later ones in one way only. The **guest's** `MTLCompilerService` takes
+0.41 s of CPU there (0.49 s in open1, 0.15 s in open2, then nothing), while
+SpringBoard and backboardd use the same CPU in every round. Host disk reads of
+`Disk.img` are negligible. Its log (`logs.syslog` for `MTLCompilerService`)
+shows the work is all for backboardd: over three rounds, 71
+`MTLSpecializeFunctionToArchive` requests (820 ms) and 90 `MTLBuildFunctions`
+(189 ms), on every boot.
+
+Why the guest compiles at all, and why it starts over at each boot:
+
+- CoreAnimation normally renders from precompiled pipelines in
+ `MTLBinaryArchive`s. On the paravirtual GPU, backboardd logs `Precompiled
+ pipelines disabled on unsupported hardware.`, so every pipeline is built at
+ run time, on its render thread.
+- backboardd does keep a Metal cache. `StartWindowServer` calls
+ `MTLSetShaderCachePath` with its system container's Caches
+ (`/private/var/containers/Data/System/<uuid>/Library/Caches`, holding
+ `functions.{list,data}` and `32023/libraries.*`). Within one boot it works: a
+ backboardd killed and relaunched compiles nothing.
+- Across a boot it does not. The cache key is constant: the driver's
+ `-[AppleParavirtDevice setupCompiler]` passes `cacheUUID` = SHA-256 of its
+ own build date, and Metal mixes in only its build stamp. But
+ `libCoreFSCache.dylib` writes `kern.bootsessionuuid` into the head of
+ `functions.list` (bytes 4–39, after the magic `45 36 27 18`). At open it
+ resets a cache stamped by another boot. Seen directly: the header went from
+ `96E73E64-…` to `30366BEF-…` with the boot session, and `functions.list`
+ from 19,372 bytes to 1,004. A clean `system.shutdown` changes nothing.
+ Every guest Metal cache follows the same rule, SpringBoard's and the apps'
+ (`/var/mobile/Library/Caches/<bundle id>/com.apple.metal`) included.
+- `libCoreFSCache` reads `FS_CACHE_REUSE_ON_REBOOT`. With it set, a cache from
+ another boot is kept. Verified without rebooting: write a foreign UUID into
+ the header and relaunch backboardd. Without the variable the cache resets
+ (19,260 to 5,932 bytes). With it set through `launchd.setenv`, nothing
+ changes (19,148 bytes, foreign header kept) and backboardd compiles 2
+ functions in the guest instead of 92.
+
+Effect on the first go-home, five Settings rounds after a backboardd relaunch
+with a foreign UUID in its cache (a stand-in for a boot):
+
+| Guest cache | Host cache for backboardd's new task | Runs | close1 on time | Guest compiles for backboardd |
+| --- | --- | --- | --- | --- |
+| reset (today) | cold | 3 | 50.9 / 50.0 / 51.9% | 92–93 |
+| reused | cold (about 120 host compiles) | 2 | 56.4 / 56.9% | 2–3 |
+| reused | seeded with its own files | 2 | 65.3 / 71.4% | 0–2 |
+
+Later go-homes run at about 78–83% on time in every mode, and no run had a GPU
+restart. Fixing both caches makes the first go-home better than any cold one,
+and it is the only combination that does. It is not yet as smooth as a warm
+one. Settings' own first open still compiles about 20 functions on the host.
+
+What setting the variable at boot takes:
+
+- iOS launchd ignores `/private/var/db/com.apple.xpc.launchd/config/system.plist`
+ `EnvironmentVariables` (tried: not applied, cache reset). `launchd.setenv`
+ lasts only until the next boot.
+- So the variable comes from SystemHook (`VPhoneGuestComponents/SystemHook`),
+ which is inserted into every spawn. Its constructor calls
+ `setenv("FS_CACHE_REUSE_ON_REBOOT", "1", 0)` first, before the xpcproxy,
+ `DISABLE_TWEAKS` and per-daemon early returns, and before any Metal code in
+ the process runs. It does so only while `/usr/lib/vphone-metal-cache-reuse`
+ exists. That marker is the patch `system-systemhook-cfw-metal_cache_reuse`
+ (Guest System set, on in `standard`, off for Apple TV): `cfw install` and
+ `cfw update-environment` write it when the patch is selected and remove it
+ when it is not. A SystemHook without the marker behaves as before.
+- The host half is the backboardd-only seed above, with the same caveat: it
+ relies on backboardd's task being the first one created. It is not part of
+ this patch.
+
+#### Real reboots with the patch (2026-10-19)
+
+`Lychee` again, now on a local 2.10.1 build with the patch. Each run is a real
+reboot: vphoned `system.shutdown`, then `vm start`, unlock, 10 s, then five
+Settings rounds measured as above (guest `CARenderServerGetFrameCounter`
+probe, 3 s windows, on time = gap of 20 ms or less). Guest compiles are the
+`Compilation SUCCESS (ParentProcessName=backboardd…` lines in `logs.syslog` for
+`MTLCompilerService` over the rounds. The header is bytes 4–39 of backboardd's
+`functions.list` in its system container. The host cache was cold in every
+run. GPU restarts are the `Trying to restart GPU` lines in that boot's
+`Lychee.log`.
+
+| Run | Bundle | Header after boot | `functions.list` before shutdown → after boot | backboardd guest compiles | GPU restarts | close1 on time | close2–5 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| base1 | 2.10.1 | new | 10,356 → 10,804 | 142 | 0 | 30.4% | 67–90% |
+| base2 | 2.10.1 | new | 19,372 → 10,692 | 146 | 0 | 31.7% | 66–86% |
+| new1 | patched | kept | 6,156 → 8,844 | 159 | 0 | 31.8% | 62–93% |
+| new2 | patched | kept | 19,204 → 19,316 | **0** | 0 | **43.9%** | 67–90% |
+| new3 | patched | kept | 19,316 → 19,316 | **0** | 0 | **37.3%** | 63–89% |
+
+- The cache now outlives a reboot: the header stays `8A5597B7-…` through three
+ boots and the file keeps its size, where every unpatched boot writes a new
+ boot UUID and starts again from about 10 KB.
+- new1 compiled as much as a cold boot because the boot before it was the
+ first with the variable and did no rounds, so its cache held 6 KB. From then
+ on (new2, new3) backboardd compiles nothing in the guest during the rounds,
+ and `MTLCompilerService` logs nothing at all.
+- The first go-home rises from about 31% to 37–44% on time. That is less than
+ the 51% → 56% the fake-boot stand-in predicted for the guest cache alone
+ (from a lower starting point here: a real boot has more going on in its first
+ minute than a relaunched backboardd). Later rounds are unchanged. The rest
+ of the first go-home is the host cache, which still recompiles at every boot.
+- Installing it here: Lychee had no restore tree for `cfw install`, and
+ `cfw update-environment` refused to run with less than 50 GiB free on the
+ volume (17 GiB). The new SystemHook reached the guest through vphoned's live
+ environment sync at `vm start`, and the marker was written with vphoned
+ `files.write`, i.e. the bytes the installer writes, not the installer itself.
+ The installer step is unchanged code in the same shape as the persona-lookup
+ marker next to it, and is not exercised by this run.
+
+#### Verdict
+
+- Per-process host seeding is safe in every run made: eleven with Camera or the
+ Settings loop, three of them with all eleven apps.
+- Neither cache alone fixes the first-use lag. The guest's Metal cache, reset at
+ every boot through `kern.bootsessionuuid`, is half of it. The host's per-task
+ cache, emptied with every task, is the other half. With both kept, the first
+ go-home goes from about 51% to 65–71% on time.
+- The guest half is an environment variable that Apple's own library honours,
+ and it reaches every process. It ships as
+ `system-systemhook-cfw-metal_cache_reuse`. On real reboots it keeps the
+ guest cache and removes every guest compile, taking the first go-home from
+ about 31% to 37–44%. The host half rests on the first-task assumption
+ described above and does not ship.
+
+
+The tools for these runs were scratch code outside the repo: a cache dumper, an
+ID rewriter, the guest frame-counter job (C, built with `xcrun -sdk iphoneos
+clang`) and zsh drivers. The method to repeat: watch the guest log for `Trying
+to restart GPU` and capture backboardd's syslog while Camera launches. A result
+without the restart count is worthless, and so is one that stops before Camera.
+
## Heap Textures Have No CPU Layout
On the iPadOS 26.6.2 iPad Pro guest (cloudOS 26.4 driver, `standard` preset),
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
index accf2f3f..c72227f4 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
@@ -21,6 +21,8 @@ public enum FirmwareGuestSystemPatchSet {
public static let installCoordinationPersona = "system-installcoordination_proxy-cfw-persona_lookup"
public static let installCoordinationPersonaMarker = "/usr/lib/vphone-installcoordination-persona-lookup"
+ public static let metalCacheReuse = "system-systemhook-cfw-metal_cache_reuse"
+ public static let metalCacheReuseMarker = "/usr/lib/vphone-metal-cache-reuse"
public static let gyroscope = "system-backboardd-cfw-gyroscope"
public static let attitude = "system-apps-cfw-attitude"
public static let arm64eX1DyldBootstrap = "system-dyld-boot-arm64e_x1_bootstrap"
@@ -261,6 +263,16 @@ public enum FirmwareGuestSystemPatchSet {
target: .guestFile(path: installCoordinationPersonaMarker),
applicability: ios27,
),
+ VPhonePatchDeclaration(
+ identifier: metalCacheReuse,
+ title: "Keep Metal shader caches",
+ summary: """
+ Has SystemHook set FS_CACHE_REUSE_ON_REBOOT=1 in every guest process, so Metal's \
+ shader caches, which libCoreFSCache stamps with the boot session, survive a reboot \
+ and backboardd does not rebuild its pipelines after every boot.
+ """,
+ target: .guestFile(path: metalCacheReuseMarker),
+ ),
// MARK: Guest Payload
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
index c30622c8..0545a54e 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
@@ -248,6 +248,7 @@ public enum FirmwarePatchSetCatalog {
"system-mobileactivationd-boot-should_hactivate",
FirmwareGuestSystemPatchSet.arm64eX1MountBootstrap,
"system-paravirt_gpu-cfw-heap_index_offset",
+ "system-systemhook-cfw-metal_cache_reuse",
"system-systemversion-cfw-build_version",
"system-virtiosound-cfw-hal_plugin",
"system-virtualaudio-cfw-microphone_graph_chains",
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index 0ba13a5c..00879028 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -1620,6 +1620,18 @@ struct VPhoneCustomFirmwareInstaller {
}
}
+ // SystemHook sets FS_CACHE_REUSE_ON_REBOOT while this marker exists.
+ let metalCachePatch = FirmwareGuestSystemPatchSet.metalCacheReuse
+ let metalCacheMarker = String(FirmwareGuestSystemPatchSet.metalCacheReuseMarker.dropFirst())
+ isolate([metalCachePatch]) {
+ if on(metalCachePatch) {
+ try system.writeFile(metalCacheMarker, contents: Data("1\n".utf8), mode: 0o644, owner: Self.guestOwner)
+ live.insert(metalCachePatch)
+ } else {
+ try system.removeItem(metalCacheMarker)
+ }
+ }
+
if !failures.isEmpty {
print("[!] \(failures.count) guest patch(es) failed and were left in their prior state: \(Set(failures).sorted().joined(separator: ", "))")
}
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
index ff580466..a59cab73 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
@@ -109,6 +109,7 @@
<string>system-mobileactivationd-boot-should_hactivate</string>
<string>system-mount-boot-arm64e_x1_bootstrap</string>
<string>system-paravirt_gpu-cfw-heap_index_offset</string>
+ <string>system-systemhook-cfw-metal_cache_reuse</string>
<string>system-systemversion-cfw-build_version</string>
<string>system-virtiosound-cfw-hal_plugin</string>
<string>system-virtualaudio-cfw-microphone_graph_chains</string>
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
index 1c09901d..7460860e 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
@@ -115,6 +115,7 @@
<string>system-mobileactivationd-boot-should_hactivate</string>
<string>system-mount-boot-arm64e_x1_bootstrap</string>
<string>system-paravirt_gpu-cfw-heap_index_offset</string>
+ <string>system-systemhook-cfw-metal_cache_reuse</string>
<string>system-systemversion-cfw-build_version</string>
<string>system-virtiosound-cfw-hal_plugin</string>
<string>system-virtualaudio-cfw-microphone_graph_chains</string>
diff --git a/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c b/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c
index 71fdc213..f6db5fdc 100644
--- a/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c
+++ b/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c
@@ -216,6 +216,14 @@ static void vpLoadLibrary(const char *kind, const char *library) {
// xpcproxy needs this bridge because launchd only spawns the proxy, not its target.
__attribute__((constructor)) static void vpLogProcess(void) {
+ // libCoreFSCache stamps every Metal shader cache with the boot session and
+ // resets it on the next boot unless this is set, so the paravirtual GPU's
+ // pipelines would be rebuilt after every boot. Set before any Metal code
+ // runs, in every process. See
+ // Research/Guest/gpu_acceleration.md.
+ if (access("/usr/lib/vphone-metal-cache-reuse", F_OK) == 0)
+ setenv("FS_CACHE_REUSE_ON_REBOOT", "1", 0);
+
char path[PATH_MAX];
uint32_t length = sizeof(path);
if (_NSGetExecutablePath(path, &length) != 0)