Skip to content

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.md
index 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 in
the 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 longer
passed (the filter is detected, and libzstd is static in the xcframework).
- **Behaviour change:** `.ontoGuestVolume` includes `--no-overwrite-dir`, which the two
guest-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 kept
their 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 a
silent regression worth writing down. On a volume with native extended attributes,
diff --git a/scripts/dist_manifest.sh b/scripts/dist_manifest.sh
index 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 driver
print -r -- "vphoned/vphoned.plist" # LaunchDaemon plist, injectLaunchDaemons
print -r -- "vphoned/entitlements.plist" # guest_sign_ent for vphoned
diff --git a/scripts/payloads/AppleParavirtGPUMetalIOGPUFamily.tar b/scripts/payloads/AppleParavirtGPUMetalIOGPUFamily.tar
deleted file mode 100644
index afa44559..00000000
Binary files a/scripts/payloads/AppleParavirtGPUMetalIOGPUFamily.tar and /dev/null differ
diff --git a/siblings/gpu/README.md b/siblings/gpu/README.md
new file mode 100644
index 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.swift
index 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 VPhoneArchive
import VPhoneCore
import 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.swift
new file mode 100644
index 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.swift
index 5b56886d..59ed5530 100644
--- a/sources/VPhoneCore/VPhoneResources.swift
+++ b/sources/VPhoneCore/VPhoneResources.swift
@@ -92,9 +92,6 @@ public struct VPhoneResources: Sendable {
// MARK: - Assets
public 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.swift
index 86d0cd02..95484830 100644
--- a/sources/vphone-cli/VPhoneCFWInstaller.swift
+++ b/sources/vphone-cli/VPhoneCFWInstaller.swift
@@ -2,7 +2,6 @@ import ArgumentParser
import Darwin
import FirmwarePatcher
import Foundation
-import VPhoneArchive
import VPhoneCore
import 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.swift
index 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.swift
new file mode 100644
index 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.swift
index 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").path
let 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 {