將 Fastboot 移至使用者空間

Fastboot 是引導程式模組和模式的名稱。Android 10 以上版本可將 Fastboot 實作從系統啟動載入程式重新移到使用者空間，以支援可調整大小的分區。這項重新定位功能可將閃燈程式碼移至可維護且可測試的常用位置，其中只有硬體抽象層 (HAL) 實作的 fastboot 供應商專屬部分。此外，Android 12 以上版本支援透過新增的 fastboot 指令刷新 RAMDISK。

統一 Fastboot 和復原功能

由於使用者空間快速啟動和復原功能相似，因此您可以將這兩項功能合併為一個分割區或二進位檔。這可帶來許多優點，例如使用較少空間、整體分區較少，以及讓 fastboot 和 recovery 共用其核心和程式庫。

Fastbootd 是使用者空間 Daemon 和模式的名稱。如要支援 fastbootd，引導程式必須實作 boot-fastboot 的新啟動控制區塊 (BCB) 指令。如要進入 fastbootd 模式，Bootloader 會將 boot-fastboot 寫入 BCB 訊息的指令欄位，並讓 BCB 的 recovery 欄位保持不變 (以便重新啟動任何中斷的復原工作)。status、stage 和 reserved 欄位也保持不變。當 BCB 指令欄位顯示 boot-fastboot 時，引導程式就會載入並啟動至復原映像檔。接著，復原會剖析 BCB 訊息，並切換至 fastbootd 模式。

ADB 指令

本節將說明用於整合 fastbootd 的 adb 指令。這項指令的結果會因執行者是系統或復原程序而異。

指令	說明
reboot fastboot	重新啟動至 fastbootd (系統)。 不需重新啟動 (復原) 即可直接進入 fastbootd。

Fastboot 指令

本節說明用於整合 fastbootd 的 Fastboot 指令，包括用於閃記及管理邏輯磁碟區的新指令。部分指令的結果會因執行者是引導程式或 fastbootd 而異。

指令	說明
reboot recovery	重新啟動至復原模式 (系統啟動載入程式)。 在不重新啟動的情況下直接進入復原程序 (fastbootd)。
reboot fastboot	重新啟動至 fastbootd。
getvar is-userspace	傳回 yes (fastbootd)。 傳回 no (啟動載入程式)。
getvar is-logical:<partition>	如果特定分區是邏輯分區，則傳回 yes，否則傳回 no。邏輯磁碟分割區支援下列所有指令。
getvar super-partition-name	傳回超級分區的名稱。如果超級分區是 A/B 分區 (通常不是)，名稱會包含目前的版位字尾。
create-logical-partition <partition> <size>	建立具有指定名稱和大小的邏輯磁碟分割區。名稱不得已是邏輯磁碟區。
delete-logical-partition <partition>	刪除指定的邏輯分區 (有效清除分區)。
resize-logical-partition <partition> <size>	在不變更內容的情況下，將邏輯分區調整至新的大小。如果可用空間不足，無法執行調整大小作業，就會失敗。
update-super <partition>	合併超級區中繼資料的變更。如果無法合併 (例如裝置上的格式是不支援的版本)，則此指令會失敗。選用的 wipe 參數會覆寫裝置的中繼資料，而非執行合併作業。
flash <partition> [ <filename> ]	將檔案寫入快閃記憶體分區。裝置必須處於解鎖狀態。
erase <partition>	清除分割區 (不需要安全清除)。裝置必須處於解鎖狀態。
getvar <variable> | all	顯示系統啟動載入程式變數或所有變數。如果變數不存在，則會傳回錯誤。
set_active <slot>	將指定的 A/B 啟動槽設為 active。在下次嘗試啟動時，系統會從指定的插槽啟動。 對於 A/B 支援，空白區是可獨立啟動的重複分區組合。版位名稱為 a、b 等，並在分區名稱中加上後置字串 _a、_b 等來區分。
reboot	正常重新啟動裝置。
reboot-bootloader (或 reboot bootloader)	重新啟動裝置，並進入系統啟動載入程式。
fastboot fetch vendor_boot <out.img>	請在 Android 12 以上版本中使用，以支援刷新供應商 ramdisks 的功能。 取得整個分區大小和區塊大小。取得每個區塊的資料，然後將資料拼接成 <out.img> 詳情請參閱 fastboot fetch vendor_boot <out.img>。
fastboot flash vendor_boot:default <vendor-ramdisk.img>	在 Android 12 以上版本中使用，以支援供應商快閃記憶體磁碟。 這是 flash 指令的特殊變化版本。它會執行 fetch vendor_boot 圖片函式，就像呼叫 fastboot fetch 一樣。它閃爍的新 vendor_boot 圖片會視啟動標頭版本為第 3 版或第 4 版而定。 詳情請參閱 fastboot flash vendor_boot:default <vendor-ramdisk.img>。
fastboot flash vendor_boot:<foo> <vendor-ramdisk.img>	在 Android 12 以上版本中使用，以支援供應商快閃記憶體磁碟。 擷取 vendor_boot 圖片。如果供應商啟動標頭為第 3 版，則會傳回錯誤。如果是第 4 版，會找到正確的廠商 ramdisk 片段 (如果有的話)。並以指定圖片取代，重新計算大小和偏移量，然後閃爍新 vendor_boot image。 詳情請參閱 fastboot flash vendor_boot:<foo> <vendor-ramdisk.img>

