Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
23.5 KB
Raw Blame
import Dynamic
import Foundation
import Virtualization
import VPhoneCoreKit

/// Minimal VM for booting a vphone (virtual iPhone) in DFU mode.
@MainActor
class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {
    let virtualMachine: VZVirtualMachine
    /// The configuration actually used by this VM, rather than a pending preference.
    let usesHardwareKeyboard: Bool
    /// The manifest's unlock-at-startup setting as the VM started with it.
    let unlocksAtStartup: Bool
    /// The manifest's Sync Host Location setting as the VM started with it.
    let syncsHostLocation: Bool
    /// ECID hex string resolved from machineIdentifier (e.g. "0x0012345678ABCDEF").
    let ecidHex: String?
    private nonisolated let shaderCache: VPhoneShaderCache.Session?
    /// Read handle for VM serial output.
    private var serialOutputReadHandle: FileHandle?
    private var serialInputSource: DispatchSourceRead?
    /// Synthetic battery source for runtime charge/connectivity updates.
    private var batterySource: AnyObject?
    /// The in-process network backing `.tunnel` mode; nil for every other mode.
    /// Held because the sockets live only as long as this reference does.
    private var userspaceNetwork: VPhoneUserspaceNetwork?
    /// How the manifest's network was realized: attachment, MAC, the address
    /// vphoned should hold the guest to, and the ports forwarded into it.
    private(set) var networkPlan: VPhoneNetworkPlan?
    /// The attachment the VM booted with, put back by `setNetworkLink(up: true)`
    /// after a runtime change.
    private var bootAttachment: VZNetworkDeviceAttachment?

    struct Options {
        var configURL: URL
        var romURL: URL?
        var nvramURL: URL
        var diskURL: URL
        var cpuCount: Int = 8
        var memorySize: UInt64 = 8 * 1024 * 1024 * 1024
        var sepStorageURL: URL
        var sepRomURL: URL?
        var screenWidth: Int = 1290
        var screenHeight: Int = 2796
        var screenPPI: Int = 460
        var screenScale: Double = 3.0
        var kernelDebugPort: Int?
        /// The guest runs iPadOS: Esc is a key there, not the back gesture.
        var isPadGuest = false
        var usesTVOS = false
        var isTVGuest = false
        var isHomePodGuest = false
        var isHomeViewGuest = false
        /// The guest runs watchOS: its side button is a key of its own (consumer
        /// Help), apart from the crown (Home) and the power key.
        var isWatchGuest = false
        /// The guest is a foldable whose panel is sized per posture at boot;
        /// its window persists the position for the next start.
        var isFoldableGuest = false
    }

    private struct DeviceIdentity {
        let ecid: UInt64
        let cpidHex: String
        let ecidHex: String
        let udid: String
    }

