Set up Design Secure Develop Configure Reference
Go to code
Overview Start Download Build Create Contribute Contact

Generic System Image (GSI)

A generic system image (GSI) is a system image with adjusted configurations for Android devices. It is 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.

GSI compliance is part of the Android Compatibility program. 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 the device implements vendor inferfaces 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 are 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 GSI has the following configuration:

  • Treble. A GSI includes full support for the HIDL-based architectural changes (also known as "Treble") introduced in Android 8.0, including support for HIDL interfaces. You can use a GSI on any Android device that uses HIDL vendor interfaces. (For more details, see Architecture resources.)
  • Verify Boot. A GSI does not include a verify boot solution (vboot 1.0, AVB, etc.). To flash a GSI to an Android device, it must have a method for disabling verify boot.
  • Build variant. A GSI always uses a userdebug build variant to enable running VTS and CTS. After replacing the system image with GSI, you can root the device then test with a user-build vendor image and a userdebug-build system image.
  • File system and image format. A GSI uses an ext4 file system with sparse image format.

The current GSI includes following major variances:

  • Version. Support for Android 8.0, Android 8.1, and Android 9.
  • CPU architecture. Support for different CPU instructions (ARM, x86, etc.) and CPU bitness (32-bit or 64-bit).
  • Partition layout. Can use system-as-root or non-system-as-root partition layout.
  • Support for binder interface bitness.

GSI types

The GSI used for compliance testing is determined by the Android version the device launches with. Android 9 supports the following GSIs:

GSI name Description Product name
Android GSI For devices launching with Android 9 aosp_$arch
Legacy GSI For devices launching with Android 8.0 or Android 8.1 aosp_$arch_a(b)

All GSIs are built from the Android 9 codebase.

Android 9 GSI changes

Devices launching with Android 9 must use Android 9 GSIs for compliance testing, which includes the following major changes from earlier GSIs:

  • Merges GSI and emulator. GSIs are built from the system images of emulator products, e.g. aosp_arm64, aosp_x86, etc.
  • System-as-root. In previous versions of Android, devices that did not support A/B updates could mount the system image under /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 does not support 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. In Android 9, VNDK is mandatory, meaning the BOARD_VNDK_RUNTIME_DISABLE must not be set (BOARD_VNDK_RUNTIME_DISABLE := # must not be set).
  • Compatible system property. Android 9 enables the access check for compatible system property (PRODUCT_COMPATIBLE_PROPERTY_OVERRIDE := true).

To test devices launching with Android 9 with cts-on-gsi, use the build targets for the Android 9 GSI.

Android 9 Legacy GSI changes

Devices upgrading to Android 9 can use Legacy GSI product named with suffix _ab or _a (e.g. aosp_arm64_ab, aosp_x86_a) for compliance testing. This GSI supports the following upgrade use cases:

  • Devices with an Android 8.1 vendor interface implementation
  • Devices updated to the Android 9 vendor interface implementation

Legacy GSIs are build from the Android 9 source tree but contain the following backward-compatible configurations for upgraded devices:

  • Non system-as-root. Devices that do not support system-as-root can continue to use _a products (e.g., aosp_arm_a).
  • 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 (e.g. /bluetooth, /firmware/radio, /persist, etc.).

To test devices upgrading to Android 9 with cts-on-gsi, use the build targets for Legacy GSI.

Android 9 Keymaster changes

In earlier versions of Android, devices implementing Keymaster 3 or lower were required to verify 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, this requirement has changed to enable vendors to boot a GSI. Specifically, Keymaster should not perform verification since 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 9 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 BOARD_VNDK_RUNTIME_DISABLE Legacy GSI
system binaries version		 Legacy GSI support
0 8.0 (any) (N/A) 9 No
1.a 8.1 (empty) (any) 9 No
1.b 8.1 current true 9 No
2 8.1 current (empty) 9 Yes
3 9 current true 9 Yes
4 9 current (empty) 9 Yes

The most common supported use case is #2, where the Legacy GSI supports devices running Android 8.1 that were built with BOARD_VNDK_VERSION but built without BOARD_VNDK_RUNTIME_DISABLE (i.e., runtime enforcement was NOT disabled).

The two unsupported use cases are #1.a and #1.b, where the Legacy GSI does NOT support devices running Android 8.1 that were not built with BOARD_VNDK_VERSION or built with BOARD_VNDK_RUNTIME_DISABLE (i.e. runtime enforcement WAS disabled). These devices are not supported because their vendor binaries depend on Android 8.1 non-VNDK shared libraries, which are not included in Legacy GSIs. To make these devices compatible with the Legacy GSI, vendors 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 9 (use case #3 and use case #4).

Building GSIs

Starting with Android 9, each Android version has a GSI branch named DESSERT-gsi on AOSP (for example, pie-gsi is the GSI branch on Android 9). 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 (e.g. system.img) and appears in the output folder out/target/product/generic_arm64_ab. 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 Legacy GSI build target aosp_arm64_ab-userdebug on GSI branch pie-gsi, run the following commands: 

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

Android 9 GSI build targets

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

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

Android 9 Legacy GSI build targets

The following Legacy GSI build targets are for devices upgrading to Android 9. Legacy GSI names include the suffix _ab or _a to distinguish them from Android 9 GSI names.

GSI name CPU arch Binder interface bitness System-as-root Product name
aosp_arm_a ARM 32 N aosp_arm_a-userdebug
aosp_arm_ab ARM 32 Y aosp_arm_ab-userdebug
**NA ARM 64 N
aosp_arm_64b_ab ARM 64 Y aosp_arm_64b_ab-userdebug
aosp_arm64_a ARM64 64 N aosp_arm64_a-userdebug
aosp_arm64_ab ARM64 64 Y aosp_arm64_ab-userdebug
aosp_x86_a x86 32 N aosp_x86_a-userdebug
aosp_x86_ab x86 32 Y aosp_x86_ab-userdebug
**NA x86 64 N
**NA x86 64 Y
aosp_x86_64_a x86-64 64 N aosp_x86_64_a-userdebug
aosp_x86_64_ab x86-64 64 Y aosp_x86_64_ab-userdebug
** Could be added by request

Flashing GSIs Requirements

Android devices can have different designs, so no single command or set of instructions for flashing a GSI to a specific device is possible. You can check with the manufacturer of the Android device for explicit flashing instructions or use the following general steps as guidelines:

  1. Ensure the device has the following:
    • Support for HIDL-HAL interfaces.
    • A method for unlocking devices (so they can be flashed using fastboot).
    • A method for disabling verify boot (e.g. vboot 1.0, AVB, etc.).
    • Unlock the device to make it flashable via fastboot. (To ensure you have the latest version of fastboot, build it from Android source tree.)
  2. Disable verify boot.
  3. Erase the current system partition, then flash the GSI to system partition.
  4. Wipe userdata and clear data from other necessary partitions (e.g. metadata).
  5. Reboot the device.

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

  1. Boot to bootloader mode and unlock the bootloader.
  2. Disable verify boot (AVB) by flashing vbmeta.img: 
    $ fastboot flash vbmeta vbmeta.img
  3. Erase and flash the GSI to system partition: 
    $ fastboot erase system
$ fastboot flash system system.img
  4. Wipe userdata and clear other necessary partitions: 
    $ fastboot -w
  5. Reboot: 
    $ fastboot reboot

Contributing to GSIs

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

  • Creating a GSI patch. Because DESSERT-gsi is not a development branch and accepts only cherrypicks from the AOSP master branch, 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 (look for "Generic System Image" in the Platform table).