Bitácora de Código

Cómo empecé a portar Omarchy a mi OnePlus 10 Pro

16 NOV 2026

Anécdotas
omarchylinuxandroidhardwarekerneldevice treeexperimentos

Conozco Linux como sistema operativo, pero el kernel siempre fue otro mundo. Para entender cómo se encuentran el hardware y el software, quiero correr Omarchy en un OnePlus 10 Pro que nadie ha portado. Primera parte: preparar todo y aprender lo básico sin flashear nada.

Siempre me ha gustado entender por qué las cosas funcionan como funcionan. No me basta con que algo sirva: quiero abrirlo, ver qué piezas tiene y cómo se hablan entre ellas. Muchos de mis proyectos empezaron así, más por curiosidad que por necesidad.

Con Linux me pasa algo curioso. Lo uso todos los días, en una PC que armé yo mismo y que corre Omarchy, y a nivel de sistema operativo me muevo bien: paquetes, servicios, configuración, la terminal. Pero el kernel, la parte del sistema que habla directamente con el hardware, es otro mundo, uno al que no le presto tanta atención como debería. En una computadora es casi transparente: el kernel descubre el hardware por su cuenta, y los problemas que me tocaba enfrentar eran más bien drivers que no existían o no eran compatibles. Nunca me había asomado a lo que pasa debajo: cómo sabe el kernel qué hardware tiene, qué ocurre entre que presionas el botón de encendido y aparece algo en pantalla, dónde se encuentran exactamente el software y los chips.

La idea llegó un día scrolleando en X. Alguien compartió Omarchy Mobile: Omarchy de verdad, con Arch Linux y Hyprland, corriendo en un teléfono sin Android debajo. No una app ni un Linux encerrado dentro de Android: el teléfono arrancando Linux directamente. Y no cualquier Linux, sino el kernel mainline, que es como se le dice al kernel oficial que mantiene la comunidad, en lugar de la versión modificada que cada fabricante mete en sus teléfonos. Me pareció interesante, pero como casi siempre con estos proyectos, limitado a teléfonos Pixel y poco más. Hasta que vi un OnePlus en la lista, y eso me dio un poco de esperanza.

Tuve que pelearme un rato con el síndrome del impostor, pero la curiosidad pudo más y dije: ¿por qué no? Tengo un OnePlus 10 Pro (modelo NE2215) que ya no es nuevo, pero tiene 12 GB de RAM y 256 GB de almacenamiento. Debería alcanzar para correr un sistema operativo completo sin tanto problema. Así empezó esto, y Omarchy en el teléfono se volvió el pretexto: lo que de verdad busco es entender las entrañas, todo lo que hace que un pedazo de hardware y un pedazo de software terminen funcionando juntos. Un teléfono es buen lugar para eso, porque ahí casi nada es genérico: cada modelo necesita que alguien describa su hardware pieza por pieza. A eso, adaptar un sistema a un dispositivo concreto, se le llama hacer un port.

Tampoco lo hago solo. Hace unos meses escribí que tal vez la IA sí haga que este sea el año de Linux, porque los agentes abaratan diagnosticar sus excepciones, y un teléfono es probablemente la excepción más grande que hay. Así que esto también es una forma de comprobarlo: lo estoy haciendo junto con Claude Code. Yo conecto cables, presiono botones, decido y pregunto por qué; el agente lee los repos, escribe scripts y me explica lo que va apareciendo. Casi todo lo que cuento aquí lo entendí así, preguntando.

Tal vez la IA sí haga que este sea el año de Linux

Tal vez la IA sí haga que este sea el año de Linux

Linux ya funcionaba en casi cualquier computadora; el problema eran las excepciones. Omarchy, los agentes y las skills están abaratando diagnosticarlas.

Lo primero fue averiguar si era viable. Casi todo lo de aquí es nuevo para mí, así que la serie sigue el orden en que fui descubriendo las cosas, incluidas las que al principio entendí mal. Esta primera entrada cuenta la primera etapa del experimento: averiguar qué tan lejos estaba el teléfono de poder correr Omarchy y preparar todo para intentarlo. En toda esa etapa respeté un límite: no flasheé ninguna partición del teléfono: no instalé el port ni escribí ninguna de las imágenes que el teléfono usa para arrancar. Su almacenamiento sí cambió por otras razones, y las voy a ir contando: desbloquearlo lo borró, y más adelante le instalé una app.

