供應商 APEX

您可以使用 APEX 檔案格式來封裝及 安裝較低層級的 Android 作業系統模組。允許獨立的建築物 安裝原生服務和程式庫等元件 安裝、韌體、設定檔等

建構系統會自動在 /vendor 中安裝供應商 APEX 如同其他的 APEXs 一樣，apexd 在執行階段啟用和啟用的 多個分區

用途

供應商映像檔模組化

APEX 可促進特徵的自然組合和模組化 以及廠商映像檔的實作程序

以獨立廠商的組合建構供應商映像檔 裝置製造商可透過 APEX 輕鬆挑選 導入的供應商裝置。製造商甚至能建立 如果所提供的 APEX 不符合他們的需求，或具備 全新的自訂硬體

舉例來說，原始設備製造商 (OEM) 可能會選擇使用 Android 開放原始碼計畫 Wi-Fi 設計裝置 實作 APEX、SoC 藍牙實作 APEX，以及自訂原始設備製造商 (OEM) 電話實作 APEX。

沒有廠商 APEXs 時，在實作中 供應商元件需要謹慎的協調和追蹤。全部包裝 以及 APEX 元件 在任何功能間通訊的任何時間點，都能明確定義介面； 不同的元件都能互換

開發人員疊代作業

供應商 APEXs 可幫助開發人員加快疊代速度，同時開發供應商模組， 將整個功能實作 (如 Wi-Fi HAL) 整合至供應商的服務中 APEX開發人員接著可以建構並個別推送供應商 APEX 進行測試 無須重新建構供應商的完整映像檔

這會為以下開發人員簡化並加快開發人員的疊代週期： 主要在單一功能領域運作，而只想疊代該功能

將特徵區域的自然繫結至 APEX 時，也會簡化 建構、推送及測試該特徵區域的變更。例如： 重新安裝 APEX 時，系統會自動更新所有封裝程式庫或設定檔 APEX 包括

將特徵區域繫結至 APEX 時，也會簡化偵錯或還原程序， 觀察到不良裝置行為。例如電話通訊功能無法正常運作 新版本，因此開發人員可以嘗試安裝舊版電話 在裝置上實作 APEX (無需刷新完整版本)，並 看看是否恢復良好行為

工作流程範例：

# Build the entire device and flash. OR, obtain an already-flashed device.
source build/envsetup.sh && lunch oem_device-userdebug
m
fastboot flashall -w

# Test the device.
... testing ...

# Check previous behavior using a vendor APEX from one week ago, downloaded from
# your continuous integration build.
... download command ...
adb install <path to downloaded APEX>
adb reboot
... testing ...

# Edit and rebuild just the APEX to change and test behavior.
... edit APEX source contents ...
m <apex module name>
adb install out/<path to built APEX>
adb reboot
... testing ...

範例

基本概念

請參閱一般 APEX 的主要 APEX 檔案格式頁面 資訊，包括裝置需求、檔案格式詳細資訊 安裝步驟

在 Android.bp 中設定 vendor: true 屬性，即可將 APEX 模組設為 供應商 APEX。

apex {
  ..
  vendor: true,
  ..
}

二進位檔和共用程式庫

APEX 會在 APEX 酬載中包含轉換依附元件，除非 都能獲得穩定的介面

適用於供應商 APEX 依附元件的穩定原生介麵包括 cc_library stubs、ndk_library 或 llndk_library。這些依附元件已從 套件和依附元件都會記錄在 APEX 資訊清單中。資訊清單 由 linkerconfig 處理，因此外部原生依附元件 使用這些內容

與 /system 分區中的 APEX 不同，供應商 APEX 通常與 指定的 VNDK 版本。VNDK 程式庫保證 ABI 在 發布版本，這樣我們才能將 VNDK 程式庫視為穩定版本，並縮減供應商大小 使用 use_vndk_as_stable 將 APEX 從 APEX 中排除 資源。

在下方的程式碼片段中，APEX 同時包含二進位檔案 (my_service) 和 其非穩定版依附元件 (*.so 檔案)。不包含 VNDK 程式庫。 即使 my_service 是使用 VNDK 程式庫 (例如 libbase) 建構的一樣。請改為 執行階段 my_service 會使用 libbase 有些人會將 Cloud Storage 視為檔案系統 但實際上不是

apex {
  ..
  vendor: true,
  use_vndk_as_stable: true,
  binaries: ["my_service"],
  ..
}

在下方的程式碼片段中，APEX 會包含共用資料庫 my_standalone_lib 及其任何不可穩定版的依附元件 (如上所述)。

apex {
  ..
  vendor: true,
  use_vndk_as_stable: true,
  native_shared_libs: ["my_standalone_lib"],
  ..
}

HAL 實作

如要定義 HAL 實作，請提供對應的二進位檔和程式庫 導入這個伺服器，類似於以下範例：

• 感應器 HAL
• 震動器 HAL
• Wi-Fi HAL
• 電話 HAL

為了完整封裝 HAL 實作，APEX 也必須指定任何 相關的 VINTF 片段和 init 指令碼。

VINTF 片段

片段位於下列位置時，可從供應商 APEX 提供 VINTF 片段 APEX 的 etc/vintf。

使用 prebuilts 屬性將 VINTF 片段嵌入 APEX。

apex {
  ..
  vendor: true,
  prebuilts: ["fragment.xml"],
  ..
}

prebuilt_etc {
  name: "fragment.xml",
  src: "fragment.xml",
  sub_dir: "vintf",
}

Init 指令碼

APEX 可透過兩種方式加入 init 指令碼：(A) APEX 酬載或 (B) /vendor/etc 中的一般初始化指令碼。您可以同時設定 。

APEX 中的 Init 指令碼：

