How it works
If you have ever built a Hackintosh, the idea is similar: make Apple's software believe it runs on Apple hardware. On a phone or tablet the gap is much bigger, because nothing in an Android device looks like an iPhone to iOS. Every project on this site solves the same four problems: starting Apple's kernel, driving the hardware, getting a picture on the screen, and keeping iOS happy without the parts it expects.
Starting Apple's kernel
An iPhone starts with Apple's boot ROM and iBoot, which only load software Apple signed. An Android phone has the chip maker's chain instead (Qualcomm, Google or Samsung), ending in the phone maker's bootloader, which expects an Android boot image. None of the projects replace that chain. Most use fastboot boot, which starts an image once from RAM without writing it to the phone, and put something in that image that can start XNU. Samsung phones have no fastboot, so the Galaxy S7 port flashes its loader to the BOOT partition and Samsung's own bootloader starts it from there.
There are two ways to do that right now:
- A small boot shim (ios-sweet and most of its ports). The bootloader starts the shim as if it were Linux. The shim sets up memory the way XNU expects, hands it a description of the hardware in Apple's format (an Apple Device Tree, generated on the PC from the phone's own device tree) and jumps into the kernel. It's a tiny stand-in for iBoot.
- UEFI plus a loader (HackiOS, UniXNU). The boot image holds a UEFI firmware for the device, ported from the Mu-Silicium project that's also used to run Windows on Android phones. UEFI then starts the project's own loader, which starts XNU. HackiOS's loader also stays around to talk to the PC over USB and to collect the kernel's log.
Then the chain is the same for everyone:
- XNU. Apple's kernel, built from Apple's public source with patches and new drivers for the device. The phone projects use xnu-8796, the iOS 16 generation; UniXNU uses xnu-10063 for iPadOS 17.
- Storage. iOS needs its system volume somewhere. ios-sweet and most ports install it into the partition Android used for user data, which needs a storage driver for the phone's flash (UFS on most of them). HackiOS can instead send the system image into the phone's RAM over USB for each session, so nothing on the phone changes.
- iOS. launchd starts, then the system daemons, then backboardd (input and display) and SpringBoard (the home screen). These are Apple's own files, from the iPhone X or iPhone 8 firmware (or, for UniXNU, the 2017 iPad Pro's).
Where the drivers come from
An Android driver is part of the Linux kernel. It's written against Linux's own functions, memory management and device model. XNU works differently and has its own driver system called IOKit, so a Linux driver can't just be copied in.
The Android side is still the main source of information. Phone makers publish the Linux kernel source for their phones, and every phone carries a device tree that lists its hardware. Together they show where the touch controller sits, how the screen is set up and how the buttons are wired. The projects use that to write new drivers for XNU that talk to the same chips. The hardware itself doesn't care which kernel is talking to it.
For big drivers, rewriting everything is a lot of work, so there's a second option: run the Linux driver on top of a translation layer that provides the Linux functions it needs. HackiOS does this for Wi-Fi: Linux's ath11k driver runs on a layer based on FreeBSD's LinuxKPI. Other ports wrote their Wi-Fi drivers from scratch instead, like the Pixel (2016) port for its QCA6174 chip.
The other half of every driver is making iOS accept it. iOS doesn't want "a Goodix touchscreen". It wants an Apple-style touch device that sends the events Apple's own touch hardware sends. So the touch driver reads finger positions from the chip and reports them to iOS the way an iPhone would. The same goes for the buttons, the battery, the speaker and the screen.
Why an iPhone X (or 8)?
Newer iPhones (XS and later) use a CPU feature called pointer authentication. Their whole system is compiled for it (the "arm64e" variant), and most of the chips these projects run on don't have it. The iPhone X and iPhone 8 share the newest chip generation (Apple A11) that runs iOS 16 without needing it, so the phone projects use their firmware: iOS 16.7.16 for ios-sweet and most ports, iOS 16.5 for HackiOS.
Which of the two a project picks is mostly about the screen. The iPhone X firmware expects a tall screen without a Home button and uses swipe gestures, which suits most modern phones. The iPhone 8 firmware expects a 16:9 screen with a Home button, which matches older phones like the Pixel (2016), whose port uses it. Its smaller screen is also less work to draw. Either way, iOS has to be told which device it's on (iPhone10,3 for the iPhone X, iPhone10,1 for the iPhone 8) so it picks the right layout and features.
iPads give a little more room. The 2017 iPad Pro (up to iPadOS 17) and the 7th-generation iPad (up to iPadOS 18) don't use pointer authentication either. UniXNU uses the 2017 iPad Pro's iPadOS 17 firmware on a Snapdragon tablet.
The screen
When the bootloader (or UEFI) shows its logo, it turns the display on and leaves an image buffer in memory that the panel keeps showing. Every project starts by reusing that buffer instead of writing a display driver: iOS draws a frame, and the kernel puts it into that buffer. Some later take over the display controller themselves; the Pixel (2016) port flips between two buffers at up to 60 Hz, so there is no tearing.
Drawing the frame is the hard part. iOS's interface is drawn by CoreAnimation, which normally runs on Apple's GPU through Metal. The projects have found several ways around that:
- ios-sweet and most ports use CoreAnimation's built-in software renderer, so the CPU draws everything. It works, at roughly 20 to 30 frames per second.
- HackiOS drives the Adreno GPU with Mesa's open-source freedreno driver, ported to run under iOS, and gives CoreAnimation OpenGL ES to draw with. Metal for apps is the next step. They're translating Apple's shader format into Mesa's, and some of Apple's system shaders already run on the Adreno.
- The Pixel (2016) and Redmi Note 12 ports do the same. The Redmi Note 12 port reuses HackiOS's code. The Pixel port did it on a much older Adreno 530 with its own kernel GPU driver, and wrote replacement shaders for the effects Apple only built for Metal (blurs, Control Center buttons).
- The Pixel 4 port goes straight to Metal: a translation layer turns Metal calls into Vulkan, and Mesa's Turnip driver runs them on the Adreno 640. SpringBoard and the apps draw on the GPU.
- UniXNU takes the same Metal-to-Vulkan route on the Adreno 740 in its tablet, on top of its own native kernel driver for the GPU, so the system interface is composited on the GPU.
The phone's panel isn't iPhone-shaped either, and iOS only lays itself out properly on screen sizes it knows. So iOS is told it has a real iPhone's panel, and the picture is fitted onto the real one. ios-sweet presents an iPhone X panel (1125 x 2436) and centers it on the 1080 x 2400 screen. The Pixel (2016) and Pixel 4 ports let the GPU scale each frame to fit.
What gets faked or switched off
- Security. iOS checks code signatures, runs apps in a sandbox and keeps encryption keys in the Secure Enclave, a security chip. These phones have no Secure Enclave, and a modified system wouldn't pass Apple's checks, so code signing and the sandbox run in a permissive mode, and the key store is a small stand-in. Don't put personal data on it.
- Apple's closed drivers. iOS talks to drivers Apple never published, like the framebuffer (IOMobileFramebuffer) and shared graphics memory (IOSurface). The projects write their own versions that answer the same calls.
- Small fixes inside iOS. ios-sweet changes a few settings files in the system image (it skips first-run setup, for example), and most of its ports keep those changes. HackiOS leaves Apple's files untouched and instead loads small libraries of its own into a few system processes at runtime.
- Activation. A new iPhone normally activates with Apple's servers. ios-sweet and its ports use an offline path that iOS already has for this, and HackiOS's library tells SpringBoard the phone is activated. Either way, Apple's servers aren't involved.
Debugging without a serial port
Most kernel ports start with a serial console, and these phones don't have a usable one, so every project builds its own way to get the kernel log out. ios-sweet keeps the last 4 MB of the log on the phone's storage and streams it over USB as a network connection, which many ports reuse. HackiOS's loader stays in memory, takes the log back when a session ends and sends it to the PC. The Pixel 6a port even shows the log as a loop of QR codes that a webcam reads. Most projects keep detailed notes: ios-sweet's NOTES.md logs every boot attempt, and HackiOS has a page on how their own checks fooled them that's worth reading before your first port.