Run a virtual iPhone on an Apple Silicon Mac.
Swift
Source paravirtual GPU bundle from selected PCC firmware
Lakr9fc1b46c00ac
diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.mdindex 1d735c66..4e4fedeb 100644--- a/research/0_binary_patch_comparison.md+++ b/research/0_binary_patch_comparison.md@@ -437,7 +437,7 @@ and nothing resolves a `python3` at runtime.| # | Component | Description | Regular | Dev | JB || --- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | :-----: | :-: | :-: || 1 | Cryptex SystemOS + AppOS | Decrypt AEA + mount + copy to device | Y | Y | Y |-| 2 | GPU driver | AppleParavirtGPUMetalIOGPUFamily bundle | Y | Y | Y |+| 2 | GPU driver | AppleParavirtGPUMetalIOGPUFamily bundle, extracted from the selected PCC OS image during `fw prepare` | Y | Y | Y || 3 | `iosbinpack64` | Jailbreak tools (base set) | Y | Y | Y || 4 | `iosbinpack64` dev overlay | Replace `rpcserver_ios` with dev build | - | Y | - || 5 | `vphoned` | vsock HID/control daemon (built + signed) | Y | Y | Y |@@ -1208,20 +1208,32 @@ recorded here rather than only in the commit.**`tar` → `VPhoneArchive`.** The last three `runProcess("/usr/bin/tar", …)` calls inthe package are gone: `cfw_input.tar.zst` into the scratch directory, `iosbinpack64.tar`-and `AppleParavirtGPUMetalIOGPUFamily.tar` onto the mounted volume. All three now use-`VPhoneArchiveExtractor` with the `.ontoGuestVolume` preset, so `--zstd` is no longer+and the former `AppleParavirtGPUMetalIOGPUFamily.tar` onto the mounted volume. Those three used+`VPhoneArchiveExtractor` with the `.ontoGuestVolume` preset, so `--zstd` was no longerpassed (the filter is detected, and libzstd is static in the xcframework).- **Behaviour change:** `.ontoGuestVolume` includes `--no-overwrite-dir`, which the twoguest-volume `tar` calls did *not* pass — they passed only `--preserve-permissions`.- Directories that iosbinpack64 and the GPU bundle share with the system volume now keep+ Directories that iosbinpack64 and the GPU bundle shared with the system volume kepttheir own mode, owner and mtime instead of taking the archive's. That is what- `cfw_install.sh` has always passed GNU tar (`--preserve-permissions --no-overwrite-dir`);- the Swift port dropped the second flag, and this restores shell parity.+ `cfw_install.sh` had always passed GNU tar (`--preserve-permissions --no-overwrite-dir`);+ the Swift port dropped the second flag, and that restored shell parity at the time.- Ownership and exact modes are unchanged: the step runs as root, where `/usr/bin/tar -xf`already implied `-p` and restored numeric owners. That is why the scratch-directory- extraction also uses `.ontoGuestVolume` despite the name — the preset is what bsdtar- did as root, and several of those members are copied onto the volume verbatim.+ extraction also used `.ontoGuestVolume` despite the name — the preset is what bsdtar+ did as root, and several of those members were copied onto the volume verbatim.++## GPU bundle now comes from the selected PCC image (2026-09-24)++The application no longer ships `AppleParavirtGPUMetalIOGPUFamily.tar`. During+`fw prepare`, the PCC `BuildManifest.plist` selects the vphone600 OS image. The+preparer decrypts and read-only mounts that image, copies its complete+`AppleParavirtGPUMetalIOGPUFamily.bundle` into the VM restore tree, then removes+the temporary decrypted image. Both the JB host-mount installer and the legacy+filesystem merge copy this staged bundle into the guest. The executable,+compiler-plugin dylib, plist, and signature resources therefore come from the+same PCC release as the selected kernel; no separately downloaded GPU binary is+required. This is a payload-source change, not a new binary patch.**`find -name '._*' -delete` → `deleteAppleDoubleFiles`,** and this one was nearly asilent regression worth writing down. On a volume with native extended attributes,diff --git a/scripts/dist_manifest.sh b/scripts/dist_manifest.shindex 6ff61ced..51292c86 100755--- a/scripts/dist_manifest.sh+++ b/scripts/dist_manifest.sh@@ -62,6 +62,5 @@ done# ../siblings/ optional guest sources and archives; not part of the# shipped app or automatic VM installation# vphoned/*.m *.h vendor/ Makefile same, and it is the bulk of scripts/-print -r -- "payloads/AppleParavirtGPUMetalIOGPUFamily.tar" # guest GPU driverprint -r -- "vphoned/vphoned.plist" # LaunchDaemon plist, injectLaunchDaemonsprint -r -- "vphoned/entitlements.plist" # guest_sign_ent for vphoneddiff --git a/scripts/payloads/AppleParavirtGPUMetalIOGPUFamily.tar b/scripts/payloads/AppleParavirtGPUMetalIOGPUFamily.tardeleted file mode 100644index afa44559..00000000Binary files a/scripts/payloads/AppleParavirtGPUMetalIOGPUFamily.tar and /dev/null differdiff --git a/siblings/gpu/README.md b/siblings/gpu/README.mdnew file mode 100644index 00000000..8952ffa8--- /dev/null+++ b/siblings/gpu/README.md@@ -0,0 +1,11 @@+# PCC GPU component++`AppleParavirtGPUMetalIOGPUFamily.bundle` is Apple firmware content. There is+no source here to compile and no binary to package in `vphone-cli.app`.++`vphone-cli fw prepare` reads the vphone600 OS path from the selected PCC+`BuildManifest.plist`, decrypts and mounts that image with macOS system tools,+and stages the complete bundle inside the VM restore tree. JB installation+copies the staged bundle into the guest. The compiler-plugin dylib and driver+executable therefore always come from the same PCC release used for the VM's+kernel.diff --git a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swiftindex 8253e256..d102b823 100644--- a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift+++ b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift@@ -5,7 +5,6 @@// launchd_cache_loader patches, vphoned, and its LaunchDaemon.import Foundation-import VPhoneArchiveimport VPhoneCoreimport VPhoneSign@@ -102,13 +101,18 @@ extension CryptexFilesystemPatcher {func addGpuDriver(targetMount: String) throws {let target = URL.init(filePath: targetMount)-- try VPhoneArchiveExtractor.extract(- resources.gpuDriverArchive, into: target, options: .ontoGuestVolume- )-let bundle = target.appending(path: "/System/Library/Extensions/AppleParavirtGPUMetalIOGPUFamily.bundle")- // Clean macOS resource fork files (._* files from tar xattrs)+ let staged = VPhonePCCGPUDriver.stagedBundle(in: restoreDir)+ guard FileManager.default.fileExists(atPath: staged.path) else {+ throw FirmwarePatcher.PatcherError.patchVerificationFailed(+ "PCC GPU driver is missing: \(staged.path). Re-run fw prepare with the PCC IPSW."+ )+ }+ if FileManager.default.fileExists(atPath: bundle.path) {+ try FileManager.default.removeItem(at: bundle)+ }+ try FileManager.default.copyItem(at: staged, to: bundle)+ // Clean AppleDouble files if the host copy created any.try deleteAppleDoubleFiles(under: bundle)try chownRecursively(uid: 0, gid: 0, at: bundle)for path in [diff --git a/sources/VPhoneCore/VPhonePCCGPUDriver.swift b/sources/VPhoneCore/VPhonePCCGPUDriver.swiftnew file mode 100644index 00000000..a14d0e35--- /dev/null+++ b/sources/VPhoneCore/VPhonePCCGPUDriver.swift@@ -0,0 +1,102 @@+import Foundation++/// Stages Apple's paravirtual GPU bundle from the selected PCC OS image.+/// The bundle belongs to that firmware build; it is never shipped in the app.+public enum VPhonePCCGPUDriver {+ public static let name = "AppleParavirtGPUMetalIOGPUFamily.bundle"++ public enum Error: Swift.Error, LocalizedError {+ case missingOSPath(URL)+ case unsafeOSPath(String)+ case missingBundle(URL)+ case toolFailed(String, String)++ public var errorDescription: String? {+ switch self {+ case let .missingOSPath(manifest):+ "No vphone600 OS image in PCC manifest: \(manifest.path)"+ case let .unsafeOSPath(path):+ "PCC manifest has an unsafe OS image path: \(path)"+ case let .missingBundle(path):+ "PCC OS image has no GPU driver bundle at \(path.path)"+ case let .toolFailed(tool, detail):+ "\(tool) failed while extracting the PCC GPU driver: \(detail)"+ }+ }+ }++ public static func stagedBundle(in restoreDirectory: URL) -> URL {+ restoreDirectory.appending(path: ".pcc-gpu/\(name)")+ }++ public static func osImage(in cloudOSDirectory: URL) throws -> URL {+ let manifest = cloudOSDirectory.appendingPathComponent("BuildManifest.plist")+ let data = try Data(contentsOf: manifest, options: .mappedIfSafe)+ let root = try PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any]+ let identities = root?["BuildIdentities"] as? [[String: Any]] ?? []+ guard let path = identities.compactMap({ identity -> String? in+ let info = identity["Info"] as? [String: Any]+ guard info?["DeviceClass"] as? String == "vphone600ap" else { return nil }+ let components = identity["Manifest"] as? [String: Any]+ let os = components?["OS"] as? [String: Any]+ let osInfo = os?["Info"] as? [String: Any]+ return osInfo?["Path"] as? String+ }).first else {+ throw Error.missingOSPath(manifest)+ }+ let parts = path.split(separator: "/", omittingEmptySubsequences: false)+ guard !path.hasPrefix("/"), !parts.contains(".."), !parts.contains("."),+ !parts.contains("") else { throw Error.unsafeOSPath(path) }+ return cloudOSDirectory.appendingPathComponent(path)+ }++ /// Called during `fw prepare`, while the extracted PCC tree still exists.+ /// Only the small bundle survives in the VM's restore tree; the decrypted+ /// system image and mount are discarded before firmware preparation ends.+ public static func stage(from cloudOSDirectory: URL, into restoreDirectory: URL) throws {+ let fm = FileManager.default+ let encrypted = try osImage(in: cloudOSDirectory)+ let destination = stagedBundle(in: restoreDirectory)+ let scratch = restoreDirectory.appendingPathComponent(".pcc-gpu-extract-\(UUID().uuidString)")+ let plain = scratch.appendingPathComponent("OS.dmg")+ let mount = scratch.appendingPathComponent("mount")+ try fm.createDirectory(at: mount, withIntermediateDirectories: true)+ defer { try? fm.removeItem(at: scratch) }++ let key = try vphoneRunBlocking { try await VPhoneAEA.symmetricKey(of: encrypted) }+ try run("/usr/bin/aea", [+ "decrypt", "-t", "4", "-i", encrypted.path, "-o", plain.path, "-key-value", key+ ])+ defer {+ _ = try? VPhoneProcessRunner.runCapturing(+ URL(fileURLWithPath: "/usr/bin/hdiutil"), ["detach", mount.path]+ )+ }+ try run("/usr/bin/hdiutil", [+ "attach", "-readonly", "-nobrowse", "-owners", "off",+ "-mountpoint", mount.path, plain.path+ ])++ let source = mount.appending(path: "System/Library/Extensions/\(name)")+ guard fm.fileExists(atPath: source.path) else { throw Error.missingBundle(source) }+ for file in ["AppleParavirtGPUMetalIOGPUFamily",+ "libAppleParavirtCompilerPluginIOGPUFamily.dylib", "Info.plist"] {+ let member = source.appendingPathComponent(file)+ guard fm.fileExists(atPath: member.path) else { throw Error.missingBundle(member) }+ }+ try fm.createDirectory(at: destination.deletingLastPathComponent(),+ withIntermediateDirectories: true)+ if fm.fileExists(atPath: destination.path) { try fm.removeItem(at: destination) }+ try fm.copyItem(at: source, to: destination)+ print("[+] GPU driver staged from PCC OS: \(destination.path)")+ }++ private static func run(_ tool: String, _ args: [String]) throws {+ let result = try VPhoneProcessRunner.runCapturing(URL(fileURLWithPath: tool), args)+ guard result.succeeded else {+ let output = result.stderr.isEmpty ? result.stdout : result.stderr+ throw Error.toolFailed(URL(fileURLWithPath: tool).lastPathComponent,+ output.trimmingCharacters(in: .whitespacesAndNewlines))+ }+ }+}diff --git a/sources/VPhoneCore/VPhoneResources.swift b/sources/VPhoneCore/VPhoneResources.swiftindex 5b56886d..59ed5530 100644--- a/sources/VPhoneCore/VPhoneResources.swift+++ b/sources/VPhoneCore/VPhoneResources.swift@@ -92,9 +92,6 @@ public struct VPhoneResources: Sendable {// MARK: - Assetspublic var scriptsDir: URL { base.appendingPathComponent("scripts") }- public var gpuDriverArchive: URL {- scriptsDir.appendingPathComponent("payloads/AppleParavirtGPUMetalIOGPUFamily.tar")- }public var vphoned: URL {let bundled = base.appendingPathComponent("vphoned.signed")diff --git a/sources/vphone-cli/VPhoneCFWInstaller.swift b/sources/vphone-cli/VPhoneCFWInstaller.swiftindex 86d0cd02..95484830 100644--- a/sources/vphone-cli/VPhoneCFWInstaller.swift+++ b/sources/vphone-cli/VPhoneCFWInstaller.swift@@ -2,7 +2,6 @@ import ArgumentParserimport Darwinimport FirmwarePatcherimport Foundation-import VPhoneArchiveimport VPhoneCoreimport VPhoneSign@@ -137,10 +136,14 @@ struct VPhoneCFWInstaller {path: "usr/libexec/diskimagesiod", verb: "patch-diskimagesiod", preserveEntitlements: true)}try renameGigalocker(data: data)- try VPhoneArchiveExtractor.extract(resources.gpuDriverArchive, into: system,- options: .ontoGuestVolume)+ let gpuSource = VPhonePCCGPUDriver.stagedBundle(in: restore)+ guard fm.fileExists(atPath: gpuSource.path) else {+ throw ValidationError("PCC GPU driver is missing: \(gpuSource.path). Re-run fw prepare with the PCC IPSW.")+ }let gpu = system.appendingPathComponent("System/Library/Extensions/AppleParavirtGPUMetalIOGPUFamily.bundle")+ if fm.fileExists(atPath: gpu.path) { try fm.removeItem(at: gpu) }+ try fm.copyItem(at: gpuSource, to: gpu)try tool("/usr/sbin/chown", ["-R", "0:0", gpu.path])for file in [gpu, gpu.appendingPathComponent("AppleParavirtGPUMetalIOGPUFamily"),gpu.appendingPathComponent("libAppleParavirtCompilerPluginIOGPUFamily.dylib"),diff --git a/sources/vphone-cli/VPhoneFirmwarePreparer.swift b/sources/vphone-cli/VPhoneFirmwarePreparer.swiftindex 7f0fc28f..0953200c 100644--- a/sources/vphone-cli/VPhoneFirmwarePreparer.swift+++ b/sources/vphone-cli/VPhoneFirmwarePreparer.swift@@ -72,6 +72,8 @@ enum VPhoneFirmwarePreparer {let originalManifest = phoneTree.appendingPathComponent("BuildManifest.plist")try clone(originalManifest, to: phoneTree.appendingPathComponent("iPhone-BuildManifest.plist"))try FirmwareManifest.generate(iPhoneDir: phoneTree, cloudOSDir: cloudTree, verbose: true)+ print("[*] Extracting GPU driver from cloudOS PCC image...")+ try VPhonePCCGPUDriver.stage(from: cloudTree, into: phoneTree)// The destination did not exist at entry and the staging directory is// on the same volume. One rename exposes the complete restore tree.diff --git a/tests/VPhoneCoreTests/PCCGPUDriverTests.swift b/tests/VPhoneCoreTests/PCCGPUDriverTests.swiftnew file mode 100644index 00000000..92fe3b08--- /dev/null+++ b/tests/VPhoneCoreTests/PCCGPUDriverTests.swift@@ -0,0 +1,47 @@+@testable import VPhoneCore+import Foundation+import Testing++struct PCCGPUDriverTests {+ @Test func selectsVphone600OSImage() throws {+ let directory = FileManager.default.temporaryDirectory+ .appendingPathComponent("pcc-gpu-test-\(UUID().uuidString)")+ try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)+ defer { try? FileManager.default.removeItem(at: directory) }++ let identities: [[String: Any]] = [+ identity(device: "vresearch101ap", os: "wrong.dmg.aea"),+ identity(device: "vphone600ap", os: "PCC-OS.dmg.aea"),+ ]+ let manifest = try PropertyListSerialization.data(+ fromPropertyList: ["BuildIdentities": identities], format: .binary, options: 0+ )+ try manifest.write(to: directory.appendingPathComponent("BuildManifest.plist"))++ #expect(try VPhonePCCGPUDriver.osImage(in: directory)+ == directory.appendingPathComponent("PCC-OS.dmg.aea"))+ #expect(VPhonePCCGPUDriver.stagedBundle(in: directory)+ == directory.appending(path: ".pcc-gpu/AppleParavirtGPUMetalIOGPUFamily.bundle"))+ }++ @Test func refusesPathOutsidePCCDirectory() throws {+ let directory = FileManager.default.temporaryDirectory+ .appendingPathComponent("pcc-gpu-test-\(UUID().uuidString)")+ try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)+ defer { try? FileManager.default.removeItem(at: directory) }+ let manifest = try PropertyListSerialization.data(+ fromPropertyList: ["BuildIdentities": [identity(device: "vphone600ap", os: "../outside.dmg")]],+ format: .binary, options: 0+ )+ try manifest.write(to: directory.appendingPathComponent("BuildManifest.plist"))++ #expect(throws: VPhonePCCGPUDriver.Error.self) {+ try VPhonePCCGPUDriver.osImage(in: directory)+ }+ }++ private func identity(device: String, os: String) -> [String: Any] {+ ["Info": ["DeviceClass": device],+ "Manifest": ["OS": ["Info": ["Path": os]]]]+ }+}diff --git a/tests/VPhoneCoreTests/ResourcesTests.swift b/tests/VPhoneCoreTests/ResourcesTests.swiftindex bcc4e580..81f69dc9 100644--- a/tests/VPhoneCoreTests/ResourcesTests.swift+++ b/tests/VPhoneCoreTests/ResourcesTests.swift@@ -18,8 +18,6 @@ struct ResourcesTests {let exe = "/Applications/vphone-cli.app/Contents/MacOS/vphone-cli"let r = VPhoneResources.resolve(executablePath: exe)#expect(r.base.path == "/Applications/vphone-cli.app/Contents/Resources")- #expect(r.gpuDriverArchive.path- == "/Applications/vphone-cli.app/Contents/Resources/scripts/payloads/AppleParavirtGPUMetalIOGPUFamily.tar")}@Test func devLayoutWalksUpToProjectRoot() throws {@@ -37,8 +35,6 @@ struct ResourcesTests {let exe = root.appendingPathComponent(".build/release/vphone-cli").pathlet r = VPhoneResources.resolve(executablePath: exe)#expect(r.base.path == root.resolvingSymlinksInPath().path)- #expect(r.gpuDriverArchive.path == root.resolvingSymlinksInPath()- .appendingPathComponent("scripts/payloads/AppleParavirtGPUMetalIOGPUFamily.tar").path)}@Test func cacheDirsAreHomeRelative() {@@ -70,7 +66,7 @@ struct ResourcesTests {let base = URL(fileURLWithPath: "/x")let r = VPhoneResources(base: base)let rooted = [- r.scriptsDir, r.gpuDriverArchive,+ r.scriptsDir,r.vphoned,]for url in rooted {