通用系統映像檔

通用系統映像檔 (GSI) 是經過調整設定的系統映像檔，適用於 Android 裝置。這項實作項目被視為「純 Android」，具備未經修改的 Android 開放原始碼計畫 (AOSP) 程式碼，可在執行 Android 9 以上版本的任何 Android 裝置上順利執行。

GSI 用於執行 VTS 和 CTS-on-GSI 測試。Android 裝置的系統映像檔會替換為 GSI，然後使用供應商測試套件 (VTS) 和Compatibility Test Suite (CTS) 進行測試，確保裝置使用最新版本 Android 正確實作供應商介面。

如要開始使用 GSI，請參閱下列各節，瞭解 GSI 設定 (和允許的差異) 和類型的詳細資料。準備好使用 GSI 時，請下載並建構裝置目標的 GSI，然後將 GSI 刷新至 Android 裝置。

GSI 設定和差異

目前的 Android GSI 具有下列設定：

• 高音：GSI 完整支援以 AIDL/HIDL 為基礎的架構變更 (也稱為 Treble)，包括支援 AIDL 介面和 HIDL 介面。您可以在使用 AIDL/HIDL 供應商介面的任何 Android 裝置上使用 GSI。(詳情請參閱架構資源)。
• 檔案系統。GSI 使用 ext4 檔案系統。

目前的 Android GSI 包含下列主要差異：

• CPU 架構。支援不同的 CPU 指令 (ARM、x86 等) 和 CPU 位元數 (32 位元或 64 位元)。

Treble 相容性測試的 GSI 目標

用於合規性測試的 GSI 取決於裝置啟動時搭載的 Android 版本。

所有 GSI 都是從 Android 12 程式碼集建構而來，且每個 CPU 架構都有對應的 GSI 二進位檔 (請參閱「建構 GSI」中的建構目標清單)。

Android 12 GSI 變更

如果裝置搭載 Android 12 或更新至 Android 12，就必須使用 Android 12 GSI 進行相容性測試。包括下列重大異動：

• 目標名稱：法規遵循測試的 GSI 目標名稱已變更為 gsi_$arch。目標名稱為「aosp_$arch」的 GSI 會保留給 Android 應用程式開發人員。測試計畫 CTS-on-GSI也會減少，以測試供應商介面。
• 舊版 GSI 已淘汰。GSI 12 會移除因應 Android 8.0 或 8.1 裝置的權宜措施，這些裝置並未完全 Treblized。
• Userdebug SEPolicy。GSI gsi_$arch 包含 userdebug_plat_sepolicy.cil。刷入 OEM 專屬 vendor_boot-debug.img 或 boot-debug.img 時，/system/bin/init 會從 GSI system.img 載入 userdebug_plat_sepolicy.cil。詳情請參閱「使用偵錯 Ramdisk 進行 VTS 測試」。

Android 11 GSI 變更

如果裝置搭載 Android 11 或更新至 Android 11，就必須使用 Android 11 GSI 進行相容性測試。包括下列重大異動：

• system_ext 內容。Android 11 定義了新的分區 system_ext。 GSI 會將系統擴充功能內容放在 system/system_ext 資料夾下。
• APEXes。GSI 包含扁平化和壓縮的 APEX。 要使用哪一個，取決於執行階段供應商分區中的系統屬性 ro.apex.updatable。詳情請參閱「 設定系統以支援 APEX 更新」。

Android 10 GSI 變更

如果裝置搭載 Android 10 或更新至 Android 10，就必須使用 Android 10 GSI 進行相容性測試。包括下列重大異動：

• 使用者版本。GSI 具有 Android 10 的使用者版本。在 Android 10 中，使用者建構 GSI 可用於 CTS-on-GSI/VTS 法規遵循測試。詳情請參閱「使用偵錯 Ramdisk 進行 VTS 測試」。
• 未稀疏格式。GSI with targets aosp_$arch are built with unsparsed format. 如有需要，您可以使用 img2simg 將未稀疏化的 GSI 轉換為稀疏格式。
• 以系統做為根目錄。名為 aosp_$arch_a 的舊版 GSI 建構目標已淘汰。如果裝置是從 Android 8 或 8.1 升級至 Android 10，且使用 ramdisk 和非系統即根目錄，請使用舊版 GSI aosp_$arch_ab。 ramdisk 中升級的 init 支援 OEM system.img，並採用 system-as-root 版面配置。
• 驗證開機程序。使用 GSI 時，您只需要解鎖裝置。 不需要停用驗證開機程序。

Android 9 GSI 變更

如果裝置搭載 Android 9 或更新至 Android 9，就必須使用 Android 9 GSI 進行相容性測試。包括下列重大異動：

• 合併 GSI 和模擬器。GSI 是以模擬器產品的系統映像檔建構而成，例如 aosp_arm64 和 aosp_x86。
• 以系統做為根目錄。在舊版 Android 中，不支援 A/B 更新的裝置可以在 /system 目錄下掛接系統映像檔。在 Android 9 中，系統映像檔的根目錄會掛接為裝置的根目錄。
• 64 位元繫結器介面。在 Android 8.x 中，32 位元 GSI 使用 32 位元繫結器介面。Android 9 不支援 32 位元繫結器介面，因此 32 位元和 64 位元 GSI 都會使用 64 位元繫結器介面。
• 強制執行 VNDK。在 Android 8.1 中，VNDK 為選用項目。 自 Android 9 起，VNDK 為必要設定，因此BOARD_VNDK_VERSION 必須設定。
• 相容的系統屬性。Android 9 可對相容的系統屬性 (PRODUCT_COMPATIBLE_PROPERTY_OVERRIDE := true) 啟用存取檢查。

