Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
17.1 KB
Raw Blame
import Foundation

// MARK: - Guest Device

/// The Apple device whose restore IPSW supplies the guest's OS image.
///
/// The boot chain, kernel, SEP and device tree always come from the PCC
/// `vresearch101ap` / `vphone600ap` identities. Only the userland changes with
/// the device: an iPhone17,3 IPSW gives the guest iOS, an iPad IPSW gives it
/// iPadOS. The device tree then has to present the matching idiom, artwork
/// and product type, or the iPadOS userland lays itself out as a phone.
///
/// The identity and `/product` values come from the device's own
/// `DeviceTree.<deviceClass>.im4p`, which the IPSW carries and `fw prepare`
/// keeps in the restore tree. What a device tree does not say — the panel's
/// size and density — is recorded here.
public struct VPhoneGuestDevice: Sendable, Equatable {
    public enum Family: String, Codable, Sendable {
        case iPhone
        case iPad
        case appleTV
        case homePod
        case homeView
        case watch

        public var osName: String {
            switch self {
            case .iPhone: "iOS"
            case .iPad: "iPadOS"
            case .appleTV: "tvOS"
            case .homePod: "HomePod Software"
            case .homeView: "HomeView Software"
            case .watch: "watchOS"
            }
        }

        /// Apple TV, HomePod and HomeView share the tvOS executable platform and
        /// filesystem layout. Their user interfaces and device idioms differ.
        public var usesTVOS: Bool {
            self == .appleTV || self == .homePod || self == .homeView
        }
    }

    public let family: Family
    /// `Ap,ProductType`, e.g. `iPad16,1`.
    public let productType: String
    /// BuildManifest `DeviceClass`, and the board in `DeviceTree.<board>.im4p`.
    public let deviceClass: String
    /// The marketing name, for logs and prompts.
    public let productName: String
    /// The guest display: a device panel, or a provisional virtual canvas.
    public let screen: VPhoneVirtualMachineManifest.ScreenConfig

    public init(
        family: Family,
        productType: String,
        deviceClass: String,
        productName: String,
        screen: VPhoneVirtualMachineManifest.ScreenConfig,
    ) {
        self.family = family
        self.productType = productType
        self.deviceClass = deviceClass
        self.productName = productName
        self.screen = screen
    }

    public var isPad: Bool {
        family == .iPad
    }

    public var usesTVOS: Bool {
        family.usesTVOS
    }

    /// Whether the guest boots a device tree of its own that presents this
    /// board, built by `fw patch` from the board's tree in the IPSW. Every
    /// device but the iPhone XS Max does; it keeps the fixed D47 identity
    /// `cfw install` writes into the restored tree.
    public var presentsBoard: Bool {
        notchedArtworkSubtype == nil
    }

    /// The artwork subtype of a guest presented as the iPhone17,3 whose own
    /// userland has none of the iPhone 16's: the XS family's asset catalogs
    /// only carry 2436 and 2688 artwork, and its SpringBoard no Dynamic Island
    /// layout. Without it Hello and the wallpaper stay empty and the home
    /// gesture breaks. Nil for every other device.
    public var notchedArtworkSubtype: Int? {
        productType == "iPhone11,6" ? 2688 : nil
    }

    // MARK: - Known Devices

    /// iPhone 16 (D47AP), the device every catalog IPSW targets.
    public static let iPhone17_3 = VPhoneGuestDevice(
        family: .iPhone,
        productType: "iPhone17,3",
        deviceClass: "d47ap",
        productName: "iPhone 16",
        screen: .default,
    )

    private static func iPhone(
        _ productType: String,
        _ deviceClass: String,
        _ productName: String,
        width: Int,
        height: Int,
    ) -> VPhoneGuestDevice {
        VPhoneGuestDevice(
            family: .iPhone,
            productType: productType,
            deviceClass: deviceClass,
            productName: productName,
            screen: .init(width: width, height: height, pixelsPerInch: 460, scale: 3.0),
        )
    }

    /// Experimental iPhone 15 / iOS 17.7 desktop bring-up on cloudOS 26.1.
    public static let iPhone15_4 = iPhone("iPhone15,4", "d37ap", "iPhone 15", width: 1179, height: 2556)

    /// Local iOS 16.6.1 bring-up experiment on cloudOS 26.1.
    public static let iPhone15_2 = iPhone("iPhone15,2", "d73ap", "iPhone 14 Pro", width: 1179, height: 2556)

