Skip to content

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.swift
index 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) : tvSupportedGuestPatches
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
index 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.swift
index 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.swift
index 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.swift
index 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 ?? build
guard 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?.key
let 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 in
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
index 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.swift
index 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 = productType
self.version = version
self.build = build
self.url = url
self.size = size
self.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 ?? guest
var 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 in
let cloudOS = guest.family == .appleTV
diff --git a/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareCatalogReportTests.swift b/VPhoneKit/VPhoneCoreKitTests/Firmware/FirmwareCatalogReportTests.swift
index 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)
}
}