hackiosx Projects r/hackios

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:

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:

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:

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:

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:

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:

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:

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:

FeatureWho 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-FiHackiOS (WCN6750), Pixel 2016 port (QCA6174), Pixel 4 port (WCN3990), Redmi Note 12 port
SoundHackiOS, Redmi Note 12 port
CameraHackiOS
Battery level and chargingPixel 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

Pieceios-sweet and its portsHackiOSUniXNU
BootThe shim (shim/), packed as an Android boot imageA Mu-Silicium UEFI port plus their loader (uefi/, xnuloader/)A Mu-Silicium UEFI fork per device plus DarwinBoot
Hardware descriptiontools/mkadt.py (constants at the top), plus a few addresses in the shimA device profile and a loader platform entry, drafted by their new-device.sh script from your device treeThe device repository's board file
Board driversKernel 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 0077redwood_*.c in the kernel tree (touch, buttons, CPU speed, GPU, Wi-Fi, audio)Separate driver repositories, one per driver
GuideThe README and NOTES of ios-sweet and of the port closest to youdocs/PORTING.mdunixnu.com/porting

When it gets stuck

What you see usually points to one step:

What you seeLikely cause
The bootloader refuses the imageWrong boot image version, compression or signature (step 1)
Nothing changes on screen, or it stays on the bootloader's logoWrong framebuffer address, or a command-mode panel that needs a refresh (step 2)
The phone reboots within secondsA watchdog still running (step 1), or memory that overlaps a reserved region (step 3)
Kernel text appears, then everything stopsInterrupt controller or timer values (step 3)
It hangs when more cores startCores 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 chipsNewer instructions the cores don't have (step 4)
Stuck waiting for the root deviceThe storage driver can't reach the controller, maybe because the bootloader shut it down (step 5)
Apple logo for a very long timeNormal on the first boot; otherwise look for crashing daemons in the log (step 6)
Lock screen, but touch does nothingThe touch chip's power rail, its pins or its protocol (step 7)
You can unlock, but swiping up doesn't go homeEdge touches aren't marked as edge touches (step 7)

Tips from the ports so far

Got further on your phone? Post it on r/hackios with the chip, the step you reached and what you had to change. It helps everyone after you, and working ports get added to the list.