    init(options: Options) throws {
        try Self.checkBundleFiles(options)

        // --- Hardware model (PV=3) ---
        let hwModel = try VPhoneHardware.createModel()
        print("[vphone] PV=3 hardware model: isSupported = true")

        // --- Load or create machineIdentifier from manifest ---
        let machineIdentifier: VZMacMachineIdentifier
        var manifest = try VPhoneVirtualMachineManifest.load(from: options.configURL)

        if !manifest.machineIdentifier.isEmpty,
           let savedID = VZMacMachineIdentifier(dataRepresentation: manifest.machineIdentifier)
        {
            machineIdentifier = savedID
            print("[vphone] Loaded machineIdentifier from config.plist (ECID stable)")
        } else {
            let reason = manifest.machineIdentifier.isEmpty
                ? "Created new machineIdentifier -> saved to config.plist"
                : "Invalid machineIdentifier in config.plist, created new"
            let newID = VZMacMachineIdentifier()
            machineIdentifier = newID

            manifest = manifest.updating(machineIdentifier: newID.dataRepresentation)
            try manifest.write(to: options.configURL)
            try VPhoneHostFilePermissions.makeAccessible(at: options.configURL)

            print("[vphone] \(reason)")
        }

        // --- MAC: generated once, then kept, like the machine identifier ---
        // A fixed MAC keeps the guest on one DHCP lease and is what a custom
        // NAT network reserves its address for.
        if manifest.networkConfig.mode != .off, manifest.networkConfig.macAddress.isEmpty {
            let mac = VPhoneMACAddress.randomLocallyAdministered()
            manifest = manifest.updating(networkConfig: manifest.networkConfig.with(macAddress: mac.description))
            try manifest.write(to: options.configURL)
            try VPhoneHostFilePermissions.makeAccessible(at: options.configURL)
            print("[vphone] Created MAC address \(mac) -> saved to config.plist")
        }

        // --- Platform ---
        let platform = VZMacPlatformConfiguration()
        platform.machineIdentifier = machineIdentifier

        if let identity = Self.resolveDeviceIdentity(machineIdentifier: machineIdentifier) {
            ecidHex = identity.ecidHex
            print("[vphone] ECID: \(identity.ecidHex)")
            print("[vphone] Predicted UDID: \(identity.udid)")
            // The cache only saves recompiling; a VM that cannot keep one boots without it.
            do {
                let shaderCache = try VPhoneShaderCache.prepare(
                    machineDirectory: options.configURL.deletingLastPathComponent(), ecid: identity.ecid,
                )
                self.shaderCache = shaderCache
                print("[vphone] Shader cache: \(shaderCache.cacheURL.path)")
            } catch {
                shaderCache = nil
                print("[vphone] Warning: shader cache not kept for this run: \(error.localizedDescription)")
            }
            let outputURL = options.configURL.deletingLastPathComponent().appendingPathComponent(
                "udid-prediction.txt",
            )
            do {
                try Self.writeUDIDPrediction(identity: identity, to: outputURL)
                try VPhoneHostFilePermissions.makeAccessible(at: outputURL)
                print("[vphone] Wrote UDID prediction: \(outputURL.path)")
            } catch {
                print("[vphone] Warning: failed to write udid-prediction.txt: \(error)")
            }
        } else {
            ecidHex = nil
            shaderCache = nil
            print("[vphone] Warning: failed to resolve ECID from machineIdentifier")
        }

        let auxStorage: VZMacAuxiliaryStorage = if try VPhoneVirtualMachineManifest.requireRegularFileIfPresent(at: options.nvramURL) {
            VZMacAuxiliaryStorage(url: options.nvramURL)
        } else {
            try VZMacAuxiliaryStorage(
                creatingStorageAt: options.nvramURL,
                hardwareModel: hwModel,
                options: [],
            )
        }
        try VPhoneHostFilePermissions.makeAccessible(at: options.nvramURL)
        platform.auxiliaryStorage = auxStorage
        platform.hardwareModel = hwModel

        // No boot-args are set here. The guest's come from the iBEC/LLB patch
        // (IBootPatcher.bootArgs and extraBootArgs), applied by `cfw install`:
        // the research iBoot reads its own NVRAM banks in this file, not the
        // store VZMacAuxiliaryStorage writes, so an NVRAM value set from the
        // host never reaches the guest.

        // --- Boot loader with custom ROM ---
        let bootloader = VZMacOSBootLoader()
        if let romURL = options.romURL {
            Dynamic(bootloader)._setROMURL(romURL)
        }

        // --- VM Configuration ---
        let config = VZVirtualMachineConfiguration()
        config.bootLoader = bootloader
        config.platform = platform
        config.cpuCount = max(options.cpuCount, VZVirtualMachineConfiguration.minimumAllowedCPUCount)
        config.memorySize = max(
            options.memorySize,
            VZVirtualMachineConfiguration.minimumAllowedMemorySize,
        )

        // Display
        let gfx = VZMacGraphicsDeviceConfiguration()
        gfx.displays = [
            VZMacGraphicsDisplayConfiguration(
                widthInPixels: options.screenWidth,
                heightInPixels: options.screenHeight,
                pixelsPerInch: options.screenPPI,
            ),
        ]
        config.graphicsDevices = [gfx]

        // Audio
        let afg = VZVirtioSoundDeviceConfiguration()
        let inputAudioStreamConfiguration = VZVirtioSoundDeviceInputStreamConfiguration()
        let outputAudioStreamConfiguration = VZVirtioSoundDeviceOutputStreamConfiguration()
        inputAudioStreamConfiguration.source = VZHostAudioInputStreamSource()
        outputAudioStreamConfiguration.sink = VZHostAudioOutputStreamSink()
        afg.streams = [inputAudioStreamConfiguration, outputAudioStreamConfiguration]
        config.audioDevices = [afg]

        // Storage
        guard try VPhoneVirtualMachineManifest.requireRegularFileIfPresent(at: options.diskURL) else {
            throw VPhoneVirtualMachineError.diskNotFound(options.diskURL.path)
        }
        let attachment = try VPhoneDiskAttachment.make(url: options.diskURL, readOnly: false)
        config.storageDevices = [VZVirtioBlockDeviceConfiguration(attachment: attachment)]

        // Network (mode, MAC, address and forwards from the bundle manifest)
        let plan = try VPhoneNetworking.plan(manifest.networkConfig)
        let network = try VPhoneNetworking.makeNetworkDevice(plan)
        config.networkDevices = network.configuration.map { [$0] } ?? []
        networkPlan = plan
        userspaceNetwork = network.userspaceNetwork
        print("[vphone] Network: \(Self.describe(plan))")

        // Serial port (PL011 UART - pipes for input/output with boot detection)
        if let serialPort = Dynamic._VZPL011SerialPortConfiguration().asObject
            as? VZSerialPortConfiguration
        {
            let inputPipe = Pipe()
            let outputPipe = Pipe()

            serialPort.attachment = VZFileHandleSerialPortAttachment(
                fileHandleForReading: inputPipe.fileHandleForReading,
                fileHandleForWriting: outputPipe.fileHandleForWriting,
            )

            // Forward host stdin -> VM serial input
            let writeHandle = inputPipe.fileHandleForWriting
            let stdinFD = FileHandle.standardInput.fileDescriptor
            let inputSource = DispatchSource.makeReadSource(
                fileDescriptor: stdinFD, queue: .global(qos: .userInteractive),
            )
            inputSource.setEventHandler { @Sendable [weak inputSource] in
                var buf = [UInt8](repeating: 0, count: 4096)
                let n = read(stdinFD, &buf, buf.count)
                if n > 0 {
                    try? writeHandle.write(contentsOf: Data(buf[..<n]))
                } else if n == 0 || errno != EINTR {
                    inputSource?.cancel()
                }
            }
            inputSource.setCancelHandler { @Sendable in try? writeHandle.close() }
            inputSource.activate()
            serialInputSource = inputSource

            serialOutputReadHandle = outputPipe.fileHandleForReading

            config.serialPorts = [serialPort]
            print("[vphone] PL011 serial port attached (interactive)")
        }

        if let obj1 = Dynamic._VZMacVideoToolboxDeviceConfiguration().asObject,
           let obj2 = Dynamic._VZMacNeuralEngineDeviceConfiguration().asObject,
           let obj3 = Dynamic._VZMacScalerAcceleratorDeviceConfiguration().asObject
        {
            Dynamic(config)._setAcceleratorDevices([obj1, obj2, obj3])
            print("[vphone] Accelerator devices configured")
        }

        // Multi-touch (USB touch screen)
        if let obj = Dynamic._VZUSBTouchScreenConfiguration().asObject {
            Dynamic(config)._setMultiTouchDevices([obj])
            print("[vphone] USB touch screen configured")
        }

        let obj = VZVirtioEntropyDeviceConfiguration()
        config.entropyDevices = [obj]
        print("[vphone] Entropy device configured")

        unlocksAtStartup = manifest.unlocksScreenAtStartup
        syncsHostLocation = manifest.sharesHostLocation
        usesHardwareKeyboard = manifest.usesHardwareKeyboard
        config.keyboards = usesHardwareKeyboard ? [VZUSBKeyboardConfiguration()] : []
        print("[vphone] Hardware keyboard: \(usesHardwareKeyboard ? "enabled" : "disabled")")

        // Vsock (host <-> guest control channel, no IP/TCP involved)
        config.socketDevices = [VZVirtioSocketDeviceConfiguration()]

        // Power source (synthetic battery - guest sees full charge, charging)
        let source = Dynamic._VZMacSyntheticBatterySource()
        source.setCharge(100.0)
        source.setConnectivity(1) // 1=charging, 2=disconnected
        let batteryConfig = Dynamic._VZMacBatteryPowerSourceDeviceConfiguration()
        batteryConfig.setSource(source.asObject)
        if let batteryObj = batteryConfig.asObject {
            Dynamic(config)._setPowerSourceDevices([batteryObj])
            batterySource = source.asObject as AnyObject?
            print("[vphone] Synthetic battery configured (100%, charging)")
        }

        // Kernel GDB debug stub (auto-assigned by default; fixed when explicitly requested)
        if let kernelDebugPort = options.kernelDebugPort {
            guard (6000 ... 65535).contains(kernelDebugPort) else {
                throw VPhoneVirtualMachineError.invalidKernelDebugPort(kernelDebugPort)
            }
            if let kernelDebugStub = Dynamic._VZGDBDebugStubConfiguration(port: kernelDebugPort)
                .asObject
            {
                Dynamic(config)._setDebugStub(kernelDebugStub)
                print("[vphone] Kernel GDB debug stub: tcp://127.0.0.1:\(kernelDebugPort)")
            } else {
                Dynamic(config)._setDebugStub(Dynamic._VZGDBDebugStubConfiguration().asObject)
                print("[vphone] Kernel GDB debug stub enabled (system-assigned port)")
            }
        } else {
            Dynamic(config)._setDebugStub(Dynamic._VZGDBDebugStubConfiguration().asObject)
            print("[vphone] Kernel GDB debug stub enabled (system-assigned port)")
        }

        // Coprocessors
        let sepConfig = Dynamic._VZSEPCoprocessorConfiguration(storageURL: options.sepStorageURL)
        if let sepRomURL = options.sepRomURL {
            sepConfig.setRomBinaryURL(sepRomURL)
        }
        sepConfig.setDebugStub(Dynamic._VZGDBDebugStubConfiguration().asObject)
        if let sepObj = sepConfig.asObject {
            Dynamic(config)._setCoprocessors([sepObj])
            print("[vphone] SEP coprocessor enabled (storage: \(options.sepStorageURL.path))")
        }

        // Validate
        try config.validate()
        print("[vphone] Configuration validated")

        virtualMachine = VZVirtualMachine(configuration: config)
        bootAttachment = virtualMachine.networkDevices.first?.attachment
        super.init()
        virtualMachine.delegate = self

        // Forward VM serial output -> host stdout
        if let readHandle = serialOutputReadHandle {
            readHandle.readabilityHandler = { handle in
                let data = handle.availableData
                if data.isEmpty {
                    return
                }
                FileHandle.standardOutput.write(data)
            }
        }
    }

