How I Started Porting Omarchy to My OnePlus 10 Pro
I know Linux as an operating system, but the kernel was always another world. To understand where hardware and software meet, I want to run Omarchy on a OnePlus 10 Pro nobody has ported. Part one: getting everything ready and learning the basics without flashing anything.
I've always liked understanding why things work the way they do. It's not enough for me that something works: I want to open it up, see what pieces it has and how they talk to each other. A lot of my projects started that way, more out of curiosity than need.
Linux is a funny case for me. I use it every day, on a PC I built myself that runs Omarchy, and at the operating system level I get around fine: packages, services, configuration, the terminal. But the kernel, the part of the system that talks directly to the hardware, is another world, one I don't pay as much attention to as I should. On a computer it's almost invisible: the kernel discovers the hardware on its own, and the problems I ran into were mostly drivers that didn't exist or weren't compatible. I'd never looked at what happens underneath: how the kernel knows what hardware it has, what goes on between pressing the power button and something showing up on screen, where exactly software and chips meet.
The idea came one day while scrolling X. Someone shared Omarchy Mobile: real Omarchy, with Arch Linux and Hyprland, running on a phone with no Android underneath. Not an app, and not a Linux boxed inside Android: the phone booting straight into Linux. And not just any Linux, but the mainline kernel, which is what people call the official kernel maintained by the community, as opposed to the modified version each manufacturer ships on its phones. I found it interesting, but as usual with these projects, limited to Pixel phones and little else. Until I saw a OnePlus on the list, and that gave me a bit of hope.
I had to wrestle with impostor syndrome for a while, but curiosity won and I thought: why not? I have a OnePlus 10 Pro (model NE2215) that isn't new anymore, but it has 12 GB of RAM and 256 GB of storage. That should be enough to run a full operating system without much trouble. That's how this started, and Omarchy on the phone became the excuse: what I'm really after is understanding the guts, everything that makes a piece of hardware and a piece of software end up working together. A phone is a good place for that, because almost nothing there is generic: every model needs someone to describe its hardware piece by piece. Adapting a system to a specific device like that is called a port.
I'm not doing it alone, either. A few months ago I wrote that AI might actually make this the year of Linux, because agents make its exceptions cheaper to diagnose, and a phone is probably the biggest exception there is. So this is also a way to test that: I'm doing it together with Claude Code. I plug in cables, press buttons, make the calls and ask why; the agent reads the repos, writes scripts and explains what shows up along the way. Almost everything I describe here I understood that way, by asking.
The first step was finding out whether it was even feasible. Almost everything here is new to me, so the series follows the order in which I found things out, including the ones I got wrong at first. This first entry covers the first stage of the experiment: finding out how far the phone was from running Omarchy and getting everything ready to try. Throughout that stage I kept to one limit: I didn't flash any partition on the phone: I didn't install the port or write any of the images the phone uses to boot. Its storage did change for other reasons, and I'll get to them: unlocking it wiped it, and later I installed an app.
Omarchy Mobile's rules for not damaging the phone
Omarchy Mobile has two repositories: one with the tools to build and install the system and notes on each supported phone, and another with the kernel, organized so its changes can be proposed to the official kernel (that's called sending patches upstream). The reference phone is the Pixel 7 Pro, nearly all the others are Pixels, and there are a few with Qualcomm chips, like mine: the OnePlus 13 and the OnePlus 6.
The first thing I read was how the project avoids breaking the phone, and to understand it I had to learn how a phone is organized inside.
A phone's storage is split into partitions, like a PC's disk, only there are many more: dozens. One holds the system, another your data (userdata), others the modem firmware, the antenna calibration, the program that boots the phone… The ones needed to boot exist twice, in two identical sets called slots A and B. That way Android can update the set it isn't using while it keeps running on the other one.
Omarchy Mobile takes advantage of that:
- Android stays untouched in one slot, as the way back, and Omarchy uses the other.
- It only writes its slot's boot partitions and
userdata. Never the bootloader (the program that runs at power-on, before any system), the modem or the calibration partitions. - At boot, before reaching the real system, the kernel loads a minimal system into RAM called an initramfs. Omarchy Mobile's ships a guard: it makes all storage read-only, except for an explicit list of partitions.
- Before touching anything, the modem partitions get backed up, because that's where the IMEI (the number that identifies the phone to the cellular network) and the radio calibration live, and those can't be replaced.
It's a project that assumes you'll make mistakes and plans for them. I liked that.
Which parts of my phone the Linux kernel already knows
The heart of a phone is a SoC (system on a chip): a single chip that puts together the processors, the GPU, the modem, the memory and storage controllers and a whole lot more. The 10 Pro's is a Snapdragon 8 Gen 1, which the kernel calls SM8450. OnePlus gave the phone the codename wly.
I couldn't find anyone who had ported this phone. But the chip is in mainline: the kernel already knows how to drive the SM8450, because other phones use it, like the Galaxy S22 and a couple of Xperias, plus Qualcomm's test boards.
This is where the first important distinction clicked. For the kernel to know what hardware there is, someone has to describe it in a file, the device tree (the next entry is about it). That description is split in two. One part describes what's inside the chip: processors, controllers, clocks. That part already exists, because the chip is the same in all these phones. The other part describes what the manufacturer soldered around the chip: the display, the touchscreen, the battery, which voltage each piece gets, which pin goes where. That part changes with every phone, and it's exactly the part I have to write.
A supported chip doesn't mean the phone boots. But it does mean I'm not starting from absolute zero.
Setting up the PC and building the kernel before touching the phone
On the PC I installed the tools for talking to the phone: adb, which talks to it while Android is running, and fastboot, which talks to the bootloader when the phone is in a special boot mode. Also a few for opening Android images, and one for extracting partitions from OnePlus update packages. That last one is needed because OnePlus, unlike Google, doesn't publish factory images of its phones: the only official thing is the updates.
The project includes a script that downloads the exact compiler all its kernels are built with, the same one Google uses for Android, and verifies every piece before using it. Before touching the phone I wanted to check that everything worked: build the project's kernel unmodified, inside a Docker container.
bin/omamobile kernel
The first two attempts didn't even start: one because I sent the build log to a folder that didn't exist, the other because Omarchy was missing a command the script took for granted. The third took 4 minutes 39 seconds and produced the kernel (15 MB), 1,827 modules and the hardware descriptions for the SM8450 phones that already exist. A cheap lesson: read the log before assuming the kernel failed.
The modules were the first thing I learned about the kernel's insides. Every driver can be built two ways: into the kernel (=y in its configuration), available from the very first instant, or as a module (=m), a separate file loaded later, when it's needed. In the configuration, the drivers for the SM8450's pins, clocks and internal buses were built in, because everything else depends on them. The storage driver, on the other hand, was a module. The phone's internal storage is a UFS memory chip, and the Arch system was going to live there, in userdata. So the initramfs would have to load that module before it could open the system. I'd never seen so clearly what an initramfs is for.
What you can learn about an Android phone without root
The next step was plugging the phone in and pulling every bit of information I could without changing anything. Android doesn't give you administrator permissions (that's what root means), so I could only see what the system shows anyone. The project has a command that gathers all of it:
bin/omamobile capture wly-stock
It saves everything outside any repository, because it includes the serial number, the IMEI and the phone's network addresses. On the first try it stopped halfway: Android won't let you read a certain file without root, the script failed there and quit. I finished the rest by hand.
What came out:
| Item | Value |
|---|---|
| Chip | SM8450 |
| Processors | 8 cores of three kinds: 4 efficiency, 3 performance and 1 more powerful |
| RAM | 12 GB |
| Storage | UFS, at address 1d84000 |
| Software | OxygenOS 15 (version 1302), Android 15 |
| Active slot | B |
That 1d84000 is the memory address where the storage controller lives, and it's the same one mainline's description of the SM8450 declares. First confirmation that what already exists in the kernel describes this chip.
The active slot was a problem. Omarchy Mobile assumes Android lives in slot A and only writes to B. On my phone, Android was running from B: following the recipe to the letter would have wiped the working Android. I had to choose between moving Android to slot A (an update always installs to the slot that isn't in use) or flipping the rule for this phone.
Something about the storage came up that I didn't know, too: a UFS chip doesn't show up as a single disk but as several. It's split into logical units, or LUNs, and Linux sees each one as a separate disk (sda, sdb, sdc…), each with its own partitions. On this phone, the boot partitions and userdata live on different LUNs. That matters, because Omarchy Mobile's guard only allows writes on the first one, so for it a partition's name isn't enough: which disk it's on matters too.
Without root I couldn't see the hardware description Android uses, but the manufacturer's list of drivers (373 modules) gave clues: three possible touch controllers (OnePlus uses the same software for several versions of the phone, with different parts), the Wi-Fi chip's driver, the audio one, OnePlus's charger and, as a curiosity, an infrared blaster.
Before going further I made a backup, because the next step wiped the phone. I copied photos, documents and downloads with adb, which keeps the files' timestamps: 12,942 files, 2.5 GB, compared folder by folder and with a checksum for each one next to it.
Why unlocking the bootloader wipes the phone
From the factory, the bootloader is locked: it only boots software signed by the manufacturer. To boot your own kernel you have to unlock it. I enabled the option in developer settings and rebooted into fastboot, the bootloader mode that takes commands over USB. On Qualcomm phones, that bootloader is called ABL.
fastboot getvar all asks the bootloader everything it knows about itself: 282 lines. The important one was this:
slot-unbootable:a: yes
Slot A was marked unbootable. When an update installs to the inactive slot and boots fine, the old slot ends up like that. On my phone, the way back is slot B, with Android working, and A is useless. That settled the earlier question: instead of moving Android, the cleanest option is to flip the rule for this phone (the project's OnePlus 13 already has an option for that) and only write to A.
The same command reported the battery at about 7.66 V. A typical phone sits around 3.8 V; the 10 Pro uses two cells in series, and that's what makes its fast charging possible (65 W on the NE2215, the North American model; the global one reaches 80 W). A note for when the charger comes up.
fastboot flashing unlock
Warning on screen, volume buttons, power button, and the phone wiped itself. It's not arbitrary: the phone's data is encrypted, and the keys depend on the boot being the one the manufacturer verified. If the bootloader let you boot unsigned code without wiping anything, anyone holding the phone could load a modified system and go after your data. The bootloader also reports the change: the boot verification state went from green (everything signed and verified) to orange (unlocked). The slot and the Android version didn't change.
OnePlus ships full updates and incremental patches
The usual way to get root is to modify Android's boot image: the boot.img file, which holds the kernel and a small initial system. I needed the one for my exact version, 1302, and OnePlus doesn't publish it. Claude suggested Oxygen Updater, an app that queries OnePlus's servers and gives you the official links to its updates (the OTAs, for over the air), and downloading the latest version with it. Once I set it up, I saw that 1302 only showed up as an incremental: a 119 MB package. Asking for the full version, what came up was 401, from January, at 6.09 GB. OnePlus publishes one full OTA per major version, and the rest only as patches on top of the earlier ones.
I downloaded both and moved them to the PC. The filename doesn't say which version it is (OnePlus names it after a fingerprint of its contents), but every OTA carries its details in plain text:
unzip -p OTA.zip META-INF/com/android/metadata
version_name=NE2215_15.0.0.401(EX01)
security_patch=2025-01-01
The full one was 401, as expected. The question was whether the incremental could take it from there to 1302 and rebuild its boot.img. Inside every OTA there's a file listing the partitions and, for each one, the operations to write it. I wrote a minimal reader to see those operations. In the full OTA, everything is written whole: "these bytes go here". In the incremental, almost everything is "copy this block from the old version" or "apply this patch to the old version". Both need the exact bytes of the starting version, and the incremental says which one that is: an intermediate version, not 401. Applying it on top of 401 would produce garbage, and the installer would notice, because each operation checks the blocks it reads. The 1302 boot.img can't be rebuilt from any public OTA: if I wanted it, I had to pull it off the phone itself, and that required root.
Installing 401 was also out. Going back from 1302 would mean installing an older version, and Qualcomm chips have anti-rollback: a counter stored in the chip's fuses, bits that get burned once and can't be reverted. The counter only goes up, and if you boot an old bootloader with the counter already higher, the phone can end up bricked. 401 stayed as study material. Or, maybe, as something to boot without installing.
Getting root by booting an image in RAM, without installing anything
With an unlocked bootloader you get this:
fastboot boot image.img
The bootloader receives the image over USB, loads it into RAM and boots it without writing it anywhere. If it doesn't work, you reboot and everything is back. The plan: modify the 401 boot.img with Magisk, the most widely used tool for rooting Android, boot it in RAM and, with root, copy the real 1302 boot straight off the phone.
There was a catch. The keys that encrypt the data are kept by a service called KeyMint, which runs in TrustZone: an isolated area of the processor where security software runs that neither Android nor Linux can touch. The boot.img header says which month its security patch is from, and the bootloader passes that to KeyMint. KeyMint remembers the highest level it has seen and refuses to use its keys if it goes down, so nobody can go back to a version with a known hole and pull the keys from there. My keys were created with the November 2025 patch; if I booted something claiming January, Android would probably be unable to decrypt my data.
The fix came from how that value is stored. The boot.img header has a 32-bit field, os_version: the high bits hold the Android version and the low 11 the patch level, packed as (year − 2000) << 4 | month:
(2025 - 2000) << 4 | 1 # 0x191: January 2025
(2025 - 2000) << 4 | 11 # 0x19b: November 2025
Since the year is the same, only the 4 month bits change, and those 4 bits sit in the field's least significant byte. The number is stored starting with that byte (little-endian), so it's byte 17 of the file. That's why comparing the Magisk image with the modified one showed a single difference: 0x91 → 0x9B.
Why the bootloader accepted the image is a separate question. Locked, it would have checked boot against its signature, which lives in another partition (vbmeta), and rejected it. But that signature had stopped matching before I touched the byte: Magisk had replaced the whole initial system. Unlocked, it just warns and boots whatever it's given.
Sending 'boot.img' (196608 KB) OKAY [ 4.380s]
Booting OKAY [ 0.449s]
Twelve seconds later the phone was answering adb. It was running the 401 kernel with the 1302 system, my data was decrypted and I had root. And something surprised me: a January kernel loaded 509 modules from the manufacturer built in November, and only one failed, over three functions that didn't exist in the older version. I asked Claude how that was possible, and it turns out that since Android 12 Google freezes the interface between the kernel and the manufacturers' modules (it calls this GKI). That's why you can swap one without rebuilding the other, and that single failure shows exactly where the limit is: whatever was added later.
With root I copied the real boot images from slot B, comparing each one's fingerprint on the phone and on the PC, and pulled what I couldn't get without root: the hardware description Android's kernel received at boot (39,213 lines), its boot log and the memory map. What it said:
Machine model: Qualcomm Technologies, Inc. Waipio MTP with PM8010, wly. Waipio is the name Qualcomm gives the SM8450 in its own kernel, and MTP is its test board: OnePlus built the phone from it.- The display is a 1440×3216 Samsung panel.
- The touchscreen is a Synaptics S3908. Of the three candidates, this is the one.
- The Wi-Fi is a Qualcomm chip connected over PCIe, the same kind of bus a PC's expansion cards use, and mainline has a driver for it.
adb reboot, and the phone came back to 1302 exactly as before, without root. Nothing changed in its partitions: all that was left was the Magisk app and two images in the downloads folder.
Writing my phone's device tree with the Galaxy S22's as a template
With all that I could finally write the description of my board. Not a complete one: the minimum for a first test, what these projects call first light (getting the kernel to boot and show something). The template was the Galaxy S22, whose mainline description is 145 lines covering just four things, and I filled them in with my phone's data:
- How the bootloader recognizes this description. The bootloader can carry several and picks its own by matching some numbers that identify the chip and the board. I copied them straight from Android's description.
- A borrowed display. At power-on, the bootloader draws the logo in a region of RAM that the image on the panel comes from: the framebuffer. First light doesn't need a display driver: it's enough to tell the kernel where that region is and how big it is, and let it keep writing there. The address is the same as on the S22. The resolution I don't know: the panel's default mode is 1080×2412, so that's my hypothesis. If the first boot shows a garbled image, it was something else.
- USB, as a device. So I could get into the phone from the PC over the cable, USB works in device mode, not as a host. Its physical part needs three voltages, and following them in Android's description turned up exactly the same ones as on the S22. Both boards come from Qualcomm's test board.
- The buttons. In OnePlus's description, the volume-down button is named
vol_up, but the code it sends is volume down. A copy-paste by the manufacturer. The code is what counts; in my description it's named after what it does. - Pins that aren't mine. The chip has general-purpose pins (GPIO) that software can use to read or control things. OnePlus reserves a few for TrustZone; if Linux touches them, the phone may reboot. They have to be declared so the kernel stays away.
There was one check the project's guide insists you never skip: reserved memory. The chip has several processors besides the main ones: the modem's, some specialized ones for audio and sensors, TrustZone's. Each uses its own chunk of RAM, and the hardware description has to tell the kernel which chunks it can't touch. If one is missing, the kernel uses it too and data gets corrupted without any warning. I wrote a script that compares each of Android's regions against what mainline reserves. The first version said Android had only 3 regions, which made no sense; the script was misreading the format. Once fixed, it found 39 regions and four gaps, and two of them were OnePlus-specific regions, one holding the bootloader's log. I reserved them all. Result: no gaps.
The description ended up at 228 lines, in my own copy of the kernel. It built with no warnings and says what it should:
fdtget sm8450-oneplus-wly.dtb / model # OnePlus 10 Pro
What's missing to boot Linux on the phone
A hardware description doesn't boot on its own. I still need to figure out how to hand it to the bootloader: the project's OnePlus 13 found that its bootloader doesn't accept what we need the direct way, and had to use a trick to chain two boots together. The 10 Pro's bootloader is a generation older, so maybe that won't be needed. I also need this phone's configuration in Omarchy Mobile, with slot A and the guard's list, and an initramfs that brings up networking and a console over the USB cable. And the first boot of a mainline kernel, RAM only, like the Magisk one.
So far I haven't flashed a single partition: it's all been reading, comparing and compiling, and I already understand a lot more about what sits between the kernel and the hardware than when I started. Next comes finding out whether the phone agrees.