通用系統映像檔

一般系統映像檔 (GSI) 是經過調整設定的系統映像檔 。應視為純 Android 實作 未經修改的 Android 開放原始碼計畫 (AOSP) 程式碼，任何 Android 搭載 Android 9 以上版本的裝置可順利執行。

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

如要開始使用 GSI，請參閱下列各節，瞭解詳細資訊 GSI 設定 (已允許) 變異數) 和類型。準備好使用 GSI 時 為裝置下載及建構 GSI ，然後將 GSI 刷新至 Android 裝置。

GSI 的設定和變異數

目前的 Android GSI 設定如下：

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

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

• CPU 架構。支援不同的 CPU 指示 (ARM、x86 等) 以及 CPU 位元率 (32 位元或 64 位元)。

Treble 法規遵循測試的 GSI 目標

用於法規遵循測試的 GSI 取決於： 以及啟動裝置時

裝置類型	建構目標
搭載 Android 14 的裝置	gsi_$arch-user (已簽署)
搭載 Android 13 的裝置	gsi_$arch-user (已簽署)
搭載 Android 12L 的裝置	gsi_$arch-user (已簽署)
搭載 Android 12 的裝置	gsi_$arch-user (已簽署)
搭載 Android 11 的裝置	gsi_$arch-user (已簽署)

所有 GSI 均使用 Android 12 程式碼集建構而成 每個 CPU 架構都有相對應的 GSI 二進位檔 (請參閱版本清單 建構 GSI 中的目標)。

Android 12 GSI 異動

搭載 Android 12 或更新的裝置必須採用 Android 系統 12 GSI 用於法規遵循測試。這包括 下方的 GSI 主要異動如下：

• 目標名稱：法規遵循的 GSI 目標名稱 測試變更為 gsi_$arch。含有目標名稱的 GSI 「aosp_$arch」會保留給 Android 應用程式開發人員。測試計畫 也會減少 CTS-on-GSI，以便測試供應商介面。
• 舊版 GSI 已逐步淘汰。GSI 12 移除配合搭載 Android 8.0 或 8.1 的裝置 未完全經過處理
• 使用者偵錯 SEPolicy。GSI gsi_$arch 包含 userdebug_plat_sepolicy.cil。閃光燈時 原始設備製造商 (OEM) 專用的 vendor_boot-debug.img，或 boot-debug.img，/system/bin/init 將載入 GSI 的 userdebug_plat_sepolicy.cil system.img。參考資料 VTS 測試工具 偵錯 Ramdisk 以取得詳細資訊。

Android 11 GSI 變更

搭載 Android 11 或更新的裝置必須採用 Android 系統 11 GSI 用於法規遵循測試。這包括 下方的 GSI 主要異動如下：

• system_ext 內容。Android。 11 定義了新的分區 system_ext。 GSI 會將系統擴充功能內容放入資料夾 system/system_ext。
• APEXs：GSI 同時包含經過簡化和壓縮的 APEX。 要使用哪個代碼取決於系統屬性 ro.apex.updatable 納入供應商分區中參考資料 設定系統以支援 APEX 更新。

Android 10 GSI 變更

搭載 Android 10 或更新的裝置必須採用 Android 系統 10 個 GSI 用於法規遵循測試。這包括 下方的 GSI 主要異動如下：

• 使用者建構：GSI 透過 Android 建構使用者 10.在 Android 10 中， 使用者建構 GSI 可用於 CTS 對 GSI/VTS 法規遵循測試。參考資料 使用 Debug Ramdisk 進行 VTS 測試 。
• 未剖析的格式。設有目標的 GSI aosp_$arch 以未剖析的格式建構。別擔心！您可以使用 img2simg：將未剖析的 GSI 轉換為稀疏格式 (如有) 無從得知
• 系統層級的根層級：名為「舊版 GSI」的建構目標 已逐步停用 aosp_$arch_a。適用於已升級的裝置 從 Android 8 或 8.1 到 Android 10 而非系統的根層級，請使用舊版 GSI aosp_$arch_ab。 已升級的 ramdisk 中升級的 init 支援 OEM 系統.img 並以系統化的方式配置
• 驗證開機程序。只要解鎖裝置，就能使用 GSI。 不需要停用驗證開機程序。

Android 9 GSI 異動

搭載 Android 9 或更新的裝置必須採用 Android 裝置 9 GSI 用於法規遵循測試。這包括 下方的 GSI 主要異動如下：

• 合併 GSI 和模擬器。GSI 是透過系統建構 模擬器產品的圖片，例如 aosp_arm64 和 aosp_x86。
• 系統層級的根層級：在舊版 Android 中 不支援 A/B 更新功能，可將系統映像檔掛接於 /system 目錄內。在 Android 9 中， 系統映像檔的根層級將掛接為裝置的根目錄。
• 64 位元繫結器介面：Android 8.x (32 位元 GSI) 都使用 32 位元繫結器介面Android 9 都不支援 32 位元繫結器介面，因此 32 位元的 GSI 和 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

您可以從 Android 開放原始碼計畫持續整合 (CI) 下載預先建構的 GSI 位於 ci.android.com。如果硬體的 GSI 類型 不開放下載，請參閱以下章節 瞭解如何針對特定目標建構 GSI。

建構 GSI

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

如要建構 GSI，請設定 Android 原始碼樹狀結構： 從 GSI 分支版本下載 選擇 GSI 版本 目標。使用下方的建構目標資料表決定正確的 GSI 版本。建構完成後，GSI 就是系統 映像檔 (即 system.img)，並顯示在輸出資料夾中 out/target/product/generic_arm64。

例如，如要建構 GSI 建構目標 GSI 分支版本 android12-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 名稱	CPU 架構	繫結機制介面位元	系統即根層級	建構目標
gsi_arm	啟動	32	是	gsi_arm-user gsi_arm-userdebug
gsi_arm64	ARM64	64	是	gsi_arm64-user gsi_arm64-userdebug
gsi_x86	x86	32	是	gsi_x86-user gsi_x86-userdebug
gsi_x86_64	x86-64	64	是	gsi_x86_64-user gsi_x86_64-userdebug

刷新 GSI 的規定

Android 裝置可以有不同的設計，因此沒有一般指令或 說明如何刷新 GSI 並套用至所有裝置。確認 取得明確的刷新指示。 以下是一般原則：

1. 確認裝置符合下列條件：
   • 經過柔和處理
   • 解鎖裝置的方法，讓裝置改用 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. 清除使用者資料，並清除其他必要分區的資料 (例如： 例如使用者資料和系統分區)：

   $ fastboot -w

5. 重新啟動：

   $ fastboot reboot

，瞭解如何調查及移除這項存取權。 如果是系統分區較小的 Android 10 以上裝置， 刷新 GSI 時，系統可能會顯示下列錯誤訊息：

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

請使用下列指令刪除產品分區，並釋出空間 系統磁碟分區這可提供用於刷新 GSI 的額外空間：

$ fastboot delete-logical-partition product_a

後置字串 _a 應與系統分區的運算單元 ID 相符。 例如這個例子中的 system_a

為 GSI 貢獻心力

Android 歡迎你對 GSI 開發作業的貢獻。親身參與 並透過下列方式改善 GSI：

• 建立 GSI 修補程式。DESSERT-gsi 「不是」開發分支版本，只接受來自 AOSP 主要分支版本，因此如要提交 GSI 修補程式，您必須：
  1. 將修補程式提交至 Android 開放原始碼計畫 main 分支版本。
  2. 將修補程式選為 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 等。