    // MARK: - Bundle Files

    /// Cancel serial forwarding before another VM takes the same host stdin.
    func stopHostDevices() {
        finishShaderCache()
        serialInputSource?.cancel()
        serialInputSource = nil
        serialOutputReadHandle?.readabilityHandler = nil
        serialOutputReadHandle = nil
    }

    /// Every file below is opened, created or overwritten by this process or
    /// by Virtualization, and neither refuses a symbolic link. A bundle can
    /// come from someone else's export, so an entry that exists must be a
    /// regular file in the bundle itself. A missing NVRAM or SEP storage is
    /// fine, because it is created; a missing disk is not.
    private static func checkBundleFiles(_ options: Options) throws {
        guard try VPhoneVirtualMachineManifest.requireRegularFileIfPresent(at: options.configURL) else {
            throw VPhoneManifestError.loadFailed(path: options.configURL.path)
        }
        guard try VPhoneVirtualMachineManifest.requireRegularFileIfPresent(at: options.diskURL) else {
            throw VPhoneVirtualMachineError.diskNotFound(options.diskURL.path)
        }
        let others = [options.nvramURL, options.sepStorageURL, options.romURL, options.sepRomURL]
        for case let url? in others {
            try VPhoneVirtualMachineManifest.requireRegularFileIfPresent(at: url)
        }
    }

