Port it to your phone
This page explains what has to happen for iOS to run on a phone it was never made for, step by step, and what usually goes wrong at each step. It doesn't give you commands to paste. Every phone is different, and the commands are in each project's README anyway. What carries over from phone to phone is knowing what each step needs, so that's what this page covers.
Use a spare phone and back it up first. Before anything else, boot a recovery and save the partitions that hold data unique to your phone: persist, the modem partitions (modemst1, modemst2, fsg, fsc), and boot, dtbo and vbmeta. Some of them hold calibration data that can't be downloaded anywhere. Most ports also erase Android's user data once you install the iOS system.
Before you start
You need four things:
- A way to run your own code. An unlocked bootloader that can start an image from the PC (
fastboot boot), or on Samsung phones, a BOOT partition you can flash. See Compatibility. - Your phone's hardware description. The device tree Android booted with (it lives at
/sys/firmware/fdton a running phone or recovery) and the phone maker's Linux kernel source. Between them they list every address, interrupt and chip on the board, and show how each chip is driven. - A base project. Start from whichever project or port runs on the chip closest to yours. A port on the same chip family saves weeks. See which project to start from and the community ports.
- A way to see what happened. At first that's the screen. Plan early for a way to get the kernel log off the phone (more in step 2).
What a port actually changes
Most of the work in these projects is generic: making XNU build, the file systems, Apple's missing drivers, the security stand-ins, the workarounds that keep iOS happy. That part carries over unchanged. The Pixel 6a port counted it for ios-sweet: of its 81 original kernel patches, about 66 don't care what phone they run on, about 10 only need new addresses, and only 5 are drivers for Qualcomm hardware.
A port replaces the device-specific layer: how the phone boots your code, where its memory and devices are, and drivers for the chips on your board. It helps a lot that the bootloader leaves some hardware running when it hands over: the screen keeps showing its image buffer, the storage link is often still up, and the USB controller is often still powered. A port leans on that at first and replaces it with real drivers later.
The steps below are in the order a port usually comes alive. Get each one working before moving on, because a problem in an early step looks like a mystery in a later one.
1. Get your own code running
The bootloader has to accept an image you built. On Qualcomm phones that's an Android boot image whose "kernel" is really the project's shim (ios-sweet and its ports) or a UEFI firmware (HackiOS, UniXNU). Bootloaders are picky, and this is where many ports lose their first day:
- Boot image versions differ. Some bootloaders only accept the newer layout (v4, with a separate
vendor_boot) and silently drop parts of an older one. The Redmi Note 12 port had to hide its payload inside the kernel image because its bootloader threw away the ramdisk. - Some bootloaders want the kernel compressed or signed in a particular way. The Pixel 4 needs an LZ4-compressed kernel with a verification footer, or it refuses the image.
- Some phones arrive in your code with a hardware watchdog still running, which resets the phone after a few seconds unless you stop it, or at a higher privilege level than XNU expects (the Pixel 6a starts the shim at EL2).
- Samsung phones have no
fastboot boot. The Galaxy S7 port flashes its loader to the BOOT partition and lets Samsung's bootloader start it.
Before the first try, find out how to force your phone back into the bootloader (on most phones, hold Power and Volume down). Your code will hang a lot, and with fastboot boot a forced reboot always brings you back to a working phone.
It works when your code visibly does something: a color on the screen, text, or a reboot to the bootloader on purpose.
2. A picture and a log
Until you have drivers, the screen is your debugger. The bootloader leaves the display running and showing an image buffer in memory. Your device tree names it (look for a reserved memory region called something like cont_splash or splash), along with the panel's width and height. Write pixels there and they show up.
One catch: panels come in two kinds. Video-mode panels keep reading the buffer by themselves, so anything you write appears. Command-mode panels (the Pixel 4 and Pixel 6a have them) only update when told to, so you have to poke the display controller to refresh. Without that the screen stays frozen on the bootloader's logo.
Next, get the log off the phone, because filming the screen gets old fast. Projects have done it by keeping the log in a reserved piece of RAM or at the end of the storage partition and reading it from recovery, by streaming it over USB as a network connection, by sending it back to their own loader (HackiOS), and even as QR codes on the screen (Pixel 6a).
It works when you can read the shim's or loader's messages, ideally on your PC.
3. Describe the hardware to XNU
XNU learns about the machine from an Apple Device Tree, and the projects generate one from your phone's device tree. These are the values that matter for a first boot:
- Memory. The RAM range XNU may use. Qualcomm and other chip makers reserve pieces of RAM for the modem, the security firmware and so on. Your range has to avoid all of them. If it doesn't, the phone usually just resets instantly when the kernel touches protected memory. Look at the
memorynode and every entry underreserved-memory; a large bank with no reservations in it is the easiest choice. - Interrupt controller. The addresses of the GICv3, which most recent Android chips use (some older chips have the older GICv2, which needs other code). If interrupts don't arrive, the kernel hangs right after its early messages. Look for the node whose
compatiblesaysarm,gic-v3. - Timer. Its frequency (19.2 MHz on Qualcomm, different on Tensor and Exynos) and which interrupt it uses. A wrong timer interrupt also looks like a hang. Look for the
arm,armv8-timernode. - CPU cores. Each core's hardware ID (its
regvalue undercpus), so the kernel can start them later. - Storage controller. Where the UFS (or eMMC) controller sits, usually a node named
ufshc.
It works when the kernel's messages scroll past and it stops at "waiting for root device" or similar. That means memory, interrupts and the timer are right.
4. The CPU cores
Start with one core and add the rest later. Two things about your CPU can bite:
- 16 KB pages. iOS uses 16 KB memory pages everywhere. Some small CPU cores, especially older or budget ones, can't use them. Either leave those cores idle, or build a kernel that uses 4 KB pages, which is what UniXNU and the Redmi Note 12 port did.
- Older instruction sets. The iPhone X's chip understands newer instructions (ARMv8.2) than some Android chips (ARMv8.0). The kernel then has to be built for the older cores, and the few newer instructions that still show up in iOS have to be emulated by the kernel. The Redmi Note 12 port documents exactly how. The Pixel (2016) port reports that the iPhone 8 firmware it uses runs on its ARMv8.0 cores without that emulation.
Once one core is stable, the others start through PSCI, the standard firmware call for turning cores on. Some chips need extra steps there, like preparing the interrupt controller for each core first.
5. Storage and the iOS system
iOS needs its system volume. The usual route is to build it on your PC from Apple's iPhone X or iPhone 8 firmware file, which the projects download straight from Apple, and write it into the phone's userdata partition. The projects never include Apple's files themselves.
Then the kernel needs a storage driver to read it:
- On ios-sweet's phone the bootloader leaves the UFS link up, so the driver mostly just sends commands. Other bootloaders shut the controller down before handing over, and then the driver has to bring it up from cold. The Pixel 6a port had to do that.
- UFS controllers on Exynos and Tensor differ from Qualcomm's, so those ports need their own variant.
- eMMC needs a different driver altogether.
- HackiOS can skip all of this for a first boot by loading the whole system into RAM over USB.
It works when launchd, the first iOS process, starts and the Apple logo appears.
6. The lock screen
With a framebuffer, a CPU and storage, iOS can already reach the lock screen, but expect a few rounds of fixes first:
- Identity. iOS has to be told which iPhone it is (or which iPad, for iPadOS), and that has to match the firmware you installed, or it picks the wrong layout and features.
- Screen size. iOS only lays itself out on screen sizes it knows. Tell it it has the real iPhone's panel and fit that onto yours.
- Daemons that crash without hardware. The modem, Bluetooth and similar daemons crash or restart forever when their chip isn't there. The projects disable the worst ones.
- Slow first boot. The first boot takes several minutes while iOS sets itself up. Later boots are much faster.
Most of these fixes are already in your base project, so this step is usually short. Read its notes when something crashes; it has probably met the same crash.
7. Touch and buttons
Now the phone has to listen. Find your touchscreen's node in the device tree. It tells you the chip (Goodix, Focaltech, Novatek, Synaptics, ST and others), which bus it's on (I²C or SPI), its reset and interrupt pins, and which power rail it needs. The Linux driver for that chip in your phone's kernel source shows how to talk to it.
The new driver reads finger positions and hands them to iOS as an Apple-style touch device. Watch out for two things:
- The touch chip is often unpowered until something turns its power rail on. On Qualcomm phones that means a request to the power controller (RPMh on newer chips, RPM on older ones).
- iOS's swipe-up-to-go-home gesture only works if touches that start at the screen edge are marked as edge touches.
Buttons are simpler: power and volume usually sit on the power management chip or on plain GPIO pins, and become Apple-style key events.
It works when you can unlock the phone, open apps and swipe back home.
8. Everything else
From here on the phone works, and every new driver makes it nicer. You don't have to start from zero. Look for a project that already did the same thing on a related chip:
| Feature | Who has done it |
|---|---|
| GPU with OpenGL ES (Mesa freedreno) | HackiOS (Adreno 642L), Redmi Note 12 port (Adreno 610), Pixel 2016 port (Adreno 530) |
| GPU with Metal (translated to Vulkan) | Pixel 4 port (Adreno 640), UniXNU (Adreno 740, with a native kernel GPU driver) |
| Wi-Fi | HackiOS (WCN6750), Pixel 2016 port (QCA6174), Pixel 4 port (WCN3990), Redmi Note 12 port |
| Sound | HackiOS, Redmi Note 12 port |
| Camera | HackiOS |
| Battery level and charging | Pixel 2016 port, Redmi Note 12 port |
| USB networking (live log, SSH) | ios-sweet, Pixel 4 port, POCO M8 port; HackiOS has SSH too |
Two things to know. GPU, Wi-Fi and audio need firmware files that belong to the phone maker. They're never in the repositories, and you copy them from your own phone's Android. And Adreno generations differ, so a GPU driver usually needs real work to move from one generation to the next.
Where these pieces live in each project
| Piece | ios-sweet and its ports | HackiOS | UniXNU |
|---|---|---|---|
| Boot | The shim (shim/), packed as an Android boot image | A Mu-Silicium UEFI port plus their loader (uefi/, xnuloader/) | A Mu-Silicium UEFI fork per device plus DarwinBoot |
| Hardware description | tools/mkadt.py (constants at the top), plus a few addresses in the shim | A device profile and a loader platform entry, drafted by their new-device.sh script from your device tree | The device repository's board file |
| Board drivers | Kernel patches; in ios-sweet 0060 (keys, touch), 0062 (touch power, battery), 0063 (touch protocol), 0061 (screen size), plus the early screen address in 0010 and 0012, and USB in 0072 to 0077 | redwood_*.c in the kernel tree (touch, buttons, CPU speed, GPU, Wi-Fi, audio) | Separate driver repositories, one per driver |
| Guide | The README and NOTES of ios-sweet and of the port closest to you | docs/PORTING.md | unixnu.com/porting |
When it gets stuck
What you see usually points to one step:
| What you see | Likely cause |
|---|---|
| The bootloader refuses the image | Wrong boot image version, compression or signature (step 1) |
| Nothing changes on screen, or it stays on the bootloader's logo | Wrong framebuffer address, or a command-mode panel that needs a refresh (step 2) |
| The phone reboots within seconds | A watchdog still running (step 1), or memory that overlaps a reserved region (step 3) |
| Kernel text appears, then everything stops | Interrupt controller or timer values (step 3) |
| It hangs when more cores start | Cores that can't use 16 KB pages, or the interrupt controller isn't prepared for them (step 4) |
| Strange crashes in iOS processes on older chips | Newer instructions the cores don't have (step 4) |
| Stuck waiting for the root device | The storage driver can't reach the controller, maybe because the bootloader shut it down (step 5) |
| Apple logo for a very long time | Normal on the first boot; otherwise look for crashing daemons in the log (step 6) |
| Lock screen, but touch does nothing | The touch chip's power rail, its pins or its protocol (step 7) |
| You can unlock, but swiping up doesn't go home | Edge touches aren't marked as edge touches (step 7) |
Tips from the ports so far
- One problem at a time. Change one thing per boot. When two things change and the phone hangs, you've learned nothing.
- Trust only what you saw. "It's not in the log" doesn't mean it didn't happen. Logs get cut off, and a check that skips cases can look like a pass. HackiOS wrote down eleven ways their own checks fooled them.
- Write everything down. Every port that got far keeps a log of every boot: what changed, what happened. It's how you, and the next person, find the pattern.
- Read the closest port's history. Most walls you'll hit, someone has already hit on a similar chip.
- If you use an AI coding agent, give it your device tree, the phone's kernel source and the closest working port, and let it work on one milestone at a time. Several of the ports here were built that way. Check its work on the real phone, not on its word.