RFC-0222：隆重推出 Fuchsia 控制器

摘要

Future Fuchsia Experience 工具 FFX 提供了 與主機機器的 Fuchsia 裝置通訊。此屬性使用 Fuchsia 介面定義語言 (FIDL)，呼叫各種服務 為了添加更多工具功能，FFX 支援子工具，這是用來擴充 FFX 指令列的獨立二進位檔 介面和功能這項工具完全以 Rust 編寫。

如果使用者想要在 Fuchsia 裝置上存取 FIDL 通訊協定，可以採取下列任一做法： 編寫 FFX 的外掛程式，請使用 Scripting Layer For Fuchsia， SL4F，或在系統上編寫元件。

這些選項都不適合用於輕量級實驗 疊代或彈性FFX 外掛程式需要在 Rust 中編寫工具，以及 進行編譯和修改SL4F 並非受到支援，而且依賴不安全 您需要在 Rust 中編寫門面， 您打算致電的 FIDL 介面。

所有方法都無法讓使用者遵守「讓自己的 Own Runtime。」

此 RFC 提議以其他方式透過 來自 FFX 的程式庫 稱為 Fuchsia Controller這類內容包括：

• 透過 FIDL 處理常式模擬與 Fuchsia 裝置互動的穩定 ABI 且無須變更 FFX 本身
• 提供至少一種熱門指令碼語言的頂級支援 穩定為穩定版 ABI (目前選擇為 Python)。
• 以指令碼語言撰寫而成的較高層級程式庫，適合用於寫入 重要的測試用途

提振精神

系統目前不支援在主機指令碼編寫互動指令碼 轉移至 Fuchsia 裝置 (透過 SDK、樹狀結構內或其他方式)。

如果使用者想使用 FFX 與 Fuchsia 裝置互動，就必須 具備可編譯至工具中的服務定義。如果 如果某項服務在樹狀結構外定義了，使用者就無法存取該項服務。如果 服務經過定義後，使用者就必須編寫 FFX 外掛程式 基礎架構

Fuchsia Controller 能讓使用者在 進行快速、反覆調整 以及輕鬆自動化支援穩定版本 ABI 可讓使用者自行選擇執行階段，以便選擇是否 因為我們支援使用 C ABI 來擴充幾乎所有 程式設計語言

相關人員

講師：

未定

審查者：

jeremymanson@google.com (工具) mgnb@google.com (FFX) ianloic@google.com (FIDL) chok@google.com (Lacewing) jzgriffin@google.com (SL4F)

諮詢：

EngProd 團隊 FFX 團隊 FIDL 團隊

社交功能：

Fuchsia Controller 是為期幾個月的對話產品 工具、FFX、FIDL 和 EngProd 團隊其他團隊包括元件架構 以及測試架構團隊作者也曾書面並展示 概念驗證及概略示範 在實作一節中概述的技術知識。

設計

總覽

Fuchsia Controller 分成三個部分：

• FFX 用戶端程式庫。
• 各語言專屬的擴充功能程式庫。
• 使用擴充功能程式庫的高階第一類別程式庫。

這些函式會與 FFX 搭配運作，以便處理連線至 Fuchsia 裝置。

繼續之前，您必須先處理一些必要條件。

FFX 的背景

FFX 是一種主機端工具 (在撰寫之前) 使用 "Daemon"CANNOT TRANSLATE 這裡的例子是自行在背景執行的分支副本， 並且會在網路中偵測到時，透過 SSH 連線至 Fuchsia 裝置。 發掘裝置的方法有很多種，但目前並不侷限於表面 其他部分

FFX Daemon 可讓 FFX 工具的使用者開啟模擬的 FIDL 頻道 與 Fuchsia 裝置間的連線。訊息是從 FFX 轉送 用戶端透過 Daemon 傳送至 Fuchsia 裝置。

FFX 幾乎完全在 Rust 中編寫。此外， 主機端模擬 FIDL 管道的資料寫入和讀取作業也會寫入 以及 Rust 中的程式碼

總結來說，FFX 可讓使用者透過 FIDL 與 Fuchsia 裝置介面 使用 Rust 編寫的外掛程式，且該外掛程式與實作 FFX。

字詞定義

以下各節的部分定義如下：

• 「隔離」是指以 FFX 的專屬執行個體 自行運作的 FFX Daemon，不使用公共通訊端 或任何常見的 FFX 設定值接著， FFX Daemon 不能與 Fuchsia 裝置進行通訊 (除非 才能進行)。
• 「Daemon 協定」是指 FFX Daemon 的主機端 FIDL 通訊協定 控制代碼這些時間可能包括套件放送，以及在 網路至 Fuchsia 裝置通訊埠轉送。Daemon 本身可以做為 類似於公開多個 Daemon 通訊協定的元件
• 提及「zircon」時管道、帳號代碼和通訊端 透過 Overnet 模擬主機端未來這些 但可以在 Fuchsia 裝置上做為實際的 Zircon 物件使用。