    private static func resolveDeviceIdentity(machineIdentifier: VZMacMachineIdentifier)
        -> DeviceIdentity?
    {
        let ecidValue: UInt64? = if let ecid = Dynamic(machineIdentifier)._ECID.asUInt64 {
            ecid
        } else if let ecidNumber = Dynamic(machineIdentifier)._ECID.asObject as? NSNumber {
            ecidNumber.uint64Value
        } else {
            nil
        }

        guard let ecidValue else { return nil }

        let cpidHex = String(format: "%08X", VPhoneHardware.udidChipID)
        let ecidHex = String(format: "%016llX", ecidValue)
        let udid = "\(cpidHex)-\(ecidHex)"
        return DeviceIdentity(ecid: ecidValue, cpidHex: cpidHex, ecidHex: ecidHex, udid: udid)
    }

    private static func writeUDIDPrediction(identity: DeviceIdentity, to outputURL: URL) throws {
        let content = """
        UDID=\(identity.udid)
        CPID=0x\(identity.cpidHex)
        ECID=0x\(identity.ecidHex)
        MACHINE_IDENTIFIER=config.plist
        """
        try content.write(to: outputURL, atomically: true, encoding: .utf8)
    }

    // MARK: - Battery

    /// Update the synthetic battery charge and connectivity at runtime.
    /// - Parameters:
    ///   - charge: Battery percentage (0.0–100.0).
    ///   - connectivity: 1 = charging, 2 = disconnected.
    func setBattery(charge: Double, connectivity: Int) {
        guard let source = batterySource else { return }
        Dynamic(source).setCharge(charge)
        Dynamic(source).setConnectivity(connectivity)
    }

