Run a virtual iPhone on an Apple Silicon Mac.
Swift
// DeviceTreeGuestDevicePatches.swift — The board presentation of the vphone600 tree.
//
// vphone600ap is a virtual iPhone: `artwork-device-idiom` is "phone", the root
// `model` is iPhone99,11, and most `/product` properties are `syscfg/xxxx`
// placeholders (flag 0x8000) that no syscfg on a VM ever fills. An iPadOS
// userland reads the same nodes, so a guest restored from an iPad IPSW lays
// itself out as a phone unless the tree it boots says otherwise, and one
// restored from another iPhone's IPSW finds placeholders where its own panel
// size, buttons and audio tunings should be.
//
// The answers come from the board's own device tree, `DeviceTree.<board>.im4p`,
// which the IPSW carries and the restore tree keeps. Every guest device but the
// iPhone XS Max gets them (`VPhoneGuestDevice.presentsBoard`); the patch IDs keep
// the `ipad_` names they were introduced with, because presets list them.
//
// - the `/product` properties in `copiedProductProperties` take the board's
// values, and are removed where the board has none — so an iPad mini keeps
// `disable-chamois` and an M-series iPad, which has Stage Manager, does not;
// - the phone-only placeholders (Dynamic Island, reachability, ringer
// switch, volume-button geometry, CarPlay, Watch pairing) take the board's
// values, and are removed where it has none (every one on an iPad), which
// is what "absent" means to MobileGestalt;
// - the root and `/product` identity becomes the board's, with VPHONE600AP
// kept second in `compatible` so the platform expert still binds.
//
// What stays vphone600: everything that describes the virtual hardware —
// `graphics-featureset-class` (the paravirtual GPU is APPLE7, not the board's),
// `framebuffer-identifier`, `has-virtualization`, the guest agent port, memory
// class and boot flags.
//
// Only the installed tree carries these. Restore boots `RestoreDeviceTree`,
// which keeps the iPhone99,11 identity `restored_external` checks against the
// manifest; see `FirmwareManifest.separateGuestDeviceTree`.
//
// One edit here is every guest's, not only an iPad's: `/product/haptics` goes
// from every tree of every role, because no VM has the actuator or the haptic
// server the node promises. See `removeHaptics(from:)`.
import Foundation
import Img4tool
import VPhoneCoreKit
import VPhonePatchKit
extension DeviceTreePatcher {
// MARK: - Role
/// Which of the VM's device trees a patcher is rewriting.
public enum TreeRole: Sendable {
/// The one file an iPhone guest restores and boots with.
case shared
/// An iPad guest's `RestoreDeviceTree`: patched exactly as an iPhone
/// guest's tree, so restore sees the board it always has.
case restore
/// An iPad guest's installed `DeviceTree`, which carries its identity.
case installed
}
// MARK: - Patch IDs
static let iPadArtworkPatch = "devicetree-cfw-ipad_artwork"
static let iPadProductPatch = "devicetree-cfw-ipad_product"
static let iPadButtonsPatch = "devicetree-cfw-ipad_buttons"
static let iPadIdentityPatch = "devicetree-cfw-ipad_identity"
static let iPadAudioPatch = "devicetree-cfw-ipad_audio"
static let tvAppArchitecturePatch = "devicetree-cfw-tv_app_architecture"
static let homeViewTouchPatch = "devicetree-cfw-homeview_touch"
static let homePodProductPatch = "devicetree-cfw-homepod_product"
static let watchPresentationPatch = "devicetree-cfw-watch_presentation"
static let watchDriverKitPatch = "devicetree-cfw-watch_driverkit"
static let watchCompanionPatch = "devicetree-cfw-watch_companion"
static let hapticsPatch = "devicetree-cfw-product_haptics_node"
static let microphoneArrayPatch = "devicetree-cfw-product_audio_microphone_array"
// MARK: - What Is Copied
/// `/product` properties taken from the board's tree, by patch.
static let copiedProductProperties: [(name: String, patchID: String)] = [
// What UIKit and SpringBoard lay out against.
("artwork-device-idiom", iPadArtworkPatch),
("artwork-device-subtype", iPadArtworkPatch),
("artwork-scale-factor", iPadArtworkPatch),
// The device MobileGestalt reports.
("fdr-product-type", iPadIdentityPatch),
("sub-product-type", iPadIdentityPatch),
("unique-model", iPadIdentityPatch),
// Name, chrome, and the panel and camera geometry.
("product-name", iPadProductPatch),
("product-description", iPadProductPatch),
("chrome-identifier", iPadProductPatch),
("compatible-device-fallback", iPadProductPatch),
("display-corner-radius", iPadProductPatch),
("display-mirroring", iPadProductPatch),
("side-button-location", iPadProductPatch),
("front-cam-offset-from-center", iPadProductPatch),
("rear-cam-offset-from-center", iPadProductPatch),
("thin-bezel", iPadProductPatch),
("ui-pip", iPadProductPatch),
("ui-background-quality", iPadProductPatch),
("ui-weather-quality", iPadProductPatch),
("assistant", iPadProductPatch),
("dictation", iPadProductPatch),
("offline-dictation", iPadProductPatch),
("builtin-mics", iPadProductPatch),
// Multitasking: Slide Over, the overlay and pinned app slots, and
// `disable-chamois`, which turns Stage Manager off where the board has it.
("medusa-overlay-app-capability", iPadProductPatch),
("ui-floating-live-app", iPadProductPatch),
("ui-overlay-app", iPadProductPatch),
("ui-pinned-app", iPadProductPatch),
("disable-chamois", iPadProductPatch),
("natural-volume-arrangement", iPadProductPatch),
]
/// vphone600 `/product` properties that describe a phone. Removed unless the
/// board's tree has them too.
static let iPhoneOnlyProductProperties = [
"island-notch-location",
"large-format-phone",
"ui-reachability",
"oled-display",
"siri-gesture",
"hme-in-arkit",
"location-reminders",
"volume-up-button-location",
"volume-down-button-location",
"watch-companion",
"carplay-2",
"car-integration",
]
/// Root properties taken from the board's tree. `compatible` is rebuilt.
static let copiedRootProperties = ["model", "target-type", "target-sub-type"]
/// The placeholder bit in a property's flags: the value is a `syscfg/` key,
/// not data.
static let placeholderFlag: UInt16 = 0x8000
// MARK: - Edits
/// One change to an existing node: a property set (added when missing) or
/// removed.
struct GuestEdit {
enum Action {
case set(Data)
case remove
}
let nodePath: [String]
let property: String
let action: Action
let patchID: String
}
/// The edits that make the vphone600 tree present the board whose tree is
/// `source`.
static func guestEdits(from source: DTNode) throws -> [GuestEdit] {
let product = ["device-tree", "product"]
let sourceProduct = try child(of: source, named: "product")
var edits: [GuestEdit] = []
func value(_ node: DTNode, _ name: String) -> Data? {
guard let property = node.properties.first(where: { $0.name == name }),
property.flags & placeholderFlag == 0
else { return nil }
return property.value
}
// J42d's tvOS tree declares arm64 apps. Keep the source's concrete
// value rather than the virtual phone's architecture; this edit is TV
// presentation only and must not change existing phone or pad output.
if let idiom = value(sourceProduct, "artwork-device-idiom"),
["tv", "home"].contains(String(decoding: idiom.prefix { $0 != 0 }, as: UTF8.self))
{
guard let architecture = value(sourceProduct, "app-macho-architecture"), !architecture.isEmpty else {
throw PatcherError.patchSiteNotFound("DeviceTree: the TV board's tree has no concrete app-macho-architecture")
}
edits.append(GuestEdit(nodePath: product, property: "app-macho-architecture",
action: .set(architecture), patchID: tvAppArchitecturePatch))
}
// HomeView's physical SPI touch controller is not present in the VM.
// Keep USB touch and start driverkitd for its HID dext, as on watchOS.
if let model = value(source, "model"),
["HomeAccessory17,1", "HomeAccessory17,2"].contains(String(decoding: model.prefix { $0 != 0 }, as: UTF8.self)) {
edits.append(GuestEdit(nodePath: product, property: "supports-driverkit",
action: .set(Data([1, 0, 0, 0])), patchID: homeViewTouchPatch))
}
// B520's accessory identity is independent of its artwork idiom,
// which is a syscfg placeholder rather than "tv". HomePod services
// query these capabilities through MobileGestalt.
if let model = value(source, "model"),
String(decoding: model.prefix { $0 != 0 }, as: UTF8.self) == "AudioAccessory5,1"
{
for name in ["horseman", "siri-hub", "app-macho-architecture"] {
let action: GuestEdit.Action = value(sourceProduct, name).map { .set($0) } ?? .remove
edits.append(GuestEdit(nodePath: product, property: name,
action: action, patchID: homePodProductPatch))
}
// Keep the VM product token. Audio uses VirtualAudio's local
// ProductIDOverride; a donor token changes unrelated MG clients.
}
if let idiom = value(sourceProduct, "artwork-device-idiom"),
String(decoding: idiom.prefix { $0 != 0 }, as: UTF8.self) == "watch"
{
edits += watchEdits(product: product, value: { value(sourceProduct, $0) })
}
for (name, patchID) in copiedProductProperties {
let action: GuestEdit.Action = value(sourceProduct, name).map { .set($0) } ?? .remove
edits.append(GuestEdit(nodePath: product, property: name, action: action, patchID: patchID))
}
for name in iPhoneOnlyProductProperties {
if let board = value(sourceProduct, name) {
edits.append(GuestEdit(nodePath: product, property: name, action: .set(board), patchID: iPadProductPatch))
} else {
edits.append(GuestEdit(nodePath: product, property: name, action: .remove, patchID: iPadProductPatch))
}
}
// An iPad has no ring/silent switch; nor does a board whose tree lacks one.
let sourceButtons = try? child(of: source, named: "buttons")
if sourceButtons.flatMap({ value($0, "function-button_ringeren") }) == nil {
edits.append(GuestEdit(nodePath: ["device-tree", "buttons"], property: "function-button_ringeren",
action: .remove, patchID: iPadButtonsPatch))
}
for name in copiedRootProperties {
guard let board = value(source, name) else {
throw PatcherError.patchSiteNotFound("DeviceTree: the board's tree has no root \(name)")
}
edits.append(GuestEdit(nodePath: ["device-tree"], property: name, action: .set(board), patchID: iPadIdentityPatch))
}
guard let compatible = value(source, "compatible"),
let first = compatible.split(separator: 0, omittingEmptySubsequences: true).first
else {
throw PatcherError.patchSiteNotFound("DeviceTree: the board's tree has no root compatible")
}
edits.append(GuestEdit(nodePath: ["device-tree"], property: "compatible",
action: .set(Self.compatible(board: Data(first))), patchID: iPadIdentityPatch))
return edits
}
// MARK: - Watch
/// `/product` properties a watch's display is described by, beyond those
/// every board copies.
static let watchDisplayProperties = ["artwork-display-gamut", "artwork-dynamic-displaymode", "framebuffer-identifier"]
/// The gestalt variant tags MobileGestalt reads in place of syscfg on the
/// VM, and the board's `/product` property each stands for. vphone600's
/// carry the D47's values; a watch whose tags still describe a phone shows
/// no UI ("unsupported screen class"). A property the board lacks is a
/// boolean it does not have: 0.
static let watchVariantTags: [(tag: String, property: String)] = [
("tag-ards", "artwork-device-subtype"),
("tag-arsf", "artwork-scale-factor"),
("tag-codf", "compatible-device-fallback"),
("tag-tprt", "sub-product-type"),
("tag-crid", "chrome-identifier"),
("tag-dcrd", "display-corner-radius"),
("tag-fbid", "framebuffer-identifier"),
("tag-prde", "product-description"),
("tag-isnl", "island-notch-location"),
("tag-waco", "watch-companion"),
]
static let watchVariantNode = ["device-tree", "product", "vphone600-gestalt-variants", "d47vm2025vre-variant"]
/// The edits a watch board needs besides the common copy: its display
/// properties, the variant tags, and `supports-driverkit`. The VM's touch
/// screen is a USB device whose HID driver is a dext, and launchd starts
/// driverkitd only on a device tree that says so; a real watch has no USB
/// touch screen, so N227b's tree does not.
static func watchEdits(product: [String], value: (String) -> Data?) -> [GuestEdit] {
var edits: [GuestEdit] = []
for name in watchDisplayProperties {
let action: GuestEdit.Action = value(name).map { .set($0) } ?? .remove
edits.append(GuestEdit(nodePath: product, property: name, action: action, patchID: watchPresentationPatch))
}
let absent = Data(count: 4)
for (tag, property) in watchVariantTags {
edits.append(GuestEdit(nodePath: watchVariantNode, property: tag,
action: .set(value(property) ?? absent), patchID: watchPresentationPatch))
}
edits.append(GuestEdit(nodePath: product, property: "supports-driverkit",
action: .set(Data([1, 0, 0, 0])), patchID: watchDriverKitPatch))
return edits
}
/// `compatible` with the board first, so `hw.model` reads it, and
/// VPHONE600AP kept for the platform expert's AppleVMApple1IO match.
static func compatible(board: Data) -> Data {
board + Data("\0VPHONE600AP\0AppleVirtualPlatformARM\0".utf8)
}
private static func child(of node: DTNode, named name: String) throws -> DTNode {
guard let child = optionalChild(of: node, named: name) else {
throw PatcherError.patchSiteNotFound("DeviceTree: the board's tree has no \(name) node")
}
return child
}
private static func optionalChild(of node: DTNode, named name: String) -> DTNode? {
node.children.first { child in
child.properties.contains { $0.name == "name" && $0.value.prefix(while: { $0 != 0 }) == Data(name.utf8) }
}
}
// MARK: - Audio
/// AppleImage4's uint32 identity callback reads this exact four-byte
/// property from /product. The research kernel's iOS value rejects a tvOS
/// DDI's signed CLAS before APFS can mount it. Keep equality verification
/// and supply the native HomePod class instead. See developer_disk_images.md.
static func presentHomePodCryptexClass(in root: DTNode) throws -> (before: Data?, after: Data)? {
try requireHomePodMini(root)
let product = try child(of: root, named: "product")
let values = product.properties.filter { $0.name == "cryptex1-product-class" }
guard values.count <= 1 else {
throw PatcherError.invalidFormat("HomePod cryptex class: duplicated product class")
}
var value = UInt32(0xf4).littleEndian
let bytes = withUnsafeBytes(of: &value) { Data($0) }
// TempPod's restored tree omits this property and the running kernel
// reports the research iOS class. Supply the native class explicitly.
guard let property = values.first else {
product.properties.append(DTProperty(name: "cryptex1-product-class", flags: 0, value: bytes, valueOffset: 0))
return (nil, bytes)
}
guard property.flags == 0, property.value.count == 4,
[UInt32(0xf2), UInt32(0xf4)].contains(property.value.loadLE(UInt32.self, at: 0)) else {
throw PatcherError.invalidFormat("HomePod cryptex class: expected one concrete iOS or tvOS uint32 product class")
}
guard property.value.loadLE(UInt32.self, at: 0) != 0xf4 else { return nil }
let before = property.value
property.value = bytes
return (before, property.value)
}
/// MobileGestalt matches this exact 20-byte donor token against its product
/// table; VirtualAudio uses that result to select the HomePod mini's enum 4
/// routing. Root model strings alone do not select the native audio family.
/// Accept a retained donor IM4P or its decoded flat payload, never a payload
/// invented from the product name or an iPhone ProductIDOverride.
public static func homePodAudioProductID(from data: Data) throws -> Data {
let payload: Data
if let im4p = try? IM4P(data) {
guard im4p.fourcc == "dtre", !im4p.isEncrypted else {
throw PatcherError.invalidFormat("HomePod audio product: expected an unencrypted dtre IM4P")
}
payload = try im4p.payload()
} else {
payload = data
}
let parser = DeviceTreePatcher(data: payload, verbose: false)
return try homePodAudioProductID(from: parser.parsePayload(payload))
}
private static func requireHomePodMini(_ root: DTNode) throws {
let models = root.properties.filter { $0.name == "model" }
guard models.count == 1, let model = models.first, model.flags == 0,
String(decoding: model.value.prefix { $0 != 0 }, as: UTF8.self) == "AudioAccessory5,1"
else {
throw PatcherError.invalidFormat("HomePod audio product: expected the AudioAccessory5,1 board tree")
}
}
static func homePodAudioProductID(from source: DTNode) throws -> Data {
try requireHomePodMini(source)
let product = try child(of: source, named: "product")
let properties = product.properties.filter { $0.name == "product-id" }
guard properties.count == 1, let property = properties.first,
property.flags == 0, property.value.count == 20
else {
throw PatcherError.invalidFormat("HomePod audio product: donor product-id must be one concrete 20-byte value")
}
return property.value
}
/// Replace only the HomePod's audio product token. The Preboot repair uses
/// this independently of the board-audio-node repair and keeps the VM's
/// virtual audio hardware and unrelated product capabilities unchanged.
static func presentHomePodAudioProduct(in root: DTNode, from source: DTNode) throws -> (before: Data?, after: Data)? {
try requireHomePodMini(root)
let value = try homePodAudioProductID(from: source)
let product = try child(of: root, named: "product")
guard product.properties.filter({ $0.name == "product-id" }).count <= 1 else {
throw PatcherError.invalidFormat("HomePod audio product: installed product-id is duplicated")
}
if let existing = product.properties.first(where: { $0.name == "product-id" }) {
guard existing.value != value || existing.flags != 0 else { return nil }
let before = existing.value
existing.value = value
existing.flags = 0
return (before, value)
}
product.properties.append(DTProperty(name: "product-id", flags: 0, value: value, valueOffset: 0))
return (nil, value)
}
// MARK: - Foldable product identity
/// The 20-byte product token of a foldable board's own tree. CoreMotion
/// selects its motion capabilities from this token — the hinge-angle
/// manager among them — and the frameworks' `isV68` checks key on it; the
/// VM platform's token selects none. Accept a retained donor IM4P or its
/// decoded flat payload, never a token invented from the product name.
public static func foldableProductID(from data: Data) throws -> Data {
let payload: Data
if let im4p = try? IM4P(data) {
guard im4p.fourcc == "dtre", !im4p.isEncrypted else {
throw PatcherError.invalidFormat("Foldable product: expected an unencrypted dtre IM4P")
}
payload = try im4p.payload()
} else {
payload = data
}
let parser = DeviceTreePatcher(data: payload, verbose: false)
return try foldableProductID(from: parser.parsePayload(payload))
}
static func foldableProductID(from source: DTNode) throws -> Data {
let subtypes = rootSubtypes(of: source)
guard subtypes.count == 1,
CustomFirmwarePostRestoreDeviceTree.foldableVMSubtypes.keys.contains(subtypes[0])
else {
throw PatcherError.invalidFormat(
"Foldable product: expected a foldable board tree, not \(subtypes.isEmpty ? "no sub-type" : subtypes.joined(separator: ", "))",
)
}
let product = try child(of: source, named: "product")
let properties = product.properties.filter { $0.name == "product-id" }
guard properties.count == 1, let property = properties.first,
property.flags == 0, property.value.count == 20
else {
throw PatcherError.invalidFormat("Foldable product: donor product-id must be one concrete 20-byte value")
}
return property.value
}
/// Replace the installed tree's product token with the foldable board's
/// own. The installed tree must itself be a foldable guest — the board's
/// own sub-type or the VM value the sub-type repair writes — so a
/// foldable board's token never reaches another guest. A tree that
/// already carries the token, or is not a foldable guest, comes back
/// unchanged.
static func presentFoldableProductID(in root: DTNode, from source: DTNode) throws -> (before: Data?, after: Data)? {
let subtypes = rootSubtypes(of: root)
guard subtypes.count == 1,
CustomFirmwarePostRestoreDeviceTree.foldableSubtypes.contains(subtypes[0])
else { return nil }
let value = try foldableProductID(from: source)
let product = try child(of: root, named: "product")
guard product.properties.filter({ $0.name == "product-id" }).count <= 1 else {
throw PatcherError.invalidFormat("Foldable product: installed product-id is duplicated")
}
if let existing = product.properties.first(where: { $0.name == "product-id" }) {
guard existing.value != value || existing.flags != 0 else { return nil }
let before = existing.value
existing.value = value
existing.flags = 0
return (before, value)
}
product.properties.append(DTProperty(name: "product-id", flags: 0, value: value, valueOffset: 0))
return (nil, value)
}
/// Give a foldable guest's `/product` the board's panel nodes.
///
/// A foldable board describes each panel in a `/product` child carrying
/// `surface-type` (V68AP: `display0` the cover, `display1` the inner
/// panel): rotation, scale, corner radii, chrome and framebuffer
/// identifiers, camera and button geometry. MobileGestalt counts those
/// children for `MGGetLogicalDeviceDisplayCount` and reads them into
/// `DisplayExtendedProperties`, which QuartzCore hands each hardware
/// display as its `extendedProperties`. vphone600 has no such child, so
/// the guest reports one display and no properties. Each node is copied
/// with every property, `AAPL,phandle` renumbered above the tree's
/// highest, and they go first under `/product` in the board's order. Like
/// the product token, they reach only a foldable guest. Returns the added
/// nodes serialized, empty when the tree already has panel nodes or is
/// not a foldable guest.
static func presentFoldableDisplays(in root: DTNode, from source: DTNode) throws -> [Data] {
let subtypes = rootSubtypes(of: root)
guard subtypes.count == 1,
CustomFirmwarePostRestoreDeviceTree.foldableSubtypes.contains(subtypes[0])
else { return [] }
func isPanel(_ node: DTNode) -> Bool {
node.properties.contains { $0.name == "surface-type" }
}
let panels = try child(of: source, named: "product").children.filter(isPanel)
guard panels.count >= 2 else {
throw PatcherError.invalidFormat("Foldable displays: the board's /product has \(panels.count) panel nodes, not two")
}
let product = try child(of: root, named: "product")
guard !product.children.contains(where: isPanel) else { return [] }
var phandle = maximumPhandle(in: root)
let nodes = panels.map { panel in
phandle += 1
let number = phandle
let node = DTNode()
node.properties = panel.properties.map { property in
let value = property.name == "AAPL,phandle"
? withUnsafeBytes(of: number.littleEndian) { Data($0) } : property.value
return DTProperty(name: property.name, flags: property.flags, value: value, valueOffset: 0)
}
return node
}
product.children.insert(contentsOf: nodes, at: 0)
return nodes.map(serialize)
}
private static func rootSubtypes(of node: DTNode) -> [String] {
node.properties
.filter { $0.name == "target-sub-type" }
.compactMap { String(data: $0.value.prefix { $0 != 0 }, encoding: .utf8) }
}
/// What `presentBoardAudio` changed: the audio node's serialized bytes
/// before and after, empty when there was no node.
struct BoardAudioChange {
let before: Data
let after: Data
}
/// Give `root`'s `/product/audio` the properties of the board's.
///
/// The tree's audio node, when there is one, came from
/// `devicetree-cfw-product_audio_node`, which copies the D47 iPhone's. Its
/// `acoustic-id` (8018) names `/Library/Audio/Tunings/AID8018`, which an iPad
/// image does not ship; VirtualAudio then builds no microphone sub-ports, and
/// on an iPad, whose board answers yes to stereo and webcam recording, it
/// throws `PRECONDITION FAILURE` in `RoutingSettings_J98` and never
/// initializes, so the guest has no audio route at all. The board's own node
/// names the tunings its image carries (AID2029 on J820).
///
/// Every property is copied as the board has it, placeholders included,
/// except `AAPL,phandle`, which is the board tree's and could collide in
/// this one; a property the board's node lacks is removed. The node is
/// added under `/product` when the tree has none. Returns nil when the
/// board has no audio node or the tree already matches it.
static func presentBoardAudio(in root: DTNode, from source: DTNode) -> BoardAudioChange? {
guard
let sourceProduct = optionalChild(of: source, named: "product"),
let sourceAudio = optionalChild(of: sourceProduct, named: "audio"),
let product = optionalChild(of: root, named: "product")
else { return nil }
let copied = sourceAudio.properties.filter { $0.name != "AAPL,phandle" }
func describe(_ properties: [DTProperty]) -> [String: (UInt16, Data)] {
Dictionary(properties.map { ($0.name, ($0.flags, $0.value)) }, uniquingKeysWith: { first, _ in first })
}
let existing = optionalChild(of: product, named: "audio")
if let existing {
let lhs = describe(existing.properties.filter { $0.name != "AAPL,phandle" })
let rhs = describe(copied)
if lhs.count == rhs.count, lhs.allSatisfy({ name, entry in
rhs[name].map { $0.0 == entry.0 && $0.1 == entry.1 } ?? false
}) {
return nil
}
}
let before = existing.map(serialize) ?? Data()
let node = existing ?? DTNode()
let phandle = node.properties.filter { $0.name == "AAPL,phandle" }
node.properties = copied.map {
DTProperty(name: $0.name, flags: $0.flags, value: $0.value, valueOffset: 0)
} + phandle
if existing == nil {
product.children.append(node)
}
return BoardAudioChange(before: before, after: serialize(node))
}
// MARK: - Haptics
/// Remove `root`'s `/product/haptics`. Returns the node's serialized bytes,
/// or nil when the tree has none.
///
/// vphone600 carries the node (`closed-loop`, `supports-3rd-party-haptics`),
/// so MobileGestalt answers yes to `DeviceSupportsHaptics` and
/// `DeviceSupportsClosedLoopHaptics`. ToneLibrary reads the pair as
/// "synchronized vibrations", sets `playHapticTracks` on every tone's player
/// item, and mediaplaybackd then builds a `CHHapticEngine` beside the audio
/// queue. A VM has no haptic server behind `com.apple.audio.hapticd`: the
/// engine's XPC setup times out six times, `FigHapticEngineCreate` fails
/// with 4099, and `itemfig_rebuildRenderPipelinesAndBoss` fails the whole
/// item with it — the tone's audio never starts. That was measured on an
/// iPad guest and on an iPhone guest alike. An iPad's own tree has no
/// haptics node and an iPhone's has one, so what the guest's board carries
/// does not decide it: no VM has the actuator or the server, so no guest
/// tree keeps the node, whatever its role.
static func removeHaptics(from root: DTNode) -> Data? {
guard
let product = optionalChild(of: root, named: "product"),
let haptics = optionalChild(of: product, named: "haptics")
else { return nil }
product.children.removeAll { $0 === haptics }
return serialize(haptics)
}
// MARK: - Microphone Array
/// `/product/audio` properties that promise processing built on the
/// board's microphone array.
static let microphoneArrayProperties = ["supports-spatial-audio-capture", "supports-audio-mix"]
/// Remove `microphoneArrayProperties` from `root`'s `/product/audio`.
/// Returns each removed property with its value, in that order; empty when
/// the tree has no audio node or none of them.
///
/// The iPhone guest's audio node is the D47's, and an iPad guest's is its
/// board's; either can say the device captures spatial audio and analyses
/// an Audio Mix. A VM's microphone is the Mac's, one or two channels
/// through virtio-snd, not the four-microphone array those answers stand
/// for. With them iOS 27's Voice Memos records through the SpatialCapture
/// route, whose DSP graph (`flexible_video_recording`, four microphones in,
/// first-order ambisonics out) gives silence for the two real channels,
/// and through the Audio Mix analysis, whose neural net faults in
/// cameracaptured. See `Research/Guest/ios27_capture_microphone_source.md`.
static func removeMicrophoneArrayClaims(from root: DTNode) -> [(name: String, value: Data)] {
guard
let product = optionalChild(of: root, named: "product"),
let audio = optionalChild(of: product, named: "audio")
else { return [] }
var removed: [(name: String, value: Data)] = []
for name in microphoneArrayProperties {
guard let index = audio.properties.firstIndex(where: { $0.name == name }) else { continue }
removed.append((name, audio.properties[index].value))
audio.properties.remove(at: index)
}
return removed
}
// MARK: - iPhone Product
/// `/product` properties an iPhone guest takes from its board's tree when
/// its own holds a `syscfg/` placeholder for them.
///
/// On vphone600 these are placeholders no syscfg fills, and MobileGestalt
/// reads a placeholder as absent. Settings then has no Siri page (`assistant`),
/// no Model Name (`product-name`), no dictation (`dictation`), and the
/// button geometry SpringBoard lays out against is missing. Measured on a
/// 26.6.2 iPhone17,3 guest: with these from D47AP, Siri opens from the side
/// button, dictation appears, and Camera Control and the Action Button are
/// in Settings (with `iPhoneAddedProductProperties` and
/// `iPhoneButtonProperties`).
///
/// Only what describes the product to userland is listed. Properties that
/// promise hardware the VM does not have — Bluetooth, baseband, NFC,
/// exclaves, `has-*`, the graphics feature set, `framebuffer-identifier`,
/// display calibration — stay as vphone600 has them.
static let iPhoneProductProperties = [
// What Settings and MobileGestalt name the device.
"product-name", "product-description",
// Siri and dictation.
"assistant", "siri-gesture", "dictation", "offline-dictation", "builtin-mics",
// Buttons SpringBoard and Settings lay out against.
"side-button-location", "volume-up-button-location", "volume-down-button-location",
// Display and chrome.
"artwork-scale-factor", "chrome-identifier", "compatible-device-fallback",
"display-corner-radius", "display-mirroring", "oled-display", "thin-bezel", "large-format-phone",
// UI and feature switches.
"ui-pip", "ui-reachability", "ui-background-quality", "ui-weather-quality",
"hme-in-arkit", "carplay-2", "location-reminders", "watch-companion",
]
/// `/product` properties vphone600 lacks altogether, added from the board:
/// the Action Button's and Camera Control's geometry, and Camera Control
/// itself, without which Settings has no Camera Control page.
static let iPhoneAddedProductProperties = [
"ringer-button-location", "camera-button-location", "supports-camera-button",
]
/// The `/product` property that tells vphoned the board has an Always On
/// display. MobileGestalt reads nothing by this name.
///
/// MobileGestalt answers the Always On display from the board's
/// `/arm-io/disp0` `always-on-time`, and that one property answers three
/// questions yes: DeviceSupportsAlwaysOnDisplay, DeviceSupportsAlwaysOnTime
/// and DeviceSupportsAlwaysOnDisplayFlipbook. The flipbook is the panel
/// controller (DCP) replaying prerendered frames; CoreBrightness asks the
/// DCP for it in backboardd, which this VM's paravirtual panel cannot
/// answer, so a guest whose tree carries `always-on-time` loses backboardd
/// at every boot and launchd restarts it into the device recovery
/// environment (iPhone18,1 27.0.1). Without the flipbook, BacklightServices
/// renders the always-on Lock Screen itself (BLSHPseudoFlipbook), which
/// works here; so the tree only marks the board, and vphoned answers the
/// first two questions yes in the MobileGestalt cache
/// (`GuestMobileGestaltCache.presentAlwaysOnDisplayOnStartup`).
static let alwaysOnDisplayMarker = "vphone-always-on-display"
/// `/buttons` properties taken from the board when they are placeholders.
/// `function-button_ringeren` is what MobileGestalt reads for the Action
/// Button. vphone600's `/buttons` has no `compatible`, so no button driver
/// binds to the node and the board's function reference is never followed.
static let iPhoneButtonProperties = ["function-button_ringeren"]
/// One property `presentPhoneProduct` set: where, and its value before
/// (nil when it was added).
struct PhoneProductChange {
let path: String
let before: Data?
let after: Data
}
/// Give an iPhone guest's `/product` and `/buttons` the board's values for
/// `iPhoneProductProperties`, `iPhoneAddedProductProperties` and
/// `iPhoneButtonProperties`, and `alwaysOnDisplayMarker` when the board has
/// an Always On display.
///
/// A listed property is copied only when the guest's is a placeholder (or,
/// for the added ones, missing) and the board's is a real value, so a tree
/// that already has them, or a board that lacks one, is left as it is.
/// Returns what changed, empty when nothing did.
static func presentPhoneProduct(in root: DTNode, from source: DTNode) -> [PhoneProductChange] {
var changes: [PhoneProductChange] = []
func fill(_ names: [String], node: String, add: Bool) {
guard
let target = optionalChild(of: root, named: node),
let board = optionalChild(of: source, named: node)
else { return }
for name in names {
guard let value = board.properties.first(where: { $0.name == name }),
value.flags & placeholderFlag == 0
else { continue }
if let existing = target.properties.first(where: { $0.name == name }) {
guard existing.flags & placeholderFlag != 0 else { continue }
changes.append(PhoneProductChange(path: "\(node)/\(name)", before: existing.value, after: value.value))
existing.flags = 0
existing.value = value.value
} else if add {
target.properties.append(DTProperty(name: name, flags: 0, value: value.value, valueOffset: 0))
changes.append(PhoneProductChange(path: "\(node)/\(name)", before: nil, after: value.value))
}
}
}
fill(iPhoneProductProperties, node: "product", add: false)
fill(iPhoneAddedProductProperties, node: "product", add: true)
fill(iPhoneButtonProperties, node: "buttons", add: false)
if let display = optionalChild(of: source, named: "arm-io").flatMap({ optionalChild(of: $0, named: "disp0") }),
display.properties.contains(where: { $0.name == "always-on-time" && $0.flags & placeholderFlag == 0 }),
let product = optionalChild(of: root, named: "product"),
!product.properties.contains(where: { $0.name == alwaysOnDisplayMarker })
{
let value = Data([1, 0, 0, 0])
product.properties.append(DTProperty(name: alwaysOnDisplayMarker, flags: 0, value: value, valueOffset: 0))
changes.append(PhoneProductChange(path: "product/\(alwaysOnDisplayMarker)", before: nil, after: value))
}
return changes
}
/// The flat encoding of one node and its children, for the patch record.
private static func serialize(_ node: DTNode) -> Data {
var out = Data()
func append(_ value: UInt32) {
withUnsafeBytes(of: value.littleEndian) { out.append(contentsOf: $0) }
}
append(UInt32(node.properties.count))
append(UInt32(node.children.count))
for property in node.properties {
var name = Data(property.name.utf8.prefix(31))
name.append(contentsOf: [UInt8](repeating: 0, count: 32 - name.count))
out.append(name)
withUnsafeBytes(of: UInt16(property.length).littleEndian) { out.append(contentsOf: $0) }
withUnsafeBytes(of: property.flags.littleEndian) { out.append(contentsOf: $0) }
out.append(property.value)
out.append(contentsOf: [UInt8](repeating: 0, count: (4 - property.length % 4) % 4))
}
for child in node.children {
out.append(serialize(child))
}
return out
}
// MARK: - Application
/// Applies `guestEdits(from:)` to the parsed tree and records each change.
func applyGuestEdits(root: DTNode) throws {
guard let sourceTree else {
throw PatcherError.fileNotFound(
"DeviceTree: \(device.productType)'s own device tree (\(device.boardDeviceTreePath)) is needed to present it",
)
}
let source = try parsePayload(sourceTree)
if gateAllows(Self.iPadAudioPatch), let change = Self.presentBoardAudio(in: root, from: source) {
patches.append(PatchRecord(
patchID: Self.iPadAudioPatch,
component: component,
fileOffset: 0,
virtualAddress: nil,
originalBytes: change.before,
patchedBytes: change.after,
description: "Set /device-tree/product/audio as on \(device.productType)",
))
if verbose {
print(" =node : /product/audio as on \(device.productType) (\(change.after.count)B) [\(Self.iPadAudioPatch)]")
}
}
for edit in try Self.guestEdits(from: source) {
guard gateAllows(edit.patchID) else { continue }
let node = try resolveNode(root, path: edit.nodePath)
let index = node.properties.firstIndex { $0.name == edit.property }
let before = index.map { node.properties[$0].value } ?? Data()
let after: Data?
switch edit.action {
case .remove:
guard let index else { continue }
node.properties.remove(at: index)
after = nil
case let .set(value):
if let index {
let property = node.properties[index]
guard property.value != value || property.flags != 0 else { continue }
property.value = value
property.flags = 0
} else {
node.properties.append(DTProperty(name: edit.property, flags: 0, value: value, valueOffset: 0))
}
after = value
}
let path = (edit.nodePath + [edit.property]).joined(separator: "/")
let description = switch edit.action {
case .remove: "Remove \(path) (not on \(device.productType))"
case .set: "Set \(path) as on \(device.productType)"
}
patches.append(PatchRecord(
patchID: edit.patchID,
component: component,
fileOffset: 0,
virtualAddress: nil,
originalBytes: before,
patchedBytes: after ?? Data(),
description: description,
))
if verbose {
print(" \(after == nil ? "-prop " : "=prop "): /\(path) \(before.hex) → \((after ?? Data()).hex) [\(edit.patchID)]")
}
}
}
/// Applies `removeHaptics(from:)` to the parsed tree, whichever guest and
/// role it is for, and records the removal.
func applyHapticsRemoval(root: DTNode) {
guard gateAllows(Self.hapticsPatch), let removed = Self.removeHaptics(from: root) else { return }
patches.append(PatchRecord(
patchID: Self.hapticsPatch,
component: component,
fileOffset: 0,
virtualAddress: nil,
originalBytes: removed,
patchedBytes: Data(),
description: "Remove /device-tree/product/haptics, which no VM has the hardware for",
))
if verbose {
print(" -node : /product/haptics, no actuator or haptic server on a VM (\(removed.count)B) [\(Self.hapticsPatch)]")
}
}
// MARK: - Notched iPhone
static let islandNotchLocationPatch = "devicetree-cfw-island_notch_location"
/// Removes `/product/island-notch-location` for a guest whose userland has
/// no Dynamic Island layout (`VPhoneGuestDevice.notchedArtworkSubtype`),
/// under the patch that otherwise sets it.
func removeIslandNotchLocation(root: DTNode) throws {
guard gateAllows(Self.islandNotchLocationPatch),
let product = Self.optionalChild(of: root, named: "product"),
let index = product.properties.firstIndex(where: { $0.name == "island-notch-location" })
else { return }
let removed = product.properties.remove(at: index)
patches.append(PatchRecord(
patchID: Self.islandNotchLocationPatch,
component: component,
fileOffset: removed.valueOffset,
virtualAddress: nil,
originalBytes: removed.value,
patchedBytes: Data(),
description: "Remove the island notch location: \(device.productName) has no Dynamic Island",
))
if verbose {
print(" -prop : /product/island-notch-location, no Dynamic Island on \(device.productName) [\(Self.islandNotchLocationPatch)]")
}
}
// MARK: - Watch Companion
/// Give an iPhone guest's `/product/watch-companion` the value 1, adding it
/// where the board copy removed it. Returns its value before (nil when it
/// was absent), or nil changes when it already is a plain 1.
///
/// vphone600's is `syscfg/waco`, which the VM's syscfg does not have, so
/// iBoot drops the property and MobileGestalt answers that the phone pairs
/// with no watch: the Watch app has no icon, and NanoRegistry's clients
/// never see the watch nanoregistryd discovers.
static func presentWatchCompanion(in root: DTNode) -> (before: Data?, after: Data)? {
guard let product = optionalChild(of: root, named: "product") else { return nil }
let value = Data([1, 0, 0, 0])
if let existing = product.properties.first(where: { $0.name == "watch-companion" }) {
guard existing.flags & placeholderFlag != 0 || existing.value != value else { return nil }
let before = existing.value
existing.flags = 0
existing.value = value
return (before, value)
}
product.properties.append(DTProperty(name: "watch-companion", flags: 0, value: value, valueOffset: 0))
return (nil, value)
}
/// Applies `presentWatchCompanion(in:)` to an iPhone guest's tree.
func applyWatchCompanion(root: DTNode) {
guard device.family == .iPhone, gateAllows(Self.watchCompanionPatch),
let change = Self.presentWatchCompanion(in: root)
else { return }
patches.append(PatchRecord(
patchID: Self.watchCompanionPatch,
component: component,
fileOffset: 0,
virtualAddress: nil,
originalBytes: change.before ?? Data(),
patchedBytes: change.after,
description: "Set /device-tree/product/watch-companion = 1",
))
if verbose {
print(" =prop : /product/watch-companion = 1, the VM syscfg has no waco [\(Self.watchCompanionPatch)]")
}
}
/// Applies `removeMicrophoneArrayClaims(from:)` to the parsed tree,
/// whichever guest and role it is for, and records each removal.
func applyMicrophoneArrayRemoval(root: DTNode) {
guard gateAllows(Self.microphoneArrayPatch) else { return }
for (name, value) in Self.removeMicrophoneArrayClaims(from: root) {
patches.append(PatchRecord(
patchID: Self.microphoneArrayPatch,
component: component,
fileOffset: 0,
virtualAddress: nil,
originalBytes: value,
patchedBytes: Data(),
description: "Remove /device-tree/product/audio/\(name), which needs a microphone array no VM has",
))
if verbose {
print(" -prop : /product/audio/\(name) \(value.hex) → absent [\(Self.microphoneArrayPatch)]")
}
}
}
}