Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Merge branch 'pr-810' into merge-pr-810

Jacky22556aea12aa
diff --cc Research/0_binary_patch_comparison.md
index a4d258aa,63896008..707f5427
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@@ -6400,135 -6289,96 +6400,229 @@@ with three `Launch Constraint Violatio
(`MobileAssetEarlyBootTask`, `init_exclavekit`, `vphoned`), no enforcing
violation and no crash report.
+## Always On display (2026-11-02)
+
+No new patch identifier and no new bytes in an Apple binary.
+`preboot-cfw-devicetree_iphone_product` (the iPhone product repair, which `cfw
+install` and `cfw update-environment` run) also adds
+`/product/vphone-always-on-display = 1` when the board's own tree has
+`/arm-io/disp0` `always-on-time`. MobileGestalt reads nothing by that name.
+vphoned reads it at startup and answers DeviceSupportsAlwaysOnDisplay
+(`2OOJf1VhaM7NxfRok3HbWQ`) and DeviceSupportsAlwaysOnTime
+(`j8/Omm6s1lsmTDFsXjsBfA`) yes in the MobileGestalt cache's `CacheExtra`
+(`GuestMobileGestaltAnswers`, `GuestMobileGestaltCache.presentAlwaysOnDisplayOnStartup`).
+Settings then offers Always On Display and SpringBoard dims the Lock Screen
+instead of turning it off. Issue #650.
+
+**Why not the tree.** libMobileGestalt (24A446) answers the three questions from
+one node:
+
+| Answer | Source |
+| --- | --- |
+| DeviceSupportsAlwaysOnTime | `IODeviceTree:/arm-io/disp0` `always-on-time` |
+| DeviceSupportsAlwaysOnDisplay | AlwaysOnTime, else `disp0` `always-on-device` |
+| DeviceSupportsAlwaysOnDisplayFlipbook | AlwaysOnTime, else `disp0` `always-on-device-flipbook` |
+
+Settings shows the row only with AlwaysOnTime (DisplayAndBrightnessSettings
+asks for it; with AlwaysOnDisplay alone there is no row, measured). The board's
+`always-on-time` therefore answers the flipbook yes too. CoreBrightness reads it
+in backboardd (`-[CBAODState initializeAODSupportConfiguration]`) and drives the
+flipbook through the panel controller (DCP), which the paravirtual panel does
+not have. An iPhone18,1 27.0.1 guest with an `/arm-io/disp0` stub carrying the
+board's `always-on-time` lost backboardd at every boot (`rebooting due to
+critical process crashes: backboardd`) and launchd restarted it into the device
+recovery environment. A second guest made without the stub booted, and
+answering all three yes in its `CacheExtra` crashed it the same way. Without
+the flipbook, `-[BLSHBacklightOSInterfaceProvider initWithPlatformProvider:]`
+gives SpringBoard BacklightServices' own renderer (`BLSHPseudoFlipbook`), which
+works on a guest. Answering the first two in the cache leaves the flipbook
+unanswered there and so no. Keeping `always-on-time` in the tree and answering
+the flipbook no in the cache would not do: the tree decides whenever the cache
+is missing, at a guest's first boot and after every drop, and one boot with the
+flipbook is enough to lose backboardd.
+
+A guest that went through that crash loop kept losing backboardd after the
+answers and the whole cache were removed; the cause was not found. Do not
+test the flipbook answer on a VM you want to keep.
+
+**When the answers land.** libMobileGestalt writes the cache when a process
+first asks after it is gone: at a guest's first boot, and after vphoned drops a
+cache older than the tree. vphoned waits for it (up to 10 minutes), adds the
+answers once, and sets `mobilegestalt_restart_pending`; the cache keeps them
+across boots, and a rebuilt cache gets them again at the next start. A new
+machine's creation boots more than once, so it is offered from its first use.
+
+**The window.** On a foldable guest the VM window covers the panel while
+`display.orientation` says `screen_off`, so a waking panel does not show its
+frame from before (`bde6440c`). SpringBoard posts `hasBlankedScreen` for the
+always-on Lock Screen too, so the window covered it. FoldDisplay now publishes
+whether the panel went off since SpringBoard last lit the screen
+(`com.vphone.folddisplay.panel-dark`: 1 stayed on, 2 went off), and
+`screen_off` is SpringBoard's blank and that.
+
+**Verified.**
+- New machine: iPhone18,1 27.0.1, cloudOS 26.4, bundle from this branch on
+ 2.14.2. `cfw install` logged `product/vphone-always-on-display: 'absent' ->
+ '01000000'`; with nothing done by hand, the cache had both answers yes and the
+ flipbook unanswered, Settings showed Always On Display On, and the locked
+ screen stayed dimmed with the clock moving (9:34 to 9:36). No backboardd crash.
+- Existing machine: iPhone19,4 27.1 (24A94425), `vm set-bundle
+ --update-environment`. The repair added the marker; the next boot dropped the
+ cache, the rebuilt one got the answers and the restart was reported pending;
+ after the restart the Lock Screen went always-on, the panel state stayed 1,
+ `screen_off` false, and the VM window showed it. With Always On Display
+ switched off in Settings the panel went off (state 2), `screen_off` was true
+ and the window covered it, then uncovered it on wake.
+
+**Not covered.** Other iPhones with the display were not run. Apple Watch:
+N227b's tree has `always-on-time` too, but on a Watch7,18 26.4 guest the same two
+answers left the screen fully dark after the timeout (Carousel decides; not
+investigated), so the repair stays iPhone-only. No iPad board has the property.
+The VM keeps rendering while dimmed: there is no low-power display.
+
+## Experimental iOS 16.6.1 desktop bring-up
+
+Measured pairing: iPhone15,2 (iPhone 14 Pro), iOS 16.6.1/20G81 userland,
+cloudOS 26.1/23B85 vphone600 boot chain. All additions below are manual opt-ins;
+shipped presets and the no-plan path leave them disabled. See
+`Research/Guest/ios16_bringup.md` for procedure, evidence and limitations.
+
+- `system-launchd-exp-ios16_mach_ports` bridges the old out-of-line self-task
+ Mach-port API to the newer fixed-three-port RPCs in the native launch hooks.
+ `dyld-exp-ios16_mach_ports_lookup` updates the old libxpc client's pre-constructor
+ lookup through a symbol-derived, bounded cache patch with undo capture.
+- `system-backboard-exp-ios16_migration` skips the fresh lab's measured migration
+ wait and releases its local shell sentinel/PreBoard re-block. It does not
+ migrate existing user data or persist completion. `system-springboard-exp-ios16_desktop`
+ avoids unavailable startup media, widget and flashlight services and uses the
+ native local setup-state setter. These services remain unavailable.
+- `system-systemhook-exp-ios16_surface` converts capability replies 0x28 ->
+ 0x18 and allocation/lookup replies 0xC68 -> 0xA68, including narrowed fields
+ and the changed plane stride. Offline metadata derives the framework-private
+ transport stub, verifies its instruction pattern and records its Mach-O UUID.
+ The runtime detour checks UUID/expected bytes, suspends peer threads, uses
+ private COW memory without writable executable pages, and restores protection.
+- `system-systemhook-exp-ios16_framebuffer` translates the measured old 0x46C
+ SwapEnd payload into the modern 0x560 layout. It inserts the new event/port
+ slots, retaining frame token, surfaces, rectangles and measured flags. Native
+ create/lock/write/read/unlock and surface lookup probes pass; submitted color
+ bars and the real SpringBoard desktop are visible.
+- `preboot-exp-ios16_ephemeral_storage` changes only the existing chosen/product
+ ephemeral-storage fields, preserving their widths and tree size. Native
+ `hw.ephemeral_storage` and `os_variant_uses_ephemeral_storage` then report 1;
+ PreBoard no longer owns the shell. Restore pre-ephemeral snapshots to undo
+ guest data effects; restoring device-tree bits alone is insufficient.
+- `system-vphoned-exp-ios16_touchscreen` registers a built-in HID touchscreen
+ only when none exists. With desktop startup selected, native backlight-state
+ changes also publish the legacy HID factor. Real mouse swipes and clicks now
+ reach the guest rather than being dropped as missing-digitizer/display-off.
+- `system-springboard-exp-ios16_keybagless_ui` is restricted to a fresh ephemeral
+ lab. The root daemon requires explicit markers and a strict session/persona
+ keybag-directory allowlist before publishing a single-link, root-owned,
+ magic-checked lease. Three signature-checked UI getters honor that lease for
+ at most three seconds and otherwise forward to native. MKB/AKS and encrypted
+ data remain unchanged; this is not working credentials or protected storage.
+- The existing battery helper weak-imports the unavailable newer precise-power
+ API and falls back to its existing ByType API. This resolves the measured
+ Preferences pre-main dyld crash without synthesizing an IOKit export.
+
+The real guest displays Home Screen, accepts mouse input and opens Settings >
+General > About (16.6.1, iPhone 14 Pro, 64 GB). Initial About lookup can wait for
+IOKit/SystemConfiguration quiescence; a proposed fallback was never deployed and
+is excluded. Wallpaper preview fails without Metal; its cancelled, unvalidated
+prototype is excluded as well. No general iOS 16/15, Metal, full audio, camera,
+networking or persistent protected-data compatibility is claimed.
++
+ ## Userspace debugging on `minimal`, watchOS and HomePod (2026-11-02)
+
+ `system-debugserver-cfw-install` re-signs the guest's `/usr/libexec/debugserver`
+ (strips `seatbelt-profiles`, sets `task_for_pid-allow`, ad hoc) in `cfw install`,
+ which `minimal` never runs. `filesystem-exp-debugserver` makes the same change in
+ the restore-image merge, before the reseal, so the new hash lands in the
+ regenerated static trust cache. Both stages share the entitlement transform
+ (`CustomFirmwareDebugserver.attachEntitlements`) and are a logged no-op when the
+ system ships no debugserver. The merged iPhone17,3 26.5, Watch7,18 26.4 and
+ HomePod Software 27.0 systems all ship one. A watch's debugserver also carries an
+ arm64_32 slice the signer cannot rewrite, so the merge thins it to arm64e first.
+
+ The entitlement alone does not let debugserver run or attach on `minimal`'s stock
+ kernel and TXM: AMFI asks TXM for developer mode and kills it ("Developer mode is
+ disabled, task_for_pid-allow is disallowed"), and an enrolment from the guest does
+ not survive a forced reboot. The `userspace-debugging` feature
+ (`FirmwarePatchSetCatalog.userspaceDebugging`) is the smallest set found to attach
+ to a system daemon and read its memory:
+
+ | Part | `minimal` / `watchos` | HomePod (`cfw install`) | Why |
+ | --- | --- | --- | --- |
+ | debugserver | `filesystem-exp-debugserver` | `system-debugserver-cfw-install` | The re-signed debugserver. |
+ | launchd | `filesystem-exp-launchd_jetsam_panic_guard` | `system-launchd-boot-jetsam_panic_guard_bypass` | See below. |
+ | kernel | `kernel-cfw-task_for_pid`, `kernel-boot-task_conversion_eval`, `kernel-cfw-debugger`, `kernel-boot-port_to_map`, `kernel-boot-proc_security_policy`, `kernel-boot-cred_label_update_execve` + `kernel-boot-hook_cred_label` | already in the preset | Task port for a process the caller does not own, and its conversion; the debugger gate `task_for_pid` checks; no panic converting the port to a vm_map; the per-process policy; the platform label and the MACF hook that reaches it. |
+ | TXM | `txm-boot-developer_mode_bypass`, `txm-cfw-debugger_entitlement`, `txm-boot-sel42_29` + `txm-cfw-get_task_allow` | already in the preset | Developer mode on without enrolment; selector 42's debugger entitlement check; the target's get-task-allow byte where selectors 42 and 41 read it. |
+
+ A part names one patch per delivery, and a preset takes the first its sets
+ declare. `standard` already has every part, so Launchpad offers no box there. The
+ Apple TV presets get none either: `cfw install` refuses debugserver and launchd
+ patches not validated for tvOS (`FirmwareGuestPatchResolution`), and the feature
+ checks that list. HomePod's list now admits the two, as validated below.
+
+ **AMFI patches are not needed.** `kernel-boot-amfi_trustcache` and
+ `kernel-boot-amfi_execve` were in the first cut "should debugserver run outside
+ the image's trust cache". It doesn't: the re-sign is in the resealed trust cache.
+ An iPhone17,3 26.5 `minimal` guest without them launches the re-signed
+ debugserver from launchd and attaches.
+
+ **launchd's jetsam guard.** With developer mode on, the host's CoreDevice (a
+ `minimal` guest pairs with the Mac over the NAT) mounts Xcode's personalized
+ Developer disk image whenever a developer service needs it, for example
+ `xcrun devicectl device info processes`. `MobileStorageMounter` mounts
+ `Xcode_iOS_DDI`, launchd loads its daemons, and launchd kills init:
+ `initproc exited -- ... jetsam property category (Daemon) is not initialized`.
+ Observed on the first boots of an iPhone guest without the patch (and in an
+ earlier `minimal-ctf` machine's log). `standard` avoids it with
+ `system-launchd-boot-jetsam_panic_guard_bypass`; on `minimal` launchd is in the
+ sealed system, so `filesystem-exp-launchd_jetsam_panic_guard` applies the same
+ `CustomFirmwareJetsamPatcher` change in the merge. With it, the same
+ `devicectl` call mounts the DDI, `dtappserviced` starts, and the guest stays up.
+ On HomePod, launchd is patched for the persona adapter, which returned before
+ the jetsam verb; `cfw install` now applies both to the one copy.
+
+ To make the feature selectable without a preset of its own, `minimal` and
+ `watchos` name the two kernel sets and select nothing from them. The pipeline
+ builds a kernel patcher only when the plan turns on a patch from those sets (the
+ research board's kext mix targets the kernelcache too, so the target alone does
+ not say), so a plain `minimal` kernel stays stock. A feature is only a list of
+ patch identifiers: turning it on is `--allow` for each, and `fw patches` reports
+ it (`features` in `--json`, with `available` and the patches for the active
+ preset) so Launchpad's patch sheet offers one box without declaring a patch
+ itself. On an installed `minimal` VM a kernel patch is reported as delivered by
+ a restore, not by `cfw update-kernel`, which refuses a VM whose system was
+ customised before its restore.
+
+ Validation (Launchpad `vm create` with the feature's patches allowed, then a
+ launchd job running `/usr/libexec/debugserver 0.0.0.0:<port> --attach=<configd>`
+ and LLDB over gdb-remote: attach, `(int)getpid()` evaluated in the target, 16
+ bytes of its code read):
+
+ | Guest | Preset | Kernel and TXM | Result |
+ | --- | --- | --- | --- |
+ | iPhone17,3 26.5 (23F77) / cloudOS 26.5 (23F75) | `minimal` | 22 kernelcache (2 base + 20 cfw) and 9 TXM records | developer mode `enabled`; attach to configd in 6.8 s; DDI mounted by `devicectl`, no panic |
+ | Watch7,18 26.4 (23T240) / cloudOS 26.4 (23E244) | `watchos` | 22 kernelcache (2 base + 20 cfw) and 9 TXM records on the watch mix | developer mode `enabled`; attach to configd in 10.3 s; the watch is not paired with the Mac, so no host DDI mount |
+ | AudioAccessory5,1 27.0 (24J361) / cloudOS 26.4 (23E5207q) | `homepod-mini` | preset's own | attach to configd in 4.3 s; Xcode has no DDI for its board |
+ | iPhone11,6 18.6 (22G86) / cloudOS 18.6 (22G86) | `minimal` | 22 kernelcache (2 base + 20 cfw) and 9 TXM records, with the iOS 18 finders | developer mode `enabled`; attach to configd in 1.1 s; after pairing, `devicectl` mounted the DDI, no panic, attach still works |
+
+ On iOS 18 the feature needs the iOS 18 kernel and TXM finders of
+ `feature/ios18-standard` ("Find the standard kernel patches in the iOS 18
+ research board kernels", "Find the LLB rootfs and TXM CFW patches on cloudOS
+ 18"). Without them `fw patch` stops at TXM: on cloudOS 18.6 the developer-mode,
+ debugger and get-task-allow sites are not found. The iOS 18 row ran with those
+ two commits on top of this branch.
+
+ On a stock boot chain (`minimal` and `watchos` with no iBEC or LLB patch, and
+ the launchd_cache_loader gate off; 2026-11-02) the feature works the same: the
+ same 22 kernelcache and 9 TXM records, `iBEC: no patches` and `LLB: no
+ patches` in the patch log, the stock LLB booting the patched kernel and TXM to
+ SpringBoard (iPhone17,3 26.5) and Carousel (Watch7,18 26.4) with vphoned up and
+ developer mode `enabled`, and LLDB attached to configd through the re-signed
+ debugserver, evaluated `(int)getpid()` and read 16 bytes at its pc. The watch
+ guest needed more than 2048 MB: at 2048 MB a stock LLB, with or without the
+ feature, stops the VM after `iLLB decompressed`; at 8192 MB both boot.