Las reglas de Omarchy Mobile para no dañar el teléfono

Omarchy Mobile tiene dos repositorios: uno con las herramientas para compilar e instalar el sistema y con notas de cada teléfono soportado, y otro con el kernel, organizado para poder proponer sus cambios al kernel oficial (a eso se le llama mandar parches a upstream). El teléfono de referencia es el Pixel 7 Pro, casi todos los demás son Pixels, y hay unos pocos con chips Qualcomm, como el mío: el OnePlus 13 y el OnePlus 6.

Lo primero que leí fue cómo el proyecto evita romper el teléfono, y para entenderlo tuve que aprender cómo está organizado por dentro.

El almacenamiento de un teléfono está dividido en particiones, como el disco de una PC, solo que son muchas más: decenas. Una guarda el sistema, otra tus datos (userdata), otras el firmware del módem, la calibración de las antenas, el programa que arranca el teléfono… Las que hacen falta para arrancar existen dos veces, en dos juegos idénticos llamados slots A y B. Así Android puede actualizarse en el juego que no está usando mientras sigue funcionando en el otro.

Omarchy Mobile aprovecha eso:

  • Android se queda intacto en un slot, como camino de regreso, y Omarchy usa el otro.
  • Solo escribe las particiones de arranque de su slot y userdata. Nunca el bootloader (el programa que corre al encender, antes que cualquier sistema), ni el módem, ni las particiones de calibración.
  • Al arrancar, antes de llegar al sistema de verdad, el kernel carga en RAM un sistema mínimo llamado initramfs. El de Omarchy Mobile trae un guardia: deja todo el almacenamiento en solo lectura, salvo una lista explícita de particiones.
  • Antes de tocar nada, se respaldan las particiones del módem, porque ahí vive el IMEI (el número que identifica al teléfono ante la red celular) y la calibración de radio, que no se pueden reponer.

Es un proyecto que asume que te vas a equivocar y se prepara para eso. Me gustó.

Qué partes de mi teléfono ya conoce el kernel de Linux

El corazón de un teléfono es un SoC (system on a chip): un solo chip que junta los procesadores, la GPU, el módem, los controladores de memoria y de almacenamiento y muchísimo más. El del 10 Pro es un Snapdragon 8 Gen 1, que para el kernel se llama SM8450. OnePlus le dio al teléfono el nombre en clave wly.

No encontré a nadie que hubiera portado este teléfono. Pero el chip sí está en mainline: el kernel ya sabe manejar el SM8450, porque lo usan otros teléfonos, como el Galaxy S22 y un par de Xperia, además de las placas de prueba de Qualcomm.

Aquí entendí la primera diferencia importante. Para que el kernel sepa qué hardware hay, alguien se lo tiene que describir en un archivo, el device tree (le dedico la siguiente entrada). Esa descripción está partida en dos. Una parte describe lo que viene dentro del chip: procesadores, controladores, relojes. Esa ya existe, porque el chip es el mismo en todos estos teléfonos. La otra describe lo que el fabricante soldó alrededor del chip: la pantalla, el táctil, la batería, qué voltaje recibe cada pieza, qué pin va a qué. Esa cambia en cada teléfono, y es justo la que me toca escribir.

Que el chip esté soportado no significa que el teléfono arranque. Pero significa que no empiezo desde cero absoluto.

Preparar la PC y compilar el kernel antes de tocar el teléfono

En la PC instalé las herramientas para hablar con el teléfono: adb, que habla con él cuando Android está corriendo, y fastboot, que habla con el bootloader cuando el teléfono está en un modo especial de arranque. También algunas para abrir las imágenes de Android y una para extraer particiones de los paquetes de actualización de OnePlus. Esa última hace falta porque OnePlus, a diferencia de Google, no publica imágenes de fábrica de sus teléfonos: lo único oficial son las actualizaciones.