    // MARK: - Network

    enum NetworkControlError: Error, CustomStringConvertible {
        case noNetworkDevice

        var description: String {
            "This VM has no network device (network mode none)."
        }
    }

    /// The in-process network when the VM runs in `tunnel` mode.
    var tunnelNetwork: VPhoneUserspaceNetwork? {
        userspaceNetwork
    }

    /// The NIC as it is now, for `vphone.sock`'s `network` command.
    var networkStatus: [String: Any] {
        var status: [String: Any] = [:]
        if let plan = networkPlan {
            status["configured"] = Self.describe(plan)
            status["mac"] = plan.macAddress?.description ?? ""
            status["guest_ipv4"] = plan.guestIPv4?.description ?? ""
            status["forwards"] = plan.portForwards.map(\.description)
            status["local_host_name"] = plan.localHostName.map { "\($0).local" } ?? ""
        }
        guard let device = virtualMachine.networkDevices.first else {
            status["device"] = false
            return status
        }
        status["device"] = true
        status["link"] = device.attachment == nil ? "down" : "up"
        status["attachment"] = Self.describe(device.attachment)
        return status
    }

    /// Unplug or replug the guest's cable without stopping it. Down detaches
    /// the NIC from every network; up puts back the attachment it booted with.
    /// Neither is saved: the next launch reads config.plist again.
    ///
    /// Only that one attachment ever goes back. Handing a running VM a new
    /// attachment, even another `VZNATNetworkDeviceAttachment`, stopped it with
    /// an internal virtualization error (macOS 27 host, iOS 27 guest), so
    /// switching networks needs a restart.
    func setNetworkLink(up: Bool) throws {
        guard let device = virtualMachine.networkDevices.first else {
            throw NetworkControlError.noNetworkDevice
        }
        device.attachment = up ? bootAttachment : nil
        print("[vphone] Network link \(up ? "up" : "down")")
    }

