Run a virtual iPhone on an Apple Silicon Mac.
Swift
// DeviceTreePatcher.swift — DeviceTree payload patcher.
//
// Historical note: derived from the legacy Python firmware patcher during the Swift migration.
//
// Strategy:
// 1. Parse the flat device tree binary into a node/property tree, and
// convert a research board tree into vphone600 (DeviceTreeResearchBoardConversion.swift).
// 2. Apply a fixed set of property patches (serial-number, home-button-type,
// artwork-device-subtype, island-notch-location).
// 3. Serialize the modified tree back to flat binary.
import Foundation
import Img4tool
import VPhoneCoreKit
import VPhonePatchKit
/// Patcher for DeviceTree payloads.
public final class DeviceTreePatcher: BufferedPatcher {
public let component = "devicetree"
public let verbose: Bool
/// Which patches the resolved preset turned on. Unrestricted by default.
public var gate: VPhonePatchGate = .unrestricted
/// Whether a research board tree is converted into vphone600 first. Off when
/// the preset leaves out `FirmwareResearchBoardPatchSet`, whose patch would
/// otherwise be declared by nothing and apply regardless.
public var convertsResearchBoard = true
/// Whether to apply the 8 identity-rewrite property patches (Tier 1b + 1c)
/// that flip device identity towards iPhone17,3 / D47AP. Enabled for
/// public JB and the historical internal EXP variant.
let includeIdentityPatches: Bool
/// The device whose OS the guest runs, and which of its trees this is.
/// An iPhone guest has one `.shared` tree; an iPad guest boots its
/// `.installed` tree and restores with a `.restore` one. See
/// DeviceTreeGuestDevicePatches.swift.
let device: VPhoneGuestDevice
let role: TreeRole
/// The guest device's own flat device tree payload, which an iPad's
/// installed tree takes its identity and `/product` answers from.
let sourceTree: Data?
let buffer: BinaryBuffer
var patches: [PatchRecord] = []
var rebuiltData: Data?
// MARK: - Device Tree Structures
/// A single property in a device tree node.
final class DTProperty {
var name: String
var length: Int {
value.count
}
var flags: UInt16
var value: Data
/// File offset of the property value within the flat binary.
let valueOffset: Int
init(name: String, flags: UInt16, value: Data, valueOffset: Int) {
self.name = name
self.flags = flags
self.value = value
self.valueOffset = valueOffset
}
}
/// A node in the device tree containing properties and child nodes.
final class DTNode {
var properties: [DTProperty] = []
var children: [DTNode] = []
}
// MARK: - Init
public init(
data: Data,
verbose: Bool = true,
includeIdentityPatches: Bool = false,
device: VPhoneGuestDevice = .default,
role: TreeRole = .shared,
sourceTree: Data? = nil,
) {
buffer = BinaryBuffer(data)
self.verbose = verbose
self.includeIdentityPatches = includeIdentityPatches
self.device = device
self.role = role
self.sourceTree = sourceTree
}
// MARK: - Patcher
public func findAll() throws -> [PatchRecord] {
patches = []
rebuiltData = nil
let root = try parsePayload(buffer.data)
try applyPatches(root: root)
rebuiltData = serializeNode(root)
return patches
}
@discardableResult
public func apply() throws -> Int {
if patches.isEmpty, rebuiltData == nil {
let _ = try findAll()
}
// `findAll()` always ends by rebuilding the payload, and node additions are
// emitted with `fileOffset: 0`, so the rebuilt payload is the only thing that
// can land on disk.
if let rebuiltData {
buffer.data = rebuiltData
}
if verbose, !patches.isEmpty {
print("\n [\(patches.count) DeviceTree patch(es) applied]")
}
return patches.count
}
public var patchedData: Data {
rebuiltData ?? buffer.data
}
/// Extract the donor board's MiniDisplay geometry without grafting its
/// physical dock-channel hardware into the VM's virtual device tree.
/// Both the retained IM4P and an already-decoded flat payload are accepted.
public static func homePodDisplayProperties(from data: Data) throws -> [String: Data] {
let payload: Data
if let im4p = try? IM4P(data) {
guard im4p.fourcc == "dtre", !im4p.isEncrypted else {
throw PatcherError.invalidFormat("HomePod display: expected an unencrypted dtre IM4P")
}
payload = try im4p.payload()
} else {
payload = data
}
let parser = DeviceTreePatcher(data: payload, verbose: false)
let root = try parser.parsePayload(payload)
let display = try parser.resolveNode(root, path: [
"device-tree", "arm-io", "dockchannel-rtp", "rtp-transport", "display",
])
let names = ["MDXCoords", "MDYCoords", "MDRingCoords", "MDBitDepth", "MDHWVersion"]
var properties: [String: Data] = [:]
for name in names {
let matches = display.properties.filter { $0.name == name }
guard matches.count == 1, let property = matches.first, property.flags == 0 else {
throw PatcherError.invalidFormat("HomePod display: missing, duplicate or unresolved \(name)")
}
properties[name] = property.value
}
let geometry = try VPhoneHomePodDisplayGeometry(deviceTreeProperties: properties)
guard geometry.bitDepth == 12, geometry.hardwareVersion == 3 else {
throw PatcherError.invalidFormat("HomePod display: unsupported MiniDisplay bit depth or hardware version")
}
return properties
}
// MARK: - Parsing
/// Align a value up to the next 4-byte boundary.
private static func align4(_ n: Int) -> Int {
(n + 3) & ~3
}
/// Decode a null-terminated C string from raw bytes.
private static func decodeCString(_ data: Data) -> String {
if let nullIndex = data.firstIndex(of: 0) {
let slice = data[data.startIndex ..< nullIndex]
return String(bytes: slice, encoding: .utf8) ?? ""
}
return String(bytes: data, encoding: .utf8) ?? ""
}
/// Parse a device tree node from the flat binary at the given offset.
/// Returns the parsed node and the offset past the end of the node.
private func parseNode(_ blob: Data, offset: Int) throws -> (DTNode, Int) {
guard offset + 8 <= blob.count else {
throw PatcherError.invalidFormat("DeviceTree: truncated node header at offset \(offset)")
}
let nProps = blob.loadLE(UInt32.self, at: offset)
let nChildren = blob.loadLE(UInt32.self, at: offset + 4)
var pos = offset + 8
let node = DTNode()
for _ in 0 ..< nProps {
guard pos + 36 <= blob.count else {
throw PatcherError.invalidFormat("DeviceTree: truncated property header at offset \(pos)")
}
let nameData = blob[blob.startIndex.advanced(by: pos) ..< blob.startIndex.advanced(by: pos + 32)]
let name = Self.decodeCString(Data(nameData))
let length = Int(blob.loadLE(UInt16.self, at: pos + 32))
let flags = blob.loadLE(UInt16.self, at: pos + 34)
pos += 36
guard pos + length <= blob.count else {
throw PatcherError.invalidFormat("DeviceTree: truncated property value '\(name)' at offset \(pos)")
}
let value = Data(blob[blob.startIndex.advanced(by: pos) ..< blob.startIndex.advanced(by: pos + length)])
let valueOffset = pos
pos += Self.align4(length)
node.properties.append(DTProperty(
name: name,
flags: flags,
value: value,
valueOffset: valueOffset,
))
}
for _ in 0 ..< nChildren {
let (child, nextPos) = try parseNode(blob, offset: pos)
node.children.append(child)
pos = nextPos
}
return (node, pos)
}
/// Parse the entire device tree payload.
func parsePayload(_ blob: Data) throws -> DTNode {
let (root, end) = try parseNode(blob, offset: 0)
guard end == blob.count else {
throw PatcherError.invalidFormat(
"DeviceTree: unexpected trailing bytes (\(blob.count - end) extra)",
)
}
return root
}
private func serializeNode(_ node: DTNode) -> Data {
var out = Data()
out.append(contentsOf: withUnsafeBytes(of: UInt32(node.properties.count).littleEndian) { Data($0) })
out.append(contentsOf: withUnsafeBytes(of: UInt32(node.children.count).littleEndian) { Data($0) })
for prop in node.properties {
var name = Data(prop.name.utf8)
if name.count >= 32 {
name = Data(name.prefix(31))
}
name.append(contentsOf: [UInt8](repeating: 0, count: 32 - name.count))
out.append(name)
out.append(contentsOf: withUnsafeBytes(of: UInt16(prop.length).littleEndian) { Data($0) })
out.append(contentsOf: withUnsafeBytes(of: prop.flags.littleEndian) { Data($0) })
out.append(prop.value)
let pad = Self.align4(prop.length) - prop.length
if pad > 0 {
out.append(Data(repeating: 0, count: pad))
}
}
for child in node.children {
out.append(serializeNode(child))
}
return out
}
// MARK: - Node Navigation
/// Get the "name" property value from a node.
private func nodeName(_ node: DTNode) -> String {
for prop in node.properties {
if prop.name == "name" {
return Self.decodeCString(prop.value)
}
}
return ""
}
/// Find a direct child node by name.
private func findChild(_ node: DTNode, name: String) throws -> DTNode {
for child in node.children {
if nodeName(child) == name {
return child
}
}
throw PatcherError.patchSiteNotFound("DeviceTree: missing child node '\(name)'")
}
/// Resolve a node path like ["device-tree", "buttons"] from the root.
func resolveNode(_ root: DTNode, path: [String]) throws -> DTNode {
guard !path.isEmpty, path[0] == "device-tree" else {
throw PatcherError.patchSiteNotFound("DeviceTree: invalid node path \(path)")
}
var node = root
for name in path.dropFirst() {
node = try findChild(node, name: name)
}
return node
}
/// Find a property by name within a node.
private func findProperty(_ node: DTNode, name: String) throws -> DTProperty {
for prop in node.properties {
if prop.name == name {
return prop
}
}
throw PatcherError.patchSiteNotFound("DeviceTree: missing property '\(name)'")
}
// MARK: - Value Encoding
/// Encode a string value with null termination, padded/truncated to a fixed length.
private static func encodeFixedString(_ text: String, length: Int) -> Data {
var raw = Data(text.utf8)
raw.append(0) // null terminator
if raw.count > length {
return Data(raw.prefix(length))
}
raw.append(contentsOf: [UInt8](repeating: 0, count: length - raw.count))
return raw
}
/// Encode raw bytes for a property whose layout the caller has prepared
/// (typically a multi-string NUL-delimited blob like `compatible`).
/// Truncates if longer than the slot, pads with NULs if shorter.
private static func encodeFixedBytes(_ data: Data, length: Int) -> Data {
if data.count > length {
return Data(data.prefix(length))
}
var out = Data(data)
out.append(contentsOf: [UInt8](repeating: 0, count: length - out.count))
return out
}
/// Encode an integer value as little-endian bytes.
private static func encodeInteger(_ value: UInt64, length: Int) throws -> Data {
var data = Data(count: length)
switch length {
case 1:
data[0] = UInt8(value & 0xFF)
case 2:
let v = UInt16(value & 0xFFFF)
data.withUnsafeMutableBytes { $0.storeBytes(of: v.littleEndian, as: UInt16.self) }
case 4:
let v = UInt32(value & 0xFFFF_FFFF)
data.withUnsafeMutableBytes { $0.storeBytes(of: v.littleEndian, as: UInt32.self) }
case 8:
data.withUnsafeMutableBytes { $0.storeBytes(of: value.littleEndian, as: UInt64.self) }
default:
throw PatcherError.invalidFormat("DeviceTree: unsupported integer length \(length)")
}
return data
}
// MARK: - Patch Application
/// Apply all property patches and record each change.
///
/// Always runs `basePropertyPatches`. Additionally runs
/// `identityPropertyPatches` + `experimentalNodeAdditions` when
/// `includeIdentityPatches` is true (the `.exp` firmware variant) —
/// other variants leave the device's identity properties untouched.
/// `/product/haptics` is removed from every tree, whatever the variant.
private func applyPatches(root: DTNode) throws {
// Before everything else, whatever the selection: every patch below is
// written against vphone600 paths and values.
try applyResearchBoardConversion(root: root)
var patchesToApply = Self.basePropertyPatches
if includeIdentityPatches {
patchesToApply.append(contentsOf: Self.identityPropertyPatches)
}
// A board-presenting guest's installed tree takes its artwork, notch and
// camera geometry from the board edits, and none of the iPhone17,3
// identity.
let presentsGuest = device.presentsBoard && role == .installed
if presentsGuest {
patchesToApply.removeAll { !Self.deviceNeutralPatches.contains($0.patchID) }
}
// An XS-family userland has its own artwork and no Dynamic Island: the
// artwork patch writes its subtype, and the island patch removes the
// property instead of setting it.
if let subtype = device.notchedArtworkSubtype {
patchesToApply = patchesToApply.compactMap { patch in
switch patch.patchID {
case Self.islandNotchLocationPatch:
return nil
case "devicetree-cfw-artwork_device_subtype":
return PropertyPatch(
nodePath: patch.nodePath, property: patch.property, length: patch.length, flags: patch.flags,
value: .integer(UInt64(subtype)), patchID: patch.patchID,
description: "Set artwork device subtype to \(subtype) (\(device.productName))",
)
default:
return patch
}
}
try removeIslandNotchLocation(root: root)
}
for patch in patchesToApply {
// Before the property is rewritten, not after: the tree is serialised
// from these nodes, so a skipped record with a mutated node would
// still change the output.
guard gateAllows(patch.patchID) else { continue }
let node = try resolveNode(root, path: patch.nodePath)
let prop = try findProperty(node, name: patch.property)
let originalBytes = Data(prop.value.prefix(patch.length))
let newValue: Data = switch patch.value {
case let .string(s):
Self.encodeFixedString(s, length: patch.length)
case let .integer(v):
try Self.encodeInteger(v, length: patch.length)
case let .bytes(d):
Self.encodeFixedBytes(d, length: patch.length)
}
prop.flags = patch.flags
prop.value = newValue
let record = PatchRecord(
patchID: patch.patchID,
component: component,
fileOffset: prop.valueOffset,
virtualAddress: nil,
originalBytes: originalBytes,
patchedBytes: newValue,
description: patch.description,
)
patches.append(record)
if verbose {
print(String(
format: " 0x%06X: %@ → %@ [%@]",
prop.valueOffset,
originalBytes.hex,
newValue.hex,
patch.patchID,
))
}
}
if includeIdentityPatches {
for nodeAdd in Self.experimentalNodeAdditions {
try applyNodeAddition(root: root, patch: nodeAdd)
}
}
if presentsGuest {
try applyGuestEdits(root: root)
}
// After the board edits, which remove a placeholder the board has too.
applyWatchCompanion(root: root)
// Every guest, every tree: no VM has the haptics the node promises.
applyHapticsRemoval(root: root)
// Nor the microphone array its audio node answers for.
applyMicrophoneArrayRemoval(root: root)
}
/// Property patches that describe the virtual board rather than a phone,
/// and so apply to an iPad's installed tree as well.
static let deviceNeutralPatches: Set<String> = [
"devicetree-cfw-serial_number",
"devicetree-cfw-home_button_type",
]
/// Apply a single `AddChildNodePatch`: construct the new `DTNode`,
/// fill its `name` + caller-supplied properties, attach to the
/// parent's `children`, and record a `PatchRecord` for the change.
///
/// Skips if a child with the same name already exists under the
/// parent — keeps the patch idempotent so re-runs against an
/// already-patched DT don't double-add.
private func applyNodeAddition(root: DTNode, patch: AddChildNodePatch) throws {
guard gateAllows(patch.patchID) else { return }
let parent = try resolveNode(root, path: patch.parentPath)
for existing in parent.children {
if nodeName(existing) == patch.nodeName {
if verbose {
print(" - : /\(patch.parentPath.joined(separator: "/"))/\(patch.nodeName) already present, skipping [\(patch.patchID)]")
}
return
}
}
let newNode = DTNode()
// The `name` property is mandatory and matches the conventional
// shape of every other DT node — fixed length = strlen(name)+1.
let nameValue = Self.encodeFixedString(patch.nodeName, length: patch.nodeName.utf8.count + 1)
newNode.properties.append(DTProperty(
name: "name",
flags: 0,
value: nameValue,
valueOffset: 0,
))
for spec in patch.properties {
let value: Data = switch spec.value {
case let .string(s):
Self.encodeFixedString(s, length: spec.length)
case let .integer(v):
try Self.encodeInteger(v, length: spec.length)
case let .bytes(d):
Self.encodeFixedBytes(d, length: spec.length)
}
newNode.properties.append(DTProperty(
name: spec.name,
flags: spec.flags,
value: value,
valueOffset: 0,
))
}
parent.children.append(newNode)
// Serialize the new node so the patch record carries the bytes
// we conceptually added. fileOffset = 0 because the rebuilt
// payload is what actually lands on disk (apply() prefers
// `rebuiltData` over per-record byte writes).
let serialized = serializeNode(newNode)
patches.append(PatchRecord(
patchID: patch.patchID,
component: component,
fileOffset: 0,
virtualAddress: nil,
originalBytes: Data(),
patchedBytes: serialized,
description: patch.description,
))
if verbose {
print(" +node : /\(patch.parentPath.joined(separator: "/"))/\(patch.nodeName) (\(newNode.properties.count) props, \(serialized.count)B) [\(patch.patchID)]")
}
}
}