El proyecto trae un script que baja el compilador exacto con el que se compilan todos sus kernels, el mismo que usa Google para Android, y verifica cada pieza antes de usarla. Antes de tocar el teléfono quise comprobar que todo funcionaba: compilar el kernel del proyecto sin cambios, dentro de un contenedor de Docker.

bash
bin/omamobile kernel

Las dos primeras veces ni arrancó: una por mandar el registro de la compilación a una carpeta que no existía y otra porque a Omarchy le faltaba un comando que el script daba por hecho. La tercera tardó 4 minutos 39 segundos y produjo el kernel (15 MB), 1827 módulos y las descripciones de hardware de los teléfonos con SM8450 que ya existen. Lección barata: revisar el registro antes de pensar que el kernel falló.

Lo de los módulos fue lo primero que aprendí del kernel por dentro. Cada driver se puede compilar de dos formas: dentro del kernel (=y en su configuración), disponible desde el primer instante, o como módulo (=m), un archivo aparte que se carga después, cuando hace falta. En la configuración, los drivers de los pines, los relojes y los buses internos del SM8450 estaban dentro, porque todo lo demás depende de ellos. El del almacenamiento, en cambio, era módulo. El almacenamiento interno del teléfono es un chip de memoria tipo UFS, y el sistema Arch iba a vivir ahí, en userdata. O sea, el initramfs tendría que cargar ese módulo antes de poder abrir el sistema. Nunca había visto tan claro para qué existe el initramfs.

Qué se puede saber de un teléfono Android sin permisos de root

El siguiente paso fue conectar el teléfono y sacarle toda la información posible sin cambiar nada. Android no te da permisos de administrador (lo que se llama root), así que solo podía ver lo que el sistema deja ver a cualquiera. El proyecto trae un comando que junta todo eso:

bash
bin/omamobile capture wly-stock

Lo guarda fuera de cualquier repositorio, porque incluye el número de serie, el IMEI y las direcciones de red del teléfono. A la primera se cortó a la mitad: Android no deja leer cierto archivo sin root, el script fallaba ahí y se detenía. Completé a mano lo que faltaba.

Lo que salió:

DatoValor
ChipSM8450
Procesadores8 núcleos de tres tipos: 4 de eficiencia, 3 de rendimiento y 1 más potente
RAM12 GB
AlmacenamientoUFS, en la dirección 1d84000
SoftwareOxygenOS 15 (versión 1302), Android 15
Slot activoB

Ese 1d84000 es la dirección de memoria donde vive el controlador del almacenamiento, y es la misma que declara la descripción del SM8450 en mainline. Primera confirmación de que lo que ya existe en el kernel describe este chip.

El slot activo era un problema. Omarchy Mobile asume que Android vive en el slot A y que él solo escribe en el B. En mi teléfono Android estaba corriendo en el B: seguir la receta al pie de la letra habría borrado el Android que funciona. Tocaba elegir entre mover Android al slot A (una actualización siempre se instala en el slot que no se está usando) o invertir la regla para este teléfono.

También apareció algo del almacenamiento que no sabía: un chip UFS no se presenta como un solo disco, sino como varios. Se dividen en unidades lógicas, o LUNs, y Linux ve cada una como un disco aparte (sda, sdb, sdc…), cada uno con sus propias particiones. En este teléfono, las particiones de arranque y userdata viven en LUNs distintos. Eso importa, porque el guardia de Omarchy Mobile solo deja escribir en el primero, así que para él no basta con saber el nombre de una partición: también importa en qué disco está.

Sin root no podía ver la descripción del hardware que usa Android, pero la lista de drivers del fabricante (373 módulos) daba pistas: tres posibles controladores táctiles (OnePlus usa el mismo software para varias versiones del teléfono, con piezas distintas), el driver del chip de Wi-Fi, el de audio, el cargador de OnePlus y, de curiosidad, un emisor infrarrojo.

Antes de seguir hice un respaldo, porque el siguiente paso borraba el teléfono. Copié fotos, documentos y descargas con adb, que conserva las fechas de los archivos: 12 942 archivos, 2.5 GB, comparados carpeta por carpeta y con una suma de verificación de cada uno al lado.

