Run a virtual iPhone on an Apple Silicon Mac.
Swift
Offer userspace debugging on minimal as a feature, not a preset
Maximilian Paßa85ac24cb595
diff --git a/Documents/Guides/launchpad-cli.md b/Documents/Guides/launchpad-cli.mdindex 41b78997..cfff81e2 100644--- a/Documents/Guides/launchpad-cli.md+++ b/Documents/Guides/launchpad-cli.md@@ -116,7 +116,7 @@ version while a machine is bound to it; rebind or delete those machines first.| `vm list` | Machines in every library with run state, Core Bundle and log path. Only a VM process holding the disk (`vphone-vm`, or Virtualization's VM service) makes a machine `running`; any other process that has it open (`tail`, Spotlight, a backup tool) is listed in `diskOpenIn` (`12925 tail`) and leaves it `stopped` || `vm start <name> [--headless] [--wait]` / `vm stop <name>` | Launch with the machine's bundle, or stop; `--wait` waits for vphoned. Stop asks the guest to shut down (vphoned `system.shutdown`) and waits up to 30 s; when the guest cannot be asked or does not stop, it ends the virtual machine as before. Like `vphone-cli vm launch`, start is not refused by a process that only has the disk open; it prints a note naming it || `vm wait <name>` / `vm log <name> [--kind create\|dfu\|patch]` | Wait for vphoned; read a console log |-| `vm create <name> [--bundle <version>] [...] [--device <product-type>] [--preset <preset>] [--ipsw <path>] [--kmutil-ssh <user@host>] [--block <patch>]... [--allow <patch>]... [--no-template \| --slim on\|off --trim … --keep-languages … --service-profile … --remove-apps … --keep-apps … --accounts-off] [--from <step>]` | The New Machine pipeline, bound to `--bundle` or the default: cloned from a template, built first when missing (2.9), or restored on its own with `--no-template`; the slimming switches are `vphone-cli vm create`'s, except that Apple Account goes with the trimmed service profile as in New Machine (`--accounts-off` is accepted and changes nothing). `--preset` takes a preset name or the path of a preset plist (2.14), which the machine keeps a copy of. `--block`/`--allow` (repeatable) turn one patch of the preset off or on, as New Machine's patch list and `vphone-cli fw set-patches` do (see below). `--device` makes an iPad guest, or with `AppleTV5,3` an Apple TV HD guest, which is always restored on its own without slimming and takes the `tvos` preset unless `--preset` names another, and with `AppleTV14,1` an Apple TV 4K guest, the same with the `tvos-4k` preset and its userland from the catalog's OTA; `--preset minimal` (Minimal: a stock boot chain, kernel and TXM, with the system customised before the restore) is also restored on its own without slimming, and its `fw patch` runs as root through the helper; the kernelcache mix of a machine whose cloudOS has no vphone600 components (its release's own cloudOS, a watch, an iOS 18 guest) is staged with `fw kernelcache` and linked by the helper as root; `--ipsw` is optional and only passed on to a 2.12.0 bundle, which stages with it, as New Machine's ipsw field (a 2.12.1 bundle extracts natively); `--kmutil-ssh` names the Mac that links an iOS 18 guest's (`--device iPhone11,6`) kernel-first mix over ssh, as New Machine's macOS builder field, and takes the password for ssh and sudo there from the client's `VPHONE_KMUTIL_SSH_PASSWORD`, never from an argument; `--from` retries from a step (`findTemplate` … `firstBoot`) with the options the creation started with; the result names the template, whether this creation built it, and the patches it used |+| `vm create <name> [--bundle <version>] [...] [--device <product-type>] [--preset <preset>] [--ipsw <path>] [--kmutil-ssh <user@host>] [--block <patch>]... [--allow <patch>]... [--no-template \| --slim on\|off --trim … --keep-languages … --service-profile … --remove-apps … --keep-apps … --accounts-off] [--from <step>]` | The New Machine pipeline, bound to `--bundle` or the default: cloned from a template, built first when missing (2.9), or restored on its own with `--no-template`; the slimming switches are `vphone-cli vm create`'s, except that Apple Account goes with the trimmed service profile as in New Machine (`--accounts-off` is accepted and changes nothing). `--preset` takes a preset name or the path of a preset plist (2.14), which the machine keeps a copy of. `--block`/`--allow` (repeatable) turn one patch of the preset off or on, as New Machine's patch list and `vphone-cli fw set-patches` do (see below). `--device` makes an iPad guest, or with `AppleTV5,3` an Apple TV HD guest, which is always restored on its own without slimming and takes the `tvos` preset unless `--preset` names another, and with `AppleTV14,1` an Apple TV 4K guest, the same with the `tvos-4k` preset and its userland from the catalog's OTA; `--preset minimal` (Minimal: a stock boot chain, kernel and TXM, with the system customised before the restore) is also restored on its own without slimming, and its `fw patch` runs as root through the helper (its Userspace debugging box, `userspace-debugging` under Features in `vphone-cli fw patches`, is an `--allow` for each patch it lists); the kernelcache mix of a machine whose cloudOS has no vphone600 components (its release's own cloudOS, a watch, an iOS 18 guest) is staged with `fw kernelcache` and linked by the helper as root; `--ipsw` is optional and only passed on to a 2.12.0 bundle, which stages with it, as New Machine's ipsw field (a 2.12.1 bundle extracts natively); `--kmutil-ssh` names the Mac that links an iOS 18 guest's (`--device iPhone11,6`) kernel-first mix over ssh, as New Machine's macOS builder field, and takes the password for ssh and sudo there from the client's `VPHONE_KMUTIL_SSH_PASSWORD`, never from an argument; `--from` retries from a step (`findTemplate` … `firstBoot`) with the options the creation started with; the result names the template, whether this creation built it, and the patches it used || `vm set-bundle <name> <version> [--update-environment]` | Bind a machine to another installed version. `--update-environment` also redeploys that version's guest environment and needs a stopped machine; a disk another process has open refuses it, naming that process, before the binding changes. If the update itself fails, the machine stays bound to the new version and `vm list` still shows the old `guestEnvironmentBundle`: run `cfw update-environment` to finish || `vm leases [--release]` | DHCP leases on the shared NAT network and the machine that owns each. `--release` frees the ones no machine in any library uses, through the helper (see [Networking](networking.md#addresses-held-by-old-macs)) || `cfw install <name>` | Install CFW into a stopped machine with its own bundle, through the helper. The helper puts temporary work files on the VM library's external volume when applicable. It and the two updates below refuse a disk another process has open, naming it (`12925 tail`). |diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.mdindex 4741a527..41f7bca6 100644--- a/Research/0_binary_patch_comparison.md+++ b/Research/0_binary_patch_comparison.md@@ -6288,3 +6288,58 @@ Cache sent to launchd successfullywith three `Launch Constraint Violation (not enforcing)` lines(`MobileAssetEarlyBootTask`, `init_exclavekit`, `vphoned`), no enforcingviolation and no crash report.++## Userspace debugging on `minimal` (2026-11-02)++`system-debugserver-cfw-install` re-signs the guest's `/usr/libexec/debugserver`+(strips `seatbelt-profiles`, sets `task_for_pid-allow`, ad hoc) in `cfw install`,+which `minimal` never runs. `filesystem-exp-debugserver` makes the same change in+the restore-image merge, before the reseal, so the new hash lands in the+regenerated static trust cache. Both stages share the entitlement transform+(`CustomFirmwareDebugserver.attachEntitlements`) and are a logged no-op when the+system ships no debugserver: a stock userland carries it only in the Developer+disk image, so it is present to re-sign on a research/cloudOS build. The patch is+opt-in (`FirmwareRestoreImagePatchSet.optInPatches`); plain `minimal` and+`watchos` leave it off.++The entitlement alone does not let debugserver run or attach on `minimal`'s stock+kernel and TXM: AMFI asks TXM for developer mode and kills it ("Developer mode is+disabled, task_for_pid-allow is disallowed"), and an enrolment from the guest does+not survive a forced reboot. The `userspace-debugging` feature+(`FirmwarePatchSetCatalog.userspaceDebugging`) groups the re-sign with the+smallest kernel and TXM set that lets it attach to any process and read its+memory:++| Patch | Why |+| --- | --- |+| `filesystem-exp-debugserver` | The re-signed debugserver, in the image's trust cache. |+| `kernel-cfw-task_for_pid` | Return a task port for a process the caller does not own. |+| `kernel-boot-task_conversion_eval` | Let that task port be converted. |+| `kernel-cfw-debugger` | Report the kernel debuggable; `task_for_pid` is gated on it. |+| `kernel-boot-port_to_map` | No panic when debugserver converts the target's task port to a vm_map. |+| `kernel-boot-proc_security_policy` | Let the per-process security policy check pass. |+| `kernel-boot-cred_label_update_execve` + `kernel-boot-hook_cred_label` | Grant the platform label and retarget the MACF hook to that handler; the handler is dead code without the hook. |+| `kernel-boot-amfi_trustcache` + `kernel-boot-amfi_execve` | Admit the re-signed debugserver should it run outside the image's trust cache. |+| `txm-boot-developer_mode_bypass` | Report developer mode on, without enrolment. |+| `txm-cfw-debugger_entitlement` | Pass selector 42's (debug memory mapping) debugger entitlement check. |+| `txm-boot-sel42_29` + `txm-cfw-get_task_allow` | Set the target's get-task-allow byte where selectors 42 and 41 read it. |++The rest of `kernel.base`/`kernel.cfw` and TXM's signature-admission patches stay+off: the resealed image's trust cache admits everything it runs. `standard`+already turns on every kernel and TXM patch above and installs its debugserver+with `cfw install`, so the feature is not offered there.++To make this selectable without a preset of its own, `minimal` now names the two+kernel sets and selects nothing from them. The pipeline builds a kernel patcher+only when the plan turns on a patch from those sets (the research board's kext+mix targets the kernelcache too, so the target alone does not say), so a plain+`minimal` kernel stays stock. `watchos` does not name them: the feature is untried+on a watch kernel. A feature is only a list of patch identifiers: turning it on is+`--allow` for each, and `fw patches` reports it (`features` in `--json`, with+`available` for the active preset) so Launchpad's patch sheet offers one box+without declaring a patch itself. On an installed `minimal` VM a kernel patch is+reported as delivered by a restore, not by `cfw update-kernel`, which refuses a+VM whose system was customised before its restore.++On an iOS 18 guest several of these patches are found only by the iOS 18 kernel+and TXM finders (`feature/ios18-standard`).diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchDrift.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchDrift.swiftindex d67ed3ae..29a81886 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchDrift.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchDrift.swift@@ -16,7 +16,8 @@ import VPhonePatchKit// MARK: - Delivery/// The step that carries a change to one patch into a guest that is already-/// installed. Which one depends only on where the patch lands.+/// 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@@ -33,12 +34,16 @@ public enum FirmwarePatchDelivery: String, Sendable, Hashable, CaseIterable, Cod/// Everything `cfw install` writes into the guest volumes.case updateEnvironment = "update-environment"- public init(target: VPhonePatchTarget) {+ /// - 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 = .firmwarePatchcase .firmware(.kernelcache):- self = .updateKernel+ self = restoredCustomisedSystem ? .restore : .updateKernelcase .firmware:// iBSS, iBEC, LLB, TXM, DeviceTree, SEP, and the restore-only// Filesystem/Manifest.@@ -114,6 +119,9 @@ public enum FirmwarePatchDrift {/// 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@@ -129,7 +137,7 @@ public enum FirmwarePatchDrift {}public var delivery: FirmwarePatchDelivery {- FirmwarePatchDelivery(target: target)+ FirmwarePatchDelivery(target: target, restoredCustomisedSystem: restoredCustomisedSystem)}}@@ -145,6 +153,8 @@ public enum FirmwarePatchDrift {/// 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],@@ -153,6 +163,7 @@ public enum FirmwarePatchDrift {applied: [String: Set<String>]?,notApplicable: Set<String> = [],standIns: [String: String] = [:],+ restoredCustomisedSystem: Bool = false,part: (VPhonePatchTarget) -> String,) -> [PatchState] {let partOf = part@@ -178,6 +189,7 @@ public enum FirmwarePatchDrift {wanted: isWanted,planned: planned.map { $0.contains(declaration.identifier) },applied: isApplied,+ restoredCustomisedSystem: restoredCustomisedSystem,)}}diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchFeature.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchFeature.swiftnew file mode 100644index 00000000..141979eb--- /dev/null+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchFeature.swift@@ -0,0 +1,96 @@+// FirmwarePatchFeature.swift — Patches a machine turns on or off together.+//+// A feature is not a patch set and not a preset: it names patches that already+// belong to sets, and is only useful as a group. Turning it on is the same as+// `--allow` for each of its patches, so the selection on disk stays a list of+// patch identifiers and nothing new has to be resolved. `fw patches --json`+// reports the features, so Launchpad can offer one checkbox for the group+// without declaring any patch of its own.++import Foundation+import VPhonePatchKit++public struct FirmwarePatchFeature: Sendable, Hashable, Identifiable {+ public let identifier: String+ public let title: String+ public let summary: String+ /// The patches the feature turns on, by identifier.+ public let patches: Set<String>++ public var id: String {+ identifier+ }++ /// Whether `preset` can carry this feature: it names every set that+ /// declares one of its patches, so `--allow` for each resolves. A preset+ /// without one of those sets cannot turn the feature on at all.+ public func isAvailable(in preset: VPhonePatchPreset) -> Bool {+ let named = Set(preset.patchSets.map(\.identifier))+ return patches.allSatisfy { patch in+ FirmwarePatchSetCatalog.bundled.contains { set in+ named.contains(set.identifier) && set.patches.contains { $0.identifier == patch }+ }+ }+ }+}++extension FirmwarePatchSetCatalog {+ /// Everything a debugger needs to attach to a process in a ``minimalPreset``+ /// guest and read its memory, and no more. `minimal` restores a resealed+ /// system onto a stock kernel and TXM; this adds:+ ///+ /// - `filesystem-exp-debugserver`: re-signs the guest's debugserver with+ /// `task_for_pid-allow` and no sandbox profile, before the reseal, so its+ /// new hash lands in the regenerated trust cache.+ /// - `kernel-cfw-task_for_pid` returns a task port for a process the caller+ /// does not own, and `kernel-boot-task_conversion_eval` lets that port be+ /// converted.+ /// - `kernel-cfw-debugger` reports the kernel debuggable, which+ /// `task_for_pid` is gated on.+ /// - `kernel-boot-port_to_map` stops the panic when debugserver converts the+ /// target's task port to a vm_map to read or write its memory.+ /// - `kernel-boot-proc_security_policy` lets the per-process policy check pass.+ /// - `kernel-boot-cred_label_update_execve` grants the platform label and+ /// `kernel-boot-hook_cred_label` retargets the MACF hook to that handler;+ /// the handler is dead code without the hook.+ /// - `kernel-boot-amfi_trustcache` and `kernel-boot-amfi_execve` admit the+ /// re-signed debugserver should it run outside the image's trust cache.+ /// - `txm-boot-developer_mode_bypass` reports developer mode on. On a TXM+ /// device AMFI asks TXM, and kills the re-signed debugserver without it+ /// ("Developer mode is disabled, task_for_pid-allow is disallowed");+ /// enrolling from the guest does not survive a forced reboot.+ /// - `txm-cfw-debugger_entitlement` passes selector 42's (debug memory+ /// mapping) debugger entitlement check, and `txm-boot-sel42_29` and+ /// `txm-cfw-get_task_allow` set the target's get-task-allow byte where+ /// selectors 42 and 41 read it, so a daemon without get-task-allow can be+ /// debugged (Research/Firmware/txm_jb_patches.md).+ ///+ /// The rest of the kernel sets, and TXM's signature-admission patches, stay+ /// off: the resealed image's own trust cache admits everything it runs.+ /// `standard` and its relatives install their debugserver with+ /// `cfw install` instead and already carry these kernel and TXM patches.+ public static let userspaceDebugging = FirmwarePatchFeature(+ identifier: "userspace-debugging",+ title: "Userspace debugging",+ summary: "A re-signed debugserver, and the kernel and TXM patches it needs to attach to any process in the guest and read its memory. The kernel and TXM stay otherwise stock.",+ patches: [+ FirmwareRestoreImagePatchSet.debugserver,+ "kernel-cfw-task_for_pid",+ "kernel-boot-task_conversion_eval",+ "kernel-cfw-debugger",+ "kernel-boot-port_to_map",+ "kernel-boot-proc_security_policy",+ "kernel-boot-cred_label_update_execve",+ "kernel-boot-hook_cred_label",+ "kernel-boot-amfi_trustcache",+ "kernel-boot-amfi_execve",+ "txm-boot-developer_mode_bypass",+ "txm-cfw-debugger_entitlement",+ "txm-boot-sel42_29",+ "txm-cfw-get_task_allow",+ ],+ )++ /// The features the bundle offers.+ public static let features: [FirmwarePatchFeature] = [userspaceDebugging]+}diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swiftindex 2052209b..61eaa2b8 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift@@ -390,8 +390,10 @@ public enum FirmwarePatchSetCatalog {/// A guest on a stock boot chain, kernel and TXM: the system is customised/// before the restore instead (``FirmwareRestoreImagePatchSet``), and- /// nothing after it. Names no kernel or guest set, so no kernel or guest- /// patcher is built.+ /// nothing after it. It names the two kernel sets but selects nothing from+ /// them, so the kernel stays stock and no kernel patcher is built; naming+ /// them is what lets a machine turn on ``userspaceDebugging``. No guest set+ /// is named.////// With every BuildManifest digest rehashed (`manifest-boot-digest_rehash`)/// the ticket covers the images as they are: a stock iBEC restores the@@ -408,6 +410,8 @@ public enum FirmwarePatchSetCatalog {summary: "A stock boot chain, kernel and TXM: the restore installs a resealed system with vphoned, the GPU driver and activation, and nothing writes it afterwards.",patchSets: [.bundled(FirmwareBootChainPatchSet.identifier),+ .bundled(FirmwareKernelBasePatchSet.identifier),+ .bundled(FirmwareKernelCustomFirmwarePatchSet.identifier),.bundled(FirmwareResearchBoardPatchSet.identifier),.bundled(FirmwareDeviceTreePatchSet.identifier),.bundled(FirmwareRestoreImagePatchSet.identifier),@@ -438,13 +442,19 @@ public enum FirmwarePatchSetCatalog {/// ``minimalPreset`` for an Apple Watch: its device tree presents the watch/// board. Its boot chain is stock too: a stock iBEC restores the guest and a/// stock LLB boots it to the pairing screen and vphoned (watchOS 26.4 23T240- /// on cloudOS 26.4 23E244, 2026-11-02). The shipped `watchos.plist` must- /// match this.+ /// on cloudOS 26.4 23E244, 2026-11-02). It does not name the kernel sets, so+ /// ``userspaceDebugging``, untried on a watch kernel, is not offered.+ /// The shipped `watchos.plist` must match this.public static let watchOSPreset = VPhonePatchPreset(identifier: VPhonePatchPreset.watchOSIdentifier,title: "Apple Watch",summary: "Minimal for an Apple Watch guest: the watch board's device tree, and a resealed system with vphoned, the GPU driver, speaker audio and activation restored onto a stock kernel and TXM.",- patchSets: minimalPreset.patchSets,+ patchSets: [+ .bundled(FirmwareBootChainPatchSet.identifier),+ .bundled(FirmwareResearchBoardPatchSet.identifier),+ .bundled(FirmwareDeviceTreePatchSet.identifier),+ .bundled(FirmwareRestoreImagePatchSet.identifier),+ ],selection: .allow(watchOSDeviceTreePatches.union(FirmwareResearchBoardPatchSet.manifest.patches.map(\.identifier))diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swiftindex d2ffac10..2c06195e 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift@@ -54,8 +54,18 @@ extension FirmwarePipeline {guard let plan else { return true }return plan.declarations.contains { $0.target == .firmware(component) && plan.isEnabled($0.identifier) }}- let includeKernelBase = includesSet(FirmwareKernelBasePatchSet.identifier)- let includeKernelCustomFirmware = includesSet(FirmwareKernelCustomFirmwarePatchSet.identifier)+ // Whether the plan turns on any patch from the two kernel sets. `minimal`+ // names them so a machine can turn some on, but selects none itself; its+ // kernel stays stock, and the kernel patchers would only log every site+ // they skipped. (The research board's kext mix targets the kernelcache+ // too, so it is not enough to ask about the target.)+ let patchesKernel = plan.map { plan in+ plan.patchSets+ .filter { [FirmwareKernelBasePatchSet.identifier, FirmwareKernelCustomFirmwarePatchSet.identifier].contains($0.identifier) }+ .contains { set in set.patches.contains { plan.isEnabled($0.identifier) } }+ } ?? true+ let includeKernelBase = includesSet(FirmwareKernelBasePatchSet.identifier) && patchesKernel+ let includeKernelCustomFirmware = includesSet(FirmwareKernelCustomFirmwarePatchSet.identifier) && patchesKernellet includeDeviceTree = includesSet(FirmwareDeviceTreePatchSet.identifier)// A guest that presents its board boots a device tree of its own (7b),diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchDriftTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchDriftTests.swiftindex 16cf8bad..b7245905 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchDriftTests.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchDriftTests.swift@@ -133,6 +133,25 @@ struct FirmwarePatchDriftTests {return Dictionary(uniqueKeysWithValues: list.map { ($0.identifier, $0) })}+ @Test+ func `A guest restored with a customised system takes kernel patches only by restore`() {+ // `cfw update-kernel` refuses a `minimal` guest, so a kernel patch it+ // turns on (userspace debugging) is delivered like the rest of its boot chain.+ let list = FirmwarePatchDrift.states(+ declarations: declarations,+ wanted: ["kernel-a", "dt"],+ planned: [],+ applied: nil,+ restoredCustomisedSystem: true,+ part: part,+ )+ let result = Dictionary(uniqueKeysWithValues: list.map { ($0.identifier, $0) })+ #expect(result["kernel-a"]?.isPending == true)+ #expect(result["kernel-a"]?.delivery == .restore)+ #expect(result["dt"]?.delivery == .updateEnvironment)+ #expect(FirmwarePatchDelivery(target: .firmware(.kernelcache)) == .updateKernel)+ }+@Testfunc `No plan and no receipt leaves every patch unknown`() {let result = states(wanted: ["kernel-a"], planned: nil, applied: nil)diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swiftindex 944df9c1..df499e17 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift@@ -183,15 +183,19 @@ struct FirmwarePatchSetCatalogTests {// patch: these are the combinations we claim boot. The tvOS// presets drop exactly the iOS ones an Apple TV has no port of.let tvPresets = [VPhonePatchPreset.homeViewIdentifier, VPhonePatchPreset.tvOSIdentifier, VPhonePatchPreset.tvOS4KIdentifier, VPhonePatchPreset.homePodMiniIdentifier]- // `minimal` and `watchos` drop every boot chain patch: their- // system is customised before the restore instead.+ // `minimal` and `watchos` drop every boot chain patch, and+ // `minimal` every kernel patch of the two sets it names only+ // so a machine can turn some on: their system is customised+ // before the restore instead, onto a stock kernel.let restoreImagePresets = [VPhonePatchPreset.minimalIdentifier, VPhonePatchPreset.watchOSIdentifier]+ let droppable = Set(+ [FirmwareBootChainPatchSet.manifest, FirmwareKernelBasePatchSet.manifest, FirmwareKernelCustomFirmwarePatchSet.manifest]+ .flatMap { $0.patches.map(\.identifier) },+ )let expected = if tvPresets.contains(preset.identifier) {Set(plan.droppedBootEssentials).isSubset(of: FirmwarePatchSetCatalog.tvOSBlockedPatches)} else if restoreImagePresets.contains(preset.identifier) {- plan.droppedBootEssentials.allSatisfy {- FirmwareBootChainPatchSet.manifest.patches.map(\.identifier).contains($0)- }+ Set(plan.droppedBootEssentials).isSubset(of: droppable)} else {plan.droppedBootEssentials.isEmpty}@@ -302,6 +306,55 @@ struct FirmwarePatchSetCatalogTests {}}+ @Test+ func `Userspace debugging is offered on minimal alone, and adds exactly its own patches there`() throws {+ let feature = FirmwarePatchSetCatalog.userspaceDebugging+ let declared = Set(FirmwarePatchSetCatalog.allDeclarations.map(\.identifier))+ #expect(feature.patches.isSubset(of: declared))+ for preset in FirmwarePatchSetCatalog.builtInPresets {+ #expect(+ feature.isAvailable(in: preset) == (preset.identifier == VPhonePatchPreset.minimalIdentifier),+ "\(preset.identifier)",+ )+ }++ for base in ["18.6.2", "26.4"] {+ let minimal = try VPhonePatchPlan.resolve(+ preset: FirmwarePatchSetCatalog.minimalPreset,+ patchSets: FirmwarePatchSetCatalog.bundled,+ iOSBase: VPhoneVersion(base),+ cloudOS: VPhoneVersion("26.4"),+ )+ let debugging = try VPhonePatchPlan.resolve(+ preset: FirmwarePatchSetCatalog.minimalPreset,+ patchSets: FirmwarePatchSetCatalog.bundled,+ iOSBase: VPhoneVersion(base),+ cloudOS: VPhoneVersion("26.4"),+ allowed: feature.patches,+ )+ // Plain minimal keeps a stock kernel; the feature adds only its own.+ let kernelSets = [FirmwareKernelBasePatchSet.manifest, FirmwareKernelCustomFirmwarePatchSet.manifest]+ .flatMap { $0.patches.map(\.identifier) }+ #expect(minimal.enabled.isDisjoint(with: kernelSets), "\(base)")+ #expect(debugging.enabled.subtracting(minimal.enabled).isSubset(of: feature.patches), "\(base)")+ #expect(debugging.enabled.union(debugging.skippedByVersion).isSuperset(of: feature.patches), "\(base)")+ }+ }++ @Test+ func `Standard carries the kernel and TXM half of userspace debugging`() {+ // So `standard`, which installs its own debugserver with `cfw install`,+ // needs no feature box.+ let preset = FirmwarePatchSetCatalog.standardPreset+ let named = Set(preset.patchSets.map(\.identifier))+ let standard = Set(FirmwarePatchSetCatalog.bundled.filter { named.contains($0.identifier) }+ .flatMap(\.patches).map(\.identifier).filter { preset.selection.includes($0) })+ let kernelAndTXM = FirmwarePatchSetCatalog.userspaceDebugging.patches+ .subtracting([FirmwareRestoreImagePatchSet.debugserver])+ #expect(kernelAndTXM.isSubset(of: standard), "\(kernelAndTXM.subtracting(standard).sorted())")+ #expect(standard.contains("system-debugserver-cfw-install"))+ }+@Testfunc `Standard leaves every manual-only patch off, on every base`() throws {for base in ["18.6.2", "26.4", "27.0"] {diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swiftindex c939dbf2..fe461b1d 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareCommand.swift@@ -537,7 +537,9 @@ struct VPhoneFirmwareSetPatchesCommand: ParsableCommand {A machine booting OpenAVB has noAVPBooter to patch.kernelcache `cfw update-kernel` (root), which keeps the- guest's data (no restore).+ guest's data (no restore). On a VM whose+ system was customised before its+ restore (`minimal`), only a restore.Guest (system, dyld cache, `cfw update-environment` (root), whichPreboot device tree) applies this choice both on and off.LLB, TXM, DeviceTree only a restore, which erases the guest's data.diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhonePatchCatalogReport.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhonePatchCatalogReport.swiftindex ba47f2f9..f8c6996c 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhonePatchCatalogReport.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhonePatchCatalogReport.swift@@ -100,6 +100,7 @@ public struct VPhonePatchCatalogReport: Sendable {applied: receipt.map { $0.parts.mapValues { Set($0.patches) } },notApplicable: Set(receipt?.parts.values.flatMap(\.notApplicable) ?? []),standIns: FirmwareGuestSystemPatchSet.prebootRepairs,+ restoredCustomisedSystem: VPhoneCustomFirmwareInstaller.restoredCustomisedSystem(plan),part: VPhoneVirtualMachinePatchReceipt.part(for:),)}@@ -162,6 +163,18 @@ public struct VPhonePatchCatalogReport: Sendable {let patchSets: [String]}+ /// A group of patches the editor turns on or off with one box+ /// (``FirmwarePatchFeature``).+ struct FeatureEntry: Encodable, Sendable {+ let identifier: String+ let title: String+ let summary: String+ let patches: [String]+ /// Whether the active preset names every set the feature draws on, so+ /// allowing its patches resolves.+ let available: Bool+ }+struct Payload: Encodable, Sendable {let vmName: String?let activePreset: String@@ -169,11 +182,12 @@ public struct VPhonePatchCatalogReport: Sendable {let allowedPatches: [String]let presets: [PresetEntry]let patches: [PatchEntry]+ let features: [FeatureEntry]/// Set only when a VM is named.let machine: MachineRecords?private enum CodingKeys: String, CodingKey {- case vmName, activePreset, blockedPatches, allowedPatches, presets, patches+ case vmName, activePreset, blockedPatches, allowedPatches, presets, patches, featurescase planRecorded, receiptRecorded, receiptParts, installed, pendingPatches}@@ -185,6 +199,7 @@ public struct VPhonePatchCatalogReport: Sendable {try container.encode(allowedPatches, forKey: .allowedPatches)try container.encode(presets, forKey: .presets)try container.encode(patches, forKey: .patches)+ try container.encode(features, forKey: .features)guard let machine else { return }try container.encode(machine.plan != nil, forKey: .planRecorded)try container.encode(machine.receipt != nil, forKey: .receiptRecorded)@@ -284,6 +299,15 @@ public struct VPhonePatchCatalogReport: Sendable {)},patches: entries(),+ features: FirmwarePatchSetCatalog.features.map {+ FeatureEntry(+ identifier: $0.identifier,+ title: $0.title,+ summary: $0.summary,+ patches: $0.patches.sorted(),+ available: $0.isAvailable(in: activePreset),+ )+ },machine: machine,)let encoder = JSONEncoder()@@ -357,6 +381,19 @@ public struct VPhonePatchCatalogReport: Sendable {lines.append(" \(box) \(entry.identifier)\(suffix)")}+ let selected = selectedPatches()+ let features = FirmwarePatchSetCatalog.features.filter { $0.isAvailable(in: activePreset) }+ if !features.isEmpty {+ lines.append("")+ lines.append("Features (turn one on by allowing each of its patches with `fw set-patches`):")+ for feature in features {+ let on = feature.patches.intersection(selected).count+ let state = on == feature.patches.count ? "on" : on == 0 ? "off" : "\(on) of \(feature.patches.count) on"+ lines.append(" \(feature.identifier) — \(feature.title) (\(state))")+ lines.append(" " + feature.patches.sorted().map { "--allow \($0)" }.joined(separator: " "))+ }+ }+if let vmName, let machine, let states = states() {let pending = states.filter { $0.isPending == true }if pending.isEmpty {diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/minimal.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/minimal.plistindex 94151732..03d2edee 100644--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/minimal.plist+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/minimal.plist@@ -12,6 +12,18 @@<key>Kind</key><string>Bundled</string></dict>+ <dict>+ <key>Identifier</key>+ <string>com.vphone.patchset.kernel.base</string>+ <key>Kind</key>+ <string>Bundled</string>+ </dict>+ <dict>+ <key>Identifier</key>+ <string>com.vphone.patchset.kernel.cfw</string>+ <key>Kind</key>+ <string>Bundled</string>+ </dict><dict><key>Identifier</key><string>com.vphone.patchset.research.board</string>diff --git a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchCatalog.swift b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchCatalog.swiftindex 733eadd0..53400c4c 100644--- a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchCatalog.swift+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchCatalog.swift@@ -135,6 +135,23 @@ nonisolated struct VPhoneLaunchpadPatchCatalog: Decodable, Sendable {private static let effects: Set<String> = ["boot", "cfw", "exp"]}+ /// A group of patches the editor turns on or off with one box, such as+ /// "Userspace debugging". The bundle names its patches, so Launchpad still+ /// declares none.+ struct Feature: Decodable, Hashable, Identifiable, Sendable {+ let identifier: String+ let title: String+ let summary: String+ let patches: [String]+ /// Whether the active preset can carry the feature: it names every+ /// set the feature's patches belong to.+ let available: Bool++ var id: String {+ identifier+ }+ }+/// The preset this report was made against: the VM's own, or the one `--preset`/// asked for.let activePreset: String@@ -142,6 +159,8 @@ nonisolated struct VPhoneLaunchpadPatchCatalog: Decodable, Sendable {let allowedPatches: [String]let presets: [Preset]let patches: [Patch]+ /// Nil from a bundle that predates features; the editor then shows none.+ let features: [Feature]?// Reported only for a named machine, and only by a bundle that compares a// machine's records. An older bundle leaves them out, and every reader@@ -196,6 +215,15 @@ nonisolated struct VPhoneLaunchpadPatchCatalog: Decodable, Sendable {return selection.blocked.union(selection.allowed).intersection(guest)}+ /// The features worth a box under the active preset: one it can carry and+ /// does not already turn on whole. `standard` installs its own debugserver+ /// and has the kernel patches, so it gets no "Userspace debugging" box.+ var offeredFeatures: [Feature] {+ (features ?? []).filter { feature in+ feature.available && !feature.patches.allSatisfy { patch($0)?.inPreset == true }+ }+ }+func preset(_ identifier: String) -> Preset? {presets.first { $0.identifier == identifier }}@@ -384,6 +412,21 @@ nonisolated struct VPhoneLaunchpadPatchSelection: Hashable, Sendable {patch.inPreset ? !blocked.contains(patch.identifier) : allowed.contains(patch.identifier)}+ /// Whether every patch of `feature` is on.+ func isOn(_ feature: VPhoneLaunchpadPatchCatalog.Feature, in catalog: VPhoneLaunchpadPatchCatalog) -> Bool {+ feature.patches.allSatisfy { catalog.patch($0).map(isOn) ?? false }+ }++ /// Turns every patch of `feature` on or off, each recorded as it differs+ /// from the preset.+ mutating func set(_ feature: VPhoneLaunchpadPatchCatalog.Feature, on: Bool, in catalog: VPhoneLaunchpadPatchCatalog) {+ for identifier in feature.patches {+ if let patch = catalog.patch(identifier) {+ set(patch, on: on)+ }+ }+ }+/// Records a box the way it differs from the preset, so a patch that agrees/// with the preset again lands in neither list.mutating func set(_ patch: VPhoneLaunchpadPatchCatalog.Patch, on: Bool) {diff --git a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchSettingsView.swift b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchSettingsView.swiftindex 7cdec3c6..31015685 100644--- a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchSettingsView.swift+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchSettingsView.swift@@ -160,6 +160,18 @@ struct VPhoneLaunchpadPatchSettingsView: View {if isLoading {ProgressView().controlSize(.small)}+ if let catalog {+ ForEach(catalog.offeredFeatures) { feature in+ Toggle(isOn: Binding(+ get: { selection.isOn(feature, in: catalog) },+ set: { selection.set(feature, on: $0, in: catalog) },+ )) {+ Text(verbatim: feature.title)+ }+ .help(feature.summary)+ .disabled(isLoading || isReadOnly)+ }+ }Spacer()VPhoneLaunchpadSearchField(text: $filter, prompt: String(localized: "Filter patches")).frame(width: 220)