Fastboot 和系統啟動載入程式

系統啟動載入程式會閃過 bootloader、radio 和 boot/recovery 分區，然後裝置會啟動至 fastboot (使用者空間)，並閃過所有其他分區。引導程式應支援下列指令。

指令	說明
download	下載圖片以供閃燈使用。
flash recovery <image>/ flash boot <image>/ flash bootloader <image>/	閃記 recovery/boot 分區和系統啟動載入程式。
reboot	重新啟動裝置。
reboot fastboot	重新啟動為 Fastboot。
reboot recovery	重新啟動至復原模式。
getvar	取得刷新復原/開機映像檔所需的系統啟動載入程式變數 (例如 current-slot 和 max-download-size)。
oem <command>	由原始設備製造商 (OEM) 定義的指令。

動態分割區

系統啟動載入程式不得允許刷新或清除動態分區，且必須在嘗試執行這些作業時傳回錯誤。對於改裝的動態分區裝置，fastboot 工具 (和引導程序) 支援強制模式，可在引導程序模式下直接刷新動態分區。舉例來說，如果 system 是修復後的裝置上的動態分區，那麼使用 fastboot --force flash system 指令可讓系統啟動載入程式 (而非 fastbootd) 刷新分區。

注意： 強制模式旨在提供彈性的原廠刷新效果。Android 開放原始碼計畫不建議開發人員使用。

關機充電

如果裝置支援關機充電，或在接上電源時自動啟動特殊模式，則 fastboot oem off-mode-charge 0 指令的實作必須略過這些特殊模式，讓裝置啟動時就像使用者按下電源鍵一樣。

Fastboot OEM HAL

如要完全取代 Fastboot 引導程式，Fastboot 必須處理所有現有的 Fastboot 指令。這些指令大多來自原始設備製造商 (OEM)，且已記錄在文件中，但需要自訂實作。許多原始設備製造商 (OEM) 專用的指令「皆未」記錄。為了處理這類指令，fastboot HAL 會指定必要的 OEM 指令。原始設備製造商 (OEM) 也可以導入自己的指令。

fastboot HAL 的定義如下：

import IFastbootLogger;

/**
 * IFastboot interface implements vendor specific fastboot commands.
 */
interface IFastboot {
    /**
     * Returns a bool indicating whether the bootloader is enforcing verified
     * boot.
     *
     * @return verifiedBootState True if the bootloader is enforcing verified
     * boot and False otherwise.
     */
    isVerifiedBootEnabled() generates (bool verifiedBootState);

    /**
     * Returns a bool indicating the off-mode-charge setting. If off-mode
     * charging is enabled, the device autoboots into a special mode when
     * power is applied.
     *
     * @return offModeChargeState True if the setting is enabled and False if
     * not.
     */
    isOffModeChargeEnabled() generates (bool offModeChargeState);

    /**
     * Returns the minimum battery voltage required for flashing in mV.
     *
     * @return batteryVoltage Minimum battery voltage (in mV) required for
     * flashing to be successful.
     */
    getBatteryVoltageFlashingThreshold() generates (int32_t batteryVoltage);

    /**
     * Returns the file system type of the partition. This is only required for
     * physical partitions that need to be wiped and reformatted.
     *
     * @return type Can be ext4, f2fs or raw.
     * @return result SUCCESS if the operation is successful,
     * FAILURE_UNKNOWN if the partition is invalid or does not require
     * reformatting.
     */
    getPartitionType(string partitionName) generates (FileSystemType type, Result result);

    /**
     * Executes a fastboot OEM command.
     *
     * @param oemCmd The oem command that is passed to the fastboot HAL.
     * @response result Returns the status SUCCESS if the operation is
     * successful,
     * INVALID_ARGUMENT for bad arguments,
     * FAILURE_UNKNOWN for an invalid/unsupported command.
     */
    doOemCommand(string oemCmd) generates (Result result);

};

啟用 Fastbootd

如何在裝置上啟用 fastbootd：

1. 在 device.mk 中將 fastbootd 新增至 PRODUCT_PACKAGES：PRODUCT_PACKAGES += fastbootd。

2. 請確認 fastboot HAL、boot control HAL 和 health HAL 已封裝為復原映像檔的一部分。

3. 新增 fastbootd 所需的任何裝置專屬 SEPolicy 權限。舉例來說，fastbootd 需要對裝置專屬分區具備寫入權限，才能閃記該分區。此外，fastboot HAL 實作也可能需要裝置專屬權限。

如要驗證使用者空間快速啟動功能，請執行供應商測試套件 (VTS)。

Flash 供應商 RAMDISK

