Run a virtual iPhone on an Apple Silicon Mac.
Swift
Persist per-machine host shader cache snapshots and honor resets
Arbifox516456dc2747
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.mdindex 54198466..9acb0c13 100644--- a/Research/0_binary_patch_comparison.md+++ b/Research/0_binary_patch_comparison.md@@ -761,7 +761,7 @@ Apple's ROM and this patch. See `Firmware/openavb_boot_rom.md`.| JB-29 | C | `patch_fpfs_scoped_vnode_open` | Sandbox MACF `mpo_vnode_check_open` (`ops[267]`) → per-process trampoline code cave | **iOS-27 random-respring fix (fpfs balloon).** JB-09 blanket-neuters `mpo_vnode_check_open` (`ops[267]` → allow) so processes can read `/var/jb`. But FileProvider's fpfs parent-walk (`fpfs_pkg_fd_lookup` → `openbyid` climbing via `getattrlistat(ATTR_CMN_PAROBJID)`) uses the stock check's EACCES at the domain-container boundary as its terminus; neutered, the walk climbs unbounded → `ResolverService` (FileProviderResolver) balloons to ~12 GB → `vm-compressor-space-shortage` jetsam → backboardd killed → **respring** (seen on 27b4/24A5390f). Fix keeps the global bypass and enforces the real check for the FileProvider daemons only: on 27, `ops[267]` is left un-neutered (removed from JB-09's blanket list — conditional `if !applyIOS27` in `patchSandboxHooksExtended`), then retargeted to a 20-insn code-cave trampoline that inlines `current_proc` (`mrs tpidr_el1` → `ldr [+0x3F0]` uthread → `ldr [+0x18]` proc), loads `p_comm` (`+0x56C`), compares the first 8 bytes to `"Resolver"`/`"fileprov"`, and on match `b`s to the real `vnode_check_open` (restores the terminus) else returns allow (`mov x0,#0 ; ret` → `/var/jb` reads + Sileo/TrollStore icons unaffected). Register-only (x8–x10), no frame/call (~18 insns/open). Struct offsets recovered via the VZ gdb stub on vphone600; cave bytes from the Keystone-backed `ARM64Encoder`, verified by Capstone round-trip; the `ops[267]` retarget preserves the auth-rebase high bits (same encoder family as JB-09). **VALIDATED on-device (2026-07-23, `17,3_27.0_24A5390f` + cloudOS 26.4, JB, `setup_machine` deploy): resprings stop; Sileo/TrollStoreLite icons render.** Backward-compat: a 26.5 base is unaffected (`ops[267]` still blanket-neutered there) — verified byte-identical kernelcache pre-vs-post (`cmp` clean, `sha256` unchanged). See `KernelJBPatchFpfsScopedOpen.swift`. | Y || JB-30 | B | `patchParavirtDisplayRefreshRate` (record `kernel-cfw-display_promotion`; introduced as `kernel-exp-display_refresh_120hz`, renamed when `standard` turned it on) | `AppleParavirtDisplay::createDisplayAttributes` (AppleParavirtGPUIOGPUFamily), the per-mode timing element call | **ProMotion: 120 Hz display timing (on in `standard` since 2026-10-09; it shipped opt-in from 2.4.2).** The host VM service builds its one `PGDisplayMode` with a constant 60.0 Hz and writes it into the display shared state page as a 16-byte entry (u16 width, u16 height, u32 refresh in 16.16 Hz, flags); the guest turns each entry into an IOAV timing element with `ldurh w1,[xN,#-8]; ldurh w2,[xN,#-6]; ldur w3,[xN,#-4]; bl`. The `ldur w3` becomes `movz w3,#120,lsl #16`. Anchor: the `createDisplayAttributes` logger cstring (all refs in one function) + the only w1/w2/w3 load triple off one base at -8/-6/-4 ahead of a call. Gated by `KernelCustomFirmwarePatcher.applyProMotion`, set from the plan. See `Research/Guest/display_refresh_rate.md`. | Y || JB-31 | C | `patchParavirtUserClientsNarrow` (records `kernel-cfw-paravirt_user_clients.redirect` / `.cave`; introduced as `kernel-exp-paravirt_user_clients`, renamed when `standard` turned it on) | Same IOUserClient Sandbox gate; the deny block's `ldr Xt,[sp,#imm]` eight bytes before the fail-log `adrp` | **Paravirtual device access on a 26.x / 18.x base (on in `standard` since 2026-10-04; it shipped opt-in).** Narrow replacement for the broad gate-off: at the deny point the class-name C string is already in x0, so a code-cave trampoline reads its first eight bytes and branches to the gate's NotPermitted allow target only for `ApplePar` / `AppleVid` / `AppleVir` / `IOSurfac` (AppleParavirt\*, AppleVideoToolboxParavirt\*, AppleVirtIO\*, IOSurfaceAcceleratorParavirtClient); every other denial runs the displaced `ldr` and falls through to the real deny. Fixes `MTLCreateSystemDefaultDevice()` nil in daemons/CLI and the VideoToolbox/ANE/IOSurface denials (upstream issue #22) without opening the rest. Cave words verified by clang/as + capstone round-trip; the two `b` words via `ARM64Encoder`. Gated by `KernelCustomFirmwarePatcher.applyParavirtUserClients`, set from the plan when `applyIOS27` is false. See `Research/Guest/gpu_acceleration.md`. | Y |-| JB-32 | B/C | `patchParavirtTask3Version` (`kernel-exp-paravirt_gpu_task3.request`, `.features`, `.identity_hook`, `.identity_code`) | `setupVersion`; task initializer's `Failed to create Page Table Lock`; superclass task retain/store; XNU flow-divert CDHASH log and proc/task inverse getter | **Persistent per-executable host shader caches through Task3, opt-in.** Phase 1 (2026-10-19) requests binary version 252 while computing guest features from the original 245. Phase 2 (2026-10-20) writes the owning executable's 20-byte code-signing cdhash at TaskRoot+0x28 before descriptor preparation and task registration. The host uses `task-<40 hex>` and retains that directory. A missing proc/hash leaves twenty zero bytes and preserves the ephemeral fallback. The owning task field is recovered from the superclass initializer, not guessed or taken from current_proc. Kernel helpers are found through source-backed semantic call flow (`cs_get_cdhash`) and the dynamically recovered proc_struct_size global (`get_bsdtask_info`); no task/proc layout offsets or kernel VAs are hardcoded. The trampoline preserves x0–x18, LR and SP, copies exactly 20 bytes and replays the displaced descriptor load. All four sites must resolve before any is emitted; failure aborts an opted-in install. Replacements use ARM64Encoder; new encoders have Keystone 0.9.2 parity tests. Gated by applyParavirtTask3 and blocked in shipped presets. Static fixture, missing-anchor and register-clobber execution tests pass. Lychee on macOS 27.0.1 / cloudOS 26.4 / iOS 27.0.1 negotiated 252 across three full boots, retained the same nine executable keys, and passed Camera with zero GPU resets. Host GPU compilation events fell 631 → 17 → 12; the Settings windows fell 121 → 5 → 0. Animation stutter remains. Measurements, cdhash checks and crash analysis are in `Research/Guest/gpu_acceleration.md`. Older hosts remain untested. | Y |+| JB-32 | B/C | `patchParavirtTask3Version` (`kernel-exp-paravirt_gpu_task3.request`, `.features`, `.identity_hook`, `.identity_code`) | `setupVersion`; task initializer's `Failed to create Page Table Lock`; superclass task retain/store; XNU flow-divert CDHASH log and proc/task inverse getter | **Persistent per-executable host shader caches through Task3, opt-in.** Phase 1 (2026-10-19) requests binary version 252 while computing guest features from the original 245. Phase 2 (2026-10-20) writes the owning executable's 20-byte code-signing cdhash at TaskRoot+0x28 before descriptor preparation and task registration. The host uses `task-<40 hex>` and retains that directory. A missing proc/hash leaves twenty zero bytes and preserves the ephemeral fallback. The owning task field is recovered from the superclass initializer, not guessed or taken from current_proc. Kernel helpers are found through source-backed semantic call flow (`cs_get_cdhash`) and the dynamically recovered proc_struct_size global (`get_bsdtask_info`); no task/proc layout offsets or kernel VAs are hardcoded. The trampoline preserves x0–x18, LR and SP, copies exactly 20 bytes and replays the displaced descriptor load. All four sites must resolve before any is emitted; failure aborts an opted-in install. Replacements use ARM64Encoder; new encoders have Keystone 0.9.2 parity tests. Gated by applyParavirtTask3 and blocked in shipped presets. Static fixture, missing-anchor and register-clobber execution tests pass. Lychee on macOS 27.0.1 / cloudOS 26.4 / iOS 27.0.1 negotiated 252 across three full boots, retained the same nine executable keys, and passed Camera with zero GPU resets. Host GPU compilation events fell 631 → 17 → 12; the Settings windows fell 121 → 5 → 0. Frame-counter gaps do not establish visible animation stutter; the user reports smooth warmed animations. Measurements, cdhash checks and crash analysis are in `Research/Guest/gpu_acceleration.md`. Older hosts remain untested. | Y |### EXP-Only Kernel Methods (Reference List)@@ -3246,7 +3246,8 @@ 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 isrevertible. While the marker exists, SystemHook's constructor sets-`FS_CACHE_REUSE_ON_REBOOT=1` before anything else, so `libCoreFSCache` keeps+`FS_CACHE_REUSE_ON_REBOOT=1` before anything else unless the variable already+has an explicit value, so `libCoreFSCache` can keepeach Metal cache stamped by an earlier boot instead of resetting it. No systembinary, shared cache or kernel byte changes.@@ -3256,3 +3257,28 @@ boots, guest compiles for backboardd during five Settings rounds fall fromabout 145 to 0, no GPU restart, and the first go-home goes from about 31% to37–44% on time. Numbers and method: `Guest/gpu_acceleration.md`, "Real rebootswith the patch (2026-10-19)".++Host cache storage (2026-10-20): the launcher keeps a durable whole-directory+snapshot in `<machine>/ShaderCache`, seeds Apple's normal ECID working cache+before boot, and checkpoints after guest shutdown and again in the parent CLI+after vphone-vm exits. A symlink experiment was rejected after sandbox denials+and repeated compilation; the working root remains a real directory. This adds+no binary patch and changes no Task3 key bytes. Index/data pairs stay together;+copies are staged before whole-directory replacement and never merged across+independent trees. Permissions use the shared symlink-safe host-file walker.+The final bundle passed two Settings/Camera boot cycles with zero host GPU task+compiles and zero GPU resets, including restoration after moving aside Apple's+working directory. All 14 cache file checksums matched after each shutdown.+Migration checks and runtime evidence are in `Guest/gpu_acceleration.md`,+"Cache location and migration".++Deletion correction: a missing machine snapshot now clears an already managed+host working copy on the next boot, instead of importing it again. A shutdown+checkpoint does not recreate a deleted snapshot. The working copy's existing+`.host-ecid` marker distinguishes this reset from the first-use import. This+resets host caches only; guest caches inside `Disk.img` remain. Frame-counter+gaps in the earlier measurements do not independently demonstrate visible+animation stutter; the user reports smooth warmed animations.+The corrected bundle's reset/reboot test recorded 607 then seven host GPU task+compilation events (129 then one during Settings), with zero GPU resets on both+boots. Fourteen cache/permission tests and the complete bundle build pass.diff --git a/Research/Guest/gpu_acceleration.md b/Research/Guest/gpu_acceleration.mdindex 71fb6b93..dbd93027 100644--- a/Research/Guest/gpu_acceleration.md+++ b/Research/Guest/gpu_acceleration.md@@ -184,10 +184,12 @@ time in the same boot.### Why the cache misses-Virtualization gives ParavirtualizedGraphics a cache directory per VM,+By default, Virtualization gives ParavirtualizedGraphics a cache directory per VM,`$DARWIN_USER_CACHE_DIR/com.apple.paravirtualizedgraphics-<number>`, and eachhost GPU task keeps its Metal function cache in a `task-<key>` directory under-it. `-[PGRemoteTask calculateCachePathAndExtension:taskRoot:]` picks the key:+it. The vphone launcher now keeps a durable copy in the machine folder+(see "Cache location and migration" below). The historical observations here+predate that relocation. `-[PGRemoteTask calculateCachePathAndExtension:taskRoot:]` picks the key:- when the device's feature byte `0x36` is set, it reads 60 bytes of the guest'stask root page and takes the 20 at offset `0x28`; if they are not all zero,@@ -688,8 +690,10 @@ inside each open/home command window, are not animation FPS, and are only asmall repeated-workload comparison on this machine. The cold host run alreadyhad the guest cache-reuse change; this is not an unpatched-versus-patched A/B.The host compilation reduction and key retention directly establish cache-reuse. The remaining frame gaps establish that **persistent caches do not-eliminate all animation lag**. Scheduling, VM rendering and other work remain.+reuse. The frame gaps do not establish visible animation stutter: the probe+does not separate animation frames from idle intervals or command pauses.+The user reports smooth warmed animations. Quantifying visible hitches would+require an animation-specific measurement; these samples cannot settle that.No new crash reports appeared during the first two application-test windows.The third produced a Passbook widget `SIGTRAP`: `_assertionFailure` →@@ -704,6 +708,103 @@ installation bundle with the lowered disk check was removed from Launchpad.Raw runtime captures and the Swift report driver are local scratch artifacts under`/tmp/vphone-shader-cache-hopper/`, not shipped components.+#### Cache location and migration, 2026-10-20++The durable host cache now lives at `<machine>/ShaderCache`. For Lychee this is+`/Users/arbifox/.vphone/machines/Lychee/ShaderCache`. Guest Metal caches remain+inside the guest filesystem in `Disk.img`; this change relocates the host+ParavirtualizedGraphics cache only.++An initial symlink experiment preserved every file checksum but failed runtime+validation: the Virtualization service logged sandbox metadata denials for the+redirected path, and GPU task compilation rose to 1,525 events without updating+the relocated files. Symlinks are therefore not the shipped storage design.++Before creating the VM, `VPhoneShaderCache.prepare` uses the machine ECID and+the invoking user's Darwin cache directory to locate Apple's required working+directory, `com.apple.paravirtualizedgraphics-<decimal ECID>`. On first use it+copies an existing unmanaged directory intact into `ShaderCache`. It seeds a real+working directory from that durable snapshot before each boot. The VM delegate+checkpoints the working copy at guest shutdown; the parent CLI checkpoints+again after vphone-vm exits, including device teardown writes. A `.host-ecid`+file inside the snapshot lets the unentitled CLI find only that ECID's working+directory, without a private Virtualization API or arbitrary stored host path.++Each transfer copies to a sibling staging directory, then replaces the entire+destination. Independently warmed `functions.list`/`functions.data` files are+never merged. Failed copies leave the prior snapshot intact. Permissions use+the shared host-file walker without following symlinks. Both roots must be real+directories. The local experimental alias was removed during validation;+production setup rejects aliases. An ECID lock stays held for the entire VM+session so concurrent launches cannot replace an active working cache.++Tests cover paired file preservation, checkpointing, repeated setup, a renamed+machine, host cache eviction/reseeding, whole-snapshot replacement, foreign+aliases, checkpoint failure, symlink rejection, concurrent launch exclusion and+hard-linked lock rejection. Initial relocation validation passed twelve+cache/permission tests and 61 targeted Task3, encoder and patch-selection tests,+plus the `VPhone` workspace build and bundle admission. The original 50 GiB+installer guard and shipped Task3 preset defaults are unchanged.++All 14 existing Lychee `functions.list`/`functions.data` checksums matched the+initial move. With relocation bundle `2.10.1-local.12d3a7da`, two full boot/shutdown+cycles each passed five Settings rounds and Camera's foreground check. Each+recorded zero host GPU task compiles, zero guest compiles during the 55-second+collection, eight fixed host display compiles, eleven retained executable keys+and zero GPU resets. After the first shutdown, the framework working directory+was moved aside; the second boot restored it exclusively from the machine+snapshot and retained all eleven keys. After each shutdown, all 14 paired file+checksums matched between the working and durable trees. Neither run logged a+checkpoint error.++The first application-test window produced no new crash report. The second+produced one Passbook widget SIGTRAP: its exception and first eight fault frames+exactly match the previously documented FinanceKit assertion failure. A brief+third boot retrieved that report; Lychee was shut down afterward. These are+cache-location health checks, not animation smoothness benchmarks.+The durable snapshot is current after shutdown; changes made during a running+session reside in Apple's working directory until checkpointed. Killing both+VM and CLI can lose that session's new entries.++The unfinished Claude handoff and its probe directory are preserved outside+the checkout at `/Users/arbifox/.vphone/research/shader-cache-2026-10-20/`.+They are research artifacts, not bundle inputs or proposed PR files.+The `validation` subdirectory holds the relocation run captures, compilation+report, checksum manifests and build/test logs.++Deletion semantics correction: the first implementation imported the surviving+working copy whenever `ShaderCache` was missing, so deleting the durable folder+could silently restore the warmed host cache. A `.host-ecid` marker in the+working copy now distinguishes a managed cache from a first-use import. When+`ShaderCache` is missing and the working copy is managed, preparation starts+with an empty snapshot and replaces the working copy. Checkpointing also+respects a missing machine snapshot instead of recreating it at shutdown.+To regenerate the host cache, stop the VM, delete `<machine>/ShaderCache`,+then start the VM with the corrected bundle. Deleting it while the VM is+running does not evict shaders already loaded into memory; the reset takes+effect at the next boot. Guest Metal caches inside `Disk.img` are a separate+layer and are not cleared by this host-only reset.++The correction passes fourteen cache/permission tests, including deleting the+machine snapshot while the VM session is active and deleting it between boots.+The full bundle build and admission pass. In bundle+`2.10.1-local.ee7a374e`, the original machine snapshot was moved to an external+research backup while leaving Apple's managed working copy intact. The next+boot began with only `.host-ecid` in the machine snapshot and regenerated its+host caches: 607 GPU task compile events overall, 129 during five Settings+rounds. The following boot retained all seven newly generated task keys and+recorded seven GPU task compile events overall, one during Settings. Both had+zero guest compiles in the 55-second collection, eight fixed display compiles,+successful Settings/Camera foreground checks and zero GPU resets. All ten+paired cache file checksums matched after the second shutdown. The reset clears+the host layer; it does not promise visible lag or a fully cold guest layer.+The reset test window had no new crash reports. The warm window had one+Passbook widget report with the same exception and first eight fault frames as+the preexisting FinanceKit failure; a brief diagnostic boot retrieved it and+the VM was shut down again.+Captures and build/test logs are preserved beside the earlier validation under+`reset-validation`.+## Heap Textures Have No CPU LayoutOn 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.swiftindex c72227f4..22cac1ff 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift@@ -267,9 +267,9 @@ public enum FirmwareGuestSystemPatchSet {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.+ Has SystemHook request FS_CACHE_REUSE_ON_REBOOT=1 at process startup, \+ allowing Metal's guest shader caches to survive a reboot and reducing \+ repeated shader compilation. An explicit environment setting takes precedence.""",target: .guestFile(path: metalCacheReuseMarker),),diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swiftindex fa8a7328..ecbe1693 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift@@ -78,9 +78,9 @@ public enum FirmwarePatchSetCatalog {/// `Research/Guest/display_refresh_rate.md`.public static let proMotionPatch = "kernel-cfw-display_promotion"- /// Paravirtual GPU binary version 252 (Task3) with the guest keeping its own- /// features: lets the host key each task's shader cache by guest-supplied- /// bytes. Off unless a VM selects it. See+ /// Paravirtual GPU Task3: keep the guest's features and supply each owning+ /// executable's cdhash so the host retains separate shader caches across+ /// boots. Off unless a VM selects it. See/// `Research/Guest/gpu_acceleration.md`.public static let paravirtTask3Patch = "kernel-exp-paravirt_gpu_task3"diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineLaunchCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineLaunchCommand.swiftindex 5439bee9..e5172f94 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineLaunchCommand.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineLaunchCommand.swift@@ -77,6 +77,10 @@ struct VPhoneVirtualMachineLaunchCommand: ParsableCommand {// `vm launch` always streams the guest serial console (inherits our// stdio); it is intentionally not gated on verbosity. run() also hands// the terminal to the child, which is what lets Ctrl-C reach the guest.+ defer {+ do { try VPhoneShaderCache.checkpoint(machineDirectory: bundle.url) }+ catch { fputs("warning: could not save shader cache: \(error)\n", stderr) }+ }throw try ExitCode(launcher.run(args, cwd: bundle.url))}}diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swiftindex 6f13a16e..b9fb9191 100644--- a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift@@ -15,6 +15,7 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {let syncsHostLocation: Bool/// ECID hex string resolved from machineIdentifier (e.g. "0x0012345678ABCDEF").let ecidHex: String?+ private nonisolated let shaderCache: VPhoneShaderCache.Session?/// Read handle for VM serial output.private var serialOutputReadHandle: FileHandle?private var serialInputSource: DispatchSourceRead?@@ -50,6 +51,7 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {}private struct DeviceIdentity {+ let ecid: UInt64let cpidHex: Stringlet ecidHex: Stringlet udid: String@@ -102,8 +104,13 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {if let identity = Self.resolveDeviceIdentity(machineIdentifier: machineIdentifier) {ecidHex = identity.ecidHex- print("[vphone] ECID: \(ecidHex!)")+ print("[vphone] ECID: \(identity.ecidHex)")print("[vphone] Predicted UDID: \(identity.udid)")+ let shaderCache = try VPhoneShaderCache.prepare(+ machineDirectory: options.configURL.deletingLastPathComponent(), ecid: identity.ecid,+ )+ self.shaderCache = shaderCache+ print("[vphone] Shader cache: \(shaderCache.cacheURL.path)")let outputURL = options.configURL.deletingLastPathComponent().appendingPathComponent("udid-prediction.txt",)@@ -116,6 +123,7 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {}} else {ecidHex = nil+ shaderCache = nilprint("[vphone] Warning: failed to resolve ECID from machineIdentifier")}@@ -320,6 +328,7 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {/// Cancel serial forwarding before another VM takes the same host stdin.func stopHostDevices() {+ finishShaderCache()serialInputSource?.cancel()serialInputSource = nilserialOutputReadHandle?.readabilityHandler = nil@@ -360,7 +369,7 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {let cpidHex = String(format: "%08X", VPhoneHardware.udidChipID)let ecidHex = String(format: "%016llX", ecidValue)let udid = "\(cpidHex)-\(ecidHex)"- return DeviceIdentity(cpidHex: cpidHex, ecidHex: ecidHex, udid: udid)+ return DeviceIdentity(ecid: ecidValue, cpidHex: cpidHex, ecidHex: ecidHex, udid: udid)}private static func writeUDIDPrediction(identity: DeviceIdentity, to outputURL: URL) throws {@@ -504,15 +513,23 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {// MARK: - Delegatenonisolated func guestDidStop(_: VZVirtualMachine) {+ finishShaderCache()print("[vphone] Guest stopped")exit(EXIT_SUCCESS)}nonisolated func virtualMachine(_: VZVirtualMachine, didStopWithError error: Error) {+ finishShaderCache()print("[vphone] Stopped with error: \(error)")exit(EXIT_FAILURE)}+ private nonisolated func finishShaderCache() {+ guard let shaderCache else { return }+ do { try shaderCache.checkpoint() }+ catch { print("[vphone] Cannot save shader cache: \(error)") }+ }+nonisolated func virtualMachine(_: VZVirtualMachine,networkDevice _: VZNetworkDevice,diff --git a/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c b/VPhoneGuestComponents/SystemHook/SystemHook-vphone.cindex f6db5fdc..8435a723 100644--- a/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c+++ b/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c@@ -216,13 +216,12 @@ 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)+ // Request cross-boot reuse at constructor entry: libCoreFSCache normally+ // invalidates Metal caches when the boot session changes. Preserve an+ // explicit environment setting. 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);diff --git a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneShaderCache.swift b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneShaderCache.swiftnew file mode 100644index 00000000..de25efc1--- /dev/null+++ b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneShaderCache.swift@@ -0,0 +1,170 @@+import Darwin+import Foundation++/// Durable host GPU cache in the machine folder. Apple's sandboxed services+/// use a working copy in their Darwin cache directory; no paths are redirected.+public enum VPhoneShaderCache {+ private static let ecidFile = ".host-ecid"++ /// Hold the ECID lock until device teardown. A second launch must never+ /// replace the working directory while an existing VM is using it.+ public final class Session: Sendable {+ public let cacheURL: URL+ private let workingURL: URL+ private let descriptor: Int32++ fileprivate init(cacheURL: URL, workingURL: URL, descriptor: Int32) {+ self.cacheURL = cacheURL+ self.workingURL = workingURL+ self.descriptor = descriptor+ }++ public func checkpoint() throws {+ try VPhoneShaderCache.checkpoint(machineDirectory: cacheURL.deletingLastPathComponent(), frameworkCache: workingURL)+ }++ deinit { close(descriptor) }+ }++ public static func prepare(machineDirectory: URL, ecid: UInt64) throws -> Session {+ try session(machineDirectory: machineDirectory, ecid: ecid, frameworkCache: frameworkCache(ecid: ecid))+ }++ static func session(machineDirectory: URL, ecid: UInt64, frameworkCache: URL) throws -> Session {+ let descriptor = try lock(frameworkCache)+ do {+ let cache = try prepare(machineDirectory: machineDirectory, ecid: ecid, frameworkCache: frameworkCache)+ return Session(cacheURL: cache, workingURL: frameworkCache, descriptor: descriptor)+ } catch {+ close(descriptor)+ throw error+ }+ }++ /// Also called by the parent CLI after vphone-vm exits, so its final copy+ /// includes writes completed while Virtualization tears down the devices.+ public static func checkpoint(machineDirectory: URL) throws {+ let cache = machineDirectory.appendingPathComponent("ShaderCache", isDirectory: true)+ guard try kind(cache) != nil else { return }+ guard try kind(cache) == S_IFDIR,+ let text = try? String(contentsOf: cache.appendingPathComponent(ecidFile), encoding: .utf8),+ let ecid = UInt64(text.trimmingCharacters(in: .whitespacesAndNewlines))+ else { throw invalid("ShaderCache has no valid host ECID", at: cache) }+ let working = try frameworkCache(ecid: ecid)+ let descriptor = try lock(working)+ defer { close(descriptor) }+ try checkpoint(machineDirectory: machineDirectory, frameworkCache: working)+ }++ @discardableResult+ static func prepare(machineDirectory: URL, ecid: UInt64, frameworkCache: URL) throws -> URL {+ let fm = FileManager.default+ let cache = machineDirectory.appendingPathComponent("ShaderCache", isDirectory: true)+ let cacheKind = try kind(cache)+ guard cacheKind == nil || cacheKind == S_IFDIR else {+ throw invalid("ShaderCache must be a real directory", at: cache)+ }+ let hostKind = try kind(frameworkCache)+ guard hostKind == nil || hostKind == S_IFDIR else {+ throw invalid("The framework cache must be a real directory", at: frameworkCache)+ }+ if cacheKind == nil {+ // Import an unmanaged cache once. A managed working copy already+ // has this marker; a missing machine snapshot then means reset.+ let managed = try kind(frameworkCache.appendingPathComponent(ecidFile)) != nil+ if hostKind == S_IFDIR && !managed {+ try snapshot(from: frameworkCache, to: cache)+ } else {+ try fm.createDirectory(at: cache, withIntermediateDirectories: false)+ }+ }+ // Keep whole snapshots together. Never merge independently warmed+ // functions.list/functions.data files or rewrite per-program identities.+ try Data("\(ecid)\n".utf8).write(to: cache.appendingPathComponent(ecidFile), options: .atomic)+ try snapshot(from: cache, to: frameworkCache)+ try VPhoneHostFilePermissions.makeAccessible(at: cache)+ return cache+ }++ static func checkpoint(machineDirectory: URL, frameworkCache: URL) throws {+ let cache = machineDirectory.appendingPathComponent("ShaderCache", isDirectory: true)+ // Respect deletion during a running session. The next prepare clears+ // the surviving managed working copy instead of importing it again.+ guard try kind(cache) != nil else { return }+ guard try kind(frameworkCache) != nil else { return }+ try snapshot(from: frameworkCache, to: cache)+ }++ /// Copy to a sibling first, then replace the complete directory. A failed+ /// copy leaves the prior snapshot intact. copyItem preserves symlinks as+ /// links; the permissions walker never follows them.+ private static func snapshot(from source: URL, to destination: URL) throws {+ let fm = FileManager.default+ guard try kind(source) == S_IFDIR else {+ throw invalid("Shader cache snapshot source must be a real directory", at: source)+ }+ let destinationKind = try kind(destination)+ guard destinationKind == nil || destinationKind == S_IFDIR else {+ throw invalid("Shader cache snapshot destination must be a real directory", at: destination)+ }+ let pending = destination.deletingLastPathComponent().appendingPathComponent(".ShaderCache-\(UUID().uuidString)")+ defer { try? fm.removeItem(at: pending) }+ try fm.copyItem(at: source, to: pending)+ try VPhoneHostFilePermissions.makeAccessible(at: pending)+ if destinationKind == nil {+ try fm.moveItem(at: pending, to: destination)+ } else {+ _ = try fm.replaceItemAt(destination, withItemAt: pending, options: .usingNewMetadataOnly)+ }+ }++ private static func frameworkCache(ecid: UInt64) throws -> URL {+ let length = confstr(_CS_DARWIN_USER_CACHE_DIR, nil, 0)+ guard length > 0 else { throw POSIXError(.ENOENT) }+ var path = [CChar](repeating: 0, count: length)+ guard confstr(_CS_DARWIN_USER_CACHE_DIR, &path, length) == length else { throw POSIXError(.ENOENT) }+ let directory = String(decoding: path.dropLast().map { UInt8(bitPattern: $0) }, as: UTF8.self)+ return URL(fileURLWithPath: directory, isDirectory: true)+ .appendingPathComponent("com.apple.paravirtualizedgraphics-\(ecid)", isDirectory: true)+ }++ private static func lock(_ working: URL) throws -> Int32 {+ let url = working.appendingPathExtension("vphone-lock")+ let descriptor = open(url.path, O_RDWR | O_CREAT | O_NOFOLLOW | O_NONBLOCK | O_CLOEXEC, 0o777)+ guard descriptor >= 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) }+ var metadata = stat()+ guard fstat(descriptor, &metadata) == 0,+ metadata.st_mode & S_IFMT == S_IFREG, metadata.st_nlink == 1+ else {+ close(descriptor)+ throw invalid("Shader cache lock must be a regular file with one link", at: url)+ }+ guard flock(descriptor, LOCK_EX | LOCK_NB) == 0 else {+ let error = CocoaError(.fileLocking, userInfo: [+ NSLocalizedDescriptionKey: "Shader cache is in use; stop the existing VM before launching it again",+ NSFilePathErrorKey: url.path,+ ])+ close(descriptor)+ throw error+ }+ guard fchmod(descriptor, 0o777) == 0 else {+ let error = POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)+ close(descriptor)+ throw error+ }+ return descriptor+ }++ private static func kind(_ url: URL) throws -> mode_t? {+ var metadata = stat()+ guard lstat(url.path, &metadata) == 0 else {+ if errno == ENOENT { return nil }+ throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)+ }+ return metadata.st_mode & S_IFMT+ }++ private static func invalid(_ message: String, at url: URL) -> CocoaError {+ CocoaError(.fileWriteInvalidFileName, userInfo: [NSLocalizedDescriptionKey: message, NSFilePathErrorKey: url.path])+ }+}diff --git a/VPhoneKit/VPhoneCoreKitTests/VirtualMachine/ShaderCacheTests.swift b/VPhoneKit/VPhoneCoreKitTests/VirtualMachine/ShaderCacheTests.swiftnew file mode 100644index 00000000..919da8b9--- /dev/null+++ b/VPhoneKit/VPhoneCoreKitTests/VirtualMachine/ShaderCacheTests.swift@@ -0,0 +1,168 @@+import Darwin+import Foundation+import Testing+@testable import VPhoneCoreKit++struct ShaderCacheTests {+ private func withLayout(_ body: (URL, URL, URL) throws -> Void) throws {+ let root = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)+ let machine = root.appendingPathComponent("Lychee")+ let host = root.appendingPathComponent("HostCache")+ try FileManager.default.createDirectory(at: machine, withIntermediateDirectories: true)+ defer { try? FileManager.default.removeItem(at: root) }+ try body(machine, host, machine.appendingPathComponent("ShaderCache"))+ }++ private func prepare(_ machine: URL, _ host: URL) throws {+ try VPhoneShaderCache.prepare(machineDirectory: machine, ecid: 123, frameworkCache: host)+ }++ @Test("A running VM holds the ECID lock and a later launch can acquire it after exit")+ func concurrentLaunch() throws {+ try withLayout { machine, host, _ in+ var first: VPhoneShaderCache.Session? = try VPhoneShaderCache.session(machineDirectory: machine, ecid: 123, frameworkCache: host)+ #expect(first != nil)+ #expect(throws: CocoaError.self) {+ try VPhoneShaderCache.session(machineDirectory: machine, ecid: 123, frameworkCache: host)+ }+ try first?.checkpoint()+ first = nil+ let second = try VPhoneShaderCache.session(machineDirectory: machine, ecid: 123, frameworkCache: host)+ try second.checkpoint()+ }+ }++ @Test("Paired cache files survive migration, checkpoint and host cache eviction")+ func preservesCacheAcrossSessions() throws {+ try withLayout { machine, host, cache in+ let task = "task-0123456789012345678901234567890123456789/16777235_530"+ let old = host.appendingPathComponent(task)+ try FileManager.default.createDirectory(at: old, withIntermediateDirectories: true)+ for name in ["functions.list", "functions.data"] {+ try Data("old \(name)".utf8).write(to: old.appendingPathComponent(name))+ }+ try prepare(machine, host)+ for name in ["functions.list", "functions.data"] {+ #expect(try Data(contentsOf: cache.appendingPathComponent(task + "/" + name)) == Data("old \(name)".utf8))+ try Data("new \(name)".utf8).write(to: host.appendingPathComponent(task + "/" + name))+ }+ try VPhoneShaderCache.checkpoint(machineDirectory: machine, frameworkCache: host)+ try FileManager.default.removeItem(at: host)+ try prepare(machine, host)+ for name in ["functions.list", "functions.data"] {+ #expect(try Data(contentsOf: host.appendingPathComponent(task + "/" + name)) == Data("new \(name)".utf8))+ }+ var metadata = stat()+ #expect(lstat(cache.path, &metadata) == 0 && metadata.st_mode & S_IFMT == S_IFDIR)+ #expect(metadata.st_mode & 0o777 == 0o777)+ #expect(lstat(host.path, &metadata) == 0 && metadata.st_mode & S_IFMT == S_IFDIR)+ }+ }++ @Test("Deleting the machine snapshot clears an already managed working cache")+ func deletedSnapshotStartsCold() throws {+ try withLayout { machine, host, cache in+ try prepare(machine, host)+ try Data("compiled".utf8).write(to: host.appendingPathComponent("shader"))+ try VPhoneShaderCache.checkpoint(machineDirectory: machine, frameworkCache: host)+ try FileManager.default.removeItem(at: cache)+ try prepare(machine, host)+ #expect(!FileManager.default.fileExists(atPath: host.appendingPathComponent("shader").path))+ #expect(!FileManager.default.fileExists(atPath: cache.appendingPathComponent("shader").path))+ #expect(try String(contentsOf: host.appendingPathComponent(".host-ecid"), encoding: .utf8) == "123\n")+ }+ }++ @Test("Shutdown does not recreate a snapshot deleted during the session")+ func deletedSnapshotStaysDeleted() throws {+ try withLayout { machine, host, cache in+ let session = try VPhoneShaderCache.session(machineDirectory: machine, ecid: 123, frameworkCache: host)+ try Data("compiled".utf8).write(to: host.appendingPathComponent("shader"))+ try FileManager.default.removeItem(at: cache)+ try session.checkpoint()+ try VPhoneShaderCache.checkpoint(machineDirectory: machine)+ #expect(!FileManager.default.fileExists(atPath: cache.path))+ #expect(FileManager.default.fileExists(atPath: host.appendingPathComponent("shader").path))+ }+ }++ @Test("A hard-linked lock cannot widen an unrelated file's permissions")+ func hardLinkedLock() throws {+ try withLayout { machine, host, _ in+ let outside = machine.appendingPathComponent("outside")+ try Data("private".utf8).write(to: outside)+ #expect(chmod(outside.path, 0o600) == 0)+ #expect(link(outside.path, host.appendingPathExtension("vphone-lock").path) == 0)+ #expect(throws: CocoaError.self) {+ try VPhoneShaderCache.session(machineDirectory: machine, ecid: 123, frameworkCache: host)+ }+ var metadata = stat()+ #expect(lstat(outside.path, &metadata) == 0 && metadata.st_mode & 0o777 == 0o600)+ }+ }++ @Test("A moved machine reseeds its working directory without a path alias")+ func movedMachine() throws {+ try withLayout { machine, host, cache in+ try prepare(machine, host)+ try Data("learned".utf8).write(to: cache.appendingPathComponent("shader"))+ let moved = machine.deletingLastPathComponent().appendingPathComponent("Renamed")+ try FileManager.default.moveItem(at: machine, to: moved)+ try prepare(moved, host)+ #expect(try Data(contentsOf: host.appendingPathComponent("shader")) == Data("learned".utf8))+ }+ }++ @Test("Independent snapshots are replaced whole and never merged")+ func wholeSnapshots() throws {+ try withLayout { machine, host, cache in+ for url in [host, cache] {+ try FileManager.default.createDirectory(at: url, withIntermediateDirectories: false)+ try Data(url.lastPathComponent.utf8).write(to: url.appendingPathComponent("functions.list"))+ try Data(url.lastPathComponent.utf8).write(to: url.appendingPathComponent("functions.data"))+ }+ try prepare(machine, host)+ for name in ["functions.list", "functions.data"] {+ #expect(try Data(contentsOf: host.appendingPathComponent(name)) == Data("ShaderCache".utf8))+ }+ }+ }++ @Test("A foreign host alias is left intact")+ func foreignAlias() throws {+ try withLayout { machine, host, _ in+ let other = machine.deletingLastPathComponent().appendingPathComponent("OtherCache")+ try FileManager.default.createDirectory(at: other, withIntermediateDirectories: false)+ try FileManager.default.createSymbolicLink(at: host, withDestinationURL: other)+ #expect(throws: CocoaError.self) { try prepare(machine, host) }+ #expect(try FileManager.default.destinationOfSymbolicLink(atPath: host.path) == other.path)+ }+ }++ @Test("A failed checkpoint leaves the previous snapshot intact")+ func checkpointFailure() throws {+ try withLayout { machine, host, cache in+ try prepare(machine, host)+ try Data("preserved".utf8).write(to: cache.appendingPathComponent("shader"))+ try FileManager.default.removeItem(at: host)+ try Data("invalid source".utf8).write(to: host)+ #expect(throws: CocoaError.self) {+ try VPhoneShaderCache.checkpoint(machineDirectory: machine, frameworkCache: host)+ }+ #expect(try Data(contentsOf: cache.appendingPathComponent("shader")) == Data("preserved".utf8))+ }+ }++ @Test("A machine cache alias is rejected without widening its destination")+ func machineAliasRejected() throws {+ try withLayout { machine, host, cache in+ let outside = machine.deletingLastPathComponent().appendingPathComponent("outside")+ try FileManager.default.createDirectory(at: outside, withIntermediateDirectories: false)+ #expect(chmod(outside.path, 0o700) == 0)+ try FileManager.default.createSymbolicLink(at: cache, withDestinationURL: outside)+ #expect(throws: CocoaError.self) { try prepare(machine, host) }+ var metadata = stat()+ #expect(lstat(outside.path, &metadata) == 0 && metadata.st_mode & 0o777 == 0o700)+ }+ }+}