RFC-0200：支援 ADB 通訊協定與硬體測試介面

摘要

此 RFC 建議將 Android Debug Bridge (ADB) 通訊協定和介面支援新增至 用於硬體測試的 Fuchsia。這項操作會讓 Fuchsia 裝置與庫存 ADB 進行互動 ，在目前的硬體測試工作流程中有多個應用程式。ADB 支援團隊將會 也能讓我們從目前採用的 Windows 主機探索 Fuchsia 裝置並進行互動， Fuchsia 工具不支援這項功能。此外，新增對 ADB 的支援，可讓我們重複使用大多數 根據 adb shell 建立的測試、工具和程序，用於硬體驗證和製造。 如要新增 ADB 介面支援，Fchsia 的 USB 週邊裝置設定將更新為採用 新的 ADB 介面，將取代 (或搭配使用) 上現有的 USB CDC 乙太網路介面 適用於已啟用 ADB 的建構作業ADB 通訊協定支援僅限於 執行硬體驗證和製造用途所需的微服務。支援的 ADB 服務將是 Fuchsia 不會試圖模仿 Android ADB 服務

提振精神

ADB 支援對於硬體驗證和製造測試而言非常實用：

• ADB 有數種工具、程式庫和架構 (1、2、3)。 以及許多其他方法) 可以重複運用
• 針對各種平台的 ADB 用戶端預先建構的二進位檔分佈範圍廣泛，且 設定簡單
• 仰賴 ADB 提供裝置探索、連線和指令的現有測試架構 執行服務可在不進行任何變更的情況下運作
• 由於 ADB 受歡迎，且開放原始碼社群支援，因此開發人員相當熟悉 ADB 大量的訓練資料
• 這項服務可以在ffx 不支援 Windows 等環境Windows 版 ADB 經過充分測試且廣泛使用 而 ADB Windows 驅動程式庫也隨時可供 Google 安裝。
• adb 支援以 USB 週邊裝置為基礎的探索與通訊，延遲時間比 目前 Fuchsia 中使用的 mDNS 型探索。 在製造業用途上，縮短延遲時間對很重要。

考慮 ADB 是輕量級且一般穩定的工具， Fuchsia 工具組。

相關人員

講師：

leannogasawara@google.com

審查者：

• curtisgalloway@google.com
• rdzhuang@google.com
• gkalsi@google.com
• prashanthsw@google.com
• jeremymason@google.com
• surajmalhotra@google.com

諮詢：

• palmer@google.com

社會化：概念驗證是針對相關利害關係人制定及討論的。

設計

下列關鍵字：「必須」、「不得」、「必要」、「應」、「不應」、「應該」、「不應」、 「建議」、「可能」和「選用」本文件一律由 IETF 定義 RFC 2119。

總覽

Android Debug Bridge (ADB) 由三個主要部分組成：用戶端、伺服器和 Daemon。 用戶端和伺服器會在主體機器上執行，並透過通訊端相互通訊。廣告 B Daemon (adbd) 會在裝置上執行，且通常會透過 USB 連線至 ADB 伺服器。 ADB Daemon 和伺服器之間的通訊是在 ADB 通訊協定中定義。

為了讓 ADB 探索 Fuchsia 裝置，我們必須公開新的 USB ADB 裝置 介面。因此必須更新 USB 週邊裝置設定 就必須編寫新的 usb ADB 函式驅動程式庫在主機上運作的 ADB 伺服器 可透過這個介面連線至裝置。連線後，ADB 伺服器將傳送/接收 ADB USB ADB 介面上的通訊協定訊息。編碼/解碼 這些 ADB 通訊協定訊息，就需要編寫 ADB Daemon 元件。視服務而定 ADB Daemon 會將要求轉送至適當的元件。我們可能需要 編寫新的 ADB 服務元件，在現有元件與 ADB 之間建立連結 Daemon我們僅支援部分 ADB 指令 (請參閱 ADB 服務)。 下圖說明建議的 ADB 軟體堆疊：

