Introduction: Unlocking Advanced Android Boot Customizations

The Android Open Source Project (AOSP) provides a robust framework, but its default boot process, primarily relying on a static `ramdisk.img` and `init` script, can sometimes be limiting for specialized embedded systems, custom hardware platforms, or advanced debugging scenarios. This article delves into an expert-level customization: integrating a custom Android initramfs into a Systemd-boot Unified Kernel Image (UKI). This approach offers unparalleled flexibility for early boot stage logic, allowing for bespoke services, pre-boot diagnostics, or secure boot implementations far beyond typical AOSP mechanisms.

Unified Kernel Images (UKIs) encapsulate the Linux kernel, its initial RAM disk (initramfs), and kernel command-line parameters into a single EFI executable. When combined with Systemd-boot, a lightweight EFI boot manager, UKIs streamline the boot process and enhance security. Our goal is to augment or replace the traditional AOSP initramfs with a custom, more flexible one that integrates seamlessly into a UKI environment, particularly beneficial for non-standard Android deployments or when leveraging systemd features from the very beginning.

Prerequisites for This Advanced Customization

• Basic Linux Kernel Compilation Knowledge: Understanding `menuconfig`, cross-compilation.
• Android Build Environment: Familiarity with AOSP source code structure (though we’re moving beyond it).
• Systemd-boot Setup: A working Systemd-boot installation on an EFI system.
• CPIO Archiving & Initramfs Concepts: Grasp of how initramfs works and basic CPIO manipulation.
• `systemd-ukify` Utility: Essential for building UKIs.

Understanding AOSP Initramfs vs. Custom Initramfs

AOSP’s boot process typically involves a kernel and a `ramdisk.img` which contains a minimal root filesystem, device trees, and the critical `init` binary. This `init` then pivots to the actual Android root filesystem (e.g., `/system`). While effective, `ramdisk.img` is usually generated as part of the AOSP build, making dynamic modifications for early boot logic cumbersome.

A custom initramfs, in contrast, is an independent CPIO archive that the kernel unpacks into RAM. It can contain any binaries, libraries, and scripts needed to perform specific tasks before the main root filesystem is mounted. This allows for:

• Early hardware initialization or diagnostics.
• Custom encrypted partition unlocking routines.
• Dynamic kernel command-line parameter generation.
• Integration of `systemd` as the very first PID 1, offering its extensive service management capabilities earlier in the boot process.

Crafting Your Custom Initramfs

The core of this customization lies in creating a standalone initramfs. For simplicity, we’ll build a minimal one that prints a message and then attempts to hand off control, mimicking a basic Linux initramfs flow that could eventually boot Android.

Step 1: Create the Initramfs Directory Structure

mkdir -p custom_initramfs/{bin,sbin,etc,proc,sys,dev,mnt,lib}

Step 2: Create a Minimal Init Script

This `init` script will be the first process executed by the kernel within our custom initramfs.

# custom_initramfs/init#!/bin/shMOUNTS="/proc /sys /dev"for i in $MOUNTS; do  mount -t auto $i $i;doneecho "[CUSTOM INITRAMFS] Hello from custom Android initramfs!"echo "[CUSTOM INITRAMFS] Attempting to pivot to real root..."sleep 2# Example: If you have a real root on /dev/sda1, you'd mount it here# mount /dev/sda1 /mnt# exec switch_root /mnt /sbin/init# For Android, you'd typically try to find and mount the system partition# and then execute /system/bin/init or similar. This is a placeholder.if [ -x /bin/busybox ]; then  /bin/busybox sh  # Fallback to shell if main init failselse  echo "[CUSTOM INITRAMFS] Busybox not found, cannot provide shell."  echo "[CUSTOM INITRAMFS] Initramfs finished. System will likely halt."  exec /bin/sh # Try a default shell if availablefi

Step 3: Include Essential Binaries (e.g., BusyBox)

For a functional `init` script, you’ll need basic utilities. BusyBox is an excellent choice for a minimal initramfs.

# Download and compile BusyBox (cross-compile if needed)cd busybox_source_dirmake defconfigmake && make install CONFIG_PREFIX=../custom_initramfs/cd ../custom_initramfs/bin/mv busybox .ln -sf busybox shln -sf busybox echoln -sf busybox mountln -sf busybox sleep

Ensure any required shared libraries (`libc.so`, etc.) are copied into `custom_initramfs/lib`. For cross-compilation, use your toolchain’s `sysroot` to find these.

Step 4: Create the CPIO Archive

cd custom_initramfsfind . -print0 | cpio --null -ov --format=newc > ../custom_initramfs.cpio.gzcd ..

This command creates a compressed CPIO archive named `custom_initramfs.cpio.gz` from your directory structure.

Integrating into a Unified Kernel Image (UKI)

Now, we’ll combine this custom initramfs with your Android kernel and other components into a UKI using `systemd-ukify`.

Step 1: Obtain Your Android Kernel

You’ll need a compiled Linux kernel for your Android device. This is typically `vmlinuz` or `Image` from your AOSP build output or a custom kernel build.

cp /path/to/your/android/kernel/Image.gz vmlinuz.efi

Step 2: Prepare Kernel Command-Line Parameters

Create a file (`cmdline.txt`) with your desired kernel parameters. These are crucial for Android boot.

# cmdline.txtroot=/dev/sdaX init=/sbin/init androidboot.console=ttyS0 console=ttyS0,115200 quiet rw loglevel=4# Add other necessary Android boot parameters like earlycon, msm_iommu, etc.

Step 3: Build the UKI with `systemd-ukify`

The `systemd-ukify` tool is designed for this purpose. We will append our custom initramfs.

systemd-ukify build 	--kernel=vmlinuz.efi 	--initrd=custom_initramfs.cpio.gz 	[email protected] 	--output=android-custom-boot.efi 	--os-release=/path/to/your/android/etc/os-release 	--os-image=android-13

The `–initrd` option specifies the initramfs to include. If you also have a separate `ramdisk.img` from AOSP that you need, you might need to combine them first or chain-load. For our purpose, `custom_initramfs.cpio.gz` is our *primary* initramfs.

Systemd-boot Configuration

Once you have `android-custom-boot.efi`, place it in your EFI system partition (ESP), typically `/boot/EFI/Linux/`.

Step 1: Place the UKI

sudo cp android-custom-boot.efi /boot/EFI/Linux/

Step 2: Create a Systemd-boot Entry

Create a new boot entry file, e.g., `/boot/loader/entries/android-custom.conf`.

# /boot/loader/entries/android-custom.conftitle   Android Custom UKIversion Android 13-Customlinux   /EFI/Linux/android-custom-boot.efioptions root=/dev/sdaX androidboot.console=ttyS0 console=ttyS0,115200 quiet rw loglevel=4# The 'options' line is technically redundant here because 'systemd-ukify' # embeds the cmdline directly. However, it can be used to override or add # parameters if desired, depending on systemd-ukify version/configuration.

Upon next reboot, Systemd-boot will detect this entry, and you can select