月台表面區域資訊清單

設計文件

提振精神

提供完整清單，列出用於 CTF 作業的平台介面測試涵蓋範圍。

詞彙解釋

(對於已定義詞彙表項目的參照，會以「草寫」的類型集顯示)。

平台介面元素。

這是 Fuchsia 公開 API 或 ABI 中最名的元件。

月台表面面積：

平台介面元素的完整集合。

平台介面片段。

是月台表面區域的一部分。

平台表面區域資訊清單。

檔案包含平台介面片段檔案的指標。

相關規定

  1. 在特定平台介面檢視畫面中識別及列舉實用的平台介面元素。

  2. 根據平台介面檢視畫面，有效率地產生及週遊許多可能的介面元素。

  3. 允許在不同平台介面種類中重複使用既有的平台介面片段。

  4. 允許在定義和建構平台介面片段時逐步加入。

  5. 與我們的建構系統合作。

為何現在發行？

為了讓 CTF 測試涵蓋範圍資訊主頁更加實用，這項工具應顯示平台途徑的涵蓋及探索部分。

  1. 平台介面的涵蓋部分可讓我們針對基礎平台做出特定正確性和安全保證。

  2. 平台表面的發現部分會引導 CTF 測試作者前往 API 介面上未充分涵蓋 CTF 測試的部分。

平台途徑區域資訊清單是 (1) 和滿足 (2) 的補充項目。

相關人員

  • CTF 維護人員
  • CTF 測試作者

設計

一系列平台介面片段檔案會說明平台介面區域，其中的平台介面資訊清單檔案也會依序列出這類檔案在 Fuchsia 建構輸出目錄 ($FUCHSIA_DIR/out/default 或類似) 中的位置。依照慣例，資訊清單檔案稱為 manifest.plasa.json，而片段檔案的名稱則與檔案路徑模式 *.fragment.plasa.json 相符，如下圖所示。

plasa 檔案的邏輯結構

影響系統選擇此軸輻式資訊清單版面配置的原因有很多：

  1. 允許不同的子系統發展自己的自訂平台途徑區域格式。

  2. 允許同時產生平台介面區域片段。這樣可以避免因合併大型檔案而造成整個平台的建構瓶頸。

  3. 允許使用建構系統內建的輕量中繼資料傳播機制來產生平台介面面積資訊清單檔案。

  4. 允許在必要時輕鬆擴充平台介面區域中繼資料。

這項工具必須辨識這個檔案的版面配置，並確保所有檔案都經過妥善處理。對於需要單一檔案的工具，您應能輕鬆編寫可合併檔案的指令碼。

資訊清單檔案格式

資訊清單檔案格式是 JSON 格式物件的序列。每個物件都包含片段檔案的參照，以及片段預期的類型宣告。資訊清單是一系列項目，因為這種格式特別容易由我們的建構系統產生，但仍可提供詳盡的內容說明。

  • 序列...

    • kind (列舉)：有問題的片段的種類。每種不同種類的解讀方式可能都不同。撰寫本文時，可能的值為：

    • api_cc：表示相關片段採用 C++ API 片段格式

    • api_fidl：表示有問題的片段符合 FIDL API 摘要格式 (根據 RFC-0076)

    • file (字串)：片段的完整標籤。

範例

[
  {
    "file": "//out/workstation_eng.x64/gen/sdk/lib/fdio/fdio.fragment.plasa.json",
    "kind": "api_cc",
  },
  {
    "file": "//out/workstation_eng.x64/gen/sdk/lib/stdcompat/stdcompat.fragment.plasa.json",
    "kind": "api_cc",
  },
  {
    "file": "//out/workstation_eng.x64/gen/sdk/lib/fit/fit.fragment.plasa.json",
    "kind": "api_cc",
  }
]

C++ API 片段檔案格式

片段檔案格式目前是平台元素項目序列。這種格式可能會視需要展開。

  • JSON 物件...

    • items (序列)...

    • name (字串)：平台介面元素的名稱。

    • file (選用 [String])：元素所在的檔案路徑。

    • line (選用 [Integer])：定義元素的 file 行。

範例

{
  "items": [
        {
            "name": "fit::deferred_action::deferred_action<T>",
            "file": "gen/sdk/lib/fit/../../../../../../sdk/lib/fit/include/lib/fit/defer.h",
            "line": 81
        },
        {
            "name": "fit::deferred_action::operator bool",
            "file": "gen/sdk/lib/fit/../../../../../../sdk/lib/fit/include/lib/fit/defer.h",
            "line": 43
        }
  ]
}

說明文件與範例

我們可能想更新 CTF 說明文件，納入平台介面資訊清單是否存在。

回溯相容性

這項新功能沒有維護的相容性基準。

安全性和隱私權

此設計在安全性和隱私權方面相當中立，如下所示：

  1. 凡是具備公開知識的平台顯示片段，可能都不受安全性和隱私權限制，取決於公開瀏覽權限的性質。

  2. 任何私人平台介面片段都可以在公開檢視以外的資訊清單中定義。如有需要，您可以將私人和可公開存取的片段加入單一資訊清單，形成整體平台介面資訊清單。

未來的工作

日後的作業將會看到平台途徑區域資訊清單涵蓋的平台介面更多元素：

  1. 代表資訊清單中的指令列公用程式和旗標。

  2. 代表資訊清單中的其他 Plasa 元素。