Run a virtual iPhone on an Apple Silicon Mac.
Swift
Wake a dark guest screen on a tap, without unlocking it
Jacky10a71f4f05e5
diff --git a/Research/Guest/screen_unlock.md b/Research/Guest/screen_unlock.mdindex 1f74b5e9..42bd33b6 100644--- a/Research/Guest/screen_unlock.md+++ b/Research/Guest/screen_unlock.md@@ -170,6 +170,41 @@ work would mean changing how the guest's keystore is provisioned at restoreand boot, which this note does not attempt. Until then a passcode guestcannot be made, and `screen.unlock`'s passcode path cannot be run.+## Tap to wake++A phone's touch controller reports a tap on a dark screen as a wake gesture,+and SpringBoard lights the Lock Screen for it. The VM's touchscreen has no+such gesture, so a click in the window on a dark guest did nothing.++vphoned (`vp_tap_to_wake_start` in `vphoned_unlock.m`,+`GuestScreenUnlock.startTapToWake`) watches+`com.apple.springboard.hasBlankedScreen`. While it is set, an+`IOHIDEventSystemClient` of the monitor type (vphoned has+`com.apple.private.hid.client.event-monitor`) sees every HID event, and a+digitizer event with `kIOHIDEventFieldDigitizerTouch` set (at most one every+half second) wakes the screen:++1. `SBSUndimScreen`.+2. If the screen is still dark 0.5 s later, one side-button press+ (consumer `0x30`), at most one every 1.5 s so two never make a Wallet+ double-click. On a dark screen the side button only wakes it.++Home is never pressed, so the guest stays on its Lock Screen. The client is+released when the notify state clears. It works for every touch source the+guest's HID system sees: the VM window, a Launchpad viewer, `input.tap`.+backboardd itself drops the waking touch (`ignoring touch event ((backlight+dim/off))`), so the tap never reaches what is under it.++On iOS 27.1 (24A94425, `waketest-iphone`, 2026-10-29) SpringBoard refuses+`SBSUndimScreen` from vphoned: `_SBXXDimScreen Authentication failed:+Process lacks credentials to access this resource.` So step 2 is what lights+the screen there, and on that build `screen.unlock` and icli's `wake` light+it only through their Home-press fallback. Which entitlement the MIG+handler checks has not been looked up.++The Controls panel's Wake button is different: it is icli's `wake`, which+presses Home after `SBSUndimScreen` until a passcode-free guest is unlocked.+## Not yet measured- **Passcode guests.** vphone does not support a passcode (see "Why adiff --git a/VPhoneDaemon/Daemon/GuestScreenUnlock.swift b/VPhoneDaemon/Daemon/GuestScreenUnlock.swiftindex d4e99c09..3354e3c5 100644--- a/VPhoneDaemon/Daemon/GuestScreenUnlock.swift+++ b/VPhoneDaemon/Daemon/GuestScreenUnlock.swift@@ -62,6 +62,48 @@ enum GuestScreenUnlock {]}+ // MARK: - Tap to Wake++ /// How long SpringBoard gets to light the screen for `SBSUndimScreen`+ /// before the side button is pressed instead.+ private static let undimWait = 0.5+ /// Two side-button presses this close together open Wallet.+ private static let sidePressInterval = 1.5+ private static let tapToWakeQueue = DispatchQueue(label: "vphoned.tap-to-wake", qos: .userInteractive)+ /// Owned by `tapToWakeQueue`.+ private nonisolated(unsafe) static var lastSidePress = Date.distantPast++ /// Lights the Lock Screen when a finger lands on a dark screen, and+ /// leaves it locked. `SBSUndimScreen` is tried first; SpringBoard refuses+ /// it on iOS 27.1 (`_SBXXDimScreen Authentication failed`), so a screen+ /// still dark half a second later gets one side-button press, which on a+ /// dark screen only wakes it. Home is never pressed: on a lit Lock Screen+ /// without a passcode it unlocks.+ static func startTapToWake() {+ vp_tap_to_wake_start {+ GuestScreenUnlock.tapToWakeQueue.async { GuestScreenUnlock.wakeForTap() }+ }+ }++ /// The log messages are literals: arguments come back `<private>` in the+ /// guest log.+ private static func wakeForTap() {+ _ = vp_screen_undim()+ tapToWakeQueue.asyncAfter(deadline: .now() + undimWait) {+ guard state().screenOff else {+ NSLog("vphoned: tap to wake: SBSUndimScreen lit the screen")+ return+ }+ guard Date().timeIntervalSince(lastSidePress) >= sidePressInterval else { return }+ lastSidePress = Date()+ if (try? pressButton("power")) != nil {+ NSLog("vphoned: tap to wake: still dark after SBSUndimScreen, pressed the side button")+ } else {+ NSLog("vphoned: tap to wake: still dark after SBSUndimScreen, the side button press failed")+ }+ }+ }+// MARK: - Lock Screenprivate static func unlock(hasPasscode: Bool, passcode: String?, deadline: Date) throws {diff --git a/VPhoneDaemon/Daemon/main.swift b/VPhoneDaemon/Daemon/main.swiftindex 2fef2811..9ef8132a 100644--- a/VPhoneDaemon/Daemon/main.swift+++ b/VPhoneDaemon/Daemon/main.swift@@ -33,6 +33,8 @@ GuestHomePodDisplay.startOnStartup()// Multi-finger injection is resolved here so the first pinch is not the call// that pays for `dlopen`; a base without the symbols logs and stays a no-op._ = vp_hid_load()+// The VM's touchscreen has no wake gesture; a tap on a dark screen lights it.+GuestScreenUnlock.startTapToWake()GuestIrisinInstaller.refreshBootstrapOnStartup()GuestAPI.restoreUSBSerialOnStartup()GuestStaticNames.shared.restoreOnStartup()diff --git a/VPhoneDaemon/Native/Include/VphonedNative.h b/VPhoneDaemon/Native/Include/VphonedNative.hindex bdc0b065..ddb19570 100644--- a/VPhoneDaemon/Native/Include/VphonedNative.h+++ b/VPhoneDaemon/Native/Include/VphonedNative.h@@ -115,6 +115,10 @@ void vp_hid_touch_edge(int phase, double x, double y, int edge);/// Turn the display on without pressing a button. False when/// SpringBoardServices has no SBSUndimScreen.bool vp_screen_undim(void);+/// Call `touched` on a private queue when a finger lands on the screen while+/// SpringBoard has it blanked, at most every half second: the tap a phone's+/// touch controller reports as a wake gesture.+void vp_tap_to_wake_start(void (* _Nonnull touched)(void));bool vp_device_pose_set(int deviceOrientation, int hingeState, int tabletopPose);/// Ask launchd to shut the guest down and halt. Returns 0 once the request isdiff --git a/VPhoneDaemon/Native/vphoned_unlock.m b/VPhoneDaemon/Native/vphoned_unlock.mindex ba56140a..a8475b42 100644--- a/VPhoneDaemon/Native/vphoned_unlock.m+++ b/VPhoneDaemon/Native/vphoned_unlock.m@@ -13,6 +13,7 @@#import "Include/VphonedNative.h"#include <dlfcn.h>+#include <notify.h>bool vp_screen_undim(void) {static void *handle;@@ -25,3 +26,107 @@ bool vp_screen_undim(void) {undim();return true;}++// MARK: - Tap to wake++/*+ * A phone's touch controller reports a tap on a dark screen as a wake gesture,+ * and SpringBoard lights the Lock Screen for it. The VM's touchscreen has no+ * such gesture, so a tap there did nothing: backboardd drops touches while+ * the backlight is off. While SpringBoard reports the screen blanked, a+ * monitor client watches the HID event system for a digitizer touch and+ * reports it to `touched`, which lights the screen (GuestScreenUnlock).+ *+ * The client exists only while the screen is dark: SpringBoard posting that+ * the screen is lit again ends it. A canceled client cannot be scheduled+ * again, so each dark period gets its own.+ */++typedef void *VPHIDClientRef;+typedef void *VPHIDEventRef;+typedef void (*VPHIDEventCallback)(void *target, void *refcon, void *sender, VPHIDEventRef event);++// kIOHIDEventSystemClientTypeMonitor.+#define VP_HID_CLIENT_MONITOR 1+#define VP_HID_EVENT_DIGITIZER 11u+// kIOHIDEventFieldDigitizerTouch: (kIOHIDEventTypeDigitizer << 16) | 9.+#define VP_FIELD_DIGITIZER_TOUCH ((VP_HID_EVENT_DIGITIZER << 16) | 9u)++static VPHIDClientRef (*pCreateWithType)(CFAllocatorRef, int, CFDictionaryRef);+static void (*pRegisterCallback)(VPHIDClientRef, VPHIDEventCallback, void *, void *);+static void (*pSchedule)(VPHIDClientRef, dispatch_queue_t);+static void (*pUnschedule)(VPHIDClientRef, dispatch_queue_t);+static uint32_t (*pEventType)(VPHIDEventRef);+static long (*pEventInteger)(VPHIDEventRef, uint32_t);++static dispatch_queue_t gTapWakeQueue;+static int gBlankedToken;+// Owned by gTapWakeQueue.+static VPHIDClientRef gTapWakeMonitor;+static uint64_t gTapWakeLast;+static void (*gTapWakeTouched)(void);++static void stop_monitor(void) {+ if (!gTapWakeMonitor) return;+ pUnschedule(gTapWakeMonitor, gTapWakeQueue);+ CFRelease(gTapWakeMonitor);+ gTapWakeMonitor = NULL;+}++static void tap_wake_event(void *target, void *refcon, void *sender, VPHIDEventRef event) {+ (void)target;+ (void)refcon;+ (void)sender;+ if (pEventType(event) != VP_HID_EVENT_DIGITIZER || pEventInteger(event, VP_FIELD_DIGITIZER_TOUCH) == 0) return;+ // A finger that stays down reports touch on every move. One wake per half+ // second is enough, and a later tap tries again if the screen stayed dark.+ uint64_t now = clock_gettime_nsec_np(CLOCK_UPTIME_RAW);+ if (now - gTapWakeLast < 500 * NSEC_PER_MSEC) return;+ gTapWakeLast = now;+ gTapWakeTouched();+}++static void update_monitor(void) {+ uint64_t blanked = 0;+ notify_get_state(gBlankedToken, &blanked);+ if (!blanked) {+ stop_monitor();+ return;+ }+ if (gTapWakeMonitor) return;+ gTapWakeMonitor = pCreateWithType(kCFAllocatorDefault, VP_HID_CLIENT_MONITOR, NULL);+ if (!gTapWakeMonitor) {+ NSLog(@"vphoned: tap to wake: no HID monitor client");+ return;+ }+ pRegisterCallback(gTapWakeMonitor, tap_wake_event, NULL, NULL);+ pSchedule(gTapWakeMonitor, gTapWakeQueue);+}++void vp_tap_to_wake_start(void (*touched)(void)) {+ gTapWakeTouched = touched;+ void *ioKit = dlopen("/System/Library/Frameworks/IOKit.framework/IOKit", RTLD_NOW);+ if (ioKit) {+ pCreateWithType = dlsym(ioKit, "IOHIDEventSystemClientCreateWithType");+ pRegisterCallback = dlsym(ioKit, "IOHIDEventSystemClientRegisterEventCallback");+ pSchedule = dlsym(ioKit, "IOHIDEventSystemClientScheduleWithDispatchQueue");+ pUnschedule = dlsym(ioKit, "IOHIDEventSystemClientUnscheduleFromDispatchQueue");+ pEventType = dlsym(ioKit, "IOHIDEventGetType");+ pEventInteger = dlsym(ioKit, "IOHIDEventGetIntegerValue");+ }+ if (!pCreateWithType || !pRegisterCallback || !pSchedule || !pUnschedule || !pEventType || !pEventInteger) {+ NSLog(@"vphoned: tap to wake: HID monitor symbols missing");+ return;+ }+ gTapWakeQueue = dispatch_queue_create("com.vphone.vphoned.tap-wake", DISPATCH_QUEUE_SERIAL);+ uint32_t status = notify_register_dispatch("com.apple.springboard.hasBlankedScreen", &gBlankedToken,+ gTapWakeQueue, ^(int token) {+ (void)token;+ update_monitor();+ });+ if (status != NOTIFY_STATUS_OK) {+ NSLog(@"vphoned: tap to wake: cannot observe the screen (notify status %u)", status);+ return;+ }+ dispatch_async(gTapWakeQueue, ^{ update_monitor(); });+}