Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
9.0 KB
Raw Blame
// FirmwarePatchDrift.swift — Where a VM's patches stand, and what a change still needs.
//
// A VM carries three patch records: the selection (what the owner wants), the
// plan (what the last `fw patch` built) and the receipt (what is live in the
// guest, part by part). This file compares them. It reads no file and writes
// none: `fw patches`, `fw set-patches` and `restore` hand it the records they
// already loaded, so the comparison is one pure rule the tests can pin.
//
// Parts are named by the caller's rule (`VPhoneVirtualMachinePatchReceipt.part(for:)`
// in `vphone-cli`), passed in as a closure so the receipt stays the one place
// that spells a part key.

import Foundation
import VPhonePatchKit

// MARK: - Delivery

/// The step that carries a change to one patch into a guest that is already
/// installed. Which one depends on where the patch lands, and for the
/// kernelcache on whether the restore installed a customised system.
public enum FirmwarePatchDelivery: String, Sendable, Hashable, CaseIterable, Codable {
    /// AVPBooter sits in the VM folder and is read at every boot, so
    /// `fw patch` alone delivers it. `fw patch` still needs the VM's restore
    /// tree, which is kept only with `--keep-artifacts`.
    case firmwarePatch = "fw-patch"
    /// The kernelcache lives in Preboot as an IMG4; `cfw update-kernel`
    /// re-patches it from the VM's FirmwareOriginals and swaps its IM4P into
    /// Preboot under the signed manifest, with no restore and no erase.
    case updateKernel = "update-kernel"
    /// iBSS and iBEC are used only while restoring, LLB lives in NOR, and TXM
    /// and DeviceTree are personalized into Preboot by the restore, which
    /// erases. Nothing else writes them.
    case restore
    /// Everything `cfw install` writes into the guest volumes.
    case updateEnvironment = "update-environment"

    /// - Parameter restoredCustomisedSystem: Whether the guest's restore
    ///   installed a system `fw patch` customised (``FirmwareRestoreImagePatchSet``).
    ///   `cfw update-kernel` refuses such a guest, so its kernelcache, like
    ///   the rest of its boot chain, changes only with a restore.
    public init(target: VPhonePatchTarget, restoredCustomisedSystem: Bool = false) {
        switch target {
        case .firmware(.avpBooter):
            self = .firmwarePatch
        case .firmware(.kernelcache):
            self = restoredCustomisedSystem ? .restore : .updateKernel
        case .firmware:
            // iBSS, iBEC, LLB, TXM, DeviceTree, SEP, and the restore-only
            // Filesystem/Manifest.
            self = .restore
        case .dyldSharedCache, .guestExecutable, .guestEntitlements, .guestFile, .prebootDeviceTree:
            self = .updateEnvironment
        @unknown default:
            // A target this build does not know is written by the guest install.
            self = .updateEnvironment
        }
    }
}

// MARK: - Drift

public enum FirmwarePatchDrift {
    /// The boot-chain components a successful restore writes into the guest,
    /// in boot order. AVPBooter is not among them: it never leaves the VM
    /// folder, and `fw patch` records it itself.
    public static let restoredComponents: [VPhoneFirmwareComponent] = [
        .iBSS, .iBEC, .llb, .txm, .restoreRamDisk, .kernelcache, .deviceTree, .sep,
    ]

    /// What a restore put into each component it wrote: the plan's enabled
    /// patches that target that component.
    ///
    /// Every component in ``restoredComponents`` is present, empty when the plan
    /// turned all of its patches off, so a receipt records "nothing" rather than
    /// leaving the part unknown.
    public static func restoredParts(
        enabledPatches: Set<String>,
        declarations: [VPhonePatchDeclaration] = FirmwarePatchSetCatalog.allDeclarations,
    ) -> [VPhoneFirmwareComponent: [String]] {
        var result: [VPhoneFirmwareComponent: [String]] = [:]
        for component in restoredComponents {
            result[component] = declarations
                .filter { $0.target == .firmware(component) && enabledPatches.contains($0.identifier) }
                .map(\.identifier)
                .sorted()
        }
        return result
    }