    /// iPhone 16 Pro: 1206x2622, 402x874 points.
    public static let iPhone17_1 = iPhone("iPhone17,1", "d93ap", "iPhone 16 Pro", width: 1206, height: 2622)
    /// iPhone 16 Pro Max: 1320x2868, 440x956 points.
    public static let iPhone17_2 = iPhone("iPhone17,2", "d94ap", "iPhone 16 Pro Max", width: 1320, height: 2868)
    /// iPhone 16 Plus: 1290x2796, 430x932 points.
    public static let iPhone17_4 = iPhone("iPhone17,4", "d48ap", "iPhone 16 Plus", width: 1290, height: 2796)
    /// iPhone 16e: 1170x2532, 390x844 points.
    public static let iPhone17_5 = iPhone("iPhone17,5", "v59ap", "iPhone 16e", width: 1170, height: 2532)
    /// iPhone 17 Pro: 1206x2622, 402x874 points.
    public static let iPhone18_1 = iPhone("iPhone18,1", "v53ap", "iPhone 17 Pro", width: 1206, height: 2622)
    /// iPhone 17 Pro Max: 1320x2868, 440x956 points.
    public static let iPhone18_2 = iPhone("iPhone18,2", "v54ap", "iPhone 17 Pro Max", width: 1320, height: 2868)
    /// iPhone 17: 1206x2622, 402x874 points.
    public static let iPhone18_3 = iPhone("iPhone18,3", "v57ap", "iPhone 17", width: 1206, height: 2622)
    /// iPhone Air: 1260x2736, 420x912 points.
    public static let iPhone18_4 = iPhone("iPhone18,4", "d23ap", "iPhone Air", width: 1260, height: 2736)
    /// iPhone 17e: 1170x2532, 390x844 points.
    public static let iPhone18_5 = iPhone("iPhone18,5", "v159ap", "iPhone 17e", width: 1170, height: 2532)
    /// iPhone 18 Pro (V63AP): 1206x2622, 402x874 points.
    public static let iPhone19_2 = iPhone("iPhone19,2", "v63ap", "iPhone 18 Pro", width: 1206, height: 2622)

    /// iPhone Duo (V68AP). The VM's panel is its outer display (the cover); the
    /// guest publishes the inner display as a second, virtual display and shows
    /// it on that panel while the device is open (libvphonefolddisplay).
    public static let iPhone19_4 = iPhone("iPhone19,4", "v68ap", "iPhone Duo", width: 1398, height: 2034)

    /// iPhone XS Max: 1242x2688 at 458 ppi, 414x896 points. Its IPSW carries the
    /// iOS 18 releases after 18.6, which the iPhone 16 never got; the research
    /// board's own iOS 18 kernel boots it (the 18.x kernelcache recipes, `minimal`
    /// only). It is presented as the iPhone17,3 with its own artwork
    /// (`notchedArtworkSubtype`).
    public static let iPhone11_6 = VPhoneGuestDevice(
        family: .iPhone,
        productType: "iPhone11,6",
        deviceClass: "d331pap",
        productName: "iPhone XS Max",
        screen: .init(width: 1242, height: 2688, pixelsPerInch: 458, scale: 3.0),
    )

    private static func iPad(
        _ productType: String,
        _ deviceClass: String,
        _ productName: String,
        width: Int,
        height: Int,
        pixelsPerInch: Int = 264,
    ) -> VPhoneGuestDevice {
        VPhoneGuestDevice(
            family: .iPad,
            productType: productType,
            deviceClass: deviceClass,
            productName: productName,
            screen: .init(width: width, height: height, pixelsPerInch: pixelsPerInch, scale: 2.0),
        )
    }

    /// iPad mini (A17 Pro): 8.3-inch, 1488x2266 at 326 ppi, 744x1133 points.
    public static let iPad16_1 = iPad("iPad16,1", "j410ap", "iPad mini (A17 Pro)", width: 1488, height: 2266, pixelsPerInch: 326)
    /// iPad (A16): 11-inch, 1640x2360, 820x1180 points.
    public static let iPad15_7 = iPad("iPad15,7", "j481ap", "iPad (A16)", width: 1640, height: 2360)
    /// iPad Air 11-inch (M3): 1640x2360, 820x1180 points.
    public static let iPad15_3 = iPad("iPad15,3", "j607ap", "iPad Air 11-inch (M3)", width: 1640, height: 2360)
    /// iPad Air 13-inch (M3): 2048x2732, 1024x1366 points.
    public static let iPad15_5 = iPad("iPad15,5", "j637ap", "iPad Air 13-inch (M3)", width: 2048, height: 2732)
    /// iPad Pro 11-inch (M4): 1668x2420, 834x1210 points.
    public static let iPad16_3 = iPad("iPad16,3", "j717ap", "iPad Pro 11-inch (M4)", width: 1668, height: 2420)
    /// iPad Pro 13-inch (M4): 2064x2752, 1032x1376 points.
    public static let iPad16_5 = iPad("iPad16,5", "j720ap", "iPad Pro 13-inch (M4)", width: 2064, height: 2752)
    /// iPad Pro 11-inch (M5): 1668x2420, 834x1210 points.
    public static let iPad17_1 = iPad("iPad17,1", "j817ap", "iPad Pro 11-inch (M5)", width: 1668, height: 2420)
    /// iPad Pro 13-inch (M5): 2064x2752, 1032x1376 points.
    public static let iPad17_3 = iPad("iPad17,3", "j820ap", "iPad Pro 13-inch (M5)", width: 2064, height: 2752)

