Introduction to System-as-Root (SAR)

The Android ecosystem has continuously evolved, introducing significant architectural changes to enhance security, update mechanisms, and device compatibility. One such pivotal change, introduced with Android 10 (Q) and solidified in subsequent versions, is the System-as-Root (SAR) partition layout. Prior to SAR, the system partition was a separate entity mounted at /system, while the root filesystem was provided by a ramdisk in the boot.img. With SAR, the entire system image is directly mounted as the root filesystem (/), eliminating the separate ramdisk and simplifying the partition structure by consolidating the system image directly into the root.

This shift has profound implications for anyone involved in building custom ROMs, developing Generic System Images (GSIs), or porting Android to new hardware. Understanding and correctly implementing SAR is crucial for ensuring device bootability, stability, and compatibility with the latest Android versions.

Understanding the System-as-Root Architecture

In a non-SAR setup, the boot.img contains a kernel and a ramdisk. The ramdisk provides the initial root filesystem, which then mounts the /system partition. In contrast, with SAR, the ramdisk is merged directly into the system image, which itself becomes the root. The boot.img now primarily contains the kernel and a minimal set of files (often referred to as system_root or first_stage_ramdisk) necessary to bring up the device and mount the actual system partition.

Key characteristics of SAR:

• Single Root Filesystem: The system partition is directly mounted as /.
• No Separate Ramdisk Partition: The traditional /ramdisk partition is gone. Initial boot components are part of the system image.
• A/B Updates: SAR works seamlessly with A/B update mechanisms, allowing for background updates.
• Logical Partitions (Super Partition): Devices often leverage logical partitions within a ‘super’ partition, which can dynamically resize system, vendor, product, and odm.

Changes in boot.img Structure

The boot.img for SAR devices often contains a kernel and a `first_stage_ramdisk` which is essentially a minimal ramdisk. This ramdisk’s primary job is to find and mount the super partition, activate the correct system slot (A or B), and then switch root into the `system_root` filesystem within that slot. The `init` process then continues from the `system_root`.

Adapting Custom ROMs for SAR Environments

Building a custom ROM (typically AOSP-based) for a SAR device requires specific adjustments in the device’s build configuration. These changes primarily occur in the device’s BoardConfig.mk and potentially the kernel configuration.

Build System Adjustments in BoardConfig.mk

The fundamental change involves telling the AOSP build system to create a System-as-Root compliant image. This is achieved by setting specific flags:

# Enable System-as-Root build type
BOARD_BUILD_SYSTEM_ROOT_IMAGE := true

# For devices with A/B updates, which often go hand-in-hand with SAR
BOARD_USES_SYSTEM_AS_ROOT := true

# Configure boot image packaging to combine ramdisk with system
PRODUCT_USES_SYSTEM_AS_ROOT := true

# Often, recovery is built into the boot image or dynamically mounted
# If using A/B, recovery might be part of the system update.
BOARD_USES_RECOVERY_AS_BOOT := true  # or TARGET_NO_RECOVERY := true if using dynamic recovery

# If your device uses logical partitions (Dynamic Partitions)
BOARD_SUPER_PARTITION_SIZE := <size_in_bytes> # e.g., 8589934592 for 8GB
BOARD_SUPER_PARTITION_GROUPS := <group_name>
BOARD_<group_name>_PARTITION_LIST := system vendor product # Add other logical partitions
BOARD_<group_name>_SIZE := <group_size_in_bytes>
BOARD_<group_name>_EXTFS_INODE_COUNT := -1 # Or a specific value

• BOARD_BUILD_SYSTEM_ROOT_IMAGE := true: This is the primary flag that instructs the build system to generate a system_root_image.img instead of a plain system.img and package the necessary ramdisk components within it.
• BOARD_USES_SYSTEM_AS_ROOT := true: While sometimes redundant with the above for newer AOSP versions, it explicitly declares the device’s SAR nature.
• Dynamic Partitions Configuration: If the device uses Android’s Dynamic Partitions feature (often found on SAR devices), you’ll need to define the BOARD_SUPER_PARTITION_SIZE and the logical partition groups. This ensures that the custom ROM can create the correct layout for `system`, `vendor`, `product`, etc., within the `super` partition.

Kernel and Ramdisk Adaptations

The kernel must be configured to support the SAR environment, especially related to Verified Boot (AVB) and the correct handling of logical partitions. Key kernel configuration options typically include:

