Run a virtual iPhone on an Apple Silicon Mac.
Kernelcache recipes
Only the 26.1–26.4 beta cloudOS releases ship vphone600 components. On any
other cloudOS, fw patch takes the research board's (vresearch101) and rebuilds
its kernelcache.release.vresearch101 with the iPhone virtualization kexts of a
donor kernelcache (kernel-boot-vresearch101_kext_mix, KernelCacheMixer).
These recipes say how, one per supported kernelcache. Details are in
Research/0_binary_patch_comparison.md ("The research board's kernelcache").
Layout
bases/<iOS version>_<iPhone build>/
manifest.json the recipe (below)
symbols.json.gz symbol map: kernelcache address (decimal) to name(s)
kexts.txt bundle identifiers of the mix
donors/<id>/
manifest.json the donor kernelcache and the cloudOS it is read from
symbols.json.gz symbol map, for a stripped donor
Base manifest.json:
| Key | Meaning |
|---|---|
kernel.sha256, kernel.decompressedSHA256 |
identify the research board kernelcache (IM4P or decompressed) |
kernel.kdk |
the KDK its extraction makes; a kernelcache whose kexts carry no DTPlatformBuild (26.6, 26.7) takes the build from here |
donor |
donors/<id>, which supplies the virtualization kexts |
builderLayout |
kernel-last (iOS 26.4+, kmutil of macOS 26.4+) or kernel-first |
guest, sources |
the guest family of a recipe of its own (watch, homePod), and its kext sources in order: each kext from the first that has it |
kextOverrides |
bundle identifier to the source it is taken from although an earlier one has it (homepod_26.5_23L471: AMFI, corecrypto, AppleImage4 and IOTimeSyncFamily from the base, IOgPTPPlugin from vphone600_26.4_23E5207q) |
The bundle list is the base's kexts without the research-board-only ones (CIOMesh, MLX5, Thunderbolt, RDMA, ...), plus the donor kexts that link against the base kernel.
The donor vphone600_26.4_23E5207q is the vphone600 kernelcache of the 26.4
beta cloudOS, the last one with vphone600 components. Only that file is read
from the cloudOS IPSW, once, and kept with its extraction in
~/.vphone/kernelcache/donors.
The iOS 18 bases (18.1 to 18.7.2, the research board kernels of their own
release's cloudOS) take their kexts from vphone600_26.1_23B78, the vphone600
kernelcache of the public cloudOS 26.1. Mixing across versions cannot go by
name: each donor import was resolved by code identity in every base, and both
maps carry the names those targets have. 18.1 to 18.3.1 leave out the audio
kexts whose imports have no counterpart there (15 donor kexts instead of 18).
Requirements
- KDK extraction is native to VPhone.bundle; no external
ipswis required. The recipe's gzip symbol map is decompressed in process. - Root for the link: kmutil only reads kexts owned by root:wheel, and links the host's own kexts in place of any others without a word.
- A kmutil of the base's
builderLayout: macOS 26.4 or later for the iOS 26 bases, macOS 15 or 26.0 to 26.3 for the iOS 18 ones. A Mac with the other layout links over ssh on one that has it (VPHONE_KMUTIL_SSH, seeDocuments/en/firmware/firmware-preparation.md). - The kmutil of macOS 27 links
kernel-lasttoo, but keeps every kext's__auth_stubs. After the link,KernelCollectionStubCallsmakes the calls through them direct again and seals corecrypto's FIPS HMAC again, so the kernel patches find the call sites they find on a macOS 26 link (Research/0_binary_patch_comparison.md, "macOS 27's kmutil keeps auth stubs").
vphone-cli fw kernelcache <vm> stages the mix as the user (the extractions
and the volume, in ~/.vphone/kernelcache/staged), and under sudo links it:
root copies the volume into a directory of its own, refusing any link out of
it, and runs kmutil on the copy. fw patch then takes the mix from the cache;
stage first as the invoking user, then run the link or fw patch under sudo.
fw kernelcache --ipsw <path> is still accepted as an ignored compatibility
argument. The native extractor revision participates in both donor
and mix cache keys, so older external-tool extractions are rebuilt.
Mixed kernelcaches are cached in ~/.vphone/kernelcache/mix, keyed by the recipe,
with kmutil's log beside each. Remove ~/.vphone/kernelcache to rebuild them.
kmutil records the absolute path of every codeless kext, so the volume is linked at a path as long as the build root Apple linked the base in, read from the base. The mix then does not depend on where it is built.
Adding a base
A recipe comes from research, not from this repository:
- Symbolicate the stripped kernelcache with BinDiff against a symbolicated KDK of
the same family (
ipsw kernel symbolicate --bindiff <kdk> <kc> --json --aliases, which writes every name of an address, as step 4 needs). - Fix wrong binds, checked against link symbols, PAC discriminators, same-generation macOS KDKs and C++ vtables, until every donor import binds and the extraction links.
- Check the base: its extraction, linked again with Apple's bundle list, must be byte-identical to the shipped kernelcache.
- For a stripped donor, put the import names of the donor extraction the maps
were built against first in its map. Several names often share an address
(folded stubs, inherited
_kc.placeholders), and an import binds to the first one; another order makes kmutil fail with "could not find a kext which exports this symbol". - Build the mix, boot it, and add the map, bundle list and manifest here.