Skip to content

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.md
index 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 restore
and boot, which this note does not attempt. Until then a passcode guest
cannot 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 a
diff --git a/VPhoneDaemon/Daemon/GuestScreenUnlock.swift b/VPhoneDaemon/Daemon/GuestScreenUnlock.swift
index 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 Screen
private static func unlock(hasPasscode: Bool, passcode: String?, deadline: Date) throws {
diff --git a/VPhoneDaemon/Daemon/main.swift b/VPhoneDaemon/Daemon/main.swift
index 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.h
index 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 is
diff --git a/VPhoneDaemon/Native/vphoned_unlock.m b/VPhoneDaemon/Native/vphoned_unlock.m
index 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(); });
+}