Por qué desbloquear el bootloader borra el teléfono

De fábrica, el bootloader está bloqueado: solo arranca software firmado por el fabricante. Para arrancar un kernel propio hay que desbloquearlo. Activé la opción en los ajustes de desarrollador y reinicié en fastboot, el modo del bootloader que recibe órdenes por USB. En los teléfonos Qualcomm, ese bootloader se llama ABL.

fastboot getvar all le pregunta al bootloader todo lo que sabe de sí mismo: 282 líneas. La importante fue esta:

text
slot-unbootable:a: yes

El slot A estaba marcado como no arrancable. Cuando una actualización se instala en el slot inactivo y arranca bien, el slot viejo queda así. En mi teléfono, el camino de regreso es el B, con Android funcionando, y el A no sirve para nada. Eso resolvió la duda de antes: en lugar de mover Android, lo más limpio es invertir la regla para este teléfono (el OnePlus 13 del proyecto ya tiene una opción para eso) y escribir solo en el A.

El mismo comando decía que la batería marcaba unos 7.66 V. Un teléfono normal anda en 3.8 V; el 10 Pro usa dos celdas en serie, y eso es lo que permite su carga rápida (65 W en el NE2215, la versión de Norteamérica; la global llega a 80 W). Un dato para cuando toque el cargador.

bash
fastboot flashing unlock

Advertencia en pantalla, botones de volumen, botón de encendido, y el teléfono se borró solo. No es un capricho: los datos del teléfono van cifrados, y las llaves dependen de que el arranque sea el verificado por el fabricante. Si el bootloader dejara arrancar código sin firmar sin borrar nada, cualquiera con el teléfono en la mano podría cargar un sistema modificado y atacar tus datos. El bootloader también reporta ese cambio: el estado de verificación del arranque pasó de green (todo firmado y verificado) a orange (desbloqueado). El slot y la versión de Android no cambiaron.

OnePlus distribuye actualizaciones completas y parches incrementales

Para tener root, la forma habitual es modificar la imagen de arranque de Android: el archivo boot.img, que contiene el kernel y un pequeño sistema inicial. Necesitaba la de mi versión exacta, la 1302, y OnePlus no la publica. Claude me sugirió Oxygen Updater, una app que consulta los servidores de OnePlus y da los enlaces oficiales de sus actualizaciones (las OTA, por over the air), y bajar con ella la última versión. Al configurarla vi que la 1302 solo aparecía como incremental: un paquete de 119 MB. Al pedir la versión completa, la que apareció fue la 401, de enero, con 6.09 GB. OnePlus publica una OTA completa por versión mayor, y las siguientes solo como parches sobre las anteriores.

Bajé las dos y las pasé a la PC. El nombre del archivo no dice qué versión es (OnePlus lo nombra con una huella de su contenido), pero cada OTA trae sus datos en texto plano:

bash
unzip -p OTA.zip META-INF/com/android/metadata
text
version_name=NE2215_15.0.0.401(EX01)
security_patch=2025-01-01

La completa era la 401, como esperaba. La pregunta era si la incremental servía para llegar de ahí a la 1302 y reconstruir su boot.img. Dentro de cada OTA hay un archivo con la lista de particiones y, para cada una, las operaciones para escribirla. Escribí un lector mínimo para ver esas operaciones. En la completa, todo se escribe entero: "estos bytes van aquí". En la incremental, casi todo es "copia este bloque de la versión vieja" o "aplica este parche a la versión vieja". Las dos operaciones necesitan los bytes exactos de la versión de partida, y la incremental dice cuál es: una versión intermedia, no la 401. Aplicarla sobre la 401 daría basura, y el instalador se daría cuenta, porque cada operación comprueba los bloques que lee. El boot.img de la 1302 no sale de ninguna OTA pública: si lo quería, tenía que sacarlo del propio teléfono, y para eso hacía falta root.

