This article serves as a guide for use case of porting custom ROM to android device, using the android open source project (AOSP). If you have an older device that isn’t receiving updates anymore and you want to run the latest version of Android, a custom ROM is just the way to go. CyanogenMod is the most popular ROM for this purpose.
Reasons for custom ROM port
- Get the latest version of Android on your device, as many manufacturers do not update their old phones
- Replace Manufacturer Skin with a Stock Version of Android
- Eliminate bloatware apps (pre-installed by Carriers and Manufactures), which can clutter your system and waste disk space
- Add additional features and system tweaks like overclocking, customize settings, disable volume warning and more.
- Configure Application permissions
This document assumes that the Build environment and android sources (AOSP) are installed and configured. The developer uses the build system for building the android image from the android sources and flash the image to the device.
Refer to following document for getting additional details on procuring and establishing the android environment
Following steps describe the process involved in making a custom ROM for an Android device. Assuming the android source for interested/ latest version of Android is downloaded and build environment is configured, here are the high level tasks involved in the development process
- Adding the make files of device to the build system.
- Including the kernel sources for the device
- Building the custom ROM image and resolving the build issues
- Boot to recovery image and flashing the custom ROM
- Debugging the boot up issues, if any
Adding the make files of device to the build system
To port a new android version to the device, we need to include the device specific makefiles to android build system, Following steps describe how to set up product makefiles for a device. Nearly everything you need to do will be in the /device/[vendor]/[codename], /vendor/[vendor]/[codename], and /kernel/[vendor]/[codename] directories.
1. Create a device/<company_name>/<device_name> directory for your product.
The /device directory contains configuration settings and other code for particular devices. It is always good to adapt a directory for an existing device (look for a device that is based on the same platform) that is architecturally similar to the one you wish to port.
2. Create a device.mk Makefile that declares the files and modules needed for the device.
Here is a snapshot of the device.mk file for Samsung S4 device
LOCAL_PATH := device/samsung/i9500 # overlays DEVICE_PACKAGE_OVERLAYS += $(LOCAL_PATH)/overlay # Boot animation TARGET_SCREEN_HEIGHT := 960 TARGET_SCREEN_WIDTH := 540 # Ramdisk PRODUCT_PACKAGES += \ fstab.universal5410 \ init.universal5410.rc \ init.universal5410.usb.rc \ init.universal5410.wifi.rc \ ueventd.universal5410.rc # Recovery PRODUCT_PACKAGES += \ init.recovery.universal5410.rc
3. Create a product definition Makefile to create a specific product based on the device.
Here is the snapshot of the i9500-vendor.mk file
# Inherit from the common Open Source product configuration $(call inherit-product, $(SRC_TARGET_DIR)/product/aosp_base_telephony.mk) PRODUCT_NAME := samsung_i9500 PRODUCT_DEVICE := i9500 PRODUCT_BRAND := Android PRODUCT_MODEL := AOSP on i9500 PRODUCT_MANUFACTURER := samsung PRODUCT_RESTRICT_VENDOR_FILES := true $(call inherit-product, device/samsung/i9500/i9500.mk) $(call inherit-product-if-exists, vendor/samsung/i9500/i9500-vendor.mk) PRODUCT_NAME := samsung_i9500 PRODUCT_PACKAGES += \ Launcher3
4. Create an AndroidProducts.mk file that points to the product’s Makefiles
PRODUCT_MAKEFILES := \ $(LOCAL_DIR)/i9500.mk
5. Create a BoardConfig.mk Makefile that contains board-specific configurations.
Here is the snapshot of the BoardConfig.mk file.
LOCAL_PATH := device/samsung/i9500 BOARD_VENDOR := samsung # Include path TARGET_SPECIFIC_HEADER_PATH := $(LOCAL_PATH)/include # Bootloader TARGET_BOOTLOADER_BOARD_NAME := universal5410 TARGET_NO_BOOTLOADER := false # Platform TARGET_BOARD_PLATFORM := exynos5 TARGET_SOC := exynos5410 # Architecture TARGET_ARCH := arm TARGET_ARCH_VARIANT := armv7-a-neon TARGET_ARCH_VARIANT_CPU := cortex-a15 TARGET_CPU_ABI := armeabi-v7a TARGET_CPU_ABI2 := armeabi TARGET_CPU_VARIANT := cortex-a15 # Kernel BOARD_KERNEL_BASE := 0x10000000 BOARD_KERNEL_PAGESIZE := 2048 TARGET_KERNEL_CONFIG := i9500_defconfig
6. Create a vendorsetup.sh file to add your product (a “lunch combo”) to the build along with a build variant separated by a dash.
Here is the snapshot of vendorsetup.sh file
add_lunch_combo i9500-userdebug add_lunch_combo i9500-eng add_lunch_combo i9500-user
7. Proprietary device files should be copied from the device to the AOSP folder, the list of the files is specified here:
Including the kernel sources for the device
We can either use a pre-built kernel image or build the kernel from scratch, which can be configured by using BoardConfig.mk file under /device/vendor-name/device-name directory
Defining kernel source location:
TARGET_KERNEL_SOURCE := kernel/vendor-name/source-name
Configuring the device to build the kernel
TARGET_KERNEL_CONFIG := device-name_defconfig
If the device requires U-Boot we need to add the following in BoardConfig.mk file.
BOARD_USES_UBOOT := true
If we wish to use a pre-built kernel image, we need to need to add the following in BoardConfig.mk file.
TARGET_PREBUILT_KERNEL := device/vendor-name/device-name/kernel
Here is the snapshot of the BoardConfig.mk file
LOCAL_PATH := device/samsung/i9500 BOARD_VENDOR := samsung # Include path TARGET_SPECIFIC_HEADER_PATH := $(LOCAL_PATH)/include # Assert TARGET_OTA_ASSERT_DEVICE := ja3g,i9500,GT-I9500 # Bootloader TARGET_BOOTLOADER_BOARD_NAME := universal5410 TARGET_NO_BOOTLOADER := false # Platform TARGET_BOARD_PLATFORM := exynos5 TARGET_SOC := exynos5410 # Architecture TARGET_ARCH := arm TARGET_ARCH_VARIANT := armv7-a-neon TARGET_ARCH_VARIANT_CPU := cortex-a15
Building the custom ROM image and resolving the build issues
Android AOSP provides most of the toolchains for building the Android image. In addition to the toolchains available in the AOSP source, we need additional build packages for building the Android image, which are described in the link mentioned above in the prerequisites section.
- For building the Android image, following are the steps involved.
Setting up the build environment. (need to be at the root of android source tree)
- Setting up device specific configuration
- Build the ROM image
General errors while building the android image are
– Wrong JAVA version
For resolving we need to install the correct version of JAVA as mentioned for the android version.
– Missing files errors
Adding Kernel/feature in the config file and forgetting to add the sources. The solution is to find the missing file and supply it.
– Linking error
We may get some issues when we miss adding the dependencies. The solution is to include the dependencies in the modules’ makefile.
– Code errors
We can get these issues when there are any syntax errors in the code. The problem might be in a Java (.java) file, or in a C (.c) file, or in a C++ (.cpp) file or a header (.h) or build config files. The solution is to correct the syntax errors.
Boot to recovery image and flashing the custom ROM
After successfully building the ROM image for the device, next step is flashing the ROM image on the device. For flashing the image on the device, the device needs to boot in recovery mode. The following commands are used for flashing the ROM image on the device.
For putting the device in recovery mode:
adb reboot bootloader
For Flashing the ROM image on the device:
fastboot flashall -w
Debugging the boot up issues
Sometimes we face issues while booting the device after flashing the images. Following are some of the issues seen.
- Bootloop issue
- Display blank issue
- Camera not working
- Radio layer not working
For debugging these issues android provides some debug tools, which will enable us to debug and fix the issue. Following are the tools available for debugging purpose.
- ADB (Android Debug Bridge)
- GDB / KDB
- FASTBOOT tools
- Printk for kernel debug
This article provided a high-level overview on porting custom rom to an Android device. This guide discussed the process of porting the latest android release to existing android devices and the tools used for debugging the build and boot up issues.
- Modifying Android native framework interfaces to fix issues related to specific features on surface flinger (Display blank out issue)
- Fixing kernel issues while building
- Application development
- Porting Lollipop and Marshmallow on device which had Kit-Kat installed.