EL2 hypervisor and toolchain that boots macOS on the Snapdragon X2 Elite

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.

docs/STATUS.md has the details, the known issues and the roadmap.

An ASUS Zenbook A16 with the Snapdragon X2 Elite X2E-96-100 (UX3607OA). Nothing else is supported. The monitor, device tables, clocks and register addresses are specific to this machine.

A Mac host running macOS 27, connected to the A16 over USB-C. q1n1 brings up a USB NCM network link on that cable, and every boot, upload and log capture goes over it.

AC power is strongly recommended. The tools refuse to boot or write the SSD below a battery threshold.

Architecture in brief

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

Loading

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/, submodule SnapAdreno), the AdrenoMetal plug-in (plugin/, submodule SnapMetal) and the shared register and contract headers (include/)

gpu/air2ir3/ the AIR to ir3 shader compiler (submodule air2ir3)

gpu/agx* an earlier virtual-AGX model, kept for reference

drivers/ SnapI2CHID (snap-i2c-hid/, submodule SnapI2CHID), the QCC2072 Wi-Fi controller (snap-qcc2072/, submodule SnapQCC2072), 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

Repositories

Snapintosh is split across the Snapintosh organization. This umbrella repository holds the EL2 monitor, the host tools and the documentation, and mounts the components below as git submodules at the paths they always had, so every relative build path is unchanged. Clone it with its submodules:

git clone --recurse-submodules https://github.com/Snapintosh/Snapintosh.git git clone https://github.com/Snapintosh/q1n1.git # next to it, at ../q1n1

Repository Mounted at Contents

Snapintosh (this repository) EL2 monitor (probes/, compat/, shadow/), tools/, docs

q1n1 ../q1n1 (separate checkout) UEFI EL2 proxy and loader, a fork of Asahi Linux's m1n1

SnapAdreno gpu/adreno-kext/kext Adreno X2-90 IOGPU and display kernel driver

SnapMetal gpu/adreno-kext/plugin Metal driver plug-in (AdrenoMetal.bundle)

air2ir3 gpu/air2ir3 AIR to Mesa ir3 shader compiler kit

SnapI2CHID drivers/snap-i2c-hid I2C-HID keyboard, touchpad and precision-touchpad driver

SnapQCC2072 drivers/snap-qcc2072 QCC2072 Wi-Fi driver (work in progress)

A change to a component lands in its own repository first; the umbrella then moves the submodule pointer in a separate commit.

This repository ships no Apple, Qualcomm or ASUS binaries or firmware. You supply them yourself:

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.

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.