🌐 Android GSI Guide

Generic System Images (GSIs) let you run almost any Android build on any Project Treble-compatible device — even without an official ROM port.

---

What is a GSI?

A Generic System Image is an Android system image built to run on any device that supports Project Treble (Android 8.0+). Instead of being tied to specific hardware, it uses a standardized vendor interface (VNDK) that separates the Android framework from device-specific drivers.

Stock ROM:    [Android framework + OEM customization + Hardware drivers] ← all merged
GSI ROM:      [Android framework only] + [vendor.img from your device] ← separated

---

Is my device Treble-compatible?

# Check via ADB
adb shell getprop ro.treble.enabled
# "true" = Treble supported

# Check with Treble Check app
# https://play.google.com/store/apps/details?id=com.kevintresuelo.treble

Most devices launched with Android 8.0 or later are Treble-compatible.

---

GSI architecture types

You need to pick the right GSI for your device:

# Find your CPU architecture
adb shell getprop ro.product.cpu.abi
# arm64-v8a = arm64

# Find partition scheme
adb shell getprop ro.product.system.partition_name
# or check if /system_ext exists: adb shell ls /system_ext

Type	Architecture	Partition
arm64-ab	64-bit ARM	A/B (most modern)
arm64-a	64-bit ARM	A-only
arm-ab	32-bit ARM	A/B
x86_64-ab	64-bit x86	A/B

---

Where to get GSIs

Source	Type	Link
Google AOSP	Pure AOSP	https://developer.android.com/topic/generic-system-image
phhusson's GSI	Feature-rich AOSP	https://github.com/phhusson/treble_experimentations
AndyYan GSI	LineageOS-based	https://github.com/AndyCGYan/lineage_build_unified
Evolution X GSI	Pixel-like	https://github.com/Evolution-X-Devices
crDroid GSI	Heavy customization	https://github.com/crdroidandroid
Pixel Experience GSI	Pixel UI	https://get.pixelexperience.org/gsi

---

Flash a GSI

# 1. Unlock bootloader (device-specific)
# 2. Boot to fastbootd (not regular fastboot!)
adb reboot fastboot   # NOT "adb reboot bootloader"

# 3. Erase system partition
fastboot erase system

# 4. Flash the GSI
fastboot flash system system.img

# 5. Disable vbmeta verification (important!)
fastboot flash vbmeta --disable-verity --disable-verification vbmeta.img

# 6. Wipe userdata
fastboot -w

# 7. Reboot
fastboot reboot

---

Known limitations

• ❌ Camera may not work perfectly (device-specific HAL issues)
• ❌ Fingerprint sensor may be broken
• ❌ NFC, IR blaster, or other peripherals may not work
• ❌ No OTA updates
• ✅ Core Android, Wi-Fi, Bluetooth, display usually work

---

Fastbootd vs Fastboot

Fastboot  → runs in bootloader, can flash boot/recovery/vbmeta
Fastbootd → runs in userspace recovery, can flash system/vendor/product

GSI flashing requires fastbootd for the system partition.
adb reboot fastboot → fastbootd
adb reboot bootloader → fastboot

See also: android-rom-guide