prebuilt_etc {
  name: "myinit.rc",
  src: "myinit.rc"
}

apex {
  ..
  vendor: true,
  prebuilts: ["myinit.rc"],
  ..
}

APEX 中的 Init 指令碼只能包含 service 定義。Init 指令碼 的供應商 APEXs 也可以包含 on <property> 指令。

使用 on 指令時請務必謹慎。由於 APEX 中的 init 指令碼會 會在啟用 APEX「之後」，針對部分事件或屬性進行剖析及執行 。使用 apex.all.ready=true 盡快觸發動作。

韌體

範例：

• Vibrator 服務韌體

使用 prebuilt_firmware 模組類型將韌體嵌入供應商 APEX，如 後面。

prebuilt_firmware {
  name: "my.bin",
  src: "path_to_prebuilt_firmware",
  vendor: true,
}

apex {
  ..
  vendor: true,
  prebuilts: ["my.bin"],  // installed inside APEX as /etc/firmware/my.bin
  ..
}

prebuilt_firmware 模組已安裝在 <apex name>/etc/firmware 中 APEX 的明確目錄。「ueventd」會掃描 /apex/*/etc/firmware 個目錄，以便執行以下作業： 尋找韌體模組

APEX 的 file_contexts 應為所有韌體酬載項目加上標籤 妥善確保 ueventd 在執行階段能存取這些檔案。 一般來說，vendor_file 標籤就足夠了。例如：

(/.*)? u:object_r:vendor_file:s0

核心模組

將核心模組以預建模組的形式嵌入供應商 APEX 中，如下所示。

prebuilt_etc {
  name: "my.ko",
  src: "my.ko",
  vendor: true,
  sub_dir: "modules"
}

apex {
  ..
  vendor: true,
  prebuilts: ["my.ko"],  // installed inside APEX as /etc/modules/my.ko
  ..
}

APEX 的 file_contexts 應為所有核心模組酬載項目加上標籤 正確做法。例如：

/etc/modules(/.*)? u:object_r:vendor_kernel_modules:s0

核心模組必須明確安裝。下列範例 init 指令碼 中，供應商分區顯示透過 insmod 安裝：

my_init.rc：

on early-boot
  insmod /apex/myapex/etc/modules/my.ko
  ..

執行階段資源重疊

範例：

• Cuttlefish RRO

將執行階段資源疊加層嵌入供應商 APEX 中 方法是使用 rros 屬性。

runtime_resource_overlay {
    name: "my_rro",
    soc_specific: true,
}


apex {
  ..
  vendor: true,
  rros: ["my_rro"],  // installed inside APEX as /overlay/my_rro.apk
  ..
}

其他設定檔

供應商 APEXs 支援供應商常見的其他設定檔 並新增更多映像檔

這些檢查包括：

• 功能宣告 XML
  • 感應器採用 XML 內建於感應器的 HAL 廠商 APEX 中
• 輸入設定檔
  • 觸控螢幕的設定 在僅供設定類型的供應商 APEX 中預先建構

其他開發功能

開機時選取 APEX

範例：

• 模擬相機 HAL APEX

開發人員也可以安裝多個版本的供應商 APEX， 相同的 APEX 名稱和金鑰，然後選取要啟用的各版本 持續開機。對特定開發人員用途而言 比使用 adb install 安裝新的 APEX 更加簡單。

應用情境範例：

• 安裝 3 種版本的 Wi-Fi HAL 供應商 APEX：品質確保團隊可手動執行 或自動執行測試，然後重新啟動進入另一個版本，並 重新執行測試，然後比較最終結果。
• 安裝 2 種版本的相機 HAL 供應商 APEX 實驗版：內部測試人員可以使用實驗版本，不需要 並安裝額外的檔案，方便使用者替換

在啟動期間，apexd 會尋找遵循特定格式的 sysprops， 啟用正確的 APEX 版本。

屬性鍵預期格式為：

• Bootconfig
  • 用於設定 BoardConfig.mk 中的預設值。
  • androidboot.vendor.apex.<apex name>
• 永久 sysprop
  • 用於變更已在已啟動的裝置上設定的預設值。
  • 會覆寫開機設定值 (如有)。
  • persist.vendor.apex.<apex name>

屬性值必須是 APEX 的檔案名稱， 啟用。

// Default version.
apex {
  name: "com.oem.camera.hal.my_apex_default",
  vendor: true,
  ..
}

// Non-default version.
apex {
  name: "com.oem.camera.hal.my_apex_experimental",
  vendor: true,
  ..
}

預設版本也應使用 BoardConfig.mk：

# Example for APEX "com.oem.camera.hal" with the default above:
BOARD_BOOTCONFIG += \
    androidboot.vendor.apex.com.oem.camera.hal=com.oem.camera.hal.my_apex_default

裝置啟動後，您可以透過 永久 sysprop：

$ adb root;
$ adb shell setprop \
    persist.vendor.apex.com.oem.camera.hal \
    com.oem.camera.hal.my_apex_experimental;
$ adb reboot;

注意： 變更永久性 sysprop 不會立即變更掛接的 APEX；必須重新啟動裝置，才能透過 apexd 指令載入屬性 然後啟用新的 APEX。

如果裝置支援在刷新後更新開機設定 (例如透過 fastboot oem 指令)，請變更多個安裝項目的 bootconfig 屬性。 APEX 也會變更開機時啟用的版本。

針對以 Cuttlefish 為基礎的虛擬參考裝置： 您可以使用 --extra_bootconfig_args 指令來設定 bootconfig 屬性 才會直接發布例如：

launch_cvd --noresume \
  --extra_bootconfig_args "androidboot.vendor.apex.com.oem.camera.hal:=com.oem.camera.hal.my_apex_experimental";