Run a virtual iPhone on an Apple Silicon Mac.
Swift
Document Apple TV guests on tvOS 26.6 and the 4K OTA build
Jackycc80a2164425
diff --git a/Documents/Guides/launchpad-cli.md b/Documents/Guides/launchpad-cli.mdindex 99ad4d54..125e3269 100644--- a/Documents/Guides/launchpad-cli.md+++ b/Documents/Guides/launchpad-cli.md@@ -113,7 +113,7 @@ version while a machine is bound to it; rebind or delete those machines first.| `vm list` | Machines in every library with run state, Core Bundle and log path. Only a VM process holding the disk (`vphone-vm`, or Virtualization's VM service) makes a machine `running`; any other process that has it open (`tail`, Spotlight, a backup tool) is listed in `diskOpenIn` (`12925 tail`) and leaves it `stopped` || `vm start <name> [--headless] [--wait]` / `vm stop <name>` | Launch with the machine's bundle, or stop; `--wait` waits for vphoned. Stop asks the guest to shut down (vphoned `system.shutdown`) and waits up to 30 s; when the guest cannot be asked or does not stop, it ends the virtual machine as before. Like `vphone-cli vm launch`, start is not refused by a process that only has the disk open; it prints a note naming it || `vm wait <name>` / `vm log <name> [--kind create\|dfu\|patch]` | Wait for vphoned; read a console log |-| `vm create <name> [--bundle <version>] [...] [--device <product-type>] [--preset <preset>] [--block <patch>]... [--allow <patch>]... [--no-template \| --slim on\|off --trim … --keep-languages … --service-profile … --remove-apps … --keep-apps … --accounts-off] [--from <step>]` | The New Machine pipeline, bound to `--bundle` or the default: cloned from a template, built first when missing (2.9), or restored on its own with `--no-template`; the slimming switches are `vphone-cli vm create`'s, except that Apple Account goes with the trimmed service profile as in New Machine (`--accounts-off` is accepted and changes nothing). `--block`/`--allow` (repeatable) turn one patch of the preset off or on, as New Machine's patch list and `vphone-cli fw set-patches` do (see below). `--device` makes an iPad guest, `--from` retries from a step (`findTemplate` … `firstBoot`) with the options the creation started with; the result names the template, whether this creation built it, and the patches it used |+| `vm create <name> [--bundle <version>] [...] [--device <product-type>] [--preset <preset>] [--block <patch>]... [--allow <patch>]... [--no-template \| --slim on\|off --trim … --keep-languages … --service-profile … --remove-apps … --keep-apps … --accounts-off] [--from <step>]` | The New Machine pipeline, bound to `--bundle` or the default: cloned from a template, built first when missing (2.9), or restored on its own with `--no-template`; the slimming switches are `vphone-cli vm create`'s, except that Apple Account goes with the trimmed service profile as in New Machine (`--accounts-off` is accepted and changes nothing). `--block`/`--allow` (repeatable) turn one patch of the preset off or on, as New Machine's patch list and `vphone-cli fw set-patches` do (see below). `--device` makes an iPad guest, or with `AppleTV5,3` an Apple TV HD guest, which is always restored on its own without slimming and takes the `tvos` preset unless `--preset` names another, and with `AppleTV14,1` an Apple TV 4K guest, the same with the `tvos-4k` preset and its userland from the catalog's OTA; `--from` retries from a step (`findTemplate` … `firstBoot`) with the options the creation started with; the result names the template, whether this creation built it, and the patches it used || `vm set-bundle <name> <version> [--update-environment]` | Bind a machine to another installed version. `--update-environment` also redeploys that version's guest environment and needs a stopped machine; a disk another process has open refuses it, naming that process, before the binding changes. If the update itself fails, the machine stays bound to the new version and `vm list` still shows the old `guestEnvironmentBundle`: run `cfw update-environment` to finish || `vm leases [--release]` | DHCP leases on the shared NAT network and the machine that owns each. `--release` frees the ones no machine in any library uses, through the helper (see [Networking](networking.md#addresses-held-by-old-macs)) || `cfw install <name>` | Install CFW into a stopped machine with its own bundle, through the helper. The helper puts temporary work files on the VM library's external volume when applicable. It and the two updates below refuse a disk another process has open, naming it (`12925 tail`). |diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.mdindex 0f3843ed..8c73615c 100644--- a/Research/0_binary_patch_comparison.md+++ b/Research/0_binary_patch_comparison.md@@ -17,6 +17,34 @@> errors abort the install before disk replacement; rollback retires the undo> record only after cache re-attestation and standalone restoration succeed.> Details and evidence: [tvOS support](Firmware/tvos_support.md).+>+> **tvOS follow-up (2026-10-15).** Apple TV guests run vphoned. tvOS dyld+> refused the iOS-platform daemon (`wrong platform to load into process`), so the+> bundle also ships `vphoned-tvos`, the same arm64 binary with `LC_BUILD_VERSION`+> platform tvOS, chosen by guest family at install and launch.+> `system-vphoned-boot-install` and `system-launchd_cache_loader-boot-unsecure_cache_gate`+> are admitted for TV; the cache-gate patcher NOPs the same branch in the+> plain-arm64 loader unchanged. `system-dyld-exp-tv_tpro` and+> `kernel-exp-tv_tpro_pagers` now apply to every tvOS 26 userland on cloudOS 26.4+> rather than 26.4 alone: the tunable is the cloudOS kernel's, and tvOS 26.6+> (23L773) needed and booted with both. The new `tvos` preset is Standard with+> both on and the iOS display, camera, audio, sensor, GPU and shared-cache+> patches off. vphoned's consumer `0x0C/0x40` is the TV button (press type+> 17): Home on a press, Control Center when held.+>+> **Apple TV 4K (2026-10-15).** New research patch+> `system-tv-exp-ota_userland` (manual-only; on only in the `tvos-4k` preset) empties+> the restored System volume and `aa extract`s the AppleTV14,1 OTA's+> `payloadv2` chunks staged in `<vm>/OTAUserland`, over an Apple TV HD 26.6+> restore with the J255 identity. On an arm64e TV guest the installer also admits+> `system-extensions-boot-gpu_bundle` and rewrites the paravirtual GPU driver's+> and compiler plugin's `LC_BUILD_VERSION` to tvOS (`MachOBuildPlatform`) before+> re-signing; the guest then renders through the paravirtual GPU at 2160p.+> `fw prepare --device AppleTV14,1` stages the OTA natively (system+> AppleArchive: AEA decryption, segmented archive) and the `tvos-4k` preset is+> `tvos` with the GPU bundle and the userland swap on and both TV TPRO patches+> off. See+> [tvOS support](Firmware/tvos_support.md#apple-tv-4k-from-its-ota).> **iOS 27 disabled services (2026-10-13):**> `system-jetsamproperties-cfw-disable_allowed` removes everydiff --git a/Research/Firmware/tvos_support.md b/Research/Firmware/tvos_support.mdindex edfc94dd..a8621f74 100644--- a/Research/Firmware/tvos_support.md+++ b/Research/Firmware/tvos_support.md@@ -12,7 +12,20 @@ About reports tvOS 26.4 (23L5208m), an IPv4 address, and 1080p HD / 120 Hz.The display mode is reported metadata, not measured rendering performance.Activation reports Failed and the model is Not Applicable. Apple services,audio, video playback, third-party apps and long-term stability remain untested.-No tvOS pairing is advertised in the firmware catalog.++Later the same day: tvOS 26.6 (23L773), the last release for the Apple TV HD,+restored on the same cloudOS and booted to TVSetup with vphoned running. The+guests now run vphoned (see [vphoned on tvOS](#vphoned-on-tvos)), which gives+the TV button: Home on a press, Control Center when held. The firmware catalog+lists tvOS 26.6 for the Apple TV HD, and New Machine and `vm create --device+AppleTV5,3` build it with the `tvos` preset.++tvOS 27 dropped the Apple TV HD, and Apple publishes no IPSW for any Apple TV+4K: AppleDB lists only OTA packages for AppleTV11,1 and AppleTV14,1, and+AppleTV18,1 is not released. An Apple TV 4K (AppleTV14,1) guest is the HD's+26.6 restore with the 4K's identity and arm64e userland taken from its OTA;+`fw prepare` reads the OTA itself. See+[Apple TV 4K from its OTA](#apple-tv-4k-from-its-ota).## Firmware and storage@@ -21,26 +34,49 @@ No tvOS pairing is advertised in the firmware catalog.- [Apple-hosted donor IPSW](https://updates.cdn-apple.com/2026WinterSeed/fullrestores/089-95491/1679DEB6-820D-40A8-9F28-1735EFDFB01D/AppleTV5,3_26.4_23L5208m_Restore.ipsw).- Verified SHA-256: `2128c348ffbb0f65096ac3e7be22e901e09773e02c17edbce4c0647769c24ae8`;length 5,269,316,627 bytes.+- [tvOS 26.6 IPSW](https://updates.cdn-apple.com/2026SummerFCS/fullrestores/140-67287/F525C1FF-B49B-40AB-A5F4-A6F4A4847407/AppleTV5,3_26.6_23L773_Restore.ipsw),+ the catalog's pairing. SHA-256+ `a5f3e397ba4d8cd03c6c46709b3d8f9811af58a5a2e758e2334317fbc68db292`, as AppleDB+ records it; length 5,269,471,026 bytes.- The lab reuses one logical 32 GB disk, about 11 GiB allocated. No secondVM, template, or automatic PCC GPU recovery disk was created.The matching release numbers motivated the pairing investigation; they do not establish-compatibility with other builds. The beta archive, FirmwareOriginals and+compatibility with other builds. Every TV pairing uses cloudOS 26.4: the kernel+fix below exists only for its kernel. The beta archive, FirmwareOriginals andrestore tree are retained locally for reproducibility and rollback.+## Creating an Apple TV machine++In Launchpad, New Machine > Device > Apple TV HD. The sheet picks tvOS 26.6+and the `tvos` preset, and turns Use Template and Slim System off: both drive+iOS Setup Assistant and its apps. From the command line:++```zsh+vphone-launchpad-cli vm create tv --device AppleTV5,3 --cpu 4 --memory 4096 --disk-size 32+```++The machine is restored on its own and starts at TVSetup. Navigate with the+arrow keys and Return; Escape goes back, holding it returns to the Home+screen. The titlebar Home button and the Mac's Home key (fn-←) are the TV+button: a click or press goes Home, holding either opens Control Center.+Device > Home Screen (⌘⇧H) and Device > Control Center (⌘⇧T) do the same+through vphoned.+## Reproducing the validated configurationUse the built bundle's `vphone-cli` on a host configured according to[host setup](../../Documents/Guides/host-setup.md). Both IPSWs must be supplied-locally: the donor above and cloudOS 23E5207q. Other pairings are unvalidated.+locally: a donor above and cloudOS 23E5207q. Other pairings are unvalidated.The VM and the installer's temporary directory must share an APFS volume;TV guest updates refuse an in-place fallback when cloning is unavailable.Copy-on-write updates share unchanged blocks, but require space for changed data.For a **new** VM only, run these commands in zsh, replacing the three paths.Do not run `vm new` or restore against an existing VM you want to preserve.-This manual pipeline creates one 32 GB disk and no template. The historical-`--iphone-source` option accepts the TV donor.+This manual pipeline creates one 32 GB disk and no template, as `vm create+--device AppleTV5,3` does. The historical `--iphone-source` option accepts the+TV donor.```zshcli='/absolute/path/to/VPhone.bundle/Contents/MacOS/vphone-cli'@@ -49,44 +85,7 @@ cloud_ipsw='/absolute/path/to/cloudOS_23E5207q_Restore.ipsw'export VPHONE_LIBRARY_ROOT="$HOME/vphone-tvos"vm='tvos-26_4-beta'"$cli" vm new "$vm" --cpu 4 --memory 4096 --disk-size 32-"$cli" fw set-patches "$vm" --preset standard \- --allow kernel-exp-tv_tpro_pagers \- --allow system-dyld-exp-tv_tpro \- --block dyld-boot-iomfb_force_kern \- --block dyld-boot-iomfb_swapend \- --block dyld-boot-lockdown_mode \- --block dyld-boot-lsd_embedded_reg \- --block dyld-boot-maxslide \- --block dyld-boot-xpc_lwcr \- --block dyld-cfw-camera \- --block preboot-cfw-devicetree_board_audio \- --block preboot-cfw-devicetree_haptics \- --block preboot-cfw-devicetree_iphone_product \- --block preboot-cfw-devicetree_microphone_array \- --block system-apps-cfw-attitude \- --block system-backboardd-cfw-gyroscope \- --block system-campo-cfw-entitlements \- --block system-debugserver-cfw-install \- --block system-diskimagesiod-cfw-is_mount_complete \- --block system-extensions-boot-gpu_bundle \- --block system-installcoordination_proxy-cfw-persona_lookup \- --block system-jetsamproperties-cfw-disable_allowed \- --block system-launchd-boot-jetsam_panic_guard_bypass \- --block system-launchd_cache_loader-boot-unsecure_cache_gate \- --block system-launchdaemons-boot-environment \- --block system-locationd-cfw-disable_auto_cohort \- --block system-mobileactivationd-boot-should_hactivate \- --block system-paravirt_gpu-cfw-heap_index_offset \- --block system-systemversion-cfw-build_version \- --block system-virtiosound-cfw-hal_plugin \- --block system-virtualaudio-cfw-microphone_graph_chains \- --block system-virtualaudio-cfw-mute_set_throw \- --block system-virtualaudio-cfw-speaker_graph_chains \- --block system-virtualaudio-cfw-speaker_protection_gate \- --block system-virtualaudio-cfw-speaker_raw_chains \- --block system-virtualaudio-cfw-speaker_route_throws \- --block system-virtualaudio-cfw-volume_mode_precondition \- --block system-vphoned-boot-install+"$cli" fw set-patches "$vm" --preset tvos"$cli" fw prepare "$vm" --device AppleTV5,3 \--iphone-source "$tv_ipsw" --cloudos-source "$cloud_ipsw""$cli" fw patch "$vm"@@ -105,10 +104,11 @@ sudo "$cli" cfw install --library-root "$VPHONE_LIBRARY_ROOT" "$vm" --keep-artifIf host preflight refuses the VM binary, run its printed allowlist command andretry the launch. Navigate setup with arrows and Return; Escape goes back.-No vphoned first-boot probe is appropriate for this configuration.+`vphone-cli vm wait`, or `vphone-launchpad-cli vm wait`, reports when vphoned+answers.-`fw set-patches` replaces all overrides, so always retain the entire selection-above. On an installed, stopped VM, guest-side changes use `sudo "$cli" cfw+`fw set-patches` replaces all overrides; the `tvos` preset holds the whole+Apple TV selection. On an installed, stopped VM, guest-side changes use `sudo "$cli" cfwupdate-environment --library-root "$VPHONE_LIBRARY_ROOT" "$vm"`; kernel changesuse `sudo "$cli" cfw update-kernel --library-root "$VPHONE_LIBRARY_ROOT" "$vm"`.Neither requires another restore. A prior research installation must first@@ -130,15 +130,19 @@ does not contain those removed patch implementations.`Ap,SystemVolumeCanonicalMetadata` with SHA-384 in the hybrid manifest.J42d's SHA-1 donor digests failed PCC metadata authentication and sealing;the corrected hybrid restore completed.-4. Apply the existing seputil/gigalocker repair. Block unvalidated iOS guest- payloads, graphics/audio hooks and shared-cache patches. Preparation now- respects the GPU patch selection, avoiding an unnecessary recovery VM.-5. Explicitly enable `system-dyld-exp-tv_tpro` and- `kernel-exp-tv_tpro_pagers`. Both are off in Standard. Keep the donor's+4. Apply the existing seputil/gigalocker repair, vphoned and the launchd+ cache gate its job needs. Block unvalidated iOS guest payloads,+ graphics/audio hooks and shared-cache patches; the `tvos` preset does both.+ Preparation skips the GPU driver for an Apple TV, avoiding an unnecessary+ recovery VM whatever order the selection is recorded in.+5. Enable `system-dyld-exp-tv_tpro` and `kernel-exp-tv_tpro_pagers`. Both+ are off in Standard and on in `tvos`, and apply to every tvOS 26 userland+ on cloudOS 26.4. Keep the donor'snative shared cache and page-in linking intact.6. Forward Escape to the TV's native virtual keyboard instead of consumingit as an iPhone edge swipe. Device > Back uses the same keyboard path,- without vphoned. Backspace remains available for editing text.+ without vphoned. Backspace remains available for editing text. Home and+ Control Center go through vphoned (below).The dyld operation rewrites only the exact `dyld_hw_tpro` and`dyld_hw_tpro_pagers` parameter-name prefixes to `vphn`, in both standalone@@ -172,7 +176,9 @@ with an executable initializer. It accepts only defaults 0 or 1. Both segmentbounds and actual file bounds are checked. The fileset's outer `__DATA` containsthe embedded `__KLDDATA`. No observed offsets or instruction words are bakedinto the patch; unsupported or ambiguous layouts fail the selected operation.-Its applicability is limited to the 26.4 donor/kernel pairing.+The tunable lives in the cloudOS 26.4 kernel, whatever tvOS userland it runs,+so the patch applies to every tvOS 26 donor on that kernel. tvOS 26.6 (23L773)+needed the same fix and booted with it.`cfw update-kernel` rebuilt from FirmwareOriginals and replaced only theinstalled Preboot kernel payload, retaining the manifest and volumes. A normal@@ -205,8 +211,8 @@ seputil/gigalocker repairs. TV environment updates recognize the guest receiptwhen vphoned is omitted. Unreadable cache undo logs abort instead of beingsilently replaced.-The titlebar Home button requires vphoned and remains disabled in this-configuration. Native arrow, Return and Escape input does not require it.+Native arrow, Return and Escape input does not require vphoned; the titlebar+Home button and Control Center do, and work now that the guest runs it.Activation, model metadata, audio and Apple services retain the limitationslisted above; this validation does not establish full Apple TV compatibility.@@ -214,3 +220,194 @@ Research helpers and the prior bundle are retained locally under`.build/tvos-research/pr-backup`, outside the PR. Boot evidence is in`.build/tvos-research/pr-clean-boot.log`; the Settings screenshot and earliernative runtime transcripts remain beside it. No second VM disk was created.++## vphoned on tvOS++vphoned is an arm64 Mach-O, so the plain-arm64 TV userland can run it, and+every symbol it imports resolves in the tvOS 26.4 shared cache, UIPasteboard+and UIScreen included. Installed unchanged, it never started: each launch+left a crash report, `Library not loaded: …/Foundation.framework/Foundation …+(wrong platform to load into process)`. dyld takes the process platform from+the main executable, and vphoned's `LC_BUILD_VERSION` says iOS (2) while every+library in the cache says tvOS (3).++The bundle build now ships `guest-resources/vphoned-tvos`: the same binary+with `vtool -set-build-version tvos 15.0 <sdk> -replace`, signed with+vphoned's entitlements. `ValidateBundle.sh` requires it to be TVOS and every+other guest binary to be IOS. `cfw install` installs it for an Apple TV guest,+and launch stages it as `.vphoned.signed`, so the host's hash check keeps the+TV copy current instead of replacing it with the iOS one.++Its launchd job goes into `/System/Library/xpc/launchd.plist` as on iOS. The+`launchd_cache_loader` gate patch found and NOPed the same branch in the+plain-arm64 loader (`0xB00` in 23L5208m), and the console then shows `Using+unsecure cache: /System/Library/xpc/launchd.plist`. Both are now admitted for+TV (`FirmwareGuestPatchResolution.tvSupportedGuestPatches`). The environment+hooks (`system-launchdaemons-boot-environment`) stay blocked; they have no TV+port.++Verified on 23L5208m and 23L773: `vm wait` returns, `device.info` reports+`own_name` "Apple TV", screenshots and `apps.launch` work, and consumer-page+HID input moves the TVSetup focus.++## TV button, Home and Control Center++A USB keyboard cannot press the TV button: no keyboard-page key maps to it.+UIKit's `_UIEventHIDPressTypeForKeyboardHIDEvent` (UIKitCore, 23L5208m) maps+consumer page `0x0C`:++| Usage | Press type | Button |+| --- | --- | --- |+| `0x40` Menu | 17 | TV / Home |+| `0x1C0` | 500 | TV / Home (second type) |+| `0x223` AC Home | 101 | game controller Home |+| `0x30` Power | 104 | Power |+| `0x41`–`0x46` | 4, 0–3, 5 | Select, arrows, Menu |+| `0xE9` / `0xEA` | 102 / 103 | Volume |++PineBoard's `+[PBSystemGestureRecipe recipeForType:]` presents Control Center+(system gesture `0x1d`) on a long press of press types 17 or 500, on a press of+104 when the `allowPowerButtonToOpenControlCenter` default is set, or on the+game controller's Home. A long press of Menu (5) runs+`_cleanUpUIStackAndLaunchKioskAppWithReason:@"Long MENU press"`, so holding+Escape also returns to the Home screen.++vphoned's `input.hid` injects consumer events inside the guest. The existing+Home Screen action already sends `0x0C/0x40`. For an Apple TV guest the titlebar+Home button sends the press when the mouse goes down and the release when it+comes up, and the Mac's Home key (fn-← on a laptop) does the same with its+key down and up, so either one held opens Control Center. Device > Control Center, shown+only for an Apple TV guest, holds the same usage for 1.2 s. On 23L5208m a+`0x0C/0x40` press over `input.hid` returned from Settings to the Home screen,+and a 1.5 s hold opened Control Center.++## Apple TV 4K from its OTA++Apple publishes no IPSW for any Apple TV 4K. The full tvOS 26.6 (23L773) OTA+for AppleTV14,1 (J255, A15) is a 4.76 GB AEA archive whose key AppleDB records.+Its userland is arm64e and, like the HD's, monolithic: no cryptexes. It ships+the IOGPU Metal stack, and every import of the paravirtual GPU driver resolves+in its shared cache. The OTA has no root filesystem image, only 37+`payloadv2/payload.NNN` chunks, each a `pbzx`-compressed Apple Archive with+owners, modes, BSD flags and APFS compression per entry, plus the root+filesystem's `.mtree` (an IM4P `msys` around a `pbze`/LZFSE Apple Archive+manifest), `.root_hash` and `.trustcache`, and the J255 device tree.++An Apple TV 4K guest is the Apple TV HD's 26.6 IPSW (same build) restored with+the J255 identity, its userland swapped for the OTA's in `cfw install`.++### Creating one++```zsh+vphone-launchpad-cli vm create tv4k --device AppleTV14,1 --cpu 4 --memory 4096 --disk-size 48+```++or `vphone-cli vm create tv4k --device AppleTV14,1`, or in Launchpad New+Machine > Device > Apple TV 4K (3rd generation). The firmware catalog pairs the+4K with the HD's 26.6 IPSW and cloudOS 26.4, and lists the OTA's URL, length+and key; `fw prepare` downloads the OTA into `<ipsw cache>/ota/` under+`AppleTV14,1_26.6_23L773_OTA.aea`, or uses the copy already there. The machine+gets the `tvos-4k` preset. Step by step, with local files:++```zsh+"$cli" vm new tv4k --cpu 4 --memory 4096 --disk-size 48+"$cli" fw set-patches tv4k --preset tvos-4k+"$cli" fw prepare tv4k --device AppleTV14,1 \+ --iphone-source "$hd_266_ipsw" --cloudos-source "$cloud_ipsw" \+ --ota-source ~/.vphone/ipsws/ota/AppleTV14,1_26.6_23L773_OTA.aea+"$cli" fw patch tv4k+```++then DFU, `restore`, `cfw install` and launch as for the HD. `--ota-key+<base64>` gives the key for an OTA the catalog does not list; a local OTA of a+listed build takes the catalog's key.++### What `fw prepare` does++`fw prepare --device AppleTV14,1` resolves the IPSW as the HD's+(`VPhoneGuestDevice.restoreBase`), so the restore tree is+`iPhoneOS_AppleTV5,3_26.6_23L773_Restore` and the hybrid manifest is built+from the HD's identity, as for an HD guest. Then, with+`VPhoneOTAArchive` (`VPhoneKit/VPhoneArchiveKit/Transfer`):++1. Before any IPSW is unpacked, the OTA is decrypted far enough to read+ `AssetData/boot/BuildManifest.plist`: it must list AppleTV14,1 and be the+ IPSW's build. A wrong key fails here too.+2. After the restore tree is built, one pass over the OTA writes+ `AssetData/boot/Firmware/all_flash/DeviceTree.j255ap.im4p` into the+ tree's `Firmware/all_flash`, beside J42d's, and every+ `AssetData/payloadv2/payload.NNN` plus `payload_chunks.txt` into+ `<vm>/OTAUserland`. The `.ecc` files, firmware, kernel and BOMs are skipped.+ The chunks must be numbered from 0 and match the list one for one. The+ folder is assembled under a temporary name and renamed into place; a+ prepare for any other firmware removes a stale one.+3. `config.plist` records AppleTV14,1 and its 3840x2160 @2x screen. The+ paravirtual GPU driver and compiler plugin are staged into `.pcc-gpu` as for+ an iPhone: only a plain-arm64 guest skips them.++The reader uses the system AppleArchive framework (`libAppleArchive`), no+`ipsw`, `aea` or `aa` process. `ArchiveEncryptionContext` reads the AEA+header and takes the symmetric key; `ArchiveByteStream.decryptionStream`+returns nil for a wrong key. The decrypted archive is segmented: its top-level+entries are metadata (`TYP=M`), and each `YOP=E` (extract) entry's `DAT` blob+is another, uncompressed Apple Archive with the next run of files; `YOP=M` is+the segment manifest and `YOP=O` the owner and mode fix-ups. Each segment is+decoded from its parent's blob through a custom byte stream, and members stream+to disk in 8 MiB blocks, so the 4.76 GB OTA is read once and never held in+memory: the pass over the real OTA takes about a second. A decrypted archive+(`AA01`, or `pbz*` compressed) reads the same way without a key.+AppleArchive's Swift wrappers close their stream when released and a decoder+does not retain its input, so every layer is kept alive until the read ends;+without that the first header read fails with `ioError`.++`fw patch` keeps the recorded AppleTV14,1 although the HD manifest does not+list it, and `cfw install` takes the guest's own board tree when J42d's is+there too.++### What `cfw install` does++`system-tv-exp-ota_userland` empties the System volume and runs `/usr/bin/aa+extract` for each chunk as root, before every other guest step, then records+the chunk list on the volume so an environment update does not extract it+again. The GPU driver and compiler plugin get `LC_BUILD_VERSION` platform tvOS+(`MachOBuildPlatform`), an Apple ad-hoc re-sign and a resealed bundle; AMFI's+trust-cache check is already patched to accept any cdhash, so the HD's static+trust cache does not matter.++The `tvos-4k` preset is `tvos` with the GPU bundle and+`system-tv-exp-ota_userland` on and both TV TPRO patches off: arm64e dyld+handles hardware TPRO, and those patches are for plain-arm64 dyld only. The+installer admits the GPU bundle and the userland swap only for an arm64e TV+guest (`FirmwareGuestPatchResolution.tvArm64eGuestPatches`).++### Results++Prototype, 2026-10-15 (VM `tvtest-4k`, staged by hand with `ipsw`): the guest+boots to the tvOS home screen. vphoned answers with `model` AppleTV14,1, tvOS+26.6, a 1920x1080-point screen at 2x; screenshots are 3840x2160. Control+Center's platters and the dock shelf render as materials. On the host the VM+has five `ParavirtualizedGraphicsGPUTask` processes (each HD guest has two),+and one had used 4.5 s of GPU time while every HD guest task read 0: the guest+renders through the paravirtual GPU. Settings > About reports tvOS 26.6+(23L773) and 2160p UHD at 120 Hz. Holding the TV button over `input.hid`+opened Control Center with frosted tiles, and the VM's GPU task (attributed to+its launcher by `responsibility_get_pid_responsible_for_pid`) gained GPU time+meanwhile.++Native path, 2026-10-15 (VM `tv4k-native`, `vphone-launchpad-cli vm create+--device AppleTV14,1 --preset tvos-4k --no-template` with the local HD and+cloudOS IPSWs): `fw prepare` found the OTA already in `~/.vphone/ipsws/ota/`+under its catalog name, checked its manifest, and staged J255's tree and the 37+chunks; the staged chunks are byte-identical to `ipsw`'s. Restore and `cfw+install` (93 patches, userland extracted, GPU driver retargeted) completed and+vphoned answered on the first boot. The guest starts at TVSetup's Language+screen at 3840x2160 with the Siri Remote artwork of the 4K, `device.info`+reports tvOS 26.6, and the VM has four `ParavirtualizedGraphicsGPUTask`+processes, one of whose GPU time went from 0.27 s to 0.95 s over twelve focus+moves sent with `input.hid`. The installed Launchpad (2.9.2) predates the+Apple TV support in New Machine and ran the iOS template trim and setup boot+after the install; setup failed at the service profile, which has no TV port.+That does not touch the steps above, and the guest booted normally afterwards.+++Apps, video, long-term stability and Apple services are untested.diff --git a/Skills/vphone-guest-control/references/machines.md b/Skills/vphone-guest-control/references/machines.mdindex 9c2d3904..cfb1f41a 100644--- a/Skills/vphone-guest-control/references/machines.md+++ b/Skills/vphone-guest-control/references/machines.md@@ -54,6 +54,11 @@ vphone-launchpad-cli vm create myphone [--bundle <version>] \`iPad15,5`, `iPad16,3`, `iPad16,5`, `iPad17,1` or `iPad17,3`. Without sourcesit takes that iPad's newest catalog pairing; with an iPad IPSW that coverstwo sizes it picks the size. See `Documents/Guides/ipados.md`.+ `AppleTV5,3` makes an Apple TV HD guest on tvOS 26.6: always without a+ template or slimming, with the `tvos` preset unless `--preset` names+ another. `AppleTV14,1` makes an Apple TV 4K guest the same way, with the+ `tvos-4k` preset; `fw prepare` takes its device tree and arm64e userland+ from the catalog's OTA. See `Research/Firmware/tvos_support.md`.- **Units:** `--cpu` is a count, `--memory` is **MB**, `--disk-size` is **GB**.Defaults 8, 8192, 64. All must be positive integers.- **Name:** letters, digits, `.`, `-`, `_`. Keep it short: the machine path must