Run a virtual iPhone on an Apple Silicon Mac.
Swift
Document iPadOS guests
Jacky12296c7f3462
diff --git a/Documents/Guides/ipados.md b/Documents/Guides/ipados.mdnew file mode 100644index 00000000..0ef96c90--- /dev/null+++ b/Documents/Guides/ipados.md@@ -0,0 +1,70 @@+# iPadOS guests++[Documentation](../README.md) · [Create and Run](create-and-run.md) · [Compatibility](compatibility.md)++A vphone VM can run iPadOS instead of iOS. Nothing about the virtual hardware+changes: the boot chain, kernel, SEP and device tree still come from the PCC+cloudOS IPSW (`vresearch101ap` / `vphone600ap`). Only the userland comes from a+different restore IPSW, an iPad's instead of the iPhone17,3's, and the device+tree is rewritten so that userland sees an iPad.++## Supported devices++| Product | Model | Board | Display |+| --- | --- | --- | --- |+| `iPad16,1` (and `iPad16,2`, same IPSW) | iPad mini (A17 Pro) | J410AP | 1488x2266 @ 326 ppi, 2x |++Other iPads are refused by `fw prepare` until their device tree values are+added to `VPhoneGuestDevice` and `DeviceTreeGuestDevicePatches.swift`.++## Create one++Pass the iPad restore IPSW where the iPhone one would go. The cloudOS is the+same one an iPhone guest of that release would use; `fw catalog` lists it.++```sh+vphone-cli vm create ipad-mini \+ --iphone-source 'https://updates.cdn-apple.com/2026SummerFCS/cf7db64d-5866-4bf2-bfff-50a32f58bec3/iPad16,1,iPad16,2_26.6.2_23G90_Restore.ipsw' \+ --cloudos-source 'https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64'+```++In Launchpad, choose **New Machine**, set **Source** to **Custom IPSWs**, and+put the iPad IPSW in the **iPhone IPSW** field and the cloudOS IPSW in the+other. The Core Bundle in use must include iPad support.++The manual stages are the same as for an iPhone guest (`vm new`,+`fw prepare`, `fw patch`, DFU + `restore`, `cfw install`, `vm launch`).+Only `fw prepare` and `fw patch` differ for an iPad; DFU, `restore` and+`cfw install` run unchanged.++## What changes for an iPad++- **`fw prepare`** recognises the IPSW from its `SupportedProductTypes`, takes+ the erase identity and `DeviceMap` entry for the guest's board (an iPad IPSW+ covers several), and records the product type and the iPad's display in the+ VM's `config.plist` (`guestProductType`, `screenConfig`). The restore tree+ is named `iPhoneOS_iPad16,1_<version>_<build>_Restore`; the `iPhone` prefix+ is the restore-tree convention every reader matches, not the device.+- **Two device trees.** The hybrid manifest normally points `DeviceTree` and+ `RestoreDeviceTree` at the same vphone600 file. For an iPad, `DeviceTree`+ points at a copy, `Firmware/all_flash/DeviceTree.vphone600ap.guest.im4p`.+ Restore boots the untouched identity that `restored_external` checks against+ the manifest (`iPhone99,11`); the guest boots the copy.+- **`fw patch`** gives that copy the iPad's identity and presentation (patch+ set `devicetree`, entries `devicetree-cfw-ipad_*`):+ - root `model` `iPad16,1`, `target-type` `J410`, `target-sub-type` `J410AP`,+ `compatible` `J410AP, VPHONE600AP, AppleVirtualPlatformARM`;+ - `/product`: `artwork-device-idiom` `pad`, subtype 2266, scale 2, the+ iPad's product name, chrome, camera and button geometry, the multitasking+ capabilities (`medusa-overlay-app-capability`, `ui-floating-live-app`,+ `ui-overlay-app`, `ui-pinned-app`), and its product type and unique model;+ - phone-only `syscfg` placeholders (Dynamic Island, reachability, ringer+ switch, volume-button geometry, CarPlay, Watch pairing) are removed.++ The virtual hardware keeps its vphone600 description: GPU feature set,+ framebuffer, memory class and boot flags.+- **`cfw install`** leaves the installed device tree alone. The iPhone17,3+ post-restore identity rewrite (`preboot-exp-devicetree_identity`) is skipped+ on an iPad guest.+- **The VM window** follows `screenConfig`, so it opens at the iPad's aspect+ ratio.diff --git a/Documents/README.md b/Documents/README.mdindex 8df09834..eec2f53a 100644--- a/Documents/README.md+++ b/Documents/README.md@@ -8,6 +8,7 @@ Start with the [Launchpad quick start](../README.md#get-started). For terminal u| [Host Setup](Guides/host-setup.md) | Apple Silicon, SIP and AMFI settings, signing and preflight || [Create and Run](Guides/create-and-run.md) | Firmware inputs, full or manual pipeline, vphoned, storage and backups || [Compatibility](Guides/compatibility.md) | Verified firmware pairs and what the checks prove |+| [iPadOS Guests](Guides/ipados.md) | Running iPadOS from an iPad restore IPSW instead of iOS || [Package Environment](Guides/package-environment.md) | Installing and removing a package manager in the VM || [Troubleshooting](Guides/troubleshooting.md) | Launch refusals, restore failures, Home key and app problems || [Launchpad Command Line](Guides/launchpad-cli.md) | Installing and testing a local build with `vphone-launchpad-cli` |diff --git a/README.md b/README.mdindex fb007c91..9f12ef15 100644--- a/README.md+++ b/README.md@@ -77,6 +77,7 @@ To turn on the automation API, add `--api-listen 127.0.0.1:8765` at launch and u| [Host Setup](Documents/Guides/host-setup.md) | SIP and AMFI settings, building from source, environment checks || [Create and Run](Documents/Guides/create-and-run.md) | Firmware sources, the creation process, storage and backups || [Compatibility](Documents/Guides/compatibility.md) | Verified firmware pairings |+| [iPadOS Guests](Documents/Guides/ipados.md) | Run iPadOS (iPad mini A17 Pro) instead of iOS || [Package Environment](Documents/Guides/package-environment.md) | Installing and removing a package manager in the VM || [Troubleshooting](Documents/Guides/troubleshooting.md) | Common errors and how to fix them || [Networking](Documents/Guides/networking.md) | Network modes, and `tunnel` for a Mac behind a VPN or proxy |diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.mdindex 29b5dad9..9fbd7173 100644--- a/Research/0_binary_patch_comparison.md+++ b/Research/0_binary_patch_comparison.md@@ -9,7 +9,7 @@> identifier is the record identifier the patcher already emits, or the common> prefix when one patch writes several sites — so `jb.kcall10` is one selectable> patch covering its four records, and `sandbox_ext` covers every-> `sandbox_ext_<index>`. 116 patches are declared in total. `vphone-cli fw patches`+> `sandbox_ext_<index>`. 120 patches are declared in total. `vphone-cli fw patches`> prints them; `--json` is what the Launchpad patch editor reads.>> Two presets ship, prewritten, in@@ -19,6 +19,28 @@> three `hv_vmm_present` concealment patches, and the iPhone17,3 identity rewrites;> `extended` blocks nothing.>+> **iPad guests (2026-10-01):** four DeviceTree patches, on in `standard`,+> exist only for a VM whose userland comes from an iPad restore IPSW+> (`iPad16,1`, iPad mini A17 Pro, J410AP): `devicetree-cfw-ipad_artwork`,+> `devicetree-cfw-ipad_product`, `devicetree-cfw-ipad_buttons` and+> `devicetree-cfw-ipad_identity`. They are written to a second device tree,+> `Firmware/all_flash/DeviceTree.vphone600ap.guest.im4p`, which `fw prepare`+> copies from the vphone600 one and the hybrid manifest names as `DeviceTree`;+> `RestoreDeviceTree` keeps pointing at the original, so restore still boots+> the `iPhone99,11` identity `restored_external` checks. On that copy the+> iPhone-shaped base properties (`artwork_device_subtype`,+> `island_notch_location`, camera offsets) and the `-exp-` identity rewrites+> are not applied; the iPad edits set the root `model` / `target-type` /+> `target-sub-type` / `compatible` to iPad16,1 / J410 / J410AP /+> `J410AP, VPHONE600AP, AppleVirtualPlatformARM`, `/product`+> `artwork-device-idiom` to `pad` (subtype 2266, scale 2), fill the `syscfg`+> placeholders J410AP carries with its values, add the iPad multitasking+> capabilities, and remove the phone-only placeholders and the ringer switch.+> GPU, framebuffer and boot properties stay vphone600's. `cfw install` skips+> `preboot-exp-devicetree_identity` on an iPad guest. Values were copied from+> `DeviceTree.j410ap.im4p` in `iPad16,1,iPad16,2_26.6.2_23G90_Restore.ipsw`.+> See `Documents/Guides/ipados.md`.+>> **Only the camera remains of EXP by default (2026-09-28).** `standard` is now the> JB baseline plus the virtual camera. Off by default, besides the concealment> below: `watchdogd.hv_vmm_cache` (moved into