Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Document the Always On display answers

Marvae6fbf93d229ef
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index b8cf435b..d3133efd 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -5993,3 +5993,80 @@ vertex outputs, render targets); an argument kind the reflection reads in a
layout the completion does not produce could still crash the compiler
service. With primitive restart no longer sent, an OpenGL ES 2 strip that draws
vertex 65535 is cut there.
+
+## Always On display (2026-11-02)
+
+No new patch identifier and no new bytes in an Apple binary.
+`preboot-cfw-devicetree_iphone_product` (the iPhone product repair, which `cfw
+install` and `cfw update-environment` run) also adds
+`/product/vphone-always-on-display = 1` when the board's own tree has
+`/arm-io/disp0` `always-on-time`. MobileGestalt reads nothing by that name.
+vphoned reads it at startup and answers DeviceSupportsAlwaysOnDisplay
+(`2OOJf1VhaM7NxfRok3HbWQ`) and DeviceSupportsAlwaysOnTime
+(`j8/Omm6s1lsmTDFsXjsBfA`) yes in the MobileGestalt cache's `CacheExtra`
+(`GuestMobileGestaltAnswers`, `GuestMobileGestaltCache.presentAlwaysOnDisplayOnStartup`).
+Settings then offers Always On Display and SpringBoard dims the Lock Screen
+instead of turning it off. Issue #650.
+
+**Why not the tree.** libMobileGestalt (24A446) answers the three questions from
+one node:
+
+| Answer | Source |
+| --- | --- |
+| DeviceSupportsAlwaysOnTime | `IODeviceTree:/arm-io/disp0` `always-on-time` |
+| DeviceSupportsAlwaysOnDisplay | AlwaysOnTime, else `disp0` `always-on-device` |
+| DeviceSupportsAlwaysOnDisplayFlipbook | AlwaysOnTime, else `disp0` `always-on-device-flipbook` |
+
+Settings shows the row only with AlwaysOnTime (DisplayAndBrightnessSettings
+asks for it; with AlwaysOnDisplay alone there is no row, measured). The board's
+`always-on-time` therefore answers the flipbook yes too. CoreBrightness reads it
+in backboardd (`-[CBAODState initializeAODSupportConfiguration]`) and drives the
+flipbook through the panel controller (DCP), which the paravirtual panel does
+not have. An iPhone18,1 27.0.1 guest with an `/arm-io/disp0` stub carrying the
+board's `always-on-time` lost backboardd at every boot (`rebooting due to
+critical process crashes: backboardd`) and launchd restarted it into the device
+recovery environment. A second guest made without the stub booted, and
+answering all three yes in its `CacheExtra` crashed it the same way. Without
+the flipbook, `-[BLSHBacklightOSInterfaceProvider initWithPlatformProvider:]`
+gives SpringBoard BacklightServices' own renderer (`BLSHPseudoFlipbook`), which
+works on a guest. Answering the first two in the cache leaves the flipbook
+unanswered there and so no.
+
+A guest that went through that crash loop kept losing backboardd after the
+answers and the whole cache were removed; the cause was not found. Do not
+test the flipbook answer on a VM you want to keep.
+
+**When the answers land.** libMobileGestalt writes the cache when a process
+first asks after it is gone: at a guest's first boot, and after vphoned drops a
+cache older than the tree. vphoned waits for it (up to 10 minutes), adds the
+answers once, and sets `mobilegestalt_restart_pending`; the cache keeps them
+across boots, and a rebuilt cache gets them again at the next start. A new
+machine's creation boots more than once, so it is offered from its first use.
+
+**The window.** On a foldable guest the VM window covers the panel while
+`display.orientation` says `screen_off`, so a waking panel does not show its
+frame from before (`bde6440c`). SpringBoard posts `hasBlankedScreen` for the
+always-on Lock Screen too, so the window covered it. FoldDisplay now publishes
+whether the panel went off since SpringBoard last lit the screen
+(`com.vphone.folddisplay.panel-dark`: 1 stayed on, 2 went off), and
+`screen_off` is SpringBoard's blank and that.
+
+**Verified.**
+- New machine: iPhone18,1 27.0.1, cloudOS 26.4, bundle from this branch on
+ 2.14.2. `cfw install` logged `product/vphone-always-on-display: 'absent' ->
+ '01000000'`; with nothing done by hand, the cache had both answers yes and the
+ flipbook unanswered, Settings showed Always On Display On, and the locked
+ screen stayed dimmed with the clock moving (9:34 to 9:36). No backboardd crash.
+- Existing machine: iPhone19,4 27.1 (24A94425), `vm set-bundle
+ --update-environment`. The repair added the marker; the next boot dropped the
+ cache, the rebuilt one got the answers and the restart was reported pending;
+ after the restart the Lock Screen went always-on, the panel state stayed 1,
+ `screen_off` false, and the VM window showed it. With Always On Display
+ switched off in Settings the panel went off (state 2), `screen_off` was true
+ and the window covered it, then uncovered it on wake.
+
+**Not covered.** Other iPhones with the display were not run. Apple Watch:
+N227b's tree has `always-on-time` too, but on a Watch7,18 26.4 guest the same two
+answers left the screen fully dark after the timeout (Carousel decides; not
+investigated), so the repair stays iPhone-only. No iPad board has the property.
+The VM keeps rendering while dimmed: there is no low-power display.
diff --git a/Research/vphoned_http_api.md b/Research/vphoned_http_api.md
index 70556670..495f1558 100644
--- a/Research/vphoned_http_api.md
+++ b/Research/vphoned_http_api.md
@@ -497,7 +497,7 @@ request carries `"force": true`.
| Area | Methods |
| --- | --- |
| Device | `device.snapshot`, `device.info` (snapshot plus network, screen, rotation, brightness, volume, low power, Developer Mode, agent, `device_name` `{name, own_name}`: the pinned name and the guest's own ComputerName), `device.screen`, `device.network`, `device.displays` (a flat IOService probe of every display-ish object with its small properties — what the display stack bound; built for the foldable display work: `AppleParavirtGPU` `DisplayPortCount`, and each `AppleParavirtDisplay` width/height/`primary`), `device.ioreg {plane}`, `device.environment`, `device.basebin {archive?}` |
-| Display, audio | `display.pose` (read-only SpringBoard pose snapshot: orientation, device_orientation, hinge, tabletop; reports unavailable for an unsupported ABI), `display.modes` (read-only CoreAnimation display bounds, native size, current/available modes, and virtual-mode selector availability; availability does not prove a mode change is supported), `display.brightness {value?}`, `display.rotation {orientation?}`, `display.posture {hinge, orientation?, tabletop?}` (a foldable guest's pose through SpringBoard's test-automation override, see below; capability `device_pose`), `display.orientation` (`{degrees, source, fold_angle?, screen_off?}`: SpringBoard's interface orientation without a screen capture, for polling; `degrees` is null while SpringBoard has no answer; on a foldable `fold_angle` is the virtual hinge's angle, so a host can follow folds it did not ask for, and `screen_off` whether SpringBoard has the screen off, so a host can keep the panel's frame from before off its window as it comes on; capability `display_orientation`), `display.rotation_lock {locked}`, `display.auto_lock` (`{auto_lock_seconds, never, lock_screen_minimum_seconds}`), `display.auto_lock.set {seconds}` (writes the mobile UserSettings input through cfprefsd, posts profiled's effective-settings notification, and returns an immediate readback; the caller must verify the effective value), `screen.unlock {passcode?, timeout?}` (`{locked, screen_off, was_locked, was_screen_off}`: the display on and the Lock Screen passed, see below; capability `screen_unlock`), `audio.volume {value?, category?}`, `audio.state` |
+| Display, audio | `display.pose` (read-only SpringBoard pose snapshot: orientation, device_orientation, hinge, tabletop; reports unavailable for an unsupported ABI), `display.modes` (read-only CoreAnimation display bounds, native size, current/available modes, and virtual-mode selector availability; availability does not prove a mode change is supported), `display.brightness {value?}`, `display.rotation {orientation?}`, `display.posture {hinge, orientation?, tabletop?}` (a foldable guest's pose through SpringBoard's test-automation override, see below; capability `device_pose`), `display.orientation` (`{degrees, source, fold_angle?, screen_off?}`: SpringBoard's interface orientation without a screen capture, for polling; `degrees` is null while SpringBoard has no answer; on a foldable `fold_angle` is the virtual hinge's angle, so a host can follow folds it did not ask for, and `screen_off` whether the panel is dark, so a host can keep the panel's frame from before off its window as it comes on (SpringBoard has the screen off and FoldDisplay saw the panel go off since it was last lit; the always-on Lock Screen keeps the panel on and is not dark); capability `display_orientation`), `display.rotation_lock {locked}`, `display.auto_lock` (`{auto_lock_seconds, never, lock_screen_minimum_seconds}`), `display.auto_lock.set {seconds}` (writes the mobile UserSettings input through cfprefsd, posts profiled's effective-settings notification, and returns an immediate readback; the caller must verify the effective value), `screen.unlock {passcode?, timeout?}` (`{locked, screen_off, was_locked, was_screen_off}`: the display on and the Lock Screen passed, see below; capability `screen_unlock`), `audio.volume {value?, category?}`, `audio.state` |
| Input | `input.touch`, `input.hid {page, usage, down?, long_press?}`, `input.button {name}`, `input.key {name}`, `input.type {text, delay_ms?}`, `input.paste {text}`, `input.tap`, `input.double_tap`, `input.long_press`, `input.swipe`, `input.drag {points}`, `input.touch_sequence {events}` — gesture coordinates are screen points; `input.pointer {x, y, seq?, buttons?}`, `input.scroll {phase, dx?, dy?, x?, y?}` (capabilities `pointer_scroll` and `pointer_buttons`, see below) |
| UI | `ui.tree` (alias `accessibility.tree`), `ui.element_at`, `ui.tap_element`, `ui.wait`, `ui.wait_gone`, `ui.ocr {languages?, min_confidence?}`, `ui.describe`, `screen.screenshot` |
| Processes | `processes.list {filter?}`, `processes.kill {pid, signal?}` **force**, `process.spawn {executable, arguments?, timeout_seconds?}`, `memory.jetsam`, `memory.pressure` (only the three kernel memory sysctls, for polling) |
@@ -582,6 +582,16 @@ the answers they read, so the field is true from that removal until the guest
restarts, also across a vphoned restart in the same boot; vphoned does not
restart the guest itself. See `Research/Guest/virtio_sound.md` §7.
+On an iPhone whose board has an Always On display, vphoned then answers
+DeviceSupportsAlwaysOnDisplay and DeviceSupportsAlwaysOnTime yes in that
+cache's `CacheExtra`. `cfw install` and `cfw update-environment` mark such a
+board with `/product/vphone-always-on-display` (the iPhone product repair);
+vphoned waits for libMobileGestalt to write the cache, adds the two answers
+once, and sets `mobilegestalt_restart_pending` as for a removal. The tree cannot
+carry the answers itself: the board's `/arm-io/disp0` `always-on-time` also
+answers the display flipbook yes, which the paravirtual panel cannot do (see
+`Research/0_binary_patch_comparison.md`, "Always On display").
+
At startup vphoned also stores `ProductIDOverride` 8010 in
`com.apple.audio.virtualaudio` for user mobile, on an iPad or iPhone guest
that has the sound plugin (`VPhoneDaemon/Daemon/GuestVirtualAudioProduct.swift`).