All new devices launching with Android {{ androidPVersionNumber }} 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 {{ androidPVersionNumber }}, 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 {{ androidPVersionNumber }}. 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:

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

About system-as-root

In Android {{ androidPVersionNumber }}, 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_a → boot_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-{{ androidPVersionNumber }} devices).

Partition layout differences for non-A/B devices before and after Android {{ androidPVersionNumber }}:

ramdisk.img
  -/
    - init.rc
    - init
    - etc -> /system/etc
    - system/ (mount point)
    - vendor/ (mount point)
    - odm/ (mount point)
    ...

system.img
  -/
    - bin/
    - etc
    - vendor -> /vendor
    - ...

system.img
  -/
    - init.rc
    - init
    - etc -> /system/etc
    - system/
      - bin/
      - etc/
      - vendor -> /vendor
      - ...
    - vendor/ (mount point)
    - odm/ (mount point)
    ...

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:
   • https://android-review.googlesource.com/#/c/kernel/common/+/158491/
   • kernel 4.4 patches, kernel 4.9 patches, etc.

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).