Custom ROM Porting Guide

A comprehensive guide on how to port a custom ROM from one Qualcomm device to another, including editing the boot image, fixing common bugs, and setting device information.

Custom ROM Porting Guide

Note:

This article explains how to adapt software from one Qualcomm-based device to another. Porting is different from compiling; it involves making two already-compiled ROMs compatible with each other.

Overview

Porting a custom ROM involves taking a ROM built for one device (the "port" or "target" ROM) and adapting it to run on your device (the "base" ROM). Compared to compiling from source, porting is often less stable initially, and you can expect to encounter bugs that need to be fixed.

The process can be broken down into three main stages: A) Getting it to Boot B) Fixing Bugs C) Finalizing Device Information

Requirements

  1. Your Device and a compatible custom/stock ROM for it (the Base ROM).
  2. A Target Device and its custom/stock ROM (the Port ROM). The devices should have the same or a very similar SoC (e.g., both Snapdragon 730).
  3. NotePad++ or a similar advanced text editor.
  4. 7-Zip or WinRAR.
  5. Android Image Kitchen (AIK) to unpack and repack boot images.
  6. A Windows or Linux computer.
  7. Tools to unpack/repack system images (e.g., system.new.dat.br to system.img).

Note:

The Android versions of the Base and Port ROMs must be the same, otherwise, you will face kernel incompatibilities and the ROM will not boot.

Understanding the ROM ZIP Structure

  • firmware-update: Contains device-specific hardware images. You must delete this folder from the Port ROM. Flashing firmware from another device will hard brick your phone.
  • META-INF: Contains the updater-script, which tells the TWRP recovery what to do. We will edit this file.
  • system.new.dat.br, system.patch.dat, system.transfer.list: This is the modern way system partitions are packaged. You will need tools to convert this to a system.img file before you can modify it.
  • vendor: Contains hardware integration files for things like sensors, GPS, etc. If the Android versions are the same, you can often use your device's vendor image and delete the one from the port ROM.
  • boot.img: The core image that integrates the software with your hardware to start the system. We will heavily modify this.

A) Getting the ROM to Boot: Editing boot.img and updater-script

1. Prepare Your Workspace

Create two folders on your desktop: "Base" and "Port". Extract the contents of the Android Image Kitchen zip into both folders.

2. Unpack the Boot Images

  • Place your device's boot.img (from your Base ROM) into the "Base" folder.
  • Place the target device's boot.img (from the Port ROM) into the "Port" folder.
  • In both folders, drag the boot.img file onto unpackimg.bat. This will create a split_img folder and a ramdisk folder.

3. Modify the Port boot.img

  • From the "Base/split_img" folder, copy the boot.img-zImage and boot.img-dtb files.
  • Paste and replace these files inside the "Port/split_img" folder.
  • Open the fstab.qcom file from both the "Base/ramdisk" and "Port/ramdisk" folders with Notepad++.
  • In the Port's fstab.qcom, delete all lines between /dev/block/bootdevice (inclusive) and /device(s) (exclusive). Replace them with the corresponding lines from your Base's fstab.qcom. If this fails, try replacing the entire fstab.qcom file.

4. Repack the Boot Image

  • In the "Port" folder, run the repackimg.bat script. It will create a file named image-new.img.
  • Rename image-new.img to boot.img.
  • Replace the original boot.img in your Port ROM's zip file with this newly created one.

5. Edit the updater-script

  • Inside the Port ROM zip, navigate to META-INF/com/google/android/ and open updater-script.
  • Look for lines that perform device checks, like getprop("ro.product.device") == "davinci". Delete these lines to prevent TWRP from aborting the installation on your device.

Now, try flashing the ROM. If it doesn't boot, compare files like init.rc, uneventd.rc, and file_contexts between the Base and Port ramdisks and merge any missing lines from Base to Port.

B) Fixing Common Bugs

Once the ROM boots, you will likely face bugs. The general strategy is to replace system files in the Port ROM with files from your Base ROM. You will need to unpack the system image to do this.

  • Sensors: Replace sensor-related libraries in system/lib/hw/, system/lib64/hw/, and lib/ and lib64/ (e.g., sensors.msmxxxx.so, libsensorservice.so).
  • Audio: Replace audio libraries in system/lib/hw/ and system/lib64/hw/ (e.g., audio.primary.msmxxxx.so).
  • Headphones/Earpiece: Replace system/etc/mixer_paths.xml.
  • Buttons: Replace key layout files in system/usr/keylayout/ (e.g., gpio-keys.kl).
  • Video Playback: Replace all files starting with venus. in system/etc/firmware/.
  • Vibration: Replace libhardware_legacy.so in system/lib/ and system/lib64/.
  • Wi-Fi: Replace wlan.ko in system/lib/modules/ and libwcnss_qmi.so in system/lib/ and system/lib64/.

Note:

Make changes one at a time and test if the ROM still boots. If it doesn't, revert the last change.

C) Finalizing Device Information

The final step is to edit the build.prop file located in the system directory of your ROM.

  • Open system/build.prop with a text editor.
  • Find properties like ro.product.brand= and ro.product.model= and change their values to match your device.
  • You can also change the default language and region here (e.g., change ro.product.locale.language=en to tr).

After making these changes, repack your system image, put it back into the zip, and you're done!