Android 9 Keymaster 變更

在舊版 Android 中，實作 Keymaster 3 以下版本的裝置必須驗證執行中系統回報的版本資訊 (ro.build.version.release 和 ro.build.version.security_patch) 是否與系統啟動載入程式回報的版本資訊相符。這類資訊通常是從開機映像檔標頭取得。

在 Android 9 以上版本中，這項規定已變更，可讓供應商啟動 GSI。具體來說，Keymaster 不應執行驗證，因為 GSI 回報的版本資訊可能與供應商系統啟動載入程式回報的版本資訊不符。如果裝置實作的是 Keymaster 3 或更舊版本，供應商必須修改 Keymaster 實作項目，略過驗證 (或升級至 Keymaster 4)。如要瞭解 Keymaster 的詳細資料，請參閱「硬體支援的 Keystore」。

下載 GSI

您可以從 AOSP 持續整合 (CI) 網站 (ci.android.com) 下載預建 GSI。如果無法下載適用於硬體平台的 GSI 類型，請參閱下一節，瞭解如何為特定目標建構 GSI。

建構 GSI

從 Android 9 開始，每個 Android 版本在 Android 開放原始碼計畫 上都有一個名為 DESSERT-gsi 的 GSI 分支版本 (例如 android12-gsi 是 Android 12 的 GSI 分支版本)。GSI 分支版本包含 Android 內容，並套用所有安全性修補程式和 GSI 修補程式。

如要建構 GSI，請從 GSI 分支版本下載，並選擇 GSI 建構目標，藉此設定 Android 來源樹狀結構。請使用下方的建構目標表格，判斷裝置適用的 GSI 版本。建構完成後，GSI 就是系統映像檔 (即 system.img)，會顯示在輸出資料夾 out/target/product/generic_arm64 中。

舉例來說，如要在 GSI 分支版本 android12-gsi 上建構 GSI 建構目標 gsi_arm64-userdebug，請執行下列指令。

$ 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 建構目標

以下 GSI 建構目標適用於搭載 Android 9 以上版本啟動的裝置。

刷新 GSI 的規定

Android 裝置的設計可能不同，因此沒有適用於所有裝置的通用指令或一組指令。如需明確的刷機操作說明，請洽詢 Android 裝置製造商。請按照下列步驟操作：

1. 確認裝置符合下列條件：
   • Treblized
   • 解鎖裝置的方法 (以便使用 fastboot 刷機)
   • 解鎖狀態，可透過 fastboot 刷機 (為確保您擁有最新版 fastboot，請從 Android 來源樹狀結構建構)。
2. 清除目前的系統分割區，然後將 GSI 刷入系統分割區。
3. 清除使用者資料，並清除其他必要分割區的資料 (例如使用者資料和系統分割區)。
4. 重新啟動裝置。

舉例來說，如要將 GSI 刷新至任何 Pixel 裝置，請按照下列步驟操作：

1. 啟動至 fastboot模式，然後解鎖系統啟動載入程式。
2. 支援 fastbootd 的裝置也需要透過下列方式啟動 fastbootd：

   $ fastboot reboot fastboot

3. 清除並將 GSI 刷入系統分區：

   $ fastboot erase system
   $ fastboot flash system system.img

4. 如果裝置支援 Android 虛擬化架構，請刷新受保護的虛擬機器韌體：

   $ fastboot flash pvmfw pvmfw.img
   

5. 清除使用者資料，並清除其他必要磁碟分割區的資料 (例如使用者資料和系統磁碟分割區)：

   $ fastboot -w

6. 重新啟動並返回系統啟動載入程式：

   $ fastboot reboot-bootloader

7. 在刷入提供的 vbmeta 時，停用驗證開機程序驗證：

   $ fastboot --disable-verification flash vbmeta vbmeta.img

8. Reboot:

   $ fastboot reboot

    Resizing 'system_a'    FAILED (remote: 'Not enough space to resize partition')
    fastboot: error: Command failed

$ fastboot delete-logical-partition product_a

為 GSI 貢獻心力

Android 歡迎您為 GSI 開發作業貢獻心力。你可以透過下列方式參與並協助改善 GSI：

• 建立 GSI 修補程式。DESSERT-gsi 「不是」開發分支版本，只接受從 AOSP 最新發布分支版本 (android17-release) 挑選的修補程式，因此如要提交 GSI 修補程式，請按照下列步驟操作：
  1. 將修補程式提交至 AOSP android17-release 分支版本。
  2. 將修補程式 Cherrypick 至 DESSERT-gsi。
  3. 提出錯誤報告，要求審查 Cherrypick。
• 回報 GSI 錯誤或提出其他建議。請參閱回報錯誤中的指示，然後瀏覽或回報 GSI 錯誤。

提示

使用 adb 變更導覽列模式

使用 GSI 開機時，導覽列模式會由供應商覆寫設定。您可以在執行階段執行下列 adb 指令，變更導覽列模式。

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

其中 mode 可以是 threebutton、twobutton、gestural 等。