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 9 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) and types. 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 AIDL/HIDL-based architectural changes (also known as Treble), including support for the AIDL interfaces and HIDL interfaces. You can use the GSI on any Android device that uses AIDL/HIDL vendor interfaces. (For more details, see Architecture resources.)
- File system. The GSI uses the ext4 file system.
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 15 | gsi_$arch-user (Signed) |
Devices launching with Android 14 | gsi_$arch-user (Signed) |
Devices launching with Android 13 | gsi_$arch-user (Signed) |
Devices launching with Android 12L | gsi_$arch-user (Signed) |
Devices launching with Android 12 | gsi_$arch-user (Signed) |
Devices launching with Android 11 | gsi_$arch-user (Signed) |
All GSIs are built from the Android 12 codebase, and each CPU architecture has a corresponding GSI binary (see the list of build targets in Building GSIs).
Android 12 GSI changes
Devices launching with or updated to Android 12 must use Android 12 GSIs for compliance testing. This includes the following major changes from earlier GSIs:
- Target name. The GSI target name for compliance
tests is changed to
gsi_$arch
. The GSI with target nameaosp_$arch
is kept for Android app developers. The test planCTS-on-GSI
is also reduced for testing vendor interface. - Legacy GSI is phased out. GSI 12 removes the workarounds accommodating Android 8.0 or 8.1 devices that are not fully Treblized.
- Userdebug SEPolicy. The GSI
gsi_$arch
containsuserdebug_plat_sepolicy.cil
. When flashing the OEM-specificvendor_boot-debug.img
orboot-debug.img
,/system/bin/init
will loaduserdebug_plat_sepolicy.cil
from the GSIsystem.img
. Reference VTS Testing with Debug Ramdisk for the detail.
Android 11 GSI changes
Devices launching with or updated to Android 11 must use Android 11 GSIs for compliance testing. This includes the following major changes from earlier GSIs:
- system_ext contents. Android
11 defines a new partition
system_ext
. GSI puts the system extension contents under the foldersystem/system_ext
. - APEXes. GSI contains both flattened and compressed APEXes.
Which one to use is determined by the system property
ro.apex.updatable
in the vendor partition at run time. Reference Configuring system to support APEX updates for the detail.
Android 10 GSI changes
Devices launching with or updated to 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 details.
- Unsparsed format. GSI with targets
aosp_$arch
are built with unsparsed format. You can useimg2simg
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 GSIaosp_$arch_ab
. The upgradedinit
in ramdisk supports OEM system.img with system-as-root layout. - Verify boot. Using GSI you only need to unlock the device. It's not necessary to disable verify boot.
Android 9 GSI changes
Devices launching with or updated to 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,
aosp_arm64
andaosp_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.
Download 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.
Build GSIs
Starting with Android 9, each Android version has a
GSI branch named DESSERT-gsi
on AOSP (for example,
android12-gsi
is the GSI branch on Android
12). 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
.
For example, to build the GSI build target
gsi_arm64-userdebug
on the GSI branch android12-gsi
,
run the following commands.
$ repo init -u https://android.googlesource.com/platform/manifest -b android12-gsi $ repo sync -cq $ source build/envsetup.sh $ lunch gsi_arm64-userdebug $ make -j4
Android GSI build targets
The following GSI build targets are for devices launching on Android 9 or higher.
GSI name | CPU arch | Binder interface bitness | System-as-root | Build target |
---|---|---|---|---|
gsi_arm |
ARM | 32 | Y | gsi_arm-user gsi_arm-userdebug |
gsi_arm64 |
ARM64 | 64 | Y | gsi_arm64-user gsi_arm64-userdebug |
gsi_x86 |
x86 | 32 | Y | gsi_x86-user gsi_x86-userdebug |
gsi_x86_64 |
x86-64 | 64 | Y | gsi_x86_64-user gsi_x86_64-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:
- Ensure that the device has the following:
- Treblized
- A method for unlocking devices (so they can be flashed using
fastboot
) - An unlocked state to make it flashable via
fastboot
(To ensure that you have the latest version offastboot
, build it from the Android source tree.)
- 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
fastboot
mode and unlock the bootloader. - The devices supporting
fastbootd
also need to boot intofastbootd
by:$ fastboot reboot fastboot
- 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
- Reboot:
$ fastboot reboot
Resizing 'system_a' FAILED (remote: 'Not enough space to resize partition') fastboot: error: Command failedUse 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_aThe postfix
_a
should match the slot id of the system partition,
such as system_a
in this example.
Contribute 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 main branch, so to submit a GSI patch, you must:- Submit the patch to the
AOSP
main
branch. - Cherrypick the patch to
DESSERT-gsi
. - 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.
Tips
Change 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.