    /// Apple TV HD donor; the documented 26.4 beta pairing boots
    /// with explicit TV patches. No general catalog pairing is advertised.
    /// J42d's device tree supplies the TV idiom and 1x scale. The 1080p canvas
    /// and 72 ppi are provisional VM settings, not an attached television's density.
    public static let appleTV5_3 = VPhoneGuestDevice(
        family: .appleTV,
        productType: "AppleTV5,3",
        deviceClass: "j42dap",
        productName: "Apple TV HD",
        screen: .init(width: 1920, height: 1080, pixelsPerInch: 72, scale: 1.0),
    )

    /// Apple TV 4K (3rd generation), research only: Apple ships it no IPSW,
    /// so its arm64e userland comes from an OTA over a restored Apple TV HD
    /// (`system-tv-exp-ota_userland`). J255's device tree supplies the 2x
    /// identity; 3840x2160 is the panel it drives at 4K.
    public static let appleTV14_1 = VPhoneGuestDevice(
        family: .appleTV,
        productType: "AppleTV14,1",
        deviceClass: "j255ap",
        productName: "Apple TV 4K (3rd generation)",
        screen: .init(width: 3840, height: 2160, pixelsPerInch: 144, scale: 2.0),
    )

    /// Apple TV 4K (4th generation), J265AP. Its tvOS 27.2 userland and
    /// device tree come from a full OTA over the Apple TV HD restore base.
    /// The virtual display uses the same 4K canvas as the 3rd generation.
    public static let appleTV18_1 = VPhoneGuestDevice(
        family: .appleTV,
        productType: "AppleTV18,1",
        deviceClass: "j265ap",
        productName: "Apple TV 4K (4th generation)",
        screen: .init(width: 3840, height: 2160, pixelsPerInch: 144, scale: 2.0),
    )

    /// HomeView's two OTA board identities. The square 1088-pixel canvas is
    /// provisional; the donor tree supplies the home idiom and 2x artwork scale.
    public static let homeAccessory17_1 = VPhoneGuestDevice(
        family: .homeView,
        productType: "HomeAccessory17,1",
        deviceClass: "j490ap",
        productName: "HomeView (J490)",
        screen: .init(width: 1088, height: 1088, pixelsPerInch: 264, scale: 2.0),
    )

    public static let homeAccessory17_2 = VPhoneGuestDevice(
        family: .homeView,
        productType: "HomeAccessory17,2",
        deviceClass: "j491ap",
        productName: "HomeView (J491)",
        screen: .init(width: 1088, height: 1088, pixelsPerInch: 264, scale: 2.0),
    )

    /// HomePod mini (B520AP). It has no physical display; this small virtual
    /// canvas satisfies the VM graphics configuration and is not a panel
    /// specification or a promise of a graphical HomePod interface.
    public static let audioAccessory5_1 = VPhoneGuestDevice(
        family: .homePod,
        productType: "AudioAccessory5,1",
        deviceClass: "b520ap",
        productName: "HomePod mini",
        screen: .init(width: 320, height: 320, pixelsPerInch: 72, scale: 1.0),
    )

    /// Apple Watch Series 11 (GPS), 46 mm: 416x496 at 326 ppi, 208x248 points.
    /// The research board's kernel boots it with the watchOS kexts of its IPSW
    /// (the `watch` kernelcache recipe); N227b's device tree supplies the watch
    /// idiom and 2x identity.
    public static let watch7_18 = VPhoneGuestDevice(
        family: .watch,
        productType: "Watch7,18",
        deviceClass: "n227bap",
        productName: "Apple Watch Series 11 (GPS)",
        screen: .init(width: 416, height: 496, pixelsPerInch: 326, scale: 2.0),
    )

    /// Whether the guest's userland is plain arm64 rather than arm64e: only
    /// the Apple TV HD's. HomePod mini 27.0 ships arm64e dyld and launchd.
    /// The Apple TV HD has no paravirtual GPU driver to load, and its
    /// dyld needs the TV TPRO patches.
    public var hasPlainArm64Userland: Bool {
        self == .appleTV5_3
    }

