Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Implement HomePod display emulation

Guilherme Rambo0b3f341704bc
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 4fa06358..8ddc5701 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -1,5 +1,29 @@
# Patch Comparison: Regular / Development / Jailbreak / Experimental
+> **HomePod top cap (2026-10-22).** `system-homepod-exp-top_cap` installs
+> `/usr/share/vphone/HomePodDisplay.plist`, extracted from the selected board's
+> `/arm-io/dockchannel-rtp/rtp-transport/display` node. It preserves the donor's
+> `MDXCoords`, `MDYCoords`, `MDRingCoords`, `MDBitDepth` and `MDHWVersion` payloads
+> for vphoned's virtual MiniDisplay HID device. Only `homepod-mini` selects it
+> by default; the installer rejects other guest families and missing or invalid
+> donor metadata. Both full installation and environment updates stage it through
+> confined descriptors; deselecting removes this added configuration and its
+> receipt entry. It also installs `libvphonehomepoddisplay.dylib` only into
+> SoundBoard through an `LC_LOAD_WEAK_DYLIB` in its backed-up executable, preserving
+> its entitlements and resealing its app bundle. launchd strips `DYLD_*`
+> environment variables from this platform process, so both the standalone
+> daemon plist and launchd cache are cleaned of the earlier environment route
+> while preserving their other keys and inserted libraries.
+> `IOHIDUserDevice` reserves `IOClass`;
+> the shim adapts MiniDisplay's discovery callback and class-identity query only
+> for the exact virtual display ID. On a failed submission it can replace that
+> virtual handle after vphoned restarts, retrying the same native frame and
+> throttling device enumeration to once per second. Other devices retain their
+> original failure behavior. LED reports still traverse the native HID device. Deselecting
+> restores the original SoundBoard executable from `.bak`, reseals the app,
+> and deletes the library. The VM retains its virtual hardware tree.
+> No instruction patch is added.
+
> **HomePod mini (2026-10-22).** `AudioAccessory5,1` / B520 uses its own
> HomePod Software 27.0 (24J361) monolithic arm64e TVOS IPSW with the cloudOS
> 26.4 boot chain. The dedicated `homepod-mini` preset retains 27 compatibility
diff --git a/Research/Firmware/homepod_mini_support.md b/Research/Firmware/homepod_mini_support.md
index 804a5fa6..50780e6a 100644
--- a/Research/Firmware/homepod_mini_support.md
+++ b/Research/Firmware/homepod_mini_support.md
@@ -115,5 +115,113 @@ process lists and boot results); its console is
`~/Library/Logs/vphone-launchpad/homepod-mini.log`.
Audio output and microphone capture, Siri, AirPlay playback, activation and
-pairing with the Home app have not been validated. The host's diagnostic
-canvas does not establish a usable graphical HomePod interface.
+pairing with the Home app have not been validated. The top-cap UI described
+below replaces the diagnostic framebuffer for interactive HomePod windows.
+
+## Top-cap display
+
+The HomePod preset additionally selects `system-homepod-exp-top_cap`. On a
+stopped existing machine, `cfw update-environment` installs this device without
+a restore, recovering its metadata from the retained original board tree.
+Disabling the patch removes the configuration and adapter and restores the
+backed-up SoundBoard executable. Other presets leave this device off.
+
+The donor node `/arm-io/dockchannel-rtp/rtp-transport/display` supplies 19 RGB
+positions: twelve outer LEDs, six inner LEDs and one center LED, at 12-bit
+depth and hardware version 3. `MDXCoords` and `MDYCoords` are unsigned
+little-endian Q16.16 positions in the full cap's unit square; their unpopulated
+rim must not be stretched away. `MDRingCoords` contains integer ring indices.
+The installer retains these five raw properties in
+`/usr/share/vphone/HomePodDisplay.plist`; the host has no hardcoded LED layout.
+
+MiniDisplay matches consumer HID usage page 12, usage 1. Its report 2 is a
+packed 245-byte output report: one-byte report ID, eight-byte mach timestamp,
+then two 118-byte banks, each with two UInt16 icon words and nineteen RGB
+UInt16 triples. All multi-byte values are little endian. Bank 0 contains
+Siri/transient output, bank 1 the always-on layer; the volume icons use bank
+0's two words. Peppy expands the physical depth to a 16-bit wire range;
+RGB and icon words both scale by 65535, independently of the 12-bit tree value.
+Its initializer reads `kMDDisplayMaxBitDepth` (16) at 0x1a6a3787c, and
+`submitPixelBuffer` computes the shift from the physical depth at 0x1a69dbda8.
+HomePodDisplayService
+already applies brightness and gamma before submitting frames. The property
+named `MDDisplayBrightness` controls driver processing, not master intensity.
+
+These observations come from this IPSW's MiniDisplay and
+HomePodDisplayService shared-cache images, extracted with relocation and ObjC
+metadata repair. Their extracted SHA-256 values are respectively
+`26d787575f4292a496cae7f9e341ae53134a8b482d4d23c5c970ea65a5828157` and
+`a958fb05e8f2b4774a2542256bfe803a078f3574adf9cdad96a7468d56ce2354`.
+Reveal points are `MDInterfaceHID._readRegistryProperties` (0x1fb5f56b0),
+`displayCount` (0x1fb5f4160), `deviceAdded:` (0x1fb5f3f88),
+`MDFrame.initWithInterface:pixelInfo:` (0x1fb5f31b8),
+`HPDSLEDController._processBrightness:` (0x1a69d9cb0) and
+`Peppy.submitPixelBuffer` (0x1a69dba30). Analysis and runtime artifacts are
+under `.build/homepod-ui-research/`.
+
+vphoned publishes an `IOHIDUserDevice` with that metadata, receives the native
+output reports, and exposes the latest immutable snapshot through
+`homepod.display.state`. MiniDisplay tests the reserved `IOClass` property in
+both discovery and property reads. A guest probe confirmed that the virtual
+HID API accepts this descriptor but rejects an `IOClass` override; setting it
+after creation returns unsupported (`0xe00002c7`). The SoundBoard-only adapter
+therefore recognizes exactly `vphone-homepod-mini-display`, performs the normal
+retain/open/semaphore discovery sequence using ObjC runtime ivars, and supplies
+the MiniDisplay class identity for that device. Other devices and other property
+reads retain the original implementations. A failed frame submission on that
+virtual handle triggers immediate HID enumeration, throttled to once per second,
+and retries the original frame on a replacement device. This handles vphoned
+restarts; the native interface otherwise retains its stale handle indefinitely.
+The original `submitFrame:error:` (0x1fb5f2ff8) forwards `IOHIDDeviceSetReport`
+errors, and `_findDevice` returns early while `_device` is non-null. Recovery
+does not call `_findDevice`, whose absent-device wait can block for 30 seconds.
+Frame generation and native report submission remain Apple's. The adapter uses
+a signed load command in SoundBoard and
+preserves its original entitlements.
+
+The Mac window displays a circular diffuser, adding both guest light layers and
+clamping emitted intensity. Its diffuser, color response and layer composition
+are visual approximations; the exact optical/hardware composition is not
+established by the inspected userspace code. Delivery keeps one snapshot request
+in flight at up to 60 Hz, drops intermediate frames, blanks on connection loss,
+and pauses requests while minimized. No host animation substitutes for output.
+The accessible +/- controls send consumer volume HID down/up (0xE9/0xEA),
+including holds and immediate releases on focus loss. Quick taps last at least
+700 ms after the guest acknowledges key-down. Timing from the mouse event can
+collapse a tap's down/up into adjacent RPCs when input delivery is delayed.
+This preserves a usable consumer-key hold for instantaneous mouse/AX taps.
+The center touch surface has no
+input mapping yet and is excluded from accessibility/tab navigation.
+
+### Top-cap validation (2026-10-22)
+
+- The full `VPhone` bundle builds, passes its admission phase and passes
+ `codesign --verify --deep --strict`. Xcode MCP runs passed 39 selected
+ firmware/patch-selection tests and all eight `HomePodDisplayTests`.
+ `VPhoneDaemon/Tests/run-homepod-display-tests.sh` checks report boundaries,
+ both banks, icon channels and full 16-bit normalization. The guest-component
+ identity harness checks virtual-device discovery, ordinary property/error
+ forwarding, duplicate discovery, replacement after failure and retry throttling.
+- On HomePod Software 27.0 (24J361), SoundBoard submits native report 2 with
+ length 245, nineteen RGB entries per bank and zero rejected reports. The Mac
+ cap visibly follows its white volume HUD and independently lit +/- channels.
+ Held clicks change the guest's `Audio/Video` volume in both directions.
+ A trace of 1 ms mouse clicks confirmed paired RPCs with at least 700 ms
+ between key-down acknowledgement and key-up. Two such clicks per button
+ changed volume from 0.48 to 0.58 and back to 0.48. Initial individual presses
+ sometimes lit the HUD without changing volume despite valid input delivery;
+ the cause inside the guest has not been established. No host-side volume
+ setter substitutes for HID input. The native-button probe also verifies
+ paired transitions from standard button and accessibility actions.
+- Killing/restarting `com.vphone.vphoned` recreates the HID device. With the
+ recovery adapter installed, native reports resume without restarting
+ SoundBoard or the VM; an additional volume press produces another report.
+- A complete opt-out/update/boot cycle reported an unconfigured display,
+ removed SoundBoard's added load command, and preserved its original
+ entitlements byte for byte. Restoring the original HomePod preset and updating
+ the guest environment brought the display back. The saved patch selection
+ before and after that cycle is identical.
+
+Runtime artifacts for these checks are under `.build/homepod-ui-research/`.
+Siri activation and its multicolor animations remain unvalidated; report and
+renderer tests exercise RGB channels without claiming those services work.
diff --git a/VPhoneDaemon/Daemon/GuestAPI+Extended.swift b/VPhoneDaemon/Daemon/GuestAPI+Extended.swift
index 4a4d257a..a3a18e25 100644
--- a/VPhoneDaemon/Daemon/GuestAPI+Extended.swift
+++ b/VPhoneDaemon/Daemon/GuestAPI+Extended.swift
@@ -24,6 +24,7 @@ extension GuestAPI {
executeAudioLatency,
executeGyroscope,
executeAttitude,
+ executeHomePodDisplay,
]
for area in areas {
if let result = try area(method, params) {
diff --git a/VPhoneDaemon/Daemon/GuestAPI+HomePodDisplay.swift b/VPhoneDaemon/Daemon/GuestAPI+HomePodDisplay.swift
new file mode 100644
index 00000000..42a4e0a7
--- /dev/null
+++ b/VPhoneDaemon/Daemon/GuestAPI+HomePodDisplay.swift
@@ -0,0 +1,8 @@
+import Foundation
+
+extension GuestAPI {
+ static func executeHomePodDisplay(_ method: String, _ params: [String: Any]) throws -> [String: Any]? {
+ guard method == "homepod.display.state" else { return nil }
+ return try GuestHomePodDisplay.state()
+ }
+}
diff --git a/VPhoneDaemon/Daemon/GuestAPI.swift b/VPhoneDaemon/Daemon/GuestAPI.swift
index 57d707e2..67d2681e 100644
--- a/VPhoneDaemon/Daemon/GuestAPI.swift
+++ b/VPhoneDaemon/Daemon/GuestAPI.swift
@@ -150,7 +150,7 @@ enum GuestAPI {
"motion_gyroscope",
"motion_gyroscope_toggle",
"motion_attitude",
- ] + pointerCapabilities(),
+ ] + pointerCapabilities() + GuestHomePodDisplay.capabilities,
]
}
diff --git a/VPhoneDaemon/Daemon/GuestHomePodDisplay.swift b/VPhoneDaemon/Daemon/GuestHomePodDisplay.swift
new file mode 100644
index 00000000..140cb9e6
--- /dev/null
+++ b/VPhoneDaemon/Daemon/GuestHomePodDisplay.swift
@@ -0,0 +1,26 @@
+import Foundation
+import VphonedNative
+
+/// Publishes MiniDisplay hardware only on firmware that carries its source
+/// device tree geometry. Apple's own display service supplies every frame.
+enum GuestHomePodDisplay {
+ static func startOnStartup() {
+ vp_homepod_display_start()
+ }
+
+ static var capabilities: [String] {
+ vp_homepod_display_is_configured() ? ["homepod_display"] : []
+ }
+
+ static func state() throws -> [String: Any] {
+ guard let json = vp_homepod_display_copy_json() else {
+ throw GuestAPIError.operationFailed("Could not read HomePod display state")
+ }
+ defer { free(json) }
+ let data = Data(bytes: json, count: strlen(json))
+ guard let state = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+ throw GuestAPIError.operationFailed("Invalid HomePod display state")
+ }
+ return state
+ }
+}
diff --git a/VPhoneDaemon/Daemon/main.swift b/VPhoneDaemon/Daemon/main.swift
index 42e147ec..6ea3ac97 100644
--- a/VPhoneDaemon/Daemon/main.swift
+++ b/VPhoneDaemon/Daemon/main.swift
@@ -20,6 +20,7 @@ GuestMobileGestaltCache.dropIfStaleOnStartup()
// Before audiomxd is asked for sound again; see the type for what it cannot cover.
GuestVirtualAudioProduct.storeOnStartup()
vp_vcam_start()
+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()
diff --git a/VPhoneDaemon/Native/Include/VphonedNative.h b/VPhoneDaemon/Native/Include/VphonedNative.h
index 937605a8..c041c418 100644
--- a/VPhoneDaemon/Native/Include/VphonedNative.h
+++ b/VPhoneDaemon/Native/Include/VphonedNative.h
@@ -15,6 +15,12 @@ int vp_native_process_mode(void);
int vp_native_run_proxy(void);
int vp_native_watch_proxy(void);
void vp_vcam_start(void);
+/// Publish the HomePod MiniDisplay HID device when firmware has its geometry.
+/// The device and its callback queue live for the worker process lifetime.
+void vp_homepod_display_start(void);
+bool vp_homepod_display_is_configured(void);
+/// Latest guest-written MiniDisplay frame and geometry, malloc-owned JSON.
+char *vp_homepod_display_copy_json(void);
/// Load the IOKit digitizer symbols used for multi-finger injection. Idempotent,
/// safe to call more than once; returns false (injection then stays a no-op)
diff --git a/VPhoneDaemon/Native/vphoned_homepod_display.m b/VPhoneDaemon/Native/vphoned_homepod_display.m
new file mode 100644
index 00000000..e7538da6
--- /dev/null
+++ b/VPhoneDaemon/Native/vphoned_homepod_display.m
@@ -0,0 +1,194 @@
+#import "Include/VphonedNative.h"
+#import "vphoned_homepod_report.h"
+#import <IOKit/IOKitLib.h>
+#include <dlfcn.h>
+#include <pthread.h>
+
+// IOHIDUserDevice is exported by iOS IOKit, but not declared by its SDK.
+// Signatures follow Apple's IOHIDFamily/IOHIDLib/IOHIDUserDevice.h.
+typedef struct __IOHIDUserDevice *VPHomePodHIDDeviceRef;
+typedef IOReturn (*VPHomePodSetReportCallback)(void *, int, uint32_t, uint8_t *, CFIndex);
+static VPHomePodHIDDeviceRef (*VPHomePodCreate)(CFAllocatorRef, CFDictionaryRef, IOOptionBits);
+static void (*VPHomePodRegisterSetReport)(VPHomePodHIDDeviceRef, VPHomePodSetReportCallback, void *);
+static void (*VPHomePodSchedule)(VPHomePodHIDDeviceRef, dispatch_queue_t);
+
+static pthread_mutex_t VPHomePodLock = PTHREAD_MUTEX_INITIALIZER;
+static VPHomePodHIDDeviceRef VPHomePodDevice;
+static dispatch_queue_t VPHomePodQueue;
+static NSDictionary *VPHomePodGeometry;
+static NSData *VPHomePodFrame;
+static NSString *VPHomePodState = @"unconfigured";
+static NSString *VPHomePodError;
+static NSUInteger VPHomePodLEDCount;
+static NSUInteger VPHomePodDisplayCount;
+static uint32_t VPHomePodBitDepth;
+static uint32_t VPHomePodHardwareVersion;
+static uint64_t VPHomePodFramesReceived;
+static uint64_t VPHomePodRejectedReports;
+static uint32_t VPHomePodLastReportID;
+static CFIndex VPHomePodLastReportLength;
+static BOOL VPHomePodConfigured;
+
+static void VPHomePodSetFailure(NSString *message) {
+ pthread_mutex_lock(&VPHomePodLock);
+ VPHomePodState = @"failed";
+ VPHomePodError = message;
+ pthread_mutex_unlock(&VPHomePodLock);
+ NSLog(@"vphoned: HomePod display: %@", message);
+}
+
+static uint32_t VPHomePodConfigurationWord(NSDictionary *configuration, NSString *key) {
+ NSData *data = configuration[key];
+ if (![data isKindOfClass:NSData.class] || data.length != 4) return 0;
+ return VPHomePodRead32(data.bytes);
+}
+
+static NSArray *VPHomePodCoordinates(NSData *data, BOOL fixedPoint) {
+ NSMutableArray *result = [NSMutableArray arrayWithCapacity:data.length / 4];
+ const uint8_t *bytes = data.bytes;
+ for (NSUInteger index = 0; index < data.length; index += 4) {
+ uint32_t word = VPHomePodRead32(bytes + index);
+ [result addObject:fixedPoint ? @((double)word / 65536.0) : @(word)];
+ }
+ return result;
+}
+
+static IOReturn VPHomePodReceiveReport(void *context, int type, uint32_t reportID,
+ uint8_t *report, CFIndex length) {
+ (void)context;
+ @autoreleasepool {
+ pthread_mutex_lock(&VPHomePodLock);
+ VPHomePodLastReportID = reportID;
+ VPHomePodLastReportLength = length;
+ // The output report includes its report ID in IOHIDDeviceSetReport.
+ // Reject truncated or unexpected reports without disturbing the last frame.
+ if (type != 1 || reportID != 2 || length < 0 ||
+ !VPHomePodValidFrame(report, (size_t)length, VPHomePodLEDCount, VPHomePodDisplayCount)) {
+ VPHomePodRejectedReports++;
+ pthread_mutex_unlock(&VPHomePodLock);
+ return kIOReturnBadArgument;
+ }
+ VPHomePodFrame = [NSData dataWithBytes:report length:(NSUInteger)length];
+ VPHomePodFramesReceived++;
+ VPHomePodState = @"receiving";
+ pthread_mutex_unlock(&VPHomePodLock);
+ return kIOReturnSuccess;
+ }
+}
+
+void vp_homepod_display_start(void) {
+ static dispatch_once_t once;
+ dispatch_once(&once, ^{
+ NSString *path = @"/usr/share/vphone/HomePodDisplay.plist";
+ if (![[NSFileManager defaultManager] fileExistsAtPath:path]) return;
+ VPHomePodConfigured = YES;
+ NSDictionary *configuration = [NSDictionary dictionaryWithContentsOfFile:path];
+ NSData *x = configuration[@"MDXCoords"];
+ NSData *y = configuration[@"MDYCoords"];
+ NSData *rings = configuration[@"MDRingCoords"];
+ uint32_t bitDepth = VPHomePodConfigurationWord(configuration, @"MDBitDepth");
+ uint32_t hardwareVersion = VPHomePodConfigurationWord(configuration, @"MDHWVersion");
+ if (![x isKindOfClass:NSData.class] || x.length == 0 || x.length % 4 != 0 ||
+ ![y isKindOfClass:NSData.class] || y.length != x.length ||
+ ![rings isKindOfClass:NSData.class] || rings.length != x.length ||
+ !bitDepth || bitDepth > 16 || !hardwareVersion || x.length / 4 > 4096) {
+ VPHomePodSetFailure(@"Invalid device tree display geometry");
+ return;
+ }
+ VPHomePodLEDCount = x.length / 4;
+ VPHomePodDisplayCount = hardwareVersion > 2 ? 2 : 1;
+ VPHomePodBitDepth = bitDepth;
+ VPHomePodHardwareVersion = hardwareVersion;
+ VPHomePodGeometry = @{@"x": VPHomePodCoordinates(x, YES), @"y": VPHomePodCoordinates(y, YES),
+ @"rings": VPHomePodCoordinates(rings, NO)};
+ VPHomePodFrame = [NSMutableData dataWithLength:VPHomePodFrameSize(VPHomePodLEDCount, VPHomePodDisplayCount)];
+ void *ioKit = dlopen("/System/Library/Frameworks/IOKit.framework/IOKit", RTLD_NOW);
+ if (ioKit) {
+ VPHomePodCreate = dlsym(ioKit, "IOHIDUserDeviceCreateWithOptions");
+ VPHomePodRegisterSetReport = dlsym(ioKit, "IOHIDUserDeviceRegisterSetReportCallback");
+ VPHomePodSchedule = dlsym(ioKit, "IOHIDUserDeviceScheduleWithDispatchQueue");
+ }
+ if (!VPHomePodCreate || !VPHomePodRegisterSetReport || !VPHomePodSchedule) {
+ VPHomePodSetFailure(@"IOHIDUserDevice APIs are unavailable");
+ return;
+ }
+ // Consumer Control (12, 1) is MiniDisplay's matching dictionary. Each
+ // report's payload is opaque to HID; MiniDisplay owns the layout.
+ NSUInteger payloadLength = VPHomePodFrameSize(VPHomePodLEDCount, VPHomePodDisplayCount) - 1;
+ const uint8_t descriptor[] = {
+ 0x05, 0x0c, 0x09, 0x01, 0xa1, 0x01, 0x85, 0x02,
+ 0x06, 0x00, 0xff, 0x09, 0x01, 0x15, 0x00, 0x26, 0xff, 0x00,
+ 0x75, 0x08, 0x96, (uint8_t)payloadLength, (uint8_t)(payloadLength >> 8), 0x91, 0x02, 0xc0,
+ };
+ NSDictionary *properties = @{
+ @"ReportDescriptor": [NSData dataWithBytes:descriptor length:sizeof(descriptor)],
+ @"Product": @"VPhone HomePod mini Top Cap",
+ @"Manufacturer": @"VPhone", @"Transport": @"Virtual", @"VendorID": @0x05ac,
+ @"ProductID": @0x0001, @"PhysicalDeviceUniqueID": @"vphone-homepod-mini-display",
+ @"DeviceUsagePage": @12, @"DeviceUsage": @1,
+ @"MDHWVersion": @(hardwareVersion),
+ @"MDXCoords": x, @"MDYCoords": y, @"MDRingCoords": rings, @"MDBitDepth": @(bitDepth),
+ };
+ VPHomePodQueue = dispatch_queue_create("vphoned.homepod-display.hid", DISPATCH_QUEUE_SERIAL);
+ // StartWhenScheduled keeps clients from sending their first frame before
+ // the set-report callback is registered and its queue is listening.
+ VPHomePodDevice = VPHomePodCreate(kCFAllocatorDefault, (__bridge CFDictionaryRef)properties, 1 << 0);
+ if (!VPHomePodDevice) {
+ VPHomePodSetFailure(@"Could not create the virtual MiniDisplay HID device");
+ return;
+ }
+ VPHomePodRegisterSetReport(VPHomePodDevice, VPHomePodReceiveReport, NULL);
+ VPHomePodSchedule(VPHomePodDevice, VPHomePodQueue);
+ pthread_mutex_lock(&VPHomePodLock);
+ if (!VPHomePodFramesReceived) VPHomePodState = @"waiting_for_guest";
+ pthread_mutex_unlock(&VPHomePodLock);
+ NSLog(@"vphoned: HomePod mini display HID device ready (%lu LEDs, %u-bit, hardware %u)",
+ (unsigned long)VPHomePodLEDCount, bitDepth, hardwareVersion);
+ });
+}
+
+bool vp_homepod_display_is_configured(void) { return VPHomePodConfigured; }
+
+char *vp_homepod_display_copy_json(void) {
+ @autoreleasepool {
+ pthread_mutex_lock(&VPHomePodLock);
+ NSData *frame = VPHomePodFrame;
+ NSMutableDictionary *result = [@{
+ @"available": VPHomePodDevice ? @YES : @NO, @"configured": @(VPHomePodConfigured),
+ @"state": VPHomePodState, @"error": VPHomePodError ?: (id)NSNull.null,
+ @"hardware_version": @(VPHomePodHardwareVersion), @"bit_depth": @(VPHomePodBitDepth),
+ @"report_bit_depth": @16,
+ @"display_count": @(VPHomePodDisplayCount),
+ @"generation": @(VPHomePodFramesReceived), @"frames_received": @(VPHomePodFramesReceived),
+ @"rejected_reports": @(VPHomePodRejectedReports), @"last_report_id": @(VPHomePodLastReportID),
+ @"last_report_length": @(VPHomePodLastReportLength),
+ @"geometry": VPHomePodGeometry ?: @{},
+ } mutableCopy];
+ pthread_mutex_unlock(&VPHomePodLock);
+ NSMutableArray *displays = [NSMutableArray arrayWithCapacity:VPHomePodDisplayCount];
+ if (frame.length == VPHomePodFrameSize(VPHomePodLEDCount, VPHomePodDisplayCount)) {
+ const uint8_t *bytes = frame.bytes;
+ for (NSUInteger display = 0; display < VPHomePodDisplayCount; display++) {
+ const uint8_t *channels = bytes + 9 + display * (4 + VPHomePodLEDCount * 6);
+ NSMutableArray *pixels = [NSMutableArray arrayWithCapacity:VPHomePodLEDCount];
+ for (NSUInteger index = 0; index < VPHomePodLEDCount; index++) {
+ const uint8_t *rgb = channels + 4 + index * 6;
+ [pixels addObject:@[@(VPHomePodReadChannel(rgb)),
+ @(VPHomePodReadChannel(rgb + 2)),
+ @(VPHomePodReadChannel(rgb + 4))]];
+ }
+ [displays addObject:@{@"pixels": pixels,
+ @"plus": @(VPHomePodReadChannel(channels)),
+ @"minus": @(VPHomePodReadChannel(channels + 2))}];
+ }
+ result[@"frame_timestamp"] = @(VPHomePodRead64(bytes + 1));
+ }
+ result[@"displays"] = displays;
+ result[@"pixels"] = displays.firstObject[@"pixels"] ?: @[];
+ result[@"plus"] = displays.firstObject[@"plus"] ?: @0;
+ result[@"minus"] = displays.firstObject[@"minus"] ?: @0;
+ NSData *json = [NSJSONSerialization dataWithJSONObject:result options:0 error:NULL];
+ if (!json) return NULL;
+ return strndup(json.bytes, json.length);
+ }
+}
diff --git a/VPhoneDaemon/Native/vphoned_homepod_report.h b/VPhoneDaemon/Native/vphoned_homepod_report.h
new file mode 100644
index 00000000..32bfebfc
--- /dev/null
+++ b/VPhoneDaemon/Native/vphoned_homepod_report.h
@@ -0,0 +1,34 @@
+#pragma once
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+// MiniDisplay's report 2: report ID, mach timestamp, then each display's +/-
+// (16 bit) and interleaved RGB words in device tree coordinate order.
+static inline uint16_t VPHomePodRead16(const uint8_t *bytes) {
+ return (uint16_t)bytes[0] | ((uint16_t)bytes[1] << 8);
+}
+
+// Peppy expands the physical MDBitDepth into kMDDisplayMaxBitDepth (16)
+// before submitting its UInt16 channels. The DT's 12-bit value is not the
+// captured output report's full-scale value.
+static inline double VPHomePodReadChannel(const uint8_t *bytes) {
+ return VPHomePodRead16(bytes) / 65535.0;
+}
+
+static inline uint32_t VPHomePodRead32(const uint8_t *bytes) {
+ return (uint32_t)VPHomePodRead16(bytes) | ((uint32_t)VPHomePodRead16(bytes + 2) << 16);
+}
+
+static inline uint64_t VPHomePodRead64(const uint8_t *bytes) {
+ return (uint64_t)VPHomePodRead32(bytes) | ((uint64_t)VPHomePodRead32(bytes + 4) << 32);
+}
+
+static inline size_t VPHomePodFrameSize(size_t ledCount, size_t displayCount) {
+ return 9 + displayCount * (4 + ledCount * 6);
+}
+
+static inline bool VPHomePodValidFrame(const uint8_t *bytes, size_t length,
+ size_t ledCount, size_t displayCount) {
+ return bytes && length == VPHomePodFrameSize(ledCount, displayCount) && bytes[0] == 2;
+}
diff --git a/VPhoneDaemon/Tests/HomePodDisplayReportTests.c b/VPhoneDaemon/Tests/HomePodDisplayReportTests.c
new file mode 100644
index 00000000..fed80282
--- /dev/null
+++ b/VPhoneDaemon/Tests/HomePodDisplayReportTests.c
@@ -0,0 +1,47 @@
+#include "../Native/vphoned_homepod_report.h"
+#include <assert.h>
+#include <stdio.h>
+
+int main(void) {
+ uint8_t report[245] = {2};
+ assert(VPHomePodFrameSize(19, 1) == 127);
+ assert(VPHomePodFrameSize(19, 2) == sizeof(report));
+ assert(VPHomePodValidFrame(report, sizeof(report), 19, 2));
+ assert(!VPHomePodValidFrame(report, sizeof(report) - 1, 19, 2));
+ assert(!VPHomePodValidFrame(report, sizeof(report), 18, 2));
+ assert(!VPHomePodValidFrame(report, sizeof(report), 19, 1));
+ assert(!VPHomePodValidFrame(NULL, sizeof(report), 19, 2));
+ report[0] = 1;
+ assert(!VPHomePodValidFrame(report, sizeof(report), 19, 2));
+ report[0] = 2;
+ // Deliberately unaligned timestamp and channel words match the HID wire
+ // layout, and catch accidental native struct alignment or endian changes.
+ const uint8_t words[] = {0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef};
+ for (size_t index = 0; index < sizeof(words); index++) report[index + 1] = words[index];
+ report[9] = 0xff; report[10] = 0xff;
+ report[11] = 0x00; report[12] = 0x80;
+ report[13] = 0xff; report[14] = 0x0f;
+ report[15] = 0x00; report[16] = 0x08;
+ report[17] = 0x01; report[18] = 0x00;
+ assert(VPHomePodRead64(report + 1) == UINT64_C(0xefcdab8967452301));
+ assert(VPHomePodRead16(report + 9) == 65535);
+ assert(VPHomePodRead16(report + 11) == 32768);
+ assert(VPHomePodRead16(report + 13) == 4095);
+ assert(VPHomePodRead16(report + 15) == 2048);
+ assert(VPHomePodRead16(report + 17) == 1);
+ assert(VPHomePodReadChannel(report + 9) == 1.0);
+ assert(VPHomePodReadChannel(report + 13) == 4095.0 / 65535.0);
+ const uint8_t liveWhite[] = {0x89, 0xbf};
+ assert(VPHomePodReadChannel(liveWhite) == 49033.0 / 65535.0);
+ assert(VPHomePodReadChannel(liveWhite) < 1.0);
+ // Hardware version 3 has a second 118-byte display block; the timestamp
+ // belongs to the whole report and is not repeated between displays.
+ report[127] = 0x34; report[128] = 0x12;
+ report[129] = 0x78; report[130] = 0x56;
+ report[243] = 0xbc; report[244] = 0x0a;
+ assert(VPHomePodRead16(report + 9 + (4 + 19 * 6)) == 0x1234);
+ assert(VPHomePodRead16(report + 11 + (4 + 19 * 6)) == 0x5678);
+ assert(VPHomePodRead16(report + 13 + (4 + 19 * 6) + 18 * 6 + 4) == 0x0abc);
+ puts("HomePod MiniDisplay report tests passed");
+ return 0;
+}
diff --git a/VPhoneDaemon/Tests/run-homepod-display-tests.sh b/VPhoneDaemon/Tests/run-homepod-display-tests.sh
new file mode 100755
index 00000000..a0bda93c
--- /dev/null
+++ b/VPhoneDaemon/Tests/run-homepod-display-tests.sh
@@ -0,0 +1,10 @@
+#!/bin/zsh
+set -euo pipefail
+
+tests="${0:a:h}"
+temporary="$(/usr/bin/mktemp -d "${TMPDIR:-/tmp}/vphone-homepod-display-tests.XXXXXX")"
+trap '/bin/rm -rf "$temporary"' EXIT
+
+/usr/bin/xcrun --sdk macosx clang -std=c11 -Wall -Wextra -Werror \
+ "$tests/HomePodDisplayReportTests.c" -o "$temporary/report-tests"
+"$temporary/report-tests"
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift
index b95b55fd..41981563 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift
@@ -9,6 +9,7 @@
// 3. Serialize the modified tree back to flat binary.
import Foundation
+import Img4tool
import VPhoneCoreKit
import VPhonePatchKit
@@ -117,6 +118,40 @@ public final class DeviceTreePatcher: BufferedPatcher {
rebuiltData ?? buffer.data
}
+ /// Extract the donor board's MiniDisplay geometry without grafting its
+ /// physical dock-channel hardware into the VM's virtual device tree.
+ /// Both the retained IM4P and an already-decoded flat payload are accepted.
+ public static func homePodDisplayProperties(from data: Data) throws -> [String: Data] {
+ let payload: Data
+ if let im4p = try? IM4P(data) {
+ guard im4p.fourcc == "dtre", !im4p.isEncrypted else {
+ throw PatcherError.invalidFormat("HomePod display: expected an unencrypted dtre IM4P")
+ }
+ payload = try im4p.payload()
+ } else {
+ payload = data
+ }
+ let parser = DeviceTreePatcher(data: payload, verbose: false)
+ let root = try parser.parsePayload(payload)
+ let display = try parser.resolveNode(root, path: [
+ "device-tree", "arm-io", "dockchannel-rtp", "rtp-transport", "display",
+ ])
+ let names = ["MDXCoords", "MDYCoords", "MDRingCoords", "MDBitDepth", "MDHWVersion"]
+ var properties: [String: Data] = [:]
+ for name in names {
+ let matches = display.properties.filter { $0.name == name }
+ guard matches.count == 1, let property = matches.first, property.flags == 0 else {
+ throw PatcherError.invalidFormat("HomePod display: missing, duplicate or unresolved \(name)")
+ }
+ properties[name] = property.value
+ }
+ let geometry = try VPhoneHomePodDisplayGeometry(deviceTreeProperties: properties)
+ guard geometry.bitDepth == 12, geometry.hardwareVersion == 3 else {
+ throw PatcherError.invalidFormat("HomePod display: unsupported MiniDisplay bit depth or hardware version")
+ }
+ return properties
+ }
+
// MARK: - Parsing
/// Align a value up to the next 4-byte boundary.
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift
index 9e3dcef6..d7b0beb3 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift
@@ -51,6 +51,7 @@ public enum FirmwareGuestPatchResolution {
/// Apple TV OTA swap, GPU injection, or plain-arm64 dyld workarounds.
public static let homePodSupportedGuestPatches = tvSupportedGuestPatches
.subtracting([FirmwareGuestSystemPatchSet.tvTPRO])
+ .union([FirmwareGuestSystemPatchSet.homePodTopCap])
.union(FirmwarePatchSetCatalog.tvOS27UserlandPatches)
public static func unvalidatedHomePodGuestPatches(enabled: Set<String>) -> [String] {
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
index 42338bab..890a2b5f 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestSystemPatchSet.swift
@@ -318,6 +318,12 @@ public enum FirmwareGuestSystemPatchSet {
target: .guestFile(path: "/usr/local/bin/vphoned"),
bootEssential: true,
),
+ VPhonePatchDeclaration(
+ identifier: homePodTopCap,
+ title: "HomePod top cap",
+ summary: "Stages the donor MiniDisplay geometry for vphoned's virtual HomePod LED display and volume buttons, with a SoundBoard-only shim for its reserved HID class identity.",
+ target: .guestFile(path: homePodDisplayPath),
+ ),
VPhonePatchDeclaration(
identifier: "system-launchdaemons-boot-environment",
title: "Guest environment",
@@ -571,6 +577,9 @@ public enum FirmwareGuestSystemPatchSet {
/// The iPad audio node repair in the restored Preboot device tree, for an
/// iPad VM patched before `fw patch` copied the board's node.
+ public static let homePodTopCap = "system-homepod-exp-top_cap"
+ public static let homePodDisplayPath = "/usr/share/vphone/HomePodDisplay.plist"
+
public static let prebootBoardAudio = "preboot-cfw-devicetree_board_audio"
/// The iPhone product description in the restored Preboot device tree,
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
index e2562b2c..f6ec8d15 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
@@ -61,7 +61,7 @@ public enum FirmwarePatchSetCatalog {
Set(FirmwareKernelFridaPatchSet.manifest.patches.map(\.identifier))
.union(hypervisorConcealmentPatches)
.union(experimentalIdentityPatches)
- .union([FirmwareGuestSystemPatchSet.otaUserland])
+ .union([FirmwareGuestSystemPatchSet.otaUserland, FirmwareGuestSystemPatchSet.homePodTopCap])
.union([FirmwareKernelCustomFirmwarePatchSet.tvTPROPagers, misTrustAuthPatch, FirmwareGuestSystemPatchSet.settingsRootRows, FirmwareGuestSystemPatchSet.settingsSoftwareUpdate, FirmwareGuestSystemPatchSet.tvTPRO, FirmwareGuestSystemPatchSet.tvOTAUserland])
/// ProMotion: the 120 Hz timing for the paravirtual display.
@@ -207,19 +207,19 @@ public enum FirmwarePatchSetCatalog {
selection: .block(manualOnlyPatches),
)
- /// Everything the bundle declares, including the Frida relaxations, the
+ /// The general-purpose experimental patches, including the Frida relaxations, the
/// hypervisor concealment and the iPhone17,3 identity. Each patch's own version
/// gate still decides whether it lands.
public static let experimentalPreset = VPhonePatchPreset(
identifier: "experimental",
title: "Experimental",
summary: """
- Every patch this bundle declares, including the Frida Stalker relaxations, \
+ The experimental patches, including the Frida Stalker relaxations, \
the iPhone17,3 identity rewrites, and the hv_vmm_present concealment that a \
- freshly restored 26.4 guest does not survive.
+ freshly restored 26.4 guest does not survive. The HomePod-only top cap is off.
""",
patchSets: bundledReferences,
- selection: .all,
+ selection: .block([FirmwareGuestSystemPatchSet.homePodTopCap]),
)
/// The iOS payloads, hooks and shared-cache patches an Apple TV guest has no
@@ -321,10 +321,11 @@ public enum FirmwarePatchSetCatalog {
public static let homePodMiniPreset = VPhonePatchPreset(
identifier: VPhonePatchPreset.homePodMiniIdentifier,
title: "HomePod mini",
- summary: "Research: HomePod mini's own arm64e TVOS IPSW with vphoned, without Apple TV OTA replacement or iPhone display, camera and audio hooks.",
+ summary: "Research: HomePod mini's own arm64e TVOS IPSW with vphoned and its donor-driven top cap, without Apple TV OTA replacement or iPhone display, camera and audio hooks.",
patchSets: bundledReferences,
selection: .block(
- manualOnlyPatches.union(tvOSBlockedPatches.subtracting(tvOS27UserlandPatches)),
+ manualOnlyPatches.subtracting([FirmwareGuestSystemPatchSet.homePodTopCap])
+ .union(tvOSBlockedPatches.subtracting(tvOS27UserlandPatches)),
),
)
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/CustomFirmware/CustomFirmwareBoardAudioTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/CustomFirmware/CustomFirmwareBoardAudioTests.swift
index 47a2c060..6cbab839 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/CustomFirmware/CustomFirmwareBoardAudioTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/CustomFirmware/CustomFirmwareBoardAudioTests.swift
@@ -7,6 +7,7 @@
@testable import FirmwarePatcher
import Foundation
+import Img4tool
import Testing
@Suite("iPad audio node from the board tree")
@@ -112,3 +113,65 @@ struct CustomFirmwareBoardAudioTests {
}
}
}
+
+@Suite("HomePod donor top-cap metadata")
+struct HomePodDisplayMetadataTests {
+ private typealias Node = FlatDeviceTreeNode
+
+ // B520AP / AudioAccessory5,1 27.0 (24J361), captured from the physical
+ // display node. These bytes are evidence fixtures, not runtime defaults.
+ private static let donor: [String: Data] = [
+ "MDXCoords": Data(base64Encoded: "KE0AAACAAADXsgAAENgAAK/lAAAQ2AAA2LIAAACAAAApTQAA8CcAAFEaAADwJwAAyFoAAKCNAADYsgAAOKUAAGByAAAoTQAAAIAAAA==")!,
+ "MDYCoords": Data(base64Encoded: "ENgAAK/lAAAQ2AAA2LIAAACAAAApTQAA8CcAAFEaAADwJwAAKE0AAACAAADXsgAAOKUAANiyAACgjQAAyFoAAChNAABgcgAAAIAAAA==")!,
+ "MDRingCoords": Data(base64Encoded: "AgAAAAIAAAACAAAAAgAAAAIAAAACAAAAAgAAAAIAAAACAAAAAgAAAAIAAAACAAAAAQAAAAEAAAABAAAAAQAAAAEAAAABAAAAAAAAAA==")!,
+ "MDBitDepth": Node.uint32(12),
+ "MDHWVersion": Node.uint32(3),
+ ]
+
+ private static func tree(_ properties: [String: Data]) -> Data {
+ Node("device-tree", children: [
+ Node("arm-io", children: [
+ Node("dockchannel-rtp", children: [
+ Node("rtp-transport", children: [
+ Node("display", properties.sorted { $0.key < $1.key }.map { ($0.key, $0.value) }),
+ ]),
+ ]),
+ ]),
+ ]).serialized
+ }
+
+ @Test func `extracts all nineteen LEDs in donor order from raw and IM4P trees`() throws {
+ let raw = Self.tree(Self.donor)
+ #expect(try DeviceTreePatcher.homePodDisplayProperties(from: raw) == Self.donor)
+ let im4p = try IM4P(fourcc: "dtre", description: "HomePod metadata test", payload: raw)
+ let extracted = try DeviceTreePatcher.homePodDisplayProperties(from: im4p.data)
+ #expect(extracted == Self.donor)
+ #expect(extracted["MDXCoords"]?.count == 19 * 4)
+ }
+
+ @Test func `requires the physical display node instead of inventing a layout`() {
+ #expect(throws: (any Error).self) {
+ try DeviceTreePatcher.homePodDisplayProperties(from: Node("device-tree").serialized)
+ }
+ }
+
+ @Test func `rejects truncated and incompatible donor properties`() {
+ for (name, replacement) in [
+ ("MDYCoords", Data([0])),
+ ("MDXCoords", Node.uint32(0x10001)),
+ ("MDBitDepth", Node.uint32(8)),
+ ("MDHWVersion", Node.uint32(4)),
+ ] {
+ var properties = Self.donor
+ properties[name] = replacement
+ #expect(throws: (any Error).self) {
+ try DeviceTreePatcher.homePodDisplayProperties(from: Self.tree(properties))
+ }
+ }
+ var incomplete = Self.donor
+ incomplete.removeValue(forKey: "MDRingCoords")
+ #expect(throws: (any Error).self) {
+ try DeviceTreePatcher.homePodDisplayProperties(from: Self.tree(incomplete))
+ }
+ }
+}
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
index ef65cfea..5e2c5b17 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
@@ -12,6 +12,20 @@ import VPhonePatchKit
@Suite("Guest patch resolution")
struct FirmwareGuestPatchResolutionTests {
+ @Test func `only the HomePod preset selects the top cap and TV rejects explicit selection`() throws {
+ let identifier = FirmwareGuestSystemPatchSet.homePodTopCap
+ for preset in FirmwarePatchSetCatalog.builtInPresets {
+ let plan = try VPhonePatchPlan.resolve(
+ preset: preset, patchSets: FirmwarePatchSetCatalog.bundled,
+ iOSBase: VPhoneVersion("27.0"), cloudOS: VPhoneVersion("26.4"),
+ )
+ #expect(plan.isEnabled(identifier) == (preset.identifier == VPhonePatchPreset.homePodMiniIdentifier))
+ }
+ #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: [identifier]).isEmpty)
+ #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier]) == [identifier])
+ #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [identifier], arm64eUserland: true) == [identifier])
+ }
+
@Test
func `TV selection keeps vphoned and excludes iOS payloads and cache patches`() throws {
let standard = try VPhonePatchPlan.resolve(
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
index 96212192..1da8406b 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
@@ -178,7 +178,7 @@ struct FirmwarePatchSetCatalogTests {
}
@Test
- func `Extended adds exactly the manual-only patches applicable to each base`() throws {
+ func `Extended adds the applicable manual patches except the HomePod-only device`() throws {
for base in ["18.6.2", "26.4", "27.0", "27.1"] {
let version = VPhoneVersion(base)
let cloud = VPhoneVersion("26.4")
@@ -196,6 +196,7 @@ struct FirmwarePatchSetCatalogTests {
)
let applicableManual = Set(FirmwarePatchSetCatalog.allDeclarations.filter {
FirmwarePatchSetCatalog.manualOnlyPatches.contains($0.identifier)
+ && $0.identifier != FirmwareGuestSystemPatchSet.homePodTopCap
&& $0.applicability.matches(iOSBase: version, cloudOS: cloud)
}.map(\.identifier))
#expect(experimental.enabled.subtracting(standard.enabled) == applicableManual)
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index eada2561..7f57e861 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -200,6 +200,9 @@ struct VPhoneCustomFirmwareInstaller {
? try restoreTree(in: bundleDirectory, path: bundlePath, owner: callerUID)
: nil
let device = configuredGuestDevice(in: bundleDirectory) ?? guestDevice(of: restore)
+ if effectiveEnabled.contains(FirmwareGuestSystemPatchSet.homePodTopCap), device.family != .homePod {
+ throw ValidationError("The HomePod top-cap patch is supported only for a HomePod guest.")
+ }
// Research: an Apple TV 4K userland staged from its OTA, which
// `system-tv-exp-ota_userland` puts in place of the restored one.
let hasOTAUserland = (try? bundleDirectory.isDirectory(VPhoneOTAArchive.userlandDirectoryName)) == true
@@ -259,6 +262,17 @@ struct VPhoneCustomFirmwareInstaller {
}
}
try requireFreeSpace(at: [bundlePath, work.url.path])
+ let boardDeviceTree = try stageBoardDeviceTree(in: bundleDirectory, work: work, device: device)
+ let homePodDisplay: Data?
+ if effectiveEnabled.contains(FirmwareGuestSystemPatchSet.homePodTopCap) {
+ guard let boardDeviceTree else {
+ throw ValidationError("HomePod top-cap emulation needs the original board device tree in FirmwareOriginals. Recover it from this VM's IPSW before updating the environment.")
+ }
+ let properties = try DeviceTreePatcher.homePodDisplayProperties(from: Data(contentsOf: boardDeviceTree))
+ homePodDisplay = try PropertyListSerialization.data(fromPropertyList: properties, format: .binary, options: 0)
+ } else {
+ homePodDisplay = nil
+ }
// Work on an APFS clone of Disk.img in the private folder, then rename
// it over the original: nothing is attached from the caller's folder,
@@ -420,6 +434,7 @@ struct VPhoneCustomFirmwareInstaller {
work: work,
owner: callerUID,
otaUserland: otaUserland,
+ homePodDisplay: homePodDisplay,
plan: plan,
priorGuest: priorGuest,
kernelPatches: receiptKernel,
@@ -442,6 +457,7 @@ struct VPhoneCustomFirmwareInstaller {
work: work,
owner: nil,
otaUserland: otaUserland,
+ homePodDisplay: homePodDisplay,
plan: plan,
priorGuest: priorGuest,
kernelPatches: receiptKernel,
@@ -456,7 +472,6 @@ struct VPhoneCustomFirmwareInstaller {
// drops that cache at startup when it is older than the tree; see
// VPhoneDaemon/Daemon/GuestMobileGestaltCache.swift.
let buildVersion = plan?.parameters[FirmwareGuestSystemPatchSet.buildVersionParameter] ?? spoofBuild
- let boardDeviceTree = try stageBoardDeviceTree(in: bundleDirectory, work: work, device: device)
// An environment update has no restore tree to read the device from;
// the VM's configuration says which board repair its tree takes.
try liveGuest.formUnion(patchPreboot(
@@ -1121,6 +1136,7 @@ struct VPhoneCustomFirmwareInstaller {
work: WorkDirectory,
owner: uid_t?,
otaUserland: VPhoneConfinedDirectory?,
+ homePodDisplay: Data?,
plan: VPhoneVirtualMachinePatchPlan?,
priorGuest: Set<String>,
kernelPatches: Set<String>?,
@@ -1309,6 +1325,24 @@ struct VPhoneCustomFirmwareInstaller {
live.insert("system-launchdaemons-boot-environment")
}
}
+ // Geometry and its SoundBoard-only identity shim belong to one patch:
+ // the daemon still exchanges every LED frame through the native HID.
+ let topCap = FirmwareGuestSystemPatchSet.homePodTopCap
+ let topCapPath = String(FirmwareGuestSystemPatchSet.homePodDisplayPath.dropFirst())
+ if plan?.isEnabled(topCap) == true {
+ guard guestDevice.family == .homePod, let homePodDisplay else {
+ throw ValidationError("Selected HomePod top-cap emulation has no validated donor display geometry.")
+ }
+ _ = try system.directory("usr/share/vphone", create: true, mode: 0o755)
+ try system.writeFile(topCapPath, contents: homePodDisplay, mode: 0o644, owner: Self.guestOwner)
+ try updateHomePodSoundBoard(system: system, work: work, enabled: true)
+ live.insert(topCap)
+ } else {
+ if guestDevice.family == .homePod || priorGuest.contains(topCap) {
+ try updateHomePodSoundBoard(system: system, work: work, enabled: false)
+ }
+ try system.removeItem(topCapPath)
+ }
for (identifier, library) in [
(FirmwareGuestSystemPatchSet.gyroscope, "libvphonegyro.dylib"),
(FirmwareGuestSystemPatchSet.accelerometer, "libvphoneaccelerometer.dylib"),
@@ -2262,6 +2296,108 @@ struct VPhoneCustomFirmwareInstaller {
print(" [+] GPU driver retargeted to tvOS")
}
+ /// IOHIDUserDevice reserves IOClass. The shim supplies MiniDisplay's class
+ /// identity only for our physical ID, inside SoundBoard. Load it through
+ /// SoundBoard's Mach-O: launchd strips DYLD environment variables from this
+ /// platform process. Also remove this patch's earlier environment route.
+ private func updateHomePodSoundBoard(system: VPhoneConfinedDirectory, work: WorkDirectory, enabled: Bool) throws {
+ let daemon = "System/Library/LaunchDaemons/com.apple.SoundBoard.plist"
+ let cache = "System/Library/xpc/launchd.plist"
+ let library = "/usr/lib/libvphonehomepoddisplay.dylib"
+ let libraryPath = String(library.dropFirst())
+ let app = "System/Library/CoreServices/SoundBoard.app"
+ let executable = "\(app)/SoundBoard"
+
+ func read(_ path: String) throws -> (dictionary: [String: Any], format: PropertyListSerialization.PropertyListFormat) {
+ var format = PropertyListSerialization.PropertyListFormat.xml
+ guard let dictionary = try PropertyListSerialization.propertyList(
+ from: system.readData(path), options: [], format: &format,
+ ) as? [String: Any] else {
+ throw ValidationError("HomePod top cap needs a valid \(path).")
+ }
+ return (dictionary, format)
+ }
+
+ func rewrite(_ dictionary: [String: Any]) throws -> [String: Any] {
+ var updated = dictionary
+ guard updated["Label"] as? String == "com.apple.SoundBoard",
+ (updated["ProgramArguments"] as? [String])?.first
+ == "/System/Library/CoreServices/SoundBoard.app/SoundBoard"
+ else {
+ throw ValidationError("HomePod top cap refuses a daemon that is not SoundBoard.")
+ }
+ guard updated["EnvironmentVariables"] == nil || updated["EnvironmentVariables"] is [String: Any] else {
+ throw ValidationError("SoundBoard has invalid launchd EnvironmentVariables.")
+ }
+ var environment = updated["EnvironmentVariables"] as? [String: Any] ?? [:]
+ guard environment["DYLD_INSERT_LIBRARIES"] == nil || environment["DYLD_INSERT_LIBRARIES"] is String else {
+ throw ValidationError("SoundBoard has invalid DYLD_INSERT_LIBRARIES.")
+ }
+ let libraries = (environment["DYLD_INSERT_LIBRARIES"] as? String ?? "")
+ .split(separator: ":", omittingEmptySubsequences: true).map(String.init)
+ .filter { $0 != library }
+ if libraries.isEmpty {
+ environment.removeValue(forKey: "DYLD_INSERT_LIBRARIES")
+ } else {
+ environment["DYLD_INSERT_LIBRARIES"] = libraries.joined(separator: ":")
+ }
+ if environment.isEmpty {
+ updated.removeValue(forKey: "EnvironmentVariables")
+ } else {
+ updated["EnvironmentVariables"] = environment
+ }
+ return updated
+ }
+
+ // Validate the complete pair before writing either half. A missing
+ // cache entry is not a reason to silently install an inert shim.
+ guard try system.isRegularFile(daemon), try system.isRegularFile(cache) else {
+ if !enabled {
+ if try revertMachO(system: system, work: work, path: executable) {
+ try sealGuestBundle(system: system, bundle: app, preserveEntitlements: true)
+ }
+ try system.removeItem(libraryPath)
+ return
+ }
+ throw ValidationError("HomePod top cap needs SoundBoard's launch daemon and launchd cache.")
+ }
+ let original = try read(daemon)
+ var cached = try read(cache)
+ let key = "/" + daemon
+ guard var entries = cached.dictionary["LaunchDaemons"] as? [String: Any],
+ let entry = entries[key] as? [String: Any]
+ else {
+ throw ValidationError("HomePod top cap cannot find SoundBoard in the launchd cache.")
+ }
+ let changedDaemon = try rewrite(original.dictionary)
+ entries[key] = try rewrite(entry)
+ cached.dictionary["LaunchDaemons"] = entries
+
+ if enabled {
+ let shim = try VPhoneGuestBinaries.resolve("libvphonehomepoddisplay.dylib")
+ try system.replaceFile(libraryPath, fromFileAt: shim, mode: 0o755, owner: Self.guestOwner)
+ try patchMachO(
+ system: system, work: work, path: executable,
+ preserveEntitlements: true, injectedDylibPath: library,
+ )
+ try sealGuestBundle(system: system, bundle: app, preserveEntitlements: true)
+ } else {
+ if try revertMachO(system: system, work: work, path: executable) {
+ try sealGuestBundle(system: system, bundle: app, preserveEntitlements: true)
+ }
+ try system.removeItem(libraryPath)
+ }
+ // This is an exact inverse of the prototype's environment insertion,
+ // keeping changes users made to other daemon keys in the meantime.
+ try system.writeFile(daemon, contents: PropertyListSerialization.data(
+ fromPropertyList: changedDaemon, format: original.format, options: 0,
+ ), mode: 0o644, owner: Self.guestOwner)
+ try system.removeItem("\(daemon).bak")
+ try system.writeFile(cache, contents: PropertyListSerialization.data(
+ fromPropertyList: cached.dictionary, format: cached.format, options: 0,
+ ), mode: 0o644, owner: Self.guestOwner)
+ }
+
private func installVphoned(guestDevice: VPhoneGuestDevice, system: VPhoneConfinedDirectory, work: WorkDirectory) throws {
// Install the same signed bytes that vm launch uses for auto-update.
// Re-signing here changes the binary hash and forces an upload and
@@ -3080,12 +3216,12 @@ struct VPhoneCustomFirmwareInstaller {
/// bundle whose seal no longer matches its contents. Ad hoc, like every
/// other guest binary this pipeline writes; the identifier is kept so the
/// plugin still answers to the name it always had.
- private func sealGuestBundle(system: VPhoneConfinedDirectory, bundle: String) throws {
+ private func sealGuestBundle(system: VPhoneConfinedDirectory, bundle: String, preserveEntitlements: Bool = false) throws {
// No --identifier: codesign keeps the one the bundle already carries.
- _ = try tool("/usr/bin/codesign", [
- "-f", "-s", "-", "--timestamp=none",
- system.directory(bundle).path,
- ])
+ var arguments = ["-f", "-s", "-", "--timestamp=none"]
+ if preserveEntitlements { arguments.append("--preserve-metadata=entitlements") }
+ arguments.append(try system.directory(bundle).path)
+ _ = try tool("/usr/bin/codesign", arguments)
}
/// Copy an optional guest binary into the work folder, or nil (with a
diff --git a/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh b/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
index 6b110205..6f17f665 100755
--- a/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
+++ b/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
@@ -89,6 +89,7 @@ daemon_sdk="$(/usr/bin/otool -l "$guest/vphoned" | /usr/bin/awk '/LC_BUILD_VERSI
/bin/cp "$guest_products/gyroscope/libvphonegyro.dylib" "$guest/libvphonegyro.dylib"
/bin/cp "$guest_products/accelerometer/libvphoneaccelerometer.dylib" "$guest/libvphoneaccelerometer.dylib"
/bin/cp "$guest_products/attitude/libvphoneattitude.dylib" "$guest/libvphoneattitude.dylib"
+/bin/cp "$guest_products/homepoddisplay/libvphonehomepoddisplay.dylib" "$guest/libvphonehomepoddisplay.dylib"
/bin/cp "$guest_products/gpu/libAppleParavirtCompilerPluginIOGPUFamily.dylib" \
"$guest/libAppleParavirtCompilerPluginIOGPUFamily.dylib"
# The HAL plugin is a bundle, signed whole by the Makefile; copied as a tree so
diff --git a/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh b/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
index 7bef958e..75734d26 100755
--- a/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
+++ b/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
@@ -122,7 +122,7 @@ fi
for name in vphoned vphoned-tvos launchdhook-vphone.dylib SystemHook-vphone.dylib libcamfix.dylib \
libvcamcaptured.dylib libmisfix.dylib libhapticsfix.dylib libbatteryhealthfix.dylib libdevicehubfix.dylib libdevicename.dylib \
- libprefsfix.dylib libsigninfix.dylib libvphonegyro.dylib libvphoneaccelerometer.dylib libvphoneattitude.dylib libAppleParavirtCompilerPluginIOGPUFamily.dylib; do
+ libprefsfix.dylib libsigninfix.dylib libvphonegyro.dylib libvphoneaccelerometer.dylib libvphoneattitude.dylib libvphonehomepoddisplay.dylib libAppleParavirtCompilerPluginIOGPUFamily.dylib; do
require_signed_macho "$guest/$name"
done
for name in vphoned.plist libcamfix.plist libvcamcaptured.plist libmisfix.plist; do
@@ -176,7 +176,7 @@ while IFS= read -r file; do
"$frameworks/"*)
[[ "$platform" != IOS ]] || { print -u2 "iOS binary in Contents/Frameworks: ${file#$bundle/}"; exit 1; }
;;
- "$guest/vphoned-tvos")
+ "$guest/vphoned-tvos"|"$guest/libvphonehomepoddisplay.dylib")
# tvOS dyld refuses an iOS-platform daemon on an Apple TV guest.
[[ "$platform" == TVOS ]] || { print -u2 "Non-tvOS binary: ${file#$bundle/}"; exit 1; }
;;
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/experimental.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/experimental.plist
index 0f010786..85f2493c 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/experimental.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/experimental.plist
@@ -1,9 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<!--
- Everything the bundle declares, including the groups `standard` leaves off: the
+ The general experimental groups `standard` leaves off: the
Frida Stalker relaxations, the hv_vmm_present concealment, and the iPhone17,3
- identity rewrites.
+ identity rewrites. The HomePod-only top cap stays off.
Read this as the catalogue and standard as the safe subset — the two name the
same patch sets and differ only in their selection. Each patch's own version gate
@@ -23,7 +23,7 @@
<key>Title</key>
<string>Experimental</string>
<key>Summary</key>
- <string>Every patch this bundle declares, including the Frida Stalker relaxations, the iPhone17,3 identity rewrites, and the hv_vmm_present concealment that a freshly restored 26.4 guest does not survive.</string>
+ <string>The experimental patches, including the Frida Stalker relaxations, the iPhone17,3 identity rewrites, and the hv_vmm_present concealment that a freshly restored 26.4 guest does not survive. The HomePod-only top cap is off.</string>
<key>PatchSets</key>
<array>
<dict>
@@ -84,7 +84,11 @@
<key>Selection</key>
<dict>
<key>Kind</key>
- <string>All</string>
+ <string>Block</string>
+ <key>Patches</key>
+ <array>
+ <string>system-homepod-exp-top_cap</string>
+ </array>
</dict>
</dict>
</plist>
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
index 9ffafc1f..8993ab8b 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
@@ -129,7 +129,7 @@
</array>
</dict>
<key>Summary</key>
- <string>Research: HomePod mini's own arm64e TVOS IPSW with vphoned, without Apple TV OTA replacement or iPhone display, camera and audio hooks.</string>
+ <string>Research: HomePod mini's own arm64e TVOS IPSW with vphoned and its donor-driven top cap, without Apple TV OTA replacement or iPhone display, camera and audio hooks.</string>
<key>Title</key>
<string>HomePod mini</string>
</dict>
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
index d5d58737..c7251306 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
@@ -67,6 +67,7 @@
<string>Block</string>
<key>Patches</key>
<array>
+ <string>system-homepod-exp-top_cap</string>
<string>kernel-exp-frida_thread_set_state_entitlement_flag</string>
<string>kernel-exp-frida_vm_map_delete_immutable_code</string>
<string>kernel-exp-hv_vmm</string>
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
index 028e632c..c7e75d40 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos-4k.plist
@@ -67,6 +67,7 @@
<string>Block</string>
<key>Patches</key>
<array>
+ <string>system-homepod-exp-top_cap</string>
<string>system-exp-ota_userland</string>
<string>kernel-exp-frida_thread_set_state_entitlement_flag</string>
<string>kernel-cfw-paravirt_gpu_task3</string>
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
index 19582a74..7ef97b3d 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/tvos.plist
@@ -67,6 +67,7 @@
<string>Block</string>
<key>Patches</key>
<array>
+ <string>system-homepod-exp-top_cap</string>
<string>kernel-exp-frida_thread_set_state_entitlement_flag</string>
<string>kernel-cfw-paravirt_gpu_task3</string>
<string>kernel-exp-frida_vm_map_delete_immutable_code</string>
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swift b/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swift
index 19cc98cc..f1a147c2 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swift
@@ -301,16 +301,36 @@ final class VPhoneGuestControl {
sendHID(page: page, usage: usage, down: true)
}
- func sendHIDUp(page: UInt32, usage: UInt32) {
- sendHID(page: page, usage: usage, down: false)
+ func sendHIDUp(page: UInt32, usage: UInt32, minimumHold: Duration = .zero) {
+ sendHID(page: page, usage: usage, down: false, minimumHold: minimumHold)
}
- private func sendHID(page: UInt32, usage: UInt32, down: Bool?) {
+ @ObservationIgnored private var heldHIDKeys: [UInt64: ContinuousClock.Instant] = [:]
+
+ private func sendHID(page: UInt32, usage: UInt32, down: Bool?, minimumHold: Duration = .zero) {
var params: [String: Any] = ["page": page, "usage": usage]
if let down {
params["down"] = down
}
- enqueueInput("input.hid", params: params)
+ let key = UInt64(page) << 32 | UInt64(usage)
+ let previous = orderedInput
+ orderedInput = Task {
+ await previous?.value
+ guard !Task.isCancelled else { return }
+ if down == false, minimumHold > .zero, let began = heldHIDKeys[key] {
+ // Preserve a tap's duration even when the guest or transport
+ // delays key-down. Timing in the view can collapse both events
+ // into consecutive RPCs after the input queue catches up.
+ let remaining = minimumHold - began.duration(to: .now)
+ if remaining > .zero { try? await Task.sleep(for: remaining) }
+ }
+ guard !Task.isCancelled else { return }
+ do {
+ _ = try await call("input.hid", params: params)
+ if down == true { heldHIDKeys[key] = .now }
+ else { heldHIDKeys.removeValue(forKey: key) }
+ } catch { print("[control] input.hid: \(error)") }
+ }
}
func sendTouch(phase: Int, x: Double, y: Double) {
@@ -614,10 +634,10 @@ final class VPhoneGuestControl {
/// `call`, with vphoned's refusal kept whole as `GuestRPCFailure`: `code`,
/// `message` and whatever the command adds (`results`, `reason`, `errno`,
/// `retryable` …).
- private func rpc(_ method: String, params: [String: Any]) async throws -> [String: Any] {
+ private func rpc(_ method: String, params: [String: Any], limits: VPhoneHTTPLimits = .rpc) async throws -> [String: Any] {
let object: [String: Any] = ["id": UUID().uuidString, "method": method, "params": params]
let body = try JSONSerialization.data(withJSONObject: object)
- let response = try await http(method: "POST", path: "/v1/rpc", body: body)
+ let response = try await http(method: "POST", path: "/v1/rpc", body: body, limits: limits)
guard let envelope = try JSONSerialization.jsonObject(with: response.body) as? [String: Any]
else { throw ControlError.protocolError("invalid JSON response") }
if let error = envelope["error"] as? [String: Any] {
@@ -628,6 +648,32 @@ final class VPhoneGuestControl {
return result
}
+ /// A latest-frame read has a short deadline: loss of the guest must blank
+ /// the cap instead of leaving a frozen animation lit for an RPC timeout.
+ func homePodDisplaySnapshot() async throws -> (geometry: VPhoneHomePodDisplayGeometry, frame: VPhoneHomePodDisplayFrame)? {
+ let state = try await rpc("homepod.display.state", params: [:], limits: .homePodDisplay)
+ guard state["available"] as? Bool == true else { return nil }
+ guard let geometry = state["geometry"] as? [String: Any],
+ let x = geometry["x"] as? [Double], let y = geometry["y"] as? [Double],
+ let rings = geometry["rings"] as? [UInt32],
+ let bitDepth = state["bit_depth"] as? Int,
+ let version = state["hardware_version"] as? UInt32,
+ let displays = state["displays"] as? [[String: Any]], !displays.isEmpty,
+ let plus = state["plus"] as? Double, let minus = state["minus"] as? Double,
+ let generation = state["generation"] as? UInt64
+ else { throw ControlError.protocolError("invalid HomePod display snapshot") }
+ let layout = try VPhoneHomePodDisplayGeometry(xCoordinates: x, yCoordinates: y, rings: rings, bitDepth: bitDepth, hardwareVersion: version)
+ let banks = try displays.map { display -> [[Double]] in
+ guard let pixels = display["pixels"] as? [[Double]] else {
+ throw ControlError.protocolError("missing HomePod LED bank")
+ }
+ return pixels
+ }
+ let frame = try VPhoneHomePodDisplayFrame(banks: banks, plusBrightness: plus, minusBrightness: minus, generation: generation)
+ guard frame.matches(layout) else { throw ControlError.protocolError("HomePod display frame does not match its geometry") }
+ return (layout, frame)
+ }
+
func listFiles(path: String) async throws -> [[String: Any]] {
let (value, _) = try await sendRequest(["t": "file_list", "path": path])
guard let entries = value["entries"] as? [[String: Any]] else {
@@ -999,6 +1045,7 @@ private struct VPhoneHTTPLimits: Sendable {
/// JSON, RPC and clipboard responses. A guest operation may run up to the
/// 120 s read timeout before it answers, so the deadline sits above it.
static let rpc = VPhoneHTTPLimits(maxBodyLength: 64 * 1024 * 1024, deadline: .seconds(180))
+ static let homePodDisplay = VPhoneHTTPLimits(maxBodyLength: 64 * 1024, deadline: .seconds(1))
/// File downloads: the response body is the file.
static let download = VPhoneHTTPLimits(maxBodyLength: 2_147_483_647, deadline: .seconds(30 * 60))
/// Uploads: the request body is large, the response is a small JSON reply.
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/HomePod/VPhoneHomePodDisplayView.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/HomePod/VPhoneHomePodDisplayView.swift
new file mode 100644
index 00000000..b1a01dc4
--- /dev/null
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/HomePod/VPhoneHomePodDisplayView.swift
@@ -0,0 +1,256 @@
+import AppKit
+import VPhoneCoreKit
+
+// MARK: - HomePod Top Cap
+
+/// The HomePod's light diffuser and capacitive controls. Every light comes
+/// from the latest guest frame; this view has no autonomous animation clock.
+@MainActor
+final class VPhoneHomePodDisplayView: NSView {
+ enum Control: Hashable {
+ case volumeDown
+ case volumeUp
+ case surface
+ }
+
+ /// Paired transitions preserve a physical hold until pointer/key release.
+ var onControlChange: ((Control, Bool, Duration) -> Void)?
+ /// Enabled only when the caller has an evidenced guest touch mapping.
+ var surfaceControlEnabled = false {
+ didSet {
+ surface.isHidden = !surfaceControlEnabled
+ surface.setAccessibilityElement(surfaceControlEnabled)
+ plus.nextKeyView = surfaceControlEnabled ? surface : minus
+ }
+ }
+ private(set) var geometry: VPhoneHomePodDisplayGeometry?
+ private(set) var displayFrame: VPhoneHomePodDisplayFrame?
+
+ private let surface = VPhoneHomePodCapControl(control: .surface, label: "HomePod touch surface")
+ private let minus = VPhoneHomePodCapControl(control: .volumeDown, label: "Decrease volume")
+ private let plus = VPhoneHomePodCapControl(control: .volumeUp, label: "Increase volume")
+
+ override init(frame frameRect: NSRect) {
+ super.init(frame: frameRect)
+ setAccessibilityElement(false)
+ for button in [surface, minus, plus] {
+ button.onChange = { [weak self] control, down, minimumHold in
+ self?.onControlChange?(control, down, minimumHold)
+ }
+ addSubview(button)
+ }
+ surface.nextKeyView = minus
+ minus.nextKeyView = plus
+ plus.nextKeyView = minus
+ surface.isHidden = true
+ surface.setAccessibilityElement(false)
+ }
+
+ required init?(coder: NSCoder) { nil }
+
+ override var isFlipped: Bool { true }
+ override var intrinsicContentSize: NSSize { NSSize(width: 360, height: 360) }
+
+ /// A geometry change invalidates the previous frame. Never retain old LED
+ /// indices against a new device layout, or display a partial snapshot.
+ func update(geometry: VPhoneHomePodDisplayGeometry, frame: VPhoneHomePodDisplayFrame) {
+ guard frame.matches(geometry) else { return }
+ guard self.geometry != geometry || displayFrame != frame else { return }
+ self.geometry = geometry
+ displayFrame = frame
+ minus.illumination = frame.minusBrightness * frame.brightness
+ plus.illumination = frame.plusBrightness * frame.brightness
+ needsDisplay = true
+ }
+
+ func clearDisplay() {
+ releaseControls()
+ guard displayFrame != nil else { return }
+ displayFrame = nil
+ minus.illumination = 0
+ plus.illumination = 0
+ needsDisplay = true
+ }
+
+ func releaseControls() {
+ for button in [surface, minus, plus] { button.releaseControl() }
+ }
+
+ func focusControls() {
+ window?.makeFirstResponder(minus)
+ }
+
+ override func viewWillMove(toWindow newWindow: NSWindow?) {
+ releaseControls()
+ NotificationCenter.default.removeObserver(self, name: NSWindow.didResignKeyNotification, object: nil)
+ if let newWindow {
+ NotificationCenter.default.addObserver(self, selector: #selector(windowResignedKey), name: NSWindow.didResignKeyNotification, object: newWindow)
+ }
+ super.viewWillMove(toWindow: newWindow)
+ }
+
+ @objc private func windowResignedKey(_ notification: Notification) { releaseControls() }
+
+ private var capRect: CGRect {
+ let diameter = max(0, min(bounds.width, bounds.height) - 32)
+ return CGRect(x: bounds.midX - diameter / 2, y: bounds.midY - diameter / 2, width: diameter, height: diameter)
+ }
+
+ override func layout() {
+ super.layout()
+ let cap = capRect
+ surface.frame = cap
+ let side = cap.width * 0.19
+ minus.frame = CGRect(x: cap.midX - cap.width * 0.30 - side / 2, y: cap.midY - side / 2, width: side, height: side)
+ plus.frame = CGRect(x: cap.midX + cap.width * 0.30 - side / 2, y: cap.midY - side / 2, width: side, height: side)
+ }
+
+ override func draw(_ dirtyRect: NSRect) {
+ NSColor(calibratedWhite: 0.055, alpha: 1).setFill()
+ dirtyRect.fill()
+ let cap = capRect
+ guard cap.width > 0 else { return }
+ let path = NSBezierPath(ovalIn: cap)
+ NSColor.black.setFill()
+ path.fill()
+ NSGraphicsContext.saveGraphicsState()
+ path.addClip()
+ if let geometry, let displayFrame, let context = NSGraphicsContext.current?.cgContext {
+ // Add emitted light under the diffuser. Conversion from linear RGB
+ // happens here, after multiplication by the guest's master level.
+ context.setBlendMode(.screen)
+ for (point, rgb) in zip(geometry.normalizedPoints, displayFrame.pixels) {
+ let scaled = rgb.map { $0 * displayFrame.brightness }
+ guard scaled.contains(where: { $0 > 0 }) else { continue }
+ let center = CGPoint(x: cap.minX + point.x * cap.width, y: cap.minY + point.y * cap.height)
+ let color = NSColor(srgbRed: Self.sRGB(scaled[0]), green: Self.sRGB(scaled[1]), blue: Self.sRGB(scaled[2]), alpha: 1)
+ if let glow = NSGradient(colorsAndLocations: (color.withAlphaComponent(0.84), 0), (color.withAlphaComponent(0.32), 0.32), (color.withAlphaComponent(0), 1)) {
+ glow.draw(fromCenter: center, radius: 0, toCenter: center, radius: cap.width * 0.24, options: [])
+ }
+ }
+ }
+ NSGraphicsContext.restoreGraphicsState()
+ NSColor(calibratedWhite: 0.20, alpha: 1).setStroke()
+ path.lineWidth = 1
+ path.stroke()
+ }
+
+ private static func sRGB(_ linear: Double) -> Double {
+ linear <= 0.0031308 ? linear * 12.92 : 1.055 * pow(linear, 1 / 2.4) - 0.055
+ }
+}
+
+// MARK: - Capacitive Hit Areas
+
+/// The pointer's up event returns to its original view even after dragging
+/// outside it. Keeping down/up separate also lets the guest recognize holds.
+@MainActor
+private final class VPhoneHomePodCapControl: NSButton {
+ let control: VPhoneHomePodDisplayView.Control
+ var onChange: ((VPhoneHomePodDisplayView.Control, Bool, Duration) -> Void)?
+ var illumination: Double = 0 { didSet { needsDisplay = true } }
+ private var isPressed = false
+
+ init(control: VPhoneHomePodDisplayView.Control, label: String) {
+ self.control = control
+ super.init(frame: .zero)
+ title = ""
+ isBordered = false
+ setButtonType(.momentaryPushIn)
+ target = self
+ action = #selector(activateControl)
+ setAccessibilityElement(true)
+ setAccessibilityRole(.button)
+ setAccessibilityLabel(label)
+ setAccessibilityHelp(control == .surface ? "Click or hold to touch the HomePod top surface." : "Click or hold to change the HomePod volume.")
+ toolTip = label
+ }
+
+ required init?(coder: NSCoder) { nil }
+ override var acceptsFirstResponder: Bool { true }
+ override var canBecomeKeyView: Bool { true }
+ override var isFlipped: Bool { true }
+ override var focusRingType: NSFocusRingType { get { .exterior } set {} }
+
+ override func hitTest(_ point: NSPoint) -> NSView? {
+ let local = convert(point, from: superview)
+ let radius = min(bounds.width, bounds.height) / 2
+ guard hypot(local.x - bounds.midX, local.y - bounds.midY) <= radius else { return nil }
+ return super.hitTest(point)
+ }
+
+ override func mouseDown(with event: NSEvent) {
+ window?.makeFirstResponder(self)
+ pressControl()
+ }
+
+ override func mouseUp(with event: NSEvent) { finishPress() }
+
+ override func keyDown(with event: NSEvent) {
+ if event.keyCode == 48 {
+ if event.modifierFlags.contains(.shift) { window?.selectPreviousKeyView(self) }
+ else { window?.selectNextKeyView(self) }
+ } else if event.keyCode == 49 || event.keyCode == 36 { pressControl() }
+ else { super.keyDown(with: event) }
+ }
+
+ override func keyUp(with event: NSEvent) {
+ if event.keyCode == 49 || event.keyCode == 36 { finishPress() }
+ else { super.keyUp(with: event) }
+ }
+
+ override func resignFirstResponder() -> Bool {
+ releaseControl()
+ return super.resignFirstResponder()
+ }
+
+ override func accessibilityPerformPress() -> Bool {
+ guard !isPressed else { return false }
+ activateControl()
+ return true
+ }
+
+ @objc private func activateControl() {
+ pressControl()
+ finishPress()
+ }
+
+ private func finishPress() {
+ // Give even instantaneous mouse/AX taps a usable consumer-key hold.
+ // The queue measures this from the guest's key-down acknowledgement.
+ releaseControl(minimumHold: .milliseconds(700))
+ }
+
+ private func pressControl() {
+ guard !isPressed else { return }
+ isPressed = true
+ onChange?(control, true, .zero)
+ }
+
+ func releaseControl(minimumHold: Duration = .zero) {
+ guard isPressed else { return }
+ isPressed = false
+ onChange?(control, false, minimumHold)
+ }
+
+ override func draw(_ dirtyRect: NSRect) {
+ guard control != .surface else { return }
+ // The button LEDs are independent output channels, including off.
+ let level = illumination <= 0.0031308 ? illumination * 12.92 : 1.055 * pow(illumination, 1 / 2.4) - 0.055
+ NSColor(calibratedWhite: level, alpha: 1).setStroke()
+ let path = NSBezierPath()
+ let length = bounds.width * 0.40
+ path.move(to: NSPoint(x: bounds.midX - length / 2, y: bounds.midY))
+ path.line(to: NSPoint(x: bounds.midX + length / 2, y: bounds.midY))
+ if control == .volumeUp {
+ path.move(to: NSPoint(x: bounds.midX, y: bounds.midY - length / 2))
+ path.line(to: NSPoint(x: bounds.midX, y: bounds.midY + length / 2))
+ }
+ path.lineWidth = max(1.5, bounds.width * 0.035)
+ path.lineCapStyle = .round
+ path.stroke()
+ }
+
+ override func drawFocusRingMask() { NSBezierPath(ovalIn: bounds.insetBy(dx: 2, dy: 2)).fill() }
+ override var focusRingMaskBounds: NSRect { bounds }
+}
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/VPhoneVirtualMachineWindowController.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/VPhoneVirtualMachineWindowController.swift
index ebb4cb29..9eef0f1a 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/VPhoneVirtualMachineWindowController.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/VPhoneVirtualMachineWindowController.swift
@@ -8,6 +8,8 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
private var windowController: NSWindowController?
private weak var control: VPhoneGuestControl?
private weak var virtualMachineView: VPhoneVirtualMachineView?
+ private(set) var homePodDisplayView: VPhoneHomePodDisplayView?
+ private var homePodGuest = false
private(set) var touchIDMonitor: VPhoneTouchIDMonitor?
private var homeButton: NSButton?
/// An Apple TV's TV button: holding the titlebar button holds it in the
@@ -39,28 +41,60 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
control: VPhoneGuestControl,
name: String,
sceneIdentifier: String,
+ homePodGuest: Bool = false,
) {
self.control = control
+ self.homePodGuest = homePodGuest
+ homeButton = nil
let view = VPhoneVirtualMachineView()
view.virtualMachine = vm
view.hardwareKeyboardEnabled = hardwareKeyboardEnabled
- view.capturesSystemKeys = hardwareKeyboardEnabled
+ view.capturesSystemKeys = hardwareKeyboardEnabled && !homePodGuest
view.keySender = keySender
view.control = control
view.screenScale = CGFloat(screenScale)
view.clipboardSync = VPhoneClipboardSync(control: control)
virtualMachineView = view
- let container = VPhoneDisplayContainerView(displayView: view)
- displayContainer = container
-
let scale = CGFloat(screenScale)
- let windowSize = NSSize(
+ let windowSize = homePodGuest ? NSSize(width: 360, height: 360) : NSSize(
width: CGFloat(screenWidth) / scale,
height: CGFloat(screenHeight) / scale,
)
panelSize = windowSize
- container.panelSize = windowSize
+ let container: NSView
+ if homePodGuest {
+ let cap = VPhoneHomePodDisplayView()
+ cap.onControlChange = { [weak self] button, down, minimumHold in
+ guard let control = self?.control else { return }
+ let usage: UInt32
+ switch button {
+ case .volumeUp: usage = 0xE9
+ case .volumeDown: usage = 0xEA
+ case .surface: return
+ }
+ if down {
+ guard control.isConnected else { return }
+ control.sendHIDDown(page: 0x0C, usage: usage)
+ } else {
+ control.sendHIDUp(page: 0x0C, usage: usage, minimumHold: minimumHold)
+ }
+ }
+ // Keep the diagnostic framebuffer attached for host automation,
+ // while the HomePod's visible output is its physical LED surface.
+ view.frame = NSRect(origin: .zero, size: windowSize)
+ view.isHidden = true
+ cap.addSubview(view, positioned: .below, relativeTo: nil)
+ homePodDisplayView = cap
+ displayContainer = nil
+ container = cap
+ } else {
+ let display = VPhoneDisplayContainerView(displayView: view)
+ display.panelSize = windowSize
+ displayContainer = display
+ homePodDisplayView = nil
+ container = display
+ }
let window = NSWindow(
contentRect: NSRect(origin: .zero, size: windowSize),
@@ -89,7 +123,7 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
observeKeyState(of: window)
// A frame saved while the guest was sideways is turned back: the guest
// boots in portrait, and the orientation poll turns it again if not.
- applyOrientation(.portrait, to: window, force: true)
+ if !homePodGuest { applyOrientation(.portrait, to: window, force: true) }
// An empty unified toolbar gives the title bar its full height. The Home
// button is a titlebar accessory rather than a toolbar item so that a
@@ -99,11 +133,15 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
toolbar.allowsDisplayModeCustomization = false
window.toolbar = toolbar
window.toolbarStyle = .unified
- let homeAccessory = makeHomeAccessory()
- window.addTitlebarAccessoryViewController(homeAccessory)
- updateHomeButton(connected: false)
+ var trailingInset: CGFloat = 0
+ if !homePodGuest {
+ let homeAccessory = makeHomeAccessory()
+ window.addTitlebarAccessoryViewController(homeAccessory)
+ updateHomeButton(connected: false)
+ trailingInset = homeAccessory.view.frame.width
+ }
pinWindowButtons(in: window)
- installTitle(name, in: window, trailingInset: homeAccessory.view.frame.width)
+ installTitle(name, in: window, trailingInset: trailingInset)
let controller = NSWindowController(window: window)
controller.showWindow(nil)
@@ -113,11 +151,14 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
NSApp.activate(ignoringOtherApps: true)
window.makeKeyAndOrderFront(nil)
placeWindowButtons()
- window.makeFirstResponder(view)
-
- let monitor = VPhoneTouchIDMonitor()
- monitor.start(control: control, window: window)
- touchIDMonitor = monitor
+ if let homePodDisplayView {
+ homePodDisplayView.focusControls()
+ } else {
+ window.makeFirstResponder(view)
+ let monitor = VPhoneTouchIDMonitor()
+ monitor.start(control: control, window: window)
+ touchIDMonitor = monitor
+ }
// Poll vphoned status for the Home button and the subtitle
timers.append(Timer.scheduledTimer(withTimeInterval: 2, repeats: true) { [weak self] _ in
@@ -131,28 +172,42 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
// The menu sets the orientation before the guest turns, and the poll
// after; either way the window follows it.
- control.observeInterfaceOrientation { [weak self, weak window] orientation in
- guard let self, let window else { return }
- applyOrientation(orientation ?? .portrait, to: window)
+ if !homePodGuest {
+ control.observeInterfaceOrientation { [weak self, weak window] orientation in
+ guard let self, let window else { return }
+ applyOrientation(orientation ?? .portrait, to: window)
+ }
+ timers.append(Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { [weak self] _ in
+ Task { @MainActor in self?.pollOrientation() }
+ })
}
- timers.append(Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { [weak self] _ in
- Task { @MainActor in self?.pollOrientation() }
- })
setFrameRateDisplay(VPhoneFrameRateDisplay.isEnabled)
}
+ // MARK: - HomePod Display
+
+ func updateHomePodDisplay(geometry: VPhoneHomePodDisplayGeometry, frame: VPhoneHomePodDisplayFrame) {
+ homePodDisplayView?.update(geometry: geometry, frame: frame)
+ }
+
+ func clearHomePodDisplay() {
+ homePodDisplayView?.clearDisplay()
+ }
+
// MARK: - Close
/// Closing the display window stops the VM, so the close button asks the
/// same question as ⌘Q, with the window still up, instead of closing
/// first. `closeForRestart` closes without asking.
func windowShouldClose(_: NSWindow) -> Bool {
+ homePodDisplayView?.releaseControls()
NSApp.terminate(nil)
return false
}
/// Disconnect the old display and input devices before rebuilding the VM.
func closeForRestart() {
+ clearHomePodDisplay()
timers.forEach { $0.invalidate() }
timers.removeAll()
frameRateTimer?.invalidate()
@@ -168,6 +223,7 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
captureView?.clipboardSync = nil
windowController?.close()
windowController = nil
+ homePodDisplayView = nil
VPhoneHostHotKeys.shared.resume()
}
@@ -223,7 +279,7 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
let center = NotificationCenter.default
keyStateObservers.append(center.addObserver(forName: NSWindow.didBecomeKeyNotification, object: window, queue: .main) { [weak self] _ in
MainActor.assumeIsolated {
- if self?.captureView?.hardwareKeyboardEnabled == true {
+ if self?.homePodGuest == false, self?.captureView?.hardwareKeyboardEnabled == true {
VPhoneHostHotKeys.shared.suspend()
}
}
@@ -233,7 +289,7 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
MainActor.assumeIsolated { VPhoneHostHotKeys.shared.resume() }
})
}
- if window.isKeyWindow, captureView?.hardwareKeyboardEnabled == true {
+ if window.isKeyWindow, !homePodGuest, captureView?.hardwareKeyboardEnabled == true {
VPhoneHostHotKeys.shared.suspend()
}
@@ -343,7 +399,7 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
var parts: [String] = []
if control.isConnected {
if let version = control.guestIOSVersion, !version.isEmpty {
- parts.append("iOS \(version)")
+ parts.append("\(homePodGuest ? "HomePod" : "iOS") \(version)")
}
if let address = control.guestIPAddress, !address.isEmpty {
parts.append(address)
@@ -367,7 +423,7 @@ class VPhoneVirtualMachineWindowController: NSObject, NSWindowDelegate {
frameRateTimer?.invalidate()
frameRateTimer = nil
frameRate = nil
- if enabled, VPhoneFrameRateMeter.isAvailable {
+ if enabled, !homePodGuest, VPhoneFrameRateMeter.isAvailable {
_ = VPhoneFrameRateMeter.takeFrameCount()
frameRateSampledAt = CACurrentMediaTime()
frameRate = 0
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift
index b05a8c0a..91e81a82 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift
@@ -33,6 +33,7 @@ extension VPhoneBootCommand {
kernelDebugPort: kernelDebugPort,
isPadGuest: manifest.guestDevice.isPad,
isTVGuest: manifest.guestDevice.family == .appleTV,
+ isHomePodGuest: manifest.guestDevice.family == .homePod,
)
}
}
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneVirtualMachineAppDelegate.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneVirtualMachineAppDelegate.swift
index 5871dd2b..3db01bea 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneVirtualMachineAppDelegate.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneVirtualMachineAppDelegate.swift
@@ -8,6 +8,7 @@ class VPhoneVirtualMachineAppDelegate: NSObject, NSApplicationDelegate {
private var vm: VPhoneVirtualMachine?
private var control: VPhoneGuestControl?
private var windowController: VPhoneVirtualMachineWindowController?
+ private var homePodDisplayTask: Task<Void, Never>?
private var menuController: VPhoneMenuController?
private var fileWindowController: VPhoneFileWindowController?
private var keychainWindowController: VPhoneKeychainWindowController?
@@ -114,7 +115,7 @@ class VPhoneVirtualMachineAppDelegate: NSObject, NSApplicationDelegate {
self.control = control
if !command.dfu {
control.unlocksAtStartup = vm.unlocksAtStartup
- control.syncsGuestEnvironment = !options.isTVGuest
+ control.syncsGuestEnvironment = !options.isTVGuest && !options.isHomePodGuest
control.syncsHostLocation = vm.syncsHostLocation
control.guestDeviceName = Self.guestDeviceName(forConfig: options.configURL)
startNetworkServices(vm: vm, control: control)
@@ -176,11 +177,44 @@ class VPhoneVirtualMachineAppDelegate: NSObject, NSApplicationDelegate {
.standardizedFileURL
.resolvingSymlinksInPath()
.path,
+ homePodGuest: options.isHomePodGuest,
)
wc.captureView?.escapeIsBackGesture = !options.isPadGuest && !options.isTVGuest
wc.captureView?.isTVGuest = options.isTVGuest
wc.homeButtonHoldsInGuest = options.isTVGuest
windowController = wc
+ if options.isHomePodGuest {
+ homePodDisplayTask = Task { [weak wc, weak control] in
+ // One snapshot in flight, with no queue of stale animation
+ // frames. A slow guest reduces the rate instead of lagging.
+ while !Task.isCancelled {
+ guard let wc, let control else { return }
+ guard let window = wc.displayWindow, window.isVisible, !window.isMiniaturized else {
+ try? await Task.sleep(for: .milliseconds(250))
+ continue
+ }
+ if control.isConnected, control.guestCapabilities.contains("homepod_display") {
+ do {
+ let snapshot = try await control.homePodDisplaySnapshot()
+ guard !Task.isCancelled else { return }
+ if let snapshot {
+ wc.updateHomePodDisplay(geometry: snapshot.geometry, frame: snapshot.frame)
+ } else {
+ wc.clearHomePodDisplay()
+ try? await Task.sleep(for: .seconds(1))
+ }
+ } catch {
+ wc.clearHomePodDisplay()
+ try? await Task.sleep(for: .seconds(1))
+ }
+ } else {
+ wc.clearHomePodDisplay()
+ try? await Task.sleep(for: .milliseconds(250))
+ }
+ try? await Task.sleep(for: .milliseconds(16))
+ }
+ }
+ }
let fileWC = VPhoneFileWindowController()
fileWindowController = fileWC
@@ -469,6 +503,9 @@ class VPhoneVirtualMachineAppDelegate: NSObject, NSApplicationDelegate {
@MainActor
private func stopControlServices() {
+ homePodDisplayTask?.cancel()
+ homePodDisplayTask = nil
+ windowController?.clearHomePodDisplay()
hostAutomationServer?.stop()
portForwarder?.stop()
apiProxy?.stop()
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
index b4e84168..d6e06063 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
@@ -48,6 +48,7 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {
/// The guest runs iPadOS: Esc is a key there, not the back gesture.
var isPadGuest = false
var isTVGuest = false
+ var isHomePodGuest = false
}
private struct DeviceIdentity {
diff --git a/VPhoneGuestComponents/HomePodDisplay/libvphonehomepoddisplay.m b/VPhoneGuestComponents/HomePodDisplay/libvphonehomepoddisplay.m
new file mode 100644
index 00000000..87b75b37
--- /dev/null
+++ b/VPhoneGuestComponents/HomePodDisplay/libvphonehomepoddisplay.m
@@ -0,0 +1,173 @@
+#import <Foundation/Foundation.h>
+#import <objc/runtime.h>
+#include <dlfcn.h>
+
+// IOHIDUserDevice deliberately rejects reserved IOKit properties, including
+// IOClass. MiniDisplay's HW3 path tests that property before reading MDHWVersion.
+// Supply the identity only for our own virtual device; Apple's renderer and
+// every frame submission remain untouched.
+static id (*VPHomePodOriginalProperty)(id, SEL, NSString *, NSError **);
+static void (*VPHomePodOriginalDeviceAdded)(id, SEL, CFTypeRef);
+static BOOL (*VPHomePodOriginalSubmit)(id, SEL, id, NSError **);
+static char VPHomePodLastRecovery;
+#ifdef VP_HOMEPOD_DISPLAY_TESTING
+extern CFTypeRef VPHomePodHIDProperty(CFTypeRef, CFStringRef);
+extern int VPHomePodHIDOpen(CFTypeRef);
+extern void VPHomePodHIDClose(CFTypeRef);
+extern CFTypeRef VPHomePodCopyDisplay(void);
+#else
+static CFTypeRef VPHomePodHIDProperty(CFTypeRef device, CFStringRef key) {
+ CFTypeRef (*get)(CFTypeRef, CFStringRef) = dlsym(RTLD_DEFAULT, "IOHIDDeviceGetProperty");
+ return get ? get(device, key) : NULL;
+}
+static int VPHomePodHIDOpen(CFTypeRef device) {
+ int (*open)(CFTypeRef, uint32_t) = dlsym(RTLD_DEFAULT, "IOHIDDeviceOpen");
+ return open ? open(device, 0) : -1;
+}
+static void VPHomePodHIDClose(CFTypeRef device) {
+ int (*close)(CFTypeRef, uint32_t) = dlsym(RTLD_DEFAULT, "IOHIDDeviceClose");
+ if (close) close(device, 0);
+}
+
+// Enumerate immediately, without _findDevice's 30-second semaphore wait. A
+// failed submission may happen while vphoned is still restarting.
+static CFTypeRef VPHomePodCopyDisplay(void) {
+ CFTypeRef (*create)(CFAllocatorRef, uint32_t) = dlsym(RTLD_DEFAULT, "IOHIDManagerCreate");
+ void (*match)(CFTypeRef, CFDictionaryRef) = dlsym(RTLD_DEFAULT, "IOHIDManagerSetDeviceMatching");
+ int (*open)(CFTypeRef, uint32_t) = dlsym(RTLD_DEFAULT, "IOHIDManagerOpen");
+ CFSetRef (*copy)(CFTypeRef) = dlsym(RTLD_DEFAULT, "IOHIDManagerCopyDevices");
+ int (*close)(CFTypeRef, uint32_t) = dlsym(RTLD_DEFAULT, "IOHIDManagerClose");
+ if (!create || !match || !open || !copy || !close) return NULL;
+ CFTypeRef manager = create(kCFAllocatorDefault, 0);
+ if (!manager) return NULL;
+ match(manager, (__bridge CFDictionaryRef)@{@"PhysicalDeviceUniqueID": @"vphone-homepod-mini-display"});
+ CFTypeRef found = NULL;
+ if (open(manager, 0) == 0) {
+ CFSetRef devices = copy(manager);
+ if (devices) {
+ for (id device in (__bridge NSSet *)devices) {
+ id identity = (__bridge id)VPHomePodHIDProperty((__bridge CFTypeRef)device, CFSTR("PhysicalDeviceUniqueID"));
+ if ([identity isKindOfClass:NSString.class] && [identity isEqualToString:@"vphone-homepod-mini-display"]) {
+ found = CFRetain((__bridge CFTypeRef)device);
+ break;
+ }
+ }
+ CFRelease(devices);
+ }
+ close(manager, 0);
+ }
+ CFRelease(manager);
+ return found;
+}
+#endif
+
+static bool VPHomePodIsVirtualDisplay(id identity) {
+ return [identity isKindOfClass:NSString.class] && [identity isEqualToString:@"vphone-homepod-mini-display"];
+}
+
+static void VPHomePodDisplayDeviceAdded(id receiver, SEL selector, CFTypeRef device) {
+ id identity = device ? (__bridge id)VPHomePodHIDProperty(device, CFSTR("PhysicalDeviceUniqueID")) : nil;
+ if (!VPHomePodIsVirtualDisplay(identity)) {
+ VPHomePodOriginalDeviceAdded(receiver, selector, device);
+ return;
+ }
+ // deviceAdded: also tests IOClass directly in the registry. For our device
+ // perform its normal retain/open/signal sequence using runtime ivars, never
+ // firmware-specific object offsets. The original close/dealloc owns release.
+ Ivar deviceIvar = class_getInstanceVariable([receiver class], "_device");
+ Ivar semaphoreIvar = class_getInstanceVariable([receiver class], "_sema");
+ if (!deviceIvar || !semaphoreIvar) return;
+ uint8_t *storage = (uint8_t *)(__bridge void *)receiver + ivar_getOffset(deviceIvar);
+ CFTypeRef previous = NULL;
+ memcpy(&previous, storage, sizeof(previous));
+ if (previous || VPHomePodHIDOpen(device) != 0) return;
+ CFTypeRef retained = CFRetain(device);
+ memcpy(storage, &retained, sizeof(retained));
+ dispatch_semaphore_t semaphore = object_getIvar(receiver, semaphoreIvar);
+ if (semaphore) dispatch_semaphore_signal(semaphore);
+}
+
+static id VPHomePodDisplayProperty(id receiver, SEL selector, NSString *key, NSError **error) {
+ if ([key isEqualToString:@"IOClass"]) {
+ id identity = VPHomePodOriginalProperty(receiver, selector, @"PhysicalDeviceUniqueID", NULL);
+ if (VPHomePodIsVirtualDisplay(identity)) {
+ return @"MiniDisplayDriver";
+ }
+ }
+ return VPHomePodOriginalProperty(receiver, selector, key, error);
+}
+
+static BOOL VPHomePodSubmitFrame(id receiver, SEL selector, id frame, NSError **error) {
+ NSError *submissionError = nil;
+ if (VPHomePodOriginalSubmit(receiver, selector, frame, &submissionError)) return YES;
+ Ivar ivar = class_getInstanceVariable([receiver class], "_device");
+ uint8_t *storage = (uint8_t *)(__bridge void *)receiver + ivar_getOffset(ivar);
+ CFTypeRef previous = NULL;
+ memcpy(&previous, storage, sizeof(previous));
+ id identity = previous ? (__bridge id)VPHomePodHIDProperty(previous, CFSTR("PhysicalDeviceUniqueID")) : nil;
+ if (VPHomePodIsVirtualDisplay(identity)) {
+ // SoundBoard retains its HID interface across a daemon restart. Only
+ // replace our failed virtual handle, and leave frame generation alone.
+ NSTimeInterval now = NSProcessInfo.processInfo.systemUptime;
+ NSNumber *last = objc_getAssociatedObject(receiver, &VPHomePodLastRecovery);
+ if (!last || now - last.doubleValue >= 1) {
+ objc_setAssociatedObject(receiver, &VPHomePodLastRecovery, @(now), OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+ CFTypeRef replacement = VPHomePodCopyDisplay();
+ if (replacement && replacement != previous && VPHomePodHIDOpen(replacement) == 0) {
+ VPHomePodHIDClose(previous);
+ memcpy(storage, &replacement, sizeof(replacement));
+ CFRelease(previous);
+ submissionError = nil;
+ BOOL result = VPHomePodOriginalSubmit(receiver, selector, frame, &submissionError);
+ if (!result && error) *error = submissionError;
+ return result;
+ }
+ if (replacement) CFRelease(replacement);
+ }
+ }
+ if (error) *error = submissionError;
+ return NO;
+}
+
+bool VPHomePodInstallDisplayIdentity(void) {
+ static bool installed;
+ if (installed) return true;
+ Class interface = NSClassFromString(@"MDInterfaceHID");
+ Method method = class_getInstanceMethod(interface, NSSelectorFromString(@"_getPropertyForKey:error:"));
+ Method added = class_getInstanceMethod(interface, NSSelectorFromString(@"deviceAdded:"));
+ Method submit = class_getInstanceMethod(interface, NSSelectorFromString(@"submitFrame:error:"));
+ // Fail visibly on a changed framework instead of guessing a method ABI.
+ if (!method || method_getNumberOfArguments(method) != 4 || !added || method_getNumberOfArguments(added) != 3 ||
+ !submit || method_getNumberOfArguments(submit) != 4 ||
+ !class_getInstanceVariable(interface, "_device") || !class_getInstanceVariable(interface, "_sema")) return false;
+ char returnType[16] = {0};
+ method_getReturnType(method, returnType, sizeof(returnType));
+ if (strcmp(returnType, @encode(id)) != 0) return false;
+ method_getReturnType(added, returnType, sizeof(returnType));
+ if (strcmp(returnType, @encode(void)) != 0) return false;
+ char argumentType[128] = {0};
+ method_getArgumentType(added, 2, argumentType, sizeof(argumentType));
+ if (argumentType[0] != '^') return false;
+ method_getReturnType(submit, returnType, sizeof(returnType));
+ if (strcmp(returnType, @encode(BOOL)) != 0) return false;
+ VPHomePodOriginalProperty = (void *)method_setImplementation(method, (IMP)VPHomePodDisplayProperty);
+ VPHomePodOriginalDeviceAdded = (void *)method_setImplementation(added, (IMP)VPHomePodDisplayDeviceAdded);
+ VPHomePodOriginalSubmit = (void *)method_setImplementation(submit, (IMP)VPHomePodSubmitFrame);
+ installed = true;
+ return true;
+}
+
+#ifndef VP_HOMEPOD_DISPLAY_TESTING
+__attribute__((constructor)) static void VPHomePodDisplayInitialize(void) {
+ @autoreleasepool {
+ // The executable load command limits this library to SoundBoard. dlopen ensures
+ // its MiniDisplay class is registered before we install the adapter.
+ void *framework = dlopen("/System/Library/PrivateFrameworks/MiniDisplay.framework/MiniDisplay", RTLD_NOW);
+ if (!framework || !VPHomePodInstallDisplayIdentity()) {
+ NSLog(@"vphone HomePod display: MiniDisplay identity adapter unavailable");
+ } else {
+ NSLog(@"vphone HomePod display: virtual MiniDisplay identity adapter ready");
+ }
+ }
+}
+#endif
diff --git a/VPhoneGuestComponents/Makefile b/VPhoneGuestComponents/Makefile
index 817542a9..793037d4 100644
--- a/VPhoneGuestComponents/Makefile
+++ b/VPhoneGuestComponents/Makefile
@@ -95,6 +95,8 @@ ACCELEROMETER_INPUTS := $(call find_headers,Accelerometer) $(call find_folders,A
ATTITUDE := $(STAGE)/attitude/libvphoneattitude.dylib
ATTITUDE_SOURCES := $(call find_sources,Attitude)
ATTITUDE_INPUTS := $(call find_headers,Attitude) $(call find_folders,Attitude) Shared/AttitudeProcess.h
+HOMEPODDISPLAY := $(STAGE)/homepoddisplay/libvphonehomepoddisplay.dylib
+HOMEPODDISPLAY_SOURCES := $(call find_sources,HomePodDisplay)
GPU_PLUGIN := $(STAGE)/gpu/libAppleParavirtCompilerPluginIOGPUFamily.dylib
GPU_PLUGIN_SOURCES := $(wildcard GraphicLoader/*.mm)
GPU_PLUGIN_INCLUDES := $(wildcard GraphicLoader/*.h GraphicLoader/*.hpp GraphicLoader/*.inc)
@@ -128,7 +130,7 @@ GPU_DYNAMIC_LOOKUP_SYMS := \
VIRTIOSOUND := $(STAGE)/virtiosound/VPhoneVirtIOSound.driver
VIRTIOSOUND_SOURCES := $(wildcard VirtIOSound/*.m VirtIOSound/*.c)
VIRTIOSOUND_INCLUDES := $(wildcard VirtIOSound/*.h) VirtIOSound/Info.plist VirtIOSound/AudioServerDriver.tbd
-ARTIFACTS := $(CAMFIX) $(VCAMCAPTURED) $(LAUNCHHOOK) $(SYSTEMHOOK) $(MISFIX) $(HAPTICSFIX) $(BATTERYHEALTHFIX) $(DEVICEHUBFIX) $(DEVICENAME) $(PREFSFIX) $(SIGNINFIX) $(GYROSCOPE) $(ACCELEROMETER) $(ATTITUDE) $(GPU_PLUGIN) $(VIRTIOSOUND)
+ARTIFACTS := $(CAMFIX) $(VCAMCAPTURED) $(LAUNCHHOOK) $(SYSTEMHOOK) $(MISFIX) $(HAPTICSFIX) $(BATTERYHEALTHFIX) $(DEVICEHUBFIX) $(DEVICENAME) $(PREFSFIX) $(SIGNINFIX) $(GYROSCOPE) $(ACCELEROMETER) $(ATTITUDE) $(HOMEPODDISPLAY) $(GPU_PLUGIN) $(VIRTIOSOUND)
PLISTS := $(STAGE)/camfix/libcamfix.plist $(STAGE)/vcamcaptured/libvcamcaptured.plist \
$(STAGE)/misfix/libmisfix.plist
GPU_PROVENANCE := $(STAGE)/gpu/README.md
@@ -139,11 +141,18 @@ GPU_PROVENANCE := $(STAGE)/gpu/README.md
all: $(ARTIFACTS) $(PLISTS) $(GPU_PROVENANCE)
+.PHONY: test-homepod-display
+test-homepod-display:
+ @mkdir -p $(OUT)
+ xcrun --sdk macosx clang -fobjc-arc -Wall -Wextra -Werror -DVP_HOMEPOD_DISPLAY_TESTING \
+ -o $(OUT)/HomePodDisplayIdentityTests Tests/HomePodDisplayIdentityTests.m $(HOMEPODDISPLAY_SOURCES) -framework Foundation
+ @$(OUT)/HomePodDisplayIdentityTests
+
gpu: $(GPU_PLUGIN)
package: all
@rm -f $(ARCHIVE)
- @/usr/bin/tar -cf $(ARCHIVE) -C $(STAGE) camfix vcamcaptured launchhook systemhook misfix hapticsfix batteryhealthfix devicehubfix devicename prefsfix signinfix gyroscope accelerometer attitude gpu virtiosound
+ @/usr/bin/tar -cf $(ARCHIVE) -C $(STAGE) camfix vcamcaptured launchhook systemhook misfix hapticsfix batteryhealthfix devicehubfix devicename prefsfix signinfix gyroscope accelerometer attitude homepoddisplay gpu virtiosound
@echo "Packaged $(ARCHIVE)"
test-loader-links:
@@ -336,6 +345,13 @@ $(ATTITUDE): $(ATTITUDE_SOURCES) $(ATTITUDE_INPUTS) | $(STAGE)/attitude
-framework Foundation -framework CoreMotion -Wl,-not_for_dyld_shared_cache
@codesign --force --sign - $@
+$(HOMEPODDISPLAY): $(HOMEPODDISPLAY_SOURCES)
+ @mkdir -p $(STAGE)/homepoddisplay
+ xcrun --sdk appletvos clang -arch arm64e -mtvos-version-min=27.0 -Os -fobjc-arc \
+ -Wall -Wextra -Werror -dynamiclib -install_name /usr/lib/libvphonehomepoddisplay.dylib \
+ -o $@ $(HOMEPODDISPLAY_SOURCES) -framework Foundation -Wl,-not_for_dyld_shared_cache
+ @codesign --force --sign - $@
+
.PHONY: test-attitude
test-attitude:
@mkdir -p $(OUT)
diff --git a/VPhoneGuestComponents/README.md b/VPhoneGuestComponents/README.md
index 0fca21e8..4e744cd9 100644
--- a/VPhoneGuestComponents/README.md
+++ b/VPhoneGuestComponents/README.md
@@ -1,7 +1,7 @@
# Sibling guest components
`make -C VPhoneGuestComponents package` cross-compiles guest components with
-Xcode's iPhoneOS SDK. The archive contains signed arm64e binaries, two camera
+Xcode's iPhoneOS SDK (the HomePod adapter uses the tvOS SDK). The archive contains signed arm64e binaries, two camera
tweak filter plists, and the GPU provenance note:
| Component | Archive contents |
@@ -15,6 +15,7 @@ tweak filter plists, and the GPU provenance note:
| Virtual gyroscope | `gyroscope/libvphonegyro.dylib` |
| Gravity accelerometer | `accelerometer/libvphoneaccelerometer.dylib` |
| Device attitude | `attitude/libvphoneattitude.dylib` |
+| HomePod display identity | `homepoddisplay/libvphonehomepoddisplay.dylib` |
| Launchd hook | `launchhook/launchdhook-vphone.dylib` |
| Process injection bridge | `systemhook/SystemHook-vphone.dylib` |
| iOS 27 app registrar | `vpregister/vpregister` |
diff --git a/VPhoneGuestComponents/Tests/HomePodDisplayIdentityTests.m b/VPhoneGuestComponents/Tests/HomePodDisplayIdentityTests.m
new file mode 100644
index 00000000..0654d1c1
--- /dev/null
+++ b/VPhoneGuestComponents/Tests/HomePodDisplayIdentityTests.m
@@ -0,0 +1,90 @@
+#import <Foundation/Foundation.h>
+#include <assert.h>
+extern bool VPHomePodInstallDisplayIdentity(void);
+
+static int opens;
+static int closes;
+static int scans;
+static CFTypeRef replacement;
+static CFTypeRef failedDevice;
+CFTypeRef VPHomePodHIDProperty(CFTypeRef device, CFStringRef key) { return CFDictionaryGetValue(device, key); }
+int VPHomePodHIDOpen(CFTypeRef device) { (void)device; opens++; return 0; }
+void VPHomePodHIDClose(CFTypeRef device) { (void)device; closes++; }
+CFTypeRef VPHomePodCopyDisplay(void) { scans++; return replacement ? CFRetain(replacement) : NULL; }
+
+@interface MDInterfaceHID : NSObject {
+@public
+ CFTypeRef _device;
+ dispatch_semaphore_t _sema;
+}
+@property NSDictionary *properties;
+@property int originalAddedCount;
+- (id)_getPropertyForKey:(NSString *)key error:(NSError **)error;
+- (void)deviceAdded:(CFTypeRef)device;
+- (BOOL)submitFrame:(id)frame error:(NSError **)error;
+@end
+@implementation MDInterfaceHID
+- (void)deviceAdded:(CFTypeRef)device { (void)device; self.originalAddedCount++; }
+- (void)dealloc { if (_device) CFRelease(_device); }
+- (BOOL)submitFrame:(id)frame error:(NSError **)error {
+ (void)frame;
+ if (_device == failedDevice) {
+ if (error) *error = [NSError errorWithDomain:@"OriginalSubmit" code:1 userInfo:nil];
+ return NO;
+ }
+ return YES;
+}
+- (id)_getPropertyForKey:(NSString *)key error:(NSError **)error {
+ id value = self.properties[key];
+ if (!value && error) *error = [NSError errorWithDomain:@"OriginalProperty" code:1 userInfo:nil];
+ return value;
+}
+@end
+
+int main(void) { @autoreleasepool {
+ assert(VPHomePodInstallDisplayIdentity());
+ assert(VPHomePodInstallDisplayIdentity());
+ MDInterfaceHID *device = [MDInterfaceHID new];
+ device.properties = @{@"PhysicalDeviceUniqueID":@"vphone-homepod-mini-display", @"MDHWVersion":@3};
+ assert([[device _getPropertyForKey:@"IOClass" error:NULL] isEqual:@"MiniDisplayDriver"]);
+ assert([[device _getPropertyForKey:@"MDHWVersion" error:NULL] isEqual:@3]);
+ NSError *error = nil;
+ assert([device _getPropertyForKey:@"absent" error:&error] == nil);
+ assert([error.domain isEqual:@"OriginalProperty"]);
+ for (id identity in @[@"other-display", @123, NSNull.null]) {
+ device.properties = @{@"PhysicalDeviceUniqueID":identity,@"IOClass":@"PhysicalDriver"};
+ assert([[device _getPropertyForKey:@"IOClass" error:NULL] isEqual:@"PhysicalDriver"]);
+ }
+ device.properties = @{};
+ error = nil;
+ assert([device _getPropertyForKey:@"IOClass" error:&error] == nil && error != nil);
+ device->_sema = dispatch_semaphore_create(0);
+ NSDictionary *hid = @{@"PhysicalDeviceUniqueID":@"vphone-homepod-mini-display"};
+ [device deviceAdded:(__bridge CFTypeRef)hid];
+ assert(opens == 1 && device->_device == (__bridge CFTypeRef)hid && device.originalAddedCount == 0);
+ assert(dispatch_semaphore_wait(device->_sema, DISPATCH_TIME_NOW) == 0);
+ [device deviceAdded:(__bridge CFTypeRef)hid];
+ assert(opens == 1);
+ [device deviceAdded:(__bridge CFTypeRef)@{@"PhysicalDeviceUniqueID":@"another-device"}];
+ assert(device.originalAddedCount == 1);
+ assert([device submitFrame:@1 error:NULL] && scans == 0);
+ failedDevice = device->_device;
+ NSDictionary *newHID = @{@"PhysicalDeviceUniqueID":@"vphone-homepod-mini-display", @"generation":@2};
+ replacement = (__bridge CFTypeRef)newHID;
+ error = nil;
+ assert([device submitFrame:@1 error:&error] && error == nil);
+ assert(device->_device == replacement && opens == 2 && closes == 1 && scans == 1);
+ // A physical device failure retains its handle and its original error.
+ MDInterfaceHID *physical = [MDInterfaceHID new];
+ physical->_device = CFRetain((__bridge CFTypeRef)@{@"PhysicalDeviceUniqueID":@"physical"});
+ failedDevice = physical->_device;
+ error = nil;
+ assert(![physical submitFrame:@1 error:&error] && [error.domain isEqual:@"OriginalSubmit"]);
+ assert(scans == 1 && closes == 1);
+ // If the virtual replacement has not appeared yet, retries are throttled.
+ failedDevice = device->_device;
+ error = nil;
+ assert(![device submitFrame:@1 error:&error] && [error.domain isEqual:@"OriginalSubmit"]);
+ assert(scans == 1 && device->_device == failedDevice);
+ puts("HomePod display identity tests passed");
+} }
diff --git a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneHomePodDisplay.swift b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneHomePodDisplay.swift
new file mode 100644
index 00000000..0d5f5c11
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneHomePodDisplay.swift
@@ -0,0 +1,108 @@
+import Foundation
+
+// MARK: - HomePod LED Geometry
+
+/// LED order and normalized positions supplied by the guest's device tree.
+/// The fixed-point hardware coordinates already describe the diffuser surface.
+public struct VPhoneHomePodDisplayGeometry: Equatable, Sendable {
+ public struct Point: Equatable, Sendable {
+ public let x: Double
+ public let y: Double
+ public let ring: UInt32
+ }
+
+ public let points: [Point]
+ public let bitDepth: Int
+ public let hardwareVersion: UInt32
+
+ public enum ValidationError: Error, Equatable {
+ case missingProperty(String)
+ case invalidCoordinates
+ case invalidBitDepth
+ case invalidFrame
+ }
+
+ public init(xCoordinates: [Double], yCoordinates: [Double], rings: [UInt32], bitDepth: Int, hardwareVersion: UInt32) throws {
+ guard !xCoordinates.isEmpty, xCoordinates.count <= 1024,
+ xCoordinates.count == yCoordinates.count, xCoordinates.count == rings.count,
+ xCoordinates.allSatisfy({ $0.isFinite && (0 ... 1).contains($0) }),
+ yCoordinates.allSatisfy({ $0.isFinite && (0 ... 1).contains($0) })
+ else { throw ValidationError.invalidCoordinates }
+ guard (1 ... 32).contains(bitDepth) else { throw ValidationError.invalidBitDepth }
+ self.points = zip(zip(xCoordinates, yCoordinates), rings).map { Point(x: $0.0.0, y: $0.0.1, ring: $0.1) }
+ self.bitDepth = bitDepth
+ self.hardwareVersion = hardwareVersion
+ }
+
+ /// Decode the unmodified DT property payloads, not a serialized kernel tree.
+ /// MDX/YCoords are little-endian unsigned 16.16 fixed-point values.
+ public init(deviceTreeProperties properties: [String: Data]) throws {
+ func words(_ name: String) throws -> [UInt32] {
+ guard let data = properties[name] else { throw ValidationError.missingProperty(name) }
+ guard !data.isEmpty, data.count % 4 == 0, data.count <= 4096 else { throw ValidationError.invalidCoordinates }
+ return stride(from: 0, to: data.count, by: 4).map { offset in
+ UInt32(data[data.startIndex + offset]) |
+ UInt32(data[data.startIndex + offset + 1]) << 8 |
+ UInt32(data[data.startIndex + offset + 2]) << 16 |
+ UInt32(data[data.startIndex + offset + 3]) << 24
+ }
+ }
+ let x = try words("MDXCoords").map { Double($0) / 65536 }
+ let y = try words("MDYCoords").map { Double($0) / 65536 }
+ let rings = try words("MDRingCoords")
+ let depth = try words("MDBitDepth")
+ let version = try words("MDHWVersion")
+ guard depth.count == 1, version.count == 1 else { throw ValidationError.invalidCoordinates }
+ try self.init(xCoordinates: x, yCoordinates: y, rings: rings, bitDepth: Int(depth[0]), hardwareVersion: version[0])
+ }
+
+ /// The hardware coordinates already use the full cap's unit square.
+ /// Do not stretch their bounds: the unpopulated border is physical margin.
+ public var normalizedPoints: [Point] { points }
+}
+
+// MARK: - Guest LED Frame
+
+/// A snapshot of guest-controlled LED output. RGB is normalized linear light;
+/// presentation applies the guest brightness without inventing animation.
+public struct VPhoneHomePodDisplayFrame: Equatable, Sendable {
+ public let pixels: [[Double]]
+ public let brightness: Double
+ public let plusBrightness: Double
+ public let minusBrightness: Double
+ public let generation: UInt64
+
+ public init(pixels: [[Double]], brightness: Double = 1, plusBrightness: Double = 0, minusBrightness: Double = 0, generation: UInt64 = 0) throws {
+ func valid(_ value: Double) -> Bool { value.isFinite && (0 ... 1).contains(value) }
+ guard !pixels.isEmpty, pixels.count <= 1024,
+ pixels.allSatisfy({ $0.count == 3 && $0.allSatisfy(valid) }),
+ [brightness, plusBrightness, minusBrightness].allSatisfy(valid)
+ else { throw VPhoneHomePodDisplayGeometry.ValidationError.invalidFrame }
+ self.pixels = pixels
+ self.brightness = brightness
+ self.plusBrightness = plusBrightness
+ self.minusBrightness = minusBrightness
+ self.generation = generation
+ }
+
+ /// The event/RPC envelope owns geometry; a frame must match that geometry
+ /// before replacing the currently displayed snapshot.
+ public func matches(_ geometry: VPhoneHomePodDisplayGeometry) -> Bool {
+ pixels.count == geometry.points.count
+ }
+
+ /// MiniDisplay HW3 carries separate Siri/transient and always-on banks for
+ /// the same emitters. Their light contributes to the same diffuser. HPDS
+ /// has already applied its brightness/LUT to each bank before submission;
+ /// MDDisplayBrightness is a driver feature flag, not a master light level.
+ public init(banks: [[[Double]]], plusBrightness: Double = 0, minusBrightness: Double = 0, generation: UInt64 = 0) throws {
+ guard !banks.isEmpty, banks.count <= 2 else { throw VPhoneHomePodDisplayGeometry.ValidationError.invalidFrame }
+ let frames = try banks.map { try Self(pixels: $0) }
+ guard let first = frames.first, frames.allSatisfy({ $0.pixels.count == first.pixels.count })
+ else { throw VPhoneHomePodDisplayGeometry.ValidationError.invalidFrame }
+ let pixels = first.pixels.indices.map { index in
+ (0 ..< 3).map { channel in min(1, frames.reduce(0) { $0 + $1.pixels[index][channel] }) }
+ }
+ try self.init(pixels: pixels, plusBrightness: plusBrightness, minusBrightness: minusBrightness, generation: generation)
+ }
+}
diff --git a/VPhoneKit/VPhoneCoreKitTests/VirtualMachine/HomePodDisplayTests.swift b/VPhoneKit/VPhoneCoreKitTests/VirtualMachine/HomePodDisplayTests.swift
new file mode 100644
index 00000000..a077dedf
--- /dev/null
+++ b/VPhoneKit/VPhoneCoreKitTests/VirtualMachine/HomePodDisplayTests.swift
@@ -0,0 +1,96 @@
+import Foundation
+import Testing
+@testable import VPhoneCoreKit
+
+struct HomePodDisplayTests {
+ @Test func `Siri and always on banks illuminate the same emitters`() throws {
+ let frame = try VPhoneHomePodDisplayFrame(banks: [[[0.4, 0.1, 0]], [[0.3, 0.2, 1]]], plusBrightness: 0.25, minusBrightness: 0.75)
+ #expect(frame.pixels == [[0.7, 0.1 + 0.2, 1]])
+ #expect(frame.brightness == 1)
+ #expect(frame.plusBrightness == 0.25 && frame.minusBrightness == 0.75)
+ #expect(throws: VPhoneHomePodDisplayGeometry.ValidationError.self) {
+ try VPhoneHomePodDisplayFrame(banks: [[[0, 0, 0]], [[0, 0, 0], [0, 0, 0]]])
+ }
+ #expect(throws: VPhoneHomePodDisplayGeometry.ValidationError.self) {
+ try VPhoneHomePodDisplayFrame(banks: [[[.nan, 0, 0]]])
+ }
+ }
+
+ private func data(_ words: [UInt32]) -> Data {
+ Data(words.flatMap { word in (0 ..< 4).map { UInt8(truncatingIfNeeded: word >> ($0 * 8)) } })
+ }
+
+ @Test func `B520 hardware layout keeps nineteen LEDs and the unlit rim`() throws {
+ let x: [UInt32] = [19752, 32768, 45783, 55312, 58799, 55312, 45784, 32768, 19753, 10224, 6737, 10224, 23240, 36256, 45784, 42296, 29280, 19752, 32768]
+ let y: [UInt32] = [55312, 58799, 55312, 45784, 32768, 19753, 10224, 6737, 10224, 19752, 32768, 45783, 42296, 45784, 36256, 23240, 19752, 29280, 32768]
+ let rings = Array(repeating: UInt32(2), count: 12) + Array(repeating: UInt32(1), count: 6) + [0]
+ let geometry = try VPhoneHomePodDisplayGeometry(deviceTreeProperties: [
+ "MDXCoords": data(x), "MDYCoords": data(y), "MDRingCoords": data(rings),
+ "MDBitDepth": data([12]), "MDHWVersion": data([3]),
+ ])
+ #expect(geometry.points.count == 19)
+ #expect(geometry.normalizedPoints[18].x == 0.5 && geometry.normalizedPoints[18].y == 0.5)
+ #expect(geometry.normalizedPoints[10].x == Double(6737) / 65536)
+ #expect(geometry.normalizedPoints[4].x < 0.9)
+ #expect(geometry.points.filter { $0.ring == 2 }.count == 12)
+ #expect(geometry.points.filter { $0.ring == 1 }.count == 6)
+ }
+
+ @Test func `device tree coordinate payloads preserve LED order and ring membership`() throws {
+ let geometry = try VPhoneHomePodDisplayGeometry(deviceTreeProperties: [
+ "MDXCoords": data([0, 32768, 65536]), "MDYCoords": data([65536, 0, 65536]),
+ "MDRingCoords": data([2, 0, 2]), "MDBitDepth": data([12]), "MDHWVersion": data([3]),
+ ])
+ #expect(geometry.bitDepth == 12 && geometry.hardwareVersion == 3)
+ #expect(geometry.points.map(\.x) == [0, 0.5, 1])
+ #expect(geometry.points.map(\.ring) == [2, 0, 2])
+ #expect(geometry.normalizedPoints.map(\.x) == [0, 0.5, 1])
+ #expect(geometry.normalizedPoints.map(\.y) == [1, 0, 1])
+ }
+
+ @Test func `truncated and mismatched device tree properties are rejected`() {
+ var properties = [
+ "MDXCoords": data([0, 65536]), "MDYCoords": data([0, 65536]),
+ "MDRingCoords": data([0, 1]), "MDBitDepth": data([12]), "MDHWVersion": data([3]),
+ ]
+ properties["MDXCoords"] = Data([0, 1, 2])
+ #expect(throws: VPhoneHomePodDisplayGeometry.ValidationError.self) {
+ try VPhoneHomePodDisplayGeometry(deviceTreeProperties: properties)
+ }
+ properties["MDXCoords"] = data([0])
+ #expect(throws: VPhoneHomePodDisplayGeometry.ValidationError.self) {
+ try VPhoneHomePodDisplayGeometry(deviceTreeProperties: properties)
+ }
+ }
+
+ @Test func `a central LED retains its hardware position`() throws {
+ let geometry = try VPhoneHomePodDisplayGeometry(xCoordinates: [0.5], yCoordinates: [0.5], rings: [0], bitDepth: 12, hardwareVersion: 3)
+ #expect(geometry.normalizedPoints[0].x == 0.5)
+ #expect(geometry.normalizedPoints[0].y == 0.5)
+ }
+
+ @Test func `nonfinite coordinates and unsupported bit depths are rejected`() {
+ #expect(throws: VPhoneHomePodDisplayGeometry.ValidationError.self) {
+ try VPhoneHomePodDisplayGeometry(xCoordinates: [.nan], yCoordinates: [0], rings: [0], bitDepth: 12, hardwareVersion: 3)
+ }
+ #expect(throws: VPhoneHomePodDisplayGeometry.ValidationError.self) {
+ try VPhoneHomePodDisplayGeometry(xCoordinates: [0], yCoordinates: [0], rings: [0], bitDepth: 0, hardwareVersion: 3)
+ }
+ }
+
+ @Test func `malformed frames cannot reach the renderer`() {
+ for pixels in [[], [[0, 1]], [[0, 1, 0, 1]], [[-0.1, 0, 0]], [[0, 1.1, 0]], [[0, .nan, 0]], [[.infinity, 0, 0]]] as [[[Double]]] {
+ #expect(throws: VPhoneHomePodDisplayGeometry.ValidationError.self) { try VPhoneHomePodDisplayFrame(pixels: pixels) }
+ }
+ #expect(throws: VPhoneHomePodDisplayGeometry.ValidationError.self) { try VPhoneHomePodDisplayFrame(pixels: [[1, 0, 0]], brightness: .nan) }
+ #expect(throws: VPhoneHomePodDisplayGeometry.ValidationError.self) { try VPhoneHomePodDisplayFrame(pixels: [[1, 0, 0]], minusBrightness: -1) }
+ }
+
+ @Test func `frames are admitted only for matching device geometry`() throws {
+ let geometry = try VPhoneHomePodDisplayGeometry(xCoordinates: [0, 1], yCoordinates: [0, 1], rings: [0, 1], bitDepth: 12, hardwareVersion: 3)
+ #expect(try VPhoneHomePodDisplayFrame(pixels: [[1, 0, 0]]).matches(geometry) == false)
+ let frame = try VPhoneHomePodDisplayFrame(pixels: [[1, 0, 0], [0, 0.5, 1]], brightness: 0.75, plusBrightness: 0.25, generation: UInt64.max)
+ #expect(frame.matches(geometry))
+ #expect(frame.generation == UInt64.max)
+ }
+}