FFX 用戶端程式庫

FFX 用戶端程式庫會透過 C ABI 公開，以便支援 包括：

• 建立、讀取、寫入及關閉 Zircon 頻道。
• 建立、讀取、寫入及關閉 Zircon 通訊端。
• 訊號 zircon 控點 (主要用於事件配對)。
• 連結 Zircon 頻道與 Fuchsia 裝置上的元件。
• 將 Zircon 頻道連接至 FFX Daemon Protocols。

並支援其他功能，例如：

• 建立 FFX Daemon 的獨立執行個體。
• 宣告 FFX 設定鍵/值組合。

特定語言擴充功能

這牽涉到 FFX 用戶端程式庫頂端的簡單抽象層 以共用資料庫的形式加以處理，以便應用在第一類中 編寫指令碼

實作

如前所述，這會建立兩個共用程式庫。

• 「FFX 用戶端」就是不受語言限制的當中會公開 與 FFX 以及 Zircon 控制代碼通訊
• 語言繫結 (在本例中為 Python) 共用資料庫。

Python 也會針對符合人體工學 FIDL 的使用行為提供 Python 繫結。

實作程序沒有任何第三方依附元件 已包含在 Fuchsia 來源樹狀結構中。我們預期 使用 FFX 用戶端程式庫來實作其他語言的支援 可能會支援 (且可能需要額外的第三方依附元件工作)，但 不在 RFC 的範圍內

發布 Python 和 SDK 是另一個不在本文討論範圍的主題 文件，且可能會封裝在其 RFC 中。

FFX 用戶端程式庫

本節的 C 定義應放在標頭檔案中 將隨 Fuchsia SDK 一併提供的由於 C 語言缺少命名空間 就會比較冗長函式名稱 並不一定是最終決定

ABI 的模式旨在確保大部分函式 使用輸出參數傳回呼叫端的結構以及傳回值 可能是無效或錯誤

系統會盡可能將 zx_status_t 和 zx_handle_t 等已建立的類型 與現有的 C 程式庫相容，例如 Zircon 程式碼集。

用於讀取頻道的函式範例如下 (這個 無意做為最終的實作或文件來源)：

extern zx_status_t ffx_channel_read(void* ctx,
                                    zx_handle_t handle,
                                    void* buf,
                                    uint32_t buf_len,
                                    zx_handle_t* handles,
                                    uint32_t handles_len
                                    uint32_t* actual_bytes_count,
                                    uint32_t* actual_handles_count);

ctx 值可以指向含有關於 現有 FFX 環境 (執行目錄、SDK 位置、設定 以及我們進行通訊的 Fuchsia 裝置)。

這類似於現有的 zx_channel_read， 省略選項參數。這個符號不會像 Zircon syscall 會在標頭中明確寫入 ABI，因此會清楚呈現 機制與支援的功能 (因為可能會有特殊限制 但這個程式碼一開始僅供主機機器編寫 而不是 Fuchsia 裝置)。

以下舉例說明取得帳號代碼的方式 函式，可用來連線至 Fuchsia 裝置 遠端控制 FIDL 定義

extern zx_status_t ffx_connect_proxy(void* ctx, const char* endpoint_path,
                                     zx_handle_t* out);

這項作業會將 FIDL 管道傳回有問題的通訊協定。 endpoint_path 應包含可直接連線的必要資訊 透過元件架構在裝置上的特定 FIDL 通訊協定 採用 "$moniker:expose:$protocol" 格式)。

支援通訊端/管道讀取和寫入，以及事件 因此，攻擊者可能可以複製 FFX 的所有 FIDL 功能 目前支援 Overnet 功能，不過在 Python 中

Python 語言繫結

Python 語言繫結會定義物件的 create*/close*/destroy* 呼叫，以 C++ 編寫並提供精簡包裝函式 FFX 用戶端程式庫它也會匯出錯誤類型，使用 ffx_error_str()。

請前往 Fuchsia Controller 原型設計請見這裡。

更高層級的繫結

如要實際使用 FIDL 通訊協定，則可使用更高層級的程式庫。 且會使用 importlib 掛接到 FIDL 中繼表示法 (IR)， 可在分散式 .pyz 中匯入任何可用的 IR， 可在開發人員的 PYTHONPATH 或手動提供 目錄。這些掛鉤會建立在執行階段與 FIDL 互動的類別 類似 C++ 或 Rust 執行編譯時間繫結時的情況。

示例如下：

import fidl.fuchsia_developer_ffx
from fuchsia_controller_py import Context

def main(ctx: Context):
  h = ctx.connect_daemon_protocol(fidl.fuchsia_developer_ffx.Echo.Marker)
  proxy = fidl.fuchsia_developer_ffx.Echo.Client(h)
  print(proxy.echo_string(value = 'foobar'))

