Custom Recovery - AOSP Expert & Production Engineering

The Role of Custom Recovery in AOSP

In the Android ecosystem, the recovery partition is a specialized, standalone runtime environment separate from the main Android OS. While the stock AOSP recovery provides basic functionality like applying OTA (Over-The-Air) updates and performing factory resets, developers and enthusiasts often require more powerful tools. This is where custom recoveries, most notably TWRP (Team Win Recovery Project), come into play.

A custom recovery enables deep system modifications: flashing unsigned zip files, performing complete Nandroid backups, modifying partitions, and providing a terminal interface with root access before the main OS boots.

Understanding the TWRP Device Tree

To build TWRP for a specific device, you must create a dedicated "device tree". This tree tells the TWRP build system how to configure the recovery environment for your specific hardware.

A standard TWRP device tree includes several critical files:

BoardConfig.mk: Defines hardware architecture, partition sizes, kernel variables, and compilation flags.
Android.mk / Android.bp: Build instructions for device specific modules.
omni_<device>.mk or twrp_<device>.mk: The main product makefile that inherits TWRP dependencies.
recovery.fstab: The file system table, dictating how partitions are mounted.

Example: `recovery.fstab`

The recovery.fstab is crucial. If partitions are defined incorrectly, TWRP will not be able to mount /system, /data, or /vendor.

# mount point   fstype  device                                       flags
/boot           emmc    /dev/block/bootdevice/by-name/boot
/recovery       emmc    /dev/block/bootdevice/by-name/recovery       flags=backup=1
/system_root    ext4    /dev/block/bootdevice/by-name/system         flags=display="System";backup=1;wipeingui
/vendor         ext4    /dev/block/bootdevice/by-name/vendor         flags=display="Vendor";backup=1;wipeingui
/data           ext4    /dev/block/bootdevice/by-name/userdata       flags=encryptable=footer;length=-16384
/misc           emmc    /dev/block/bootdevice/by-name/misc

Building TWRP from Source

Building a custom recovery follows a similar structure to building AOSP, but utilizes a minimal manifest. The minimal manifest pulls only the necessary repositories (build system, bionic, core system tools) needed for recovery, omitting heavy frameworks like the UI system or telephony.

Syncing the TWRP Source

You typically start by initializing a TWRP minimal manifest repo:

# Initialize the TWRP minimal manifest
repo init -u https://github.com/minimal-manifest-twrp/platform_manifest_twrp_aosp.git -b twrp-11

# Sync the repositories
repo sync -c -j$(nproc --all) --force-sync --no-clone-bundle --no-tags

Initiating the Build

Once your device tree is placed in device/<manufacturer>/<codename>, you can start the build process:

# Setup build environment
source build/envsetup.sh

# Select your device
lunch twrp_<codename>-eng

# Build the recovery image
mka recoveryimage

The output will be a recovery.img located in out/target/product/<codename>/.

Recovery Touchscreen and Display Bring-Up

One of the most common issues when porting a custom recovery is a non-functional display or touchscreen. The recovery environment must interact with the hardware without the complex Android framework layer.

Display Bring-Up

TWRP utilizes minui, a minimal graphics library. It relies on the kernel's DRM/KMS or the legacy Framebuffer interface (/dev/graphics/fb0).

If the display is corrupted or blank, check your BoardConfig.mk for graphics flags. You may need to define specific pixel formats or disable DRM if your kernel does not support it properly.

# Example BoardConfig.mk graphics flags
TARGET_RECOVERY_PIXEL_FORMAT := "RGBX_8888"
TW_THEME := portrait_hdpi
TW_NO_SCREEN_BLANK := true

Touchscreen Bring-Up

The touchscreen driver runs in the kernel and exposes an input device node (e.g., /dev/input/event1). TWRP's input system reads from these nodes.

If the touchscreen does not work, it is usually due to one of two reasons:

Kernel Driver Missing: The touchscreen driver might be compiled as a module (.ko) in the stock ROM, but not included in the recovery kernel. You must either compile the driver inline with the recovery kernel or load the module during the recovery init phase.
Incorrect Event Routing: TWRP might not recognize the specific input event types emitted by your hardware.

To debug touchscreen issues, use the adb shell provided by the recovery:

# Watch input events in real-time to verify hardware detection
adb shell getevent

If getevent shows output when you touch the screen, the kernel driver is working. You then need to ensure TWRP maps those events correctly, potentially by adjusting TW_INPUT_BLACKLIST or providing a custom idc (Input Device Configuration) file.

Mastering custom recovery bring-up is a fundamental skill, providing the necessary safety net and low-level access required for advanced Android platform development.