Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Merge upstream main into iphone-product-tree

Jackyedfa61c36a33
diff --cc Research/0_binary_patch_comparison.md
index 144c78c9,da52f842..1d1ab019
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@@ -2642,42 -2677,35 +2677,75 @@@ removed. There is no migration
**Opting out.** `vphone-cli fw set-patches <vm> --block
kernel-cfw-paravirt_user_clients`, then re-patch.
+ ## Guest patches follow the selection, both ways (2026-10-04)
+
+ No new Apple binary patch. This changes how every guest-side patch in this
+ document (the dyld shared cache rows, the guest Mach-O and file patches, the
+ Preboot device-tree repairs) is applied after a VM exists, so it is recorded
+ here. Full write-up and live validation:
+ `Research/Firmware/post_creation_patch_changes.md`.
+
+ **Before.** `cfw install` applied the guest half from `PatchPlan.plist`, and
+ turning a guest patch off on an installed VM did nothing: the step was skipped
+ and the patched bytes stayed. The dyld cache patches were applied in place with
+ no record of what they replaced.
+
+ **Now.** `cfw install` and `cfw update-environment` resolve the guest half from
+ the VM's current `PatchSelection.plist`, apply what is on and revert what is
+ off. Mach-O, entitlement and guest-file patches revert from the `.bak` beside
+ the file; the Preboot device tree from `devicetree.img4.bak`; the dyld cache
+ from `.vphone-dsc-undo.json` in the cache directory, which holds the original
+ bytes of every content write a cache verb makes (slot hashes are re-derived by
+ re-attesting, not logged). Each cache verb takes `--undo-log`/`--undo-id`, and
+ the hidden `cfw patch-dsc-revert` verb applies the log. What is live is recorded
+ in the `Guest` part of `<vm>/PatchReceipt.plist`.
+
+ **Existing VMs.** A guest installed before this change has no undo log and no
+ backup for the files several patches share, so those patches are reported "not
+ revertible" when turned off and stay recorded as live; nothing is guessed. Every
+ dyld row above that a cache verb idempotently re-runs keeps its undo records, so
+ a revert works however many installs later it happens.
+
+ **Boot chain unchanged.** Boot-chain patches still reach a guest only through a
+ restore (AVPBooter through `fw patch`); `fw set-patches` and `fw patches <vm>`
+ say so per patch.
++
+## An iPhone guest's product description from D47AP (2026-10-04)
+
+An iPhone17,3 guest had no Siri page, no Camera Control, no Action Button and no
+Model Name, whatever its identity patches. Most of vphone600's `/product` is
+`syscfg/xxxx` placeholders (flag `0x8000`) that no syscfg fills on a VM, and
+MobileGestalt reads a placeholder as absent. An iPad guest already takes these
+from its board tree (`devicetree-cfw-ipad_*`); an iPhone guest did not, although
+its IPSW carries the iPhone's own tree, `Firmware/all_flash/DeviceTree.d47ap.im4p`.
+
+| Patch | Component | Effect |
+| --- | --- | --- |
- | `preboot-cfw-devicetree_iphone_product` (new) | Restored Preboot `devicetree.img4`, `cfw install` and `cfw update-environment`, iPhone guests | `DeviceTreePatcher.presentPhoneProduct` (`vphone-cli cfw patch-dt-iphone-product <dt> <board>`): fills the `iPhoneProductProperties` placeholders in `/product` from D47AP, adds `iPhoneAddedProductProperties`, and fills `/buttons/function-button_ringeren`. Only a placeholder is overwritten, only with a real board value. The board tree comes from `FirmwareOriginals`, or is recovered there from the VM's IPSW in `~/.vphone/ipsws` (`VPhoneBoardDeviceTree.need` now answers for iPhones too). |
++| `preboot-cfw-devicetree_iphone_product` (new) | Restored Preboot `devicetree.img4`, `cfw install` and `cfw update-environment`, iPhone17,3 guests (a board-presenting guest already boots its own board's description) | `DeviceTreePatcher.presentPhoneProduct` (`vphone-cli cfw patch-dt-iphone-product <dt> <board>`): fills the `iPhoneProductProperties` placeholders in `/product` from D47AP, adds `iPhoneAddedProductProperties`, and fills `/buttons/function-button_ringeren`. Only a placeholder is overwritten, only with a real board value. The board tree comes from `FirmwareOriginals`, or is recovered there from the VM's IPSW in `~/.vphone/ipsws` (`VPhoneBoardDeviceTree.need` now answers for the iPhone17,3 too). |
+
+What is copied, and why:
+
+| Group | Properties | What it turns on |
+| --- | --- | --- |
+| Name | `product-name`, `product-description` | About › Model Name |
+| Siri | `assistant`, `siri-gesture`, `dictation`, `offline-dictation`, `builtin-mics` | Settings › Siri, side-button Siri, dictation |
+| Buttons | `side-button-location`, `volume-up-button-location`, `volume-down-button-location`; added `ringer-button-location`, `camera-button-location`, `supports-camera-button`; `/buttons/function-button_ringeren` | Settings › Action Button and Camera Control (with Accessibility pages) |
+| Display, UI | `artwork-scale-factor`, `chrome-identifier`, `compatible-device-fallback`, `display-corner-radius`, `display-mirroring`, `oled-display`, `thin-bezel`, `large-format-phone`, `ui-pip`, `ui-reachability`, `ui-background-quality`, `ui-weather-quality`, `hme-in-arkit`, `carplay-2`, `location-reminders`, `watch-companion` | the rest of D47AP's description |
+
+Deliberately left as vphone600 has them: anything that promises hardware the VM
+does not have — `bluetooth-*`, `baseband-chipset`, `nfc-express`, `exclaves-enabled`,
+`has-*`, `graphics-featureset-*`, `framebuffer-identifier`, `wifi-chipset`, the
+display calibration placeholders — and the vphone600-only placeholders
+(`gestalt-variant-id`, `variant-name`, `thinning-product-type`,
+`jetsam-properties-product-type`, `vm-supports-generative-models`).
+`/buttons` keeps no `compatible`, so no button driver binds to it and the
+board's function reference in `function-button_ringeren` is never followed.
+
+Measured on iOS 26.6.2 (23G90) + cloudOS 26.4 (23E5207q), preset `standard` plus
+the nine identity patches, by applying the same edit to the installed tree by
+hand: Settings shows Siri, Camera Control (Camera and Accessibility pages) and
+the Action Button; Siri opens from a long side-button press (HID 0x0C/0x30); the
+Action Button's long press (HID 0x0B/0x2D) runs Flashlight and Camera with the
+Dynamic Island, with no tweak; the search field gains dictation. The guest boots
+normally. Not yet measured: the change on a VM without the identity patches, on
+iOS 18.x, and a Camera Control press.
diff --cc VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index fb48cd3a,b1f9d817..eff7559d
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@@ -292,14 -353,33 +353,38 @@@ struct VPhoneCustomFirmwareInstaller
// the old tree on its Data volume, which the host cannot reach. vphoned
// drops that cache at startup when it is older than the tree; see
// VPhoneDaemon/Daemon/GuestMobileGestaltCache.swift.
- try patchPreboot(
+ let buildVersion = plan?.parameters[FirmwareGuestSystemPatchSet.buildVersionParameter] ?? spoofBuild
+ let boardDeviceTree = try stageBoardDeviceTree(in: bundleDirectory, work: work)
++ // An environment update has no restore tree to read the device from;
++ // the VM's configuration says which board repair its tree takes.
++ let device = configuredGuestDevice(in: bundleDirectory) ?? guestDevice(of: restore)
+ liveGuest.formUnion(try patchPreboot(
volumes: volumes,
work: work,
plan: plan,
- guestDevice: guestDevice(of: restore),
+ priorGuest: priorGuest,
- guestDevice: guestDevice(of: restore),
++ guestDevice: device,
includeIdentity: mode == .full,
- boardDeviceTree: stageBoardDeviceTree(in: bundleDirectory, work: work),
- )
+ buildVersion: buildVersion,
+ boardDeviceTree: boardDeviceTree,
+ ))
+ // Selected patches this guest has nothing for, so the receipt does not
+ // report them as missing forever: the board audio repair on an
- // iPhone17,3, which has no board tree, and the build spoof with no value
- // set. A board-presenting guest whose board tree could not be recovered
- // is not among them: its repair is missing, and drift should keep
- // saying so.
++ // iPhone17,3, which has no board of its own to present, the iPhone
++ // product repair on a board-presenting guest, whose tree already
++ // carries its board's description, and the build spoof with no value
++ // set. A guest whose board tree could not be recovered is not among
++ // them: its repair is missing, and drift should keep saying so.
+ var notApplicableGuest = Set<String>()
- let device = configuredGuestDevice(in: bundleDirectory) ?? guestDevice(of: restore)
- if !device.presentsBoard {
++ if device.presentsBoard {
++ notApplicableGuest.insert(FirmwareGuestSystemPatchSet.prebootIPhoneProduct)
++ } else {
+ notApplicableGuest.insert(FirmwareGuestSystemPatchSet.prebootBoardAudio)
+ }
+ if buildVersion?.isEmpty ?? true {
+ notApplicableGuest.insert("system-systemversion-cfw-build_version")
+ }
+ notApplicableGuest.subtract(liveGuest)
// The snapshot rename is a full install's alone: it has already been
// done on any VM an environment update is allowed to run against, and
// this run creates no new snapshot to flip.
@@@ -1190,12 -1494,32 +1499,32 @@@
return VPhoneGuestDevice.detect(buildManifest: manifest) ?? .default
}
- /// `includeIdentity` is false for an environment update, which carries
- /// only the device tree repairs: the board repairs, which need
- /// `boardDeviceTree` (an iPad's audio node, an iPhone's product
- /// description), and the haptics removal, which every guest gets.
+ /// `includeIdentity` is false for an environment update, which carries only
- /// the device tree repairs: the board audio repair, which needs
- /// `boardDeviceTree`, the haptics removal and the microphone-array repair.
- /// `boardDeviceTree` is the iPad's own device tree, staged from the VM's
- /// `FirmwareOriginals`, or nil for an iPhone guest or a VM patched before
- /// `fw patch` kept it.
++ /// the device tree repairs: the board repair, which needs `boardDeviceTree`
++ /// (a board-presenting guest's audio node, an iPhone17,3's product
++ /// description), the haptics removal and the microphone-array repair.
+ /// `boardDeviceTree` is the guest's own board tree (`DeviceTree.<board>.im4p`),
+ /// staged from the VM's `FirmwareOriginals`, or nil when none is kept there.
+ ///
+ /// Returns the Preboot device-tree identifiers live afterwards, for the
+ /// receipt. The repairs share one personalized `devicetree.img4`, so there
+ /// is no per-repair inverse; instead the final tree is built in staging and
+ /// written only if it differs from what is on disk, so an unchanged result
+ /// never bumps the mtime (vphoned drops its MobileGestalt cache when the
+ /// tree is newer than it). The backup kept beside the tree is its state
+ /// *after* the identity rewrite and *before* the repairs:
+ ///
+ /// - full install: restore that backup to a clean base, apply identity,
+ /// re-take the backup from the post-identity bytes, then apply the
+ /// enabled repairs;
+ /// - environment update (no identity step): restore the backup, apply the
+ /// enabled repairs.
+ ///
+ /// A backup is taken only when the base is known clean — a backup already
+ /// existed, or no repair was live before. A tree repaired before backups
+ /// were kept has none, and an off repair on it is reported not revertible
+ /// and left in place.
+ @discardableResult
private func patchPreboot(
volumes: [[String: Any]],
work: WorkDirectory,
@@@ -1218,30 -1538,39 +1543,43 @@@
let identity = FirmwareGuestIdentityPatchSet.prebootDeviceTreeIdentity
var rewriteIdentity = false
if includeIdentity {
- if guestDevice.isPad {
+ if guestDevice.presentsBoard {
print(" [·] \(identity): skipped, the device tree already presents \(guestDevice.productType)")
} else {
- rewriteIdentity = on(identity)
+ rewriteIdentity = enabled(identity)
+ if !rewriteIdentity { print(" [·] \(identity): off in the current selection") }
}
+ } else if priorGuest.contains(identity) {
+ // An environment update does not touch the identity rewrite; if the
+ // last install wrote it, it is still live.
+ live.insert(identity)
}
- let spoofBuild = includeIdentity ? spoofBuild : nil
- var repairs: [(verb: String, arguments: [String])] = []
+
+ // The repairs, which share the one devicetree.img4.
+ var repairGroup: [(id: String, verb: String, arguments: [String])] = []
if let boardDeviceTree {
- if guestDevice.isPad {
- if on(FirmwareGuestSystemPatchSet.prebootBoardAudio) {
- repairs.append(("patch-dt-board-audio", [boardDeviceTree.path]))
- }
- } else if on(FirmwareGuestSystemPatchSet.prebootIPhoneProduct) {
- repairs.append(("patch-dt-iphone-product", [boardDeviceTree.path]))
- repairGroup.append((FirmwareGuestSystemPatchSet.prebootBoardAudio, "patch-dt-board-audio", [boardDeviceTree.path]))
++ if guestDevice.presentsBoard {
++ repairGroup.append((FirmwareGuestSystemPatchSet.prebootBoardAudio, "patch-dt-board-audio", [boardDeviceTree.path]))
++ } else {
++ repairGroup.append((FirmwareGuestSystemPatchSet.prebootIPhoneProduct, "patch-dt-iphone-product", [boardDeviceTree.path]))
+ }
}
- if on(FirmwareGuestSystemPatchSet.prebootHaptics) {
- repairs.append(("patch-dt-haptics", []))
+ repairGroup.append((FirmwareGuestSystemPatchSet.prebootHaptics, "patch-dt-haptics", []))
+ repairGroup.append((FirmwareGuestSystemPatchSet.prebootMicrophoneArray, "patch-dt-microphone-array", []))
+ let repairsOn = repairGroup.filter { enabled($0.id) }
+ for off in repairGroup where !enabled(off.id) {
+ print(" [·] \(off.id): off in the current selection")
}
- if on(FirmwareGuestSystemPatchSet.prebootMicrophoneArray) {
- repairs.append(("patch-dt-microphone-array", []))
- }
- guard rewriteIdentity || !repairs.isEmpty || !(spoofBuild ?? "").isEmpty else { return }
+
+ let buildID = "system-systemversion-cfw-build_version"
+
+ // Mount only when there is device-tree work to do, a repair to revert,
+ // or a build spoof to apply or revert.
+ let mayRevertRepair = repairGroup.contains { !enabled($0.id) && priorGuest.contains($0.id) }
+ let wantsBuild = (buildVersion.map { !$0.isEmpty } ?? false) && enabled(buildID)
+ let touchesBuild = wantsBuild || priorGuest.contains(buildID)
+ guard rewriteIdentity || !repairsOn.isEmpty || mayRevertRepair || touchesBuild else { return live }
+
guard
let preboot = volumes.first(where: { ($0["Roles"] as? [String])?.contains("Preboot") == true }),
let device = preboot["DeviceIdentifier"] as? String
@@@ -1306,14 -1719,11 +1728,15 @@@
return work.file(board.name)
}
- /// Make sure an iPad VM's `FirmwareOriginals` holds the board tree that
+ /// Make sure a VM's `FirmwareOriginals` holds the board tree that
/// `stageBoardDeviceTree` stages, recovering it from the IPSW the VM was
- /// made from when it has none. An iPad VM patched before `fw patch` kept it
- /// needs it for the board audio repair, without which VirtualAudio looks
- /// for the iPhone's tunings and the guest has no sound. An iPhone VM needs
- /// it for the product description repair, without which MobileGestalt
- /// reads Siri, Camera Control, the Action Button and the model name as
- /// absent; `fw patch` does not keep an iPhone's, so it always comes from here.
- /// made from when a VM patched before `fw patch` kept it has none. Without
- /// it the board audio repair cannot run, VirtualAudio looks for the
- /// iPhone's tunings, and the guest has no sound.
++ /// made from when it has none. A board-presenting VM patched before `fw
++ /// patch` kept it needs it for the board audio repair, without which
++ /// VirtualAudio looks for the iPhone's tunings and the guest has no sound.
++ /// An iPhone17,3 VM needs it for the product description repair, without
++ /// which MobileGestalt reads Siri, Camera Control, the Action Button and the
++ /// model name as absent; `fw patch` does not keep the iPhone17,3's, so it
++ /// always comes from here.
///
/// The IPSW cache and the VM folder are the caller's, so the search and
/// the write run with the caller's credentials, as `cfw install` records
@@@ -1330,14 -1740,11 +1753,14 @@@
plan: VPhoneVirtualMachinePatchPlan?,
invokingUser: VPhoneInvokingUser?,
) {
- guard plan?.isEnabled(FirmwareGuestSystemPatchSet.prebootBoardAudio) ?? true else { return }
let device = configuredGuestDevice(in: bundleDirectory) ?? guestDevice(of: restore)
- let repair = device.isPad ? FirmwareGuestSystemPatchSet.prebootBoardAudio : FirmwareGuestSystemPatchSet.prebootIPhoneProduct
++ let repair = device.presentsBoard ? FirmwareGuestSystemPatchSet.prebootBoardAudio : FirmwareGuestSystemPatchSet.prebootIPhoneProduct
+ guard plan?.isEnabled(repair) ?? true else { return }
let tree = (device.boardDeviceTreePath as NSString).lastPathComponent
let originals = VPhoneBundleOperations.firmwareOriginalsDirectoryName
- let skipped = device.isPad
- let skipped = "[!] Board audio repair skipped, so this \(device.productType) guest will have no sound:"
++ let skipped = device.presentsBoard
+ ? "[!] Board audio repair skipped, so this \(device.productType) guest will have no sound:"
+ : "[!] iPhone product repair skipped, so this \(device.productType) guest will have no Siri, Camera Control, Action Button or Model Name:"
do {
let need = try VPhoneBoardDeviceTree.need(
device: device,
diff --cc VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneBoardDeviceTree.swift
index fc321b7c,ced2ea03..39a6ba51
--- a/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneBoardDeviceTree.swift
+++ b/VPhoneKit/VPhoneArchiveKit/Transfer/VPhoneBoardDeviceTree.swift
@@@ -2,9 -2,8 +2,10 @@@ import Darwi
import Foundation
import VPhoneCoreKit
-/// An iPad guest's own device tree, `DeviceTree.<board>.im4p`, as a VM folder
-/// keeps it and as the IPSW the VM was made from carries it.
+/// A guest's own device tree, `DeviceTree.<board>.im4p`, as a VM folder
- /// keeps it and as the IPSW the VM was made from carries it: an iPad's for its
- /// audio node, an iPhone's (`DeviceTree.d47ap.im4p`) for its product description.
++/// keeps it and as the IPSW the VM was made from carries it: a board-presenting
++/// guest's for its audio node, an iPhone17,3's (`DeviceTree.d47ap.im4p`) for its
++/// product description.
///
/// `fw patch` keeps the tree in the VM's `FirmwareOriginals`, mirrored under
/// the restore tree's name, and the board audio repair that `cfw install` and
@@@ -99,9 -98,7 +100,10 @@@ public enum VPhoneBoardDeviceTree
/// What a run has to do about a VM's board tree.
public enum Need: Equatable {
- /// Nothing to do. Every guest has a board tree now — an iPad's carries
- /// its audio node, an iPhone's its product description — so `need`
- /// does not answer this; it stays for callers that switch over `Need`.
- /// An iPhone17,3 guest, which has no board tree.
++ /// Nothing to do. Every guest has a board tree now — a board-presenting
++ /// guest's carries its audio node, an iPhone17,3's its product
++ /// description — so `need` does not answer this; it stays for callers
++ /// that switch over `Need`.
case none
/// `FirmwareOriginals` already holds one, or several, which staging
/// refuses to choose between.