Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Duo: run the inner display at the panel's 120 Hz

Jacky16795479d751
diff --git a/Research/Guest/iphone_duo_bringup.md b/Research/Guest/iphone_duo_bringup.md
index a7a35440..1a035d88 100644
--- a/Research/Guest/iphone_duo_bringup.md
+++ b/Research/Guest/iphone_duo_bringup.md
@@ -4786,3 +4786,53 @@ Measured on the test VM (bundle built from this change):
- Guest screenshots match the VM window at offset (0, 0) in all four inner and
three cover orientations (cover tested with Safari, which rotates on iPhone).
- Three launch-sequence captures: no black frames, 2-5 transient tiles.
+
+## 2026-10-29 night: the inner display at 120 Hz
+
+Open, the VM window counted 60 fps while the cover (the paravirtual panel,
+with the ProMotion patch) runs at 120. Two caps, one in each process:
+
+- **backboardd.** A `CAWindowServerVirtualDisplay` gets one 60 Hz mode whatever
+ `kCAVirtualDisplayUpdateRate` says. `VirtualDisplay::refresh_rate()` uses the
+ update rate only while the display has no current mode; with one, it takes
+ the mode's 16.16 rate. `heartbeat_rate()` is that mode's period divided by
+ the integer `kCAVirtualDisplayMinimumFrameDuration` (default 1). Clients read
+ `CADisplay.refreshRate` (the mode), and `UIScreen.maximumFramesPerSecond`
+ is its inverse, so every app on the inner display was capped at 60
+ (UpdateRate 120: the display ticked faster, apps still saw 60; UpdateRate
+ 60 + MinimumFrameDuration 2: heartbeat 1/120, refresh still 1/60).
+ The display's modes can be replaced with `-[CAWindowServerDisplay
+ setDigitalModes:withTimings:]` (`VirtualDisplay::set_digital_modes`), which
+ takes the framebuffer timing format: timings with `HorizontalAttributes` /
+ `VerticalAttributes` `{Active}` and `VerticalAttributes.PreciseSyncRate`
+ (16.16, default `0x3c0000` = 60), optional `Score`, and color modes
+ (`PixelEncoding` 0, `Depth` ≤ 8, `Colorimetry` 1/10/16, `EOTF` 0,
+ `DynamicRange` 0). A mode is preferred only when its score is above 0
+ (Colorimetry 16 adds 2, plain RGB nothing); with no preferred mode the
+ display comes up 0×0 and SpringBoard aborts in
+ `-[SBMainDisplayConfigurationTransformer transformDisplayConfiguration:]`.
+ FoldDisplay now sets one timing, 2853×2007 at 120, with Colorimetry 1 and
+ Score 1: the inner mode reads `RGB_8bit` like the panel's.
+- **SpringBoard.** The compositor's display link asks for the panel's
+ `maximumFramesPerSecond` (120 with the ProMotion patch, else 60).
+
+backboardd cannot read the panel's rate while it adds the inner display: the
+primary's rate is not set yet during display detection, and asking
+`CADisplay` there blocks backboardd (the inner display never appeared).
+
+Measured on duospike-inner (iOS 27.1, Settings open, 3 s windows):
+
+| | panel (LCD) | inner |
+|---|---|---|
+| `UIScreen.maximumFramesPerSecond` | 120 | 120 (was 60) |
+| `CADisplay.refreshRate` / heartbeat | 1/120 / 1/120 | 1/120 / 1/120 (was 1/60) |
+| default `CADisplayLink`, ticks in 3 s | 377 | 377 |
+| compositor renders in 3 s | | 375-378 |
+
+Idle CPU on the home screen, three 10 s samples each: 60 Hz build SpringBoard
+6.9-7.9%, backboardd 37.8-45.6%; 120 Hz build 9.3-10.4% and 50.3-51.3%.
+
+Window captures (ScreenCaptureKit) cannot judge 120 Hz here: the cover, which
+is natively 120, measures the same 40-55 changes per second as the inner
+display, because the host composites the window at its own rate. Use guest
+display links, or the host's `lastSubmittedTime` poller from the vGPU notes.
diff --git a/VPhoneGuestComponents/FoldDisplay/FoldDisplayBackboard.m b/VPhoneGuestComponents/FoldDisplay/FoldDisplayBackboard.m
index 28519db9..17841c7d 100644
--- a/VPhoneGuestComponents/FoldDisplay/FoldDisplayBackboard.m
+++ b/VPhoneGuestComponents/FoldDisplay/FoldDisplayBackboard.m
@@ -35,6 +35,29 @@ static void vpTagUnknownDisplay(id display) {
vpFoldDisplayLog([NSString stringWithFormat:@"inner display: tag %@ (%lu)", describe(unknown), (unsigned long)unknown]);
}
+// The inner panel is a 120 Hz ProMotion panel. A virtual display's mode is
+// 60 Hz whatever kCAVirtualDisplayUpdateRate says, and every client reads
+// its refresh rate, heartbeat and UIScreen.maximumFramesPerSecond from that
+// mode, so apps on the inner display drew at 60. The display takes digital
+// modes in the framebuffer's timing format instead: one timing at the
+// panel's size with a 16.16 PreciseSyncRate of 120, and one 8-bit RGB color
+// mode (Colorimetry 1, as the primary's RGB_8bit). Only a mode scoring above
+// 0 can be preferred, and plain RGB adds nothing, hence Score 1. A mode set
+// replaces the current mode it does not contain, so this one becomes current.
+static void vpSetInnerDisplayProMotionMode(id display) {
+ SEL setModes = sel_registerName("setDigitalModes:withTimings:");
+ Method method = class_getInstanceMethod(object_getClass(display), setModes);
+ if (!method || strcmp(method_getTypeEncoding(method), "B32@0:8@16@24") != 0) {
+ vpFoldDisplayLog(@"inner display: digital modes ABI unavailable, staying at 60 Hz");
+ return;
+ }
+ NSArray *colors = @[@{@"ID": @1, @"PixelEncoding": @0, @"Depth": @8, @"Colorimetry": @1, @"EOTF": @0, @"DynamicRange": @0}];
+ NSArray *timings = @[@{@"ID": @1, @"Score": @1, @"HorizontalAttributes": @{@"Active": @2853},
+ @"VerticalAttributes": @{@"Active": @2007, @"PreciseSyncRate": @(120 << 16)}}];
+ BOOL set = ((BOOL (*)(id, SEL, id, id))objc_msgSend)(display, setModes, colors, timings);
+ vpFoldDisplayLog([NSString stringWithFormat:@"inner display: 120 Hz mode %@", set ? @"set" : @"refused"]);
+}
+
// Adds the inner panel's render display to a render server, once. It is
// never removed: FrontBoard keeps identities for the life of the monitor.
static BOOL vpAddInnerRenderDisplayToServer(id server) {
@@ -52,6 +75,7 @@ static BOOL vpAddInnerRenderDisplayToServer(id server) {
@"kCAVirtualDisplayUpdateRate": @60, @"kCAVirtualDisplayName": vpInnerDisplayName,
}];
if (!display) { vpFoldDisplayLog(@"inner display: initializer returned nil"); return NO; }
+ vpSetInnerDisplayProMotionMode(display);
((void (*)(id, SEL, id))objc_msgSend)(server, sel_registerName("addDisplay:"), display);
SEL setEnabled = sel_registerName("setEnabled:");
Method enable = class_getInstanceMethod(object_getClass(display), setEnabled);
diff --git a/VPhoneGuestComponents/FoldDisplay/FoldDisplayPanel.m b/VPhoneGuestComponents/FoldDisplay/FoldDisplayPanel.m
index 00f06878..11575b99 100644
--- a/VPhoneGuestComponents/FoldDisplay/FoldDisplayPanel.m
+++ b/VPhoneGuestComponents/FoldDisplay/FoldDisplayPanel.m
@@ -173,6 +173,8 @@ static int vpInnerPanelShown;
static BOOL vpInnerPanelRendering; // main thread only
static dispatch_queue_t vpInnerPanelQueue;
static void (*vpRenderDisplay)(mach_port_t, CFStringRef, void *, int32_t, int32_t);
+// CAFrameRateRange: minimum, maximum, preferred.
+typedef struct { float minimum, maximum, preferred; } VPhoneFrameRateRange;
@interface VPhoneInnerPanelRefresh : NSObject
@end
@@ -292,11 +294,17 @@ static void vpShowInnerDisplay(BOOL shown) {
vpInnerPanelImage = image;
vpInnerPanelRefresh = ((id (*)(id, SEL, id, SEL))objc_msgSend)(objc_getClass("CADisplayLink"),
sel_registerName("displayLinkWithTarget:selector:"), [VPhoneInnerPanelRefresh new], @selector(refresh:));
+ // The panel shows the inner display at the panel's top rate, asked for
+ // rather than left to the system's choice for a link with no range.
+ NSInteger fps = ((NSInteger (*)(id, SEL))objc_msgSend)(vpReadObject(rootWindow, "screen"), sel_registerName("maximumFramesPerSecond"));
+ SEL setRange = sel_registerName("setPreferredFrameRateRange:");
+ if (fps > 60 && [vpInnerPanelRefresh respondsToSelector:setRange])
+ ((void (*)(id, SEL, VPhoneFrameRateRange))objc_msgSend)(vpInnerPanelRefresh, setRange, (VPhoneFrameRateRange){fps, fps, fps});
((void (*)(id, SEL, id, id))objc_msgSend)(vpInnerPanelRefresh, sel_registerName("addToRunLoop:forMode:"),
NSRunLoop.mainRunLoop, NSRunLoopCommonModes);
- vpFoldDisplayLog([NSString stringWithFormat:@"inner display: shown=1 panel={%.0f, %.0f} inner={%.0f, %.0f} turned=%d scale={%.3f, %.3f}",
+ vpFoldDisplayLog([NSString stringWithFormat:@"inner display: shown=1 panel={%.0f, %.0f} inner={%.0f, %.0f} turned=%d scale={%.3f, %.3f} fps=%ld",
panel.size.width, panel.size.height, inner.width, inner.height, turned,
- panel.size.width / upright.width, panel.size.height / upright.height]);
+ panel.size.width / upright.width, panel.size.height / upright.height, (long)fps]);
} @catch (NSException *exception) {
vpFoldDisplayLog([NSString stringWithFormat:@"inner display: show exception %@", exception.reason]);
}