Skip to content

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.md
new file mode 100644
index 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.md
index 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.md
index 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.md
index 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