    static func describe(_ plan: VPhoneNetworkPlan) -> String {
        var parts = switch plan.attachment {
        case .none: ["none"]
        case .sharedNAT: ["nat"]
        case let .bridged(interface): ["bridged(\(interface))"]
        case let .tunnel(configuration):
            ["tunnel(\(configuration.guestAddress)/\(configuration.prefixLength) via \(configuration.hostAddress))"]
        }
        if let mac = plan.macAddress {
            parts.append("mac \(mac)")
        }
        if case .manual = plan.guestIPv4 {
            parts.append("guest \(plan.guestIPv4!)")
        }
        if !plan.portForwards.isEmpty {
            parts.append("forwards \(plan.portForwards.map(\.description).joined(separator: ", "))")
        }
        if let name = plan.localHostName {
            parts.append("mdns \(name).local")
        }
        return parts.joined(separator: "  ")
    }

    static func describe(_ attachment: VZNetworkDeviceAttachment?) -> String {
        switch attachment {
        case nil: "none"
        case is VZNATNetworkDeviceAttachment: "nat"
        case let bridged as VZBridgedNetworkDeviceAttachment: "bridged(\(bridged.interface.identifier))"
        case is VZFileHandleNetworkDeviceAttachment: "tunnel"
        case let other?: String(describing: type(of: other))
        }
    }

    // MARK: - Start

    @MainActor
    func start(forceDFU: Bool) async throws {
        let opts = VZMacOSVirtualMachineStartOptions()
        Dynamic(opts)._setForceDFU(forceDFU)
        Dynamic(opts)._setStopInIBootStage1(false)
        Dynamic(opts)._setStopInIBootStage2(false)
        print("[vphone] Starting\(forceDFU ? " DFU" : "")...")
        // Start draining before the framework touches the device, or the guest's
        // first DHCP request is sent into a socket nobody is reading.
        userspaceNetwork?.start()
        nonisolated(unsafe) let vm = virtualMachine
        try await vm.start(options: opts)
        if forceDFU {
            print("[vphone] VM started in DFU mode - connect with irecovery")
        } else {
            print("[vphone] VM started - booting normally")
        }

        // Print auto-assigned debug stub port after VM starts (private API, macOS 26+ only)
        if ProcessInfo.processInfo.operatingSystemVersion.majorVersion >= 26 {
            if let debugStub = Dynamic(vm)._configuration._debugStub.asAnyObject {
                if let port = Dynamic(debugStub).port.asInt, port > 0 {
                    print("[vphone] Kernel GDB debug stub listening on tcp://127.0.0.1:\(port)")
                }
            }
        } else {
            print("[vphone] Kernel GDB debug stub port query requires macOS 26+, skipped")
        }
    }

    // MARK: - Delegate

    nonisolated func guestDidStop(_: VZVirtualMachine) {
        finishShaderCache()
        print("[vphone] Guest stopped")
        exit(EXIT_SUCCESS)
    }

    nonisolated func virtualMachine(_: VZVirtualMachine, didStopWithError error: Error) {
        finishShaderCache()
        print("[vphone] Stopped with error: \(error)")
        exit(EXIT_FAILURE)
    }

    private nonisolated func finishShaderCache() {
        guard let shaderCache else { return }
        do { try shaderCache.checkpoint() }
        catch { print("[vphone] Cannot save shader cache: \(error)") }
    }

    nonisolated func virtualMachine(
        _: VZVirtualMachine,
        networkDevice _: VZNetworkDevice,
        attachmentWasDisconnectedWithError error: Error,
    ) {
        print("[vphone] Network error: \(error)")
    }
}