    /// The device whose IPSW is restored under this one, for a device Apple
    /// ships no IPSW for: the Apple TV HD under the Apple TV 4K, whose own
    /// device tree and userland `fw prepare` takes from its OTA. HomeView uses
    /// the same restore base with its own board tree and full OTA. Nil for every
    /// device restored from its own IPSW.
    public var restoreBase: VPhoneGuestDevice? {
        self == .appleTV14_1 || self == .appleTV18_1 || family == .homeView ? .appleTV5_3 : nil
    }

    public static let known: [VPhoneGuestDevice] = [
        iPhone17_3,
        iPhone17_4, iPhone17_1, iPhone17_2, iPhone17_5,
        iPhone18_3, iPhone18_4, iPhone18_1, iPhone18_2, iPhone18_5,
        iPhone19_2, iPhone19_4,
        iPhone11_6, iPhone15_4, iPhone15_2,
        iPad16_1,
        iPad15_7,
        iPad15_3, iPad15_5,
        iPad16_3, iPad16_5,
        iPad17_1, iPad17_3,
        appleTV5_3, appleTV14_1, appleTV18_1,
        audioAccessory5_1, homeAccessory17_1, homeAccessory17_2,
        watch7_18,
    ]

    /// Cellular models that ship in the same IPSW as a known Wi-Fi model and map
    /// onto it: the VM has no baseband, so it gets the Wi-Fi identity.
    static let aliases: [String: String] = [
        "iPhone11,4": "iPhone11,6",
        "iPad16,2": "iPad16,1",
        "iPad15,4": "iPad15,3",
        "iPad15,6": "iPad15,5",
        "iPad16,4": "iPad16,3",
        "iPad16,6": "iPad16,5",
        "iPad17,2": "iPad17,1",
        "iPad17,4": "iPad17,3",
    ]

    /// The device a VM has when its configuration names none: every VM made
    /// before iPad guests existed is an iPhone17,3.
    public static let `default` = iPhone17_3

    public static func named(_ productType: String?) -> VPhoneGuestDevice? {
        guard let productType else { return nil }
        let canonical = aliases[productType] ?? productType
        return known.first { $0.productType == canonical }
    }

    // MARK: - Restore Tree

    /// The folder `fw prepare` builds the restore tree in.
    ///
    /// Every reader of the tree — restore, `cfw install`, Launchpad's cleanup —
    /// matches `iPhone*_Restore`, so non-iPhone trees keep that prefix as a
    /// restore-tree compatibility convention.
    public func restoreTreeName(version: String, build: String) -> String {
        switch family {
        case .iPhone: "\(productType)_\(version)_\(build)_Restore"
        case .iPad, .appleTV, .homePod, .homeView, .watch: "iPhoneOS_\(productType)_\(version)_\(build)_Restore"
        }
    }

    /// Where the restore tree keeps this device's own device tree.
    public var boardDeviceTreePath: String {
        "Firmware/all_flash/DeviceTree.\(deviceClass).im4p"
    }

    // MARK: - Detection

    /// The device a restore BuildManifest is for, from its
    /// `SupportedProductTypes`. One IPSW often covers several models — an 11-
    /// and a 13-inch iPad and their cellular twins — so `preferring` names the
    /// one wanted; without it, or when the IPSW does not cover it, the first
    /// known model wins. Nil when the manifest names no known device.
    public static func detect(buildManifest: [String: Any], preferring productType: String? = nil) -> VPhoneGuestDevice? {
        let types = buildManifest["SupportedProductTypes"] as? [String] ?? []
        if let productType, types.contains(productType), let device = named(productType) {
            return device
        }
        for type in types {
            if let device = named(type) {
                return device
            }
        }
        return nil
    }

    public static func detect(buildManifestAt url: URL, preferring productType: String? = nil) -> VPhoneGuestDevice? {
        guard let data = try? Data(contentsOf: url),
              let plist = try? PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any]
        else { return nil }
        return detect(buildManifest: plist, preferring: productType)
    }

    /// Every known device a restore BuildManifest can supply.
    public static func covered(by buildManifest: [String: Any]) -> [VPhoneGuestDevice] {
        let types = buildManifest["SupportedProductTypes"] as? [String] ?? []
        var devices: [VPhoneGuestDevice] = []
        for type in types {
            if let device = named(type), !devices.contains(device) {
                devices.append(device)
            }
        }
        return devices
    }

    /// Whether a restore BuildManifest is for an iPad at all, known or not.
    public static func isPadManifest(_ buildManifest: [String: Any]) -> Bool {
        let types = buildManifest["SupportedProductTypes"] as? [String] ?? []
        return types.contains { $0.hasPrefix("iPad") }
    }
}