The project's README from github.com/Acelogic/Snapintosh. As one markdown file: README.md.
Snapintosh boots Apple's macOS 27 (build 26A428) on an ASUS Zenbook A16 laptop with a Qualcomm Snapdragon X2 Elite (X2E-96-100). It is an EL2 monitor (hypervisor) and the toolchain around it. The monitor runs Apple's stock kernelcache (the J700/T8140 kernel) unmodified by default. It supplies the platform contracts that the kernel expects from Apple silicon: the SPTM and TXM monitor calls, translation of the kernel's 16 KiB page tables, and the Apple devices the kernel looks for.
Graphics run on the laptop's own Adreno X2-90 GPU through a driver stack written for this project:
There is no software, CPU or paravirtual rendering path.
The project also includes an I2C-HID keyboard and touchpad driver (SnapI2CHID), native QCC2072 Wi-Fi work, and NVMe storage through an emulated Apple storage controller.
Snapintosh is used together with q1n1, a UEFI EL2 proxy forked from Asahi Linux's m1n1. q1n1 takes the machine at EL2 after UEFI and serves m1n1's proxy protocol over USB-C to a Mac host, which drives Snapintosh from there.
This is experimental software, written for one laptop model.
| Area | State |
|---|---|
| macOS desktop on the A16 | Boots to the desktop with GPU acceleration. Rendering is correct: the pixel checks across the desktop test scenes pass. |
| Smoothness | In progress. Interaction is usable but not yet smooth. The target is a steady ~60 Hz first and the panel's 120 Hz later. |
| Input | The built-in keyboard and touchpad work, including trackpad gestures, Mission Control and app switching. |
| Wi-Fi (QCC2072) | Scanning, a WPA2 connection, DHCP and ping work through a host-proxy harness driven from the Mac. Joining from the macOS Wi-Fi menu does not work yet. |
| Storage | macOS is installed on, and boots from, the internal NVMe. |
| Other hardware | Audio, cameras, Bluetooth, sleep and external displays are not supported. |
docs/STATUS.md has the details, the known issues and the roadmap.
flowchart TD
UEFI["A16 UEFI firmware"] --> Q1N1
Q1N1["q1n1: UEFI EL2 proxy<br/>(USB-C NCM link to the Mac host)"] --> MON
MON["Snapintosh EL2 monitor<br/>SPTM/TXM call emulation, 16K-to-4K shadow page tables,<br/>Apple device models (AIC, ANS2 NVMe, DART, ...), GPU ring and SMMU mediation"] --> XNU
XNU["Stock macOS kernel at EL1 + AuxKC<br/>(AdrenoX2 + AdrenoDisplay, SnapI2CHID, ...)"] --> USER
USER["macOS userspace<br/>WindowServer, Core Animation, apps<br/>AdrenoMetal.bundle + air2ir3 compiler runtime"]
HOST["Mac host: tools/cycle.py, q1n1 proxy client"] -. USB-C NCM .-> Q1N1
A16 UEFI -> q1n1 (EL2 proxy) -> Snapintosh monitor (EL2) -> XNU + AuxKC (EL1) -> userspace + Metal plug-in (EL0)
docs/ARCHITECTURE.md explains each layer.
| Path | Contents |
|---|---|
compat/ |
the EL2 monitor: SPTM/TXM contracts, CPU, interrupt, timer and device emulation, the GPU ring and SMMU mediation, the NVMe backend |
shadow/ |
the page-table walker and the 16 KiB guest to 4 KiB hardware shadow tables |
probes/ |
the code that runs on the target (loader, monitor entry) and the host-side image builder and runner |
tools/ |
firmware acquisition, kernelcache analysis, the boot-cycle tool (cycle.py), build helpers and the native test suites |
gpu/adreno-kext/ |
the AdrenoX2 kext (kext/), the AdrenoMetal plug-in (plugin/) and the shared register and contract headers |
gpu/air2ir3/ |
the AIR to ir3 shader compiler (README) |
gpu/agx* |
an earlier virtual-AGX model, kept for reference |
drivers/ |
smaller kexts: SnapI2CHID (snap-i2c-hid/), the QCC2072 Wi-Fi controller (snap-qcc2072/), the boot framebuffer, a loader test |
config/ |
monitor feature flags and guest launchd jobs |
build/ |
generated output (gitignored, apart from the AuxKC link helpers) |
docs/ |
design and reference documentation |
You need:
/Library/Developer/KDKs/KDK_27.0_26A428.kdk;gpu/air2ir3/tools/mesa-setup.sh;../q1n1).docs/BUILDING.md has the steps.
This repository ships no Apple, Qualcomm or ASUS binaries or firmware. You supply them yourself:
python3 tools/fetch-ipsw.py <url> [destination]. Then extract the J700 boot
set (kernelcache, device tree, SPTM, TXM and others) with
python3 tools/extract-firmware.py <ipsw> j700ap. Nothing runs without it.gen80100_gmu.bin, gen80100_sqe.fw) and the QCC2072 Wi-Fi firmware come
from the linux-firmware project. The Wi-Fi board file
(bdwlan_qcc2072_1p0_ncm820A.elf) comes from ASUS's Windows WLAN driver
package for this model. The tools check each file against a pinned SHA-256.The project depends on Apple software that each user must obtain and use under Apple's terms.
Snapintosh is an experimental hypervisor that runs with full control of the machine.
--thermal-guard), but those guards are not a guarantee.Use it at your own risk.
Snapintosh is an independent project. It is not affiliated with, endorsed by or sponsored by Apple, Qualcomm, ASUS or Asahi Linux. macOS, Metal and Apple are trademarks of Apple Inc. Snapdragon and Adreno are trademarks of Qualcomm Incorporated. Zenbook is a trademark of ASUSTeK Computer Inc. All other trademarks belong to their owners.
Running macOS on non-Apple hardware may conflict with Apple's macOS software licence agreement. You are responsible for making sure that your use complies with the licences that apply to you.
The project's own code is MIT licensed; see LICENSE. Some
components carry other licences. Generated Mesa register tables keep Mesa's
MIT notice, and the QEMU tracer patch in tools/qemu-sptm-oracle/ is
GPL-2.0-or-later. THIRD_PARTY_NOTICES.md and
LICENSES/ list every third-party component and its licence text.
Snapintosh builds on the published work of others:
THIRD_PARTY_NOTICES.md has the complete list.
| Read | For |
|---|---|
| docs/STATUS.md | what works, known issues, roadmap |
| docs/ARCHITECTURE.md | how the layers fit together, including the GPU stack and Wi-Fi |
| docs/BUILDING.md | building the monitor, kexts, plug-in and compiler |
| docs/RUNNING.md | a boot cycle with tools/cycle.py |
| docs/KERNEL-PATCHES.md | the opt-in kernel patches and why each exists |
| docs/BOOT-CHAIN.md | how a stock macOS kernel boots on this SoC |
| docs/FULL-INSTALL.md | installing to and booting from the internal NVMe |
| docs/COMPATIBILITY.md | guest/host boundaries and pinned profiles |
| gpu/air2ir3/README.md | the shader compiler |
| docs/WORKSPACE-LAYOUT.md | local inputs, generated output and what is never committed |
| docs/GUI-BOOT-ROADMAP.md | the path from the first kernel instruction to the desktop |
Snapintosh boots Apple's macOS 27 (build 26A428) on an ASUS Zenbook A16 laptop with a Qualcomm Snapdragon X2 Elite (X2E-96-100). It is an EL2 monitor (hypervisor) and the toolchain around it.