Generic System Images

A generic system image (GSI) is a system image with adjusted configurations for Android devices. It's considered a pure Android implementation with unmodified Android Open Source Project (AOSP) code that any Android device running Android 8.1 or higher can run successfully.

GSIs are used for running VTS and CTS-on-GSI tests. The system image of an Android device is replaced with a GSI then tested with the Vendor Test Suite (VTS) and the Compatibility Test Suite (CTS) to ensure that the device implements vendor interfaces correctly with the latest version of Android.

To get started with GSIs, review the following sections for details on GSI configurations (and allowed variances), types (Android GSI and Legacy GSI), and vendor binaries and VNDK dependencies. When you're ready to use a GSI, download and build the GSI for your device target, then flash the GSI to an Android device.

GSI configuration and variances

The current Android GSI has the following configuration:

  • Treble. The GSI includes full support for the HIDL-based architectural changes (also known as Treble) introduced in Android 8.0, including support for the HIDL interfaces. You can use the GSI on any Android device that uses HIDL vendor interfaces. (For more details, see Architecture resources.)
  • Verify boot. The GSI doesn't include a verify boot solution (such as vboot 1.0 or AVB). To flash the GSI to an device launching on Android 9 or earlier, the device must have a method for disabling verify boot.
  • File system. The GSI uses the ext4 file system.
  • Partition layout. The GSI uses system-as-root partition layout.

The current Android GSI includes the following major variances:

  • CPU architecture. Support for different CPU instructions (ARM, x86, etc.) and CPU bitness (32 bit or 64 bit).

GSI targets for Treble compliance tests

The GSI used for compliance testing is determined by the Android version that the device launches with.

Device type Build target
Devices launching with Android 10 aosp_$arch-user
Devices launching with Android 9 aosp_$arch-userdebug
Devices launching with Android 8.0 or Android 8.1 aosp_$arch_ab-userdebug

All GSIs are built from the Android 10 codebase, and each CPU architecture has a corresponding GSI binary (see the list of build targets in Building GSIs).

Android 10 GSI changes

Devices launching with Android 10 must use Android 10 GSIs for compliance testing. This includes the following major changes from earlier GSIs:

  • User build. GSI has user build from Android 10. In Android 10, the user build GSI can be used in CTS-on-GSI/VTS compliance testing. Reference VTS Testing with Debug Ramdisk for the detail.
  • Unsparsed format. GSI with targets aosp_$arch are built with unsparsed format. You can use img2simg to convert an unsparsed GSI to sparse format if necessary.
  • System-as-root. The legacy GSI build target named aosp_$arch_a had been phased out. For the devices upgraded from Android 8 or 8.1 to Android 10 with ramdisk and non-system-as-root, use the legacy GSI aosp_$arch_ab. The upgraded init in ramdisk supports OEM system.img with system-as-root layout.

To test devices launching on Android 9 or 10 with CTS-on-GSI, use the Android GSI build targets.

Legacy GSI

Legacy GSIs named with the suffix _ab (for example, aosp_arm64_ab). These GSIs are built from the Android 10 source tree but contain the following backward-compatible configurations for devices upgraded from Android 8 or 8.1:

  • 32-bit userspace + 32-bit binder interface. 32-bit GSIs can continue to use the 32-bit binder interface.
  • 8.1 VNDK. Devices can use the included 8.1 VNDK.
  • Mount directories. Some legacy devices use directories as mount pointers (for example, /bluetooth, /firmware/radio, and /persist).

To test devices launching on Android 8 or 8.1 with CTS-on-GSI, use the Legacy GSI build targets.

Android 9 GSI changes

Android 9 GSIs include the following major changes from earlier GSIs:

  • Merges GSI and emulator. GSIs are built from the system images of emulator products, for example, aosp_arm64 and aosp_x86.
  • System-as-root. In previous versions of Android, devices that didn't support A/B updates could mount the system image under the /system directory. In Android 9, the root of the system image is mounted as the root of the device.
  • 64-bit binder interface. In Android 8.x, 32-bit GSIs used the 32-bit binder interface. Android 9 doesn't support the 32-bit binder interface, so both 32-bit GSIs and 64-bit GSIs use the 64-bit binder interface.
  • VNDK enforcement. In Android 8.1, VNDK was optional. Starting from Android 9, VNDK is mandatory, so BOARD_VNDK_VERSION must be set.
  • Compatible system property. Android 9 enables the access check for a compatible system property (PRODUCT_COMPATIBLE_PROPERTY_OVERRIDE := true).

Android 9 Keymaster changes

In earlier versions of Android, devices implementing Keymaster 3 or lower were required to verify that the version info (ro.build.version.release and ro.build.version.security_patch) reported by the running system matched the version info reported by bootloader. Such information was typically obtained from the boot image header.

In Android 9 and higher, this requirement has changed to enable vendors to boot a GSI. Specifically, Keymaster shouldn't perform verification because the version info reported by the GSI may not match the version info reported by vendor's bootloader. For devices implementing Keymaster 3 or lower, vendors must modify the Keymaster implementation to skip verification (or upgrade to Keymaster 4). For details on Keymaster, refer to Hardware-backed Keystore.

Vendor binaries and VNDK dependencies

Devices upgrading to Android 10 have different upgrade paths depending on the version of vendor binaries in use on the device and the VNDK-related configurations used to build the device. The following table summarizes the legacy GSI support for upgraded devices.

Use case Vendor
binaries
version		 BOARD_VNDK_VERSION Legacy GSI
system binaries version		 Legacy GSI support
0 8.0 (any) 10 No
1 8.1 (empty) 10 No
2 8.1 current 10 Yes
3 10 current 10 Yes

The most common supported use case is #2, where the legacy GSIs support devices running Android 8.1 that were built with BOARD_VNDK_VERSION set to current.