if __name__ == '__main__':
  ctx = Context(None)
  main(ctx)

從 fidl. 匯入作業會遭資料庫掛鉤捕捉到 符合 fuchsia.developer.ffx 的任何現有 FIDL IR 命名空間 根據其中定義的結構和通訊協定產生類別。

FIDL 線路格式編碼/解碼

如果是第一次傳遞，則實際的編碼和解碼作業可能會使用 fidl_codec 程式庫，稍後就能完全在 Python。

fidl_codec 包含用於讀取/寫入 FIDL 線格式的程式碼 其主要功能是以 FIDL IR 定義為基礎， 可用於建構物件的值訪客 FIDL 訊息。用於 fidlcat 工具。FIDL 結構的編碼方式 可透過訪客模式完成 建立一個可寫入 FIDL 控制代碼的緩衝區。

成效

FFX 用戶端程式庫 ABI

跨 FFX 用戶端 ABI 時，會遇到大部分效能負擔 例如 Unix Domain Socket 讀取/寫入，以及與 Fuchsia 裝置。

此外，FFX 用戶端程式庫會複製 FIDL 讀取作業 但一次會跨越 Rust ABI 邊界，然後再次執行一次 將資料從 C++ 程式碼載入 Python 物件。這可以解決 避免日後出現問題

一般使用案例通常需要 FIDL 的使用費低，也就是呼叫 透過結構體適用的簡單函式在編寫較複雜的 FIDL 時 (例如 主機不支援 VMO)，因此不建議為 才需進行

人體工學

FFX 用戶端 ABI

系統會盡可能在設定檔較小的情況下實作 FFX 用戶端二進位檔， 避免使用過多樣板實作其他語言的繫結。

高階 Python 繫結

較高層級的 Python 繫結將使用 FIDL IR 建立類別繫結 執行程式碼這樣一來，您不僅可以用 Python 程式碼 其行為符合其他 FIDL 語言繫結 Rust、Dart 或 C++，但也能以 FIDL 進行實驗 實現更多反覆式開發的目標

如果 FIDL 服務在樹狀結構外定義，也會使 FIDL 服務定義在樹狀結構外 可透過 SDK 存取服務 (方法是先產生 FIDL IR， 再匯入 Fuchsia Controller)。

安全性考量

這個 RFC 中主要的安全性影響與 FFX 本身相關， 。

測試

FIDL 線路格式

FIDL 團隊有一套測試用的 (GIDL 和 DynSuite) 以及編碼和解碼作業這適用於 正在使用 fidl_codec (尚未針對這些套件進行測試)，或者 Python 明確從傳輸格式寫入/讀取。

FFX 用戶端程式庫和 Python C 繫結

這些體積輕巧，沒有太多的單元測試可以做 而不是確認是否符合特定例外條件為了測試 FFX 用戶端程式庫的 ffx_error_str() 可以使用明確定義的錯誤 避免依賴 FFX 本身內的特定字串

這類程式碼的大部分測試都位於整合和/或 端對端測試舉個簡單的例子，每段程式碼都要練習 針對非 Fusia 裝置獨立測試使用 Echo 通訊協定。測試 實際執行時，就可以取得遙控器的例項 並呼叫 IdentifyHost 函式。

說明文件

Fuchsia Controller 的說明文件會保留在「fuchsia.dev」網站上。

缺點、替代方案和未知

缺點

一流的 Python 支援

當 FFX 用戶端程式庫可以支援 Python 不適合大型的正式環境專案。Python 可以快速編寫程式碼 輕鬆維護及易讀性

替代方案

為何不是 Golang、Java、Rust 或 Dart？

在我們與 e2e 測試團隊、產品開發人員 連至訂房團隊，他們偏好使用指令碼語言 讓使用者能互動且易於使用這指向 Python 沒有繫結。

不明

FIDL IR

透過 SDK 讓使用者樹狀結構外取用 FIDL IR 並不容易 才不會產生費用因此您可能需要 才能簡化依附元件

SDK 中的 FFX

上述使用 FFX Daemon 通訊協定的例子無法反向運作 因為 FFX FIDL 通訊協定尚未包含在 SDK 中。API 審查之前為 已部分完成，但仍需完成。難以衡量 可能需要很長一段時間，因為 FFX 還有寬廣的 FIDL 介面 通常會持續移動

FIDL 轉碼器

您可能不必在最終結果中使用 fidl_codec。 也會在 Python 共用資料庫中加入更多介面， 之後需要仔細逐步淘汰這些元件

建議替代方案：

• 產生的程式碼 (例如在 C++ 和 Rust 中處理此做法的方式)。
• 在 Python 中實作的 fidl_codec 類比。

既有藝術品和參考資料

• SL4F 演進計畫
• Fchsia 的主機驅動程式測試