    /// The patches the selection turns on that also pass their version gate.
    ///
    /// `selected` is the selection before any gate (a preset plus the VM's
    /// boxes). A patch pinned to another OS release is not wanted on this VM,
    /// however it was selected, so it never counts as drift. With neither
    /// version known there is nothing to gate against and the selection stands.
    public static func wantedPatches(
        selected: Set<String>,
        declarations: [VPhonePatchDeclaration],
        iOSBase: VPhoneVersion?,
        cloudOS: VPhoneVersion?,
    ) -> Set<String> {
        guard iOSBase != nil || cloudOS != nil else { return selected }
        return Set(declarations.lazy
            .filter { selected.contains($0.identifier) }
            .filter { $0.applicability.matches(iOSBase: iOSBase, cloudOS: cloudOS) }
            .map(\.identifier))
    }

    /// One patch, compared across the three records.
    public struct PatchState: Sendable, Hashable {
        public let identifier: String
        public let target: VPhonePatchTarget
        /// The receipt part the patch lives in.
        public let part: String
        /// Whether the current selection wants it, after the version gate.
        public let wanted: Bool
        /// Whether the last `fw patch` turned it on; nil with no plan.
        public let planned: Bool?
        /// Whether it is live in the guest; nil when the receipt does not
        /// record its part.
        public let applied: Bool?
        /// Whether the guest's restore installed a customised system, which
        /// changes what delivers a kernelcache patch.
        public let restoredCustomisedSystem: Bool

        /// What the guest is believed to run: the receipt where it records the
        /// part, else the plan, which is what the next restore or install
        /// would write. Nil when neither says.
        public var reference: Bool? {
            applied ?? planned
        }

        /// Whether the wanted state still has to reach the guest. Nil when
        /// nothing records what the guest has.
        public var isPending: Bool? {
            reference.map { $0 != wanted }
        }

        public var delivery: FirmwarePatchDelivery {
            FirmwarePatchDelivery(target: target, restoredCustomisedSystem: restoredCustomisedSystem)
        }
    }

    /// Every declaration, compared.
    ///
    /// - Parameters:
    ///   - wanted: ``wantedPatches(selected:declarations:iOSBase:cloudOS:)``.
    ///   - planned: The plan's enabled patches, or nil with no plan.
    ///   - applied: The receipt's patches by part, or nil with no receipt. A
    ///     part missing from it leaves its patches' `applied` nil.
    ///   - standIns: A patch and the patch that puts the same change into
    ///     the guest another way, such as a boot-chain DeviceTree patch and the
    ///     Preboot repair for a VM restored before it
    ///     (`FirmwareGuestSystemPatchSet.prebootRepairs`). When the stand-in is
    ///     live, the patch reads as applied, whatever its own part records.
    ///   - restoredCustomisedSystem: Whether the guest's restore installed a
    ///     customised system; see ``FirmwarePatchDelivery/init(target:restoredCustomisedSystem:)``.
    ///   - part: The receipt's rule for naming a target's part.
    public static func states(
        declarations: [VPhonePatchDeclaration],
        wanted: Set<String>,
        planned: Set<String>?,
        applied: [String: Set<String>]?,
        notApplicable: Set<String> = [],
        standIns: [String: String] = [:],
        restoredCustomisedSystem: Bool = false,
        part: (VPhonePatchTarget) -> String,
    ) -> [PatchState] {
        let partOf = part
        let targets = Dictionary(declarations.map { ($0.identifier, $0.target) }, uniquingKeysWith: { first, _ in first })
        return declarations.map { declaration in
            let part = partOf(declaration.target)
            let isWanted = wanted.contains(declaration.identifier)
            // A patch the guest has nothing for reads as whatever is wanted,
            // so turning it on or off is never reported as pending.
            var isApplied = applied?[part].map {
                notApplicable.contains(declaration.identifier) ? isWanted : $0.contains(declaration.identifier)
            }
            if let standIn = standIns[declaration.identifier],
               let standInTarget = targets[standIn],
               applied?[partOf(standInTarget)]?.contains(standIn) == true
            {
                isApplied = true
            }
            return PatchState(
                identifier: declaration.identifier,
                target: declaration.target,
                part: part,
                wanted: isWanted,
                planned: planned.map { $0.contains(declaration.identifier) },
                applied: isApplied,
                restoredCustomisedSystem: restoredCustomisedSystem,
            )
        }
    }
}