Skip to content

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.md
index 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` and
The 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,3
post-restore identity rewrite (`preboot-exp-devicetree_identity`) is skipped
on an iPad guest.
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 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 the
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/IBoot/BasePatches/IBootPatchDisplayScale.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/IBoot/BasePatches/IBootPatchDisplayScale.swift
new file mode 100644
index 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.swift
index 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: BinaryBuffer
let mode: Mode
let disasm = ARM64Disassembler()
@@ -80,6 +86,9 @@ public class IBootPatcher: BufferedPatcher {
patchBootArgs()
patchRootfssBypass()
patchPanicBypass()
+ if let displayScale {
+ patchDisplayScale(displayScale)
+ }
}
return patches
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareBootChainPatchSet.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareBootChainPatchSet.swift
index 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: TXM
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift
index 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 in
let p = IBootPatcher(data: data, mode: .llb, verbose: verbose)
p.extraBootArgs = extraBootArgs
+ p.displayScale = hasGuestTree ? UInt16(guestDevice.artworkScale) : nil
p.gate = gate
return 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.swift
new file mode 100644
index 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"))
+ }
+}