Tampoco había que instalar la 401. Volver de la 1302 sería instalar una versión vieja, y los chips Qualcomm tienen anti-rollback: un contador grabado en fusibles del chip, unos bits que se queman una vez y no se pueden revertir. El contador solo sube, y si arrancas una versión vieja del bootloader con el contador más alto, el teléfono puede quedar inservible. La 401 se quedaba como material de estudio. O, quizá, como algo para arrancar sin instalar.

Conseguir root arrancando una imagen en RAM, sin instalar nada

Con el bootloader desbloqueado existe esto:

bash
fastboot boot imagen.img

El bootloader recibe la imagen por USB, la carga en RAM y la arranca sin escribirla en ningún lado. Si no funciona, reinicias y vuelve todo como estaba. El plan: modificar el boot.img de la 401 con Magisk, la herramienta más usada para tener root en Android, arrancarlo en RAM y, ya con root, copiar el boot real de la 1302 directo del teléfono.

Había un detalle. Las llaves que cifran los datos las guarda un servicio llamado KeyMint, que corre en TrustZone: una zona aislada del procesador, donde corre software de seguridad que ni Android ni Linux pueden tocar. La cabecera del boot.img dice de qué mes es su parche de seguridad, y el bootloader se lo pasa a KeyMint. KeyMint recuerda el nivel más alto que ha visto y se niega a usar sus llaves si baja, para que nadie pueda volver a una versión con un agujero conocido y desde ahí sacarlas. Mis llaves se crearon con el parche de noviembre de 2025; si arrancaba algo que dijera enero, Android probablemente no podría descifrar mis datos.

La solución salió de cómo está guardado ese dato. En la cabecera del boot.img hay un campo de 32 bits, os_version: los bits altos guardan la versión de Android y los 11 bajos el nivel de parche, empaquetado como (año − 2000) << 4 | mes:

python
(2025 - 2000) << 4 | 1    # 0x191: enero de 2025
(2025 - 2000) << 4 | 11   # 0x19b: noviembre de 2025

Como el año es el mismo, solo cambian los 4 bits del mes, y esos 4 bits caen en el byte menos significativo del campo. El número se guarda empezando por ese byte (little-endian), así que es el byte 17 del archivo. Por eso, al comparar la imagen de Magisk con la modificada, había una sola diferencia: 0x91 → 0x9B.

Que el bootloader aceptara la imagen así tiene otra explicación. Bloqueado, habría comparado boot contra su firma, que vive en otra partición (vbmeta), y la habría rechazado. Pero esa firma ya no coincidía desde antes de tocar el byte: Magisk había reemplazado el sistema inicial completo. Desbloqueado, solo avisa y arranca lo que le den.

text
Sending 'boot.img' (196608 KB)   OKAY [  4.380s]
Booting                          OKAY [  0.449s]

A los 12 segundos el teléfono respondía a adb. Corría el kernel de la 401 con el sistema de la 1302, mis datos estaban descifrados y tenía root. Y algo me sorprendió: un kernel de enero cargó 509 módulos del fabricante compilados en noviembre, y solo falló uno, por tres funciones que no existían en la versión vieja. Le pregunté a Claude cómo era posible, y resulta que desde Android 12 Google congela la interfaz entre el kernel y los módulos de los fabricantes (lo llama GKI). Por eso se puede cambiar uno sin recompilar los otros, y ese único fallo muestra justo el límite: lo que se agregó después.

Con root copié las imágenes de arranque reales del slot B, comparando la huella de cada una en el teléfono y en la PC, y saqué lo que sin root no podía: la descripción del hardware que recibió el kernel de Android al arrancar (39 213 líneas), su registro de arranque y el mapa de memoria. Lo que dijo:

  • Machine model: Qualcomm Technologies, Inc. Waipio MTP with PM8010, wly. Waipio es el nombre que Qualcomm le da al SM8450 en su propio kernel, y MTP es su placa de pruebas: OnePlus construyó el teléfono a partir de ella.
  • La pantalla es un panel Samsung de 1440×3216.
  • El táctil es un Synaptics S3908. De los tres candidatos, este es el bueno.
  • El Wi-Fi es un chip Qualcomm conectado por PCIe, el mismo tipo de bus de las tarjetas de una PC, y mainline tiene driver para él.

