Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Use native PCC restore as the GPU source

Lakrb06496efc0c5
diff --git a/docs/guides/create-and-run.md b/docs/guides/create-and-run.md
index a805c977..c2d18fa1 100644
--- a/docs/guides/create-and-run.md
+++ b/docs/guides/create-and-run.md
@@ -17,7 +17,7 @@ vphone-cli vm create myphone \
Creation runs prepare → JB patch → online DFU restore → host-mounted CFW installation → first GUI boot. It needs network access for the restore ticket. CFW installation needs administrator authentication; on a host without an interactive terminal, `--root-popup` uses a macOS authentication dialog. The default virtual disk is 64 GB. `--keep-artifacts` retains the large prepared restore tree; omit it when disk space matters.
-If Apple's WKMS server no longer serves the AEA key for the selected PCC image, `fw prepare` automatically creates a temporary vphone VM, starts it in DFU, and restores the selected cloudOS IPSW using this project's restore backend. It mounts the restored System volume read-only, extracts the GPU bundle, then removes the temporary VM. This first restore supplies the GPU driver for the second, hybrid iPhone restore. `vm create` and `fw prepare` also accept `--gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle` to reuse a previously extracted bundle. The CLI checks its iPhoneOS platform version against the selected cloudOS version. Each restore obtains its own ticket online.
+`fw prepare` creates a temporary vphone VM, starts it in DFU, and restores the selected cloudOS IPSW using this project's restore backend. It mounts the restored System volume read-only, extracts the GPU bundle, then removes the temporary VM. This first restore supplies the GPU driver for the second, hybrid iPhone restore. `vm create` and `fw prepare` also accept `--gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle` to reuse a previously extracted bundle without the temporary restore. The CLI checks its iPhoneOS platform version against the selected cloudOS version. Each restore obtains its own ticket online.
Success ends with `First boot: vphoned ping succeeded` and `JB VM created; vphoned connected`. **The verification VM is then stopped.** The ping proves the daemon answered over the host control socket during that boot; it does not leave a running VM behind.
diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.md
index b24bd4fb..0d3f7ecd 100644
--- a/research/0_binary_patch_comparison.md
+++ b/research/0_binary_patch_comparison.md
@@ -1226,13 +1226,13 @@ passed (the filter is detected, and libzstd is static in the xcframework).
## 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 when Apple serves its AEA
-key, copies its complete `AppleParavirtGPUMetalIOGPUFamily.bundle` into the VM
-restore tree, then removes the temporary image. When WKMS returns 403,
-`vphone-cli` creates a temporary PV=3 VM, boots it in DFU, and restores the
-selected cloudOS IPSW through its own `VPhoneRestoreBridge`. The preparer
-copies the bundle from its sealed System volume and removes the temporary VM.
+`fw prepare`, `vphone-cli` creates a temporary PV=3 VM, boots it in DFU, and
+restores the selected cloudOS IPSW through its own `VPhoneRestoreBridge`. The
+preparer copies `AppleParavirtGPUMetalIOGPUFamily.bundle` from the sealed System
+volume into the VM restore tree and removes the temporary VM. This is the
+default path; `--gpu-driver-bundle` reuses a validated bundle instead. Both
+cloudOS 26.1 and 26.4 PCC AEA key URLs returned HTTP 403 on 2026-09-24, so
+the preparer no longer requests those keys before the temporary restore.
Both the JB host-mount installer and the filesystem merge copy this staged
bundle into the iPhone guest. The 26.4 `23E5207q` restored bundle has
`DTPlatformVersion=26.4`, `CFBundleVersion=64.4.4`, and binary SHA-256
diff --git a/siblings/gpu/README.md b/siblings/gpu/README.md
index f973f5ba..772b0528 100644
--- a/siblings/gpu/README.md
+++ b/siblings/gpu/README.md
@@ -3,15 +3,13 @@
`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 when Apple serves its AEA
-key, and stages the complete bundle inside the VM restore tree. If that key is
-unavailable, `vphone-cli` creates its own temporary PV=3 VM, boots it into DFU,
-and restores the selected cloudOS IPSW with the project's in-process
-idevicerestore backend. The CLI mounts its sealed System volume read-only,
-copies the bundle, and removes the temporary VM. JB installation copies the
-staged bundle into the iPhone guest. The driver therefore comes from the same
-PCC release used for the VM's kernel.
+`vphone-cli fw prepare` creates a temporary PV=3 VM, boots it into DFU, and
+restores the selected cloudOS IPSW with the project's in-process idevicerestore
+backend. The CLI mounts its sealed System volume read-only, stages the GPU
+bundle inside the iPhone restore tree, and removes the temporary VM. An explicit
+`--gpu-driver-bundle` reuses a validated bundle instead. JB installation copies
+the staged bundle into the iPhone guest. The driver therefore comes from the
+same PCC release used for the VM's kernel.
The cloudOS 26.4 `23E5207q` bundle recovered from its restored System volume
has `DTPlatformVersion=26.4`, `CFBundleVersion=64.4.4`, and no
diff --git a/sources/VPhoneCore/VPhonePCCGPUDriver.swift b/sources/VPhoneCore/VPhonePCCGPUDriver.swift
index 37c38218..8d9e65ea 100644
--- a/sources/VPhoneCore/VPhonePCCGPUDriver.swift
+++ b/sources/VPhoneCore/VPhonePCCGPUDriver.swift
@@ -1,32 +1,20 @@
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.
+/// Stages Apple's paravirtual GPU bundle from a restored PCC System volume or
+/// a user-supplied bundle. The bundle 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 invalidCachedBundle(URL)
+ case invalidBundle(URL)
case wrongPlatformVersion(URL, expected: String, actual: String)
- 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 .invalidCachedBundle(path):
+ case let .invalidBundle(path):
"GPU driver bundle is incomplete or has the wrong identifier: \(path.path)"
case let .wrongPlatformVersion(path, expected, actual):
"GPU driver at \(path.path) is for iPhoneOS \(actual), expected cloudOS \(expected)"
- case let .toolFailed(tool, detail):
- "\(tool) failed while extracting the PCC GPU driver: \(detail)"
}
}
}
@@ -35,74 +23,15 @@ public enum VPhonePCCGPUDriver {
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.
+ /// Keep only the validated bundle in the VM's restore tree.
public static func stage(
- from cloudOSDirectory: URL,
+ from bundle: URL,
into restoreDirectory: URL,
- cachedBundle: URL? = nil,
- expectedPlatformVersion: String? = nil,
+ expectedPlatformVersion: String,
) throws {
let fm = FileManager.default
let destination = stagedBundle(in: restoreDirectory)
- if let cachedBundle {
- let source = cachedBundle.standardizedFileURL.resolvingSymlinksInPath()
- try validateBundle(at: source, expectedPlatformVersion: expectedPlatformVersion)
- 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 local bundle: \(destination.path)")
- return
- }
-
- let encrypted = try osImage(in: cloudOSDirectory)
- 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) }
+ let source = bundle.standardizedFileURL.resolvingSymlinksInPath()
try validateBundle(at: source, expectedPlatformVersion: expectedPlatformVersion)
try fm.createDirectory(at: destination.deletingLastPathComponent(),
withIntermediateDirectories: true)
@@ -110,21 +39,21 @@ public enum VPhonePCCGPUDriver {
try fm.removeItem(at: destination)
}
try fm.copyItem(at: source, to: destination)
- print("[+] GPU driver staged from PCC OS: \(destination.path)")
+ print("[+] GPU driver staged: \(destination.path)")
}
- static func validateBundle(at source: URL, expectedPlatformVersion: String?) throws {
+ static func validateBundle(at source: URL, expectedPlatformVersion: String) throws {
let fm = FileManager.default
var isDirectory: ObjCBool = false
guard fm.fileExists(atPath: source.path, isDirectory: &isDirectory), isDirectory.boolValue else {
- throw Error.invalidCachedBundle(source)
+ throw Error.invalidBundle(source)
}
for file in ["AppleParavirtGPUMetalIOGPUFamily",
"Info.plist",
"_CodeSignature/CodeResources"]
{
guard fm.fileExists(atPath: source.appendingPathComponent(file).path) else {
- throw Error.invalidCachedBundle(source)
+ throw Error.invalidBundle(source)
}
}
let infoURL = source.appendingPathComponent("Info.plist")
@@ -133,23 +62,12 @@ public enum VPhonePCCGPUDriver {
guard let properties = plist as? [String: Any],
properties["CFBundleIdentifier"] as? String ==
"com.apple.driver.AppleParavirtGPUMetalIOGPUFamily"
- else { throw Error.invalidCachedBundle(source) }
- if let expectedPlatformVersion {
- let actual = properties["DTPlatformVersion"] as? String ?? "unknown"
- guard actual == expectedPlatformVersion else {
- throw Error.wrongPlatformVersion(
- source, expected: expectedPlatformVersion, actual: actual,
- )
- }
- }
- }
-
- 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))
+ else { throw Error.invalidBundle(source) }
+ let actual = properties["DTPlatformVersion"] as? String ?? "unknown"
+ guard actual == expectedPlatformVersion else {
+ throw Error.wrongPlatformVersion(
+ source, expected: expectedPlatformVersion, actual: actual,
+ )
}
}
}
diff --git a/sources/vphone-cli/VPhoneFirmwarePreparer.swift b/sources/vphone-cli/VPhoneFirmwarePreparer.swift
index e0dba36e..e6ec65bd 100644
--- a/sources/vphone-cli/VPhoneFirmwarePreparer.swift
+++ b/sources/vphone-cli/VPhoneFirmwarePreparer.swift
@@ -73,17 +73,14 @@ 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(gpuDriverBundle == nil
- ? "[*] Extracting GPU driver from cloudOS PCC image..."
- : "[*] Staging GPU driver from local bundle...")
- do {
+ if let gpuDriverBundle {
+ print("[*] Staging GPU driver from local bundle...")
try VPhonePCCGPUDriver.stage(
- from: cloudTree, into: phoneTree, cachedBundle: gpuDriverBundle,
+ from: gpuDriverBundle, into: phoneTree,
expectedPlatformVersion: cloud.version,
)
- } catch let failure as VPhoneAEA.Error {
- guard case .keyFetchFailed = failure, gpuDriverBundle == nil else { throw failure }
- print("[*] PCC AEA key unavailable; restoring cloudOS in a temporary vphone VM...")
+ } else {
+ print("[*] Restoring cloudOS in a temporary vphone VM to extract its GPU driver...")
try VPhonePCCGPURecovery.stage(
cloudOSDirectory: cloudTree, into: phoneTree,
expectedPlatformVersion: cloud.version,
diff --git a/sources/vphone-cli/VPhonePCCGPURecovery.swift b/sources/vphone-cli/VPhonePCCGPURecovery.swift
index 5f5c534d..67f4e32e 100644
--- a/sources/vphone-cli/VPhonePCCGPURecovery.swift
+++ b/sources/vphone-cli/VPhonePCCGPURecovery.swift
@@ -82,14 +82,13 @@ enum VPhonePCCGPURecovery {
_ = dfu.waitUntilExit()
try stageFromSystemDisk(
- vm.url.appending(path: "Disk.img"), cloudOSDirectory: cloudOSDirectory,
+ vm.url.appending(path: "Disk.img"),
into: restoreDirectory, expectedPlatformVersion: expectedPlatformVersion,
)
}
private static func stageFromSystemDisk(
_ diskImage: URL,
- cloudOSDirectory: URL,
into restoreDirectory: URL,
expectedPlatformVersion: String,
) throws {
@@ -123,7 +122,7 @@ enum VPhonePCCGPURecovery {
path: "System/Library/Extensions/\(VPhonePCCGPUDriver.name)",
)
try VPhonePCCGPUDriver.stage(
- from: cloudOSDirectory, into: restoreDirectory, cachedBundle: source,
+ from: source, into: restoreDirectory,
expectedPlatformVersion: expectedPlatformVersion,
)
print("[+] GPU driver staged from cloudOS restored by vphone-cli")
diff --git a/tests/VPhoneCoreTests/PCCGPUDriverTests.swift b/tests/VPhoneCoreTests/PCCGPUDriverTests.swift
index fc086e35..1cecb659 100644
--- a/tests/VPhoneCoreTests/PCCGPUDriverTests.swift
+++ b/tests/VPhoneCoreTests/PCCGPUDriverTests.swift
@@ -3,44 +3,7 @@ import Testing
@testable import VPhoneCore
struct PCCGPUDriverTests {
- @Test func `selects vphone 600 OS image`() 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 `refuses path outside PCC directory`() 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)
- }
- }
-
- @Test func `stages a validated local bundle without an AEA key request`() throws {
+ @Test func `stages a validated GPU bundle`() throws {
let root = FileManager.default.temporaryDirectory
.appendingPathComponent("pcc-gpu-test-\(UUID().uuidString)")
defer { try? FileManager.default.removeItem(at: root) }
@@ -63,30 +26,27 @@ struct PCCGPUDriverTests {
let restore = root.appendingPathComponent("restore")
try VPhonePCCGPUDriver.stage(
- from: root.appendingPathComponent("missing-cloudos"),
+ from: source,
into: restore,
- cachedBundle: source,
expectedPlatformVersion: "26.4",
)
let staged = VPhonePCCGPUDriver.stagedBundle(in: restore)
+ #expect(staged == restore.appending(path: ".pcc-gpu/AppleParavirtGPUMetalIOGPUFamily.bundle"))
#expect(try Data(contentsOf: staged.appendingPathComponent("AppleParavirtGPUMetalIOGPUFamily"))
== Data("AppleParavirtGPUMetalIOGPUFamily".utf8))
#expect(throws: VPhonePCCGPUDriver.Error.self) {
try VPhonePCCGPUDriver.stage(
- from: root, into: restore, cachedBundle: source,
+ from: source, into: restore,
expectedPlatformVersion: "26.1",
)
}
try FileManager.default.removeItem(at: source.appendingPathComponent("_CodeSignature/CodeResources"))
#expect(throws: VPhonePCCGPUDriver.Error.self) {
- try VPhonePCCGPUDriver.stage(from: root, into: restore, cachedBundle: source)
+ try VPhonePCCGPUDriver.stage(
+ from: source, into: restore, expectedPlatformVersion: "26.4",
+ )
}
}
-
- private func identity(device: String, os: String) -> [String: Any] {
- ["Info": ["DeviceClass": device],
- "Manifest": ["OS": ["Info": ["Path": os]]]]
- }
}