Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
10.1 KB
Raw Blame
// FirmwareGuestPatchResolution.swift — Which guest patches an installed VM should run now.
//
// A VM carries two patch records the guest half of an install reads: the plan
// `fw patch` resolved, and the selection its owner has since edited. They can
// disagree, and which one wins depends on where a patch lands.
//
// A boot-chain patch was built into the restore tree or `FirmwareOriginals` the
// moment `fw patch` ran; the bytes are already in those files, so the plan is
// the truth for them and the current selection cannot change them without
// another `fw patch`. A guest patch is different: nothing writes it until the
// guest half of an install runs, and that half runs every `cfw install` and
// `cfw update-environment`. So a guest patch should follow the current
// selection, which is both what lets `fw set-patches` then `cfw
// update-environment` turn one on and what lets it turn one off.
//
// `VPhoneCustomFirmwareInstaller.withLateGuestPatches` used to do a narrow
// version of this — it merged in a short list of guest patches newer than most
// VMs' plans, and only ever added. This resolves the whole guest half from the
// selection, both directions, and the installer's late-patch list is gone.

import Foundation
import VPhonePatchKit

public enum FirmwareGuestPatchResolution {
    /// CoreFSCache's original reuse flag also bypasses the compiler key.
    /// Versioning the driver cannot invalidate stale output unless that key
    /// check is retained, or cross-boot reuse is turned off altogether.
    public static func missingCompilerCacheDependencies(enabled: Set<String>, applied: Set<String>? = nil) -> [String] {
        guard enabled.contains(FirmwareGuestSystemPatchSet.paravirtGPUCompilerCache),
              enabled.contains(FirmwareGuestSystemPatchSet.metalCacheReuse),
              !(applied ?? enabled).contains(FirmwareGuestSystemPatchSet.metalCacheReuseKey)
        else { return [] }
        return [FirmwareGuestSystemPatchSet.metalCacheReuseKey]
    }

    public static let glesPrimitiveRestartDependencies: Set<String> = [
        FirmwareGuestSystemPatchSet.paravirtGPUPrimitiveRestart,
        FirmwareGuestSystemPatchSet.metalVertexIDFormat,
    ]

    /// The primitive-buffer fallback still uses the driver's render-state
    /// setup and private builtin vertex formats. Reject an incomplete choice
    /// before mounting or writing the guest; opting out remains unrestricted.
    public static func missingGLESPrimitiveRestartDependencies(enabled: Set<String>) -> [String] {
        guard enabled.contains(FirmwareGuestSystemPatchSet.glesPrimitiveRestart) else { return [] }
        return glesPrimitiveRestartDependencies.subtracting(enabled).sorted()
    }

    /// TV admits the gigalocker repair, opt-in dyld TPRO compatibility, virtual
    /// Bluetooth, and vphoned with the launchd cache gate its launchd.plist entry needs.
    /// Other payloads, cache patches and shell integration need a TV port and
    /// validation before the installer can select them.
    public static let tvSupportedGuestPatches: Set<String> = [
        FirmwareGuestSystemPatchSet.virtualBluetooth,
        "system-seputil-boot-gigalocker_uuid",
        "system-gigalocker-boot-rename",
        FirmwareGuestSystemPatchSet.tvTPRO,
        "system-vphoned-boot-install",
        "system-launchd_cache_loader-boot-unsecure_cache_gate",
    ]

    /// An arm64e Apple TV (the 4K, from its OTA) also admits the paravirtual
    /// 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.
    /// It admits the environment's launchd hook and SystemHook too, marked
    /// tvOS at install, with the launchd patch that loads the hook: both are
    /// arm64e, so a plain-arm64 launchd could not load them.
    public static let tvArm64eGuestPatches: Set<String> = Set([
        "system-extensions-boot-gpu_bundle",
        FirmwareGuestSystemPatchSet.tvOTAUserland,
        FirmwareGuestSystemPatchSet.tvSetupDisplayLookup,
        FirmwareGuestSystemPatchSet.tvSetupFocus,
        FirmwareGuestSystemPatchSet.tvLocalActivation,
        FirmwareGuestSystemPatchSet.tvLegacySetup,
        "system-launchdaemons-boot-environment",
        "system-launchd-boot-jetsam_panic_guard_bypass",
    ]).union(FirmwarePatchSetCatalog.tvOS27UserlandPatches)

    public static func unvalidatedTVGuestPatches(enabled: Set<String>, arm64eUserland: Bool = false) -> [String] {
        let admitted = arm64eUserland ? tvSupportedGuestPatches.union(tvArm64eGuestPatches) : tvSupportedGuestPatches
        return enabled.intersection(guestTargetIdentifiers).subtracting(admitted).sorted()
    }

