Skip to content

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.md
index 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.md
index 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 successfully
with three `Launch Constraint Violation (not enforcing)` lines
(`MobileAssetEarlyBootTask`, `init_exclavekit`, `vphoned`), no enforcing
violation 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.swift
index 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 = .firmwarePatch
case .firmware(.kernelcache):
- self = .updateKernel
+ self = restoredCustomisedSystem ? .restore : .updateKernel
case .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.swift
new file mode 100644
index 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.swift
index 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.swift
index 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) && patchesKernel
let 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.swift
index 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)
+ }
+
@Test
func `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.swift
index 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"))
+ }
+
@Test
func `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.swift
index 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 no
AVPBooter 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), which
Preboot 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.swift
index 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, features
case 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.plist
index 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.swift
index 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.swift
index 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)