我們會在下列各節中詳細說明各個部分。

ADB 介面和裝置探索

ADB 僅適用於支援 USB 週邊模式的 Fuchsia 主機板。將 對於 Fuchsia 產品的 ADB 支援，產品設定必須包含 ADB 套件和設定 啟動 args 即可指定 usb ADB 介面。硬體測試預設會啟用 ADB 介面 僅適用於產品。使用者或實際執行版本不應啟用 ADB，以限制攻擊途徑 這些建構作業

Fuchsia 的 USB 週邊裝置設定將更新，改為使用新的 ADB 介面， 在啟用 ADB 的版本中取代 (或搭配使用) 現有 USB CDC 乙太網路介面。 新介面必須遵守 ADB 介面規定：

• USB 類別：vendor
• USB 子類別：0x42
• 通訊協定：1

在主機上執行的 ADB 伺服器會持續輪詢具有介面描述元的新型 USB 裝置 符合上述屬性的情況找到之後，它會記下 USB 裝置描述元並將其用於識別裝置。ADB 用戶端會使用這個序號 將要求轉送至裝置。在 Fuchsia 上，這個序號會由系統啟動載入程式傳遞 衍生自 MAC 位址，或為硬式編碼備用序號 (以 排序。

USB ADB 函式驅動程式庫

此驅動程式庫負責處理 ADB 介面的 USB 要求。這支驅動程式庫只會 負責計算 USB 封包和回呼

ADB 元件

這個元件瞭解 ADB 通訊協定，且負責剖析及轉送訊息 或適當的服務。

ADB 服務

ADB 用戶端傳送指令至 ADB 伺服器時，伺服器可能會使用 要求連線至裝置上的服務，例如殼層或記錄器服務。ADB Daemon 查看已註冊的服務供應商清單，找出相符的結果。如果相符，註冊的 服務供應商要求存取 Zircon 通訊端，adb Daemon 轉送 ADB 的所有通訊 與此通訊端的服務相關用戶端。要求的服務範例包括殼層、Logcat、通訊埠 轉寄和同步處理檔案核心概念是為 舉例來說，我們可以讓 adb-shell 元件開啟且管理殼層殼層 ADB 傳輸與儀表板之間以 Pty 為基礎的裝置通訊；我們也可以 adb-ffx 元件，用於連結 ADB 傳輸和 overnet。服務清單

服務和 ADB 元件之間的介面可列於以下幾行：

// Max length of arguments passed in adb OPEN message.
const MAX_ARGS_LENGTH uint64 = 1024

/// A Provider is a provider for one service.
/// The interaction between the adb daemon and Provider is as follows:
///    - adb daemon is started eagerly by core.cml
///    - When an request for a service comes in, adb daemon starts up a lazy component serving
///      Provider and calls ConnectToService, handing it a socket.
///    - If the service has already been started, it opens that service and hands it a socket.
///    - adb daemon and Provider communicate over the socket.
@discoverable
protocol Provider {
    /// Connect `socket` to the service (called in response to adb OPEN message).
    /// `args` provides additional arguments passed by the client if any.
    ConnectToService(resource struct {
        socket zx.handle:SOCKET;
        args string:<MAX_ARGS_LENGTH, optional>;
    }) -> (struct {}) error zx.status;
};

ADB 通訊協定指定數種服務，但我們只支援部分服務 這些元件包括殼層、Logcat、sync (適用於 ADB 推送/提取)。這些服務可能無法模擬 ADB 的所有行為 並專門為 Fuchsia 量身打造，例如殼層指令必須與 Fuchsia 支援的指令和記錄可能採用 Fuchsia 系統記錄格式。ADB Shell 服務 則會在下一節中詳細說明。日後將支援更多服務 我們會視個案情形而定

ADB 服務範例：ADB 殼層

本節說明 ADB 服務與 ADB Daemon 之間的互動，將範例 ADB 殼層服務。ADB 殼層元件將負責 將 A/O 殼層 I/O 橋接到破折號殼層 I/O 破折號 啟動器 課程中也會快速介紹 Memorystore 這是 Google Cloud 的全代管 Redis 服務根據預設，adb-shell.cm 會提供類似透過 sshd-host.cm 使用 ffx component explore 或其他功能較受限的殼層。如果遷移至 但您可以在 Fuchsia 中將 ADB 殼層遷移至這項工具。限制 針對特定產品設定的能力，以及對特定用途而言，自訂殼層供應商 功能有限，可以改用這項元件這與使用 ffx component explore <specific-moniker> 類似。

ADB Daemon 每次都會要求新的 ADB 殼層工作階段 (並因此產生新的破折號工作階段) 使用者要求新的 ADB 殼層執行個體。從 ADB 用戶端或破折號連線關閉連線 就會關閉整個工作階段互動順序會按以下順序顯示 圖表：

驗證與加密

ADB 通訊協定支援使用 RSA 金鑰組進行驗證。也支援 TLS 加密。 這兩項功能皆為選用。在最初的實作過程中，這些功能將 只是為了測試版本，而只用於在受限制的情況下執行的開發人員或測試版本 環境此外，由於 USB 是唯一支援的傳輸方式，因此會將攻擊方法限制在 在某種程度上日後，如果系統已支援這些格式，就必須對 ADB 進行更新 Daemon

維護

系統將支援目前的 ADB 通訊協定版本 0x01000000。日後的通訊協定更新將 我們會依個案情況處理ADB 通訊協定通常不會經常變更，而且一直以來 回溯相容

實作

導入作業可分為三個部分。

• 在不同主機板和版本中新增支援。
• ADB Daemon
  • 部分元件會在 OSRB。
• ADB 服務
  • 目前的方案支援「adb-shell」和「adb-ffx」。
  • 如果必須支援其他指令，這個階段可能會擴大。

目前有概念驗證，可做為實作的參考。

成效

運算影響：新增 ADB 支援應該不會造成大量的運算負擔。adb 而非 SSH Daemon 和/或 overnetstack，這兩者都依賴相似的 驅動程式和元件，因此系統的整體 CPU 使用率應保持一致。

對大小的影響：加入 ADB Daemon 和 Service 大約會 1 MB。請注意，這僅適用於與 ADB 組合在一起的開發和測試版本。 聯絡。使用 ADB 時，執行階段記憶體用量應該不會受到任何重大影響 而非現有工具

ADB 中的指令處理延遲時間可能會比 SSH 或其他位置稍長一點 而非額外的網路堆疊。裝置探索延遲時間 採用的系統是根據 USB 列舉計算，而非定期廣播，因此會比較小 就像在 mDNS 中一樣

回溯相容性

這個部分分成三個部分：一個是 ADB 通訊協定本身的回溯相容性 不在 Fuchsia 專案的控制範圍內。已知所有 ADB 通訊協定都不會有 確保回溯相容性其次，ADB 服務支援 - 淘汰 都會影響需要使用這些服務的主機端指令/指令碼正確的遷移策略 進行這類變更時所需使用的資源第三，殼層指令舉例來說，淘汰 假設 CLI xyz-tool 表示執行 adb shell xyz-tool 的指令碼將無法再運作。 這個疑慮屬於 Fuchsia 工具的範疇，與 ADB 無關，因此不會 並予以解決

安全性考量

至於 ADB 傳輸的安全性考量，有些啟用規定 驗證與加密但初始實作程序不會啟用這些功能。開始時間 ADB 只會在特定版本 (例如開發人員版本或測試版本) 中提供，不會在使用者中使用 不必造成重大的問題

至於透過 ADB 公開的服務安全性考量，上述原則和 Fuchsia 的現有服務。adb-shell / adb-ffx 公開的互動介面是 小於或小於 dash-shell /ffx 的數值。適用於特定用途的限定範圍殼層 只要將殼層供應商從 adb-shell 替換為 自訂殼層

初始實作僅支援 USB 傳輸。這會限制可能的攻擊方法 。另外，ADB Daemon 本身是元件 安全漏洞中的安全漏洞會沙箱，只套用至該特定程序，而且只會影響 ADB 作業。

隱私權注意事項

ADB 服務公開的資料與兩者的 ffx component explore 或 SSH 相同 所有隱私權問題都會經過審查此外，這項技術僅限 開發人員或測試版本，不會部署至使用者/正式環境。USB ADB 介面 但會是其他 USB 裝置所使用的序號 例如 CDC 乙太網路介面這大多是由系統啟動載入程式設定 (如果未衍生而來的話) 。產品設定期間須謹慎留意，否則不得使用 重要性很高

測試

ADB 堆疊的所有部分都將進行單元測試。最後，ADB Daemon 之間的整合測試 系統會加入 ADB 服務由於 ADB 子系統之間的合約是以 FIDL 為基礎 (USB ADB 驅動程式庫除外) 測試可能相當隱密。系統將新增裝置列舉測試 適用於 USB ADB 介面如有需要，將新增 ADB 的主機端 E2E 測試。在 E2E 測試中 測試主機上可能需要安裝 ADB。您可以透過 E2E 測試 / 整合測試 用於效能 測試和指令延遲測試定期進行 ADB 連線的壓力測試 我們會將 USB 插頭/拔除插頭，以提升穩定性測試。模糊 ADB Daemon 導入的功能

說明文件

需新增以下文件：

• 支援的 ADB 功能清單
• 擴充 ADB 服務指南
• 使用手冊

缺點、替代方案和未知

支援 ADB 需要維護成本使用兩組工具會增加開銷 用於通訊與裝置控制，也就是 ffx 和 ADB。雖然這兩個網路 特徵不同的用途 。ffx 適用於各種開發人員工作流程，但目前設有限制 。ADB 可用於填補 硬體測試在裝置上共用服務，可進一步降低維護成本 介於 ffx 和 ADB 之間。舉例來說，破折號啟動器、 overnetstack、記錄檔接收器等可以與 ADB 搭配使用

替代做法：將 ffx 通訊埠匯入 Windows

這個問題目前遇到的阻礙：讓 Windows 的信任工具鍊支援 Windows，並增加 USB 連結 至 ffx。此外，採用 ADB 的現有測試架構將需要修改，才能使用 ffx，或必須提供 ADB 和 ffx 之間的翻譯輔助程式。這項策略也可以 之後重新審視adb 提供便利的解決方案，同時開發 Windows 適用的 ffx 仍在處理中。

替代做法：在 Linux 虛擬機器中執行主機端 ffx

請使用在 Windows 上執行的 Linux 虛擬機器(VM)，並通過裝置的 USB 連線。取代為 此設定，現有的 ffx 工作流程適用於裝置探索和互動功能。但 因此設定 VM 所需的時間可能相當龐大，而且不穩定/穩定可靠 此外，有些機構會限制在代管 Windows 機器上使用 VM。使用 Docker 容器 ，不過 USB 轉送功能可能不適用於 Windows 版本。

替代方法：USB 序列

將 USB CDC ACM 週邊裝置的支援新增至 Fuchsia。Windows 內含 USB 序列 就能立即使用 USB CDC ACM 介面。這樣一來，我們才能將 USB 連接埠做為 序列通訊裝置。這種做法的缺點缺少了豐富的指令集 ( 我們將提供殼層、記錄檔和殼層，且不支援單一執行個體。另外， 因此需要更新以 ADB 為基礎的現有測試架構。

既有藝術品和參考資料

• ADB 總覽 - ADB 用戶端、伺服器和 Daemon 總覽
• ADB 通訊協定 - ADB 訊息類型和欄位
• Android 上的 ADB - Android ADB 實作