    /// HomePod has its own arm64e IPSW. Sharing TVOS does not admit the
    /// Apple TV OTA swap, GPU injection, or plain-arm64 dyld workarounds.
    public static let homePodSupportedGuestPatches = tvSupportedGuestPatches
        .subtracting([FirmwareGuestSystemPatchSet.tvTPRO])
        .union([FirmwareGuestSystemPatchSet.homePodTopCap, FirmwareGuestSystemPatchSet.homePodSetupBypass, FirmwareGuestSystemPatchSet.homePodAirPlayVM,
                FirmwareGuestSystemPatchSet.homePodAudioProduct, FirmwareGuestSystemPatchSet.homePodWelcome,
                FirmwareGuestSystemPatchSet.homePodSiriSpeech,
                FirmwareGuestSystemPatchSet.homePodOTAUserland, FirmwareGuestSystemPatchSet.homePodSoundGlow,
                FirmwareGuestSystemPatchSet.homePodCryptexStaging, FirmwareGuestSystemPatchSet.homePodCryptexClass,
                FirmwareGuestSystemPatchSet.installCoordinationPersona,
                FirmwareGuestSystemPatchSet.homePodAdHocInstall,
                FirmwareGuestSystemPatchSet.virtioSoundDriver])
        // Userspace debugging: debugserver attached on a HomePod Software 27.0 guest.
        .union(["system-debugserver-cfw-install", "system-launchd-boot-jetsam_panic_guard_bypass"])
        .union(FirmwarePatchSetCatalog.tvOS27UserlandPatches)

    public static func unvalidatedHomePodGuestPatches(enabled: Set<String>) -> [String] {
        enabled.intersection(guestTargetIdentifiers).subtracting(homePodSupportedGuestPatches).sorted()
    }

    /// HomeView uses its own shell and setup. Sharing the tvOS ABI does not
    /// admit Apple TV setup/focus/activation adapters or HomePod capabilities.
    public static let homeViewSupportedGuestPatches = tvSupportedGuestPatches
        .union(tvArm64eGuestPatches)
        .subtracting([FirmwareGuestSystemPatchSet.tvTPRO, FirmwareGuestSystemPatchSet.tvLegacySetup,
                     FirmwareGuestSystemPatchSet.tvSetupDisplayLookup, FirmwareGuestSystemPatchSet.tvSetupFocus,
                     FirmwareGuestSystemPatchSet.tvLocalActivation])
        .union([FirmwareGuestSystemPatchSet.homeViewProfileLookup, FirmwareGuestSystemPatchSet.homeViewDisplayLookups, FirmwareGuestSystemPatchSet.homeViewSetupBypass, FirmwareGuestSystemPatchSet.homeViewEnvironmentService])

    public static func unvalidatedHomeViewGuestPatches(enabled: Set<String>) -> [String] {
        enabled.intersection(guestTargetIdentifiers).subtracting(homeViewSupportedGuestPatches).sorted()
    }

    public static let homePodWelcomeDependencies: Set<String> = [
        "system-vphoned-boot-install",
        FirmwareGuestSystemPatchSet.homePodTopCap,
        FirmwareGuestSystemPatchSet.homePodSetupBypass,
        FirmwareGuestSystemPatchSet.virtioSoundDriver,
        FirmwareGuestSystemPatchSet.homePodSiriSpeech,
    ]

    /// A welcome opt-out remains installable when any prerequisite is also off.
    /// This checks the current guest selection before any filesystem writes;
    /// the guest runtime must still verify readiness before consuming its claim.
    public static func missingHomePodWelcomeDependencies(enabled: Set<String>) -> [String] {
        guard enabled.contains(FirmwareGuestSystemPatchSet.homePodWelcome) else { return [] }
        return homePodWelcomeDependencies.subtracting(enabled).sorted()
    }

    public static let homePodSiriSpeechDependencies: Set<String> = [
        "system-vphoned-boot-install",
        FirmwareGuestSystemPatchSet.homePodTopCap,
        FirmwareGuestSystemPatchSet.virtioSoundDriver,
    ]

    public static func missingHomePodSiriSpeechDependencies(enabled: Set<String>) -> [String] {
        guard enabled.contains(FirmwareGuestSystemPatchSet.homePodSiriSpeech) else { return [] }
        return homePodSiriSpeechDependencies.subtracting(enabled).sorted()
    }

    public static let homePodSoundGlowDependencies: Set<String> = [
        "system-vphoned-boot-install",
        FirmwareGuestSystemPatchSet.homePodTopCap,
    ]

    public static func missingHomePodSoundGlowDependencies(enabled: Set<String>) -> [String] {
        guard enabled.contains(FirmwareGuestSystemPatchSet.homePodSoundGlow) else { return [] }
        return homePodSoundGlowDependencies.subtracting(enabled).sorted()
    }

    /// Every bundled-set patch whose bytes the guest half of an install writes —
    /// the dyld shared cache, a guest Mach-O, its entitlements, a guest file, or
    /// the Preboot device tree. The complement is the boot chain, which `fw
    /// patch` owns.
    public static var guestTargetIdentifiers: Set<String> {
        Set(
            FirmwarePatchSetCatalog.allDeclarations
                .filter { !$0.target.isBootChain }
                .map(\.identifier),
        )
    }

    /// The identifiers the guest half should apply now: boot-chain patches as
    /// the plan resolved them, guest patches as the current selection resolves
    /// them. A guest patch the plan had on but the selection now blocks drops
    /// out; one the plan never had but the selection now allows comes in.
    public static func effectiveEnabled(
        planEnabled: Set<String>,
        selectionEnabled: Set<String>,
    ) -> Set<String> {
        let guest = guestTargetIdentifiers
        return planEnabled.subtracting(guest).union(selectionEnabled.intersection(guest))
    }

    /// The guest patches a selection leaves off — the ones a run should try to
    /// revert. Boot-chain patches are never here: this is only about the guest
    /// half.
    public static func guestPatchesOff(selectionEnabled: Set<String>) -> Set<String> {
        guestTargetIdentifiers.subtracting(selectionEnabled)
    }
}