Run a virtual iPhone on an Apple Silicon Mac.
Swift
Build an Apple TV 4K on tvOS 27.0 from its OTA
Jacky32dc319c088e
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swiftindex 6ea05b6c..7aa13f01 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift@@ -35,12 +35,12 @@ public enum FirmwareGuestPatchResolution {]/// An arm64e Apple TV (the 4K, from its OTA) also admits the paravirtual- /// GPU driver, which a plain-arm64 userland cannot load, and the OTA- /// userland swap itself.- public static let tvArm64eGuestPatches: Set<String> = [+ /// GPU driver, which a plain-arm64 userland cannot load, the OTA userland+ /// swap itself, and the iOS 27 shared-cache patches its tvOS 27 OTA meets.+ public static let tvArm64eGuestPatches: Set<String> = Set(["system-extensions-boot-gpu_bundle",FirmwareGuestSystemPatchSet.tvOTAUserland,- ]+ ]).union(FirmwarePatchSetCatalog.tvOS27UserlandPatches)public static func unvalidatedTVGuestPatches(enabled: Set<String>, arm64eUserland: Bool = false) -> [String] {let admitted = arm64eUserland ? tvSupportedGuestPatches.union(tvArm64eGuestPatches) : tvSupportedGuestPatchesdiff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swiftindex 1edf12f5..3122cac6 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift@@ -252,6 +252,18 @@ public enum FirmwarePatchSetCatalog {"system-virtualaudio-cfw-volume_mode_precondition",]+ /// The iOS 27 shared-cache patches a 27 userland needs on the 26.4 kernel,+ /// the display swap through the kernel among them. The Apple TV 4K keeps+ /// them on for its tvOS 27 OTA; each is gated on 27, so a 26 userland+ /// never meets them.+ public static let tvOS27UserlandPatches: Set<String> = [+ "dyld-boot-iomfb_force_kern",+ "dyld-boot-lockdown_mode",+ "dyld-boot-lsd_embedded_reg",+ "dyld-boot-maxslide",+ "dyld-boot-xpc_lwcr",+ ]+/// Standard for an Apple TV guest: the TV TPRO compatibility on, and/// ``tvOSBlockedPatches`` off. The shipped `tvos.plist` must match this.public static let tvOSPreset = VPhonePatchPreset(@@ -268,8 +280,9 @@ public enum FirmwarePatchSetCatalog {/// The Apple TV preset for an arm64e Apple TV 4K whose userland comes from/// its OTA: the paravirtual GPU driver, which the HD cannot load, and the- /// userland swap on; the TV TPRO patches, which only plain-arm64 dyld- /// needs, off. The shipped `tvos-4k.plist` must match this.+ /// userland swap and ``tvOS27UserlandPatches`` on; the TV TPRO patches,+ /// which only plain-arm64 dyld needs, off. The shipped `tvos-4k.plist`+ /// must match this.public static let tvOS4KPreset = VPhonePatchPreset(identifier: VPhonePatchPreset.tvOS4KIdentifier,title: "Apple TV 4K",@@ -278,7 +291,7 @@ public enum FirmwarePatchSetCatalog {selection: .block(manualOnlyPatches.subtracting([FirmwareGuestSystemPatchSet.tvOTAUserland])- .union(tvOSBlockedPatches.subtracting(["system-extensions-boot-gpu_bundle"])),+ .union(tvOSBlockedPatches.subtracting(["system-extensions-boot-gpu_bundle"]).subtracting(tvOS27UserlandPatches)),),)diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineDiscovery.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineDiscovery.swiftindex 7ed27fa8..672bf0a6 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineDiscovery.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineDiscovery.swift@@ -46,9 +46,16 @@ extension FirmwarePipeline {return version}- /// iPhone base version (`iPhone-BuildManifest.plist`, preserved by fw_prepare).+ /// The version of the OTA a device without an IPSW takes its userland+ /// from, which `fw prepare` records beside the base's manifest: the+ /// userland, not the restored IPSW, is what the guest patches meet.+ public static let otaVersionFileName = "OTA-SystemVersion.plist"++ /// iPhone base version: the staged OTA's when there is one, else+ /// `iPhone-BuildManifest.plist`'s, preserved by fw_prepare.static func readBaseProductVersion(_ restoreDir: URL) -> String? {- readProductVersion(restoreDir, manifest: "iPhone-BuildManifest.plist")+ readProductVersion(restoreDir, manifest: otaVersionFileName)+ ?? readProductVersion(restoreDir, manifest: "iPhone-BuildManifest.plist")}/// The device whose IPSW supplied the guest OS: the one `fw prepare`diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swiftindex 77e838f1..137b9fc1 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift@@ -86,6 +86,17 @@ struct FirmwareGuestPatchResolutionTests {#expect(!tv4K.isEnabled(FirmwareGuestSystemPatchSet.paravirtGPUIndexOffset))#expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: tv4K.enabled, arm64eUserland: true).isEmpty)#expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: tv4K.enabled) == [gpu, ota].sorted())+ // The 27 shared-cache patches are on but meet only a 27 userland.+ #expect(tv4K.enabled.isDisjoint(with: FirmwarePatchSetCatalog.tvOS27UserlandPatches))+ let tv4K27 = try VPhonePatchPlan.resolve(+ preset: FirmwarePatchSetCatalog.tvOS4KPreset,+ patchSets: FirmwarePatchSetCatalog.bundled,+ iOSBase: VPhoneVersion("27.0"),+ cloudOS: VPhoneVersion("26.4"),+ )+ #expect(tv4K27.enabled.isSuperset(of: FirmwarePatchSetCatalog.tvOS27UserlandPatches))+ #expect(tv4K27.isEnabled("kernel-boot-iomfb_swapend"))+ #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: tv4K27.enabled, arm64eUserland: true).isEmpty)// The HD's preset is the mirror image.let tvHD = try plan(FirmwarePatchSetCatalog.tvOSPreset)diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swiftindex c8c84844..2ca6f71d 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swift@@ -44,6 +44,17 @@ enum VPhoneFirmwarePreparer {resources: VPhoneResources,) throws {let fm = FileManager.default+ // A source naming a catalog OTA, such as a tvOS the Apple TV HD never+ // got, restores the OTA's base IPSW and stages that OTA.+ var iPhoneSource = iPhoneSource, otaSource = otaSource, productType = productType+ if let release = VPhoneFirmwareCatalog.otaRelease(source: iPhoneSource) {+ guard let base = VPhoneFirmwareCatalog.restoreBaseURL(for: release) else {+ throw ValidationError("The firmware catalog has no \(release.baseVersion) IPSW to restore the \(release.productType) OTA \(release.version) over.")+ }+ otaSource = otaSource ?? iPhoneSource+ iPhoneSource = base+ productType = productType ?? release.productType+ }let existing = try fm.contentsOfDirectory(at: bundle.url,includingPropertiesForKeys: [.isDirectoryKey],@@ -114,7 +125,7 @@ enum VPhoneFirmwarePreparer {blockedPatches: Set(selection.blockedPatches),allowedPatches: Set(selection.allowedPatches),)- guard let plan = try pipeline.resolvePlan(iOSBase: VPhoneVersion(phone.version), cloudOS: VPhoneVersion(cloud.version)) else {+ guard let plan = try pipeline.resolvePlan(iOSBase: VPhoneVersion(ota?.version ?? phone.version), cloudOS: VPhoneVersion(cloud.version)) else {throw ValidationError("Patch preset '\(selection.presetIdentifier)' did not resolve.")}@@ -147,7 +158,10 @@ enum VPhoneFirmwarePreparer {try FirmwareManifest.generate(iPhoneDir: phoneTree, cloudOSDir: cloudTree, device: restored, verbose: true)let userland = staging.appendingPathComponent(VPhoneOTAArchive.userlandDirectoryName, isDirectory: true)if let ota {- try stageOTA(ota, device: device, build: phone.build, restoreTree: phoneTree, userland: userland)+ try stageOTA(ota, device: device, restoreTree: phoneTree, userland: userland)+ let version: [String: String] = ["ProductVersion": ota.version, "ProductBuildVersion": ota.build]+ try PropertyListSerialization.data(fromPropertyList: version, format: .xml, options: 0)+ .write(to: phoneTree.appendingPathComponent(FirmwarePipeline.otaVersionFileName))}// A plain-arm64 Apple TV cannot load the arm64e paravirtual GPU driver,// and a creation may record its patch selection only after preparing.@@ -248,8 +262,8 @@ enum VPhoneFirmwarePreparer {// MARK: - OTA userland/// The OTA a device without an IPSW takes its device tree and userland- /// from, with its key: `source` and `key` when given, else the catalog's- /// OTA of the IPSW's build, downloaded into the IPSW cache's `ota` folder+ /// from, with its key, version and build: `source` and `key` when given,+ /// else the catalog's OTA of the IPSW's build, downloaded into the IPSW cache's `ota` folder/// unless it is already there. Its manifest is checked now, before any/// IPSW is unpacked for it.static func resolveOTA(@@ -259,8 +273,12 @@ enum VPhoneFirmwarePreparer {build: String,ipswCacheDirectory: URL,downloadConnections: Int,- ) throws -> (file: URL, key: String?) {- let release = VPhoneFirmwareCatalog.otaRelease(for: device.productType, build: build)+ ) throws -> (file: URL, key: String?, version: String, build: String) {+ // A catalog OTA is of its own build, which differs from the IPSW's+ // when it is restored over its base's last release.+ let release = source.flatMap(VPhoneFirmwareCatalog.otaRelease(source:))+ ?? VPhoneFirmwareCatalog.otaRelease(for: device.productType, build: build)+ let build = release?.build ?? buildguard source != nil || release != nil else {throw ValidationError("The firmware catalog has no \(device.productType) OTA for build \(build). Pass the device's full OTA of that build with --ota-source, and its key with --ota-key.")}@@ -281,15 +299,14 @@ enum VPhoneFirmwarePreparer {let key = key ?? release?.keylet identity = try VPhoneOTAArchive.checkIdentity(of: file, key: key, device: device, build: build)print("[+] \(device.productType) OTA \(identity.version) (\(identity.build)): \(file.path)")- return (file, key)+ return (file, key, identity.version, identity.build)}/// The device's own device tree into the restore tree, beside its base's,/// and the OTA's payload chunks into `userland`.private static func stageOTA(- _ ota: (file: URL, key: String?),+ _ ota: (file: URL, key: String?, version: String, build: String),device: VPhoneGuestDevice,- build: String,restoreTree: URL,userland: URL,) throws {@@ -303,7 +320,7 @@ enum VPhoneFirmwarePreparer {from: ota.file,key: ota.key,device: device,- build: build,+ build: ota.build,deviceTreeDirectory: flash,userlandDirectory: userland,) { name indiff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plistindex fe068d1b..f4af5bbb 100644--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist@@ -84,12 +84,7 @@<string>dyld-exp-mis_trust_auth</string><string>system-preferences-exp-root_rows</string><string>dyld-exp-settings_software_update_row</string>- <string>dyld-boot-iomfb_force_kern</string><string>dyld-boot-iomfb_swapend</string>- <string>dyld-boot-lockdown_mode</string>- <string>dyld-boot-lsd_embedded_reg</string>- <string>dyld-boot-maxslide</string>- <string>dyld-boot-xpc_lwcr</string><string>dyld-cfw-camera</string><string>preboot-cfw-devicetree_board_audio</string><string>preboot-cfw-devicetree_haptics</string>diff --git a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swift b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swiftindex bce58885..47819a33 100644--- a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swift+++ b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swift@@ -41,7 +41,7 @@ public struct VPhoneCloudOSOption: Sendable, Equatable {// MARK: - VPhoneOTARelease/// A full OTA update for a device Apple ships no IPSW for. `fw prepare`-/// restores the base device's IPSW of the same build and takes this device's+/// restores the base device's IPSW of `baseVersion` and takes this device's/// device tree and userland from the OTA (`VPhoneGuestDevice.restoreBase`).public struct VPhoneOTARelease: Sendable, Equatable {public let productType: String@@ -52,14 +52,19 @@ public struct VPhoneOTARelease: Sendable, Equatable {public let size: Int64/// The AEA archive's symmetric key, base64, as AppleDB records it.public let key: String+ /// The version of the base device's IPSW the OTA is restored over. The+ /// same as `version` while the base still gets releases; a later OTA goes+ /// over the base's last one, since only the userland is taken from it.+ public let baseVersion: String- public init(productType: String, version: String, build: String, url: String, size: Int64, key: String) {+ public init(productType: String, version: String, build: String, url: String, size: Int64, key: String, baseVersion: String? = nil) {self.productType = productTypeself.version = versionself.build = buildself.url = urlself.size = sizeself.key = key+ self.baseVersion = baseVersion ?? version}/// The name the IPSW cache keeps it under, in its `ota` folder.@@ -420,7 +425,7 @@ public enum VPhoneFirmwareCatalog {]/// Full OTAs of devices without an IPSW, oldest first. Each has a- /// `tvReleases` entry of the same version for its `restoreBase`. The keys+ /// `tvReleases` entry of its `baseVersion` for its `restoreBase`. The keys/// are AppleDB's.public static let otaReleases: [VPhoneOTARelease] = [.init(@@ -431,6 +436,17 @@ public enum VPhoneFirmwareCatalog {size: 4_764_729_344,key: "zm99NLG9ucGRIqHjpHC5BVHS3v55gz7bBmVfeizDMv0=",),+ // tvOS 27 dropped the Apple TV HD, so the 27 userland goes over its+ // last IPSW.+ .init(+ productType: "AppleTV14,1",+ version: "27.0",+ build: "24J361",+ url: "https://updates.cdn-apple.com/2026FallFCS/fbf3c544-b770-4756-9cca-abfb2d3cb65e/com_apple_MobileAsset_SoftwareUpdate/9bf3ad6ac49c25016599bbb77d8ea1c612cb745eb7ee9e502af1926c860b7e18.aea",+ size: 4_831_838_208,+ key: "L3wZrfSYx2pFDbJSYtEteNDspB26qBv0lxLlkWrKTYk=",+ baseVersion: "26.6",+ ),]/// The full OTA of `productType` at `build`, or nil when the catalog has none.@@ -438,20 +454,38 @@ public enum VPhoneFirmwareCatalog {otaReleases.first { $0.productType == productType && $0.build == build }}+ /// The catalog OTA a firmware source names, by its URL or by the name the+ /// IPSW cache keeps it under, or nil for any other source.+ public static func otaRelease(source: String) -> VPhoneOTARelease? {+ let name = (source as NSString).lastPathComponent+ return otaReleases.first { $0.url == source || $0.fileName == name }+ }++ /// The URL of the base device's IPSW `release` is restored over.+ public static func restoreBaseURL(for release: VPhoneOTARelease) -> String? {+ guard let base = VPhoneGuestDevice.named(release.productType)?.restoreBase else { return nil }+ let releases = (iPhoneReleases + iPadReleases + tvReleases).first { $0.devices.contains(base.productType) }?.releases+ return releases?.first { $0.version == release.baseVersion }?.url+ }+/// The pairings for one guest device, oldest first: the iPhone17,3 list,/// or another model's releases with the cloudOS an iPhone17,3 of that/// release uses. A cellular iPad gets its Wi-Fi model's; an Apple TV gets/// cloudOS 26.4, the only kernel its TPRO compatibility patch covers; a- /// device without an IPSW gets its restore base's releases that have an- /// OTA for it; an unknown device gets none.+ /// device without an IPSW gets one per OTA for it, named for the OTA: the+ /// base's IPSW when the OTA is of the same version, else the OTA itself,+ /// which `fw prepare` restores over its base's IPSW; an unknown device+ /// gets none.public static func pairings(for device: String) -> [VPhoneFirmwarePairing] {guard let guest = VPhoneGuestDevice.named(device) else { return [] }guard guest.presentsBoard else { return pairings }let restored = guest.restoreBase ?? guestvar releases = (iPhoneReleases + iPadReleases + tvReleases).first { $0.devices.contains(restored.productType) }?.releases ?? []if restored != guest {- let versions = Set(otaReleases.filter { $0.productType == guest.productType }.map(\.version))- releases = releases.filter { versions.contains($0.version) }+ releases = otaReleases.filter { $0.productType == guest.productType }.compactMap { ota in+ guard let base = releases.first(where: { $0.version == ota.baseVersion }) else { return nil }+ return (version: ota.version, url: ota.version == base.version ? base.url : ota.url)+ }}return releases.map { release inlet cloudOS = guest.family == .appleTVdiff --git a/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareCatalogReportTests.swift b/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareCatalogReportTests.swiftindex 37d84a14..5b36362e 100644--- a/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareCatalogReportTests.swift+++ b/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareCatalogReportTests.swift@@ -27,16 +27,22 @@ struct FirmwareCatalogReportTests {}}- @Test func `the Apple TV 4K pairs the Apple TV HD IPSW of each build with an OTA`() throws {+ @Test func `the Apple TV 4K pairs each OTA with the Apple TV HD IPSW it is restored over`() throws {let pairings = VPhoneFirmwareCatalog.pairings(for: "AppleTV14,1")- #expect(pairings.map(\.iosName) == ["tvOS 26.6"])- let hd = VPhoneFirmwareCatalog.pairings(for: "AppleTV5,3")+ #expect(pairings.map(\.iosName) == ["tvOS 26.6", "tvOS 27.0"])+ let hd = try #require(VPhoneFirmwareCatalog.pairings(for: "AppleTV5,3").first { $0.iosName == "tvOS 26.6" })for p in pairings {#expect(p.device == "AppleTV14,1")- // Restored from the HD's IPSW, on the same cloudOS.- let base = try #require(hd.first { $0.iosName == p.iosName })- #expect(p.iosURL == base.iosURL && p.cloudosURL == base.cloudosURL)+ #expect(p.cloudosURL == hd.cloudosURL)}+ // 26.6 names the HD's IPSW of its own version; 27.0, which the HD+ // never got, names its OTA, and `fw prepare` finds the base from it.+ #expect(pairings[0].iosURL == hd.iosURL)+ let ota27 = try #require(VPhoneFirmwareCatalog.otaRelease(source: pairings[1].iosURL))+ #expect(ota27.version == "27.0" && ota27.build == "24J361" && ota27.baseVersion == "26.6")+ #expect(VPhoneFirmwareCatalog.restoreBaseURL(for: ota27) == hd.iosURL)+ #expect(VPhoneFirmwareCatalog.otaRelease(source: "/cache/ota/\(ota27.fileName)") == ota27)+ #expect(VPhoneFirmwareCatalog.otaRelease(source: hd.iosURL) == nil)let ota = try #require(VPhoneFirmwareCatalog.otaRelease(for: "AppleTV14,1", build: "23L773"))#expect(ota.version == "26.6")#expect(ota.url.hasPrefix("https://updates.cdn-apple.com/") && ota.url.hasSuffix(".aea"))@@ -45,10 +51,12 @@ struct FirmwareCatalogReportTests {#expect(ota.fileName == "AppleTV14,1_26.6_23L773_OTA.aea")#expect(VPhoneFirmwareCatalog.otaRelease(for: "AppleTV14,1", build: "23L760") == nil)#expect(VPhoneFirmwareCatalog.otaRelease(for: "AppleTV5,3", build: "23L773") == nil)- // Every OTA has a base release of its version to be restored over.+ // Every OTA has a base release to be restored over.for release in VPhoneFirmwareCatalog.otaReleases {let base = try #require(VPhoneGuestDevice.named(release.productType)?.restoreBase)- #expect(VPhoneFirmwareCatalog.pairings(for: base.productType).contains { $0.iosName.hasSuffix(" \(release.version)") })+ #expect(VPhoneFirmwareCatalog.pairings(for: base.productType).contains { $0.iosName.hasSuffix(" \(release.baseVersion)") })+ #expect(VPhoneFirmwareCatalog.restoreBaseURL(for: release) != nil)+ #expect(Data(base64Encoded: release.key)?.count == 32)}}