Android 12 以上版本支援使用額外新增的 Fastboot 指令來刷新 RAMDISK，該指令可從裝置中擷取完整的 vendor_boot 映像檔。這個指令會提示主機端 Fastboot 工具讀取供應商啟動標頭、重新映像，並閃過新映像檔。

為了提取完整的 vendor_boot 映像檔，我們已將 fetch:vendor_boot 指令同時新增至 Quickboot 通訊協定和 Android 12 中此通訊協定的快速啟動實作。請注意，fastbootd 會實作這項功能，但引導程式本身可能不會。原始設備製造商 (OEM) 可在該通訊協定的啟動載入程式實作中，新增 fetch:vendor_boot 指令。但是，如果系統啟動載入程式模式下無法辨識指令，在系統啟動載入程式模式下重新整理個別廠商 ramdisk 時，便無法使用供應商支援的選項。

系統啟動載入程式變更

指令 getvar:max-fetch-size 和 fetch:name 已在 fastbootd 中實作。如要在啟動載入器中閃記供應商的 RAMDISK，您必須實作這兩個指令。

Fastbootd 變更

getvar:max-fetch-size 與 max-download-size 相似。它會指定裝置可在單一 DATA 回應中傳送的最大大小。驅動程式不得擷取大於此值的大小。

fetch:name[:offset[:size]] 會對裝置執行一系列檢查。如果下列所有條件都為真，fetch:name[:offset[:size]] 指令會傳回資料：

• 裝置正在執行可進行偵錯的版本。
• 裝置已解鎖 (啟動狀態為橘色)。
• 擷取的分區名稱為 vendor_boot。
• size 值介於 0 < size <= max-fetch-size。

驗證完成後，fetch:name[:offset[:size]] 會傳回分區大小和偏移量。注意事項：

• fetch:name 等同於 fetch:name:0，而 fetch:name:0 等同於 fetch:name:0:partition_size。
• fetch:name:offset 等同於 fetch:name:offset:(partition_size - offset)

因此 fetch:name[:offset[:size]] = fetch:name:offset:(partition_size - offset)。

如果未指定 offset 或 partition_size (或兩者皆未指定)，系統會使用預設值，offset 為 0，size 則為 partition_size - offset 的計算值。

• 指定偏移量，未指定大小：size = partition_size - offset
• 未指定這兩個值：兩者使用的預設值，size = partition_size - 0。

舉例來說，fetch:foo 會擷取偏移量 0 的整個 foo 分區。

驅動程式變更

我們已在 Fastboot 工具中新增指令，以便實作驅動程式變更。每個命令都會連結至 Fastboot 指令表格中的完整定義。

• fastboot fetch vendor_boot out.img

  • 呼叫 getvar max-fetch-size 以判斷區塊大小。
  • 呼叫 getvar partition-size:vendor_boot[_a] 以判斷整個分區的大小。
  • 針對每個區塊呼叫 fastboot fetch vendor_boot[_a]:offset:size。(區塊大小大於 vendor_boot 大小，因此通常只有一個區塊。)
  • 將資料拼接至 out.img。

• fastboot flash vendor_boot:default vendor-ramdisk.img

  這是 flash 指令的特殊變化版本。它會擷取 vendor_boot 圖片，就像呼叫 fastboot fetch 一樣。

  • 如果供應商啟動程序是標頭 3 版，則會執行以下操作：
    • 使用指定的映像檔取代供應商的 RAM 磁碟。
    • 閃爍新 vendor_boot 圖片。
  • 如果供應商啟動標頭為 第 4 版，則會執行以下操作：
    • 將整個供應商 ramdisk 取代為指定映像檔，以便指定映像檔成為 vendor_boot 映像檔中唯一的供應商 ramdisk 片段。
    • 重新計算供應商 RAMDISK 資料表中的大小和偏移量。
    • 閃爍新 vendor_boot 圖片。

• fastboot flash vendor_boot:foo vendor-ramdisk.img

  擷取 vendor_boot image，就像呼叫 fastboot fetch 一樣。

  • 如果廠商開機標頭是第 3 版，就會傳回錯誤。

  • 如果供應商啟動標頭為第 4 版，則會執行以下操作：

    • 找出名稱為 ramdisk_<var>&lt;foo></var> 的供應商 RAMDISK 片段。如果找不到，或有多個相符項目 系統會傳回錯誤。
    • 使用指定映像檔取代供應商的 RAMDISK 片段。
    • 重新計算供應商 RAMDISK 表格中的每個大小和偏移量。
    • 閃爍新 vendor_boot 圖片。

  • 如未指定 <foo>，則會嘗試尋找 ramdisk_。

mkbootimg

名稱 default 是保留用於在 Android 12 以上版本中命名供應商 RAM 磁碟片段的名稱。雖然 fastboot flash vendor_boot:default 語意保持不變，但您不得將 RAM 磁碟片段命名為 default。

SELinux 異動

fastbootd.te 已進行變更，以支援供應商快閃記憶體磁碟。