Run a virtual iPhone on an Apple Silicon Mac.
Swift
Give an iPad guest its own screen scale
Jacky0cd93133134b
diff --git a/Documents/Guides/ipados.md b/Documents/Guides/ipados.mdindex b8d5a8da..c4d9d1a6 100644--- a/Documents/Guides/ipados.md+++ b/Documents/Guides/ipados.md@@ -66,6 +66,11 @@ Only `fw prepare` and `fw patch` differ for an iPad; DFU, `restore` andThe virtual hardware keeps its vphone600 description: GPU feature set,framebuffer, memory class and boot flags.+- **LLB** gets one more patch on an iPad guest, `llb-cfw-display_scale`. LLB+ fills `/chosen/display-scale` from the paravirtual display's boot video+ word, which always says 3x; MobileGestalt turns that property into the+ screen scale, so an iPad would get a 496x755-point canvas. The patch makes+ LLB write the iPad's own scale (2x, 744x1133 points).- **`cfw install`** leaves the installed device tree alone. The iPhone17,3post-restore identity rewrite (`preboot-exp-devicetree_identity`) is skippedon an iPad guest.diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.mdindex 9fbd7173..413a1037 100644--- a/Research/0_binary_patch_comparison.md+++ b/Research/0_binary_patch_comparison.md@@ -9,7 +9,7 @@> identifier is the record identifier the patcher already emits, or the common> prefix when one patch writes several sites — so `jb.kcall10` is one selectable> patch covering its four records, and `sandbox_ext` covers every-> `sandbox_ext_<index>`. 120 patches are declared in total. `vphone-cli fw patches`+> `sandbox_ext_<index>`. 121 patches are declared in total. `vphone-cli fw patches`> prints them; `--json` is what the Launchpad patch editor reads.>> Two presets ship, prewritten, in@@ -39,6 +39,23 @@> GPU, framebuffer and boot properties stay vphone600's. `cfw install` skips> `preboot-exp-devicetree_identity` on an iPad guest. Values were copied from> `DeviceTree.j410ap.im4p` in `iPad16,1,iPad16,2_26.6.2_23G90_Restore.ipsw`.+>+> A fifth, `llb-cfw-display_scale`, fixes the screen scale. UIScreen's scale is+> MobileGestalt's `main-screen-scale`, and libMobileGestalt — the only reader+> of the property in the 26.6.2 userland — takes it from+> `IODeviceTree:/chosen/display-scale`. LLB (single-stage boot) writes that+> property as `((v_depth >> 16) & 0xff) + 1` from the boot video word, which+> the paravirtual display always reports as 3x, whatever the panel's size or+> the `pixelsPerInch` VZ is given (264 and 326 were tried). At 3x the iPad+> mini's 1488x2266 panel is 496x755 points and iPadOS lays its home screen+> out over itself. The patch, anchored on the ADRP+ADD of the `display-scale`+> literal and the following `ubfx wN, wM, #16, #8 ; add wN, wN, #1 ;+> str wN, [x0]`, replaces the `add` with `mov wN, #<artwork scale>`+> (`ARM64Encoder.encodeMovzW`). Found at `LLB.vresearch101.RELEASE` 0xB9CC in+> cloudOS 26.4 (23E5207q). Editing the MobileGestalt cache's cached screen+> struct (`oBbtJ8x+s1q0OkaiocPuog`, `{1488, 2266, 326, 3.0f}`) does not change+> the live scale. Emitted only for an iPad guest.+>> See `Documents/Guides/ipados.md`.>> **Only the camera remains of EXP by default (2026-09-28).** `standard` is now thediff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/IBoot/BasePatches/IBootPatchDisplayScale.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/IBoot/BasePatches/IBootPatchDisplayScale.swiftnew file mode 100644index 00000000..d3f08a2d--- /dev/null+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/IBoot/BasePatches/IBootPatchDisplayScale.swift@@ -0,0 +1,144 @@+// IBootPatchDisplayScale.swift — LLB `/chosen/display-scale` for an iPad guest.+//+// Part of IBootPatcher; see IBootPatcher.swift for the patch schedule by mode.+//+// The guest's UIScreen scale is MobileGestalt's `main-screen-scale`, which+// libMobileGestalt reads from `IODeviceTree:/chosen/display-scale` — the only+// reader of that property in the iOS 26.6.2 userland. LLB (the single-stage+// boot path, so it is LLB and not iBoot that prepares the kernel's tree) fills+// it from the boot video depth word:+//+// adrp x8, "display-scale"@PAGE ; add x8, x8, "display-scale"@PAGEOFF+// ... ; look the property up in /chosen+// ubfx w8, w20, #16, #8 ; v_depth scale byte+// add w8, w8, #1 ; stored as scale - 1+// str w8, [x0] ; property value+//+// For the paravirtual display that byte always says 3, whatever the panel's+// size or density, which is right for the phone vphone600 is and wrong for an+// iPad: an iPad mini's 1488x2266 panel at 3x is 496x755 points, a phone-sized+// canvas the iPad layouts overflow. The patch replaces the `add` with+// `mov w8, #<scale>`, so the property carries the guest device's own artwork+// scale and the screen is 744x1133 points, as on the real device. The boot+// video word itself, which only the kernel's boot console reads, is left alone.++import Foundation+import VPhonePatchKit++extension IBootPatcher {+ // MARK: - Display Scale (LLB, iPad guests only)++ static let displayScaleProperty = "display-scale"++ func patchDisplayScale(_ scale: UInt16) {+ let id = "\(component)-cfw-display_scale"+ guard let stringOffset = findCString(Self.displayScaleProperty) else {+ if verbose {+ print(" [-] display-scale: property name not found")+ }+ return+ }++ for xref in findADRPAddReferences(to: stringOffset) {+ // The value the property gets is computed a few lookups after its name+ // is loaded; 48 instructions is past the store for every observed build.+ var offset = xref + 8+ let limit = min(xref + 8 + 48 * 4, buffer.original.count - 12)+ while offset <= limit {+ defer { offset += 4 }+ guard let extract = disasm.disassembleOne(in: buffer.original, at: offset),+ let increment = disasm.disassembleOne(in: buffer.original, at: offset + 4),+ let store = disasm.disassembleOne(in: buffer.original, at: offset + 8),+ let register = scaleByteExtract(extract),+ isIncrementByOne(increment, of: register),+ isStore(store, of: register),+ let number = generalRegisterNumber(register),+ let replacement = ARM64Encoder.encodeMovzW(rd: UInt32(number), imm16: scale)+ else { continue }++ emit(+ offset + 4,+ replacement,+ id: id,+ description: "display-scale: \(scale)x instead of the boot video's",+ )+ return+ }+ }++ if verbose {+ print(" [-] display-scale: value computation not found")+ }+ }++ // MARK: - Matching++ /// `ubfx wN, wM, #16, #8`: the boot video depth word's scale byte. Returns wN.+ private func scaleByteExtract(_ instruction: ARM64Instruction) -> ARM64Register? {+ guard instruction.mnemonic == "ubfx",+ let operands = instruction.detail?.operands,+ operands.count == 4,+ operands[0].type == .register,+ operands[1].type == .register,+ operands[2].type == .immediate, operands[2].imm == 16,+ operands[3].type == .immediate, operands[3].imm == 8+ else { return nil }+ return operands[0].reg+ }++ /// `add wN, wN, #1`.+ private func isIncrementByOne(_ instruction: ARM64Instruction, of register: ARM64Register) -> Bool {+ guard instruction.mnemonic == "add",+ let operands = instruction.detail?.operands,+ operands.count == 3,+ operands[0].type == .register, operands[0].reg == register,+ operands[1].type == .register, operands[1].reg == register,+ operands[2].type == .immediate, operands[2].imm == 1+ else { return false }+ return true+ }++ /// `str wN, [xK]` — the property value, written in place.+ private func isStore(_ instruction: ARM64Instruction, of register: ARM64Register) -> Bool {+ guard instruction.mnemonic == "str",+ let operands = instruction.detail?.operands,+ operands.count == 2,+ operands[0].type == .register, operands[0].reg == register,+ operands[1].type == .memory, operands[1].mem.disp == 0+ else { return false }+ return true+ }++ private func generalRegisterNumber(_ register: ARM64Register) -> Int? {+ (0 ... 30).first { ARM64Register.w($0) == register }+ }++ // MARK: - References++ /// Offset of a NUL-terminated string that starts on a string boundary.+ private func findCString(_ text: String) -> Int? {+ let needle = Data(text.utf8) + Data([0])+ return buffer.findAll(needle).first { $0 == 0 || buffer.original[$0 - 1] == 0 }+ }++ /// ADRP+ADD pairs that materialise `target` (raw binary, base address 0:+ /// the page arithmetic is the same at any page-aligned load address).+ private func findADRPAddReferences(to target: Int) -> [Int] {+ let data = buffer.original+ var references: [Int] = []+ var offset = 0+ while offset + 8 <= data.count {+ defer { offset += 4 }+ guard let adrp = disasm.disassembleOne(in: data, at: offset), adrp.mnemonic == "adrp",+ let add = disasm.disassembleOne(in: data, at: offset + 4), add.mnemonic == "add",+ let page = adrp.detail?.operands, page.count >= 2,+ let low = add.detail?.operands, low.count >= 3,+ page[0].reg == low[1].reg,+ page[1].type == .immediate, low[2].type == .immediate,+ page[1].imm + low[2].imm == Int64(target)+ else { continue }+ references.append(offset)+ }+ return references+ }+}diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/IBoot/IBootPatcher.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/IBoot/IBootPatcher.swiftindex d0a6863f..b267a324 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/IBoot/IBootPatcher.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/IBoot/IBootPatcher.swift@@ -7,6 +7,7 @@// ibss — serial labels + image4 callback// ibec — serial labels + image4 callback + boot-args + bootx precondition (if present)// llb — serial labels + image4 callback + boot-args + rootfs bypass (5 patches) + panic bypass+// + display scale (iPad guests only)//// Each patch method is defined as an extension in its own file under IBoot/Patches/.@@ -48,6 +49,11 @@ public class IBootPatcher: BufferedPatcher {/// by default, so 26.x bases keep the stock boot-args.public var extraBootArgs: String = ""+ /// The `/chosen/display-scale` LLB writes, when the guest is not the phone+ /// the boot video describes. Nil leaves LLB's own value. See+ /// IBootPatchDisplayScale.swift.+ public var displayScale: UInt16?+let buffer: BinaryBufferlet mode: Modelet disasm = ARM64Disassembler()@@ -80,6 +86,9 @@ public class IBootPatcher: BufferedPatcher {patchBootArgs()patchRootfssBypass()patchPanicBypass()+ if let displayScale {+ patchDisplayScale(displayScale)+ }}return patchesdiff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareBootChainPatchSet.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareBootChainPatchSet.swiftindex f97c942f..37b15598 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareBootChainPatchSet.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareBootChainPatchSet.swift@@ -118,6 +118,12 @@ public enum FirmwareBootChainPatchSet {target: .firmware(.llb),bootEssential: true,),+ VPhonePatchDeclaration(+ identifier: "llb-cfw-display_scale",+ title: "LLB display scale",+ summary: "Gives an iPad guest its own screen scale instead of the virtual phone's 3x.",+ target: .firmware(.llb),+ ),// MARK: TXMdiff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swiftindex 0733c811..e0a6c29d 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift@@ -48,6 +48,12 @@ extension FirmwarePipeline {let includeKernelCustomFirmware = includesSet(FirmwareKernelCustomFirmwarePatchSet.identifier)let includeDeviceTree = includesSet(FirmwareDeviceTreePatchSet.identifier)+ // An iPad guest boots a device tree of its own (7b) and needs LLB to give+ // it the iPad's display scale (4).+ let guestDevice = Self.readGuestDevice(restoreDir)+ let guestTreeURL = restoreDir.appending(path: FirmwareManifest.guestDeviceTreePath)+ let hasGuestTree = guestDevice.isPad && FileManager.default.fileExists(atPath: guestTreeURL.path)+/// Whether the plan turned a patch on. Without a plan, fall back to the/// release the patch is pinned to, which is the same answer the standard/// preset gives.@@ -162,6 +168,7 @@ extension FirmwarePipeline {patcherFactories: includeBootChain ? [{ data, verbose inlet p = IBootPatcher(data: data, mode: .llb, verbose: verbose)p.extraBootArgs = extraBootArgs+ p.displayScale = hasGuestTree ? UInt16(guestDevice.artworkScale) : nilp.gate = gatereturn p}] : [],@@ -237,9 +244,6 @@ extension FirmwarePipeline {// properties so the guest presents a consistent iPhone17,3 identity.// An iPad guest restores with this tree and boots its own copy (7b).let dtIncludeIdentity = variant == .jb || variant == .exp- let guestDevice = Self.readGuestDevice(restoreDir)- let guestTreeURL = restoreDir.appending(path: FirmwareManifest.guestDeviceTreePath)- let hasGuestTree = guestDevice.isPad && FileManager.default.fileExists(atPath: guestTreeURL.path)components.append(ComponentDescriptor(name: "DeviceTree",inRestoreDir: true,diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/IBootDisplayScaleTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/IBootDisplayScaleTests.swiftnew file mode 100644index 00000000..7f6c5b56--- /dev/null+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/IBootDisplayScaleTests.swift@@ -0,0 +1,50 @@+@testable import FirmwarePatcher+import Foundation+import Testing+import VPhonePatchKit++/// LLB's `/chosen/display-scale` store, on a fragment shaped like the+/// cloudOS 26.4 (23E5207q) `LLB.vresearch101.RELEASE` site at 0xB9C8.+@Suite("LLB display scale")+struct IBootDisplayScaleTests {+ /// Little-endian words, each checked against Capstone:+ ///+ /// 0x1000 adrp x8, #0x2000+ /// 0x1004 add x8, x8, #0x10 ; "display-scale" at 0x2010+ /// 0x1008 nop+ /// 0x100c ubfx w8, w20, #0x10, #8 ; the three words LLB has at 0xB9C8+ /// 0x1010 add w8, w8, #1+ /// 0x1014 str w8, [x0]+ static func image(storeIncrement: UInt32 = 0x1100_0508) -> Data {+ var data = Data(count: 0x3000)+ let words: [UInt32] = [0xB000_0008, 0x9100_4108, 0xD503_201F, 0x5310_5E88, storeIncrement, 0xB900_0008]+ for (index, word) in words.enumerated() {+ withUnsafeBytes(of: word.littleEndian) { data.replaceSubrange(0x1000 + index * 4 ..< 0x1004 + index * 4, with: $0) }+ }+ let name = Data("display-scale\0".utf8)+ data.replaceSubrange(0x2010 ..< 0x2010 + name.count, with: name)+ return data+ }++ @Test func `the increment becomes the guest's scale`() throws {+ let patcher = IBootPatcher(data: Self.image(), mode: .llb, verbose: false)+ patcher.patchDisplayScale(2)+ let record = try #require(patcher.patches.first)+ #expect(patcher.patches.count == 1)+ #expect(record.patchID == "llb-cfw-display_scale")+ #expect(record.fileOffset == 0x1010)+ #expect(record.patchedBytes == ARM64Encoder.encodeMovzW(rd: 8, imm16: 2))+ }++ @Test func `a different computation is left alone`() {+ // `add w8, w8, #2` is not the scale-minus-one encoding the patch knows.+ let patcher = IBootPatcher(data: Self.image(storeIncrement: 0x1100_0908), mode: .llb, verbose: false)+ patcher.patchDisplayScale(2)+ #expect(patcher.patches.isEmpty)+ }++ @Test func `the patch is declared`() {+ let declared = FirmwareBootChainPatchSet.manifest.patches.map(\.identifier)+ #expect(declared.contains("llb-cfw-display_scale"))+ }+}