The case #1 isn't supported. In this case, the legacy GSIs do NOT support devices running Android 8.1 where BOARD_VNDK_VERSION is omitted from the build. These devices can't be supported because their vendor binaries depend on Android 8.1 non-VNDK shared libraries, which aren't included in legacy GSIs. To make these devices compatible with a legacy GSI, you must do one of the following:

  • Enable BOARD_VNDK_VERSION without BOARD_VNDK_RUNTIME_DISABLE (use case #2).

    OR

  • Port/upgrade the vendor binaries to depend on the shared libraries from Android 10 (use case #3).

Downloading GSIs

You can download prebuilt GSIs from the AOSP continuous integration (CI) website at ci.android.com. If the GSI type for your hardware platform is unavailable for download, refer to the following section for details on building GSIs for specific targets.

Building GSIs

Starting with Android 9, each Android version has a GSI branch named DESSERT-gsi on AOSP (for example, android10-gsi is the GSI branch on Android 10). GSI branches include the content of Android with all security patches and GSI patches applied.

To build a GSI, set up the Android source tree by downloading from a GSI branch and choosing a GSI build target. Use the build target tables below to determine the correct GSI version for your device. After the build completes, the GSI is the system image (that is, system.img) and appears in the output folder out/target/product/generic_arm64. The build also outputs vbmeta.img, which you can use to disable verify boot on the devices using Android Verified Boot.

For example, to build the GSI build target aosp_arm64-userdebug on the GSI branch android10-gsi, run the following commands. 

$ repo init -u https://android.googlesource.com/platform/manifest -b android10-gsi
$ repo sync -cq
$ source build/envsetup.sh
$ lunch aosp_arm64-userdebug
$ make -j4

Android GSI build targets

The following GSI build targets are for devices launching on Android 9 or higher. Due to a reduction in variances between architectures, Android 10 includes only four GSI products.

GSI name CPU arch Binder interface bitness System-as-root Build target
aosp_arm ARM 64 Y aosp_arm-user
aosp_arm-userdebug
aosp_arm64 ARM64 64 Y aosp_arm64-user
aosp_arm64-userdebug
aosp_x86 x86 64 Y aosp_x86-user
aosp_x86-userdebug
aosp_x86_64 x86-64 64 Y aosp_x86_64-user
aosp_x86_64-userdebug

Legacy GSI build targets

The following legacy GSI build targets are for devices upgrading from Android 8.0 or 8.1 to Android 10. Legacy GSI names include the suffix _ab to distinguish them from Android 10 GSI names.

GSI name CPU arch Binder interface bitness System-as-root Build target
aosp_arm_ab ARM 32 Y aosp_arm_ab-userdebug
aosp_arm_64b_ab ARM 64 Y aosp_arm_64b_ab-userdebug
aosp_arm64_ab ARM64 64 Y aosp_arm64_ab-userdebug
aosp_x86_ab x86 32 Y aosp_x86_ab-userdebug
aosp_x86_64_ab x86-64 64 Y aosp_x86_64_ab-userdebug

Requirements for flashing GSIs

Android devices can have different designs, so there is no generic command or set of instructions for flashing a GSI to apply to all devices. Check with the manufacturer of the Android device for explicit flashing instructions. Use the following steps as a general guideline:

  1. Ensure that the device has the following:
    • Treblized
    • A method for unlocking devices (so they can be flashed using fastboot)
    • A method for disabling verify boot (for example, vboot 1.0 or AVB)
    • An unlocked state to make it flashable via fastboot (To ensure that you have the latest version of fastboot, build it from the Android source tree.)
  2. Disable verify boot.
  3. Erase the current system partition, then flash the GSI to the system partition.
  4. Wipe the user data and clear the data from other necessary partitions (for example, user data and system partitions).
  5. Reboot the device.

For example, to flash a GSI to any Pixel device:

  1. Boot to fastboot mode and unlock the bootloader. The devices supporting fastbootd also need to boot into fastbootd by: 
    $ fastboot reboot fastboot
  2. Disable verify boot (AVB) by flashing vbmeta.img: 
    $ fastboot --disable-verification flash vbmeta vbmeta.img
  3. Erase and flash the GSI to the system partition: 
    $ fastboot erase system
$ fastboot flash system system.img
  4. Wipe the user data and clear the data from other necessary partitions (for example, user data and system partitions): 
    $ fastboot -w
  5. Reboot: 
    $ fastboot reboot
On Android 10 devices that have smaller system partitions, the following error message might appear when flashing the GSI: 
    Resizing 'system_a'    FAILED (remote: 'Not enough space to resize partition')
    fastboot: error: Command failed
Use the following command to delete the product partition and free up space for the system partition. This provides extra space to flash the GSI: 
$ fastboot delete-logical-partition product_a
The postfix _a should match the slot id of the system partition, such as system_a in this example.

Contributing to GSIs

Android welcomes your contributions to GSI development. You can get involved and help improve the GSI by:

  • Creating a GSI patch. DESSERT-gsi is not a development branch and accepts only cherrypicks from the AOSP master branch, so to submit a GSI patch, you must:
    1. Submit the patch to the AOSP master branch.
    2. Cherrypick the patch to DESSERT-gsi.
    3. File a bug to get the cherrypick reviewed.
  • Reporting GSI bugs or making other suggestions. Review the instructions in Reporting Bugs, then browse or file GSI bugs.

Tips

Changing the navigation bar mode using adb

When booting with GSI, the navigation bar mode is configured by vendor overriding. You can change the navigation bar mode by running the following adb command in runtime. 

adb exec-out cmd overlay enable-exclusive com.android.internal.systemui.navbar.mode

Where mode can be threebutton, twobutton, gestural, and so on.