Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

docs: describe reproducible iOS 16 selection and rollback limits

黑曜猫21c2594a60ea
diff --git a/Research/Guest/ios16_bringup.md b/Research/Guest/ios16_bringup.md
index 4678e7c0..08968cd1 100644
--- a/Research/Guest/ios16_bringup.md
+++ b/Research/Guest/ios16_bringup.md
@@ -1,207 +1,132 @@
-# Local iOS 16.6.1 bring-up experiment
-
-Status: native SpringBoard desktop and mouse interaction are verified on the
-fresh iOS 16.6.1 lab. IOSurface and framebuffer protocol adapters restore real
-scanout; a missing HID touchscreen and the old backlight publication path were
-separate input blockers. Settings now renders General after its battery helper
-stopped strongly importing a newer IOKit API. About now works on the same guest
-without an additional patch, after its native network initialization wait.
-The wallpaper experiment was stopped at the user's request before deployment;
-the running lab retains its working 2.15.0-local.7097296f environment.
-
-This remains an experimental, ephemeral UI bring-up. Its fresh keybag-less UI
-mode does not unlock encrypted storage or provide working passcodes. Native
-MKB/AKS are unchanged. Other applications and persistent protected data are not
-claimed to work.
-
-- Guest: iPhone 14 Pro, iPhone15,2/d73ap, 1179x2556 at 3x.
+# Experimental iOS 16.6.1 desktop bring-up
+
+This is an opt-in fresh-lab experiment, not general iOS 16 support. The measured
+VM reaches the native SpringBoard desktop, accepts mouse clicks and swipes, and
+opens Settings > General > About. About shows iOS 16.6.1, iPhone 14 Pro and 64 GB.
+The native keybag remains locked: UI-only lab mode does not decrypt protected
+data, implement credentials, or support migrating an existing user's device.
+
+## Measured configuration
+
+- iPhone 14 Pro: iPhone15,2/d73ap, 1179 × 2556 at 3x.
- Userland: iOS 16.6.1, 20G81.
-- Boot chain and kernel: cloudOS 26.1, 23B85, vphone600.
-- VM: 6 CPUs, 6144 MB RAM, 64 GB disk, no NIC.
-- Apple IPSW: `https://updates.cdn-apple.com/2023SummerFCS/fullrestores/042-44327/EDD9D5D2-E1C0-4B64-B6B1-642E087BB595/iPhone15,2_16.6.1_20G81_Restore.ipsw`.
-- IPSW SHA-1: `1d80ba85912850bb6cc62540730652b29e4c3e8e` (verified after download).
-
-This branch enables the existing older-userland SwapEnd, thread-guard and
-paravirtual-user-client declarations for 16, plus the BSD-only Skywalk boot
-argument. It does not enable the iOS 17-specific SpringBoard library on 16.
-Firmware preparation is restricted to this exact experimental pairing.
-
-Initial validation: complete native bundle build and admission passed;
-69 selected firmware/patch-model tests and 20 guest-device tests passed.
-The original IPSW restore completed. Guest installation was then refused by
-the host helper while walking the external library path, even though that
-directory exists. A separate internal-disk copy is being used to distinguish
-host path access from guest compatibility.
-
-On the pristine 20G81 seputil, the existing patch resolved the complete
-`%s/%s.gl` literal at 0x10001D3A4 through a code reference at 0x10000BEC4.
-It changed only the filename field to `AA` and an immediate second run was
-idempotent. This is an offline binary check, not evidence of a normal boot.
-
-The user completed macOS administrator authentication and the internal install
-completed. On first normal boot, launchd exits PID 1 with "could not set up
-inheritance port". Its call at 0x10001682C is `_mach_ports_register`; the next
-instruction branches to that fatal block on failure. XNU 12377.41.6 uses fixed
-three-port descriptors for task RPCs 3403/3404; iOS 16 uses an OOL port array.
-
-The opt-in `system-launchd-exp-ios16_mach_ports` selects an API bridge in
-launchdhook/SystemHook and its marker. Native self-task register/lookup tests
-pass. The VM also blocks `system-launchd-boot-jetsam_panic_guard_bypass`, whose
-pattern is absent on 20G81: otherwise the existing grouped launchd patch fails
-before it inserts launchdhook. The bridge selection now owns launchd's weak
-load and backup in the same group, so installation cannot count only the marker
-as success. Guest console confirms register3 succeeds and launchd completes
-early boot. Spawned xpcproxy processes then trap before inserted-library
-constructors: exception diagnostics locate `__libxpc_initializer.cold.6` at
-0x1E6EE647C, reached from the failed `_mach_ports_lookup` call at 0x1E6ECBCA4.
-
-`dyld-exp-ios16_mach_ports_lookup` is a second, explicitly selected cache
-patch. It replaces the bounded 388-byte `_mach_ports_lookup` client at
-0x1C5FFC078 in libsystem_kernel with the modern inline-three-port reply
-decoder, preserving the public allocated-array API. PC-relative request
-construction stays in place; the expanded reply frame preserves FP-relative
-saved registers and compact unwind. The generated payload validates reply ID,
-size, descriptor count and dispositions and preserves error cleanup. Cache
-writes are re-attested and recorded for opt-out restoration. No guest success
-is claimed for this second patch until normal boot is retested.
-
-Protocol reference: Apple XNU `xnu-12377.41.6`, `osfmk/mach/task.defs` and
-`libsyscall/mach/task.c`. The guest runs `kernelcache.release.vphone600`
-26.1/23B85 (Darwin 25.1.0, xnu-12377.42.6~55).
-
-The inline-port cache client passes the eighth real boot: libxpc initializes,
-system services run and vphoned answers. The full affected cache chunk matches
-its pristine input after offline apply/idempotence/undo testing. 70 selected
-patch-model tests pass; a subsequent catalogue/plan run passes 41 tests.
-
-The next desktop blocker is measured in backboardd's migration queue, waiting
-inside `_DMPerformMigration`. A local opt-in backboard library releases this
-call. On the next boot that stack disappears, but SpringBoard still waits in
-FBSystemShellInitialize. Static analysis of BKSystemShellSentinel's
-`checkInAndWaitForDataMigration:completionBlock:` at 0x100064D30 shows another
-wait on `_lock_migratorDidComplete` and `_lock_systemAppBlocked`. PreBoard is
-running and holds the alternate-system-app block. The next test asks this
-native check-in method to use its existing non-waiting mode. Method encodings
-are checked before replacement. No global migration-complete state is written.
-
-After boot, auto-boot is set false by the incomplete migration flow. A small
-native libirecovery helper, restricted to this VM's ECID C9E118E06642A328 and
-recovery-mode PIDs, restores auto-boot and reboots. This is a lab workaround,
-not a general recovery or SEP compatibility fix.
-
-The native EXC_CRASH observer captured the media failure before inserted-library
-constructors execute: abort <- cc_abort <- ccrng_getentropy_generate <-
-ccrng_process_init <- arc4random_buf <- libobjc initialization. Independent
-getentropy/arc4random probes pass as root and mobile, including a probe signed
-with the media service's retained entitlements. The investigation read
-the faulting thread's errno through THREAD_IDENTIFIER_INFO and the measured
-20G81 __error TLS layout. No random bytes are replaced or fabricated.
-
-## Current checkpoint
-
-The active lab is `/Users/Shared/VPhoneLab16/iPhone-14-Pro-iOS16-Lab`.
-Use that library root explicitly. The external restored original is retained at
-`/Volumes/ZHITAI/Data/VPhone/Library/lab-backups/iPhone-14-Pro-iOS16-Lab-restored-original`.
-Before enabling the native ephemeral-storage flags, the mutable disk, SEP
-storage, NVRAM, configuration and patch receipts were APFS-cloned under the
-internal lab's `BeforeEphemeral` directory. They have not been restored or deleted.
-
-Native probes now report `hw.ephemeral_storage=1` and
-`os_variant_uses_ephemeral_storage=1`. PreBoard no longer runs. Backboard's local
-shell sentinel reports migration complete, unblocked, and no alternate system
-app. SpringBoard's main thread reaches its ordinary run loop. The fresh Data
-volume has only session/persona keybags; no system keybag is provisioned.
-
-The measured protocol adaptations are:
-
-- The early Mach-port bridges described above, including an inline-three-port
- cache client for old libxpc.
-- IOSurfaceRoot selector 13's capability reply: modern 0x28 to old 0x18, with
- widened integer fields narrowed only when representable.
-- IOSurface allocation/lookup reply: modern 0xC68 to old 0xA68, including the
- 0x88/0x98 plane header/stride to 0x68/0x80 layout, up to 20 planes.
-- IOMFB method-5 input: old 0x46C (or its earlier size-only 0x560 patch) to the
- new 0x560 layout. The nine widened event-value and event-port slots are zero;
- frame token, surface/rectangle fields and measured flags retain their meaning.
-
-Display adaptation patches only an attested framework-private IOKit transport
-stub in process-private memory. Generated metadata validates the framework UUID,
-original stub and displacement; the shared cache file is not modified by this
-runtime adapter. Host metadata is prepared in a child so cache mappings are
-released before the installer unmounts its staged volume. Native surface
-create/lock/write/read/unlock, ID lookup and Mach-port lookup pass. A manual RGB
-frame visibly reaches VZ, followed by native Lock Screen and desktop frames.
-Animation samples around 100–120 fps do not establish sustained application
-performance; a static screen can correctly report zero new frames.
-
-## Input and fresh-lab UI
-
-A HID monitor proves normalized digitizer events reach backboardd. Its first
-rejection was "AX event, but main screen digitizer is missing". The new manual
-`system-vphoned-exp-ios16_touchscreen` registers a display-integrated built-in
-HID touchscreen only if none exists. Backboard then acquires its main digitizer.
-The next rejection was "backlight dim/off": SpringBoard's newer brightness path
-never published the legacy HID factor. The desktop library now forwards the
-native requested backlight state and publishes its native factor through the
-system-app API with the correct BOOL publication flag. Actual Home events now
-change the protected factor from 0 to 1, and real mouse swipes/clicks respond.
-
-The empty lab's native keybag query still returns lock state 1; a single native
-nil-passcode check returns -8. No passcode was supplied or created. The manual
-`system-springboard-exp-ios16_keybagless_ui` is a UI-only experiment: vphoned,
-as root, checks explicit markers, native ephemeral storage and a root-owned
-keybag directory containing only the measured session/persona files. Any unknown
-entry, system bag, symlink or read error refuses the mode. A root-owned atomic
-lease expires after three seconds. Only while it is valid, the selected
-SpringBoard library uses the unprotected UI model through three signature-checked
-Objective-C getters. It does not replace MKB/AKS, alter a credential or decrypt
-protected data. Keep this separate from genuine keybag compatibility.
-
-The selected lab uses standard with explicit manual allows for:
-`system-launchd-exp-ios16_mach_ports`, `dyld-exp-ios16_mach_ports_lookup`,
-`kernel-exp-frida_syscall_filter_off`, `system-keybag-exp-ios16_ephemeral`,
-`system-backboard-exp-ios16_migration`, `system-springboard-exp-ios16_desktop`,
-`system-systemhook-exp-ios16_surface`, `system-systemhook-exp-ios16_framebuffer`,
-`preboot-exp-ios16_ephemeral_storage`, `system-vphoned-exp-ios16_touchscreen`,
-and `system-springboard-exp-ios16_keybagless_ui`.
-The unvalidated `system-posterboard-exp-ios16_cpu_preview` remains disabled.
-The unmatched `system-launchd-boot-jetsam_panic_guard_bypass` remains blocked.
-All new declarations remain off in every bundled preset and with no explicit
-plan. Newer guests do not select these iOS 16 paths.
-
-## Settings and validation
-
-Settings initially exits in dyld before main because libbatteryhealthfix
-strongly imports IOPSCopyPowerSourcesByTypePrecise, absent from 20G81's IOKit.
-The import is now weak; older bases can use the existing ByType path, while
-newer bases retain Precise. A host dyld compatibility probe passes, and the
-actual guest now renders Settings > General.
-
-Opening About then blocks in PSGAboutDataSource._macAddress ->
-_SCNetworkInterfaceCopyAllWithPreferences, waiting on a background Ethernet
-watcher's once token and IOKit quiescence. The real FrontBoard watchdog report
-is Preferences-2026-11-01-205100.ips. Before a proposed fallback was deployed,
-the user confirmed that the native page works on 2.15.0-local.7097296f and
-provided a screenshot showing 16.6.1, iPhone 14 Pro and 64 GB. The fallback was
-withdrawn from the final source and never selected or installed. Initial
-quiescence can still delay this page.
-
-Wallpaper settings opens. Add New Wallpaper instead crashes PosterBoard in
-PBFHomeScreenPreviewImageBuilder._imageForView:, whose Metal renderer inserts
-a nil command queue into an options dictionary. A native probe confirms that
-MTLCreateSystemDefaultDevice returns nil. The new manual-only software-preview
-patch replaces only that signature-checked helper when Metal is unavailable,
-using a bounded UIKit bitmap renderer. Its actual gallery and static wallpaper
-application validation was stopped at the user's request. The build was
-interrupted and no wallpaper prototype was installed. Dynamic wallpaper
-rendering is not claimed.
-
-The selected catalogue/plan/parser/encoder/device-tree run passes 50 tests in
-five suites before the wallpaper addition. Native ASan/UBSan surface conversion and
-lab-lease policy tests pass. Full bundle builds and admission pass at each
-reported deployed checkpoint. The wallpaper addition still needs its final build,
-selection validation and real UI test.
-
-Audio/media routing, widget contents and flashlight remain unavailable. Network
-is intentionally none. The iOS 17 PR source branch is unchanged and clean; no
-iOS 16 work has been pushed.
+- Boot chain/kernel: cloudOS 26.1, 23B85, vphone600.
+- 6 CPUs, 6144 MB RAM, 64 GB sparse disk, network `none`.
+- [Apple IPSW](https://updates.cdn-apple.com/2023SummerFCS/fullrestores/042-44327/EDD9D5D2-E1C0-4B64-B6B1-642E087BB595/iPhone15,2_16.6.1_20G81_Restore.ipsw).
+- IPSW SHA-1: `1d80ba85912850bb6cc62540730652b29e4c3e8e`.
+
+Firmware preparation accepts this exact experimental pairing. The existing
+older-userland SwapEnd, thread-guard and paravirtual-user-client paths also
+accept 16; the BSD-only Skywalk boot argument is used. The iOS 17 desktop hook
+is never enabled for 16.
+
+## Selection and deployment
+
+Every experimental addition is disabled in all shipped presets and without an
+explicit plan. Start with `standard` and explicitly allow these identifiers:
+
+```text
+system-launchd-exp-ios16_mach_ports
+dyld-exp-ios16_mach_ports_lookup
+kernel-exp-frida_syscall_filter_off
+system-keybag-exp-ios16_ephemeral
+system-backboard-exp-ios16_migration
+system-springboard-exp-ios16_desktop
+system-systemhook-exp-ios16_surface
+system-systemhook-exp-ios16_framebuffer
+preboot-exp-ios16_ephemeral_storage
+system-vphoned-exp-ios16_touchscreen
+system-springboard-exp-ios16_keybagless_ui
+```
+
+Explicitly block `system-launchd-boot-jetsam_panic_guard_bypass`: its pattern is
+absent on 20G81 and otherwise aborts the grouped launchd patch before hook load.
+Pass these selections to `vm create` or `fw set-patches`; the latter replaces
+its entire override record, so retain every required allow when changing it.
+Use Launchpad's CLI and a complete locally built `VPhone.bundle`, not a detached
+copy of the host executable. See `Documents/Guides/launchpad-cli.md` for installing
+that bundle and binding a machine without changing other machines' versions.
+
+Boot-chain changes require firmware preparation/patching and restore. The
+post-restore device-tree step owns the ephemeral-storage flags. Guest markers,
+cache metadata and inserted libraries are selection-aware and synchronized by
+`cfw install` / `cfw update-environment` while stopped. Cache metadata generation
+runs in separate CLI child processes so cache mappings do not hold installation
+mounts open. A successful command is insufficient evidence of a usable desktop;
+check the guest UI after a cold boot.
+
+Retain an offline backup of Disk.img, SEPStorage, nvram.bin, configuration and
+patch records before enabling native ephemeral storage. The lab used APFS
+clones before that transition. These backups are part of the VM's retained
+`BeforeEphemeral` directory. The lab was later copied to an external APFS volume;
+main and backup disk logical contents were compared before the external copy
+was successfully cold-booted. Machine configuration uses relative file paths.
+
+## What each adaptation fixes
+
+Launchd initially dies at `mach_ports_register` with "could not set up inheritance
+port". The native hook translates old out-of-line self-task calls to XNU's newer
+inline-three-port RPCs. Spawned libxpc initializes before constructors, so its
+old `mach_ports_lookup` client also needs a bounded, symbol-derived cache patch.
+The modern reply decoder preserves allocated-array semantics and error cleanup.
+
+Backboard initially waits inside `_DMPerformMigration`. The local migration hook
+skips that measured wait, completes/unblocks the native shell sentinel, and
+suppresses its PreBoard-only re-block. Native ephemeral-storage device-tree
+flags then make `hw.ephemeral_storage` and `os_variant_uses_ephemeral_storage`
+report 1; PreBoard no longer runs. SpringBoard's native setup setter clears its
+local setup reason. Unavailable media/widget/flashlight startup waits are omitted.
+No persisted migration-complete record or setup preference is fabricated.
+
+IOSurfaceRoot capability replies grew from 0x18 to 0x28 and allocation/lookup
+replies from 0xA68 to 0xC68. The converter checks narrowing of widened values and
+maps the changed header and up to 20 planes. Offline metadata identifies the
+framework-private IOKit stub by decoded calls/literal references and records its
+UUID and expected bytes. Runtime installation uses a process-private COW page,
+suspends peers during replacement, and never keeps a page writable/executable.
+Other processes and the shared-cache file are not modified by the detour.
+
+IOMobileFramebuffer's SwapEnd payload grew from 0x46C to 0x560. Its converter
+inserts nine event-value slots and nine port slots, preserving the measured frame
+token, surfaces, rectangles and flags. Native IOSurface create/lock/write/read/
+unlock, ID lookup and Mach-port lookup pass. Submitted color bars, Lock Screen
+and the real SpringBoard desktop become visible. This does not implement Metal.
+
+Backboard drops injected touches when no main-screen digitizer exists. The
+selected daemon registers a built-in touchscreen only if none is present.
+SpringBoard also publishes its native backlight-state changes through the legacy
+HID factor API; its third argument is a publication Boolean, not the source enum.
+A Home press changes the measured factor from 0 to 1. Real mouse swipes and
+clicks then respond. A blank screen after idle can still be normal display sleep.
+
+The fresh guest contains only session/persona keybags. A single native
+nil-passcode probe returned -8 and left MKB lock state 1; no password was supplied
+or created. The UI-only selection requires a root daemon's strict directory
+allowlist and an atomic, root-owned, single-link, magic-checked lease refreshed
+every second. A lease older than three seconds is rejected. Three signature-
+checked UI getters use an unprotected UI model only during a valid lease;
+MKB/AKS and key material are untouched. Unknown files or read errors refuse mode.
+
+Settings originally crashes before main because the existing battery helper
+strongly imports `IOPSCopyPowerSourcesByTypePrecise`, absent on 20G81. It now
+weak-imports that API and uses its existing ByType implementation on older bases.
+A native host weak-import/interpose probe passes and the real Settings app opens.
+About initially waited on SystemConfiguration's Ethernet-watcher once token and
+IOKit quiescence; it subsequently worked without an additional patch.
+
+## Verification and limitations
+
+The pre-PR bundle passed complete native build and bundle admission. Selected
+catalogue/plan/parser/encoder/device-tree tests passed (50 tests in five suites).
+ASan/UBSan conversion and lease-policy tests cover field bounds, narrowing,
+inserted slots, lease freshness, timestamps, ownership, file types and modes.
+The real guest displayed Home Screen and Settings/About with working mouse input.
+These are bounded bring-up results, not full OS or every-application validation.
+
+Wallpaper stays black. Add New Wallpaper crashes its Metal preview because the
+guest has no Metal device; the cancelled software-preview prototype is excluded.
+The proposed About fallback was never installed and is also excluded. Widget
+content, audio/media routing, camera, flashlight, networking and persistent
+protected data remain unavailable or unverified. The IPSW contains only a Files
+app placeholder, not a complete executable. Dynamic wallpapers, iOS 15 and other
+iOS 16 releases have not been demonstrated.