• CONFIG_DM_VERITY: Device Mapper Verity for integrity checking.
• CONFIG_VERIFIED_BOOT: Related to Android Verified Boot.
• Filesystem drivers for the system partition (e.g., `EXT4`, `F2FS`).
• Required device mapper drivers (e.g., `DM_LINEAR`, `DM_SNAPSHOT`).

The initial ramdisk (or first_stage_ramdisk) contained within the boot.img must also correctly identify and mount the `super` partition and then pivot to the `system_root` image. This involves critical modifications to the fstab and init.rc files within the ramdisk. An example fstab entry for a logical system partition might look like this:

# For dynamic partitions in the super partition
/dev/block/by-name/super        /mnt/vendor/super       auto    defaults        wait,logical

# Mount system from the super partition after logical partitions are activated
/dev/block/mapper/system        /       ext4    ro,barrier=1,discard    wait,avb=vbmeta_system,slotselect,first_stage_mount

The first_stage_init process in init.rc handles the early mounting and pivot root operations. Ensure your device’s fstab correctly references the super partition and then the logical system partition for the root mount point (`/`).

Adapting GSI Projects to SAR Environments

Generic System Images (GSIs) are designed to be universally compatible with Treble-enabled devices. Since Android 10, all GSIs are built with System-as-Root in mind, meaning a standard GSI should theoretically work on any SAR-compliant device.

The primary consideration when using GSIs on SAR devices is the flashing process. Instead of flashing `system.img` to a `system` partition, you typically flash a SAR-compliant GSI (often named system-<arch>-<flavor>.img) to the device’s logical system partition within the `super` partition. This usually involves tools like `fastboot`:

# Erase old logical partitions if necessary (use with caution!)
fastboot erase system_a
fastboot erase system_b

# Resize the super partition if your GSI requires more space than allocated
# This step is highly device-specific and may require 'lpmake' or similar tools.
# For example, create a new super partition image and flash it.

# Flash the GSI to the system slot (assuming A/B)
fastboot flash system_a <path_to_gsi.img>

# Or, for devices without A/B but still using SAR logical partitions
fastboot flash system <path_to_gsi.img>

It’s crucial to confirm the exact flashing commands for your specific device model, as partition names and flashing methods can vary. Some devices might require using the `fastboot update` command with a full `payload.bin` for dynamic partitions.

Common Pitfalls and Troubleshooting

• Bootloops and `No OS found`

  This is often caused by an incorrect `fstab` entry in the ramdisk, preventing the system partition from being mounted as root. Verify paths, filesystem types, and mount flags. Incorrectly flashing the GSI (e.g., flashing `system.img` to a non-SAR device) can also lead to this.

• Verified Boot (AVB) Issues

  SAR devices heavily rely on Android Verified Boot. If your custom ROM or GSI is not properly signed with the device’s expected keys, it might refuse to boot or display a red state. Ensure you are using appropriate signing keys or have disabled AVB (not recommended for security).

  # Example for generating AVB keys
  avbtool make_image --output boot.img --kernel kernel --ramdisk ramdisk.img --partition_name boot --key path/to/boot_key.pem --algorithm SHA256_RSA2048
  

• Partition Sizing

  If you’re building a custom ROM for a device with logical partitions, ensure the sizes defined in BoardConfig.mk for the super partition and its groups (`BOARD_SUPER_PARTITION_SIZE`, `BOARD_<group>_SIZE`) are adequate and correctly configured for your device’s hardware. Incorrect sizing can lead to ‘out of space’ errors during flashing or at boot.

• Vendor Mismatch

  While GSIs aim for compatibility, a significant mismatch between the GSI’s Android version and the device’s vendor partition version can lead to crashes or instability. Always try to match the GSI’s Android version to your device’s stock vendor partition version.

Conclusion

System-as-Root represents a fundamental shift in Android’s low-level architecture, impacting how custom ROMs are built and how GSIs are integrated. By understanding the consolidated `boot.img` structure, configuring build flags like `BOARD_BUILD_SYSTEM_ROOT_IMAGE := true`, and meticulously crafting ramdisk `fstab` and `init.rc` files, developers can successfully adapt their projects to this modern Android environment. While the initial learning curve can be steep, embracing SAR is essential for staying current with Android development and maximizing device compatibility and security.