Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Merge upstream main into homepod-ui

Guilherme Ramboa7d161290f4b
diff --cc Research/0_binary_patch_comparison.md
index ad5d986d,41b8dedb..77151259
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@@ -1,194 -1,16 +1,222 @@@
# Patch Comparison: Regular / Development / Jailbreak / Experimental
++> **HomePod integration with upstream main (2026-10-23).**
++> Merged upstream `d14231a4` into the HomePod branch, retaining upstream's
++> 2.12 compatibility contract, Apple Watch, research-board and sealed restore
++> image workflows alongside HomePod's donor inference, OTA userland and audio
++> routing. The `homepod-mini` shipped preset now names the research-board set
++> and blocks the new manual Frida relaxations and iOS Bluetooth-controller
++> patch, matching its built-in definition. HomePod's original global product
++> token, 48 kHz audio-only routing and Sound Glow policies are unchanged.
++> Validation: full VPhone bundle (including admission checks) and Launchpad
++> builds passed; 683 CoreKit, 170 selected patch/pipeline and 105 archive tests
++> passed. The CoreKit throughput threshold needed one isolated retry after
++> failing during the full parallel run. Two research-board firmware comparison
++> tests skipped without their optional fixtures. HomePod display, setup,
++> welcome, Siri and Sound Glow native harnesses and Launchpad machine/cache,
++> compatibility, template and control harnesses passed. No bundle was installed
++> and no live VM behavior was retested for this merge.
++
+> **HomePod 27.2 OTA and native Sound Glow (2026-10-23, live verified).**
+> The 27.0 donor lacks the artwork/color extraction and native media animation
+> cases introduced in 27.2. `system-homepod-exp-ota_userland` stages the full
+> Apple HomePod mini OTA over the same device's 27.0 IPSW, retaining its restore
+> identity and cloudOS boot chain, as the Apple TV OTA pairing does.
+> `system-homepod-exp-sound_glow` injects the existing guest adapter into
+> NowPlayingCap and generates `/usr/share/vphone/HomePodSoundGlow.plist`.
+> Its narrow native `AccessorySettingProvider.mediaUI` getter selects value 1;
+> Apple's artwork service, color extractor and CAPAnimationEffect.media remain
+> responsible for rendering. Opt-out restores the original app and removes the
+> policy. Both declarations are HomePod-only, require 27.2 or later, and are
+> selected by default only by `homepod-mini`. Original product identity and
+> existing audio/Siri behavior are retained. Local validation and native
+> evidence are recorded in [Sound Glow](Firmware/homepod_sound_glow.md).
+> Live 27.2 boot and clear Music/AirPlay audio are verified. Initial playback
+> exposed an unresolved own-device endpoint in the native artwork request.
+> A scoped request adapter selects MediaRemote's local destination only for
+> that own-device UID; native request/response and artwork processing remain
+> intact. Remote requests and opt-out pass through. The routing correction,
+> artwork processing succeed live in 24K120. Purple and yellow album artwork
+> produce distinct native animated colors; pause fades to idle and resume works.
+> A follow-up to the existing Siri speech patch uses a mixable, ducking auxiliary
+> session with notify-on-deactivation after the live interruption test made
+> Music abandon the receiver. The owner confirmed full speech while Music stayed
+> on HomePod; native frames handed off to Siri and returned to colored music.
+> Successful installation now records the actual mounted HomePod SystemVersion
+> after disk commit, preserving cloudOS and variant. Preparing an OTA alone does
+> not promote the host label; full-install command/creator variant recording
+> retains HomePod identity. Restore-info tests cover this merge.
+> Opt-out removes the policy and injected load command and restores white native
+> playback. Re-enable plus cold boot restores audible music and colored native
+> animation, confirmed by the owner and changing valid RGB reports. Final live
+> bundle: `2.11.0-local.8e60e757`; original 27.0 VM and default bundle preserved.
+
+> **HomePod Siri speech policy (2026-10-23, live speech verified).**
+> New optional `system-homepod-exp-siri_speech` generates
+> `/usr/share/vphone/HomePodSiriSpeech.plist` with `Enabled=true`, restricted to
+> 27.x HomePod guests and selected by default only in `homepod-mini`. Installation
+> requires vphoned, the top-cap adapter and virtio sound; welcome additionally
+> requires this speech policy. Opt-out removes only the selected policy.
+> The native branch supports an output-only auxiliary AVAudioSession ID carried
+> on a normal type 13 SVXSystemEvent, allowing SoundBoard's existing Siri lifecycle
+> and completion to handle speech without entering physical recording setup.
+> The candidate repair is scoped to the existing SoundBoard adapter; global
+> product identity, audio route and microphone capability flags remain intact.
+> Live `siriSay:` speaks the full exact welcome sentence. SiriHeadlessService
+> reports synthesis success, sirittsd records playback start/finish, SoundBoard
+> returns to idle and deactivates the auxiliary session. Colorful native frames
+> advance during speech and return to black afterward.
+> See [welcome and speech policy](Firmware/homepod_welcome.md).
+
+> **HomePod welcome policy (2026-10-23, live sequence verified).**
+> New optional `system-homepod-exp-welcome` is restricted to 27.x and admitted
+> only for HomePod guests. Only `homepod-mini` selects it by default. The guest
+> installer checks that vphoned, the HomePod top cap, local setup completion and
+> virtio sound and native Siri speech are selected, then generates
+> `/usr/share/vphone/HomePodWelcome.plist` with `Enabled=true`. Opt-out removes
+> only that policy; once-only Data state remains owned by the guest runtime.
+> The coordinator runs in SoundBoard's existing injected HomePod adapter, using
+> native tone completion, a coordinated Identify activity and Siri finalization
+> after boot readiness. A durable guest-identity claim prevents replay across
+> restarts and updates while allowing each template clone its own welcome.
+> The owner confirms tone, exact speech and both animations on automatic boot.
+> Logs establish TonePlaying, ToneFinished, SpeechRequested and SpeechFinalized.
+> Live inspection caught Identify remaining active: cleanup must call the
+> coordinated `setLocalSessionActive:NO`, which invokes the subclass cleanup;
+> calling `endLocalSessionActivity` alone does not relinquish ownership. The
+> regression mock now preserves that native distinction. Final installed bundle
+> `2.11.0-local.3f1d474e` passes the complete sequence on a fresh-identity clone,
+> returning to an empty activity stack. The original claim/status stay byte
+> identical after update, cold boot and SoundBoard restart with no replay.
+> Direct Siri speech, native animated frames and ordinary tone 1 still pass
+> afterward, including the owner's audible and return-to-idle confirmation.
+> See [welcome policy and native behavior](Firmware/homepod_welcome.md).
+
+> **HomePod welcome pre-live ABI audit (2026-10-23).**
+> Direct 24J361 donor-cache metadata establishes UInt32 tone playback
+> (`SBUITonePlaybackManager play:completion:`, `v28@0:8I16@?20`). The candidate's
+> initial UInt64 mock and guard agreed with each other but would reject the real
+> guest method. Both are corrected, with an independent donor-signature fixture
+> and rejection coverage for the old shape. Native Siri state/selector analysis
+> also confirms a presenting-state activity path separate from microphone audio
+> activation; live animation, metering and audibility remain pending.
+
+> **HomePod audio-only identity correction (2026-10-22, live validation).**
+> An A/B boot of the same installed bundle, changing only the validated donor
+> product token back to its prior virtual value, restores the native red replay;
+> restoring the donor token blacks the same fixture. The donor identity enables
+> HomePodDisplayService's physical gamma path, which requires absent brightness
+> hardware. Audio now selects native B520 route **4** through VirtualAudio's own
+> `ProductIDOverride`, stored by vphoned and set in-process by the HAL plugin.
+> The boot-tree HomePod capability patch retains the original VM product token.
+> `preboot-homepod-exp-audio_product` is now blocked in every preset; its existing
+> inverse restores previously installed guests from the shared Preboot backup.
+> The old repair remains declared for explicit research and reversible migration.
+> No display workaround or new instruction patch. All 88 focused Xcode firmware
+> tests, four audio transport harnesses, the unchanged display adapter harness,
+> the full bundle build and strict signature verification pass. Installed
+> `2.11.0-local.40cd1d45` restores the exact original Preboot tree; MobileGestalt
+> retains the virtual product enum while VirtualAudio uses route 4. The owner
+> confirms clear tones. LED replay and native identify output work across two
+> cold boots; the second playback run has zero starvation/drops in all cycles.
+
+> **HomePod audio port (2026-10-22, live routing validation).**
+> New `preboot-homepod-exp-audio_product` restores the donor's exact 20-byte
+> `/product/product-id` in Preboot through the existing reversible repair
+> composition; new HomePod boot trees receive it too. MobileGestalt then resolves
+> HomePod mini's native VirtualAudio product 4 instead of the VM's unknown 0.
+> `homepod-mini` selects the shared virtio-snd HAL driver, retargeted/resealed
+> for tvOS, publishing its output as the native `PuffinOutput` endpoint. It does
+> not apply the iPhone 8010 override or VirtualAudio instruction/tuning patches.
+> Other presets keep the new identity repair off and TV excludes the driver.
+> First live run proves native product 4, B520 tuning selection and driver load;
+> routing requires the HomePod-only raw UInt32 `mode/glob/0` custom property.
+> The driver advertises this through `cust`, retains the native `defa`/`raww`/
+> `tphn`/`meas` mode and reports changes. Corrected build `61d08ba5` routes to
+> `PuffinOutput`; six playback cycles have zero starvation/drop counters.
+> Final build `b284734a` plays ordinary-session test tones on the Mac's selected
+> Studio Display speakers; the owner confirms clear tones.
+> Live silence traced to B520 speaker DSP buffer overruns at 44.1 kHz.
+> HomePod output now advertises only its 48 kHz wire rate; forcing a 48 kHz
+> session removes the errors and produces nonzero PCM in a scoped host tap.
+> iPhone/iPad retain their alternate-rate support.
+> No new instruction patch. See [native evidence and validation](Guest/homepod_audio.md).
+
+> **HomePod setup completion and controls (2026-10-22, live validation).**
+> New `system-homepod-exp-setup_bypass` is HomePod-only, restricted to 27.x,
+> and selected only by `homepod-mini`. It installs the System marker
+> `/usr/share/vphone/HomePodSetup.plist`. A short-lived mobile helper journals
+> `SetupDone` and `SetupFinishedAllSteps` in `com.apple.purplebuddy`, synchronizes
+> them, and calls the donor's `BYSetupAssistantPrepareLaunchSentinel` before
+> checking the native needs-setup and initial-run APIs. The sentinel is a
+> per-user POSIX semaphore, not a filesystem flag. Removing the marker restores
+> exactly the original two keys, including absent values; the inverse survives
+> until native restoration succeeds. The helper remains installed for rollback
+> even if vphoned is deselected. This completes local setup state; it does not
+> provision an Apple Account or HomeKit home. **Live late-start correction:**
+> an already-running HPSetup retains assistant/voice-trigger assertions even
+> after SoundBoard receives completion and runs post-setup initialization.
+> Native preparation publishes fresh completion; after verification, the helper
+> replays the donor's exported notification only for an existing sentinel and
+> gracefully stops only mobile's exact
+> `/Applications/HPSetup.app/HPSetup`, rechecking identity immediately before
+> SIGTERM. It observes disappearance before reporting success; failures retain
+> the inverse for retry. No SIGKILL, arbitrary process verb or new entitlement.
+> Opt-out does not terminate processes. No new instruction patch.
+> vphoned also exposes all 29 `SBSDebugInterface` methods through a fixed,
+> ABI-checked catalog using `com.apple.debuginfo.soundboard`; the HomePod-only
+> Controls section includes native animation/phase choices and typed button and
+> LED replay adapters. The host top cap now uses runtime-compiled Metal 4 optics
+> with a macOS 15 Metal compatibility path. GPU tests and 35 Xcode catalog and
+> selection tests pass. Final bundle `2.11.0-local.26745ac8` passed live late
+> completion (one native init), fresh/repeated boot, and native Metal display
+> presentation/reconnection. Opt-out restored absent keys and setup behavior.
+> See [implementation, live evidence, and service boundaries](Firmware/homepod_soundboard_controls.md).
+
+> **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
+> and vphoned, blocks the Apple TV OTA swap, HD TPRO workaround and iPhone
+> GPU/audio/environment hooks. New `devicetree-cfw-homepod_product` copies
+> concrete `horseman`, `siri-hub` and app architecture capabilities from B520's
+> donor tree only into its installed identity. No new kernel instruction patch.
+> See [HomePod mini support](Firmware/homepod_mini_support.md) for evidence,
+> validation status and limitations.
+ > **iPhone Duo bring-up (2026-10-23, first boot fails):**
+ > `iPhone19,4` / V68AP, iOS 27.1 (24A94425), is registered with one outer
+ > display and paired with cloudOS 26.4 (23E5207q). Its device tree reports
+ > `arm64e.x1`. This exercises the existing standard iOS 27 / ARM64E_X1 patch
+ > selection on a new userland; it introduces no new instruction patch or
+ > preset. Restore and CFW install completed, but setup and a windowed boot
+ > panic with PID 1 SIGILL. Installed dyld still uses CSSC instructions that
+ > this Mac lacks and current X1 lowering does not cover; exact fault-site
+ > attribution remains unverified. Four optional VirtualAudio patches also
+ > failed. Neither successful boot nor dual-display/hinge support is established. See
+ > [inputs, evidence and boot results](Guest/iphone_duo_bringup.md).
> **Experimental full OTA System update (2026-10-20):**
> `system-exp-ota_userland` is off in Standard and the TV presets. For a stopped
diff --cc Research/Firmware/homepod_soundboard_controls.md
index c2b8f715,00000000..fb36d5bf
mode 100644,000000..100644
--- a/Research/Firmware/homepod_soundboard_controls.md
+++ b/Research/Firmware/homepod_soundboard_controls.md
@@@ -1,357 -1,0 +1,356 @@@
+# HomePod SoundBoard controls and setup
+
+## Scope and validation boundary
+
+This extends the HomePod mini support for AudioAccessory5,1, HomePod Software
+27.0 (24J361). The implementation adds a Metal top-cap renderer, the complete
+SoundBoardServices debug interface, and optional local setup completion. Initial
+validation was offline; on 2026-10-22 the owner authorized bundle installation
+and live tests on the existing `homepod-mini` VM. The live results and remaining
+service boundaries are recorded below.
+
+## Runtime Metal renderer
+
+`VPhoneHomePodMetalView` replaces AppKit gradient/LED drawing while native
+buttons retain accessibility, focus and the existing consumer HID input path.
+The source string in `VPhoneHomePodShader.swift` is compiled at runtime using
+`MTL4Compiler` and `MTL4LibraryDescriptor`, then an `MTL4RenderPipelineDescriptor`.
+Submission uses an actual `MTL4CommandQueue`, command allocator, command buffer,
+argument table and explicit residency set. Each of three slots owns its input
+buffers and command memory until GPU feedback. Snapshots arriving while all
+slots are busy collapse to the newest pending frame. The UI does not wait for
+GPU completion. Drawable acquisition/presentation uses the Metal 4 drawable
+wait/signal protocol.
+
+Metal 4 is used on a supporting GPU on macOS 26 or later. The macOS 15 minimum
+is retained with runtime MSL 3.1 compilation and the older command queue API;
+both paths use the same optical shader. There are no `.metal` build inputs,
+`metal`/`metallib` invocations or optional Xcode Metal toolchain dependencies.
+Apple's [Metal 4 compilation API](https://developer.apple.com/documentation/metal/using-the-metal-4-compilation-api)
+and [core API documentation](https://developer.apple.com/documentation/metal/understanding-the-metal-4-core-api),
+checked against the selected SDK headers, describe these separate APIs.
+
+The shader uses the donor device-tree coordinates without stretching the
+unpopulated rim. A normalized Gaussian mixture (weights 0.86/0.14, sigma
+0.155/0.29 in cap coordinates) spreads the guest's two summed light banks.
+Normalization includes unlit emitters so sparse patterns remain visible. A
+smooth radial mask suppresses light near the opaque rim. Exposure and a soft
+shoulder preserve colored highlights; an sRGB render target performs one final
+transfer. Static glass/rim shading and analytic +/- masks supply the surface.
+Only guest brightness controls illumination. There is no time input, host Siri
+animation or interpolated invented frame.
+
+The optical parameters are an approximation informed by the original mini's
+[Apple launch photography](https://www.apple.com/newsroom/2020/10/apple-introduces-homepod-mini-a-powerful-smart-speaker-with-amazing-sound/)
+and [Apple's status-light examples](https://support.apple.com/en-us/101607).
+They reproduce broad mixed light and a dark edge; they are not measurements of
+the diffuser, spectral response or exact layer composition. The current product
+page describes a newer mini and was not treated as B520 hardware evidence.
+
+`VPhoneExecutable/VPhoneVirtualization/Tests/run-homepod-metal-tests.sh` compiles
+the actual shader/backend with Swift and runs without a VM. On macOS 27.0.1,
+Apple M2 Max, the real Metal 4 compiler/queue passed off/white/RGB isolation,
+edge attenuation, independent icon lighting, diffuser blending, identical-frame
+determinism and eight rounds of three concurrent frames. The MSL 3.1 path
+matched Metal 4 output within two byte levels. Synthetic image fixtures are in
+`.build/homepod-metal-tests/`; multicolor fixtures are not evidence of Siri
+working in a guest. The GPU probe needs GPU access outside the process sandbox.
+A separate scratch app compiled the actual `VPhoneHomePodDisplayView`, renderer
+and shader. Its 640-point Retina window displayed the synthetic multicolor
+frame through a real CAMetalDrawable, retained accessible volume buttons, and
+redrew correctly when zoomed to a wide desktop window and restored. This needed
+no VM or installed bundle. The initial scratch-app minimize test hit a UI automation limitation; its two
+owned test processes were terminated. The later live VM window was successfully
+minimized and restored, with continued native frames, as recorded below.
+
+## Complete SoundBoard debug interface
+
+The donor SoundBoardServices cache image was extracted with repaired Objective-C
+metadata and stubs; SHA-256
+`5e5d68df84c8c3a54669a1618ea1cb8f3d12996b4ffe5d9be3828b62917cf41a`.
+REA inventory `ev_9490010b3a7f2ac743b300cfd85baa88060529dde104530675217ac23d7be5e2`
+contains 29 debug methods plus lifecycle methods. Exact argument encodings and
+reply block types were recovered from the original cache's optimized relative
+method lists and `SBSDebugInfoImplementer` protocol, rather than inferred from
+decompiler casts. Original-cache disassembly of `SBSServer` demonstrates the
+`com.apple.debuginfo.soundboard` entitlement gate; vphoned carries that grant.
+SoundBoard's executable is not changed for this interface.
+
+| Group | Exposed selectors |
+| --- | --- |
+| Diagnostics | `getAllDebugInfo:`, `getSelectDebugInfo:reply:` |
+| Display | `getLEDInfo:`, `sendLEDCommand:`, `render:`, `setLEDContents:`, `setBootSpinner:` |
+| Audio | `getVolume:`, `setVolume:`, `playTone:`, `stopTone:`, `siriSay:` |
+| Input | `sendButtonCommand:` |
+| Tuning | `getTuningInfo:`, `setTuningInfoOnBox:at:withValue:` |
+| Preferences | `getUserDefaults:`, `setUserDefaults:withValue:`, `resetUserDefault:`, `resetAllUserDefaults`, `getFeatureFlags:`, `setFeatureFlags:` |
+| Network | `triggerWiFiCoreCapture:`, `setWifiEnabled:`, `disassociateCurrentNetwork`, `disassociateNetworkWithName:` |
+| Software Update | `injectSWUpdateToHome:`, `setHomeUpdateState:`, `clearHomeSWUpdate`, `suScanForSoftwareUpdate` |
+
+`homepod.debug.catalog` advertises the fixed operations and per-method ABI
+availability. `homepod.debug.call` accepts an operation from that catalog and a
+typed arguments object. There is no arbitrary selector invocation. Availability
+requires SoundBoard.app and a loadable `SBSDebugInterface`; `homepod_debug` is
+independent of top-cap patch selection. Host visibility comes from the VM's
+HomePod identity, so this section does not appear for Apple TV or iPhone guests.
+It remains visible but disabled while disconnected and explains unavailable
+guest support.
+
+Seven operations return asynchronous replies (five dictionaries, a feature-flag
+array and Float volume). Reads have a three-second deadline; late replies are
+ignored, and a timed-out XPC client is reopened for a later call. The remaining
+22 native methods have no acknowledgement; the UI reports submission, without
+claiming that SoundBoard applied the command. JSON replies preserve Foundation
+collections and data, and decode native feature flags/default metadata where
+available while retaining archived bytes.
+
+The native wire adapters follow the donor implementations:
+
+- `render:` uses animation and phase strings. All 25 feature names and 20 phase
+ values recovered from the native enum tables appear in pickers. SoundBoard
+ converts space-separated animation words to its feature spelling.
+- `sendButtonCommand:` requires secure archived `HPButtonEvent` data. Typed
+ fields produce the native archive; existing archives can be sent as base64.
+ Buttons are Minus, Plus, Center and Cover (1–4). Actions are TouchMightHaveBegun,
+ TapRegistered, HoldBegan, HoldEnded and TouchCancelled (1–5). Integer widths,
+ tap counts, mach times and Boolean fields are checked before construction.
+- `setLEDContents:` requires a nonempty replay array, not HID report bytes.
+ Each frame contains `LedValuesTimestamp` (ascending UInt64) and
+ `LedValuesData` (native NSData). B520's replay buffer contains 40 Float RGB
+ triples, 480 bytes, including icon channels; it differs from the 245-byte
+ packed MiniDisplay output report. The editor accepts exact base64, RGB triples
+ or an RGB fill and converts to native data with geometry/length validation.
+- Feature-flag dictionaries use `domain`, `feature`, `value`. User-default
+ replies include secure `SBSDefaultInfo` archives, retained as base64 and
+ additionally decoded for readable metadata. Software-update injection retains
+ the native dictionary interface and documented keys in the editor.
+
+`VPhoneDaemon/Tests/run-homepod-debug-tests.sh` exercises all 29 unique catalog
+IDs against a frozen, independently recovered 24J361 method-encoding fixture,
+object/Float replies, typed multi-argument invocation, strict Boolean versus
+numeric types, native button archives (including UInt64.max mach time), replay
+encoding/base64, missing ABI/unknown operation rejection and timeout behavior.
+It also delivers a reply after the timeout and confirms the next request does
+not inherit that stale result. The setup-journal harness explicitly rejects both
+duplicate absent keys and keys appearing in both original and absent sets,
+without writing preferences.
+These host stubs verify marshaling; they do not establish SoundBoard XPC effects.
+Detailed REA records, method encodings, enum tables and annotated cache
+disassembly are retained under `.build/homepod-ui-research/`.
+
+## Setup completion and inverse
+
+`system-homepod-exp-setup_bypass` is a declared optional patch, gated to HomePod
+27.x and enabled only in the `homepod-mini` preset. Other presets explicitly
+disable it, and explicit selection for another family is rejected. Its System
+marker is `/usr/share/vphone/HomePodSetup.plist`, with `Enabled=true`.
+
+The reveal procedure uses the donor's own setup flow:
+
+1. Extract SoundBoardFramework and SetupAssistant from the 24J361 cache with
+ Objective-C/stub repair. Their SHA-256 values are respectively
+ `a352a2ba4025e714ca8b7208490991d821f63387aeb5268c7937974029246749` and
+ `b214983fb007e97304bdb18299a9d71f4828f0563844d3c4134a92f82cb598d9`.
+2. Follow `SBSetupController.deviceNeedsSetup` into
+ `BYSetupAssistantNeedsToRun`. The internal function has an explicit
+ AudioAccessory branch returning the inverse of `SetupDone`; this is not an
+ assumption borrowed from iPhone setup.
+3. Follow `SBSetupController._setBuddyComplete`: it writes `SetupDone` in
+ `com.apple.purplebuddy`, current user/any host, synchronizes, and calls
+ `BYSetupAssistantPrepareLaunchSentinel`. Independently follow
+ `BYSetupAssistantHasCompletedInitialRun` to `SetupFinishedAllSteps`.
+4. Trace stock sentinel preparation/clearing: it uses
+ `sem_open`/`sem_unlink("purplebuddy.sentinel")`, a per-user semaphore, and
+ publishes the native finished notification. SoundBoard's setup check either
+ calls `runSetupGatedInitialization` immediately or waits for that notification.
+ This supports either process launch ordering without invoking SoundBoard's
+ private initialization manually.
+
+Relevant REA records include
+`ev_d061572b15543450b80e40a49a80a4a9fa7a2fb5ea9f98ca432783fc8675f0ba`
+(AudioAccessory gate),
+`ev_ee864420a79b7fcd589e2a5e715f737d1504258744899d0604f78f84875dc202`
+(native completion), and
+`ev_974490d0674d54c2e49d69fb08ea8dab75d760c323cb8d5574fd6b9037858fce`
+(sentinel preparation). Unresolved decompiler stubs were correlated with original
+cache disassembly. These are reconstructed control-flow observations, not source.
+
+Data is encrypted during host installation. The installer instead stages
+`vphone-homepod-setup` and a launchd job running as mobile (501). Before its
+first write the helper saves exactly the original two preference values,
+including which keys were absent, in
+`/var/mobile/Library/Application Support/vphone/HomePodSetupOriginal.plist`
+(0600 inside a 0700 directory). Repeated boots preserve the first inverse and
+leave unrelated preferences alone. After synchronization it calls stock
+sentinel preparation and requires `NeedsToRun=false` and
+`HasCompletedInitialRun=true`. Native preparation publishes completion when
+creating the sentinel. If the native gate was already complete immediately
+before preparation, the helper replays the donor's exported
+`BYSetupAssistantFinishedDarwinNotification` instead, avoiding duplicate
+post-setup initialization for a newly created sentinel. It gracefully ends any remaining
+mobile HPSetup session. Process enumeration is restricted to effective UID 501;
+the full `/Applications/HPSetup.app/HPSetup` executable path is checked again
+immediately before SIGTERM. A bounded disappearance/quiet check handles an app
+launch already in flight. There is no escalation to SIGKILL. Missing process
+APIs, unreadable owned-process identity, signal errors or a lingering setup
+process make the helper fail and retry, retaining its original-key journal.
+Status/error/date are written to
+`HomePodSetupStatus.plist` in the same directory.
+
+On deselection the marker is removed, and the helper restores just those two
+keys, prepares the stock sentinel and verifies the restored native state before
+deleting the journal. A failed synchronization or native verification keeps the
+journal for retry. The runtime is installed for every HomePod environment update
+even if vphoned and the bypass are deselected, so opt-out retains a rollback
+path. With neither marker nor journal the helper exits without loading the
+framework or modifying preferences. launchd retries unsuccessful runs with a
+15-second throttle; successful runs exit.
+
+This supplies local setup completion only. It does not create activation
+tickets, Apple Account credentials, a HomeKit home, network pairing or identity.
+`make -C VPhoneGuestComponents test-homepod-setup` passed journal creation,
+idempotence, absent/existing-key restoration, unrelated edits, synchronization
+failure retention, invalid/duplicate journal rejection and file-mode checks.
+Native transition tests additionally model the donor's creation-only event and
+verify one fresh-completion event, one existing-sentinel recovery event, no
+opt-out publication, and no publication after failed verification. This
+conditional relies on the analyzed retail HomePod path (`ForceNoBuddy=false`);
+internal NonUI/unsupported overrides and concurrent external sentinel mutation
+are outside that evidence. The tvOS arm64e helper builds and signs with system
+SDK/framework dependencies.
+All 35 owning Xcode catalog/selection tests passed, including preset roundtrips,
+version/family gates and exclusion of Apple TV payloads.
+The process harness additionally covers both launch orderings, an in-flight
+launch, exact executable matching, identity changes before signaling, denied
+identity lookup, enumeration failure, timeout without stronger signals and
+refusal to operate as another user.
+
+Xcode MCP builds of `vphone-vm` and the iOS-device `vphoned` target passed.
+The aggregate `VPhone` scheme is absent from MCP's scheme list, so the finished
+bundle was built with the documented `xcodebuild` fallback and passed both bundle
+admission and `codesign --verify --deep --strict`. The initial offline build log is
+`.build/homepod-ui-research/metal-debug-setup-bundle-build.log`; subsequent live
+iteration logs are in `.build/homepod-ui-research/live-metal-debug-setup/`.
+
+## Live validation scope
+
+The completed tests cover signed bundle installation, real Metal drawable
+presentation and window lifecycle, native XPC queries and representative
+reversible writes, setup completion from an unconfigured baseline, late
+HPSetup teardown, repeat boot and opt-out restoration. All 29 operations are
+exposed and runtime ABI-available; all seven query operations return native
+replies. The remaining write methods are submission-only native APIs. Their
+physical Wi-Fi, tuning, update/HomeKit and Apple-service effects depend on guest
+hardware and real provisioning; interface availability is not proof of those
+effects. Audible tone/speech output and cloud Siri requests were not established.
+TestLEDDraw's internal-content gate is documented rather than bypassed.
+
+## Live investigation (2026-10-22)
+
+The owner authorized bundle updates. Launchpad installed
+`2.11.0-local.352ddbd3` with `--keep-default`, rebound only `homepod-mini`, and
+updated its guest environment through the normal helper. An APFS clone of the
+stopped VM disk and its original patch selection were saved under
+`.build/homepod-ui-research/live-metal-debug-setup/` before mutation.
+
+- The guest booted in five seconds. All 29 runtime method signatures are
+ available. All seven reads returned native replies, including 150 default
+ records and 2,917 feature flags. Volume changed from 0.53 to 0.58 and read
+ back within Float precision, then was restored. A debug default changed and
+ reset with readback. Tone 0 was submitted and stopped; audible output has not
+ yet been established.
+- The real HomePod Controls window shows the complete grouped operation menu,
+ argument editors and animation/phase choices. Native volume input produced
+ the white HUD through the Metal renderer. A native replay with 40 red RGB
+ triples produced nineteen red HID pixels and lit icon channels; the real cap
+ rendered red. Evidence includes `native-volume-metal.png` and
+ `native-replay-red-metal.png` in that directory.
+- Further native tracing establishes prerequisites that are now described in
+ the catalog help: `render:` needs `HomePodBuddyConnection=1` and SoundBoard
+ restart to create its debug Buddy controller. `sendLEDCommand:` requires the
+ TestLEDDraw activity, created only on internal-content builds. Retail firmware
+ may accept and ignore it; this is distinct from shader or wire-format failure.
+ The native all-color grammar is `all 255 0 0` (channels divided by 256), and an
+ empty command clears TestLEDDraw. Replay works independently of those gates.
+ Its exact order is nineteen Siri RGB triples, two icon RGB triples, then
+ nineteen AOD RGB triples. Times are deltas from the first timestamp; a single
+ black frame replaces replay and ends it safely. Empty arrays are rejected
+ because the native implementation indexes the first element unconditionally.
+- `SoundBoardFinishedSetup=false` does not contradict configured startup. It
+ is a legacy persisted diagnostic record, while functional activity/application
+ gates use `SBSetupController.deviceNeedsSetup` → native SetupAssistant state.
+ Already-completed startup intentionally skips the legacy controller and goes
+ directly to post-setup initialization. The bounded source analysis and REA
+ IDs are in `soundboard-finished-setup-findings.md` under the evidence directory's
+ parent. Real HomeKit provisioning remains separate.
+- Initial opt-out restored the two original values and removed the journal.
+ A temporary mobile fixture then removed exactly the two completion keys and
+ called stock sentinel preparation: native NeedsSetup became true and initial
+ run completion false. Restarting SoundBoard brought HPSetup to the foreground
+ and disabled Siri, establishing a real unconfigured baseline.
+- **Late-start defect reproduced and corrected:** with that unconfigured baseline, the shipped helper was
+ deliberately disabled at boot and then started after HPSetup was active.
+ It reported success and changed the native predicates, but HPSetup remained
+ foreground and Siri remained disabled. The flags alone do not prove successful
+ late completion. Captured native logs show `setupdone` received,
+ `_setupFinished` and `Doing post setup init`; that path alone does not dismiss
+ HPSetup. A graceful termination of only the verified HPSetup process immediately
+ removed the foreground activity and enabled Siri/Hey Siri. The helper now
+ performs that exact teardown after verified completion and reports success
+ only after disappearance. Bundle `2.11.0-local.a2a1cf33` passed the controlled
+ late-start test: native needs-setup was false, initial-run completion true,
+ HPSetup process count zero, and Siri/Hey Siri enabled. Its bundled and running
+ helper hashes matched. Logs showed graceful HPSetup exit and released
+ assertions. This first correction also exposed duplicate completion
+ notifications; the conditional publication described above addresses that.
+- Opt-out on the corrected helper restored both originally absent completion
+ keys, removed the inverse journal and returned native NeedsSetup=true /
+ CompletedInitialRun=false. A new boot ran HPSetup in the foreground with Siri
+ disabled, confirming restoration rather than just marker removal.
+
+The final bundle is `2.11.0-local.26745ac8`, installed through Launchpad and
+bound only to `homepod-mini`; the library default and other VMs are unchanged.
+The final helper SHA-256 is
+`1e7ec8eb39b18055ab0e11d4aa2b719f964b86397d06cd59583baef48f103f8e`, verified
+against bytes read back from the running guest. Final results:
+
+- With HPSetup deliberately running before the helper, captured SoundBoard logs
+ contain exactly one `setupdone`, one `_setupFinished`, and one `Doing post
+ setup init`. HPSetup exited by SIGTERM, its assertions were invalidated, and
+ native Siri/Hey Siri became enabled. The helper reported success only after
+ the process disappeared.
+- A fresh normal boot from native NeedsSetup=true / CompletedInitialRun=false
+ completed successfully without HPSetup remaining. A second normal boot
+ reported fresh success, preserved the original absent-key journal, and kept
+ Siri/Hey Siri enabled with no foreground setup activity. These cover normal
+ concurrent startup and deliberately late helper startup; only the latter
+ has a controlled, observed process ordering.
+- Native Siri `On` then `Thinking` produced changing multicolor inner-bank
+ frames through SoundBoard → virtual MiniDisplay HID → guest WebSocket → the
+ actual Metal cap. The live window redrew when zoomed and restored. It also
+ redrew after minimize/restore; restoring required the owner because the UI
+ automation tool could not reactivate a minimized `.bundle` through Launch
+ Services. Native volume HUD and replay-color presentation were tested above.
+- Restarting SoundBoard recovered debug replies. Restarting vphoned interrupted
+ the request as expected, then display reports and queries resumed; the new
+ display generation had zero rejected reports. The short disconnect's blank
+ frame was not separately captured.
+- The actual Controls menu lists all 29 operations. Its live volume reply and
+ final Center/TapRegistered `coalesced:true` editor were inspected. Other
+ hardware/service-dependent effects remain within the boundary above.
+- Cleanup reset `HomePodBuddyConnection` to its stock false value, restarted
+ SoundBoard, restored the original volume 0.53, and removed the temporary
+ fixture job/output. Boot had removed the fixture binary/plist from `/var/tmp`.
+ The final selection is the `homepod-mini` preset with empty override lists,
+ setup helper enabled, native setup complete, and the final GUI VM running.
+- No SoundBoard, vphoned or setup-helper crash report was present. Existing
+ guest `ProxiedCrashCopier`, locationd and other service reports remain; the
+ result is not a claim that all donor daemons run without faults.
+
+Evidence is in `.build/homepod-ui-research/live-metal-debug-setup/`: final
+bundle build log; `final-late-*`, `final-normal-*`, `final-repeat-*` and
+`corrected-optout-*` native records; `final-native-siri-metal*.png`,
+`final-native-metal-restored.png`, and Controls screenshots. The APFS disk clone
+and original patch selection are retained there for local recovery. No
+activation ticket, Apple Account or HomeKit identity was fabricated. The
+fixture is not shipped in the bundle.
-
diff --cc VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreeGuestDevicePatches.swift
index f08a54af,c6b1dc50..29022e32
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreeGuestDevicePatches.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreeGuestDevicePatches.swift
@@@ -63,7 -62,9 +63,10 @@@ extension DeviceTreePatcher
static let iPadIdentityPatch = "devicetree-cfw-ipad_identity"
static let iPadAudioPatch = "devicetree-cfw-ipad_audio"
static let tvAppArchitecturePatch = "devicetree-cfw-tv_app_architecture"
+ static let homePodProductPatch = "devicetree-cfw-homepod_product"
+ static let watchPresentationPatch = "devicetree-cfw-watch_presentation"
+ static let watchDriverKitPatch = "devicetree-cfw-watch_driverkit"
+ static let watchCompanionPatch = "devicetree-cfw-watch_companion"
static let hapticsPatch = "devicetree-cfw-product_haptics_node"
static let microphoneArrayPatch = "devicetree-cfw-product_audio_microphone_array"
@@@ -174,23 -175,13 +177,29 @@@
action: .set(architecture), patchID: tvAppArchitecturePatch))
}
+ // B520's accessory identity is independent of its artwork idiom,
+ // which is a syscfg placeholder rather than "tv". HomePod services
+ // query these capabilities through MobileGestalt.
+ if let model = value(source, "model"),
+ String(decoding: model.prefix { $0 != 0 }, as: UTF8.self) == "AudioAccessory5,1"
+ {
+ for name in ["horseman", "siri-hub", "app-macho-architecture"] {
+ let action: GuestEdit.Action = value(sourceProduct, name).map { .set($0) } ?? .remove
+ edits.append(GuestEdit(nodePath: product, property: name,
+ action: action, patchID: homePodProductPatch))
+ }
+ // Keep the VM product token. Audio uses VirtualAudio's local
+ // ProductIDOverride; a donor token changes unrelated MG clients.
+ }
+
+ if let idiom = value(sourceProduct, "artwork-device-idiom"),
+ String(decoding: idiom.prefix { $0 != 0 }, as: UTF8.self) == "watch"
+ {
+ edits += watchEdits(product: product, value: { value(sourceProduct, $0) })
+ }
+
for (name, patchID) in copiedProductProperties {
+
let action: GuestEdit.Action = value(sourceProduct, name).map { .set($0) } ?? .remove
edits.append(GuestEdit(nodePath: product, property: name, action: action, patchID: patchID))
}
diff --cc VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
index 7e371450,abf2b4de..71cbe361
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwarePatchSetCatalog.swift
@@@ -315,23 -323,90 +323,106 @@@ public enum FirmwarePatchSetCatalog
),
)
+ /// HomePod mini uses its own monolithic arm64e TVOS IPSW. Keep the 27
+ /// kernel compatibility patches, but never swap in an Apple TV OTA or
+ /// install the iPhone GPU/routing environment. The shared virtio audio
+ /// driver selects native B520 routing through an audio-only preference,
+ /// retaining the original VM product token for other services.
+ public static let homePodMiniPreset = VPhonePatchPreset(
+ identifier: VPhonePatchPreset.homePodMiniIdentifier,
+ title: "HomePod mini",
+ summary: "Research: HomePod mini's own arm64e TVOS IPSW with vphoned, its donor-driven top cap, local setup completion and virtio audio using an audio-only B520 route, without changing the VM product token or adding Apple TV OTA replacement or iPhone display, camera and routing hooks.",
+ patchSets: bundledReferences,
+ selection: .block(
+ manualOnlyPatches.subtracting([FirmwareGuestSystemPatchSet.homePodTopCap, FirmwareGuestSystemPatchSet.homePodSetupBypass, FirmwareGuestSystemPatchSet.homePodWelcome, FirmwareGuestSystemPatchSet.homePodSiriSpeech, FirmwareGuestSystemPatchSet.homePodOTAUserland, FirmwareGuestSystemPatchSet.homePodSoundGlow])
+ .union(tvOSBlockedPatches.subtracting(tvOS27UserlandPatches).subtracting([FirmwareGuestSystemPatchSet.virtioSoundDriver])),
+ ),
+ )
+
- /// The presets the bundle ships.
+ /// The device tree patches ``minimalPreset`` keeps: the board presentation the
+ /// guest UI lays out against, and the haptics and microphone array no VM
+ /// has. They change no code, so they are no system modification.
+ public static let minimalDeviceTreePatches: Set<String> = [
+ "devicetree-cfw-serial_number",
+ "devicetree-cfw-home_button_type",
+ "devicetree-cfw-artwork_device_subtype",
+ "devicetree-cfw-island_notch_location",
+ "devicetree-cfw-product_haptics_node",
+ "devicetree-cfw-product_audio_microphone_array",
+ "devicetree-cfw-watch_companion",
+ ]
+
+ /// The boot chain patches ``minimalPreset`` keeps: iBEC's and LLB's, which the
+ /// old `.less` variant applied too. A stock LLB does not get the restored
+ /// guest to its kernel (it restarts after its banner, with Apple's ROMs as
+ /// with OpenAVB and OpenSEP). AVPBooter, iBSS, TXM and the restore ramdisk
+ /// stay stock.
+ public static let minimalBootChainPatches: Set<String> = [
+ "ibec-cfw-serial_label",
+ "ibec-boot-image4_callback",
+ "ibec-boot-boot_args",
+ "ibec-boot-bootx_precondition",
+ "llb-cfw-serial_label",
+ "llb-boot-image4_callback",
+ "llb-boot-boot_args",
+ "llb-boot-rootfs",
+ "llb-boot-panic_bypass",
+ "llb-cfw-display_scale",
+ ]
+
+ /// A guest on a stock kernel and TXM, with only iBEC and LLB patched: the
+ /// system is customised before the restore instead
+ /// (``FirmwareRestoreImagePatchSet``), and nothing after it. Names only the
+ /// sets it draws on, so no kernel or guest patcher is built.
+ /// The shipped `minimal.plist` must match this.
+ public static let minimalPreset = VPhonePatchPreset(
+ identifier: VPhonePatchPreset.minimalIdentifier,
+ title: "Minimal",
+ summary: "No kernel or TXM patches and only iBEC and LLB in the boot chain: the restore installs a resealed system with vphoned, the GPU driver and activation, and nothing writes it afterwards.",
+ patchSets: [
+ .bundled(FirmwareBootChainPatchSet.identifier),
+ .bundled(FirmwareResearchBoardPatchSet.identifier),
+ .bundled(FirmwareDeviceTreePatchSet.identifier),
+ .bundled(FirmwareRestoreImagePatchSet.identifier),
+ ],
+ selection: .allow(
+ minimalBootChainPatches
+ .union(minimalDeviceTreePatches)
+ .union(FirmwareResearchBoardPatchSet.manifest.patches.map(\.identifier))
+ .union(FirmwareRestoreImagePatchSet.manifest.patches.map(\.identifier)),
+ ),
+ )
+
+ /// The device tree patches ``watchOSPreset`` keeps: the board presentation
+ /// of its own tree, the watch display and DriverKit, and what no VM has.
+ public static let watchOSDeviceTreePatches: Set<String> = [
+ "devicetree-cfw-serial_number",
+ "devicetree-cfw-ipad_artwork",
+ "devicetree-cfw-ipad_product",
+ "devicetree-cfw-ipad_buttons",
+ "devicetree-cfw-ipad_identity",
+ "devicetree-cfw-ipad_audio",
+ "devicetree-cfw-watch_presentation",
+ "devicetree-cfw-watch_driverkit",
+ "devicetree-cfw-product_haptics_node",
+ "devicetree-cfw-product_audio_microphone_array",
+ ]
- public static let builtInPresets: [VPhonePatchPreset] = [standardPreset, experimentalPreset, tvOSPreset, tvOS4KPreset, homePodMiniPreset]
+ /// ``minimalPreset`` for an Apple Watch: its device tree presents the watch
+ /// board. The shipped `watchos.plist` must match this.
+ public static let watchOSPreset = VPhonePatchPreset(
+ identifier: VPhonePatchPreset.watchOSIdentifier,
+ title: "Apple Watch",
+ summary: "Minimal for an Apple Watch guest: the watch board's device tree, and a resealed system with vphoned, the GPU driver and activation restored onto a stock kernel and TXM.",
+ patchSets: minimalPreset.patchSets,
+ selection: .allow(
+ minimalBootChainPatches
+ .union(watchOSDeviceTreePatches)
+ .union(FirmwareResearchBoardPatchSet.manifest.patches.map(\.identifier))
+ .union(FirmwareRestoreImagePatchSet.manifest.patches.map(\.identifier)),
+ ),
+ )
+
+ /// The presets the bundle ships.
- public static let builtInPresets: [VPhonePatchPreset] = [standardPreset, experimentalPreset, tvOSPreset, tvOS4KPreset, minimalPreset, watchOSPreset]
++ public static let builtInPresets: [VPhonePatchPreset] = [standardPreset, experimentalPreset, tvOSPreset, tvOS4KPreset, homePodMiniPreset, minimalPreset, watchOSPreset]
}
diff --cc VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
index 80515ccd,c8cf4afe..fe868b6a
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwarePatchSetCatalogTests.swift
@@@ -135,10 -135,20 +135,20 @@@ struct FirmwarePatchSetCatalogTests
// Nothing a shipped iOS preset does should drop a boot-essential
// patch: these are the combinations we claim boot. The tvOS
// presets drop exactly the iOS ones an Apple TV has no port of.
- let tvPresets = [VPhonePatchPreset.tvOSIdentifier, VPhonePatchPreset.tvOS4KIdentifier]
+ let tvPresets = [VPhonePatchPreset.tvOSIdentifier, VPhonePatchPreset.tvOS4KIdentifier, VPhonePatchPreset.homePodMiniIdentifier]
- let expected = tvPresets.contains(preset.identifier)
- ? Set(plan.droppedBootEssentials).isSubset(of: FirmwarePatchSetCatalog.tvOSBlockedPatches)
- : plan.droppedBootEssentials.isEmpty
+ // `minimal` drops every boot chain patch but iBEC's and LLB's:
+ // its system is customised before the restore instead.
+ let restoreImagePresets = [VPhonePatchPreset.minimalIdentifier, VPhonePatchPreset.watchOSIdentifier]
+ let expected = if tvPresets.contains(preset.identifier) {
+ Set(plan.droppedBootEssentials).isSubset(of: FirmwarePatchSetCatalog.tvOSBlockedPatches)
+ } else if restoreImagePresets.contains(preset.identifier) {
+ Set(plan.droppedBootEssentials).isDisjoint(with: FirmwarePatchSetCatalog.minimalBootChainPatches)
+ && plan.droppedBootEssentials.allSatisfy {
+ FirmwareBootChainPatchSet.manifest.patches.map(\.identifier).contains($0)
+ }
+ } else {
+ plan.droppedBootEssentials.isEmpty
+ }
#expect(
expected,
"\(preset.identifier) on \(base)/\(cloud) drops \(plan.droppedBootEssentials)",
diff --cc VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift
index f373a935,8d64047c..af346216
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift
@@@ -1,6 -1,6 +1,7 @@@
import ArgumentParser
+ import FirmwarePatcher
import Foundation
+import VPhoneArchiveKit
import VPhoneCoreKit
import VPhonePatchKit
@@@ -87,68 -87,62 +88,93 @@@ struct VPhoneVirtualMachineCreateComman
@Flag(name: .customShort("v"), help: "Increase verbosity: -v tool detail, -vv guest serial, -vvv internal trace")
var verboseCount: Int
- private var isAppleTV: Bool {
- VPhoneGuestDevice.named(device)?.family == .appleTV
+ /// A local donor can identify the guest even when --device is omitted.
+ /// Validation reads it once; explicit device selection always takes precedence.
+ private var inferredProductType: String?
+
+ private var selectedGuest: VPhoneGuestDevice? {
+ VPhoneGuestDevice.named(device ?? inferredProductType)
+ }
+
+ private var selectedDevice: String? {
+ device ?? inferredProductType
+ }
+
+ private var ipswCacheDirectory: URL {
+ ipswCache.map {
+ URL(fileURLWithPath: ($0 as NSString).expandingTildeInPath, isDirectory: true)
+ } ?? VPhoneResources.ipswCacheDirectory()
+ }
+
+ private var usesTVOS: Bool {
+ selectedGuest?.usesTVOS == true
}
+ /// A preset that customises the system before the restore (`minimal`): the
+ /// offline trim and the setup boot of a template write the System volume,
+ /// which would break that system's seal.
+ private var customisesRestoredSystem: Bool {
+ VPhonePatchPresetStore.preset(named: preset ?? defaultPreset)?.patchSets
+ .contains { $0.identifier == FirmwareRestoreImagePatchSet.identifier } ?? false
+ }
+
/// An Apple TV takes the TV preset; one whose userland comes from an OTA
- /// takes the arm64e one, with the GPU driver and the userland swap.
+ /// takes the arm64e one, with the GPU driver and the userland swap. An
+ /// Apple Watch takes the watch preset, an iPhone XS Max `minimal`: its iOS 18
+ /// research board kernel boots no other.
private var defaultPreset: String {
- guard let guest = selectedGuest, guest.usesTVOS else {
- return VPhonePatchPreset.standardIdentifier
- switch VPhoneGuestDevice.named(device) {
++ switch selectedGuest {
+ case let guest? where guest.family == .appleTV:
+ guest.restoreBase == nil ? VPhonePatchPreset.tvOSIdentifier : VPhonePatchPreset.tvOS4KIdentifier
++ case let guest? where guest.family == .homePod:
++ VPhonePatchPreset.homePodMiniIdentifier
+ case let guest? where guest.family == .watch:
+ VPhonePatchPreset.watchOSIdentifier
+ case let guest? where guest.notchedArtworkSubtype != nil:
+ VPhonePatchPreset.minimalIdentifier
+ default:
+ VPhonePatchPreset.standardIdentifier
}
- if guest.family == .homePod { return VPhonePatchPreset.homePodMiniIdentifier }
- return guest.restoreBase == nil ? VPhonePatchPreset.tvOSIdentifier : VPhonePatchPreset.tvOS4KIdentifier
}
- func validate() throws {
+ mutating func validate() throws {
+ // Named templates reject firmware options below and need no IPSW read.
+ // localArchive also recognizes an existing cached remote source without
+ // downloading or changing the cache.
+ if template == nil, device == nil, let iphoneSource,
+ let archive = try VPhoneIPSWCache.localArchive(iphoneSource, in: ipswCacheDirectory)
+ {
+ inferredProductType = VPhoneIPSWCache.guestDevice(for: archive)?.productType
+ }
+
if template != nil, noTemplate {
throw ValidationError("--template and --no-template exclude each other.")
}
if noTemplate, try !slimming.request.isEmpty {
throw ValidationError("The slimming switches shape a template; --no-template builds the VM without one.")
}
- if otaSource != nil || otaKey != nil, VPhoneGuestDevice.named(device)?.restoreBase == nil {
- throw ValidationError("--ota-source and --ota-key are for a device Apple ships no IPSW for, such as --device AppleTV14,1.")
+ if otaSource != nil || otaKey != nil,
+ VPhoneGuestDevice.named(device)?.restoreBase == nil,
+ VPhoneGuestDevice.named(device)?.family != .homePod {
+ throw ValidationError("--ota-source and --ota-key require an OTA userland device, such as --device AppleTV14,1 or AudioAccessory5,1.")
}
- if isAppleTV {
+ if usesTVOS {
// Templates and their setup boot drive iOS Setup Assistant and its apps.
if template != nil {
- throw ValidationError("An Apple TV guest is built without a template; --template cannot be used.")
+ throw ValidationError("A tvOS or HomePod guest is built without a template; --template cannot be used.")
}
if try !slimming.request.isEmpty {
- throw ValidationError("An Apple TV guest is built without a template; the slimming switches do not apply.")
+ throw ValidationError("A tvOS or HomePod guest is built without a template; the slimming switches do not apply.")
}
}
+ if customisesRestoredSystem {
+ if template != nil {
+ throw ValidationError("The \(preset ?? defaultPreset) preset builds a VM without a template; --template cannot be used.")
+ }
+ if try !slimming.request.isEmpty {
+ throw ValidationError("The \(preset ?? defaultPreset) preset builds a VM without a template; the slimming switches do not apply.")
+ }
+ }
_ = try slimming.resolve()
if template != nil {
let firmware = [
@@@ -173,7 -167,7 +199,7 @@@
let unlocks = try unlockAtStartup.map { try VPhoneVirtualMachineConfigCommand.parseSwitch($0, option: "--unlock-at-startup") }
let templateUse: VPhoneVirtualMachineCreator.TemplateUse = if let template {
.identifier(template)
- } else if noTemplate || usesTVOS {
- } else if noTemplate || isAppleTV || customisesRestoredSystem {
++ } else if noTemplate || usesTVOS || customisesRestoredSystem {
.none
} else {
.automatic
diff --cc VPhoneExecutable/VPhoneCommand/VPhonePatchKit/PatchSet/VPhonePatchPreset.swift
index 1afa6410,83be7547..5b8cfda2
--- a/VPhoneExecutable/VPhoneCommand/VPhonePatchKit/PatchSet/VPhonePatchPreset.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhonePatchKit/PatchSet/VPhonePatchPreset.swift
@@@ -82,8 -86,9 +86,11 @@@ public struct VPhonePatchPreset: Sendab
/// userland taken from the device's OTA.
public static let tvOS4KIdentifier = "tvos-4k"
+ /// HomePod mini's own arm64e TVOS IPSW, without an OTA userland swap.
+ public static let homePodMiniIdentifier = "homepod-mini"
+ /// The identifier an Apple Watch guest gets: ``minimalIdentifier`` for a
+ /// watch, which presents its own board.
+ public static let watchOSIdentifier = "watchos"
/// Whether this is the preset a VM gets by default.
public var isStandard: Bool {
diff --cc VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
index 071ead01,cd894067..adb339d0
--- a/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
+++ b/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh
@@@ -120,12 -144,12 +144,12 @@@ if /usr/bin/grep -q 'AVPSEPBooter-' "$r
exit 1
fi
- for name in vphoned vphoned-tvos launchdhook-vphone.dylib SystemHook-vphone.dylib libcamfix.dylib \
+ for name in vphoned vphoned-tvos vphoned-watchos 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 vphone-homepod-setup libAppleParavirtCompilerPluginIOGPUFamily.dylib; do
require_signed_macho "$guest/$name"
done
-for name in vphoned.plist libcamfix.plist libvcamcaptured.plist libmisfix.plist; do
+for name in vphoned.plist libcamfix.plist libvcamcaptured.plist libmisfix.plist com.vphone.homepod-setup.plist; do
[[ -f "$guest/$name" ]] || { print -u2 "Missing guest configuration: $name"; exit 1; }
done
# The virtio sound HAL plugin is a whole bundle: audiomxd finds its factory
diff --cc VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
index e8605f91,00000000..f12453c9
mode 100644,000000..100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/homepod-mini.plist
@@@ -1,136 -1,0 +1,145 @@@
+<?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">
+<plist version="1.0">
+<dict>
+ <key>Identifier</key>
+ <string>homepod-mini</string>
+ <key>PatchSets</key>
+ <array>
+ <dict>
+ <key>Identifier</key>
+ <string>com.vphone.patchset.bootchain</string>
+ <key>Kind</key>
+ <string>Bundled</string>
+ </dict>
+ <dict>
+ <key>Identifier</key>
+ <string>com.vphone.patchset.kernel.base</string>
+ <key>Kind</key>
+ <string>Bundled</string>
+ </dict>
+ <dict>
+ <key>Identifier</key>
+ <string>com.vphone.patchset.kernel.cfw</string>
+ <key>Kind</key>
+ <string>Bundled</string>
+ </dict>
+ <dict>
+ <key>Identifier</key>
+ <string>com.vphone.patchset.kernel.hypervisor</string>
+ <key>Kind</key>
+ <string>Bundled</string>
+ </dict>
+ <dict>
+ <key>Identifier</key>
+ <string>com.vphone.patchset.kernel.frida</string>
+ <key>Kind</key>
+ <string>Bundled</string>
+ </dict>
++ <dict>
++ <key>Identifier</key>
++ <string>com.vphone.patchset.research.board</string>
++ <key>Kind</key>
++ <string>Bundled</string>
++ </dict>
+ <dict>
+ <key>Identifier</key>
+ <string>com.vphone.patchset.devicetree</string>
+ <key>Kind</key>
+ <string>Bundled</string>
+ </dict>
+ <dict>
+ <key>Identifier</key>
+ <string>com.vphone.patchset.guest.system</string>
+ <key>Kind</key>
+ <string>Bundled</string>
+ </dict>
+ <dict>
+ <key>Identifier</key>
+ <string>com.vphone.patchset.guest.display</string>
+ <key>Kind</key>
+ <string>Bundled</string>
+ </dict>
+ <dict>
+ <key>Identifier</key>
+ <string>com.vphone.patchset.guest.identity</string>
+ <key>Kind</key>
+ <string>Bundled</string>
+ </dict>
+ </array>
+ <key>Selection</key>
+ <dict>
+ <key>Kind</key>
+ <string>Block</string>
+ <key>Patches</key>
+ <array>
+ <string>system-exp-ota_userland</string>
+ <string>kernel-exp-frida_thread_set_state_entitlement_flag</string>
++ <string>kernel-exp-frida_tpro_off</string>
++ <string>kernel-exp-frida_syscall_filter_off</string>
+ <string>kernel-cfw-paravirt_gpu_task3</string>
+ <string>kernel-exp-frida_vm_map_delete_immutable_code</string>
+ <string>kernel-exp-hv_vmm</string>
+ <string>dyld-exp-hv_vmm</string>
+ <string>system-watchdogd-exp-hv_vmm_cache</string>
+ <string>devicetree-exp-target_sub_type</string>
+ <string>devicetree-exp-compatible_secondary</string>
+ <string>devicetree-exp-product_fdr_product_type</string>
+ <string>devicetree-exp-product_sub_product_type</string>
+ <string>devicetree-exp-product_unique_model</string>
+ <string>devicetree-exp-product_gestalt_variants_rename</string>
+ <string>devicetree-exp-arm_io_device_type</string>
+ <string>devicetree-exp-arm_io_soc_generation</string>
+ <string>preboot-exp-devicetree_identity</string>
+ <string>dyld-exp-mis_trust_auth</string>
+ <string>system-preferences-exp-root_rows</string>
+ <string>dyld-exp-settings_software_update_row</string>
+ <string>dyld-boot-arm64e_x1_bootstrap</string>
+ <string>dyld-boot-iomfb_swapend</string>
+ <string>dyld-cfw-camera</string>
+ <string>kernel-boot-arm64e_x1</string>
+ <string>preboot-cfw-devicetree_board_audio</string>
+ <string>preboot-cfw-devicetree_haptics</string>
+ <string>preboot-cfw-devicetree_iphone_product</string>
+ <string>preboot-cfw-devicetree_microphone_array</string>
+ <string>preboot-homepod-exp-audio_product</string>
+ <string>restoreramdisk-boot-apfs_sha3_hash</string>
+ <string>system-apps-cfw-attitude</string>
+ <string>system-backboardd-cfw-gyroscope</string>
+ <string>system-backboardd-cfw-accelerometer</string>
+ <string>system-campo-cfw-entitlements</string>
++ <string>system-bluetoothd-cfw-btvc_le_connection</string>
+ <string>system-debugserver-cfw-install</string>
+ <string>system-dyld-boot-arm64e_x1_bootstrap</string>
+ <string>system-diskimagesiod-cfw-is_mount_complete</string>
+ <string>system-extensions-boot-gpu_bundle</string>
+ <string>system-tv-exp-ota_userland</string>
+ <string>system-fsck-boot-arm64e_x1_bootstrap</string>
+ <string>system-installcoordination_proxy-cfw-persona_lookup</string>
+ <string>system-jetsamproperties-cfw-disable_allowed</string>
+ <string>system-launchd-boot-arm64e_x1_bootstrap</string>
+ <string>system-launchd-boot-jetsam_panic_guard_bypass</string>
+ <string>system-launchdaemons-boot-environment</string>
+ <string>system-locationd-cfw-disable_auto_cohort</string>
+ <string>system-mobileactivationd-boot-should_hactivate</string>
+ <string>system-mount-boot-arm64e_x1_bootstrap</string>
+ <string>system-paravirt_gpu-cfw-heap_index_offset</string>
+ <string>system-systemhook-cfw-metal_cache_reuse</string>
+ <string>system-systemversion-cfw-build_version</string>
+ <string>system-virtualaudio-cfw-microphone_graph_chains</string>
+ <string>system-virtualaudio-cfw-mute_set_throw</string>
+ <string>system-virtualaudio-cfw-speaker_graph_chains</string>
+ <string>system-virtualaudio-cfw-speaker_protection_gate</string>
+ <string>system-virtualaudio-cfw-speaker_raw_chains</string>
+ <string>system-virtualaudio-cfw-speaker_route_throws</string>
+ <string>system-virtualaudio-cfw-volume_mode_precondition</string>
+ <string>system-dyld-exp-tv_tpro</string>
+ <string>kernel-exp-tv_tpro_pagers</string>
+ </array>
+ </dict>
+ <key>Summary</key>
+ <string>Research: HomePod mini's own arm64e TVOS IPSW with vphoned, its donor-driven top cap, local setup completion and virtio audio using an audio-only B520 route, without changing the VM product token or adding Apple TV OTA replacement or iPhone display, camera and routing hooks.</string>
+ <key>Title</key>
+ <string>HomePod mini</string>
+</dict>
+</plist>
diff --cc VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
index 7c408836,1e492ec9..f140853d
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/patches_presets/standard.plist
@@@ -67,15 -73,10 +73,17 @@@
<string>Block</string>
<key>Patches</key>
<array>
+ <string>system-homepod-exp-top_cap</string>
+ <string>system-homepod-exp-setup_bypass</string>
+ <string>system-homepod-exp-welcome</string>
+ <string>system-homepod-exp-siri_speech</string>
+ <string>system-homepod-exp-ota_userland</string>
+ <string>system-homepod-exp-sound_glow</string>
+ <string>preboot-homepod-exp-audio_product</string>
<string>kernel-exp-frida_thread_set_state_entitlement_flag</string>
<string>kernel-exp-frida_vm_map_delete_immutable_code</string>
+ <string>kernel-exp-frida_tpro_off</string>
+ <string>kernel-exp-frida_syscall_filter_off</string>
<string>kernel-exp-hv_vmm</string>
<string>dyld-exp-hv_vmm</string>
<string>system-watchdogd-exp-hv_vmm_cache</string>
diff --cc VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swift
index 889d3693,8e447549..17ae062a
--- a/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swift
@@@ -313,28 -310,14 +313,32 @@@ final class VPhoneGuestControl
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) {
+ /// `edge` is the screen edge the touch started at, in `_VZTouch` swipeAim
+ /// encoding (1 top, 2 bottom, 4 right, 8 left, 0 none). A guest with
+ /// `touch_edge` injects such a touch with the digitizer edge flags UIKit's
+ /// screen-edge gestures (home, Control Center) require.
+ func sendTouch(phase: Int, x: Double, y: Double, edge: Int = 0) {
let name =
switch phase {
case 0: "down"
diff --cc VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift
index 91e81a82,efa2f052..9c21f3ed
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift
@@@ -33,7 -33,7 +33,8 @@@ extension VPhoneBootCommand
kernelDebugPort: kernelDebugPort,
isPadGuest: manifest.guestDevice.isPad,
isTVGuest: manifest.guestDevice.family == .appleTV,
+ isHomePodGuest: manifest.guestDevice.family == .homePod,
+ isWatchGuest: manifest.guestDevice.family == .watch,
)
}
}
diff --cc VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
index d6e06063,840e459c..04435062
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
@@@ -48,7 -48,9 +48,10 @@@ class VPhoneVirtualMachine: NSObject, V
/// The guest runs iPadOS: Esc is a key there, not the back gesture.
var isPadGuest = false
var isTVGuest = false
+ var isHomePodGuest = false
+ /// The guest runs watchOS: its side button is a key of its own (consumer
+ /// Help), apart from the crown (Home) and the power key.
+ var isWatchGuest = false
}
private struct DeviceIdentity {
diff --cc VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swift
index 944ffa12,74e642e0..3b65e001
--- a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swift
+++ b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwareCatalog.swift
@@@ -431,16 -462,37 +463,45 @@@ public enum VPhoneFirmwareCatalog
]),
]
+ /// HomePod mini's native IPSW. The boot chain still comes from cloudOS;
+ /// this is a research pairing, not a claim about Siri or Home pairing.
+ static let homePodReleases: [(devices: [String], releases: [(version: String, url: String)])] = [
+ (devices: ["AudioAccessory5,1"], releases: [
+ ("27.0", "https://updates.cdn-apple.com/2026SFallFCS/a595a3b2-2c42-470a-9417-a705aaafa05c/AudioAccessory5,1_27.0_24J361_Restore.ipsw"),
+ ]),
+ ]
+
- /// Full OTAs of devices without an IPSW, oldest first.
- /// Each has a
+ /// Apple Watch releases. The watch boots the research board kernel of the
+ /// cloudOS its kernelcache recipe is for, rebuilt with the watchOS kexts:
+ /// 26.4 (23E244) for watchOS 26.4.
+ static let watchReleases: [(devices: [String], releases: [(version: String, url: String)])] = [
+ (devices: ["Watch7,18"], releases: [
+ ("26.4", "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-09130/486B2E2B-DEDB-4DCF-80F0-7A84ED51B074/Watch7,18_26.4_23T240_Restore.ipsw"),
+ ]),
+ ]
+
+ /// iPhone XS Max releases, each paired with its own release's research board
+ /// cloudOS: the 18.x kernelcache recipes rebuild that iOS 18 kernel with the
+ /// cloudOS 26.1 vphone600 kexts. Kernel-first, so macOS 26.4 and later link
+ /// it over ssh on an older Mac (`VPHONE_KMUTIL_SSH`), and only `minimal` boots it.
+ static let iOS18ResearchBoardReleases: [(version: String, url: String, cloudOS: VPhoneCloudOSOption)] = [
+ ("18.1", "https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-12814/E17284F9-4885-4E16-840A-40DF173142B3/iPhone11,2,iPhone11,4,iPhone11,6_18.1_22B83_Restore.ipsw",
+ .init(name: "cloudOS 18.1 (22B83)", url: "https://updates.cdn-apple.com/private-cloud-compute/729b85b9b89b4383e7dfafdf0f5867b8cd2f3e4e69b279c8785dc7d044e377b7")),
+ ("18.2.1", "https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-56807/7999846C-76E5-42DC-A3F0-96E5FD27FF44/iPhone11,2,iPhone11,4,iPhone11,6_18.2.1_22C161_Restore.ipsw",
+ .init(name: "cloudOS 18.2.1 (22C161)", url: "https://updates.cdn-apple.com/private-cloud-compute/0aadbf7c7e768c73e1f0a6331fbcc96e3792a9f2176509f6225059fbad0bb6b6")),
+ ("18.3.1", "https://updates.cdn-apple.com/2025WinterFCS/fullrestores/072-84318/BE724963-525E-4B8D-8E9F-018395E81BA2/iPhone11,2,iPhone11,4,iPhone11,6_18.3.1_22D72_Restore.ipsw",
+ .init(name: "cloudOS 18.3.1 (22D72)", url: "https://updates.cdn-apple.com/private-cloud-compute/0ce2ff6ad1af4052bbabf38a4627506613ca5c2061e198888391a430357f0b39")),
+ ("18.5", "https://updates.cdn-apple.com/2025SpringFCS/fullrestores/082-45658/0CEE897C-AD56-4422-BD70-FA3CB060E23C/iPhone11,2,iPhone11,4,iPhone11,6_18.5_22F76_Restore.ipsw",
+ .init(name: "cloudOS 18.5 (22F76)", url: "https://updates.cdn-apple.com/private-cloud-compute/ceb5e5bde2427bf7a227b61ff307f79c4b9c701f46023262abd763758aea6453")),
+ ("18.6", "https://updates.cdn-apple.com/2025SummerFCS/fullrestores/082-99059/7A2E93FF-79D9-4AD7-862B-5A4B812ADD90/iPhone11,2,iPhone11,4,iPhone11,6_18.6_22G86_Restore.ipsw",
+ .init(name: "cloudOS 18.6 (22G86)", url: "https://updates.cdn-apple.com/private-cloud-compute/8b2181f68080c42ae57bb8bf516715841060ee3aaf8c0ff06e1cf627169ef574")),
+ ("18.7", "https://updates.cdn-apple.com/2025FallFCS/fullrestores/082-75719/D271E370-84A4-494D-8547-BDBE20AC1EEA/iPhone11,2,iPhone11,4,iPhone11,6_18.7_22H20_Restore.ipsw",
+ .init(name: "cloudOS 18.7 (22H20)", url: "https://updates.cdn-apple.com/private-cloud-compute/9b0acae06a068476c5bf0c1ecdf686cf1ff4ead5a9dcf7429c7d86d01033ef9b")),
+ ("18.7.2", "https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-18690/1C111BF6-B55E-460B-AE63-5343B163CAE4/iPhone11,2,iPhone11,4,iPhone11,6_18.7.2_22H124_Restore.ipsw",
+ .init(name: "cloudOS 18.7.2 (22H43)", url: "https://updates.cdn-apple.com/private-cloud-compute/d425a03c76f1ddb92a65a27d56e80beffe399605018d4d268f5ef8889d0ec9e7")),
+ ]
+
+ /// Full OTAs of devices without an IPSW, oldest first. Each has a
/// `tvReleases` entry of its `baseVersion` for its `restoreBase`. The keys
/// are AppleDB's.
public static let otaReleases: [VPhoneOTARelease] = [
@@@ -490,9 -531,8 +551,9 @@@
/// The URL of the base device's IPSW `release` is restored over.
public static func restoreBaseURL(for release: VPhoneOTARelease) -> String? {
- guard let base = VPhoneGuestDevice.named(release.productType)?.restoreBase else { return nil }
- let releases = (iPhoneReleases + iPadReleases + tvReleases + watchReleases).first { $0.devices.contains(base.productType) }?.releases
+ guard let device = VPhoneGuestDevice.named(release.productType) else { return nil }
+ let base = device.restoreBase ?? device
- let releases = (iPhoneReleases + iPadReleases + tvReleases + homePodReleases).first { $0.devices.contains(base.productType) }?.releases
++ let releases = (iPhoneReleases + iPadReleases + tvReleases + homePodReleases + watchReleases).first { $0.devices.contains(base.productType) }?.releases
return releases?.first { $0.version == release.baseVersion }?.url
}
@@@ -506,24 -547,32 +568,37 @@@
/// gets none.
public static func pairings(for device: String) -> [VPhoneFirmwarePairing] {
guard let guest = VPhoneGuestDevice.named(device) else { return [] }
+ if guest.notchedArtworkSubtype != nil {
+ return iOS18ResearchBoardReleases.map { release in
+ VPhoneFirmwarePairing(
+ device: guest.productType,
+ iosName: "iOS \(release.version)",
+ iosURL: release.url,
+ cloudosName: release.cloudOS.name,
+ cloudosURL: release.cloudOS.url,
+ )
+ }
+ }
guard guest.presentsBoard else { return pairings }
let restored = guest.restoreBase ?? guest
- var releases = (iPhoneReleases + iPadReleases + tvReleases + homePodReleases).first { $0.devices.contains(restored.productType) }?.releases ?? []
- var releases = (iPhoneReleases + iPadReleases + tvReleases + watchReleases).first { $0.devices.contains(restored.productType) }?.releases ?? []
++ var releases = (iPhoneReleases + iPadReleases + tvReleases + homePodReleases + watchReleases).first { $0.devices.contains(restored.productType) }?.releases ?? []
if restored != guest {
releases = otaReleases.filter { $0.productType == guest.productType }.compactMap { ota in
guard let base = releases.first(where: { $0.version == ota.baseVersion }) else { return nil }
return (version: ota.version, url: ota.version == base.version ? base.url : ota.url)
}
+ } else if guest.family == .homePod {
+ releases += otaReleases.filter { $0.productType == guest.productType }.compactMap { ota in
+ guard restoreBaseURL(for: ota) != nil else { return nil }
+ return (version: ota.version, url: ota.url)
+ }
}
return releases.map { release in
- let cloudOS = guest.usesTVOS
- ? VPhoneCloudOSOption(name: "cloudOS 26.4", url: cloud264)
- : recommendedCloudOS(forVersion: release.version)
+ let cloudOS = switch guest.family {
- case .appleTV: VPhoneCloudOSOption(name: "cloudOS 26.4", url: cloud264)
++ case .appleTV, .homePod: VPhoneCloudOSOption(name: "cloudOS 26.4", url: cloud264)
+ case .watch: researchBoardCloudOS(forVersion: release.version) ?? recommendedCloudOS(forVersion: release.version)
+ case .iPhone, .iPad: recommendedCloudOS(forVersion: release.version)
+ }
return VPhoneFirmwarePairing(
device: guest.productType,
iosName: "\(guest.family.osName) \(release.version)",
diff --cc VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwarePicker.swift
index 9b041c16,f5f9ab43..91ff1f54
--- a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwarePicker.swift
+++ b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneFirmwarePicker.swift
@@@ -101,7 -101,7 +101,8 @@@ public enum VPhoneFirmwarePicker
let os = switch VPhoneGuestDevice.named(pairings.first?.device)?.family {
case .iPad: "an iPadOS"
case .appleTV: "a tvOS"
+ case .homePod: "a HomePod"
+ case .watch: "a watchOS"
case .iPhone, nil: "an iPhone"
}
let idx = try choose(
diff --cc VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swift
index 401097b8,7638cccf..5152050b
--- a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swift
+++ b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swift
@@@ -107,9 -107,9 +107,9 @@@ public struct VPhoneResources: Sendabl
vphoned(for: .iPhone)
}
- /// The vphoned a guest of this family runs. Apple TV and HomePod take the same arm64
- /// daemon marked as a tvOS executable: tvOS dyld refuses to load its
- /// system libraries into an iOS-platform process.
- /// The vphoned a guest of this family runs. Apple TV and Apple Watch take
- /// the same arm64 daemon marked as a tvOS or watchOS executable: their
- /// dyld refuses to load its system libraries into an iOS-platform process.
++ /// The vphoned a guest of this family runs. Apple TV and HomePod use
++ /// a tvOS executable, Apple Watch a watchOS executable: their dyld refuses
++ /// to load system libraries into an iOS-platform process.
public func vphoned(for family: VPhoneGuestDevice.Family) -> URL {
let name = Self.vphonedName(for: family)
let bundled = guestResources.appendingPathComponent(name)
@@@ -121,7 -121,11 +121,11 @@@
}
public static func vphonedName(for family: VPhoneGuestDevice.Family) -> String {
- family.usesTVOS ? "vphoned-tvos" : "vphoned"
+ switch family {
- case .appleTV: "vphoned-tvos"
++ case .appleTV, .homePod: "vphoned-tvos"
+ case .watch: "vphoned-watchos"
+ case .iPhone, .iPad: "vphoned"
+ }
}
public var gpuCompilerPlugin: URL {
diff --cc VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestDevice.swift
index 228eb478,f02e9291..1ded1477
--- a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestDevice.swift
+++ b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestDevice.swift
@@@ -19,22 -19,16 +19,24 @@@ public struct VPhoneGuestDevice: Sendab
case iPhone
case iPad
case appleTV
+ case homePod
+ case watch
public var osName: String {
switch self {
case .iPhone: "iOS"
case .iPad: "iPadOS"
case .appleTV: "tvOS"
+ case .homePod: "HomePod Software"
+ case .watch: "watchOS"
}
}
+
+ /// Apple TV and HomePod share the tvOS executable platform and
+ /// filesystem layout. Their user interfaces and device idioms differ.
+ public var usesTVOS: Bool {
+ self == .appleTV || self == .homePod
+ }
}
public let family: Family
@@@ -65,16 -59,21 +67,25 @@@
family == .iPad
}
+ public var usesTVOS: Bool {
+ family.usesTVOS
+ }
+
/// Whether the guest boots a device tree of its own that presents this
/// board, built by `fw patch` from the board's tree in the IPSW. Every
- /// device but the iPhone17,3 does; that one keeps the fixed D47 identity
- /// `cfw install` writes into the restored tree.
+ /// device but the iPhone17,3 and the iPhone XS Max does; those keep the
+ /// fixed D47 identity `cfw install` writes into the restored tree.
public var presentsBoard: Bool {
- productType != Self.iPhone17_3.productType
+ productType != Self.iPhone17_3.productType && notchedArtworkSubtype == nil
+ }
+
+ /// The artwork subtype of a guest presented as the iPhone17,3 whose own
+ /// userland has none of the iPhone 16's: the XS family's asset catalogs
+ /// only carry 2436 and 2688 artwork, and its SpringBoard no Dynamic Island
+ /// layout. Without it Hello and the wallpaper stay empty and the home
+ /// gesture breaks. Nil for every other device.
+ public var notchedArtworkSubtype: Int? {
+ productType == "iPhone11,6" ? 2688 : nil
}
// MARK: - Known Devices
@@@ -183,20 -199,20 +211,32 @@@
screen: .init(width: 3840, height: 2160, pixelsPerInch: 144, scale: 2.0),
)
+ /// HomePod mini (B520AP). It has no physical display; this small virtual
+ /// canvas satisfies the VM graphics configuration and is not a panel
+ /// specification or a promise of a graphical HomePod interface.
+ public static let audioAccessory5_1 = VPhoneGuestDevice(
+ family: .homePod,
+ productType: "AudioAccessory5,1",
+ deviceClass: "b520ap",
+ productName: "HomePod mini",
+ screen: .init(width: 320, height: 320, pixelsPerInch: 72, scale: 1.0),
+ )
+
+ /// Apple Watch Series 11 (GPS), 46 mm: 416x496 at 330 ppi, 208x248 points.
+ /// The research board's kernel boots it with the watchOS kexts of its IPSW
+ /// (the `watch` kernelcache recipe); N227b's device tree supplies the watch
+ /// idiom and 2x identity.
+ public static let watch7_18 = VPhoneGuestDevice(
+ family: .watch,
+ productType: "Watch7,18",
+ deviceClass: "n227bap",
+ productName: "Apple Watch Series 11 (GPS)",
+ screen: .init(width: 416, height: 496, pixelsPerInch: 330, scale: 2.0),
+ )
+
/// Whether the guest's userland is plain arm64 rather than arm64e: only
- /// the Apple TV HD's. It has no paravirtual GPU driver to load, and its
+ /// the Apple TV HD's. HomePod mini 27.0 ships arm64e dyld and launchd.
+ /// The Apple TV HD has no paravirtual GPU driver to load, and its
/// dyld needs the TV TPRO patches.
public var hasPlainArm64Userland: Bool {
self == .appleTV5_3
@@@ -221,7 -238,7 +262,8 @@@
iPad16_3, iPad16_5,
iPad17_1, iPad17_3,
appleTV5_3, appleTV14_1,
+ audioAccessory5_1,
+ watch7_18,
]
/// Cellular models that ship in the same IPSW as a known Wi-Fi model and map
@@@ -256,7 -274,7 +299,7 @@@
public func restoreTreeName(version: String, build: String) -> String {
switch family {
case .iPhone: "\(productType)_\(version)_\(build)_Restore"
- case .iPad, .appleTV, .homePod: "iPhoneOS_\(productType)_\(version)_\(build)_Restore"
- case .iPad, .appleTV, .watch: "iPhoneOS_\(productType)_\(version)_\(build)_Restore"
++ case .iPad, .appleTV, .homePod, .watch: "iPhoneOS_\(productType)_\(version)_\(build)_Restore"
}
}
diff --cc VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift
index a28369e8,4a2603f3..2889bcf2
--- a/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift
@@@ -598,11 -596,16 +598,16 @@@ struct VPhoneLaunchpadControlCommands
defaultPreset: VPhoneLaunchpadPatchSelection.defaultPreset(forDevice: device),
emit: emit,
)
- let usesTemplate = !request.flag("no-template") && !requiresStandaloneRestore
+ // The Minimal preset seals the system it restores, which a template's
+ // trim and setup boot would write.
+ let restoredSystem = patches.customisesRestoredSystem
- let usesTemplate = !request.flag("no-template") && !isAppleTV && !restoredSystem
++ let usesTemplate = !request.flag("no-template") && !requiresStandaloneRestore && !restoredSystem
let slimming: VPhoneLaunchpadSlimming
- if requiresStandaloneRestore {
- if isAppleTV || restoredSystem {
++ if requiresStandaloneRestore || restoredSystem {
if !Self.slimmingSwitches(request).isEmpty {
- throw VPhoneLaunchpadError("Apple TV and HomePod are created without a template; the slimming switches do not apply.")
- throw VPhoneLaunchpadError(isAppleTV
- ? "An Apple TV is created without a template; the slimming switches do not apply."
++ throw VPhoneLaunchpadError(requiresStandaloneRestore
++ ? "Apple TV and HomePod are created without a template; the slimming switches do not apply."
+ : "The \(patches.preset) preset creates a machine without a template; the slimming switches do not apply.")
}
var off = VPhoneLaunchpadSlimming()
off.slim = false
diff --cc VPhoneLaunchpad/VPhoneLaunchpad/IPSWCache/VPhoneLaunchpadIPSW.swift
index 811d09fe,f6c15a4d..cc1e59bb
--- a/VPhoneLaunchpad/VPhoneLaunchpad/IPSWCache/VPhoneLaunchpadIPSW.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpad/IPSWCache/VPhoneLaunchpadIPSW.swift
@@@ -9,7 -9,7 +9,7 @@@ import Foundatio
/// manifest cannot be read.
nonisolated struct VPhoneLaunchpadIPSW: Hashable, Sendable {
enum Kind: Hashable, Sendable {
- case iPhone, iPad, appleTV, homePod, cloudOS, unknown
- case iPhone, iPad, appleTV, watch, cloudOS, unknown
++ case iPhone, iPad, appleTV, homePod, watch, cloudOS, unknown
/// The system the IPSW installs: the first word of its title.
var systemName: String? {
@@@ -17,7 -17,7 +17,8 @@@
case .iPhone: "iOS"
case .iPad: "iPadOS"
case .appleTV: "tvOS"
+ case .homePod: "HomePod Software"
+ case .watch: "watchOS"
case .cloudOS: "cloudOS"
case .unknown: nil
}
@@@ -51,9 -51,9 +52,12 @@@
if productTypes.contains(where: { $0.hasPrefix("AppleTV") }) {
return .appleTV
}
+ if productTypes.contains(where: { $0.hasPrefix("AudioAccessory") }) {
+ return .homePod
+ }
+ if productTypes.contains(where: { $0.hasPrefix("Watch") }) {
+ return .watch
+ }
return .unknown
}
diff --cc VPhoneLaunchpad/VPhoneLaunchpad/IPSWCache/VPhoneLaunchpadIPSWRows.swift
index bc1de45a,6a76a249..b46150e9
--- a/VPhoneLaunchpad/VPhoneLaunchpad/IPSWCache/VPhoneLaunchpadIPSWRows.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpad/IPSWCache/VPhoneLaunchpadIPSWRows.swift
@@@ -137,9 -137,9 +137,10 @@@ nonisolated enum VPhoneLaunchpadIPSWRow
case .iPhone: 0
case .iPad: 1
case .appleTV: 2
- case .watch: 3
- case .cloudOS: 4
- case .unknown: 5
+ case .homePod: 3
- case .cloudOS: 4
- case .unknown: 5
++ case .watch: 4
++ case .cloudOS: 5
++ case .unknown: 6
}
}
@@@ -160,7 -160,7 +161,8 @@@
case .iPhone: String(localized: "iPhone")
case .iPad: String(localized: "iPad")
case .appleTV: String(localized: "Apple TV")
+ case .homePod: String(localized: "HomePod")
+ case .watch: String(localized: "Apple Watch")
case .cloudOS: String(localized: "cloudOS")
case .unknown: String(localized: "Unknown")
}
diff --cc VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadMachine.swift
index 10e9fbe0,fe018707..c25997ef
--- a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadMachine.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadMachine.swift
@@@ -150,13 -152,15 +152,17 @@@ nonisolated struct VPhoneLaunchpadMachi
guestProductType?.hasPrefix("AppleTV") == true
}
- /// True for an Apple Watch guest.
+ var isHomePod: Bool {
+ guestProductType?.hasPrefix("AudioAccessory") == true
+ }
+
- /// The guest OS's name.
+ var isWatch: Bool {
+ guestProductType?.hasPrefix("Watch") == true
+ }
+
- /// The guest OS's name: iPadOS on an iPad, tvOS on an Apple TV, watchOS
- /// on an Apple Watch.
++ /// The guest OS name, including accessory and watch guests.
var osName: String {
- isHomePod ? "HomePod Software" : isAppleTV ? "tvOS" : isPad ? "iPadOS" : "iOS"
- isWatch ? "watchOS" : isAppleTV ? "tvOS" : isPad ? "iPadOS" : "iOS"
++ isHomePod ? "HomePod Software" : isWatch ? "watchOS" : isAppleTV ? "tvOS" : isPad ? "iPadOS" : "iOS"
}
/// config.plist's `guestProductType`, else the product type in the name
@@@ -172,7 -177,7 +179,7 @@@
let originals = folder.appendingPathComponent("FirmwareOriginals", isDirectory: true)
let names = (try? FileManager.default.contentsOfDirectory(atPath: originals.path)) ?? []
for name in names.sorted() where name.hasSuffix("_Restore") {
- if let type = name.split(separator: "_").first(where: { $0.wholeMatch(of: /(iPhone|iPad|AppleTV|AudioAccessory)\d+,\d+/) != nil }) {
- if let type = name.split(separator: "_").first(where: { $0.wholeMatch(of: /(iPhone|iPad|AppleTV|Watch)\d+,\d+/) != nil }) {
++ if let type = name.split(separator: "_").first(where: { $0.wholeMatch(of: /(iPhone|iPad|AppleTV|AudioAccessory|Watch)\d+,\d+/) != nil }) {
return String(type)
}
}
@@@ -262,9 -270,12 +272,12 @@@ nonisolated struct VPhoneLaunchpadFirmw
/// The product type `fw prepare --device` takes.
let productType: String
let name: String
- /// `iPhone`, `iPad`, `appleTV` or `homePod`.
- /// `iPhone`, `iPad`, `appleTV` or `watch`.
++ /// The guest family identifier, including homePod and watch.
let family: String
let pairings: [Pairing]
+ /// `kernel-first` for a device whose kernelcache mix only the kmutil
+ /// of macOS 15 or 26.0 to 26.3 links, from a bundle that has one.
+ var kernelcacheLayout: String?
var id: String {
productType
@@@ -278,18 -296,13 +298,22 @@@
family == "appleTV"
}
+ var isWatch: Bool {
+ family == "watch"
+ }
+
+ var isHomePod: Bool {
+ family == "homePod"
+ }
+
+ /// HomePod and Apple TV do not use iOS templates or slimming.
+ var requiresStandaloneRestore: Bool {
+ isAppleTV || isHomePod
+ }
+
/// The system its IPSWs install.
var osName: String {
- isHomePod ? "HomePod Software" : isAppleTV ? "tvOS" : isPad ? "iPadOS" : "iOS"
- isWatch ? "watchOS" : isAppleTV ? "tvOS" : isPad ? "iPadOS" : "iOS"
++ isHomePod ? "HomePod Software" : isWatch ? "watchOS" : isAppleTV ? "tvOS" : isPad ? "iPadOS" : "iOS"
}
/// The name with its product type, `iPhone 16 (iPhone17,3)`: Launchpad
diff --cc VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadNewMachineView.swift
index 95a4aac8,d857de07..80e3e477
--- a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadNewMachineView.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadNewMachineView.swift
@@@ -33,9 -33,18 +33,20 @@@ struct VPhoneLaunchpadNewMachineView: V
@State private var pairing: String?
@State private var usesCustomSources = false
@State private var iphoneSource = ""
+ @State private var customGuestProductType: String?
+ @State private var inspectedCustomSource: String?
@State private var cloudOSSource = ""
+ /// Run the release on its own cloudOS, where the research board stands in
+ /// for vphone600 and the kernelcache is mixed (`fw kernelcache`).
+ @State private var usesOwnCloudOS = false
+ /// The ipsw that stages a mix; vphone-cli does not ship one.
+ @AppStorage("KernelcacheIPSW") private var kernelcacheIPSW = ""
+ /// The Mac that links an iOS 18 guest's kernel-first mix over ssh
+ /// (`user@host`), kept like the ipsw.
+ @AppStorage("KernelcacheBuilder") private var kernelcacheBuilderDestination = ""
+ /// Its password, for ssh and sudo there. Kept only while the sheet is
+ /// open, and by the creation that runs with it.
+ @State private var kernelcacheBuilderPassword = ""
@State private var cpu = Self.defaultCPU
@State private var memoryMB = Self.defaultMemoryMB
@State private var diskSizeGB = Self.defaultDiskSizeGB
@@@ -170,7 -226,7 +228,8 @@@
private var canCreate: Bool {
nameProblem == nil && advancedProblem == nil && sources != nil && bundleVersion != nil
+ && (!usesCustomSources || inspectedCustomSource == iphoneSource)
+ && (!rebuildsKernelcache || hasKernelcacheIPSW) && kernelcacheBuilderProblem == nil
}
var body: some View {
@@@ -215,10 -257,21 +274,21 @@@
// Off when there is no template to clone; it can still be turned on
// to build one.
.onChange(of: templateAvailable, initial: true) {
- if let templateAvailable, !requiresStandaloneRestore {
- if let templateAvailable, !isAppleTVGuest, !patches.customisesRestoredSystem {
++ if let templateAvailable, !requiresStandaloneRestore, !patches.customisesRestoredSystem {
usesTemplate = templateAvailable
}
}
+ // The Minimal preset is restored on its own and not slimmed.
+ .onChange(of: patches.customisesRestoredSystem) { _, restored in
- guard !isAppleTVGuest else { return }
++ guard !requiresStandaloneRestore else { return }
+ if restored {
+ usesTemplate = false
+ slimming.slim = false
+ } else {
+ usesTemplate = templateAvailable ?? true
+ slimming = VPhoneLaunchpadSlimming()
+ }
+ }
.onAppear {
if let version = bundleVersion, let known = Self.catalogs[version] {
apply(known)
@@@ -257,9 -310,9 +327,9 @@@
hardwarePage
advancedSections(.hardware)
case .template:
- VPhoneLaunchpadSlimmingSections(part: .template, usesTemplate: $usesTemplate, templateAvailable: templateAvailable, slimming: $slimming, requiresStandaloneRestore: requiresStandaloneRestore)
- VPhoneLaunchpadSlimmingSections(part: .template, usesTemplate: $usesTemplate, templateAvailable: templateAvailable, slimming: $slimming, forAppleTV: isAppleTVGuest, forRestoredSystem: patches.customisesRestoredSystem)
++ VPhoneLaunchpadSlimmingSections(part: .template, usesTemplate: $usesTemplate, templateAvailable: templateAvailable, slimming: $slimming, requiresStandaloneRestore: requiresStandaloneRestore, forRestoredSystem: patches.customisesRestoredSystem)
case .slimming:
- VPhoneLaunchpadSlimmingSections(part: .slimming, usesTemplate: $usesTemplate, templateAvailable: templateAvailable, slimming: $slimming, requiresStandaloneRestore: requiresStandaloneRestore)
- VPhoneLaunchpadSlimmingSections(part: .slimming, usesTemplate: $usesTemplate, templateAvailable: templateAvailable, slimming: $slimming, forAppleTV: isAppleTVGuest, forRestoredSystem: patches.customisesRestoredSystem)
++ VPhoneLaunchpadSlimmingSections(part: .slimming, usesTemplate: $usesTemplate, templateAvailable: templateAvailable, slimming: $slimming, requiresStandaloneRestore: requiresStandaloneRestore, forRestoredSystem: patches.customisesRestoredSystem)
case .firmware:
bundleSection
firmwareSourceSection
@@@ -395,8 -448,27 +465,27 @@@
.lineLimit(1)
.truncationMode(.middle)
} else {
- Text("Choose an iPhone IPSW and a cloudOS IPSW in Advanced Options.").foregroundStyle(.red)
+ Text("Choose a guest IPSW and a cloudOS IPSW in Advanced Options.").foregroundStyle(.red)
}
+ } else if let own = ownCloudOS {
+ Text(hasKernelcacheIPSW
+ ? "On its own cloudOS, \(own.name): the kernelcache is rebuilt, which asks for administrator access once."
+ : "Choose an ipsw with `kernel extract --kdk` in Advanced Options to run on \(own.name).")
+ .foregroundStyle(hasKernelcacheIPSW ? Color.secondary : Color.red)
+ } else if linksKernelFirst, let cloudOS = selectedPairing?.recommendedCloudOS.name {
+ if !hasKernelcacheIPSW {
+ Text("Choose an ipsw with `kernel extract --kdk` in Advanced Options: the release's own kernel is rebuilt with the vphone600 kexts.").foregroundStyle(.red)
+ } else if let kernelcacheBuilderProblem {
+ Text(kernelcacheBuilderProblem).foregroundStyle(.red)
+ } else {
+ Text("With \(cloudOS): the kernelcache is rebuilt and linked \(kernelcacheBuilder.map { "on \($0.destination)" } ?? "on this Mac"), and the restore image asks for administrator access once.")
+ .foregroundStyle(.secondary)
+ }
+ } else if rebuildsKernelcache, let cloudOS = selectedPairing?.recommendedCloudOS.name {
+ Text(hasKernelcacheIPSW
+ ? "With \(cloudOS): the kernelcache is rebuilt with the watch's kexts, which asks for administrator access once."
+ : "Choose an ipsw with `kernel extract --kdk` in Advanced Options: the watch's kernelcache is rebuilt with its kexts.")
+ .foregroundStyle(hasKernelcacheIPSW ? Color.secondary : Color.red)
} else if let selectedGuest, let cloudOS = selectedPairing?.recommendedCloudOS.name {
Text("Recommended firmware pairings for \(selectedGuest.detailedName), with \(cloudOS).")
.foregroundStyle(.secondary)
@@@ -568,10 -640,26 +657,26 @@@
Toggle("Use Specified Firmware", isOn: $usesCustomSources)
if usesCustomSources {
- sourceField("iPhone IPSW", $iphoneSource)
+ sourceField("Guest IPSW", $iphoneSource)
sourceField("cloudOS IPSW", $cloudOSSource)
+ } else if let pairing = selectedPairing, let own = pairing.matchingCloudOS {
+ Picker("cloudOS", selection: $usesOwnCloudOS) {
+ Text(verbatim: pairing.recommendedCloudOS.name).tag(false)
+ Text(verbatim: own.name).tag(true)
+ }
+ if usesOwnCloudOS {
+ sourceField("ipsw", $kernelcacheIPSW)
+ }
} else {
LabeledContent("cloudOS", value: selectedPairing?.recommendedCloudOS.name ?? "—")
+ if rebuildsKernelcache {
+ sourceField("ipsw", $kernelcacheIPSW)
+ }
+ if linksKernelFirst {
+ TextField("macOS builder", text: $kernelcacheBuilderDestination, prompt: Text("user@host"))
+ SecureField("Password", text: $kernelcacheBuilderPassword, prompt: Text("None with ssh keys"))
+ .disabled(kernelcacheBuilder == nil)
+ }
}
} header: {
Text("Firmware")
@@@ -708,36 -802,36 +819,39 @@@
/// Select a guest device and its newest release.
private func choose(_ productType: String?) {
- let hadOwnPreset = hasOwnPresetGuest
- let wasGuest = guest
+ let previous = guestProductType
guest = productType
pairing = selectedGuest?.defaultPairing?.id
- // Each Apple TV and Apple Watch starts from a preset of its own.
- guard hasOwnPresetGuest != hadOwnPreset || hasOwnPresetGuest && wasGuest != productType else { return }
- // An Apple TV or Apple Watch guest is restored on its own with a
- // preset of its own: templates and slimming drive iOS Setup Assistant
- // and its apps.
- patches = VPhoneLaunchpadPatchSelection()
- if hasOwnPresetGuest {
- patches.preset = VPhoneLaunchpadPatchSelection.defaultPreset(forDevice: productType)
- usesTemplate = false
- slimming.slim = false
- } else {
- usesTemplate = templateAvailable ?? true
- slimming = VPhoneLaunchpadSlimming()
- }
- Task { await loadPatchCatalog() }
+ applyGuestDefaults(previousProductType: previous)
}
- /// An Apple TV from the catalog, which is built without a template.
- private var isAppleTVGuest: Bool {
- !usesCustomSources && selectedGuest?.isAppleTV == true
+ /// Custom IPSWs carry the guest identity in their manifest or file name.
+ private var guestProductType: String? {
+ usesCustomSources ? customGuestProductType : selectedGuest?.productType
}
- /// An Apple TV, Apple Watch or iOS 18 guest from the catalog: each has a
- /// preset of its own.
- private var hasOwnPresetGuest: Bool {
- !usesCustomSources && (selectedGuest?.isAppleTV == true || selectedGuest?.isWatch == true || linksKernelFirst)
+ /// Apple TV and HomePod are restored without iOS templates or slimming.
+ private var requiresStandaloneRestore: Bool {
+ guestProductType?.hasPrefix("AppleTV") == true || guestProductType?.hasPrefix("AudioAccessory") == true
+ }
+
+ private func applyGuestDefaults(previousProductType: String?) {
- let wasStandalone = previousProductType?.hasPrefix("AppleTV") == true || previousProductType?.hasPrefix("AudioAccessory") == true
++ let previousPreset = VPhoneLaunchpadPatchSelection.defaultPreset(forDevice: previousProductType)
++ let nextPreset = VPhoneLaunchpadPatchSelection.defaultPreset(forDevice: guestProductType)
++ let hadOwnPreset = previousPreset != VPhoneLaunchpadPatchSelection.defaultPreset
++ let hasOwnPreset = nextPreset != VPhoneLaunchpadPatchSelection.defaultPreset
+ // Preserve custom iPhone/iPad patch and template settings when
+ // switching between guests that share the iOS creation workflow.
- guard wasStandalone != requiresStandaloneRestore
- || requiresStandaloneRestore && previousProductType != guestProductType else { return }
++ guard hadOwnPreset != hasOwnPreset
++ || hasOwnPreset && previousProductType != guestProductType else { return }
+ patches = VPhoneLaunchpadPatchSelection()
+ patches.preset = VPhoneLaunchpadPatchSelection.defaultPreset(forDevice: guestProductType)
- usesTemplate = requiresStandaloneRestore ? false : templateAvailable ?? true
++ usesTemplate = hasOwnPreset ? false : templateAvailable ?? true
+ slimming = VPhoneLaunchpadSlimming()
- if requiresStandaloneRestore {
++ if hasOwnPreset {
+ slimming.slim = false
+ }
+ Task { await loadPatchCatalog() }
}
/// Read again whenever the preset or the version changes: `inPreset`, which
diff --cc VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchCatalog.swift
index bd7bfc5b,add04f9b..b401e979
--- a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchCatalog.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadPatchCatalog.swift
@@@ -283,16 -283,22 +283,26 @@@ nonisolated struct VPhoneLaunchpadPatch
/// `VPhonePatchPreset.tvOS4KIdentifier`: its arm64e userland comes from
/// the OTA, with the paravirtual GPU driver.
static let tvOS4KPreset = "tvos-4k"
+ /// The preset that customises the system before the restore and patches
+ /// no boot chain: `fw patch` runs as root, and nothing writes the system
+ /// afterwards, so there is no template and no slimming.
+ static let minimalPreset = "minimal"
+ /// The preset an Apple Watch guest gets, mirroring
+ /// `VPhonePatchPreset.watchOSIdentifier`: `minimal` for the watch board.
+ static let watchOSPreset = "watchos"
+ /// The HomePod mini's arm64e userland has a preset of its own.
+ static let homePodMiniPreset = "homepod-mini"
+
/// The preset a new machine of `productType` starts from.
static func defaultPreset(forDevice productType: String?) -> String {
switch productType {
+ case "AudioAccessory5,1": homePodMiniPreset
case "AppleTV14,1": tvOS4KPreset
case let type? where type.hasPrefix("AppleTV"): tvOSPreset
+ case let type? where type.hasPrefix("Watch"): watchOSPreset
+ // The iOS 18 research board kernels boot no other preset.
+ case "iPhone11,6", "iPhone11,4": minimalPreset
default: defaultPreset
}
}
diff --cc VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadSlimmingView.swift
index e9fc61f1,5f4bd66d..0ec55192
--- a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadSlimmingView.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadSlimmingView.swift
@@@ -15,9 -15,12 +15,12 @@@ struct VPhoneLaunchpadSlimmingSections
/// IPSWs, which the list cannot be matched against.
var templateAvailable: Bool?
@Binding var slimming: VPhoneLaunchpadSlimming
- /// An Apple TV is restored on its own and not slimmed: templates and
+ /// Apple TV and HomePod are restored on their own and not slimmed: templates and
/// slimming drive iOS Setup Assistant and its apps.
- var forAppleTV = false
+ var requiresStandaloneRestore = false
+ /// The `minimal` preset seals the system it restores, which the trim and
+ /// setup boot of a template would write.
+ var forRestoredSystem = false
@State private var choosesApps = false
var body: some View {
@@@ -27,11 -30,14 +30,14 @@@
case .slimming:
Section {
Toggle("Slim System", isOn: $slimming.slim)
- .disabled(requiresStandaloneRestore)
- .disabled(forAppleTV || forRestoredSystem)
++ .disabled(requiresStandaloneRestore || forRestoredSystem)
} footer: {
- if forAppleTV {
- Text("An Apple TV keeps every file, service and app.")
+ if requiresStandaloneRestore {
+ Text("Apple TV and HomePod keep every file, service and app.")
.foregroundStyle(.secondary)
+ } else if forRestoredSystem {
+ Text("The Minimal preset keeps the restored system exactly as sealed.")
+ .foregroundStyle(.secondary)
} else if !usesTemplate, slimming.slim {
Text("Without a template the machine is slimmed on its own, with a setup boot of its own. Setup Assistant is skipped.")
.foregroundStyle(.secondary)
@@@ -45,13 -51,15 +51,15 @@@
private var templateSection: some View {
Section {
Toggle("Use Template", isOn: $usesTemplate)
- .disabled(requiresStandaloneRestore)
- .disabled(forAppleTV || forRestoredSystem)
++ .disabled(requiresStandaloneRestore || forRestoredSystem)
} header: {
Text("Template")
} footer: {
VStack(alignment: .leading, spacing: 4) {
- if forAppleTV {
- Text("An Apple TV is restored on its own, with keys of its own. Templates are made for iPhone and iPad.")
+ if requiresStandaloneRestore {
+ Text("Apple TV and HomePod are restored on their own, with keys of their own. Templates are made for iPhone and iPad.")
+ } else if forRestoredSystem {
+ Text("The Minimal preset restores the machine on its own, with keys of its own: building a template writes the system it seals.")
} else {
if templateAvailable == false {
Text("No template is available for this firmware. Turning this on saves a sample of the machine in the template library.")
@@@ -92,7 -100,7 +100,7 @@@
}
}
}
- .disabled(requiresStandaloneRestore || !slimming.slim)
- .disabled(!slimming.slim)
++ .disabled(requiresStandaloneRestore || forRestoredSystem || !slimming.slim)
}
private var trimNote: String {
@@@ -139,7 -151,7 +151,7 @@@
}
.foregroundStyle(.secondary)
}
- .disabled(requiresStandaloneRestore || !slimming.slim)
- .disabled(!slimming.slim)
++ .disabled(requiresStandaloneRestore || forRestoredSystem || !slimming.slim)
}
private var appsPopover: some View {