System-as-root

All new devices launching with Android 9 must use system-as-root (BOARD_BUILD_SYSTEM_ROOT_IMAGE must be true), which merges ramdisk.img into system.img, which in turn is mounted as rootfs. For devices upgrading to Android 9, system-as-root is not mandatory. This document describes system-as-root, lists kernel requirements for dm-verity support (including dependent kernel patches), and provides setup examples.

About system-only OTAs

The current Android ecosystem supports two types of partition layout:

  • In an A/B partitioning scheme, the system partition is mounted as rootfs.
  • In a non-A/B partitioning scheme, the ramdisk.img in the /boot partition is loaded into memory (which in turn is mounted as rootfs) while the system partition is mounted at /system.

System-only OTAs, in which a system.img can be updated across major Android releases without changing other partitions, are supported by the architectural changes made in Android 8.0 as part of Project Treble. However, for non-A/B devices, as ramdisk.img is in /boot partition, it cannot be updated via a system-only OTA using the Android 8.x architecture. As a result, an old ramdisk.img might not work with a new system.img for the following reasons:

  • The older /init in ramdisk.img might not be able to parse the *.rc files on /system.
  • The ramdisk contains /init.rc, which also may be out of date compared to what is required for the new /system.

To ensure system-only OTAs work as expected, system-as-root is mandatory in Android 9. Non-A/B devices must switch from ramdisk partition layout to system-as-root partition layout; A/B devices do not need to change as they already must use system-as-root.

About A/B and non-A/B devices

A/B devices and non-A/B devices have the following partition details:

A/B Devices Non-A/B Devices
Each partition (except userdata) has two copies (slots):
  • /boot_a
  • /boot_b
  • /system_a
  • /system_b
  • /vendor_a
  • /vendor_b
  • ...
Each partition has one copy, no other backup partitions.
  • /boot
  • /system
  • /vendor
  • ...

For details on A/B and non-A/B devices, refer to A/B (Seamless) System Updates.

About system-as-root

In Android 9, non-A/B devices should adopt system-as-root so they can be updated via a system-only OTA.

Unlike A/B devices that re-purpose /boot as the recovery partition, non-A/B devices must keep the /recovery partition separate as they do not have the fallback slot partition (e.g., from boot_aboot_b). If /recovery is removed on non-A/B device and made similar to the A/B scheme, recovery mode could break during a failed update to /boot partition. For this reason, the /recovery partition must be a separate partition than /boot for non-A/B devices, which implies the recovery image will continue to be updated in a deferred manner (i.e. the same as in pre-9 devices).

Partition layout differences for non-A/B devices before and after Android 9:

Component Image ramdisk (before 9) system-as-root (after 9)
Image Content boot.img Contains a kernel and a ramdisk.img:
ramdisk.img
  -/
    - init.rc
    - init
    - etc -> /system/etc
    - system/ (mount point)
    - vendor/ (mount point)
    - odm/ (mount point)
    ...
Contains a normal boot kernel only.
recovery.img Contains a recovery kernel and a recovery-ramdisk.img.
system.img Contains the following:
system.img
  -/
    - bin/
    - etc
    - vendor -> /vendor
    - ...
Contains the merged content of original system.img and ramdisk.img:
system.img
  -/
    - init.rc
    - init
    - etc -> /system/etc
    - system/
      - bin/
      - etc/
      - vendor -> /vendor
      - ...
    - vendor/ (mount point)
    - odm/ (mount point)
    ...
Partition Layout N/A
  1. /boot
  2. /system
  3. /recovery
  4. /vendor, … etc
  1. /boot
  2. /system
  3. /recovery
  4. /vendor, … etc

Setting up dm-verity

In system-as-root, the kernel must mount system.img under / (mount point) with dm-verity. AOSP supports the following dm-verity implementations for system.img:

  1. For vboot 1.0, the kernel must parse android-specific metadata on /system, then convert to dm-verity params to set up dm-verity. Requires these kernel-patches.
  2. For vboot 2.0 (AVB), the bootloader must integrate external/avb/libavb, which then parses the hashtree descriptor for /system, converts it to dm-verity params, and finally passes the params to the kernel via kernel command line. (Hashtree descriptors of /system might be on /vbmeta or on /system itself.)

    Requires the following kernel-patches:

Examples from real devices showing dm-verity related settings for system-as-root in kernel command line:

vboot 1.0

ro root=/dev/dm-0 rootwait skip_initramfs init=/init
dm="system none ro,0 1 android-verity /dev/sda34"
veritykeyid=id:7e4333f9bba00adfe0ede979e28ed1920492b40f

vboot 2.0 (AVB)

ro root=/dev/dm-0 rootwait  skip_initramfs init=/init

dm="1 vroot none ro 1,0 5159992 verity 1
PARTUUID=00000016-0000-0000-0000-000000000000
PARTUUID=00000016-0000-0000-0000-000000000000 4096 4096 644999 644999
sha1 d80b4a8be3b58a8ab86fad1b498640892d4843a2
8d08feed2f55c418fb63447fec0d32b1b107e42c 10 restart_on_corruption
ignore_zero_blocks use_fec_from_device
PARTUUID=00000016-0000-0000-0000-000000000000 fec_roots 2 fec_blocks
650080 fec_start 650080"
  

Device-specific root folders

With system-as-root, after the Generic System Image (GSI) is flashed on the device (and before running Vendor Test Suite tests), any device-specific root folders added via BOARD_ROOT_EXTRA_FOLDERS will be gone because the entire root directory content has been replaced by the system-as-root GSI. The removal of these folders might cause the device to become unbootable if a dependency on the device-specific root folders exists (e.g., they are used as mount points).

To avoid this issue, do not use BOARD_ROOT_EXTRA_FOLDERS to add device-specific root folders (it will likely be deprecated in the future). If you need to specify device-specific mount points, use /mnt/vendor/<mount point> (added in these changelists). These vendor-specific mount points can be directly specified in both the fstab device tree (for first-stage mount) and the /vendor/etc/fstab.{ro.hardware} file without additional setup (as fs_mgr will create them under /mnt/vendor/* automatically).