Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Turn ProMotion on in the standard preset

Jacky492a4f612cd0
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 984b5142..b64a6548 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -570,7 +570,7 @@
| JB-27 | B | `patch_iomfb_swapend_handler_size` | method-5 handler internal size gate (`cmp w2,#0x588 ; b.ne <err>`) | Companion to JB-26: beyond the dispatch-table check the handler re-checks the struct size (`cmp w2,#0x588 ; b.ne <kIOReturnBadArgument>`; verified unique at decompressed file-off 0x16ae22c; success path forwards the raw struct ptr to a `vtable+0x590` paravirt swap method). Retarget the `cmp` immediate to `0x6e0` so forced-kern iOS 27's native SwapEnd reaches real swap processing (27's IOMFBSwapRec prefix matches 26.x → handler reads valid fields). Semantic anchor (`cmp w2,#imm` word + following `b.ne` decode). Enabled together with JB-26 + DSC force-kern for iOS 27. | Y |
| JB-28 | A | `patch_disk_images2_client_abi` | `com.apple.driver.AppleDiskImages2` kext: `DIDeviceCreatorUserClient::CreateDevice` + `DIDeviceIOUserClient::Connect` ABI-version gates, and the `AllocPortsArray`/`RegisterNotificationPort` notif-port sizing | **iOS-27 DDI (`/System/Developer`) auto-mount — attach layer.** `pymobiledevice3 mounter auto-mount` on the 26.4-kernel / 27-userland hybrid fails at attach: the kernel DiskImages2 driver is ABI v9, the 27 userland's DiskImages2 controller/daemon is ABI v11 (`DIDeviceCreatorUserClient::CreateDevice: Incompatible client: expected ABI version 9 actual 11`). Three layers: **GATE1** NOPs the CreateDevice controller-ABI `cmp #9 ; b.ne` reject; **GATE2b** NOPs the Connect daemon-ABI `cmp #9 ; b.ne` reject (both anchored on the C++ signature cstring → unique `cmp #9`/`b.ne`; version-robust; no-op-in-effect on version-matched userlands where ABI 9==9). **GATE2** (array + 2 bound checks) fixes a RegisterNotificationPort off-by-one (userland registers at index==maxPorts, one past the array) by widening the AllocPortsArray allocation (`lsl x1,xN,#3` → `mov x1,#0x4000`) AND both bound-check field loads (`ldrh [.,#0xd8]`/`ldr [.,#0xe8]` → `mov wD,#0x800`); applied **all-or-nothing** (widening the bound checks without the backing array would let RegisterNotificationPort write past it → corruption) and skipped/logged on builds whose notif-port codegen differs (the off-by-one is 26.4-hybrid-specific). Pairs with the sandbox ops[124] allow (JB-09) and the diskimagesiod userland patch (CFW binary-patch #13). Anchors structural (Capstone decode of the pinned function's instructions); replacement bytes from the Keystone-backed `ARM64Encoder`. **GATE2a anchor note:** the AllocPortsArray size-shift is matched on `lsl` mnemonic + destination `x1` (the unique size-writing lsl in the function) — NOT a 3-operand `lsl xd,xn,#imm` shape, because Capstone on this toolchain decodes the lsl-immediate (a UBFM alias) as **2 operands**; requiring 3 operands makes GATE2 silently skip (the all-or-nothing returns a harmless no-op). Verified on the `c0ecdb4b` 26.4 deployment kernel via `patch-component --component kernel-jb --records-out`: all five di2 records emit (`di2_createdevice_abi`, `di2_connect_abi`, `di2_allocports_size`, `di2_notif_boundcheck_d8`, `di2_notif_boundcheck_e8`) — always verify the di2 records EMIT, not merely that the JB suite reports "no failures". No-op-in-effect for version-matched userlands. | Y |
| JB-29 | C | `patch_fpfs_scoped_vnode_open` | Sandbox MACF `mpo_vnode_check_open` (`ops[267]`) → per-process trampoline code cave | **iOS-27 random-respring fix (fpfs balloon).** JB-09 blanket-neuters `mpo_vnode_check_open` (`ops[267]` → allow) so processes can read `/var/jb`. But FileProvider's fpfs parent-walk (`fpfs_pkg_fd_lookup` → `openbyid` climbing via `getattrlistat(ATTR_CMN_PAROBJID)`) uses the stock check's EACCES at the domain-container boundary as its terminus; neutered, the walk climbs unbounded → `ResolverService` (FileProviderResolver) balloons to ~12 GB → `vm-compressor-space-shortage` jetsam → backboardd killed → **respring** (seen on 27b4/24A5390f). Fix keeps the global bypass and enforces the real check for the FileProvider daemons only: on 27, `ops[267]` is left un-neutered (removed from JB-09's blanket list — conditional `if !applyIOS27` in `patchSandboxHooksExtended`), then retargeted to a 20-insn code-cave trampoline that inlines `current_proc` (`mrs tpidr_el1` → `ldr [+0x3F0]` uthread → `ldr [+0x18]` proc), loads `p_comm` (`+0x56C`), compares the first 8 bytes to `"Resolver"`/`"fileprov"`, and on match `b`s to the real `vnode_check_open` (restores the terminus) else returns allow (`mov x0,#0 ; ret` → `/var/jb` reads + Sileo/TrollStore icons unaffected). Register-only (x8–x10), no frame/call (~18 insns/open). Struct offsets recovered via the VZ gdb stub on vphone600; cave bytes from the Keystone-backed `ARM64Encoder`, verified by Capstone round-trip; the `ops[267]` retarget preserves the auth-rebase high bits (same encoder family as JB-09). **VALIDATED on-device (2026-07-23, `17,3_27.0_24A5390f` + cloudOS 26.4, JB, `setup_machine` deploy): resprings stop; Sileo/TrollStoreLite icons render.** Backward-compat: a 26.5 base is unaffected (`ops[267]` still blanket-neutered there) — verified byte-identical kernelcache pre-vs-post (`cmp` clean, `sha256` unchanged). See `KernelJBPatchFpfsScopedOpen.swift`. | Y |
-| JB-30 | B | `patchParavirtDisplayRefreshRate` | `AppleParavirtDisplay::createDisplayAttributes` (AppleParavirtGPUIOGPUFamily), the per-mode timing element call | **120 Hz display timing (opt-in, `kernel-exp-display_refresh_120hz`, off in `standard`).** The host VM service builds its one `PGDisplayMode` with a constant 60.0 Hz and writes it into the display shared state page as a 16-byte entry (u16 width, u16 height, u32 refresh in 16.16 Hz, flags); the guest turns each entry into an IOAV timing element with `ldurh w1,[xN,#-8]; ldurh w2,[xN,#-6]; ldur w3,[xN,#-4]; bl`. The `ldur w3` becomes `movz w3,#120,lsl #16`. Anchor: the `createDisplayAttributes` logger cstring (all refs in one function) + the only w1/w2/w3 load triple off one base at -8/-6/-4 ahead of a call. Gated by `KernelCustomFirmwarePatcher.applyDisplayRefresh`, set from the plan. See `Research/Guest/display_refresh_rate.md`. | opt-in |
+| JB-30 | B | `patchParavirtDisplayRefreshRate` (record `kernel-cfw-display_promotion`; introduced as `kernel-exp-display_refresh_120hz`, renamed when `standard` turned it on) | `AppleParavirtDisplay::createDisplayAttributes` (AppleParavirtGPUIOGPUFamily), the per-mode timing element call | **ProMotion: 120 Hz display timing (on in `standard` since 2026-10-09; it shipped opt-in from 2.4.2).** The host VM service builds its one `PGDisplayMode` with a constant 60.0 Hz and writes it into the display shared state page as a 16-byte entry (u16 width, u16 height, u32 refresh in 16.16 Hz, flags); the guest turns each entry into an IOAV timing element with `ldurh w1,[xN,#-8]; ldurh w2,[xN,#-6]; ldur w3,[xN,#-4]; bl`. The `ldur w3` becomes `movz w3,#120,lsl #16`. Anchor: the `createDisplayAttributes` logger cstring (all refs in one function) + the only w1/w2/w3 load triple off one base at -8/-6/-4 ahead of a call. Gated by `KernelCustomFirmwarePatcher.applyProMotion`, set from the plan. See `Research/Guest/display_refresh_rate.md`. | Y |
| JB-31 | C | `patchParavirtUserClientsNarrow` (records `kernel-cfw-paravirt_user_clients.redirect` / `.cave`; introduced as `kernel-exp-paravirt_user_clients`, renamed when `standard` turned it on) | Same IOUserClient Sandbox gate; the deny block's `ldr Xt,[sp,#imm]` eight bytes before the fail-log `adrp` | **Paravirtual device access on a 26.x / 18.x base (on in `standard` since 2026-10-04; it shipped opt-in).** Narrow replacement for the broad gate-off: at the deny point the class-name C string is already in x0, so a code-cave trampoline reads its first eight bytes and branches to the gate's NotPermitted allow target only for `ApplePar` / `AppleVid` / `AppleVir` / `IOSurfac` (AppleParavirt\*, AppleVideoToolboxParavirt\*, AppleVirtIO\*, IOSurfaceAcceleratorParavirtClient); every other denial runs the displaced `ldr` and falls through to the real deny. Fixes `MTLCreateSystemDefaultDevice()` nil in daemons/CLI and the VideoToolbox/ANE/IOSurface denials (upstream issue #22) without opening the rest. Cave words verified by clang/as + capstone round-trip; the two `b` words via `ARM64Encoder`. Gated by `KernelCustomFirmwarePatcher.applyParavirtUserClients`, set from the plan when `applyIOS27` is false. See `Research/Guest/gpu_acceleration.md`. | Y |
### EXP-Only Kernel Methods (Reference List)
@@ -2898,3 +2898,45 @@ with the actual read-only destination. The fallback creates a private RW copy,
then changes it to RX; other calls pass through. No kernel patch or protection
policy change is added. See `Research/Guest/flutter_aot_remap_compatibility.md`
for exact guards, failure semantics, reproduction and validation limits.
+
+## ProMotion joins `standard` (2026-10-09)
+
+No new Apple binary patch and no new bytes. JB-30, the 120 Hz timing element,
+leaves `standard`'s block list and `FirmwarePatchSetCatalog.manualOnlyPatches`,
+so every new VM's paravirtual display advertises 120 Hz. It has no version gate,
+so it lands on every base. The pipeline's no-plan fallback in
+`buildComponentList` is on too, so a pipeline built without a preset agrees with
+`standard`; the patcher's own `applyProMotion` default stays false, so
+`KernelcacheCustomFirmwareComparisonTests` still compares against the records the
+reference was taken from.
+
+**Why.** Measured since 2026-10-04 (`Research/Guest/display_refresh_rate.md`): the
+host scans out every frame the guest presents up to 120, the userland renders at
+the advertised rate with no change of its own, a static screen costs what it did
+at 60 Hz, and a guest with the patch booted on iPadOS 26.6.2 and iOS 27.0. The cost
+is unchanged: up to twice the host CPU and GPU while the guest animates.
+
+**Depends on Lakr233/vphone-cli#643 for iOS 26.** On an iPhone17,3 26.6.2 guest
+with the 2.9.0 guest components, SpringBoard deadlocked in three of three 120 Hz
+boots. Its main thread held `libvphoneattitude`'s `@synchronized` lock in the
+`setDeviceMotionUpdateInterval:` hook while waiting for Core Motion's MotionThread,
+which was waiting for that lock in the `isDeviceMotionActive` hook (guest spindump,
+symbolicated against 23G90). #643 fixes that lock order. With its fix cherry-picked,
+the same guest booted at 120 Hz and scrolled Settings at 119.3 frames per second.
+Details: `Research/Guest/display_refresh_rate.md`, "iPhone 26.6.2, and the attitude
+hook deadlock".
+
+**Renamed, with a migration.** The editor titles it ProMotion and the naming rule
+gives `cfw` to a patch `standard` turns on, so the record is
+**`kernel-cfw-display_promotion`**. The old `kernel-exp-display_refresh_120hz`
+shipped from 2.4.2, unlike the same-day `kernel-exp-paravirt_user_clients`, so a
+VM may have it checked. `FirmwarePatchSetCatalog.renamedPatches` maps old to new,
+and `VPhonePatchPresetStore` reads `PatchSelection.plist`, `PatchPlan.plist` and
+`PatchReceipt.plist` through it: such a VM resolves instead of failing `fw patch`
+with `unknownPatch`, and its kernelcache counts as already carrying the patch.
+
+**Existing `standard` VMs** now read as wanting it in the kernelcache part and
+keep 60 Hz until `cfw update-kernel` or a restore writes it.
+
+**Opting out.** `vphone-cli fw set-patches <vm> --block
+kernel-cfw-display_promotion`, then `cfw update-kernel`.
diff --git a/Research/Guest/display_refresh_rate.md b/Research/Guest/display_refresh_rate.md
index c810ff47..6c0b8703 100644
--- a/Research/Guest/display_refresh_rate.md
+++ b/Research/Guest/display_refresh_rate.md
@@ -2,10 +2,11 @@
A vphone guest renders at 60 Hz whatever the host display does. This note
records where the 60 comes from, why no Virtualization setting changes it, and
-the opt-in kernel patch `kernel-exp-display_refresh_120hz` that makes the guest
-display advertise 120 Hz. Measured on 2026-10-04 on macOS 27.0.1 (26A434),
-Apple M5 Pro, built-in 120 Hz display, cloudOS 26.4 (23E5207q) kernel with an
-iPadOS 26.6.2 (23G90) userland.
+the kernel patch `kernel-cfw-display_promotion` (titled ProMotion) that makes the
+guest display advertise 120 Hz. It is on in `standard` since 2026-10-09; it
+shipped opt-in as `kernel-exp-display_refresh_120hz` from 2.4.2. Measured on
+2026-10-04 on macOS 27.0.1 (26A434), Apple M5 Pro, built-in 120 Hz display,
+cloudOS 26.4 (23E5207q) kernel with an iPadOS 26.6.2 (23G90) userland.
## Where 60 Hz Comes From
@@ -80,7 +81,7 @@ driver publishes; the results below show the userland takes its pace from it.
`KernelCustomFirmwarePatcher.patchParavirtDisplayRefreshRate`
(`Kernel/CustomFirmwarePatches/Drivers/KernelCustomFirmwarePatchDisplayRefresh.swift`)
replaces the load of `w3` with `movz w3, #120, lsl #16`, that is 120.0 Hz in
-16.16. One instruction, one record: `kernel-exp-display_refresh_120hz`.
+16.16. One instruction, one record: `kernel-cfw-display_promotion`.
Reveal procedure, no offsets:
@@ -98,9 +99,10 @@ Reveal procedure, no offsets:
On the 23E5207q research kernelcache the record lands at file offset
`0xEB1A98`.
-It is declared in `com.vphone.patchset.kernel.cfw` with no version gate and
-blocked in `standard`, so it is a per-VM checkmark or a preset of its own. It is
-a preference, not a fix: see the cost in the results.
+It is declared in `com.vphone.patchset.kernel.cfw` with no version gate and is on
+in `standard`; a VM that blocks it keeps the host's 60 Hz mode. It is a
+preference, not a fix: see the cost in the results. See "On in `standard`" below
+for why it moved and what happens to a VM that opted in under the old name.
## Results
@@ -133,9 +135,10 @@ A guest whose product type is a 60 Hz device follows the patch too:
scrolling Settings, 97% of them on time, and about 102 swiping Home Screen
pages. The userland does not cap the rate by model.
-Not measured: an iPhone guest, an iOS 27 userland, and a host display that is
-not 120 Hz, where the window cannot show the extra frames whatever the guest
-renders.
+Not measured here: an iPhone guest, an iOS 27 userland, and a host display that
+is not 120 Hz, where the window cannot show the extra frames whatever the guest
+renders. An iPhone 26.6.2 guest was measured later; see "iPhone 26.6.2, and the
+attitude hook deadlock" below.
## Animations at 120 Hz
@@ -237,3 +240,77 @@ The guest side, with vphoned only:
The report gives exact CPU time per thread and unsymbolicated frames as
`library + offset [address]`. Subtract the `System Primary` shared cache slide
in the report header from an address and pass it to `ipsw dyld a2s`.
+
+## On in `standard` (2026-10-09)
+
+The patch leaves `standard`'s block list and
+`FirmwarePatchSetCatalog.manualOnlyPatches`, so every new VM gets the 120 Hz
+timing element. The measurements above are why it can: the host scans out every
+frame up to 120, the userland follows the advertised rate with no change of its
+own, an iPad guest whose model is a 60 Hz device follows it too, and a static
+screen costs what it did at 60 Hz. The 2026-10-05 kernel update round
+(`Research/0_binary_patch_comparison.md`, "The kernelcache reaches an installed
+guest without a restore") toggled it on an iPhone17,3 27.0 (24A435) guest, which
+booted. The cost while animating is unchanged: up to twice the host CPU and GPU
+of a 60 Hz guest.
+
+### iPhone 26.6.2, and the attitude hook deadlock
+
+Checked on 2026-10-09 on a dedicated VM: iPhone17,3 26.6.2 (23G90), cloudOS 26.4
+(23E5207q) kernel, `standard` from a bundle built from this change (2.9.0 base),
+`--no-template`. The kernelcache record landed at `0xEB1A98`, as on the iPad.
+
+With the 2.9.0 guest components the guest never left the Apple logo. In three
+boots at 120 Hz (the first boot after the restore and two reboots) SpringBoard and
+backboardd stopped at 3–4 s of CPU and stayed there; every SpringBoard-bound vphoned
+call (`apps.launch`, `apps.foreground`) hung. A guest spindump (launchd job, 5 s)
+reported the deadlock itself:
+
+- SpringBoard's main thread: `_SBFApplyParallaxSettingsToViewWithFactor` →
+ `-[UIView _updateParallaxEffectWithAltitude:bias:]` → `-[UIView addMotionEffect:]`
+ → `-[_UIMotionEffectEngine init]` → `-[_UIMotionEffectCoreMotionEventProvider init]`
+ → `VPhoneInterval` (`libvphoneattitude.dylib`, the `setDeviceMotionUpdateInterval:`
+ hook, holding `@synchronized(session)`) → Core Motion's native setter, waiting for
+ the MotionThread.
+- `com.apple.CoreMotion.MotionThread`: a Core Motion callback → `VPhoneActive` (the
+ `isDeviceMotionActive` hook) → `objc_sync_enter`, waiting for the main thread.
+
+The hook image was matched by UUID (`BFDEACD1-AAAB-324E-8A5C-5ACF6135EE47`, this
+build's `libvphoneattitude.dylib`) and the system frames symbolicated against the
+23G90 shared cache with `ipsw dyld a2s`. This is the lock-order bug that
+Lakr233/vphone-cli#643 fixes, not the display patch: #643 reports it at 60 Hz on
+every 2.9.0 iOS 26.6.2 template build. Here, with the same guest data, a 60 Hz
+kernelcache (`fw set-patches --block`, `cfw update-kernel`) booted once without
+hanging, so 120 Hz seems to make the race easier to lose; one 60 Hz boot does not
+show that 60 Hz is safe.
+
+With #643's hook fix (12c72fa) cherry-picked onto the same bundle and the guest
+environment redeployed (`vm set-bundle --update-environment`), the 120 Hz kernel
+booted. Setup Assistant was skipped, SpringBoard relaunched and reached the Home
+Screen. Continuous Settings scrolling for 12 s scanned out 119.3 frames per second,
+with a median gap of 8.2 ms and 98.5% of the gaps under 12.5 ms.
+
+So `standard` with ProMotion needs #643's attitude fix on an iOS 26 guest. Ship it
+in a bundle that also carries #643.
+
+The pipeline's no-plan fallback in `buildComponentList` is now on as well, so a
+pipeline built without a preset agrees with `standard`. The patcher's own
+`applyProMotion` default stays false, so the kernel CFW reference comparison is
+unchanged.
+
+**Renamed.** The `{component}-{effect}-{name}` rule gives `cfw` to a patch
+`standard` turns on, and the editor now titles it ProMotion, so the identifier is
+`kernel-cfw-display_promotion`. Unlike the earlier renames, the old identifier
+shipped (2.4.2 onwards) and a VM may have checked it, so
+`FirmwarePatchSetCatalog.renamedPatches` maps it. `VPhonePatchPresetStore` reads
+`PatchSelection.plist`, `PatchPlan.plist` and `PatchReceipt.plist` through that
+map: a VM that opted in under the old name resolves instead of failing `fw patch`
+with `unknownPatch`, and a kernelcache already patched under the old name counts
+as carrying the new one rather than as drift.
+
+**Existing VMs.** A `standard` VM whose kernelcache was patched without it now
+reads as wanting it. Its guest keeps 60 Hz until `cfw update-kernel` (or a
+restore) writes the re-patched kernelcache.
+
+**Opting out.** `vphone-cli fw set-patches <vm> --block
+kernel-cfw-display_promotion`, then `cfw update-kernel`.
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/CustomFirmwarePatches/Drivers/KernelCustomFirmwarePatchDisplayRefresh.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/CustomFirmwarePatches/Drivers/KernelCustomFirmwarePatchDisplayRefresh.swift
index c0785c67..dd18c0bc 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/CustomFirmwarePatches/Drivers/KernelCustomFirmwarePatchDisplayRefresh.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/CustomFirmwarePatches/Drivers/KernelCustomFirmwarePatchDisplayRefresh.swift
@@ -80,7 +80,7 @@ extension KernelCustomFirmwarePatcher {
emit(
loadOff,
movz,
- patchID: "kernel-exp-display_refresh_120hz",
+ patchID: FirmwarePatchSetCatalog.proMotionPatch,
virtualAddress: fileOffsetToVA(loadOff),
description: "timing element refresh ldur w3,[mode,#-4] -> movz w3,#\(Self.displayRefreshHz),lsl #16 [16.16 Hz]",
)
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/KernelCustomFirmwarePatcher.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/KernelCustomFirmwarePatcher.swift
index 97cedfbd..7e20335b 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/KernelCustomFirmwarePatcher.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/KernelCustomFirmwarePatcher.swift
@@ -31,9 +31,10 @@ public final class KernelCustomFirmwarePatcher: KernelCustomFirmwarePatcherBase,
/// byte-identical when false.
public var applyFrida = false
- /// Opt-in 120 Hz display timing. Set from the plan: `standard` blocks it, so
- /// a guest keeps the host's 60 Hz mode unless the VM asked otherwise.
- public var applyDisplayRefresh = false
+ /// ProMotion, the 120 Hz display timing. Set from the plan, and `standard`
+ /// turns it on; a VM that blocks it keeps the host's 60 Hz mode. False here so
+ /// a patcher built directly writes what the reference records were taken from.
+ public var applyProMotion = false
/// On a base older than 27: a narrow allowlist at the same sandbox gate, so a
/// process outside an app sandbox can open the paravirtual GPU, video decoder,
@@ -102,9 +103,9 @@ public final class KernelCustomFirmwarePatcher: KernelCustomFirmwarePatcherBase,
patchVmMapDeleteImmutableCode()
}
- // Opt-in: the paravirtual display advertises 120 Hz instead of the
- // host's fixed 60 Hz mode.
- if applyDisplayRefresh {
+ // The paravirtual display advertises 120 Hz instead of the host's
+ // fixed 60 Hz mode, unless the VM blocked it.
+ if applyProMotion {
patchParavirtDisplayRefreshRate()
}
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareKernelCustomFirmwarePatchSet.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareKernelCustomFirmwarePatchSet.swift
index 163e5af2..18ca8a7d 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareKernelCustomFirmwarePatchSet.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareKernelCustomFirmwarePatchSet.swift
@@ -289,12 +289,13 @@ public enum FirmwareKernelCustomFirmwarePatchSet {
// MARK: Display
VPhonePatchDeclaration(
- identifier: FirmwarePatchSetCatalog.displayRefreshPatch,
- title: "120 Hz display timing",
+ identifier: FirmwarePatchSetCatalog.proMotionPatch,
+ title: "ProMotion",
summary: """
- Makes the paravirtual display advertise 120 Hz instead of the host's fixed \
- 60 Hz mode. Off by default: the guest renders twice as often, and only a \
- 120 Hz host display shows it.
+ Makes the paravirtual display advertise 120 Hz, as a ProMotion panel does, \
+ instead of the host's fixed 60 Hz mode. While it animates the guest renders \
+ twice as often, so the host spends up to twice the CPU and GPU on it; turn it \
+ off to keep 60 Hz.
""",
target: .firmware(.kernelcache),
),
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
index 3829be6b..28d2902a 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
@@ -55,23 +55,48 @@ public enum FirmwarePatchSetCatalog {
/// `dyld-exp-mis_trust_auth` is off because a userspace hook now does its
/// job: see ``misTrustAuthPatch``.
///
- /// `kernel-exp-display_refresh_120hz` is off because it is a preference with a
- /// cost: see ``displayRefreshPatch``.
- ///
- /// `kernel-cfw-paravirt_user_clients` is not in this list: `standard` turns it
- /// on. See ``paravirtUserClientsPatch``.
+ /// `kernel-cfw-paravirt_user_clients` and `kernel-cfw-display_promotion`
+ /// are not in this list: `standard` turns them on. See
+ /// ``paravirtUserClientsPatch`` and ``proMotionPatch``.
public static let manualOnlyPatches: Set<String> =
Set(FirmwareKernelFridaPatchSet.manifest.patches.map(\.identifier))
.union(hypervisorConcealmentPatches)
.union(experimentalIdentityPatches)
- .union([misTrustAuthPatch, displayRefreshPatch, FirmwareGuestSystemPatchSet.settingsRootRows, FirmwareGuestSystemPatchSet.settingsSoftwareUpdate])
+ .union([misTrustAuthPatch, FirmwareGuestSystemPatchSet.settingsRootRows, FirmwareGuestSystemPatchSet.settingsSoftwareUpdate])
- /// The 120 Hz timing for the paravirtual display.
- ///
- /// Off in `standard`: the host's mode is 60 Hz, a guest rendering twice as
- /// often costs twice the host CPU and GPU, and only a 120 Hz host display
- /// shows the difference. See `Research/Guest/display_refresh_rate.md`.
- public static let displayRefreshPatch = "kernel-exp-display_refresh_120hz"
+ /// ProMotion: the 120 Hz timing for the paravirtual display.
+ ///
+ /// On in `standard`. The host's mode is 60 Hz and Virtualization has no
+ /// setting for it; the guest renders at whatever rate the timing element
+ /// advertises, and the host scans out every frame it presents. A guest
+ /// rendering twice as often costs up to twice the host CPU and GPU while it
+ /// animates, and nothing while it is static. Blocking it per VM keeps 60 Hz.
+ ///
+ /// Introduced opt-in as `kernel-exp-display_refresh_120hz`, which shipped from
+ /// 2.4.2; renamed `kernel-cfw-display_promotion` when `standard` turned it on,
+ /// as the naming rule requires. ``renamedPatches`` maps a VM's record of the
+ /// old name. See
+ /// `Research/Guest/display_refresh_rate.md`.
+ public static let proMotionPatch = "kernel-cfw-display_promotion"
+
+ /// Identifiers a released bundle declared that a later one renamed, old to new.
+ ///
+ /// A VM's `PatchSelection.plist` and `PatchReceipt.plist` outlive the bundle
+ /// that wrote them, and `fw patch` throws `unknownPatch` for an identifier
+ /// nothing declares. Only renames that reached a release are listed: one that
+ /// never left a development branch has no record to carry.
+ public static let renamedPatches: [String: String] = [
+ "kernel-exp-display_refresh_120hz": proMotionPatch,
+ ]
+
+ /// The identifiers this bundle declares for ones a VM recorded, in order, each
+ /// once.
+ public static func currentIdentifiers(_ identifiers: [String]) -> [String] {
+ var seen = Set<String>()
+ return identifiers
+ .map { renamedPatches[$0] ?? $0 }
+ .filter { seen.insert($0).inserted }
+ }
/// A narrow IOUserClient sandbox allowlist for the paravirtual devices, on a
/// base older than 27.
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift
index deb8b525..c5d07351 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift
@@ -90,8 +90,8 @@ extension FirmwarePipeline {
isEnabled($0.identifier, fallback: false)
}
- // The 120 Hz display timing, off unless the VM asked for it.
- let applyDisplayRefresh = isEnabled(FirmwarePatchSetCatalog.displayRefreshPatch, fallback: false)
+ // ProMotion, the 120 Hz display timing: on in `standard`, on every base.
+ let applyProMotion = isEnabled(FirmwarePatchSetCatalog.proMotionPatch, fallback: true)
// The paravirtual user-client allowlist, on in `standard` and pinned to the
// 26.x and 18.x bases (27 opens the whole gate instead).
let applyParavirtUserClients = isEnabled(
@@ -243,7 +243,7 @@ extension FirmwarePipeline {
applyExcGuard: applyExcGuard,
applyIOS27: applyIOS27,
applyFrida: applyFrida,
- applyDisplayRefresh: applyDisplayRefresh,
+ applyProMotion: applyProMotion,
applyParavirtUserClients: applyParavirtUserClients,
includeBase: includeKernelBase,
includeCustomFirmware: includeKernelCustomFirmware,
@@ -391,7 +391,7 @@ extension FirmwarePipeline {
applyExcGuard: Bool,
applyIOS27: Bool,
applyFrida: Bool,
- applyDisplayRefresh: Bool,
+ applyProMotion: Bool,
applyParavirtUserClients: Bool,
includeBase: Bool,
includeCustomFirmware: Bool,
@@ -411,7 +411,7 @@ extension FirmwarePipeline {
let p = KernelCustomFirmwarePatcher(data: data, verbose: verbose)
p.applyIOS27 = applyIOS27
p.applyFrida = applyFrida
- p.applyDisplayRefresh = applyDisplayRefresh
+ p.applyProMotion = applyProMotion
p.applyParavirtUserClients = applyParavirtUserClients
p.gate = gate
return p
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/FirmwarePatcherTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/FirmwarePatcherTests.swift
index 1ee12996..848f3bca 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/FirmwarePatcherTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/FirmwarePatcherTests.swift
@@ -637,6 +637,39 @@ struct FirmwarePipelineTests {
}
}
+ @Test func `standard turns ProMotion on unless the VM blocks it`() throws {
+ // From the standard plan and from the no-plan fallback, on every base.
+ let root = URL(fileURLWithPath: NSTemporaryDirectory())
+ func flag(_ base: String?, standard: Bool, blocked: Set<String> = []) throws -> Bool {
+ let version = VPhoneVersion(base)
+ let pipeline = FirmwarePipeline(
+ vmDirectory: root,
+ variant: .jb,
+ verbose: false,
+ preset: standard ? FirmwarePatchSetCatalog.standardPreset : nil,
+ blockedPatches: blocked,
+ )
+ let plan = try pipeline.resolvePlan(iOSBase: version, cloudOS: VPhoneVersion("26.4"))
+ let components = pipeline.buildComponentList(
+ restoreDir: root,
+ iOSBase: version,
+ plan: plan,
+ gate: plan.map { VPhonePatchGate(plan: $0) } ?? .unrestricted,
+ )
+ let kernel = try #require(components.first { $0.name == "kernelcache" })
+ let patcher = try #require(
+ kernel.patcherFactories.lazy.compactMap { try? $0(Data(), false) as? KernelCustomFirmwarePatcher }.first,
+ )
+ return patcher.applyProMotion
+ }
+ for base in ["18.6.2", "26.6.2", "27.0", nil] {
+ for standard in [true, false] {
+ #expect(try flag(base, standard: standard))
+ }
+ #expect(try !flag(base, standard: true, blocked: [FirmwarePatchSetCatalog.proMotionPatch]))
+ }
+ }
+
@Test func `find file supports glob patterns`() throws {
let fm = FileManager.default
let tempDir = URL(fileURLWithPath: NSTemporaryDirectory())
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
index a2455628..88c9bda9 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
@@ -248,6 +248,51 @@ struct FirmwarePatchSetCatalogTests {
}
}
+ @Test
+ func `Standard turns ProMotion on, on every base`() throws {
+ let patch = FirmwarePatchSetCatalog.proMotionPatch
+ #expect(!FirmwarePatchSetCatalog.manualOnlyPatches.contains(patch))
+ #expect(FirmwarePatchSetCatalog.standardPreset.selection.includes(patch))
+ for base in ["18.6.2", "26.0", "26.4", "26.6.2", "27.0"] {
+ for cloud in ["26.1", "26.4"] {
+ let plan = try VPhonePatchPlan.resolve(
+ preset: FirmwarePatchSetCatalog.standardPreset,
+ patchSets: FirmwarePatchSetCatalog.bundled,
+ iOSBase: VPhoneVersion(base),
+ cloudOS: VPhoneVersion(cloud),
+ )
+ #expect(plan.isEnabled(patch), "\(patch) on \(base)/\(cloud)")
+ }
+ }
+ // A VM that blocks it keeps the host's 60 Hz.
+ let blocked = try VPhonePatchPlan.resolve(
+ preset: FirmwarePatchSetCatalog.standardPreset,
+ patchSets: FirmwarePatchSetCatalog.bundled,
+ iOSBase: VPhoneVersion("27.0"),
+ cloudOS: VPhoneVersion("26.4"),
+ blocked: [patch],
+ )
+ #expect(!blocked.isEnabled(patch))
+ }
+
+ @Test
+ func `A renamed patch maps to one the catalogue declares`() {
+ let declared = Set(FirmwarePatchSetCatalog.allDeclarations.map(\.identifier))
+ for (old, new) in FirmwarePatchSetCatalog.renamedPatches {
+ #expect(!declared.contains(old), "\(old) is still declared")
+ #expect(declared.contains(new), "\(old) maps to \(new), which nothing declares")
+ }
+ // A record that named the old 120 Hz identifier, possibly beside the new
+ // one, reads as the new one, once, in place.
+ #expect(
+ FirmwarePatchSetCatalog.currentIdentifiers([
+ "kernel-exp-hv_vmm",
+ "kernel-exp-display_refresh_120hz",
+ FirmwarePatchSetCatalog.proMotionPatch,
+ ]) == ["kernel-exp-hv_vmm", FirmwarePatchSetCatalog.proMotionPatch],
+ )
+ }
+
@Test
func `The Frida relaxations need cloudOS 26.4`() throws {
for cloud in ["26.1", "26.4"] {
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhonePatchPresetStore.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhonePatchPresetStore.swift
index 87c440e3..fb802282 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhonePatchPresetStore.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhonePatchPresetStore.swift
@@ -55,8 +55,14 @@ public struct VPhoneVirtualMachinePatchSelection: Codable, Sendable, Hashable {
let container = try decoder.container(keyedBy: CodingKeys.self)
presetIdentifier = try container.decodeIfPresent(String.self, forKey: .presetIdentifier)
?? VPhonePatchPreset.standardIdentifier
- blockedPatches = try container.decodeIfPresent([String].self, forKey: .blockedPatches) ?? []
- allowedPatches = try container.decodeIfPresent([String].self, forKey: .allowedPatches) ?? []
+ // A record outlives the bundle that wrote it, so a renamed patch is read
+ // under the name this bundle declares.
+ blockedPatches = try FirmwarePatchSetCatalog.currentIdentifiers(
+ container.decodeIfPresent([String].self, forKey: .blockedPatches) ?? [],
+ )
+ allowedPatches = try FirmwarePatchSetCatalog.currentIdentifiers(
+ container.decodeIfPresent([String].self, forKey: .allowedPatches) ?? [],
+ )
}
}
@@ -98,7 +104,9 @@ public struct VPhoneVirtualMachinePatchPlan: Codable, Sendable, Hashable {
let container = try decoder.container(keyedBy: CodingKeys.self)
presetIdentifier = try container.decode(String.self, forKey: .presetIdentifier)
patchSets = try container.decodeIfPresent([String].self, forKey: .patchSets) ?? []
- enabledPatches = try container.decodeIfPresent([String].self, forKey: .enabledPatches) ?? []
+ enabledPatches = try FirmwarePatchSetCatalog.currentIdentifiers(
+ container.decodeIfPresent([String].self, forKey: .enabledPatches) ?? [],
+ )
iOSBaseVersion = try container.decodeIfPresent(String.self, forKey: .iOSBaseVersion)
cloudOSVersion = try container.decodeIfPresent(String.self, forKey: .cloudOSVersion)
parameters = try container.decodeIfPresent([String: String].self, forKey: .parameters) ?? [:]
@@ -155,11 +163,15 @@ public struct VPhoneVirtualMachinePatchReceipt: Codable, Sendable, Hashable {
public init(from decoder: any Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
- patches = try container.decode([String].self, forKey: .patches)
+ patches = try FirmwarePatchSetCatalog.currentIdentifiers(
+ container.decode([String].self, forKey: .patches),
+ ).sorted()
writer = try container.decode(String.self, forKey: .writer)
bundleVersion = try container.decodeIfPresent(String.self, forKey: .bundleVersion)
date = try container.decode(Date.self, forKey: .date)
- notApplicable = try container.decodeIfPresent([String].self, forKey: .notApplicable) ?? []
+ notApplicable = try FirmwarePatchSetCatalog.currentIdentifiers(
+ container.decodeIfPresent([String].self, forKey: .notApplicable) ?? [],
+ ).sorted()
}
}
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
index 0bf7060b..eb7dfafe 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
@@ -19,8 +19,11 @@
userspace in installd, misagent and SpringBoard, so editing the shared cache for
it buys nothing there, costs an iOS 27 guest its boot (issue #532), and on 24A435 cannot
even be applied. See FirmwarePatchSetCatalog.misTrustAuthPatch.
- The fifth is the 120 Hz display timing, a preference that doubles how often the
- guest renders. See FirmwarePatchSetCatalog.displayRefreshPatch.
+ The fifth is the Settings row hiding (system-preferences-exp-root_rows and
+ dyld-exp-settings_software_update_row), a preference.
+ ProMotion, the 120 Hz display timing (kernel-cfw-display_promotion), is on: the
+ guest renders at the rate its display advertises, and the host shows every frame.
+ See FirmwarePatchSetCatalog.proMotionPatch.
The narrow paravirtual user-client allowlist (kernel-cfw-paravirt_user_clients) is
on: without it a daemon on a 26.x or 18.x base cannot open the paravirtual GPU,
and cameracaptured crash-loops on it. See
@@ -123,7 +126,6 @@
<string>dyld-exp-mis_trust_auth</string>
<string>system-preferences-exp-root_rows</string>
<string>dyld-exp-settings_software_update_row</string>
- <string>kernel-exp-display_refresh_120hz</string>
</array>
</dict>
</dict>