adb reboot, y el teléfono volvió a la 1302 tal cual, sin root. No cambió nada en sus particiones: lo único que quedó fue la app de Magisk y dos imágenes en la carpeta de descargas.

Escribir el device tree de mi teléfono con el del Galaxy S22 como plantilla

Con todo eso ya podía escribir la descripción de mi placa. No una completa: el mínimo para una primera prueba, lo que en estos proyectos se llama primera luz (que el kernel arranque y se vea algo). La plantilla fue el Galaxy S22, que en mainline tiene una descripción de 145 líneas con solo cuatro cosas, y las llené con los datos de mi teléfono:

  • Cómo reconoce el bootloader esta descripción. El bootloader puede llevar varias y elige la suya comparando unos números que identifican al chip y a la placa. Los copié tal cual de la descripción de Android.
  • La pantalla, prestada. Al encender, el bootloader dibuja el logo en una zona de la RAM de donde sale la imagen que muestra el panel: el framebuffer. Para una primera luz no hace falta un driver de pantalla: basta con decirle al kernel dónde está esa zona y cuánto mide, y que siga escribiendo ahí. La dirección es la misma que en el S22. La resolución no la sé: el modo por defecto del panel es 1080×2412, así que esa es mi hipótesis. Si en el primer arranque la imagen sale rayada, era otra.
  • El USB, como dispositivo. Para poder entrar al teléfono desde la PC por el cable, el USB funciona en modo dispositivo, no como anfitrión. Su parte física necesita tres voltajes, y al seguirlos en la descripción de Android salieron exactamente los mismos que en el S22. Las dos placas vienen de la placa de pruebas de Qualcomm.
  • Los botones. El de bajar volumen, en la descripción de OnePlus, se llama vol_up, pero el código que manda es el de bajar volumen. Un copy-paste del fabricante. Lo que cuenta es el código; en mi descripción se llama como lo que hace.
  • Pines que no son míos. El chip tiene pines de propósito general (GPIO) que el software puede usar para leer o controlar cosas. OnePlus le reserva unos cuantos a TrustZone; si Linux los toca, el teléfono puede reiniciarse. Hay que declararlos para que el kernel no se acerque.

Había una comprobación que la guía del proyecto insiste en no saltarse: la memoria reservada. El chip tiene varios procesadores además de los principales: el del módem, unos procesadores especializados para audio y sensores, el de TrustZone. Cada uno usa su propio pedazo de RAM, y la descripción del hardware tiene que decirle al kernel cuáles no puede tocar. Si falta uno, el kernel lo usa también y los datos se corrompen sin ningún aviso. Escribí un script que compara cada región de Android con lo que reserva mainline. La primera versión dijo que Android tenía solo 3 regiones, lo cual no tenía sentido; el script leía mal el formato. Corregido, salieron 39 regiones y cuatro huecos, y dos eran regiones propias de OnePlus, una con el registro del bootloader. Las reservé todas. Resultado: ningún hueco.

La descripción quedó en 228 líneas, en mi propia copia del kernel. Compiló sin avisos y dice lo que tiene que decir:

bash
fdtget sm8450-oneplus-wly.dtb / model   # OnePlus 10 Pro

Qué falta para arrancar Linux en el teléfono

Una descripción del hardware no arranca sola. Falta averiguar cómo dársela al bootloader: el OnePlus 13 del proyecto descubrió que el suyo no acepta lo que necesitamos por la vía directa, y tuvo que usar un truco para encadenar dos arranques. El bootloader del 10 Pro es de una generación anterior, así que quizá no haga falta. También falta la configuración de este teléfono en Omarchy Mobile, con el slot A y la lista del guardia, y un initramfs que levante red y consola por el cable USB. Y falta el primer arranque de un kernel mainline, solo en RAM, como el de Magisk.

Hasta aquí no flasheé ninguna partición: todo fue leer, comparar y compilar, y ya entiendo bastante más de lo que hay entre el kernel y el hardware que cuando empecé. Lo siguiente es ver si el teléfono está de acuerdo.