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 project 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 Android device, the device must have a method for disabling verify boot.
- Build variant. The GSI always uses a
userdebugbuild variant to enable running VTS and CTS. After replacing the system image with the 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. The GSI uses an ext4 file system with a sparse image format.
The current Android GSI project includes the 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.
The GSI used for compliance testing is determined by the Android version that the device launches with. Android supports the following GSIs.
|GSI name||Description||Product name|
|Android GSI||For devices launching with Android 9. This GSI can run only on devices running Android 9 and higher.||
|Legacy GSI||For devices launching with Android 8.0 or Android 8.1. This GSI can run only on devices running Android 8.x.||
All GSIs are built from the Android 9 codebase, and each CPU architecture has a corresponding GSI binary (see the list of build targets in Building GSIs).
Android 9 GSI changes
Devices launching with Android 9 must use Android 9 GSIs for compliance testing. This includes the following major changes from earlier GSIs:
- Merges GSI and emulator. GSIs are built from the system
images of emulator products, for example,
- System-as-root. In previous versions of Android, devices
that didn't support A/B updates could mount the system image under the
/systemdirectory. 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. In
Android 9, VNDK is mandatory, so
BOARD_VNDK_VERSIONmust be set.
- Compatible system property. Android
9 enables the access check for a compatible
system property (
PRODUCT_COMPATIBLE_PROPERTY_OVERRIDE := true).
To test devices launching with Android 9 with CTS-on-GSI, use the Android 9 GSI build targets.
Android 9 legacy GSI changes
Devices upgrading to Android 9 can use a legacy GSI
product named with the suffix
aosp_x86_a) for compliance
testing. This GSI supports the following upgrade use cases:
- Devices with the Android 8.1 vendor interface implementation
- Devices updated to the Android 9 vendor interface implementation
Legacy GSIs are built from the Android 9 source tree but contain the following backward-compatible configurations for upgraded devices:
- Non system-as-root. Devices that don't support
system-as-root can continue to use
_aproducts (for example,
- 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,
To test devices upgrading to Android 9 with CTS-on-GSI, use the legacy GSI build targets.
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.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 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 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.
system binaries version
|Legacy GSI support|
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
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:
BOARD_VNDK_RUNTIME_DISABLE(use case #2).
- Port/upgrade the vendor binaries to depend on the shared libraries from Android 9 (use case #3).
You can download prebuilt GSIs for some Android 9 GSI types 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.
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 (that is,
system.img) and appears in the output folder
out/target/product/generic_arm64_ab. The build
vbmeta.img, which you can use to disable verify
boot on the devices using Android
For example, to build the legacy GSI build target
aosp_arm64_ab-userdebug on the GSI branch
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|
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
_a to distinguish them from Android
9 GSI names.
|GSI name||CPU arch||Binder interface bitness||System-as-root||Product name|
Requirements for flashing GSIs
Android devices can have different designs, so no single command or set of instructions for flashing a GSI to a specific device is possible. Check with the manufacturer of the Android device for explicit flashing instructions or use the following general steps as guidelines:
- Ensure that the device has the following:
- Support for HIDL-HAL interfaces
- A method for unlocking devices (so they can be flashed using
- 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.)
- Disable verify boot.
- Erase the current system partition, then flash the GSI to the system partition.
- Wipe the user data and clear the data from other necessary partitions (for example, user data and system partitions).
- Reboot the device.
For example, to flash a GSI to any Pixel device:
- Boot to
fastbootmode and unlock the bootloader.
- Disable verify boot (AVB) by flashing
$ fastboot --disable-verification flash vbmeta vbmeta.img
- Erase and flash the GSI to the system partition:
$ fastboot erase system $ fastboot flash system system.img
- Wipe the user data and clear the data from other necessary partitions (for
example, user data and system partitions):
$ fastboot -w
$ 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.
DESSERT-gsiis not a development branch and accepts only cherrypicks from the AOSP master branch, so to submit a GSI patch, you must:
- Submit the patch to the
- Cherrypick the patch to
- File a bug to get the cherrypick reviewed.
- Submit the patch to the AOSP
- Reporting GSI bugs or making other suggestions. Review the instructions in Reporting Bugs, then browse or file GSI bugs.